diff options
| author | Craig Jennings <c@cjennings.net> | 2024-04-07 13:41:34 -0500 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2024-04-07 13:41:34 -0500 |
| commit | 754bbf7a25a8dda49b5d08ef0d0443bbf5af0e36 (patch) | |
| tree | f1190704f78f04a2b0b4c977d20fe96a828377f1 /devdocs/c | |
new repository
Diffstat (limited to 'devdocs/c')
597 files changed, 39040 insertions, 0 deletions
diff --git a/devdocs/c/11.html b/devdocs/c/11.html new file mode 100644 index 00000000..b4044d37 --- /dev/null +++ b/devdocs/c/11.html @@ -0,0 +1,69 @@ + <h1 id="firstHeading" class="firstHeading">C11</h1> <p><b>ISO/IEC 9899:2011</b>, a.k.a. <b>C11</b>, is a previous revision of the C standard.</p> +<h2 id="Obsolete"> Obsolete</h2> <h3 id="Removed"> Removed</h3> <ul><li> <code><a href="io/gets" title="c/io/gets">gets()</a></code> </li></ul> <h2 id="New_language_features"> New language features</h2> <ul> +<li> Multithreaded environments <ul> +<li> <a href="language/atomic" title="c/language/atomic">Atomic objects</a> (<a href="keyword/_atomic" title="c/keyword/ Atomic"><code>_Atomic</code></a>) </li> +<li> <a href="language/storage_duration#Storage_duration" title="c/language/storage duration">Thread local storage</a> (<a href="keyword/_thread_local" title="c/keyword/ Thread local"><code>_Thread_local</code></a>) </li> +</ul> </li> +<li> Enhanced alignment support <ul> +<li> <a href="language/_alignof" title="c/language/ Alignof">Alignment query</a> (<a href="keyword/_alignof" title="c/keyword/ Alignof"><code>_Alignof</code></a>) </li> +<li> <a href="language/_alignas" title="c/language/ Alignas">Alignment strengthening</a> (<a href="keyword/_alignas" title="c/keyword/ Alignas"><code>_Alignas</code></a>) </li> +<li> Over-aligned types </li> +</ul> </li> +<li> Unicode support <ul> +<li> <a href="language/character_constant" title="c/language/character constant"><code>u</code>/<code>U</code> character constants</a> </li> +<li> <a href="language/string_literal" title="c/language/string literal"><code>u8</code>/<code>u</code>/<code>U</code> string literals</a> </li> +</ul> </li> +<li> <a href="language/generic" title="c/language/generic">Generic selection expressions</a> (<a href="keyword/_generic" title="c/keyword/ Generic"><code>_Generic</code></a>) </li> +<li> <a href="language/_noreturn" title="c/language/ Noreturn">Non-returning functions</a> (<a href="keyword/_noreturn" title="c/keyword/ Noreturn"><code>_Noreturn</code></a>) </li> +<li> Anonymous <a href="language/struct" title="c/language/struct">struct</a> and <a href="language/union" title="c/language/union">union</a> members </li> +<li> Fine-grained <a href="language/eval_order" title="c/language/eval order">evaluation order</a> </li> +<li> Extending the lifetime of <a href="language/lifetime#Temporary_lifetime" title="c/language/lifetime">temporary objects</a> </li> +<li> <a href="language/_static_assert" title="c/language/ Static assert"><code>_Static_assert</code></a> </li> +<li> <a href="language/analyzability" title="c/language/analyzability">Analyzability</a> </li> +</ul> <h3 id="Feature_test_macros_for_optional_features"> Feature test macros for optional features</h3> <ul> +<li> <a href="preprocessor/replace" title="c/preprocessor/replace"><code>__STDC_ANALYZABLE__</code></a> <ul><li> Indicates analyzability is supported. </li></ul> </li> +<li> <a href="preprocessor/replace" title="c/preprocessor/replace"><code>__STDC_LIB_EXT1__</code></a> <ul><li> Indicates bounds checking functions are supported. </li></ul> </li> +<li> <a href="preprocessor/replace" title="c/preprocessor/replace"><code>__STDC_NO_ATOMICS__</code></a> <ul><li> Indicates atomic objects and the atomic operation library are not supported. </li></ul> </li> +<li> <a href="preprocessor/replace" title="c/preprocessor/replace"><code>__STDC_NO_COMPLEX__</code></a> <ul><li> Indicates complex types and the complex math functions are not supported. </li></ul> These features were mandatory in C99. </li> +<li> <a href="preprocessor/replace" title="c/preprocessor/replace"><code>__STDC_NO_THREADS__</code></a> <ul><li> Indicates thread local storage and the thread support library are not supported. </li></ul> </li> +<li> <a href="preprocessor/replace" title="c/preprocessor/replace"><code>__STDC_NO_VLA__</code></a> <ul><li> Indicates <a href="language/array#Variable-length_arrays" title="c/language/array">variable length arrays and variably modified types</a> are not supported. </li></ul> These features were mandatory in C99. </li> +</ul> <h2 id="New_library_features"> New library features</h2> <h3 id="New_headers"> New headers</h3> <ul> +<li> <a href="types" title="c/types"><code><stdalign.h></code></a> </li> +<li> <a href="thread#Atomic_operations" title="c/thread"><code><stdatomic.h></code></a> </li> +<li> <a href="language/_noreturn" title="c/language/ Noreturn"><code><stdnoreturn.h></code></a> </li> +<li> <a href="thread" title="c/thread"><code><threads.h></code></a> </li> +<li> <a href="string/multibyte" title="c/string/multibyte"><code><uchar.h></code></a> </li> +</ul> <h3 id="Library_features"> Library features</h3> <ul> +<li> <a href="thread" title="c/thread">Concurrency support library</a> </li> +<li> <a href="memory/aligned_alloc" title="c/memory/aligned alloc"><code>aligned_alloc()</code></a> </li> +<li> UTF-16/32 type aliases <ul> +<li> <a href="string/multibyte/char16_t" title="c/string/multibyte/char16 t"><code>char16_t</code></a> </li> +<li> <a href="string/multibyte/char32_t" title="c/string/multibyte/char32 t"><code>char32_t</code></a> </li> +</ul> </li> +<li> UTF-16/32 conversion functions <ul> +<li> <code><a href="string/multibyte/mbrtoc16" title="c/string/multibyte/mbrtoc16">mbrtoc16()</a></code> </li> +<li> <code><a href="string/multibyte/mbrtoc32" title="c/string/multibyte/mbrtoc32">mbrtoc32()</a></code> </li> +<li> <code><a href="string/multibyte/c16rtomb" title="c/string/multibyte/c16rtomb">c16rtomb()</a></code> </li> +<li> <code><a href="string/multibyte/c32rtomb" title="c/string/multibyte/c32rtomb">c32rtomb()</a></code> </li> +</ul> </li> +<li> <code><a href="program/quick_exit" title="c/program/quick exit">quick_exit</a></code> </li> +<li> <code><a href="program/at_quick_exit" title="c/program/at quick exit">at_quick_exit</a></code> </li> +<li> Exclusive modes of <code><a href="io/fopen" title="c/io/fopen">fopen()</a></code> and <code><a href="io/freopen" title="c/io/freopen">freopen()</a></code> (<code>"x"</code>) </li> +<li> <a href="error#Bounds_checking" title="c/error">Bounds checking functions</a> </li> +<li> <a href="chrono/timespec" title="c/chrono/timespec"><code>timespec</code></a> </li> +<li> <a href="chrono/timespec_get" title="c/chrono/timespec get"><code>timespec_get()</code></a> </li> +<li> <a href="numeric/complex/cmplx" title="c/numeric/complex/CMPLX"><code>CMPLX(F|L)?</code></a> </li> +<li> New numeric limit macros <ul> +<li> <a href="types/limits" title="c/types/limits"><code>(FLT|DBL|LDBL)_DECIMAL_DIG</code></a> </li> +<li> <a href="types/limits" title="c/types/limits"><code>(FLT|DBL|LDBL)_TRUE_MIN</code></a> </li> +<li> <a href="types/limits" title="c/types/limits"><code>(FLT|DBL|LDBL)_HAS_SUBNORM</code></a> </li> +</ul> </li> +<li> Thread local <code><a href="error/errno" title="c/error/errno">errno</a></code> </li> +</ul> <h2 id="Defect_reports"> Defect reports</h2> <p><a href="https://en.cppreference.com/mwiki/index.php?title=Template:c/language/history/DR11&action=edit&redlink=1" class="new" title="Template:c/language/history/DR11 (page does not exist)">Template:c/language/history/DR11</a></p> +<h2 id="Compiler_support"> Compiler support</h2> <p><a href="https://en.cppreference.com/mwiki/index.php?title=Template:c/compiler_support/11&action=edit&redlink=1" class="new" title="Template:c/compiler support/11 (page does not exist)">Template:c/compiler support/11</a></p> +<div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/11" class="_attribution-link">https://en.cppreference.com/w/c/11</a> + </p> +</div> diff --git a/devdocs/c/17.html b/devdocs/c/17.html new file mode 100644 index 00000000..2cb44849 --- /dev/null +++ b/devdocs/c/17.html @@ -0,0 +1,70 @@ + <h1 id="firstHeading" class="firstHeading">C17</h1> <p><b>ISO/IEC 9899:2018</b>, a.k.a. <b>C17</b>/<b>C18</b> (denote the year of completion and publication respectively), is the current revision of the C standard.</p> +<p>C17 is same as C11, except that it bumps the <a href="preprocessor/replace" title="c/preprocessor/replace"><code>__STDC_VERSION__</code></a> predefined macro to <code>201710L</code>, contains several defect reports, and deprecates some features.</p> +<h2 id="Obsolete"> Obsolete</h2> <h3 id="Deprecated"> Deprecated</h3> <ul> +<li> <code><a href="atomic/atomic_var_init" title="c/atomic/ATOMIC VAR INIT">ATOMIC_VAR_INIT</a></code> </li> +<li> Support for calling <a href="memory/realloc" title="c/memory/realloc"><code>realloc()</code></a> with zero size </li> +</ul> <h2 id="Defect_reports"> Defect reports</h2> <div style="margin-left:0px"> <table class="mw-collapsible mw-collapsed"> <tr> <th>Defect Reports fixed in C17 (54 defects) </th> +</tr> <tr> <td> <ul> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_400">DR 400</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_401">DR 401</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_402">DR 402</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_403">DR 403</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_404">DR 404</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_405">DR 405</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_406">DR 406</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_407">DR 407</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_410">DR 410</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_412">DR 412</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_414">DR 414</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_415">DR 415</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_416">DR 416</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_417">DR 417</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_419">DR 419</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_423">DR 423</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_426">DR 426</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_428">DR 428</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_429">DR 429</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_430">DR 430</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_431">DR 431</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_433">DR 433</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_434">DR 434</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_436">DR 436</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_437">DR 437</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_438">DR 438</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_439">DR 439</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_441">DR 441</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_444">DR 444</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_445">DR 445</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_447">DR 447</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_448">DR 448</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_450">DR 450</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_452">DR 452</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_453">DR 453</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_457">DR 457</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_458">DR 458</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_459">DR 459</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_460">DR 460</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_462">DR 462</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_464">DR 464</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_465">DR 465</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_468">DR 468</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_470">DR 470</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_471">DR 471</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_472">DR 472</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_473">DR 473</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_475">DR 475</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_477">DR 477</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_480">DR 480</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_481">DR 481</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_485">DR 485</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_487">DR 487</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_491">DR 491</a> </li> +</ul> </td> +</tr> +</table> +</div> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/17" class="_attribution-link">https://en.cppreference.com/w/c/17</a> + </p> +</div> diff --git a/devdocs/c/23.html b/devdocs/c/23.html new file mode 100644 index 00000000..e3a73d0b --- /dev/null +++ b/devdocs/c/23.html @@ -0,0 +1,193 @@ + <h1 id="firstHeading" class="firstHeading">C23</h1> <p>The next generation of the C standard.</p> +<p>See: <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n3096.pdf">The current WD of C23</a>.</p> +<h2 id="Obsolete"> Obsolete</h2> <h3 id="Removed"> Removed</h3> <ul> +<li> Old-style function <a href="language/function_declaration" title="c/language/function declaration">declarations</a> and <a href="language/function_definition" title="c/language/function definition">definitions</a> </li> +<li> Representations for <a href="language/arithmetic_types" title="c/language/arithmetic types">signed integers</a> other than two's complement </li> +<li> Permission that <code>u</code>/<code>U</code>-prefixed <a href="language/character_constant" title="c/language/character constant">character constants</a> and <a href="language/string_literal" title="c/language/string literal">string literals</a> may be not UTF-16/32 </li> +<li> Mixed wide <a href="language/string_literal" title="c/language/string literal">string literal</a> concatenation </li> +<li> Support for calling <a href="memory/realloc" title="c/memory/realloc"><code>realloc()</code></a> with zero size (the behavior becomes undefined) </li> +<li> <a href="types" title="c/types"><code>__alignof_is_defined</code></a> and <a href="types" title="c/types"><code>__alignas_is_defined</code></a> </li> +<li> <a href="error/static_assert" title="c/error/static assert"><code>static_assert</code></a> is not provided as a macro defined in <a href="error" title="c/error"><code><assert.h></code></a> (becomes a keyword) </li> +<li> <a href="thread/thread_local" title="c/thread/thread local"><code>thread_local</code></a> is not provided as a macro defined in <a href="thread" title="c/thread"><code><threads.h></code></a> (becomes a keyword) </li> +</ul> <h3 id="Deprecated"> Deprecated</h3> <ul> +<li> <a href="language/_noreturn" title="c/language/ Noreturn"><code><stdnoreturn.h></code></a> </li> +<li> Old feature-test macros <ul> +<li> <a href="preprocessor/replace" title="c/preprocessor/replace"><code>__STDC_IEC_559__</code></a> </li> +<li> <a href="preprocessor/replace" title="c/preprocessor/replace"><code>__STDC_IEC_559_COMPLEX__</code></a> </li> +</ul> </li> +<li> <a href="language/_noreturn" title="c/language/ Noreturn"><code>_Noreturn</code></a> function specifier </li> +<li> <a href="language/attributes/noreturn" title="c/language/attributes/noreturn"><code>_Noreturn</code></a> attribute token </li> +<li> <code><a href="chrono/asctime" title="c/chrono/asctime">asctime()</a></code> </li> +<li> <code><a href="chrono/ctime" title="c/chrono/ctime">ctime()</a></code> </li> +<li> <a href="types/limits" title="c/types/limits"><code>DECIMAL_DIG</code></a> (use the appropriate type-specific macro (<a href="types/limits#Limits_of_floating-point_types" title="c/types/limits"><code>FLT_DECIMAL_DIG</code></a>, etc) instead) </li> +<li> Definition of following numeric limit macros in <a href="numeric/math" title="c/numeric/math"><code><math.h></code></a> (they should be used via <a href="types/limits#Limits_of_floating_point_types" title="c/types/limits"><code><float.h></code></a>) <ul> +<li> <a href="numeric/math" title="c/numeric/math"><code>INFINITY</code></a> </li> +<li> <a href="numeric/math" title="c/numeric/math"><code>DEC_INFINITY</code></a> </li> +<li> <a href="numeric/math" title="c/numeric/math"><code>NAN</code></a> </li> +<li> <a href="numeric/math" title="c/numeric/math"><code>DEC_NAN</code></a> </li> +</ul> </li> +<li> <a href="types" title="c/types"><code>__bool_true_false_are_defined</code></a> </li> +</ul> <h2 id="New_language_features"> New language features</h2> <ul> +<li> <a href="language/arithmetic_types" title="c/language/arithmetic types">Decimal floating-point types</a> (<a href="keyword/_decimal32" title="c/keyword/ Decimal32"><code>_Decimal32</code></a>, <a href="keyword/_decimal64" title="c/keyword/ Decimal64"><code>_Decimal64</code></a>, and <a href="keyword/_decimal128" title="c/keyword/ Decimal128"><code>_Decimal128</code></a>) </li> +<li> <a href="language/arithmetic_types" title="c/language/arithmetic types">Bit-precise integers</a> (<a href="https://en.cppreference.com/mwiki/index.php?title=c/keyword/_BitInt&action=edit&redlink=1" class="new" title="c/keyword/ BitInt (page does not exist)"><code>_BitInt</code></a>) </li> +<li> <a href="language/integer_constant" title="c/language/integer constant">Binary integer constants</a> </li> +<li> <a href="language/character_constant" title="c/language/character constant"><code>u8</code> character constants</a> </li> +<li> Type change of <a href="language/string_literal" title="c/language/string literal"><code>u8</code> string literals</a> </li> +<li> Digit separator <code>'</code> </li> +<li> Empty <a href="language/initialization" title="c/language/initialization">initializer</a> <code>={}</code> </li> +<li> <a href="language/attributes" title="c/language/attributes">Attributes</a> <ul> +<li> <code>[[<a href="language/attributes/deprecated" title="c/language/attributes/deprecated">deprecated</a>]]</code> </li> +<li> <code>[[<a href="language/attributes/fallthrough" title="c/language/attributes/fallthrough">fallthrough</a>]]</code> </li> +<li> <code>[[<a href="language/attributes/maybe_unused" title="c/language/attributes/maybe unused">maybe_unused</a>]]</code> </li> +<li> <code>[[<a href="language/attributes/nodiscard" title="c/language/attributes/nodiscard">nodiscard</a>]]</code> </li> +<li> <code>[[<a href="language/attributes/noreturn" title="c/language/attributes/noreturn">noreturn</a>]]</code> </li> +<li> <code>[[<a href="language/attributes/reproducible" title="c/language/attributes/reproducible" class="mw-redirect">reproducible</a>]]</code> </li> +<li> <code>[[<a href="language/attributes/unsequenced" title="c/language/attributes/unsequenced">unsequenced</a>]]</code> </li> +</ul> </li> +<li> Unnamed parameters in <a href="language/function_definition" title="c/language/function definition">function definitions</a> </li> +<li> Identical cvr-qualifications for <a href="language/array" title="c/language/array">array types</a> and their element types </li> +<li> Single-argument <a href="language/_static_assert" title="c/language/ Static assert"><code>_Static_assert</code></a> </li> +<li> <a href="keyword/static_assert" title="c/keyword/static assert"><code>static_assert</code></a> becomes a keyword (may be a predefined macro for compatibility reasons) </li> +<li> <a href="keyword/thread_local" title="c/keyword/thread local"><code>thread_local</code></a> becomes a keyword (may be a predefined macro for compatibility reasons) </li> +<li> <a href="language/goto" title="c/language/goto">Labels</a> followed by declarations and <code>}</code> </li> +<li> <a href="keyword/nullptr" title="c/keyword/nullptr"><code>nullptr</code></a> constant and the associated <a href="types/nullptr_t" title="c/types/nullptr t"><code>nullptr_t</code></a> type </li> +<li> <a href="keyword/true" title="c/keyword/true"><code>true</code></a> and <a href="keyword/false" title="c/keyword/false"><code>false</code></a> become keywords (may be predefined macros for compatibility reasons) </li> +<li> New preprocessor directives <ul> +<li> <a href="preprocessor/conditional" title="c/preprocessor/conditional"><code> #elifdef</code></a> </li> +<li> <a href="preprocessor/conditional" title="c/preprocessor/conditional"><code> #elifndef</code></a> </li> +<li> <a href="preprocessor/error" title="c/preprocessor/error"><code> #warning</code></a> </li> +<li> <a href="preprocessor/embed" title="c/preprocessor/embed"><code> #embed</code></a> </li> +</ul> </li> +<li> Pragmas for rounding direction <ul> +<li> <code>STDC</code> <a href="preprocessor/impl" title="c/preprocessor/impl"><code>FENV_ROUND</code></a> </li> +<li> <code>STDC</code> <a href="preprocessor/impl" title="c/preprocessor/impl"><code>FENV_DEC_ROUND</code></a> </li> +</ul> </li> +</ul> <h3 id="Feature_test_macros_for_optional_features"> Feature test macros for optional features</h3> <ul> +<li> <a href="preprocessor/replace" title="c/preprocessor/replace"><code>__STDC_IEC_60559_BFP__</code></a> <ul><li> Indicates IEEE-754 binary floating-point arithmetic and required math functions are supported. </li></ul> This macro supersedes <a href="preprocessor/replace" title="c/preprocessor/replace"><code>__STDC_IEC_559__</code></a>. </li> +<li> <a href="preprocessor/replace" title="c/preprocessor/replace"><code>__STDC_IEC_60559_DFP__</code></a> <ul><li> Indicates IEEE-754 decimal floating-point arithmetic and required math functions are supported. </li></ul> </li> +<li> <a href="preprocessor/replace" title="c/preprocessor/replace"><code>__STDC_IEC_60559_COMPLEX__</code></a> <ul><li> Indicates IEEE-754 complex arithmetic and required math functions are supported. </li></ul> This macro supersedes <a href="preprocessor/replace" title="c/preprocessor/replace"><code>__STDC_IEC_559_COMPLEX__</code></a>. </li> +</ul> <h2 id="New_library_features"> New library features</h2> <h3 id="New_headers"> New headers</h3> <ul> +<li> <code><stdbit.h></code> </li> +<li> <code><stdckdint.h></code> </li> +</ul> <h3 id="Library_features"> Library features</h3> <ul> +<li> Extended binary floating-point math functions </li> +<li> Decimal floating-point math functions <ul> +<li> -<code>d<i>N</i></code> variants for existing and new floating-point math functions </li> +<li> <a href="https://en.cppreference.com/mwiki/index.php?title=c/numeric/math/quantize&action=edit&redlink=1" class="new" title="c/numeric/math/quantize (page does not exist)"><code>quantizedN()</code></a> </li> +<li> <a href="https://en.cppreference.com/mwiki/index.php?title=c/numeric/math/samequantum&action=edit&redlink=1" class="new" title="c/numeric/math/samequantum (page does not exist)"><code>samequantumdN()</code></a> </li> +<li> <a href="https://en.cppreference.com/mwiki/index.php?title=c/numeric/math/quantum&action=edit&redlink=1" class="new" title="c/numeric/math/quantum (page does not exist)"><code>quantumdN()</code></a> </li> +<li> <a href="https://en.cppreference.com/mwiki/index.php?title=c/numeric/math/llquantexp&action=edit&redlink=1" class="new" title="c/numeric/math/llquantexp (page does not exist)"><code>llquantexpdN()</code></a> </li> +<li> <a href="https://en.cppreference.com/mwiki/index.php?title=c/numeric/math/encodedec&action=edit&redlink=1" class="new" title="c/numeric/math/encodedec (page does not exist)"><code>encodedecdN()</code></a> </li> +<li> <a href="https://en.cppreference.com/mwiki/index.php?title=c/numeric/math/decodedec&action=edit&redlink=1" class="new" title="c/numeric/math/decodedec (page does not exist)"><code>decodedecdN()</code></a> </li> +<li> <a href="https://en.cppreference.com/mwiki/index.php?title=c/numeric/math/encodebin&action=edit&redlink=1" class="new" title="c/numeric/math/encodebin (page does not exist)"><code>encodebindN()</code></a> </li> +<li> <a href="https://en.cppreference.com/mwiki/index.php?title=c/numeric/math/decodebin&action=edit&redlink=1" class="new" title="c/numeric/math/decodebin (page does not exist)"><code>decodebindN()</code></a> </li> +</ul> </li> +<li> <a href="string/byte/strfromf" title="c/string/byte/strfromf">Floating-point formatting functions</a> </li> +<li> Library support for UTF-8 <ul> +<li> <code>char8_t</code> type alias </li> +<li> <a href="string/multibyte/mbrtoc8" title="c/string/multibyte/mbrtoc8"><code>mbrtoc8()</code></a> </li> +<li> <a href="string/multibyte/c8rtomb" title="c/string/multibyte/c8rtomb"><code>c8rtomb()</code></a> </li> +<li> <a href="thread" title="c/thread"><code>atomic_char8_t</code></a> type alias </li> +<li> <a href="atomic/atomic_lock_free_consts" title="c/atomic/ATOMIC LOCK FREE consts"><code>ATOMIC_CHAR8_T_LOCK_FREE</code></a> test macro </li> +</ul> </li> +<li> <a href="string/byte/memset" title="c/string/byte/memset"><code>memset_explicit()</code></a> </li> +<li> POSIX functions <ul> +<li> <a href="string/byte/memccpy" title="c/string/byte/memccpy"><code>memccpy()</code></a> </li> +<li> <a href="string/byte/strdup" title="c/string/byte/strdup"><code>strdup()</code></a> </li> +<li> <a href="string/byte/strndup" title="c/string/byte/strndup"><code>strndup()</code></a> </li> +<li> <a href="chrono/gmtime" title="c/chrono/gmtime"><code>gmtime_r()</code></a> </li> +<li> <a href="chrono/localtime" title="c/chrono/localtime"><code>localtime_r()</code></a> </li> +<li> Extensions for <a href="chrono/strftime" title="c/chrono/strftime"><code>strftime()</code></a> and <a href="chrono/wcsftime" title="c/chrono/wcsftime"><code>wcsftime()</code></a> </li> +</ul> </li> +<li> Extensions for <a href="io/fscanf" title="c/io/fscanf"><code>fscanf()</code></a> and <a href="io/fprintf" title="c/io/fprintf"><code>fprintf()</code></a> function families <ul> +<li> <code>w<i>N</i></code> and <code>wf<i>N</i></code> length modifiers for <a href="types/integer" title="c/types/integer"><code>[u]intN_t</code></a> and <a href="types/integer" title="c/types/integer"><code>[u]int_fastN_t</code></a> respectively </li> +<li> <code>H</code>, <code>D</code>, and <code>DD</code> length modifiers for <code>_Decimal32</code>, <code>_Decimal64</code>, and <code>_Decimal128</code> respectively </li> +<li> <code>b</code> conversion specifier for unsigned integer types </li> +</ul> </li> +<li> <a href="chrono/timespec_getres" title="c/chrono/timespec getres"><code>timespec_getres()</code></a> </li> +<li> Macro constants for width of integer types </li> +<li> Additional numeric limit macros for floating-point types </li> +<li> Library version-test macros <ul> +<li> <a href="numeric/fenv" title="c/numeric/fenv"><code>__STDC_VERSION_FENV_H__</code></a> </li> +<li> <a href="numeric/math" title="c/numeric/math"><code>__STDC_VERSION_MATH_H__</code></a> </li> +<li> <a href="types/integer" title="c/types/integer"><code>__STDC_VERSION_STDINT_H__</code></a> </li> +<li> <a href="string/byte" title="c/string/byte"><code>__STDC_VERSION_STDLIB_H__</code></a> </li> +<li> <a href="numeric/tgmath" title="c/numeric/tgmath"><code>__STDC_VERSION_TGMATH_H__</code></a> </li> +<li> <a href="chrono" title="c/chrono"><code>__STDC_VERSION_TIME_H__</code></a> </li> +<li> <a href="https://en.cppreference.com/mwiki/index.php?title=STDC_VERSION_STDCKDINT_H&action=edit&redlink=1" class="new" title="STDC VERSION STDCKDINT H (page does not exist)"><code>__STDC_VERSION_STDCKDINT_H__</code></a> </li> +<li> <a href="https://en.cppreference.com/mwiki/index.php?title=STDC_VERSION_STDBIT_H&action=edit&redlink=1" class="new" title="STDC VERSION STDBIT H (page does not exist)"><code>__STDC_VERSION_STDBIT_H__</code></a> </li> +</ul> </li> +</ul> <h2 id="Defect_reports"> Defect reports</h2> <div style="margin-left:0px"> <table class="mw-collapsible mw-collapsed"> <tr> <th>Defect Reports fixed in C23 (? defects) </th> +</tr> <tr> <td> <ul> +<li> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2379.htm">DR 440</a> </li> +<li> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2326.htm">DR 432</a> </li> +<li> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2326.htm">DR 467</a> </li> +<li> <a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_476">DR 476</a> </li> +<li> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2324.htm">DR 482</a> </li> +<li> <a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_488">DR 488</a> </li> +<li> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2713.htm">DR 489</a> </li> +<li> <a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_494">DR 494</a> </li> +<li> <a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_496">DR 496</a> </li> +<li> <a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_497">DR 497</a> </li> +<li> <a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_499">DR 499</a> </li> +<li> <a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_500">DR 500</a> </li> +<li> <a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_501">DR 501</a> </li> +</ul> </td> +</tr> +</table> +</div> <h2 id="Compiler_support"> Compiler support</h2> <h3 id="C23_core_language_features"> C23 core language features</h3> <table class="wikitable tbody-scroll mw-collapsible t-compiler-support-top"> <tr style="height:15em"> <th>C23 feature<br><br> </th> <th>Paper(s)<br><br> </th> <th> <div>GCC</div> </th> <th> <div>Clang</div> </th> <th> <div>MSVC</div> </th> <th> <div>Apple Clang</div> </th> <th> <div>EDG eccp</div> </th> <th> <div>Intel C++</div> </th> <th> <div>IBM XL C++</div> </th> <th> <div>IBM Open XL C++ for AIX</div> </th> <th> <div>IBM Open XL C++ for z/OS</div> </th> <th> <div>Sun/Oracle C++</div> </th> <th> <div>Embarcadero C++ Builder</div> </th> <th> <div>Cray</div> </th> <th> <div><span title="ex Portland Group/PGI">Nvidia HPC C++ (ex PGI)*</span></div> </th> <th> <div>Nvidia nvcc</div> </th> <th> </th> +</tr> <tr> <td> <a href="language/_static_assert" title="c/language/ Static assert"><code>_Static_assert</code></a> with no message </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2265.pdf">N2265</a> </td> <td class="table-yes">9 </td> <td class="table-yes">9 </td> <td class="table-yes">Yes </td> <td class="table-yes">Yes </td> <td class="table-yes">6.5 </td> <td class="table-yes">2021.1.2 (clang based) </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <code>[[<a href="language/attributes/nodiscard" title="c/language/attributes/nodiscard">nodiscard</a>]]</code> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2267.pdf">N2267</a> </td> <td class="table-yes">10 </td> <td class="table-yes">9 </td> <td class="table-no"> </td> <td class="table-yes">Yes </td> <td class="table-yes">6.4 </td> <td class="table-yes">2021.1.2 (clang based) </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <code>[[<a href="language/attributes/maybe_unused" title="c/language/attributes/maybe unused">maybe_unused</a>]]</code> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2270.pdf">N2270</a> </td> <td class="table-yes">10 </td> <td class="table-yes">9 </td> <td class="table-no"> </td> <td class="table-yes">Yes </td> <td class="table-yes">6.4 </td> <td class="table-yes">2021.1.2 (clang based) </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <code>[[<a href="language/attributes/deprecated" title="c/language/attributes/deprecated">deprecated</a>]]</code> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2334.pdf">N2334</a> </td> <td class="table-yes">10 </td> <td class="table-yes">9 </td> <td class="table-no"> </td> <td class="table-yes">Yes </td> <td class="table-yes">6.4 </td> <td class="table-yes">2021.1.2 (clang based) </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <a href="language/attributes" title="c/language/attributes">Attributes</a> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2335.pdf">N2335</a><br><a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2554.pdf">N2554</a> </td> <td class="table-yes">10 </td> <td class="table-yes">9 </td> <td class="table-no"> </td> <td class="table-yes">Yes </td> <td class="table-yes">6.4 </td> <td class="table-yes">2021.1.2 (clang based) </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> IEEE 754 decimal floating-point types </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2341.pdf">N2341</a> </td> <td class="table-maybe">4.2 <span title="Only TR 24732 mentioned; some requirements in core language missing">(partial)*</span> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-maybe">13.0 <span title="Only IEEE 754-2008 mentioned; the status of conformance is unknown">(partial)*</span> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <code>[[<a href="language/attributes/fallthrough" title="c/language/attributes/fallthrough">fallthrough</a>]]</code> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2408.pdf">N2408</a> </td> <td class="table-yes">10 </td> <td class="table-yes">9 </td> <td class="table-no"> </td> <td class="table-yes">Yes </td> <td class="table-yes">6.4 </td> <td class="table-yes">2021.1.2 (clang based) </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <a href="language/character_constant" title="c/language/character constant"><code>u8</code> character constants</a> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2418.pdf">N2418</a> </td> <td class="table-yes">10 </td> <td class="table-yes">15 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-yes">6.5 </td> <td class="table-yes">2022.2 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Removal of <a href="language/function_definition" title="c/language/function definition">function definitions</a> without prototype </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2432.pdf">N2432</a> </td> <td class="table-yes">10 </td> <td class="table-yes">15 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-yes">2022.2 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <code>[[<a href="language/attributes/nodiscard" title="c/language/attributes/nodiscard">nodiscard</a>]]</code> with message </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2448.pdf">N2448</a> </td> <td class="table-yes">11 </td> <td class="table-yes">10 </td> <td class="table-no"> </td> <td class="table-yes">Yes </td> <td class="table-yes">6.4 </td> <td class="table-yes">2021.1.2 (clang based) </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Unnamed parameters in function definitions </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2480.pdf">N2480</a> </td> <td class="table-yes">11 </td> <td class="table-yes">11 </td> <td class="table-no"> </td> <td class="table-yes">Yes </td> <td class="table-yes">6.4 </td> <td class="table-yes">2021.1.2 (clang based) </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <a href="language/statements#Labels" title="c/language/statements">Labels</a> before declarations and end of blocks </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2508.pdf">N2508</a> </td> <td class="table-yes">11 </td> <td class="table-yes">16 </td> <td class="table-maybe">Partial<span title="extension, missing support for labels before end of blocks">*</span> </td> <td class="table-no"> </td> <td class="table-yes">6.5 </td> <td class="table-yes">17.0<span title="extension, would trigger warnings; +missing support for labels before declarations in old versions">*</span> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <a href="language/integer_constant" title="c/language/integer constant">Binary integer constants</a> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2549.pdf">N2549</a> </td> <td class="table-yes">4.3<span title="extension">*</span><br>11 </td> <td class="table-yes">2.9<span title="extension">*</span><br>9 </td> <td class="table-yes"> +<span title="VS 2015">19.0 (2015)*</span><span title="extension">*</span> </td> <td class="table-yes">Yes </td> <td class="table-yes">6.5 </td> <td class="table-yes">11.0<span title="extension">*</span> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <a href="language/attributes#Attribute_testing" title="c/language/attributes"><code>__has_c_attribute</code></a> in preprocessor conditionals </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2553.pdf">N2553</a> </td> <td class="table-yes">11 </td> <td class="table-yes">9 </td> <td class="table-no"> </td> <td class="table-yes">Yes </td> <td class="table-yes">6.5 </td> <td class="table-yes">2021.1.2 (clang based) </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Allow duplicate attributes </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2557.pdf">N2557</a> </td> <td class="table-yes">11 </td> <td class="table-yes">13 </td> <td class="table-no"> </td> <td class="table-yes">Yes </td> <td class="table-yes">6.5 </td> <td class="table-yes">2021.4 (clang-based </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> IEEE 754 interchange and extended types </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2601.pdf">N2601</a> </td> <td class="table-maybe">7 <span title="Only TS 18661-3 mentioned; the status of conformance is unknown">(partial)*</span> </td> <td class="table-maybe">6 <span title="Only _Float16 is supported">(partial)*</span> </td> <td class="table-no"> </td> <td class="table-maybe"> +<span title="Only _Float16 is supported">Partial*</span> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Digit separators </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2626.pdf">N2626</a> </td> <td class="table-yes">12 </td> <td class="table-yes">13 </td> <td class="table-yes"> +<span title="VS 2015">19.0 (2015)*</span><span title="extension">*</span> </td> <td class="table-yes">Yes </td> <td class="table-yes">6.5 </td> <td class="table-yes">18.0<span title="extension">*</span> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <a href="preprocessor/conditional" title="c/preprocessor/conditional"><code>#elifdef</code> and <code>#elifndef</code></a> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2645.pdf">N2645</a> </td> <td class="table-yes">12 </td> <td class="table-yes">13 </td> <td class="table-no"> </td> <td class="table-yes"> <p><span title="Xcode 13.3 (13E113)">13.1.6*</span></p> +</td> <td class="table-yes">6.5 </td> <td class="table-yes">2021.4 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Type change of <a href="language/string_literal" title="c/language/string literal"><code>u8</code> string literals</a> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2653.htm">N2653</a> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <code>[[<a href="language/attributes/maybe_unused" title="c/language/attributes/maybe unused">maybe_unused</a>]]</code> for labels </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2662.pdf">N2662</a> </td> <td class="table-yes">11 </td> <td class="table-yes">16 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-yes">6.5 </td> <td class="table-yes">2022.2 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <a href="preprocessor/error" title="c/preprocessor/error"><code> #warning</code></a> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2686.pdf">N2686</a> </td> <td class="table-yes">Yes </td> <td class="table-yes">Yes </td> <td class="table-no"> </td> <td class="table-yes">Yes </td> <td class="table-yes">6.5 </td> <td class="table-yes">Yes </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Bit-precise integer types (<code>_BitInt</code>) </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2763.pdf">N2763</a> </td> <td class="table-no"> </td> <td class="table-yes">15 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-yes">6.5 </td> <td class="table-yes">2022.2 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <code>[[<a href="language/attributes/noreturn" title="c/language/attributes/noreturn">noreturn</a>]]</code> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2764.pdf">N2764</a> </td> <td class="table-yes">13 </td> <td class="table-yes">15 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-yes">6.5 </td> <td class="table-yes">2022.2 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Suffixes for bit-precise integer constants </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2775.pdf">N2775</a> </td> <td class="table-no"> </td> <td class="table-yes">15 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-yes">2022.2 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <a href="preprocessor/include" title="c/preprocessor/include"><code>__has_include</code></a> in preprocessor conditionals </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2799.pdf">N2799</a> </td> <td class="table-yes">5 </td> <td class="table-yes">Yes </td> <td class="table-yes"> +<span title="VS 2017 15.3">19.11*</span> </td> <td class="table-yes">Yes </td> <td class="table-yes">6.5 </td> <td class="table-yes">18.0 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Identifier Syntax using Unicode Standard Annex 31 </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2836.pdf">N2836</a> </td> <td class="table-yes">13 </td> <td class="table-yes">15 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-yes">6.5 </td> <td class="table-yes">2022.2 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Removal of <a href="language/function_declaration" title="c/language/function declaration">function declarations</a> without prototype </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2841.htm">N2841</a> </td> <td class="table-yes">13 </td> <td class="table-yes">15 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-yes">2022.2 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <a href="language/initialization#Empty_initialization" title="c/language/initialization">Empty initializers</a> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2900.htm">N2900</a> </td> <td class="table-maybe">Partial<span title="extension; missing support for scalars and VLAs">*</span> </td> <td class="table-maybe">Partial<span title="extension; missing support for scalars and VLAs">*</span> </td> <td class="table-no"> </td> <td class="table-maybe">Partial<span title="extension; missing support for scalars and VLAs">*</span> </td> <td class="table-maybe">Partial<span title="extension; missing support for scalars and VLAs">*</span> </td> <td class="table-maybe">Partial<span title="extension; missing support for scalars and VLAs">*</span> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <a href="language/typeof" title="c/language/typeof"><code>typeof</code></a> and <a href="language/typeof" title="c/language/typeof"><code>typeof_unqual</code></a> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2927.htm">N2927</a><br><a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2930.pdf">N2930</a> </td> <td class="table-yes">Partial<span title="extension; only typeof (and __typeof__ in strict modes)">*</span><br>13 </td> <td class="table-yes">Partial<span title="extension; only typeof (and __typeof__ in strict modes)">*</span><br>16 </td> <td class="table-no"> </td> <td class="table-maybe">Partial<span title="extension; only typeof (and __typeof__ in strict modes)">*</span> </td> <td class="table-maybe">Partial<span title="extension; only typeof (and __typeof__ in strict modes)">*</span> </td> <td class="table-maybe">Partial<span title="extension; only typeof (and __typeof__ in strict modes)">*</span> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-maybe">Partial<span title="extension; only typeof (and __typeof__ in strict modes)">*</span> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> New spelling of keywords </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2934.pdf">N2934</a> </td> <td class="table-maybe">13 </td> <td class="table-maybe">16 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-yes">6.5 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Predefined <a href="language/bool_constant" title="c/language/bool constant"><code>true</code> and <code>false</code></a> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2935.pdf">N2935</a> </td> <td class="table-yes">13 </td> <td class="table-yes">15 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-yes">2022.2 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <code>[[<a href="language/attributes/unsequenced" title="c/language/attributes/unsequenced">unsequenced</a>]]</code> and <code>[[<a href="language/attributes/reproducible" title="c/language/attributes/reproducible" class="mw-redirect">reproducible</a>]]</code> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2956.htm">N2956</a> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Relax requirements for <a href="language/variadic" title="c/language/variadic">variadic parameter list</a> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2975.pdf">N2975</a> </td> <td class="table-yes">13 </td> <td class="table-yes">16 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-yes">6.5 </td> <td class="table-yes">2023.1 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Type inference in object definitions </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n3007.htm">N3007</a> </td> <td class="table-yes">13 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <a href="preprocessor/embed" title="c/preprocessor/embed"><code> #embed</code></a> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n3017.htm">N3017</a> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <a href="language/constexpr" title="c/language/constexpr"><code>constexpr</code></a> objects </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n3018.htm">N3018</a> </td> <td class="table-yes">13 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Improved Normal Enumerations </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n3029.htm">N3029</a> </td> <td class="table-yes">13 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Enhancements to Enumerations </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n3030.htm">N3030</a> </td> <td class="table-yes">13 </td> <td class="table-maybe">Maybe </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <a href="preprocessor/replace#Function-like_macros" title="c/preprocessor/replace"><code>__VA_OPT__</code></a> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n3033.htm">N3033</a> </td> <td class="table-maybe">8 </td> <td class="table-maybe">12 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-yes">6.5 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Storage-class specifiers for compound literals </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n3038.htm">N3038</a> </td> <td class="table-yes">13 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <a href="language/nullptr" title="c/language/nullptr"><code>nullptr</code></a> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n3042.htm">N3042</a> </td> <td class="table-yes">13 </td> <td class="table-maybe">16 </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr style="height:15em"> <th> <br><br>C23 feature </th> <th> <br><br>Paper(s) </th> <th> <div>GCC</div> </th> <th> <div>Clang</div> </th> <th> <div>MSVC</div> </th> <th> <div>Apple Clang</div> </th> <th> <div>EDG eccp</div> </th> <th> <div>Intel C++</div> </th> <th> <div>IBM XL C++</div> </th> <th> <div>IBM Open XL C++ for AIX</div> </th> <th> <div>IBM Open XL C++ for z/OS</div> </th> <th> <div>Sun/Oracle C++</div> </th> <th> <div>Embarcadero C++ Builder</div> </th> <th> <div>Cray</div> </th> <th> <div><span title="ex Portland Group/PGI">Nvidia HPC C++ (ex PGI)*</span></div> </th> <th> <div>Nvidia nvcc</div> </th> +</tr> +</table> <h3 id="C23_library_features"> C23 library features</h3> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/23" class="_attribution-link">https://en.cppreference.com/w/c/23</a> + </p> +</div> diff --git a/devdocs/c/95.html b/devdocs/c/95.html new file mode 100644 index 00000000..32318a0a --- /dev/null +++ b/devdocs/c/95.html @@ -0,0 +1,14 @@ + <h1 id="firstHeading" class="firstHeading">C95</h1> <p><b>ISO/IEC 9899/AMD1:1995</b>, a.k.a. <b>C95</b>, is a previous revision of the C standard.</p> +<h2 id="New_language_features"> New language features</h2> <ul> +<li> <a href="language/operator_alternative" title="c/language/operator alternative">Digraphs</a> </li> +<li> <a href="preprocessor/replace" title="c/preprocessor/replace"><code>__STDC_VERSION__</code></a> </li> +</ul> <h2 id="New_library_features"> New library features </h2> <h3 id="New_headers"> New headers</h3> <ul> +<li> <a href="language/operator_alternative" title="c/language/operator alternative"><code><iso646.h></code></a> </li> +<li> <a href="string/wide" title="c/string/wide"><code><wctype.h></code></a> </li> +<li> <a href="string/wide" title="c/string/wide"><code><wchar.h></code></a> </li> +</ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/95" class="_attribution-link">https://en.cppreference.com/w/c/95</a> + </p> +</div> diff --git a/devdocs/c/99.html b/devdocs/c/99.html new file mode 100644 index 00000000..50a02097 --- /dev/null +++ b/devdocs/c/99.html @@ -0,0 +1,142 @@ + <h1 id="firstHeading" class="firstHeading">C99</h1> <p><b>ISO/IEC 9899:1999</b>, a.k.a. <b>C99</b>, is a previous revision of the C standard.</p> +<h2 id="Obsolete"> Obsolete</h2> <h3 id="Removed"> Removed</h3> <ul> +<li> Implicit <code>int</code> in declarations </li> +<li> Implicit function declarations </li> +</ul> <h3 id="Deprecated"> Deprecated</h3> <ul><li> <code><a href="io/gets" title="c/io/gets">gets()</a></code> </li></ul> <h2 id="New_language_features"> New language features</h2> <ul> +<li> Universal-character-names in <a href="language/identifier" title="c/language/identifier">identifiers</a> </li> +<li> Increased <a href="language/identifier#Translation_limits" title="c/language/identifier">translation limits</a> </li> +<li> <code>//</code> <a href="comment" title="c/comment">comments</a> </li> +<li> <a href="language/restrict" title="c/language/restrict"><code>restrict</code></a> pointers </li> +<li> Enhanced <a href="language/arithmetic_types" title="c/language/arithmetic types">arithmetic types</a> <ul> +<li> <code>_Bool</code> </li> +<li> <code>long long</code> and <code>unsigned long long</code> </li> +<li> Extended integer types </li> +<li> <a href="keyword/_complex" title="c/keyword/ Complex"><code>_Complex</code></a> types (<code>float _Complex</code>, <code>double _Complex</code>, and <code>long double _Complex</code>) </li> +<li> <a href="keyword/_imaginary" title="c/keyword/ Imaginary"><code>_Imaginary</code></a> types (<code>float _Imaginary</code>, <code>double _Imaginary</code>, and <code>long double _Imaginary</code>) </li> +</ul> </li> +<li> Flexible array members </li> +<li> <a href="language/array#Variable-length_arrays" title="c/language/array">Variable-length array</a> (VLA) types and variably-modified (VM) types </li> +<li> Improvements of <span class="t-spar">braced-init-list</span> for <a href="language/array_initialization" title="c/language/array initialization">array</a>, <a href="language/struct_initialization" title="c/language/struct initialization">struct and union</a> types <ul> +<li> Non-constant initializers </li> +<li> Designated initializers </li> +</ul> </li> +<li> Idempotent cvr-qualifiers </li> +<li> Trailing comma in <a href="language/enum" title="c/language/enum"><span class="t-spar">enumerator-list</span></a> </li> +<li> Hexadecimal <a href="language/floating_constant" title="c/language/floating constant">floating constants</a> </li> +<li> <a href="language/compound_literal" title="c/language/compound literal">Compound literals</a> </li> +<li> Floating-point environment </li> +<li> Requiring truncation for divisions of signed integer types </li> +<li> Implicit <code>return 0;</code> in the <a href="language/main_function" title="c/language/main function"><code>main()</code> function</a> </li> +<li> Declarations and statements in mixed order </li> +<li> <span class="t-spar">init-statement</span> in <a href="language/for" title="c/language/for"><code>for</code></a> loops </li> +<li> <a href="language/inline" title="c/language/inline"><code>inline</code></a> functions </li> +<li> Predefined variable <a href="language/function_definition" title="c/language/function definition"><code>__func__</code></a> </li> +<li> Cvr-qualifiers and <code>static</code> in <code>[]</code> within function declarations </li> +<li> <a href="preprocessor/replace" title="c/preprocessor/replace">Variadic macros</a> </li> +<li> <a href="preprocessor/impl" title="c/preprocessor/impl"><code>_Pragma</code></a> preprocessor operator </li> +<li> Standard pragmas for floating-point evaluation <ul> +<li> <code>STDC</code> <a href="preprocessor/impl" title="c/preprocessor/impl"><code>FENV_ACCESS</code></a> </li> +<li> <code>STDC</code> <a href="preprocessor/impl" title="c/preprocessor/impl"><code>FP_CONTRACT</code></a> </li> +<li> <code>STDC</code> <a href="preprocessor/impl" title="c/preprocessor/impl"><code>CX_LIMITED_RANGE</code></a> </li> +</ul> </li> +</ul> <h3 id="Feature_test_macros_for_optional_features"> Feature test macros for optional features</h3> <ul> +<li> <a href="preprocessor/replace" title="c/preprocessor/replace"><code>__STDC_IEC_559__</code></a> <ul><li> Indicates IEEE-754 binary floating-point arithmetic and required math functions are supported. </li></ul> </li> +<li> <a href="preprocessor/replace" title="c/preprocessor/replace"><code>__STDC_IEC_559_COMPLEX__</code></a> <ul><li> Indicates IEEE-754 complex arithmetic and required math functions are supported. </li></ul> </li> +<li> <a href="preprocessor/replace" title="c/preprocessor/replace"><code>__STDC_HOSTED__</code></a> <ul><li> Indicates that the implementation is <a href="language/conformance" title="c/language/conformance">hosted</a>. </li></ul> </li> +<li> <a href="preprocessor/replace" title="c/preprocessor/replace"><code>__STDC_ISO_10646__</code></a> <ul><li> Indicates that Unicode is used by the wide literal encodings and expands to the latest supported revision. </li></ul> </li> +<li> <a href="preprocessor/replace" title="c/preprocessor/replace"><code>__STDC_MB_MIGHT_NEQ_WC__</code></a> <ul><li> Indicates that there are some characters in the basic character set having different code unit values in <a href="language/character_constant" title="c/language/character constant">ordinary and wide literal encodings</a>. </li></ul> </li> +</ul> <h2 id="New_library_features"> New library features</h2> <h3 id="New_headers"> New headers</h3> <ul> +<li> <a href="numeric/complex" title="c/numeric/complex"><code><complex.h></code></a> </li> +<li> <a href="numeric/fenv" title="c/numeric/fenv"><code><fenv.h></code></a> </li> +<li> <a href="types/integer" title="c/types/integer"><code><inttypes.h></code></a> </li> +<li> <a href="types" title="c/types"><code><stdbool.h></code></a> </li> +<li> <a href="types/integer" title="c/types/integer"><code><stdint.h></code></a> </li> +<li> <a href="numeric/tgmath" title="c/numeric/tgmath"><code><tgmath.h></code></a> </li> +</ul> <h3 id="Library_features"> Library features</h3> <ul> +<li> <a href="types/integer" title="c/types/integer">Aliases for integer types</a> <ul> +<li> Integer types with exact width (<code>int<i>N</i>_t</code> and <code>uint<i>N</i>_t</code>) </li> +<li> Fastest integer types with at least given width (<code>int_fast<i>N</i>_t</code> and <code>uint_fast<i>N</i>_t</code>) </li> +<li> Smallest integer types with at least given width (<code>int_least<i>N</i>_t</code> and <code>uint_least<i>N</i>_t</code>) </li> +<li> Integer types capable for cast between object pointers (<code><a href="types/integer" title="c/types/integer">intptr_t</a></code> and <code><a href="types/integer" title="c/types/integer">uintptr_t</a></code>) </li> +<li> Integer types with maximum width (<code><a href="types/integer" title="c/types/integer">intmax_t</a></code> and <code><a href="types/integer" title="c/types/integer">uintmax_t</a></code>) </li> +</ul> </li> +<li> Operations on <code>long long</code> and <code><a href="types/integer" title="c/types/integer">intmax_t</a></code> <ul> +<li> <code><a href="numeric/math/abs" title="c/numeric/math/abs">llabs()</a></code> </li> +<li> <code><a href="numeric/math/abs" title="c/numeric/math/abs">imaxabs()</a></code> </li> +<li> <code><a href="numeric/math/div" title="c/numeric/math/div">lldiv()</a></code> </li> +<li> <code><a href="numeric/math/div" title="c/numeric/math/div">imaxdiv()</a></code> </li> +</ul> </li> +<li> <a href="numeric/fenv" title="c/numeric/fenv">Floating-point environment access</a> </li> +<li> Extended floating-point math functions <ul> +<li> New floating-point math functions </li> +<li> -<code>f</code> and -<code>l</code> variants for existing and new floating-point math functions </li> +<li> <a href="numeric/math/math_errhandling" title="c/numeric/math/math errhandling">Math error handling</a> </li> +</ul> </li> +<li> <a href="numeric/complex" title="c/numeric/complex">Complex functions</a> </li> +<li> <code><a href="program/_exit" title="c/program/ Exit">_Exit()</a></code> </li> +<li> Formatting support for <code>long long</code>, <code>unsigned long long</code>, <code><a href="types/integer" title="c/types/integer">intmax_t</a></code>, and <code><a href="types/integer" title="c/types/integer">uintmax_t</a></code> <ul> +<li> <code><a href="string/byte/atoi" title="c/string/byte/atoi">atoll()</a></code> </li> +<li> <code><a href="string/byte/strtoimax" title="c/string/byte/strtoimax">strtoimax()</a></code> </li> +<li> <code><a href="string/byte/strtol" title="c/string/byte/strtol">strtoll()</a></code> </li> +<li> <code><a href="string/byte/strtoul" title="c/string/byte/strtoul">strtoull</a></code> </li> +<li> <code><a href="string/byte/strtoimax" title="c/string/byte/strtoimax">strtoumax()</a></code> </li> +<li> <code><a href="string/wide/wcstoimax" title="c/string/wide/wcstoimax">wcstoimax()</a></code> </li> +<li> <code><a href="string/wide/wcstol" title="c/string/wide/wcstol">wcstoll()</a></code> </li> +<li> <code><a href="string/wide/wcstoul" title="c/string/wide/wcstoul">wcstoull()</a></code> </li> +<li> <code><a href="string/wide/wcstoimax" title="c/string/wide/wcstoimax">wcstoumax()</a></code> </li> +</ul> </li> +<li> <code><a href="string/byte/isblank" title="c/string/byte/isblank">isblank()</a></code> and <code><a href="string/wide/iswblank" title="c/string/wide/iswblank">iswblank()</a></code> </li> +<li> <code><a href="io/fprintf" title="c/io/fprintf">snprintf()</a></code> and <code><a href="io/vfprintf" title="c/io/vfprintf">vsnprintf()</a></code> </li> +<li> <code><a href="io/vfscanf" title="c/io/vfscanf">vfscanf()</a></code> and <code><a href="io/vfwscanf" title="c/io/vfwscanf">vfwscanf()</a></code> function families </li> +<li> Extensions for <a href="io/fscanf" title="c/io/fscanf"><code>fscanf()</code></a> and <a href="io/fprintf" title="c/io/fprintf"><code>fprintf()</code></a> function families <ul> +<li> <code>ll</code> length modifier for <code>long long</code> and <code>unsigned long long</code> </li> +<li> <code>hh</code> length modifier for <code>signed char</code> and <code>unsigned char</code> </li> +<li> <code>l</code> length modifier for <code>double</code> </li> +<li> <code>z</code> length modifier for <code><a href="types/size_t" title="c/types/size t">size_t</a></code> and its signed version </li> +<li> <code>t</code> length modifier for <code><a href="types/ptrdiff_t" title="c/types/ptrdiff t">ptrdiff_t</a></code> and its unsigned version </li> +<li> <code>j</code> length modifier for <code><a href="types/integer" title="c/types/integer">intmax_t</a></code> and <code><a href="types/integer" title="c/types/integer">uintmax_t</a></code> </li> +<li> <code>a</code> conversion specifier for floating-point types </li> +</ul> </li> +<li> Numeric limit macros for <code>long long</code> and <code>unsigned long long</code> </li> +<li> Numeric limit macros corresponding to existing and new aliases for integer types </li> +<li> <a href="types/integer#Format_macro_constants" title="c/types/integer">Format string macros for integer types</a> </li> +<li> <a href="variadic/va_copy" title="c/variadic/va copy"><code>va_copy</code></a> </li> +<li> <a href="numeric/tgmath" title="c/numeric/tgmath">Type-generic math macros</a> </li> +<li> Floating-point comparison macros </li> +<li> Floating-point classification macros </li> +<li> Compatibility macros for <code>_Bool</code> (<a href="types" title="c/types"><code>bool</code></a>, <a href="types" title="c/types"><code>true</code></a>, and <a href="types" title="c/types"><code>false</code></a>) </li> +</ul> <h2 id="Defect_reports"> Defect reports</h2> <p><a href="https://en.cppreference.com/mwiki/index.php?title=Template:c/language/history/DR99&action=edit&redlink=1" class="new" title="Template:c/language/history/DR99 (page does not exist)">Template:c/language/history/DR99</a></p> +<h2 id="Compiler_support"> Compiler support</h2> <h3 id="C99_core_language_features"> C99 core language features</h3> <table class="wikitable tbody-scroll mw-collapsible t-compiler-support-top"> <tr style="height:15em"> <th>C99 feature<br><br> </th> <th>Paper(s)<br><br> </th> <th> <div>GCC</div> </th> <th> <div>Clang</div> </th> <th> <div>MSVC</div> </th> <th> <div>Apple Clang</div> </th> <th> <div>EDG eccp</div> </th> <th> <div>Intel C++</div> </th> <th> <div>IBM XL C++</div> </th> <th> <div>IBM Open XL C++ for AIX</div> </th> <th> <div>IBM Open XL C++ for z/OS</div> </th> <th> <div>Sun/Oracle C++</div> </th> <th> <div>Embarcadero C++ Builder</div> </th> <th> <div>Cray</div> </th> <th> <div><span title="ex Portland Group/PGI">Nvidia HPC C++ (ex PGI)*</span></div> </th> <th> <div>Nvidia nvcc</div> </th> <th> </th> +</tr> <tr> <td> Universal-character-names in <a href="language/identifier" title="c/language/identifier">identifiers</a> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-yes">3.1 </td> <td class="table-yes">Yes </td> <td class="table-yes">Yes </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Increased <a href="language/identifier#Translation_limits" title="c/language/identifier">translation limits</a> </td> <td> N590 </td> <td class="table-yes">0.9 </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <code>//</code> <a href="comment" title="c/comment">comments</a> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n644.htm">N644</a> </td> <td class="table-yes">2.7 </td> <td class="table-yes">Yes </td> <td class="table-yes">Yes </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <a href="language/restrict" title="c/language/restrict"><code>restrict</code></a> pointers </td> <td> N448 </td> <td class="table-yes">2.95 </td> <td class="table-yes">Yes </td> <td class="table-maybe">partial<span title="needs /std:c11 or later">*</span> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Enhanced <a href="language/arithmetic_types" title="c/language/arithmetic types">arithmetic types</a> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n815.htm">N815</a><br><a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n601.ps">N601</a><br><a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n620.ps">N620</a><br><a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n638.ps">N638</a><br><a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n657.ps">N657</a><br><a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n694.ps">N694</a><br><a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n809.ps">N809</a> </td> <td class="table-yes">Yes </td> <td class="table-maybe">partial </td> <td class="table-maybe">Maybe </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Flexible array members </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-yes">3.0 </td> <td class="table-yes">Yes </td> <td class="table-yes">Yes </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <a href="language/array#Variable-length_arrays" title="c/language/array">Variable-length array</a> (VLA) types </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n683.htm">N683</a> </td> <td class="table-yes">0.9 </td> <td class="table-yes">Yes </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Variably-modified (VM) types </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2778.pdf">N2778</a> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-yes">Yes </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Designated initializers </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n494.pdf">N494</a> </td> <td class="table-yes">3.0 </td> <td class="table-yes">Yes </td> <td class="table-yes">Yes </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Non-constant initializers </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-yes">1.21 </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Idempotent cvr-qualifiers </td> <td> N505 </td> <td class="table-yes">3.0 </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Trailing comma in <a href="language/enum" title="c/language/enum"><span class="t-spar">enumerator-list</span></a> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-yes">0.9 </td> <td class="table-yes">Yes </td> <td class="table-yes">Yes </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Hexadecimal <a href="language/floating_constant" title="c/language/floating constant">floating constants</a> </td> <td> N308 </td> <td class="table-yes">2.8 </td> <td class="table-yes">Yes </td> <td class="table-yes">Yes </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <a href="language/compound_literal" title="c/language/compound literal">Compound literals</a> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n716.htm">N716</a> </td> <td class="table-yes">3.1 </td> <td class="table-yes">Yes </td> <td class="table-yes">Yes </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Floating-point environment </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-maybe">partial </td> <td class="table-maybe">partial </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Requiring truncation for divisions of signed integer types </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n617.htm">N617</a> </td> <td class="table-yes">0.9 </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Implicit <code>return 0;</code> in the <a href="language/main_function" title="c/language/main function"><code>main()</code> function</a> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-yes">Yes </td> <td class="table-yes">Yes </td> <td class="table-yes">Yes </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Declarations and statements in mixed order </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n740.htm">N740</a> </td> <td class="table-yes">3.0 </td> <td class="table-yes">Yes </td> <td class="table-yes">Yes </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <span class="t-spar">init-statement</span> in <a href="language/for" title="c/language/for"><code>for</code></a> loops </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-yes">Yes </td> <td class="table-yes">Yes </td> <td class="table-yes">Yes </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <a href="language/inline" title="c/language/inline"><code>inline</code></a> functions </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n741.htm">N741</a> </td> <td class="table-yes">4.3 </td> <td class="table-yes">Yes </td> <td class="table-yes">Yes </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Predefined variable <a href="language/function_definition" title="c/language/function definition"><code>__func__</code></a> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n611.ps">N611</a> </td> <td class="table-yes">2.95 </td> <td class="table-yes">Yes </td> <td class="table-yes">Yes </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Cvr-qualifiers and <code>static</code> in <code>[]</code> within function declarations </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-yes">3.1 </td> <td class="table-yes">Yes </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <a href="preprocessor/replace" title="c/preprocessor/replace">Variadic macros</a> </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n707.htm">N707</a> </td> <td class="table-yes">2.95 </td> <td class="table-yes">Yes </td> <td class="table-yes">Yes </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> <a href="preprocessor/impl" title="c/preprocessor/impl"><code>_Pragma</code></a> preprocessor operator </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n634.ps">N634</a> </td> <td class="table-yes">3.0 </td> <td class="table-yes">Yes </td> <td class="table-maybe">partial<span title="needs /std:c11 or later">*</span> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr> <td> Standard pragmas for floating-point evaluation </td> <td> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n631.htm">N631</a><br><a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n696.ps">N696</a> </td> <td class="table-no"> No </td> <td class="table-no"> No </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-yes">Yes </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> <td class="table-no"> </td> +</tr> <tr style="height:15em"> <th> <br><br>C99 feature </th> <th> <br><br>Paper(s) </th> <th> <div>GCC</div> </th> <th> <div>Clang</div> </th> <th> <div>MSVC</div> </th> <th> <div>Apple Clang</div> </th> <th> <div>EDG eccp</div> </th> <th> <div>Intel C++</div> </th> <th> <div>IBM XL C++</div> </th> <th> <div>IBM Open XL C++ for AIX</div> </th> <th> <div>IBM Open XL C++ for z/OS</div> </th> <th> <div>Sun/Oracle C++</div> </th> <th> <div>Embarcadero C++ Builder</div> </th> <th> <div>Cray</div> </th> <th> <div><span title="ex Portland Group/PGI">Nvidia HPC C++ (ex PGI)*</span></div> </th> <th> <div>Nvidia nvcc</div> </th> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/99" class="_attribution-link">https://en.cppreference.com/w/c/99</a> + </p> +</div> diff --git a/devdocs/c/algorithm%2Fbsearch.html b/devdocs/c/algorithm%2Fbsearch.html new file mode 100644 index 00000000..295e3093 --- /dev/null +++ b/devdocs/c/algorithm%2Fbsearch.html @@ -0,0 +1,104 @@ + <h1 id="firstHeading" class="firstHeading">bsearch, bsearch_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">void* bsearch( const void *key, const void *ptr, size_t count, size_t size, + int (*comp)(const void*, const void*) );</pre> +</td> <td> (1) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">void* bsearch_s( const void *key, const void *ptr, rsize_t count, rsize_t size, + int (*comp)(const void *, const void *, void *), + void *context );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">/*QVoid*/* bsearch( const void *key, /*QVoid*/ *ptr, size_t count, size_t size, + int (*comp)(const void*, const void*) );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">/*QVoid*/* bsearch_s( const void *key, /*QVoid*/ *ptr, rsize_t count, rsize_t size, + int (*comp)(const void *, const void *, void *), + void *context );</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Finds an element equal to element pointed to by <code>key</code> in an array pointed to by <code>ptr</code>. The array contains <code>count</code> elements of <code>size</code> bytes and must be partitioned with respect to <code>key</code>, that is, all the elements that compare less than must appear before all the elements that compare equal to, and those must appear before all the elements that compare greater than the key object. A fully sorted array satisfies these requirements. The elements are compared using function pointed to by <code>comp</code>. The behavior is undefined if the array is not already partitioned with respect to <code>*key</code> in ascending order according to the same criterion that <code>comp</code> uses.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that the additional state argument <code>context</code> is passed to <code>comp</code> and that the following errors are detected at runtime and call the currently installed <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> <code>count</code> or <code>size</code> is greater than <code>RSIZE_MAX</code> </li> +<li> <code>key</code>, <code>ptr</code> or <code>comp</code> is a null pointer (unless <code>count</code> is zero) </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>bsearch_s</code> <span class="t-rev-inl t-since-c23"><span> (and the corresponding type-generic macro)</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> is only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../program" title="c/program"><code><stdlib.h></code></a>.</dd> +</dl> +</div> <div class="t-li1"> +<span class="t-li">3,4)</span> Type-generic macros equivalent to <span class="t-v">(1)</span> and <span class="t-v">(2)</span> respectively. Let <code>T</code> be a unqualified object type (including <code>void</code>). <ul> +<li> If <code>ptr</code> is of type <code>const T*</code>, the return type is <code>const void*</code>. </li> +<li> Otherwise, if <code>ptr</code> is of type <code>T*</code>, the return type is <code>void*</code>. </li> +<li> Otherwise, the behavior is undefined. </li> +</ul> If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if <code>(bsearch)</code>, <code>(bsearch_s)</code>, or a function pointer is used), the actual function declaration <span class="t-v">(1)</span> or <span class="t-v">(2)</span> becomes visible.</div> <p>If the array contains several elements that <code>comp</code> would indicate as equal to the element searched for, then it is unspecified which element the function will return as the result.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>Direct usages of actual functions <span class="t-v">(1)</span> and <span class="t-v">(2)</span> are deprecated.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> key </td> <td> - </td> <td> pointer to the element to search for </td> +</tr> <tr class="t-par"> <td> ptr </td> <td> - </td> <td> pointer to the array to examine </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> number of element in the array </td> +</tr> <tr class="t-par"> <td> size </td> <td> - </td> <td> size of each element in the array in bytes </td> +</tr> <tr class="t-par"> <td> comp </td> <td> - </td> <td> comparison function which returns a negative integer value if the first argument is <i>less</i> than the second, a positive integer value if the first argument is <i>greater</i> than the second and zero if the arguments are equivalent. <code>key</code> is passed as the first argument, an element from the array as the second.<br> <p>The signature of the comparison function should be equivalent to the following:</p> +<p><span class="t-cc"> <span class="kw4">int</span> cmp<span class="br0">(</span><span class="kw4">const</span> <span class="kw4">void</span> <span class="sy2">*</span>a, <span class="kw4">const</span> <span class="kw4">void</span> <span class="sy2">*</span>b<span class="br0">)</span><span class="sy4">;</span></span></p> +<p>The function must not modify the objects passed to it and must return consistent results when called for the same objects, regardless of their positions in the array.</p> +<p></p> +</td> +</tr> <tr class="t-par"> <td> context </td> <td> - </td> <td> state of the comparator (e.g., collating sequence), passed to <code>comp</code> as the third argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> Pointer to an element in the array that compares equal to <code>*key</code>, or null pointer if such element has not been found.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that the null pointer is also returned on runtime constraints violations.</div> <div class="t-li1"> +<span class="t-li">3,4)</span> Same as <span class="t-v">(1)</span> and <span class="t-v">(2)</span> respectively, except that cv-qualification is adjusted.</div> <h3 id="Notes"> Notes</h3> <p>Despite the name, neither C nor POSIX standards require this function to be implemented using binary search or make any complexity guarantees.</p> +<p>Unlike other bounds-checked functions, <code>bsearch_s</code> does not treat arrays of zero size as a runtime constraint violation and instead indicates element not found (the other function that accepts arrays of zero size is <code>qsort_s</code>).</p> +<p>Until <code>bsearch_s</code>, users of <code>bsearch</code> often used global variables to represent the state of the comparator.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdlib.h> +#include <stdio.h> + +struct data { + int nr; + char const *value; +} dat[] = { + {1, "Foo"}, {2, "Bar"}, {3, "Hello"}, {4, "World"} +}; + +int data_cmp(void const *lhs, void const *rhs) +{ + struct data const *const l = lhs; + struct data const *const r = rhs; + + if (l->nr < r->nr) return -1; + else if (l->nr > r->nr) return 1; + else return 0; + + // return (l->nr > r->nr) - (l->nr < r->nr); // possible shortcut + // return l->nr - r->nr; // erroneous shortcut (fails if INT_MIN is present) +} + +int main(void) +{ + struct data key = { .nr = 3 }; + struct data const *res = bsearch(&key, dat, sizeof dat / sizeof dat[0], + sizeof dat[0], data_cmp); + if (res) { + printf("No %d: %s\n", res->nr, res->value); + } else { + printf("No %d not found\n", key.nr); + } +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">No 3: Hello</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.22.5.1 The bsearch function (p: 258) </li> +<li> K.3.6.3.1 The bsearch_s function (p: 441-442) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.22.5.1 The bsearch function (p: 355) </li> +<li> K.3.6.3.1 The bsearch_s function (p: 608-609) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.5.1 The bsearch function (p: 318-319) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.5.1 The bsearch function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="qsort" title="c/algorithm/qsort"> <span class="t-lines"><span>qsort</span><span>qsort_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> sorts a range of elements with unspecified type <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/algorithm/bsearch" title="cpp/algorithm/bsearch">C++ documentation</a></span> for <code>bsearch</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/algorithm/bsearch" class="_attribution-link">https://en.cppreference.com/w/c/algorithm/bsearch</a> + </p> +</div> diff --git a/devdocs/c/algorithm%2Fqsort.html b/devdocs/c/algorithm%2Fqsort.html new file mode 100644 index 00000000..f1006ea4 --- /dev/null +++ b/devdocs/c/algorithm%2Fqsort.html @@ -0,0 +1,85 @@ + <h1 id="firstHeading" class="firstHeading">qsort, qsort_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">void qsort( void *ptr, size_t count, size_t size, + int (*comp)(const void *, const void *) );</pre> +</td> <td> (1) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t qsort_s( void *ptr, rsize_t count, rsize_t size, + int (*comp)(const void *, const void *, void *), + void *context );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Sorts the given array pointed to by <code>ptr</code> in ascending order. The array contains <code>count</code> elements of <code>size</code> bytes. Function pointed to by <code>comp</code> is used for object comparison. </div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that the additional context parameter <code>context</code> is passed to <code>comp</code> and that the following errors are detected at runtime and call the currently installed <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> <code>count</code> or <code>size</code> is greater than <code>RSIZE_MAX</code> </li> +<li> <code>ptr</code> or <code>comp</code> is a null pointer (unless <code>count</code> is zero) </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>qsort_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../program" title="c/program"><code><stdlib.h></code></a>.</dd> +</dl> +</div> <p>If <code>comp</code> indicates two elements as equivalent, their order in the resulting sorted array is unspecified.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ptr </td> <td> - </td> <td> pointer to the array to sort </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> number of elements in the array </td> +</tr> <tr class="t-par"> <td> size </td> <td> - </td> <td> size of each element in the array in bytes </td> +</tr> <tr class="t-par"> <td> comp </td> <td> - </td> <td> comparison function which returns a negative integer value if the first argument is <i>less</i> than the second, a positive integer value if the first argument is <i>greater</i> than the second and zero if the arguments are equivalent.<br> <p>The signature of the comparison function should be equivalent to the following:</p> +<p><span class="t-cc"> <span class="kw4">int</span> cmp<span class="br0">(</span><span class="kw4">const</span> <span class="kw4">void</span> <span class="sy2">*</span>a, <span class="kw4">const</span> <span class="kw4">void</span> <span class="sy2">*</span>b<span class="br0">)</span><span class="sy4">;</span></span></p> +<p>The function must not modify the objects passed to it and must return consistent results when called for the same objects, regardless of their positions in the array.</p> +<p></p> +</td> +</tr> <tr class="t-par"> <td> context </td> <td> - </td> <td> additional information (e.g., collating sequence), passed to <code>comp</code> as the third argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> (none)</div> <div class="t-li1"> +<span class="t-li">2)</span> zero on success, non-zero if a runtime constraints violation was detected</div> <h3 id="Notes"> Notes</h3> <p>Despite the name, neither C nor POSIX standards require this function to be implemented using <a href="https://en.wikipedia.org/wiki/Quicksort" class="extiw" title="enwiki:Quicksort">quicksort</a> or make any complexity or stability guarantees.</p> +<p>Unlike other bounds-checked functions, <code>qsort_s</code> does not treat arrays of zero size as a runtime constraint violation and instead returns successfully without altering the array (the other function that accepts arrays of zero size is <code>bsearch_s</code>).</p> +<p>Until <code>qsort_s</code>, users of <code>qsort</code> often used global variables to pass additional context to the comparison function.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> +#include <limits.h> + +int compare_ints(const void* a, const void* b) +{ + int arg1 = *(const int*)a; + int arg2 = *(const int*)b; + + if (arg1 < arg2) return -1; + if (arg1 > arg2) return 1; + return 0; + + // return (arg1 > arg2) - (arg1 < arg2); // possible shortcut + // return arg1 - arg2; // erroneous shortcut (fails if INT_MIN is present) +} + +int main(void) +{ + int ints[] = { -2, 99, 0, -743, 2, INT_MIN, 4 }; + int size = sizeof ints / sizeof *ints; + + qsort(ints, size, sizeof(int), compare_ints); + + for (int i = 0; i < size; i++) { + printf("%d ", ints[i]); + } + + printf("\n"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">-2147483648 -743 -2 0 2 4 99</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.22.5.2 The qsort function (p: 258-259) </li> +<li> K.3.6.3.2 The qsort_s function (p: 442-443) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.22.5.2 The qsort function (p: 355-356) </li> +<li> K.3.6.3.2 The qsort_s function (p: 609) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.5.2 The qsort function (p: 319) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.5.2 The qsort function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="bsearch" title="c/algorithm/bsearch"> <span class="t-lines"><span>bsearch</span><span>bsearch_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> searches an array for an element of unspecified type <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/algorithm/qsort" title="cpp/algorithm/qsort">C++ documentation</a></span> for <code>qsort</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/algorithm/qsort" class="_attribution-link">https://en.cppreference.com/w/c/algorithm/qsort</a> + </p> +</div> diff --git a/devdocs/c/algorithm.html b/devdocs/c/algorithm.html new file mode 100644 index 00000000..103b3fd5 --- /dev/null +++ b/devdocs/c/algorithm.html @@ -0,0 +1,22 @@ + <h1 id="firstHeading" class="firstHeading">Algorithms</h1> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdlib.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="algorithm/qsort" title="c/algorithm/qsort"> <span class="t-lines"><span>qsort</span><span>qsort_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> sorts a range of elements with unspecified type <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="algorithm/bsearch" title="c/algorithm/bsearch"> <span class="t-lines"><span>bsearch</span><span>bsearch_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> searches an array for an element of unspecified type <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.22.5 Searching and sorting utilities (p: 354-356) </li> +<li> K.3.6.3 Searching and sorting utilities (p: 607-609) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.5 Searching and sorting utilities (p: 318-319) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.5 Searching and sorting utilities </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/algorithm" title="cpp/algorithm">C++ documentation</a></span> for <span class=""><span>Algorithms library</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/algorithm" class="_attribution-link">https://en.cppreference.com/w/c/algorithm</a> + </p> +</div> diff --git a/devdocs/c/atomic%2Fatomic_compare_exchange.html b/devdocs/c/atomic%2Fatomic_compare_exchange.html new file mode 100644 index 00000000..5075a508 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_compare_exchange.html @@ -0,0 +1,45 @@ + <h1 id="firstHeading" class="firstHeading">atomic_compare_exchange_weak, atomic_compare_exchange_strong, atomic_compare_exchange_weak_explicit, atomic_compare_exchange_strong_explicit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdatomic.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">_Bool atomic_compare_exchange_strong( volatile A* obj, + C* expected, C desired );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">_Bool atomic_compare_exchange_weak( volatile A *obj, + C* expected, C desired );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">_Bool atomic_compare_exchange_strong_explicit( volatile A* obj, + C* expected, C desired, + memory_order succ, + memory_order fail );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">_Bool atomic_compare_exchange_weak_explicit( volatile A *obj, + C* expected, C desired, + memory_order succ, + memory_order fail );</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Atomically compares the contents of memory pointed to by <code>obj</code> with the contents of memory pointed to by <code>expected</code>, and if those are bitwise equal, replaces the former with <code>desired</code> (performs read-modify-write operation). Otherwise, loads the actual contents of memory pointed to by <code>obj</code> into <code>*expected</code> (performs load operation).</p> +<p>The memory models for the read-modify-write and load operations are <code>succ</code> and <code>fail</code> respectively. The (1-2) versions use <code><a href="memory_order" title="c/atomic/memory order">memory_order_seq_cst</a></code> by default.</p> +<p>The weak forms ((2) and (4)) of the functions are allowed to fail spuriously, that is, act as if <code>*obj != *expected</code> even if they are equal. When a compare-and-exchange is in a loop, the weak version will yield better performance on some platforms. When a weak compare-and-exchange would require a loop and a strong one would not, the strong one is preferable.</p> +<p>This is a <a href="../language/generic" title="c/language/generic">generic function</a> defined for all <a href="../language/atomic" title="c/language/atomic">atomic object types</a> <code>A</code>. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and <a href="../language/volatile" title="c/language/volatile">volatile</a> (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects. <code>C</code> is the non-atomic type corresponding to <code>A</code>.</p> +<p>It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like <code>(atomic_compare_exchange)(...)</code>), or a program defines an external identifier with the name of a generic function, the behavior is undefined.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> obj </td> <td> - </td> <td> pointer to the atomic object to test and modify </td> +</tr> <tr class="t-par"> <td> expected </td> <td> - </td> <td> pointer to the value expected to be found in the atomic object </td> +</tr> <tr class="t-par"> <td> desired </td> <td> - </td> <td> the value to store in the atomic object if it is as expected </td> +</tr> <tr class="t-par"> <td> succ </td> <td> - </td> <td> the memory synchronization ordering for the read-modify-write operation if the comparison succeeds. All values are permitted. </td> +</tr> <tr class="t-par"> <td> fail </td> <td> - </td> <td> the memory synchronization ordering for the load operation if the comparison fails. Cannot be <code><a href="memory_order" title="c/atomic/memory order">memory_order_release</a></code> or <code><a href="memory_order" title="c/atomic/memory order">memory_order_acq_rel</a></code> and cannot specify stronger ordering than <code>succ</code> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The result of the comparison: <code>true</code> if <code>*obj</code> was equal to <code>*exp</code>, <code>false</code> otherwise.</p> +<h3 id="Notes"> Notes</h3> <p>The behavior of <code>atomic_compare_exchange_*</code> family is as if the following was executed atomically:</p> +<div class="c source-c"><pre data-language="c">if (memcmp(obj, expected, sizeof *obj) == 0) { + memcpy(obj, &desired, sizeof *obj); + return true; +} else { + memcpy(expected, obj, sizeof *obj); + return false; +}</pre></div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.17.7.4 The atomic_compare_exchange generic functions (p: 207) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.17.7.4 The atomic_compare_exchange generic functions (p: 283-284) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="atomic_exchange" title="c/atomic/atomic exchange"> <span class="t-lines"><span>atomic_exchange</span><span>atomic_exchange_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> swaps a value with the value of an atomic object <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic/atomic_compare_exchange" title="cpp/atomic/atomic compare exchange">C++ documentation</a></span> for <code>atomic_compare_exchange_weak, atomic_compare_exchange_strong, atomic_compare_exchange_weak_explicit, atomic_compare_exchange_strong_explicit</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic/atomic_compare_exchange" class="_attribution-link">https://en.cppreference.com/w/c/atomic/atomic_compare_exchange</a> + </p> +</div> diff --git a/devdocs/c/atomic%2Fatomic_exchange.html b/devdocs/c/atomic%2Fatomic_exchange.html new file mode 100644 index 00000000..d508573b --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_exchange.html @@ -0,0 +1,24 @@ + <h1 id="firstHeading" class="firstHeading">atomic_exchange, atomic_exchange_explicit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdatomic.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">C atomic_exchange( volatile A* obj, C desired );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">C atomic_exchange_explicit( volatile A* obj, C desired, memory_order order );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Atomically replaces the value pointed by <code>obj</code> with <code>desired</code> and returns the value <code>obj</code> held previously. The operation is read-modify-write operation. The first version orders memory accesses according to <code><a href="memory_order" title="c/atomic/memory order">memory_order_seq_cst</a></code>, the second version orders memory accesses according to <code>order</code>.</p> +<p>This is a <a href="../language/generic" title="c/language/generic">generic function</a> defined for all <a href="../language/atomic" title="c/language/atomic">atomic object types</a> <code>A</code>. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and <a href="../language/volatile" title="c/language/volatile">volatile</a> (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects. <code>C</code> is the non-atomic type corresponding to <code>A</code>.</p> +<p>It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like <code>(atomic_exchange)(...)</code>), or a program defines an external identifier with the name of a generic function, the behavior is undefined..</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> obj </td> <td> - </td> <td> pointer to the atomic object to modify </td> +</tr> <tr class="t-par"> <td> desired </td> <td> - </td> <td> the value to replace the atomic object with </td> +</tr> <tr class="t-par"> <td> order </td> <td> - </td> <td> the memory synchronization ordering for this operation: all values are permitted </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The value held previously be the atomic object pointed to by <code>obj</code>.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.17.7.3 The atomic_exchange generic functions (p: 207) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.17.7.3 The atomic_exchange generic functions (p: 283) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="atomic_compare_exchange" title="c/atomic/atomic compare exchange"> <span class="t-lines"><span>atomic_compare_exchange_strong</span><span>atomic_compare_exchange_strong_explicit</span><span>atomic_compare_exchange_weak</span><span>atomic_compare_exchange_weak_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> swaps a value with an atomic object if the old value is what is expected, otherwise reads the old value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic/atomic_exchange" title="cpp/atomic/atomic exchange">C++ documentation</a></span> for <code>atomic_exchange, atomic_exchange_explicit</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic/atomic_exchange" class="_attribution-link">https://en.cppreference.com/w/c/atomic/atomic_exchange</a> + </p> +</div> diff --git a/devdocs/c/atomic%2Fatomic_fetch_add.html b/devdocs/c/atomic%2Fatomic_fetch_add.html new file mode 100644 index 00000000..8bfa2a40 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_fetch_add.html @@ -0,0 +1,53 @@ + <h1 id="firstHeading" class="firstHeading">atomic_fetch_add, atomic_fetch_add_explicit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdatomic.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">C atomic_fetch_add( volatile A* obj, M arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">C atomic_fetch_add_explicit( volatile A* obj, M arg, memory_order order );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Atomically replaces the value pointed by <code>obj</code> with the result of addition of <code>arg</code> to the old value of <code>obj</code>, and returns the value <code>obj</code> held previously. The operation is read-modify-write operation. The first version orders memory accesses according to <code><a href="memory_order" title="c/atomic/memory order">memory_order_seq_cst</a></code>, the second version orders memory accesses according to <code>order</code>.</p> +<p>This is a <a href="../language/generic" title="c/language/generic">generic function</a> defined for all <a href="../language/atomic" title="c/language/atomic">atomic object types</a> <code>A</code>. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and <a href="../language/volatile" title="c/language/volatile">volatile</a> (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects. <code>M</code> is either the non-atomic type corresponding to <code>A</code> if <code>A</code> is atomic integer type, or <code><a href="../types/ptrdiff_t" title="c/types/ptrdiff t">ptrdiff_t</a></code> if <code>A</code> is atomic pointer type.</p> +<p>It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like <code>(atomic_fetch_add)(...)</code>), or a program defines an external identifier with the name of a generic function, the behavior is undefined.</p> +<p>For signed integer types, arithmetic is defined to use two’s complement representation. There are no undefined results. For pointer types, the result may be an undefined address, but the operations otherwise have no undefined behavior.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> obj </td> <td> - </td> <td> pointer to the atomic object to modify </td> +</tr> <tr class="t-par"> <td> arg </td> <td> - </td> <td> the value to add to the value stored in the atomic object </td> +</tr> <tr class="t-par"> <td> order </td> <td> - </td> <td> the memory synchronization ordering for this operation: all values are permitted </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The value held previously by the atomic object pointed to by <code>obj</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <threads.h> +#include <stdatomic.h> + +atomic_int acnt; +int cnt; + +int f(void* thr_data) +{ + for(int n = 0; n < 1000; ++n) { + atomic_fetch_add_explicit(&acnt, 1, memory_order_relaxed); // atomic + ++cnt; // undefined behavior, in practice some updates missed + } + return 0; +} + +int main(void) +{ + thrd_t thr[10]; + for(int n = 0; n < 10; ++n) + thrd_create(&thr[n], f, NULL); + for(int n = 0; n < 10; ++n) + thrd_join(thr[n], NULL); + + printf("The atomic counter is %u\n", acnt); + printf("The non-atomic counter is %u\n", cnt); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">The atomic counter is 10000 +The non-atomic counter is 9511</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.17.7.5 The atomic_fetch and modify generic functions (p: 208) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.17.7.5 The atomic_fetch and modify generic functions (p: 284-285) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="atomic_fetch_sub" title="c/atomic/atomic fetch sub"> <span class="t-lines"><span>atomic_fetch_sub</span><span>atomic_fetch_sub_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> atomic subtraction <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic/atomic_fetch_add" title="cpp/atomic/atomic fetch add">C++ documentation</a></span> for <code>atomic_fetch_add, atomic_fetch_add_explicit</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic/atomic_fetch_add" class="_attribution-link">https://en.cppreference.com/w/c/atomic/atomic_fetch_add</a> + </p> +</div> diff --git a/devdocs/c/atomic%2Fatomic_fetch_and.html b/devdocs/c/atomic%2Fatomic_fetch_and.html new file mode 100644 index 00000000..3c5f0033 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_fetch_and.html @@ -0,0 +1,26 @@ + <h1 id="firstHeading" class="firstHeading">atomic_fetch_and, atomic_fetch_and_explicit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdatomic.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">C atomic_fetch_and( volatile A* obj, M arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">C atomic_fetch_and_explicit( volatile A* obj, M arg, memory_order order );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Atomically replaces the value pointed by <code>obj</code> with the result of bitwise AND between the old value of <code>obj</code> and <code>arg</code>, and returns the value <code>obj</code> held previously. The operation is read-modify-write operation. The first version orders memory accesses according to <code><a href="memory_order" title="c/atomic/memory order">memory_order_seq_cst</a></code>, the second version orders memory accesses according to <code>order</code>.</p> +<p>This is a <a href="../language/generic" title="c/language/generic">generic function</a> defined for all <a href="../language/atomic" title="c/language/atomic">atomic object types</a> <code>A</code>. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and <a href="../language/volatile" title="c/language/volatile">volatile</a> (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects. <code>M</code> is either the non-atomic type corresponding to <code>A</code> if <code>A</code> is atomic integer type, or <code><a href="../types/ptrdiff_t" title="c/types/ptrdiff t">ptrdiff_t</a></code> if <code>A</code> is atomic pointer type.</p> +<p>It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like <code>(atomic_fetch_and)(...)</code>), or a program defines an external identifier with the name of a generic function, the behavior is undefined.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> obj </td> <td> - </td> <td> pointer to the atomic object to modify </td> +</tr> <tr class="t-par"> <td> arg </td> <td> - </td> <td> the value to bitwise AND to the value stored in the atomic object </td> +</tr> <tr class="t-par"> <td> order </td> <td> - </td> <td> the memory synchronization ordering for this operation: all values are permitted </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The value held previously be the atomic object pointed to by <code>obj</code>.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.17.7.5 The atomic_fetch and modify generic functions (p: 208) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.17.7.5 The atomic_fetch and modify generic functions (p: 284-285) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="atomic_fetch_or" title="c/atomic/atomic fetch or"> <span class="t-lines"><span>atomic_fetch_or</span><span>atomic_fetch_or_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> atomic bitwise OR <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic_fetch_xor" title="c/atomic/atomic fetch xor"> <span class="t-lines"><span>atomic_fetch_xor</span><span>atomic_fetch_xor_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> atomic bitwise exclusive OR <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic/atomic_fetch_and" title="cpp/atomic/atomic fetch and">C++ documentation</a></span> for <code>atomic_fetch_and, atomic_fetch_and_explicit</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic/atomic_fetch_and" class="_attribution-link">https://en.cppreference.com/w/c/atomic/atomic_fetch_and</a> + </p> +</div> diff --git a/devdocs/c/atomic%2Fatomic_fetch_or.html b/devdocs/c/atomic%2Fatomic_fetch_or.html new file mode 100644 index 00000000..5479688c --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_fetch_or.html @@ -0,0 +1,26 @@ + <h1 id="firstHeading" class="firstHeading">atomic_fetch_or, atomic_fetch_or_explicit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdatomic.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">C atomic_fetch_or( volatile A* obj, M arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">C atomic_fetch_or_explicit( volatile A* obj, M arg, memory_order order );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Atomically replaces the value pointed by <code>obj</code> with the result of bitwise OR between the old value of <code>obj</code> and <code>arg</code>, and returns the value <code>obj</code> held previously. The operation is read-modify-write operation. The first version orders memory accesses according to <code><a href="memory_order" title="c/atomic/memory order">memory_order_seq_cst</a></code>, the second version orders memory accesses according to <code>order</code>.</p> +<p>This is a <a href="../language/generic" title="c/language/generic">generic function</a> defined for all <a href="../language/atomic" title="c/language/atomic">atomic object types</a> <code>A</code>. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and <a href="../language/volatile" title="c/language/volatile">volatile</a> (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects. <code>M</code> is either the non-atomic type corresponding to <code>A</code> if <code>A</code> is atomic integer type, or <code><a href="../types/ptrdiff_t" title="c/types/ptrdiff t">ptrdiff_t</a></code> if <code>A</code> is atomic pointer type.</p> +<p>It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like <code>(atomic_fetch_or)(...)</code>), or a program defines an external identifier with the name of a generic function, the behavior is undefined.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> obj </td> <td> - </td> <td> pointer to the atomic object to modify </td> +</tr> <tr class="t-par"> <td> arg </td> <td> - </td> <td> the value to bitwise OR to the value stored in the atomic object </td> +</tr> <tr class="t-par"> <td> order </td> <td> - </td> <td> the memory synchronization ordering for this operation: all values are permitted </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The value held previously be the atomic object pointed to by <code>obj</code>.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.17.7.5 The atomic_fetch and modify generic functions (p: 208) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.17.7.5 The atomic_fetch and modify generic functions (p: 284-285) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="atomic_fetch_and" title="c/atomic/atomic fetch and"> <span class="t-lines"><span>atomic_fetch_and</span><span>atomic_fetch_and_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> atomic bitwise AND <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic_fetch_xor" title="c/atomic/atomic fetch xor"> <span class="t-lines"><span>atomic_fetch_xor</span><span>atomic_fetch_xor_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> atomic bitwise exclusive OR <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic/atomic_fetch_or" title="cpp/atomic/atomic fetch or">C++ documentation</a></span> for <code>atomic_fetch_or, atomic_fetch_or_explicit</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic/atomic_fetch_or" class="_attribution-link">https://en.cppreference.com/w/c/atomic/atomic_fetch_or</a> + </p> +</div> diff --git a/devdocs/c/atomic%2Fatomic_fetch_sub.html b/devdocs/c/atomic%2Fatomic_fetch_sub.html new file mode 100644 index 00000000..2ce31ca1 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_fetch_sub.html @@ -0,0 +1,25 @@ + <h1 id="firstHeading" class="firstHeading">atomic_fetch_sub, atomic_fetch_sub_explicit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdatomic.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">C atomic_fetch_sub( volatile A* obj, M arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">C atomic_fetch_sub_explicit( volatile A* obj, M arg, memory_order order );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Atomically replaces the value pointed by <code>obj</code> with the result of subtraction of <code>arg</code> from the old value of <code>obj</code>, and returns the value <code>obj</code> held previously. The operation is read-modify-write operation. The first version orders memory accesses according to <code><a href="memory_order" title="c/atomic/memory order">memory_order_seq_cst</a></code>, the second version orders memory accesses according to <code>order</code>.</p> +<p>This is a <a href="../language/generic" title="c/language/generic">generic function</a> defined for all <a href="../language/atomic" title="c/language/atomic">atomic object types</a> <code>A</code>. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and <a href="../language/volatile" title="c/language/volatile">volatile</a> (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects. <code>M</code> is either the non-atomic type corresponding to <code>A</code> if <code>A</code> is atomic integer type, or <code><a href="../types/ptrdiff_t" title="c/types/ptrdiff t">ptrdiff_t</a></code> if <code>A</code> is atomic pointer type.</p> +<p>It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like <code>(atomic_fetch_sub)(...)</code>), or a program defines an external identifier with the name of a generic function, the behavior is undefined.</p> +<p>For signed integer types, arithmetic is defined to use two’s complement representation. There are no undefined results. For pointer types, the result may be an undefined address, but the operations otherwise have no undefined behavior.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> obj </td> <td> - </td> <td> pointer to the atomic object to modify </td> +</tr> <tr class="t-par"> <td> arg </td> <td> - </td> <td> the value to subtract from the value stored in the atomic object </td> +</tr> <tr class="t-par"> <td> order </td> <td> - </td> <td> the memory synchronization ordering for this operation: all values are permitted </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The value held previously by the atomic object pointed to by <code>obj</code>.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.17.7.5 The atomic_fetch and modify generic functions (p: 208) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.17.7.5 The atomic_fetch and modify generic functions (p: 284-285) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="atomic_fetch_add" title="c/atomic/atomic fetch add"> <span class="t-lines"><span>atomic_fetch_add</span><span>atomic_fetch_add_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> atomic addition <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic/atomic_fetch_sub" title="cpp/atomic/atomic fetch sub">C++ documentation</a></span> for <code>atomic_fetch_sub, atomic_fetch_sub_explicit</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic/atomic_fetch_sub" class="_attribution-link">https://en.cppreference.com/w/c/atomic/atomic_fetch_sub</a> + </p> +</div> diff --git a/devdocs/c/atomic%2Fatomic_fetch_xor.html b/devdocs/c/atomic%2Fatomic_fetch_xor.html new file mode 100644 index 00000000..34db6b5b --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_fetch_xor.html @@ -0,0 +1,26 @@ + <h1 id="firstHeading" class="firstHeading">atomic_fetch_xor, atomic_fetch_xor_explicit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdatomic.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">C atomic_fetch_xor( volatile A* obj, M arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">C atomic_fetch_xor_explicit( volatile A* obj, M arg, memory_order order );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Atomically replaces the value pointed by <code>obj</code> with the result of bitwise XOR between the old value of <code>obj</code> and <code>arg</code>, and returns the value <code>obj</code> held previously. The operation is read-modify-write operation. The first version orders memory accesses according to <code><a href="memory_order" title="c/atomic/memory order">memory_order_seq_cst</a></code>, the second version orders memory accesses according to <code>order</code>.</p> +<p>This is a <a href="../language/generic" title="c/language/generic">generic function</a> defined for all <a href="../language/atomic" title="c/language/atomic">atomic object types</a> <code>A</code>. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and <a href="../language/volatile" title="c/language/volatile">volatile</a> (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects. <code>M</code> is either the non-atomic type corresponding to <code>A</code> if <code>A</code> is atomic integer type, or <code><a href="../types/ptrdiff_t" title="c/types/ptrdiff t">ptrdiff_t</a></code> if <code>A</code> is atomic pointer type.</p> +<p>It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like <code>(atomic_fetch_xor)(...)</code>), or a program defines an external identifier with the name of a generic function, the behavior is undefined.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> obj </td> <td> - </td> <td> pointer to the atomic object to modify </td> +</tr> <tr class="t-par"> <td> arg </td> <td> - </td> <td> the value to bitwise XOR to the value stored in the atomic object </td> +</tr> <tr class="t-par"> <td> order </td> <td> - </td> <td> the memory synchronization ordering for this operation: all values are permitted </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The value held previously be the atomic object pointed to by <code>obj</code>.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.17.7.5 The atomic_fetch and modify generic functions (p: 208) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.17.7.5 The atomic_fetch and modify generic functions (p: 284-285) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="atomic_fetch_or" title="c/atomic/atomic fetch or"> <span class="t-lines"><span>atomic_fetch_or</span><span>atomic_fetch_or_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> atomic bitwise OR <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic_fetch_and" title="c/atomic/atomic fetch and"> <span class="t-lines"><span>atomic_fetch_and</span><span>atomic_fetch_and_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> atomic bitwise AND <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic/atomic_fetch_xor" title="cpp/atomic/atomic fetch xor">C++ documentation</a></span> for <code>atomic_fetch_xor, atomic_fetch_xor_explicit</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic/atomic_fetch_xor" class="_attribution-link">https://en.cppreference.com/w/c/atomic/atomic_fetch_xor</a> + </p> +</div> diff --git a/devdocs/c/atomic%2Fatomic_flag.html b/devdocs/c/atomic%2Fatomic_flag.html new file mode 100644 index 00000000..9ce4958c --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_flag.html @@ -0,0 +1,26 @@ + <h1 id="firstHeading" class="firstHeading">atomic_flag</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdatomic.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">struct atomic_flag;</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p><code>atomic_flag</code> is an atomic boolean type. Unlike other atomic types, it is guaranteed to be lock-free. Unlike <a href="../thread#Atomic_operations" title="c/thread"><code>atomic_bool</code></a>, <code>atomic_flag</code> does not provide load or store operations.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.17.1/4 atomic_flag (p: 200) </li> +<li> 7.17.8 Atomic flag type and operations (p: 208-209) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.17.1/4 atomic_flag (p: 273) </li> +<li> 7.17.8 Atomic flag type and operations (p: 285-286) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="atomic_flag_init" title="c/atomic/ATOMIC FLAG INIT"> <span class="t-lines"><span>ATOMIC_FLAG_INIT</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> initializes a new <code>atomic_flag</code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic_flag_test_and_set" title="c/atomic/atomic flag test and set"> <span class="t-lines"><span>atomic_flag_test_and_set</span><span>atomic_flag_test_and_set_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> sets an atomic_flag to true and returns the old value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic_flag_clear" title="c/atomic/atomic flag clear"> <span class="t-lines"><span>atomic_flag_clear</span><span>atomic_flag_clear_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> sets an atomic_flag to false <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic/atomic_flag" title="cpp/atomic/atomic flag">C++ documentation</a></span> for <code>atomic_flag</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic/atomic_flag" class="_attribution-link">https://en.cppreference.com/w/c/atomic/atomic_flag</a> + </p> +</div> diff --git a/devdocs/c/atomic%2Fatomic_flag_clear.html b/devdocs/c/atomic%2Fatomic_flag_clear.html new file mode 100644 index 00000000..a9afc72a --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_flag_clear.html @@ -0,0 +1,22 @@ + <h1 id="firstHeading" class="firstHeading">atomic_flag_clear, atomic_flag_clear_explicit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdatomic.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">void atomic_flag_clear( volatile atomic_flag* obj );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">void atomic_flag_clear_explicit( volatile atomic_flag* obj, memory_order order );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Atomically changes the state of a <code>atomic_flag</code> pointed to by <code>obj</code> to clear (<code>false</code>). The first version orders memory accesses according to <code><a href="memory_order" title="c/atomic/memory order">memory_order_seq_cst</a></code>, the second version orders memory accesses according to <code>order</code>.</p> +<p>The argument is pointer to a volatile atomic flag to accept addresses of both non-volatile and <a href="../language/volatile" title="c/language/volatile">volatile</a> (e.g. memory-mapped I/O) atomic flags.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> obj </td> <td> - </td> <td> pointer to the atomic flag object to modify </td> +</tr> <tr class="t-par"> <td> order </td> <td> - </td> <td> the memory synchronization ordering for this operation: all values are permitted </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.17.8.2 The atomic_flag_clear functions (p: 209) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.17.8.2 The atomic_flag_clear functions (p: 286) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="atomic_flag_test_and_set" title="c/atomic/atomic flag test and set"> <span class="t-lines"><span>atomic_flag_test_and_set</span><span>atomic_flag_test_and_set_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> sets an atomic_flag to true and returns the old value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic/atomic_flag_clear" title="cpp/atomic/atomic flag clear">C++ documentation</a></span> for <code>atomic_flag_clear, atomic_flag_clear_explicit</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic/atomic_flag_clear" class="_attribution-link">https://en.cppreference.com/w/c/atomic/atomic_flag_clear</a> + </p> +</div> diff --git a/devdocs/c/atomic%2Fatomic_flag_init.html b/devdocs/c/atomic%2Fatomic_flag_init.html new file mode 100644 index 00000000..dbe9fef1 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_flag_init.html @@ -0,0 +1,26 @@ + <h1 id="firstHeading" class="firstHeading">ATOMIC_FLAG_INIT</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdatomic.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">#define ATOMIC_FLAG_INIT /* unspecified */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Expands to an initializer that can be used to initialize <code><a href="atomic_flag" title="c/atomic/atomic flag">atomic_flag</a></code> type to the clear state. The value <code>atomic_flag</code> that is not initialized using this macro is indeterminate.</p> +<h3 id="Example"> Example</h3> <div class="c source-c"><pre data-language="c">#include <stdatomic.h> + +atomic_flag flag = ATOMIC_FLAG_INIT;</pre></div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.17.1/3 ATOMIC_FLAG_INIT (p: 200) </li> +<li> 7.17.8/4 ATOMIC_FLAG_INIT (p: 208) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.17.1/3 ATOMIC_FLAG_INIT (p: 273) </li> +<li> 7.17.8/4 ATOMIC_FLAG_INIT (p: 285) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="atomic_var_init" title="c/atomic/ATOMIC VAR INIT"> <span class="t-lines"><span>ATOMIC_VAR_INIT</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span><span class="t-mark-rev t-deprecated-c17">(deprecated in C17)</span><span class="t-mark-rev t-until-c23">(removed in C23)</span></span></span></div> </td> <td> initializes a new atomic object <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic_flag" title="c/atomic/atomic flag"> <span class="t-lines"><span>atomic_flag</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> lock-free atomic boolean flag <br><span class="t-mark">(struct)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic/ATOMIC_FLAG_INIT" title="cpp/atomic/ATOMIC FLAG INIT">C++ documentation</a></span> for <code>ATOMIC_FLAG_INIT</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic/ATOMIC_FLAG_INIT" class="_attribution-link">https://en.cppreference.com/w/c/atomic/ATOMIC_FLAG_INIT</a> + </p> +</div> diff --git a/devdocs/c/atomic%2Fatomic_flag_test_and_set.html b/devdocs/c/atomic%2Fatomic_flag_test_and_set.html new file mode 100644 index 00000000..cd9bf556 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_flag_test_and_set.html @@ -0,0 +1,22 @@ + <h1 id="firstHeading" class="firstHeading">atomic_flag_test_and_set, atomic_flag_test_and_set_explicit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdatomic.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">_Bool atomic_flag_test_and_set( volatile atomic_flag* obj );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">_Bool atomic_flag_test_and_set_explicit( volatile atomic_flag* obj, memory_order order );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Atomically changes the state of a <code>atomic_flag</code> pointed to by <code>obj</code> to set (<code>true</code>) and returns the previous value. The first version orders memory accesses according to <code><a href="memory_order" title="c/atomic/memory order">memory_order_seq_cst</a></code>, the second version orders memory accesses according to <code>order</code>.</p> +<p>The argument is pointer to a volatile atomic flag to accept addresses of both non-volatile and <a href="../language/volatile" title="c/language/volatile">volatile</a> (e.g. memory-mapped I/O) atomic flags.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> obj </td> <td> - </td> <td> pointer to the atomic flag object to modify </td> +</tr> <tr class="t-par"> <td> order </td> <td> - </td> <td> the memory synchronization ordering for this operation: all values are permitted </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The previous value held by the atomic flag pointed to by <code>obj</code>.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.17.8.1 The atomic_flag_test_and_set functions (p: 209) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.17.8.1 The atomic_flag_test_and_set functions (p: 285-286) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="atomic_flag_clear" title="c/atomic/atomic flag clear"> <span class="t-lines"><span>atomic_flag_clear</span><span>atomic_flag_clear_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> sets an atomic_flag to false <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic/atomic_flag_test_and_set" title="cpp/atomic/atomic flag test and set">C++ documentation</a></span> for <code>atomic_flag_test_and_set, atomic_flag_test_and_set_explicit</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic/atomic_flag_test_and_set" class="_attribution-link">https://en.cppreference.com/w/c/atomic/atomic_flag_test_and_set</a> + </p> +</div> diff --git a/devdocs/c/atomic%2Fatomic_init.html b/devdocs/c/atomic%2Fatomic_init.html new file mode 100644 index 00000000..a6790747 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_init.html @@ -0,0 +1,26 @@ + <h1 id="firstHeading" class="firstHeading">atomic_init</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdatomic.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">void atomic_init( volatile A* obj, C desired );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Initializes the default-constructed atomic object <code>obj</code> with the value <code>desired</code>. The function is not atomic: concurrent access from another thread, even through an atomic operation, is a data race.</p> +<p>This is a <a href="../language/generic" title="c/language/generic">generic function</a> defined for all <a href="../language/atomic" title="c/language/atomic">atomic object types</a> <code>A</code>. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and <a href="../language/volatile" title="c/language/volatile">volatile</a> (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects. <code>C</code> is the non-atomic type corresponding to <code>A</code>.</p> +<p>It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like <code>(atomic_init)(...)</code>), or a program defines an external identifier with the name of a generic function, the behavior is undefined.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> obj </td> <td> - </td> <td> pointer to an atomic object to initialize </td> +</tr> <tr class="t-par"> <td> desired </td> <td> - </td> <td> the value to initialize atomic object with </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="Notes"> Notes</h3> <p><code>atomic_init</code> is the only way to initialize dynamically-allocated atomic objects. For example:</p> +<div class="c source-c"><pre data-language="c">_Atomic int *p = malloc(sizeof(_Atomic int)); +atomic_init(p, 42);</pre></div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.17.2.2 The atomic_init generic function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.17.2.2 The atomic_init generic function (p: 201) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.17.2.2 The atomic_init generic function (p: 274-275) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="atomic_var_init" title="c/atomic/ATOMIC VAR INIT"> <span class="t-lines"><span>ATOMIC_VAR_INIT</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span><span class="t-mark-rev t-deprecated-c17">(deprecated in C17)</span><span class="t-mark-rev t-until-c23">(removed in C23)</span></span></span></div> </td> <td> initializes a new atomic object <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic/atomic_init" title="cpp/atomic/atomic init">C++ documentation</a></span> for <code>atomic_init</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic/atomic_init" class="_attribution-link">https://en.cppreference.com/w/c/atomic/atomic_init</a> + </p> +</div> diff --git a/devdocs/c/atomic%2Fatomic_is_lock_free.html b/devdocs/c/atomic%2Fatomic_is_lock_free.html new file mode 100644 index 00000000..373ff242 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_is_lock_free.html @@ -0,0 +1,39 @@ + <h1 id="firstHeading" class="firstHeading">atomic_is_lock_free</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdatomic.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">_Bool atomic_is_lock_free( const volatile A* obj );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Determines if the atomic operations on all objects of the type <code>A</code> (the type of the object pointed to by <code>obj</code>) are lock-free. In any given program execution, the result of calling <code>atomic_is_lock_free</code> is the same for all pointers of the same type.</p> +<p>This is a <a href="../language/generic" title="c/language/generic">generic function</a> defined for all <a href="../language/atomic" title="c/language/atomic">atomic object types</a> <code>A</code>. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and <a href="../language/volatile" title="c/language/volatile">volatile</a> (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects.</p> +<p>It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like <code>(atomic_is_lock_free)(...)</code>), or a program defines an external identifier with the name of a generic function, the behavior is undefined.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> obj </td> <td> - </td> <td> pointer to the atomic object to inspect </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>true</code> if the operations on all objects of the type <code>A</code> are lock-free, <code>false</code> otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdatomic.h> + +_Atomic struct A { int a[100]; } a; +_Atomic struct B { int x, y; } b; +int main(void) +{ + printf("_Atomic struct A is lock free? %s\n", + atomic_is_lock_free(&a) ? "true" : "false"); + printf("_Atomic struct B is lock free? %s\n", + atomic_is_lock_free(&b) ? "true" : "false"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">_Atomic struct A is lock free? false +_Atomic struct B is lock free? true</pre></div> </div> <h3 id="Defect_reports"> Defect reports</h3> <p>The following behavior-changing defect reports were applied retroactively to previously published C standards.</p> +<table class="dsctable"> <tr> <th>DR </th> <th>Applied to </th> <th>Behavior as published </th> <th>Correct behavior </th> +</tr> <tr> <td> +<a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_465">DR 465</a> </td> <td>C11 </td> <td>this function was per-object </td> <td>this functions is per-type </td> +</tr> +</table> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.17.5.1 The atomic_is_lock_free generic function (p: 205) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.17.5.1 The atomic_is_lock_free generic function (p: 280) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="atomic_lock_free_consts" title="c/atomic/ATOMIC LOCK FREE consts"> <span class="t-lines"><span>ATOMIC_BOOL_LOCK_FREE</span><span>ATOMIC_CHAR_LOCK_FREE</span><span>ATOMIC_CHAR16_T_LOCK_FREE</span><span>ATOMIC_CHAR32_T_LOCK_FREE</span><span>ATOMIC_WCHAR_T_LOCK_FREE</span><span>ATOMIC_SHORT_LOCK_FREE</span><span>ATOMIC_INT_LOCK_FREE</span><span>ATOMIC_LONG_LOCK_FREE</span><span>ATOMIC_LLONG_LOCK_FREE</span><span>ATOMIC_POINTER_LOCK_FREE</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> indicates that the given atomic type is lock-free <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic/atomic_is_lock_free" title="cpp/atomic/atomic is lock free">C++ documentation</a></span> for <code>atomic_is_lock_free</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic/atomic_is_lock_free" class="_attribution-link">https://en.cppreference.com/w/c/atomic/atomic_is_lock_free</a> + </p> +</div> diff --git a/devdocs/c/atomic%2Fatomic_load.html b/devdocs/c/atomic%2Fatomic_load.html new file mode 100644 index 00000000..6c2bd77f --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_load.html @@ -0,0 +1,24 @@ + <h1 id="firstHeading" class="firstHeading">atomic_load, atomic_load_explicit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdatomic.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">C atomic_load( const volatile A* obj );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">C atomic_load_explicit( const volatile A* obj, memory_order order );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Atomically loads and returns the current value of the atomic variable pointed to by <code>obj</code>. The operation is atomic read operation.</p> +<p>The first version orders memory accesses according to <code><a href="memory_order" title="c/atomic/memory order">memory_order_seq_cst</a></code>, the second version orders memory accesses according to <code>order</code>. <code>order</code> must be one of <code><a href="memory_order" title="c/atomic/memory order">memory_order_relaxed</a></code>, <code><a href="memory_order" title="c/atomic/memory order">memory_order_consume</a></code>, <code><a href="memory_order" title="c/atomic/memory order">memory_order_acquire</a></code> or <code><a href="memory_order" title="c/atomic/memory order">memory_order_seq_cst</a></code>. Otherwise the behavior is undefined.</p> +<p>This is a <a href="../language/generic" title="c/language/generic">generic function</a> defined for all <a href="../language/atomic" title="c/language/atomic">atomic object types</a> <code>A</code>. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and <a href="../language/volatile" title="c/language/volatile">volatile</a> (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects. <code>C</code> is the non-atomic type corresponding to <code>A</code>.</p> +<p>It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like <code>(atomic_load)(...)</code>), or a program defines an external identifier with the name of a generic function, the behavior is undefined.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> obj </td> <td> - </td> <td> pointer to the atomic object to access </td> +</tr> <tr class="t-par"> <td> order </td> <td> - </td> <td> the memory synchronization ordering for this operation </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The current value of the atomic variable pointed to by <code>obj</code>.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.17.7.2 The atomic_load generic functions (p: 206) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.17.7.2 The atomic_load generic functions (p: 282) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="atomic_store" title="c/atomic/atomic store"> <span class="t-lines"><span>atomic_store</span><span>atomic_store_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> stores a value in an atomic object <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic/atomic_load" title="cpp/atomic/atomic load">C++ documentation</a></span> for <code>atomic_load, atomic_load_explicit</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic/atomic_load" class="_attribution-link">https://en.cppreference.com/w/c/atomic/atomic_load</a> + </p> +</div> diff --git a/devdocs/c/atomic%2Fatomic_lock_free_consts.html b/devdocs/c/atomic%2Fatomic_lock_free_consts.html new file mode 100644 index 00000000..ad4bd120 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_lock_free_consts.html @@ -0,0 +1,27 @@ + <h1 id="firstHeading" class="firstHeading">ATOMIC_*_LOCK_FREE</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdatomic.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">#define ATOMIC_BOOL_LOCK_FREE /* implementation-defined */ +#define ATOMIC_CHAR_LOCK_FREE /* implementation-defined */ +#define ATOMIC_CHAR16_T_LOCK_FREE /* implementation-defined */ +#define ATOMIC_CHAR32_T_LOCK_FREE /* implementation-defined */ +#define ATOMIC_WCHAR_T_LOCK_FREE /* implementation-defined */ +#define ATOMIC_SHORT_LOCK_FREE /* implementation-defined */ +#define ATOMIC_INT_LOCK_FREE /* implementation-defined */ +#define ATOMIC_LONG_LOCK_FREE /* implementation-defined */ +#define ATOMIC_LLONG_LOCK_FREE /* implementation-defined */ +#define ATOMIC_POINTER_LOCK_FREE /* implementation-defined */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">#define ATOMIC_CHAR8_T_LOCK_FREE /* implementation-defined */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <p>Expands to <a href="../language/constant_expression" title="c/language/constant expression">preprocessor constant expressions</a> that evaluate to either <code>0</code>, <code>1</code>, or <code>2</code> which indicate the lock-free property of the corresponding <a href="../thread#Atomic_operations" title="c/thread">atomic types</a> (both signed and unsigned).</p> +<table class="t-dsc-begin"> <tr class="t-dsc-hitem"> <th> Value </th> <th> Explanation </th> +</tr> <tr class="t-dsc"> <td> <code>0</code> </td> <td> The atomic type is never lock-free </td> +</tr> <tr class="t-dsc"> <td> <code>1</code> </td> <td> The atomic type is sometimes lock-free </td> +</tr> <tr class="t-dsc"> <td> <code>2</code> </td> <td> The atomic type is always lock-free </td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.17.1/3 atomic lock-free macros (p: 200) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.17.1/3 atomic lock-free macros (p: 273) </li></ul> +</ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic/ATOMIC_LOCK_FREE_consts" class="_attribution-link">https://en.cppreference.com/w/c/atomic/ATOMIC_LOCK_FREE_consts</a> + </p> +</div> diff --git a/devdocs/c/atomic%2Fatomic_signal_fence.html b/devdocs/c/atomic%2Fatomic_signal_fence.html new file mode 100644 index 00000000..6dec1af8 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_signal_fence.html @@ -0,0 +1,19 @@ + <h1 id="firstHeading" class="firstHeading">atomic_signal_fence</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdatomic.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">void atomic_signal_fence( memory_order order );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Establishes memory synchronization ordering of non-atomic and relaxed atomic accesses, as instructed by <code>order</code>, between a thread and a signal handler executed on the same thread. This is equivalent to <code><a href="atomic_thread_fence" title="c/atomic/atomic thread fence">atomic_thread_fence</a></code>, except no CPU instructions for memory ordering are issued. Only reordering of the instructions by the compiler is suppressed as <code>order</code> instructs. For example, a fence with release semantics prevents reads or writes from being moved past subsequent writes and a fence with acquire semantics prevents reads or writes from being moved ahead of preceding reads.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> order </td> <td> - </td> <td> the memory ordering executed by this fence </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.17.4.2 The atomic_signal_fence function (p: 204-205) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.17.4.2 The atomic_signal_fence function (p: 279) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="atomic_thread_fence" title="c/atomic/atomic thread fence"> <span class="t-lines"><span>atomic_thread_fence</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> generic memory order-dependent fence synchronization primitive <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic/atomic_signal_fence" title="cpp/atomic/atomic signal fence">C++ documentation</a></span> for <code>atomic_signal_fence</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic/atomic_signal_fence" class="_attribution-link">https://en.cppreference.com/w/c/atomic/atomic_signal_fence</a> + </p> +</div> diff --git a/devdocs/c/atomic%2Fatomic_store.html b/devdocs/c/atomic%2Fatomic_store.html new file mode 100644 index 00000000..c213430e --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_store.html @@ -0,0 +1,24 @@ + <h1 id="firstHeading" class="firstHeading">atomic_store, atomic_store_explicit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdatomic.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">void atomic_store( volatile A* obj , C desired );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">void atomic_store_explicit( volatile A* obj, C desired, memory_order order );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Atomically replaces the value of the atomic variable pointed to by <code>obj</code> with <code>desired</code>. The operation is atomic write operation.</p> +<p>The first version orders memory accesses according to <code><a href="memory_order" title="c/atomic/memory order">memory_order_seq_cst</a></code>, the second version orders memory accesses according to <code>order</code>. <code>order</code> must be one of <code><a href="memory_order" title="c/atomic/memory order">memory_order_relaxed</a></code>, <code><a href="memory_order" title="c/atomic/memory order">memory_order_release</a></code> or <code><a href="memory_order" title="c/atomic/memory order">memory_order_seq_cst</a></code>. Otherwise the behavior is undefined.</p> +<p>This is a <a href="../language/generic" title="c/language/generic">generic function</a> defined for all <a href="../language/atomic" title="c/language/atomic">atomic object types</a> <code>A</code>. The argument is pointer to a volatile atomic type to accept addresses of both non-volatile and <a href="../language/volatile" title="c/language/volatile">volatile</a> (e.g. memory-mapped I/O) atomic objects, and volatile semantic is preserved when applying this operation to volatile atomic objects. <code>C</code> is the non-atomic type corresponding to <code>A</code>.</p> +<p>It is unspecified whether the name of a generic function is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function (e.g. parenthesized like <code>(atomic_store)(...)</code>), or a program defines an external identifier with the name of a generic function, the behavior is undefined.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> obj </td> <td> - </td> <td> pointer to the atomic object to modify </td> +</tr> <tr class="t-par"> <td> order </td> <td> - </td> <td> the memory synchronization ordering for this operation </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.17.7.1 The atomic_store generic functions (p: 206) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.17.7.1 The atomic_store generic functions (p: 282) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="atomic_load" title="c/atomic/atomic load"> <span class="t-lines"><span>atomic_load</span><span>atomic_load_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads a value from an atomic object <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic/atomic_store" title="cpp/atomic/atomic store">C++ documentation</a></span> for <code>atomic_store, atomic_store_explicit</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic/atomic_store" class="_attribution-link">https://en.cppreference.com/w/c/atomic/atomic_store</a> + </p> +</div> diff --git a/devdocs/c/atomic%2Fatomic_thread_fence.html b/devdocs/c/atomic%2Fatomic_thread_fence.html new file mode 100644 index 00000000..73fd6206 --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_thread_fence.html @@ -0,0 +1,19 @@ + <h1 id="firstHeading" class="firstHeading">atomic_thread_fence</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdatomic.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">void atomic_thread_fence( memory_order order );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Establishes memory synchronization ordering of non-atomic and relaxed atomic accesses, as instructed by <code>order</code>, without an associated atomic operation. For example, all non-atomic and relaxed atomic stores that happen before a <code><a href="memory_order" title="c/atomic/memory order">memory_order_release</a></code> fence in thread A will be synchronized with non-atomic and relaxed atomic loads from the same locations made in thread B after an <code><a href="memory_order" title="c/atomic/memory order">memory_order_acquire</a></code> fence.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> order </td> <td> - </td> <td> the memory ordering executed by this fence </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.17.4.1 The atomic_thread_fence function (p: 204) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.17.4.1 The atomic_thread_fence function (p: 278-279) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="atomic_signal_fence" title="c/atomic/atomic signal fence"> <span class="t-lines"><span>atomic_signal_fence</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> fence between a thread and a signal handler executed in the same thread <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic/atomic_thread_fence" title="cpp/atomic/atomic thread fence">C++ documentation</a></span> for <code>atomic_thread_fence</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic/atomic_thread_fence" class="_attribution-link">https://en.cppreference.com/w/c/atomic/atomic_thread_fence</a> + </p> +</div> diff --git a/devdocs/c/atomic%2Fatomic_var_init.html b/devdocs/c/atomic%2Fatomic_var_init.html new file mode 100644 index 00000000..66208dac --- /dev/null +++ b/devdocs/c/atomic%2Fatomic_var_init.html @@ -0,0 +1,24 @@ + <h1 id="firstHeading" class="firstHeading">ATOMIC_VAR_INIT</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdatomic.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11 t-until-c23"> <td> <pre data-language="c">#define ATOMIC_VAR_INIT(value) /* unspecified */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> <br><span class="t-mark">(deprecated in C17)</span> <br><span class="t-mark-rev t-until-c23">(removed in C23)</span> </td> </tr> </table> <p>Expands to an expression that can be used to initialize an atomic variable of the same type as <code>value</code>.</p> +<p>The initial value of atomic object of automatic storage duration that is not explicitly initialized is indeterminate. The default (zero) initialization of static and thread-local variables produces a valid value however.</p> +<p>When initializing an atomic variable, any concurrent access, even through an atomic operation, is a data race (it may happen if the address is immediately passed to another thread with a <code><a href="memory_order" title="c/atomic/memory order">memory_order_relaxed</a></code> operation).</p> +<h3 id="Notes"> Notes</h3> <p>This macro was a part of early draft design for C11 atomic types. It is not needed in C11, and is deprecated in C17 and removed in C23.</p> +<h3 id="Defect_reports"> Defect reports</h3> <p>The following behavior-changing defect reports were applied retroactively to previously published C standards.</p> +<table class="dsctable"> <tr> <th>DR </th> <th>Applied to </th> <th>Behavior as published </th> <th>Correct behavior </th> +</tr> <tr> <td> +<a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_485">DR 485</a> </td> <td>C11 </td> <td>the specification was redundant and contradictory to the core language </td> <td>fixed </td> +</tr> +</table> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.17.2.1 The ATOMIC_VAR_INIT macro (p: 201) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.17.2.1 The ATOMIC_VAR_INIT macro (p: 274) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="atomic_flag_init" title="c/atomic/ATOMIC FLAG INIT"> <span class="t-lines"><span>ATOMIC_FLAG_INIT</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> initializes a new <code><a href="http://en.cppreference.com/w/c/atomic/atomic_flag"><span class="kw917">atomic_flag</span></a></code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic/ATOMIC_VAR_INIT" title="cpp/atomic/ATOMIC VAR INIT">C++ documentation</a></span> for <code>ATOMIC_VAR_INIT</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic/ATOMIC_VAR_INIT" class="_attribution-link">https://en.cppreference.com/w/c/atomic/ATOMIC_VAR_INIT</a> + </p> +</div> diff --git a/devdocs/c/atomic%2Fkill_dependency.html b/devdocs/c/atomic%2Fkill_dependency.html new file mode 100644 index 00000000..3a4d470f --- /dev/null +++ b/devdocs/c/atomic%2Fkill_dependency.html @@ -0,0 +1,20 @@ + <h1 id="firstHeading" class="firstHeading">kill_dependency</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdatomic.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">A kill_dependency( A y );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Informs the compiler that the dependency tree started by an <code><a href="memory_order" title="c/atomic/memory order">memory_order_consume</a></code> atomic load operation does not extend past the return value of <code>kill_dependency</code>; that is, the argument does not carry a dependency into the return value.</p> +<p>The function is implemented as a macro. <code>A</code> is the type of <code>y</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> y </td> <td> - </td> <td> the expression whose return value is to be removed from a dependency tree </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Returns <code>y</code>, no longer a part of a dependency tree.</p> +<h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.17.3.1 The kill_dependency macro (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.17.3.1 The kill_dependency macro (p: 203-204) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.17.3.1 The kill_dependency macro (p: 278) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic/kill_dependency" title="cpp/atomic/kill dependency">C++ documentation</a></span> for <code>kill_dependency</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic/kill_dependency" class="_attribution-link">https://en.cppreference.com/w/c/atomic/kill_dependency</a> + </p> +</div> diff --git a/devdocs/c/atomic%2Fmemory_order.html b/devdocs/c/atomic%2Fmemory_order.html new file mode 100644 index 00000000..e7d320ac --- /dev/null +++ b/devdocs/c/atomic%2Fmemory_order.html @@ -0,0 +1,92 @@ + <h1 id="firstHeading" class="firstHeading">memory_order</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdatomic.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">enum memory_order { + memory_order_relaxed, + memory_order_consume, + memory_order_acquire, + memory_order_release, + memory_order_acq_rel, + memory_order_seq_cst +};</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p><code>memory_order</code> specifies how memory accesses, including regular, non-atomic memory accesses, are to be ordered around an atomic operation. Absent any constraints on a multi-core system, when multiple threads simultaneously read and write to several variables, one thread can observe the values change in an order different from the order another thread wrote them. Indeed, the apparent order of changes can even differ among multiple reader threads. Some similar effects can occur even on uniprocessor systems due to compiler transformations allowed by the memory model.</p> +<p>The default behavior of all atomic operations in the <a href="../language/atomic" title="c/language/atomic">language</a> and the library provides for <i>sequentially consistent ordering</i> (see discussion below). That default can hurt performance, but the library's atomic operations can be given an additional <code>memory_order</code> argument to specify the exact constraints, beyond atomicity, that the compiler and processor must enforce for that operation.</p> +<h3 id="Constants"> Constants</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdatomic.h></code> </th> +</tr> <tr class="t-dsc-hitem"> <th> Value </th> <th> Explanation </th> +</tr> <tr class="t-dsc"> <td> <code>memory_order_relaxed</code> </td> <td> Relaxed operation: there are no synchronization or ordering constraints imposed on other reads or writes, only this operation's atomicity is guaranteed (see <a href="#Relaxed_ordering">Relaxed ordering</a> below). </td> +</tr> <tr class="t-dsc"> <td> <code>memory_order_consume</code> </td> <td> A load operation with this memory order performs a <i>consume operation</i> on the affected memory location: no reads or writes in the current thread dependent on the value currently loaded can be reordered before this load. Writes to data-dependent variables in other threads that release the same atomic variable are visible in the current thread. On most platforms, this affects compiler optimizations only (see <a href="#Release-Consume_ordering">Release-Consume ordering</a> below). </td> +</tr> <tr class="t-dsc"> <td> <code>memory_order_acquire</code> </td> <td> A load operation with this memory order performs the <i>acquire operation</i> on the affected memory location: no reads or writes in the current thread can be reordered before this load. All writes in other threads that release the same atomic variable are visible in the current thread (see <a href="#Release-Acquire_ordering">Release-Acquire ordering</a> below). </td> +</tr> <tr class="t-dsc"> <td> <code>memory_order_release</code> </td> <td> A store operation with this memory order performs the <i>release operation</i>: no reads or writes in the current thread can be reordered after this store. All writes in the current thread are visible in other threads that acquire the same atomic variable (see <a href="#Release-Acquire_ordering">Release-Acquire ordering</a> below) and writes that carry a dependency into the atomic variable become visible in other threads that consume the same atomic (see <a href="#Release-Consume_ordering">Release-Consume ordering</a> below). </td> +</tr> <tr class="t-dsc"> <td> <code>memory_order_acq_rel</code> </td> <td> A read-modify-write operation with this memory order is both an <i>acquire operation</i> and a <i>release operation</i>. No memory reads or writes in the current thread can be reordered before the load, nor after the store. All writes in other threads that release the same atomic variable are visible before the modification and the modification is visible in other threads that acquire the same atomic variable. </td> +</tr> <tr class="t-dsc"> <td> <code>memory_order_seq_cst</code> </td> <td> A load operation with this memory order performs an <i>acquire operation</i>, a store performs a <i>release operation</i>, and read-modify-write performs both an <i>acquire operation</i> and a <i>release operation</i>, plus a single total order exists in which all threads observe all modifications in the same order (see <a href="#Sequentially-consistent_ordering">Sequentially-consistent ordering</a> below). </td> +</tr> </table> <h4 id="Relaxed_ordering"> Relaxed ordering</h4> <p>Atomic operations tagged <code>memory_order_relaxed</code> are not synchronization operations; they do not impose an order among concurrent memory accesses. They only guarantee atomicity and modification order consistency.</p> +<p>For example, with <code>x</code> and <code>y</code> initially zero,</p> +<p><code><span class="co1">// Thread 1:</span><br> r1 <span class="sy1">=</span> <a href="http://en.cppreference.com/w/c/atomic/atomic_load"><span class="kw933">atomic_load_explicit</span></a><span class="br0">(</span>y, memory_order_relaxed<span class="br0">)</span><span class="sy4">;</span> <span class="co1">// A</span><br> <a href="http://en.cppreference.com/w/c/atomic/atomic_store"><span class="kw931">atomic_store_explicit</span></a><span class="br0">(</span>x, r1, memory_order_relaxed<span class="br0">)</span><span class="sy4">;</span> <span class="co1">// B</span><br> <span class="co1">// Thread 2:</span><br> r2 <span class="sy1">=</span> <a href="http://en.cppreference.com/w/c/atomic/atomic_load"><span class="kw933">atomic_load_explicit</span></a><span class="br0">(</span>x, memory_order_relaxed<span class="br0">)</span><span class="sy4">;</span> <span class="co1">// C</span><br> <a href="http://en.cppreference.com/w/c/atomic/atomic_store"><span class="kw931">atomic_store_explicit</span></a><span class="br0">(</span>y, <span class="nu0">42</span>, memory_order_relaxed<span class="br0">)</span><span class="sy4">;</span> <span class="co1">// D</span></code></p> +<p>is allowed to produce <code>r1 == r2 == 42</code> because, although A is <i>sequenced-before</i> B within thread 1 and C is <i>sequenced before</i> D within thread 2, nothing prevents D from appearing before A in the modification order of y, and B from appearing before C in the modification order of x. The side-effect of D on y could be visible to the load A in thread 1 while the side effect of B on x could be visible to the load C in thread 2. In particular, this may occur if D is completed before C in thread 2, either due to compiler reordering or at runtime.</p> +<p>Typical use for relaxed memory ordering is incrementing counters, such as the reference counters , since this only requires atomicity, but not ordering or synchronization .</p> +<h4 id="Release-Consume_ordering"> Release-Consume ordering</h4> <p>If an atomic store in thread A is tagged <code>memory_order_release</code>, an atomic load in thread B from the same variable is tagged <code>memory_order_consume</code>, and the load in thread B reads a value written by the store in thread A, then the store in thread A is <i>dependency-ordered before</i> the load in thread B.</p> +<p>All memory writes (non-atomic and relaxed atomic) that <i>happened-before</i> the atomic store from the point of view of thread A, become <i>visible side-effects</i> within those operations in thread B into which the load operation <i>carries dependency</i>, that is, once the atomic load is completed, those operators and functions in thread B that use the value obtained from the load are guaranteed to see what thread A wrote to memory.</p> +<p>The synchronization is established only between the threads <i>releasing</i> and <i>consuming</i> the same atomic variable. Other threads can see different order of memory accesses than either or both of the synchronized threads.</p> +<p>On all mainstream CPUs other than DEC Alpha, dependency ordering is automatic, no additional CPU instructions are issued for this synchronization mode, only certain compiler optimizations are affected (e.g. the compiler is prohibited from performing speculative loads on the objects that are involved in the dependency chain).</p> +<p>Typical use cases for this ordering involve read access to rarely written concurrent data structures (routing tables, configuration, security policies, firewall rules, etc) and publisher-subscriber situations with pointer-mediated publication, that is, when the producer publishes a pointer through which the consumer can access information: there is no need to make everything else the producer wrote to memory visible to the consumer (which may be an expensive operation on weakly-ordered architectures). An example of such scenario is <a href="https://en.wikipedia.org/wiki/Read-copy-update" class="extiw" title="enwiki:Read-copy-update">rcu_dereference</a>.</p> +<p>Note that currently (2/2015) no known production compilers track dependency chains: consume operations are lifted to acquire operations.</p> +<h4 id="Release_sequence"> Release sequence</h4> <p>If some atomic is store-released and several other threads perform read-modify-write operations on that atomic, a "release sequence" is formed: all threads that perform the read-modify-writes to the same atomic synchronize with the first thread and each other even if they have no <code>memory_order_release</code> semantics. This makes single producer - multiple consumers situations possible without imposing unnecessary synchronization between individual consumer threads.</p> +<h4 id="Release-Acquire_ordering"> Release-Acquire ordering</h4> <p>If an atomic store in thread A is tagged <code>memory_order_release</code>, an atomic load in thread B from the same variable is tagged <code>memory_order_acquire</code>, and the load in thread B reads a value written by the store in thread A, then the store in thread A <i>synchronizes-with</i> the load in thread B.</p> +<p>All memory writes (including non-atomic and relaxed atomic) that <i>happened-before</i> the atomic store from the point of view of thread A, become <i>visible side-effects</i> in thread B. That is, once the atomic load is completed, thread B is guaranteed to see everything thread A wrote to memory. This promise only holds if B actually returns the value that A stored, or a value from later in the release sequence.</p> +<p>The synchronization is established only between the threads <i>releasing</i> and <i>acquiring</i> the same atomic variable. Other threads can see different order of memory accesses than either or both of the synchronized threads.</p> +<p>On strongly-ordered systems — x86, SPARC TSO, IBM mainframe, etc. — release-acquire ordering is automatic for the majority of operations. No additional CPU instructions are issued for this synchronization mode; only certain compiler optimizations are affected (e.g., the compiler is prohibited from moving non-atomic stores past the atomic store-release or performing non-atomic loads earlier than the atomic load-acquire). On weakly-ordered systems (ARM, Itanium, PowerPC), special CPU load or memory fence instructions are used.</p> +<p>Mutual exclusion locks, such as <a href="../thread#Mutual_exclusion" title="c/thread">mutexes</a> or <a href="atomic_flag_test_and_set" title="c/atomic/atomic flag test and set">atomic spinlocks</a>, are an example of release-acquire synchronization: when the lock is released by thread A and acquired by thread B, everything that took place in the critical section (before the release) in the context of thread A has to be visible to thread B (after the acquire) which is executing the same critical section.</p> +<h4 id="Sequentially-consistent_ordering"> Sequentially-consistent ordering</h4> <p>Atomic operations tagged <code>memory_order_seq_cst</code> not only order memory the same way as release/acquire ordering (everything that <i>happened-before</i> a store in one thread becomes a <i>visible side effect</i> in the thread that did a load), but also establish a <i>single total modification order</i> of all atomic operations that are so tagged.</p> +<p>Formally,</p> +<p>each <code>memory_order_seq_cst</code> operation B that loads from atomic variable M, observes one of the following:</p> +<ul> +<li> the result of the last operation A that modified M, which appears before B in the single total order, </li> +<li> OR, if there was such an A, B may observe the result of some modification on M that is not <code>memory_order_seq_cst</code> and does not <i>happen-before</i> A, </li> +<li> OR, if there wasn't such an A, B may observe the result of some unrelated modification of M that is not <code>memory_order_seq_cst</code>. </li> +</ul> <p>If there was a <code>memory_order_seq_cst</code> <code><a href="atomic_thread_fence" title="c/atomic/atomic thread fence">atomic_thread_fence</a></code> operation X <i>sequenced-before</i> B, then B observes one of the following:</p> +<ul> +<li> the last <code>memory_order_seq_cst</code> modification of M that appears before X in the single total order, </li> +<li> some unrelated modification of M that appears later in M's modification order. </li> +</ul> <p>For a pair of atomic operations on M called A and B, where A writes and B reads M's value, if there are two <code>memory_order_seq_cst</code> <code><a href="atomic_thread_fence" title="c/atomic/atomic thread fence">atomic_thread_fence</a></code>s X and Y, and if A is <i>sequenced-before</i> X, Y is <i>sequenced-before</i> B, and X appears before Y in the Single Total Order, then B observes either:</p> +<ul> +<li> the effect of A, </li> +<li> some unrelated modification of M that appears after A in M's modification order. </li> +</ul> <p>For a pair of atomic modifications of M called A and B, B occurs after A in M's modification order if</p> +<ul> +<li> there is a <code>memory_order_seq_cst</code> <code><a href="atomic_thread_fence" title="c/atomic/atomic thread fence">atomic_thread_fence</a></code> X such that A is <i>sequenced-before</i> X and X appears before B in the Single Total Order, </li> +<li> or, there is a <code>memory_order_seq_cst</code> <code><a href="atomic_thread_fence" title="c/atomic/atomic thread fence">atomic_thread_fence</a></code> Y such that Y is <i>sequenced-before</i> B and A appears before Y in the Single Total Order, </li> +<li> or, there are <code>memory_order_seq_cst</code> <code><a href="atomic_thread_fence" title="c/atomic/atomic thread fence">atomic_thread_fence</a></code>s X and Y such that A is <i>sequenced-before</i> X, Y is <i>sequenced-before</i> B, and X appears before Y in the Single Total Order. </li> +</ul> <p>Note that this means that:</p> +<div class="t-li1"> +<span class="t-li">1)</span> as soon as atomic operations that are not tagged <code>memory_order_seq_cst</code> enter the picture, the sequential consistency is lost,</div> <div class="t-li1"> +<span class="t-li">2)</span> the sequentially-consistent fences are only establishing total ordering for the fences themselves, not for the atomic operations in the general case (<i>sequenced-before</i> is not a cross-thread relationship, unlike <i>happens-before</i>).</div> <p>Sequential ordering may be necessary for multiple producer-multiple consumer situations where all consumers must observe the actions of all producers occurring in the same order.</p> +<p>Total sequential ordering requires a full memory fence CPU instruction on all multi-core systems. This may become a performance bottleneck since it forces the affected memory accesses to propagate to every core.</p> +<h3 id="Relationship_with_volatile"> Relationship with volatile</h3> <p>Within a thread of execution, accesses (reads and writes) through <a href="../language/volatile" title="c/language/volatile">volatile lvalues</a> cannot be reordered past observable side-effects (including other volatile accesses) that are separated by a sequence point within the same thread, but this order is not guaranteed to be observed by another thread, since volatile access does not establish inter-thread synchronization.</p> +<p>In addition, volatile accesses are not atomic (concurrent read and write is a <a href="../language/memory_model" title="c/language/memory model">data race</a>) and do not order memory (non-volatile memory accesses may be freely reordered around the volatile access).</p> +<p>One notable exception is Visual Studio, where, with default settings, every volatile write has release semantics and every volatile read has acquire semantics (<a rel="nofollow" class="external text" href="https://docs.microsoft.com/en-us/cpp/cpp/volatile-cpp">Microsoft Docs</a>), and thus volatiles may be used for inter-thread synchronization. Standard <code>volatile</code> semantics are not applicable to multithreaded programming, although they are sufficient for e.g. communication with a <code><a href="../program/signal" title="c/program/signal">signal</a></code> handler that runs in the same thread when applied to <code><a href="http://en.cppreference.com/w/c/program/sig_atomic_t"><span class="kw499">sig_atomic_t</span></a></code> variables.</p> +<h3 id="Examples"> Examples</h3> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.17.1/4 memory_order (p: 200) </li> +<li> 7.17.3 Order and consistency (p: 201-203) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.17.1/4 memory_order (p: 273) </li> +<li> 7.17.3 Order and consistency (p: 275-277) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic/memory_order" title="cpp/atomic/memory order">C++ documentation</a></span> for <span class=""><span>memory order</span></span> </td> +</tr> </table> <h3 id="External_links"> External links</h3> <table> <tr style="vertical-align:top;"> <td>1. </td> <td> +<a href="https://en.wikipedia.org/wiki/MOESI_protocol" class="extiw" title="enwiki:MOESI protocol">MOESI protocol</a> </td> +</tr> <tr style="vertical-align:top;"> <td>2. </td> <td> +<a rel="nofollow" class="external text" href="https://www.cl.cam.ac.uk/~pes20/weakmemory/cacm.pdf">x86-TSO: A Rigorous and Usable Programmer’s Model for x86 Multiprocessors</a> P. Sewell et. al., 2010 </td> +</tr> <tr style="vertical-align:top;"> <td>3. </td> <td> +<a rel="nofollow" class="external text" href="https://www.cl.cam.ac.uk/~pes20/ppc-supplemental/test7.pdf">A Tutorial Introduction to the ARM and POWER Relaxed Memory Models</a> P. Sewell et al, 2012 </td> +</tr> <tr style="vertical-align:top;"> <td>4. </td> <td> +<a rel="nofollow" class="external text" href="https://researchspace.auckland.ac.nz/bitstream/handle/2292/11594/MESIF-2009.pdf?sequence=6">MESIF: A Two-Hop Cache Coherency Protocol for Point-to-Point Interconnects</a> J.R. Goodman, H.H.J. Hum, 2009 </td> +</tr> <tr style="vertical-align:top;"> <td>5. </td> <td> +<a rel="nofollow" class="external text" href="https://research.swtch.com/mm">Memory Models</a> Russ Cox, 2021 </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic/memory_order" class="_attribution-link">https://en.cppreference.com/w/c/atomic/memory_order</a> + </p> +</div> diff --git a/devdocs/c/atomic.html b/devdocs/c/atomic.html new file mode 100644 index 00000000..e0c45c68 --- /dev/null +++ b/devdocs/c/atomic.html @@ -0,0 +1,109 @@ + <h1 id="firstHeading" class="firstHeading">Atomic operations library</h1> <p>If the macro constant <code>__STDC_NO_ATOMICS__</code><span class="t-mark-rev t-since-c11">(C11)</span> is defined by the compiler, the header <code><stdatomic.h></code>, the keyword <code>_Atomic</code>, and all of the names listed here are not provided.</p> +<h3 id="Types"> Types</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdatomic.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/memory_order" title="c/atomic/memory order"> <span class="t-lines"><span>memory_order</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> defines memory ordering constraints <br> <span class="t-mark">(enum)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_flag" title="c/atomic/atomic flag"> <span class="t-lines"><span>atomic_flag</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> lock-free atomic boolean flag <br><span class="t-mark">(struct)</span> </td> +</tr> </table> <h3 id="Macros"> Macros</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdatomic.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_lock_free_consts" title="c/atomic/ATOMIC LOCK FREE consts"> <span class="t-lines"><span>ATOMIC_BOOL_LOCK_FREE</span><span>ATOMIC_CHAR_LOCK_FREE</span><span>ATOMIC_CHAR16_T_LOCK_FREE</span><span>ATOMIC_CHAR32_T_LOCK_FREE</span><span>ATOMIC_WCHAR_T_LOCK_FREE</span><span>ATOMIC_SHORT_LOCK_FREE</span><span>ATOMIC_INT_LOCK_FREE</span><span>ATOMIC_LONG_LOCK_FREE</span><span>ATOMIC_LLONG_LOCK_FREE</span><span>ATOMIC_POINTER_LOCK_FREE</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> indicates that the given atomic type is lock-free <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_flag_init" title="c/atomic/ATOMIC FLAG INIT"> <span class="t-lines"><span>ATOMIC_FLAG_INIT</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> initializes a new <code><a href="http://en.cppreference.com/w/c/atomic/atomic_flag"><span class="kw917">atomic_flag</span></a></code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_var_init" title="c/atomic/ATOMIC VAR INIT"> <span class="t-lines"><span>ATOMIC_VAR_INIT</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span><span class="t-mark-rev t-deprecated-c17">(deprecated in C17)</span><span class="t-mark-rev t-until-c23">(removed in C23)</span></span></span></div> </td> <td> initializes a new atomic object <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/kill_dependency" title="c/atomic/kill dependency"> <span class="t-lines"><span>kill_dependency</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> breaks a dependency chain for <code><a href="http://en.cppreference.com/w/c/atomic/memory_order"><span class="kw912">memory_order_consume</span></a></code> <br> <span class="t-mark">(function macro)</span> </td> +</tr> </table> <h3 id="Functions"> Functions</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdatomic.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_flag_test_and_set" title="c/atomic/atomic flag test and set"> <span class="t-lines"><span>atomic_flag_test_and_set</span><span>atomic_flag_test_and_set_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> sets an atomic_flag to true and returns the old value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_flag_clear" title="c/atomic/atomic flag clear"> <span class="t-lines"><span>atomic_flag_clear</span><span>atomic_flag_clear_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> sets an atomic_flag to false <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_init" title="c/atomic/atomic init"> <span class="t-lines"><span>atomic_init</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> initializes an existing atomic object <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_is_lock_free" title="c/atomic/atomic is lock free"> <span class="t-lines"><span>atomic_is_lock_free</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> indicates whether the atomic object is lock-free <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_store" title="c/atomic/atomic store"> <span class="t-lines"><span>atomic_store</span><span>atomic_store_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> stores a value in an atomic object <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_load" title="c/atomic/atomic load"> <span class="t-lines"><span>atomic_load</span><span>atomic_load_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads a value from an atomic object <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_exchange" title="c/atomic/atomic exchange"> <span class="t-lines"><span>atomic_exchange</span><span>atomic_exchange_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> swaps a value with the value of an atomic object <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_compare_exchange" title="c/atomic/atomic compare exchange"> <span class="t-lines"><span>atomic_compare_exchange_strong</span><span>atomic_compare_exchange_strong_explicit</span><span>atomic_compare_exchange_weak</span><span>atomic_compare_exchange_weak_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> swaps a value with an atomic object if the old value is what is expected, otherwise reads the old value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_fetch_add" title="c/atomic/atomic fetch add"> <span class="t-lines"><span>atomic_fetch_add</span><span>atomic_fetch_add_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> atomic addition <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_fetch_sub" title="c/atomic/atomic fetch sub"> <span class="t-lines"><span>atomic_fetch_sub</span><span>atomic_fetch_sub_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> atomic subtraction <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_fetch_or" title="c/atomic/atomic fetch or"> <span class="t-lines"><span>atomic_fetch_or</span><span>atomic_fetch_or_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> atomic bitwise OR <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_fetch_xor" title="c/atomic/atomic fetch xor"> <span class="t-lines"><span>atomic_fetch_xor</span><span>atomic_fetch_xor_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> atomic bitwise exclusive OR <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_fetch_and" title="c/atomic/atomic fetch and"> <span class="t-lines"><span>atomic_fetch_and</span><span>atomic_fetch_and_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> atomic bitwise AND <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_thread_fence" title="c/atomic/atomic thread fence"> <span class="t-lines"><span>atomic_thread_fence</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> generic memory order-dependent fence synchronization primitive <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_signal_fence" title="c/atomic/atomic signal fence"> <span class="t-lines"><span>atomic_signal_fence</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> fence between a thread and a signal handler executed in the same thread <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <h3 id="Types_2"> Types</h3> <p>The standard library offers convenience typedefs for the <a href="language/atomic" title="c/language/atomic">core language atomic types</a>.</p> +<table class="t-dsc-begin"> <tr class="t-dsc-hitem"> <th> Typedef name </th> <th> Full type name </th> +</tr> <tr class="t-dsc"> <td> <code>atomic_bool</code> </td> <td> <code>_Atomic _Bool</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_char</code> </td> <td> <code>_Atomic char</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_schar</code> </td> <td> <code>_Atomic signed char</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uchar</code> </td> <td> <code>_Atomic unsigned char</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_short</code> </td> <td> <code>_Atomic short</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_ushort</code> </td> <td> <code>_Atomic unsigned short</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_int</code> </td> <td> <code>_Atomic int</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uint</code> </td> <td> <code>_Atomic unsigned int</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_long</code> </td> <td> <code>_Atomic long</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_ulong</code> </td> <td> <code>_Atomic unsigned long</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_llong</code> </td> <td> <code>_Atomic long long</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_ullong</code> </td> <td> <code>_Atomic unsigned long long</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_char8_t</code> <span class="t-mark-rev t-since-c23">(C23)</span> </td> <td> <code>_Atomic char8_t</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_char16_t</code> </td> <td> <code>_Atomic char16_t</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_char32_t</code> </td> <td> <code>_Atomic char32_t</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_wchar_t</code> </td> <td> <code>_Atomic wchar_t</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_int_least8_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw114">int_least8_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uint_least8_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw128">uint_least8_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_int_least16_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw115">int_least16_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uint_least16_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw129">uint_least16_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_int_least32_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw116">int_least32_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uint_least32_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw130">uint_least32_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_int_least64_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw117">int_least64_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uint_least64_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw131">uint_least64_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_int_fast8_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw110">int_fast8_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uint_fast8_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw124">uint_fast8_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_int_fast16_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw111">int_fast16_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uint_fast16_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw125">uint_fast16_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_int_fast32_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw112">int_fast32_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uint_fast32_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw126">uint_fast32_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_int_fast64_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw113">int_fast64_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uint_fast64_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw127">uint_fast64_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_intptr_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw119">intptr_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uintptr_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw133">uintptr_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_size_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_ptrdiff_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/ptrdiff_t"><span class="kw101">ptrdiff_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_intmax_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw118">intmax_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uintmax_t</code> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw132">uintmax_t</span></a></code> </td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.17 Atomics <stdatomic.h> (p: TBD) </li> +<li> 7.31.8 Atomics <stdatomic.h> (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.17 Atomics <stdatomic.h> (p: TBD) </li> +<li> 7.31.8 Atomics <stdatomic.h> (p: TBD) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.17 Atomics <stdatomic.h> (p: 273-286) </li> +<li> 7.31.8 Atomics <stdatomic.h> (p: 455-456) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic" title="cpp/atomic">C++ documentation</a></span> for <span class=""><span>Atomic operations library</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/atomic" class="_attribution-link">https://en.cppreference.com/w/c/atomic</a> + </p> +</div> diff --git a/devdocs/c/chrono%2Fasctime.html b/devdocs/c/chrono%2Fasctime.html new file mode 100644 index 00000000..436673de --- /dev/null +++ b/devdocs/c/chrono%2Fasctime.html @@ -0,0 +1,85 @@ + <h1 id="firstHeading" class="firstHeading">asctime, asctime_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><time.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-until-c23"> <td><pre data-language="c">char* asctime( const struct tm* time_ptr );</pre></td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">[[deprecated]] char* asctime( const struct tm* time_ptr );</pre> +</td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t asctime_s( char* buf, rsize_t bufsz, const struct tm* time_ptr );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <span class="t-li">1)</span> Converts given calendar time <code><a href="tm" title="c/chrono/tm">tm</a></code> to a textual representation of the following fixed 25-character form: <code>Www Mmm dd hh:mm:ss yyyy\n</code> <ul> +<li> +<code>Www</code> - three-letter English abbreviated day of the week from <code>time_ptr->tm_wday</code>, one of <code>Mon</code>, <code>Tue</code>, <code>Wed</code>, <code>Thu</code>, <code>Fri</code>, <code>Sat</code>, <code>Sun</code>. </li> +<li> +<code>Mmm</code> - three-letter English abbreviated month name from <code>time_ptr->tm_mon</code>, one of <code>Jan</code>, <code>Feb</code>, <code>Mar</code>, <code>Apr</code>, <code>May</code>, <code>Jun</code>, <code>Jul</code>, <code>Aug</code>, <code>Sep</code>, <code>Oct</code>, <code>Nov</code>, <code>Dec</code>. </li> +<li> +<code>dd</code> - 2-digit day of the month from <code>timeptr->tm_mday</code> as if printed by <code><a href="../io/fprintf" title="c/io/fprintf">sprintf</a></code> using <code>%2d</code> </li> +<li> +<code>hh</code> - 2-digit hour from <code>timeptr->tm_hour</code> as if printed by <code><a href="../io/fprintf" title="c/io/fprintf">sprintf</a></code> using <code>%.2d</code> </li> +<li> +<code>mm</code> - 2-digit minute from <code>timeptr->tm_min</code> as if printed by <code><a href="../io/fprintf" title="c/io/fprintf">sprintf</a></code> using <code>%.2d</code> </li> +<li> +<code>ss</code> - 2-digit second from <code>timeptr->tm_sec</code> as if printed by <code><a href="../io/fprintf" title="c/io/fprintf">sprintf</a></code> using <code>%.2d</code> </li> +<li> +<code>yyyy</code> - 4-digit year from <code>timeptr->tm_year + 1900</code> as if printed by <code><a href="../io/fprintf" title="c/io/fprintf">sprintf</a></code> using <code>%4d</code> +</li> +</ul> <div class="t-li1"> + The behavior is undefined if any member of <code>*time_ptr</code> is outside its normal range</div> <div class="t-li1"> + The behavior is undefined if the calendar year indicated by <code>time_ptr->tm_year</code> has more than 4 digits or is less than the year 1000.</div> <div class="t-li1"> + The function does not support localization, and the newline character cannot be removed.</div> <div class="t-li1"> + The function modifies static storage and is not thread-safe.</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> This function is deprecated and should not be used in new code. </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that the message is written into user-provided storage <code>buf</code>, which is guaranteed to be null-terminated, and the following errors are detected at runtime and call the currently installed <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> <code>buf</code> or <code>time_ptr</code> is a null pointer </li> +<li> <code>bufsz</code> is less than 26 or greater than <code>RSIZE_MAX</code> </li> +<li> not all members of <code>*time_ptr</code> are within their normal ranges </li> +<li> the year indicated by <code>time_ptr->tm_year</code> is less than 0 or greater than 9999 </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>asctime_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../chrono" title="c/chrono"><code><time.h></code></a>.</dd> +</dl> +</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> time_ptr </td> <td> - </td> <td> pointer to a <code><a href="tm" title="c/chrono/tm">tm</a></code> object specifying the time to print </td> +</tr> <tr class="t-par"> <td> buf </td> <td> - </td> <td> pointer to a user-supplied buffer at least 26 bytes in length </td> +</tr> <tr class="t-par"> <td> bufsz </td> <td> - </td> <td> size of the user-supplied buffer </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> pointer to a static null-terminated character string holding the textual representation of date and time as described above. The string may be shared between <code>asctime</code> and <code><a href="ctime" title="c/chrono/ctime">ctime</a></code>, and may be overwritten on each invocation of any of those functions.</div> <div class="t-li1"> +<span class="t-li">2)</span> zero on success, non-zero on failure, in which case <code>buf[0]</code> is set to zero (unless <code>buf</code> is a null pointer or <code>bufsz</code> is zero or greater than <code>RSIZE_MAX</code>).</div> <h3 id="Notes"> Notes</h3> <p><code>asctime</code> returns a pointer to static data and is not thread-safe. POSIX marks this function obsolete and recommends <code><a href="strftime" title="c/chrono/strftime">strftime</a></code> instead. The C standard also recommends <code><a href="strftime" title="c/chrono/strftime">strftime</a></code> instead of <code>asctime</code> and <code>asctime_s</code> because <code>strftime</code> is more flexible and locale-sensitive.</p> +<p>POSIX limits undefined behaviors only to when the output string would be longer than 25 characters, when <code>timeptr->tm_wday</code> or <code>timeptr->tm_mon</code> are not within the expected ranges, or when <code>timeptr->tm_year</code> exceeds <code>INT_MAX-1990</code>.</p> +<p>Some implementations handle <code>timeptr->tm_mday==0</code> as meaning the last day of the preceding month.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#define __STDC_WANT_LIB_EXT1__ 1 +#include <time.h> +#include <stdio.h> + +int main(void) +{ + struct tm tm = *localtime(&(time_t){time(NULL)}); + printf("%s", asctime(&tm)); + +#ifdef __STDC_LIB_EXT1__ + char str[26]; + asctime_s(str, sizeof str, &tm); + printf("%s", str); +#endif +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Tue May 26 21:51:50 2015 +Tue May 26 21:51:50 2015</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.27.2.1 The asctime function (p: 287) </li> +<li> K.3.8.2.1 The asctime_s function (p: 453-454) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.27.2.1 The asctime function (p: 392-393) </li> +<li> K.3.8.2.1 The asctime_s function (p: 624-625) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.23.3.1 The asctime function (p: 341-342) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.12.3.1 The asctime function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="ctime" title="c/chrono/ctime"> <span class="t-lines"><span>ctime</span><span>ctime_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-deprecated-c23">(deprecated in C23)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a <code><a href="time_t" title="c/chrono/time t">time_t</a></code> object to a textual representation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strftime" title="c/chrono/strftime"> <span class="t-lines"><span>strftime</span></span></a></div> </td> <td> converts a <code><a href="tm" title="c/chrono/tm">tm</a></code> object to custom textual representation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/chrono/c/asctime" title="cpp/chrono/c/asctime">C++ documentation</a></span> for <code>asctime</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/chrono/asctime" class="_attribution-link">https://en.cppreference.com/w/c/chrono/asctime</a> + </p> +</div> diff --git a/devdocs/c/chrono%2Fclock.html b/devdocs/c/chrono%2Fclock.html new file mode 100644 index 00000000..3f1ec38a --- /dev/null +++ b/devdocs/c/chrono%2Fclock.html @@ -0,0 +1,83 @@ + <h1 id="firstHeading" class="firstHeading">clock</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><time.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">clock_t clock(void);</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Returns the approximate processor time used by the process since the beginning of an implementation-defined era related to the program's execution. To convert result value to seconds, divide it by <code><a href="clocks_per_sec" title="c/chrono/CLOCKS PER SEC">CLOCKS_PER_SEC</a></code>.</p> +<p>Only the difference between two values returned by different calls to <code>clock</code> is meaningful, as the beginning of the <code>clock</code> era does not have to coincide with the start of the program. <code>clock</code> time may advance faster or slower than the wall clock, depending on the execution resources given to the program by the operating system. For example, if the CPU is shared by other processes, <code>clock</code> time may advance slower than wall clock. On the other hand, if the current process is multithreaded and more than one execution core is available, <code>clock</code> time may advance faster than wall clock.</p> +<h3 id="Parameters"> Parameters</h3> <p>(none)</p> +<h3 id="Return_value"> Return value</h3> <p>Processor time used by the program so far or <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/chrono/clock_t"><span class="kw524">clock_t</span></a><span class="br0">)</span><span class="br0">(</span><span class="sy2">-</span><span class="nu0">1</span><span class="br0">)</span></code> if that information is unavailable or its value cannot be represented.</p> +<h3 id="Notes"> Notes</h3> <p>On POSIX-compatible systems, <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_getres.html"><code>clock_gettime</code></a> with clock id <code>CLOCK_PROCESS_CPUTIME_ID</code> offers better resolution.</p> +<p>The value returned by <code>clock()</code> may wrap around on some non-conforming implementations. For example, on such an implementation, if <code><a href="clock_t" title="c/chrono/clock t">clock_t</a></code> is a signed 32-bit integer and <code><a href="clocks_per_sec" title="c/chrono/CLOCKS PER SEC">CLOCKS_PER_SEC</a></code> is 1000000, it will wrap after about 2147 seconds (about 36 minutes).</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>This example demonstrates the difference between <code>clock()</code> time and real time.</p> +<div class="c source-c"><pre data-language="c">#ifndef __STDC_NO_THREADS__ + #include <threads.h> +#else + // POSIX alternative + #define _POSIX_C_SOURCE 199309L + #include <pthread.h> +#endif + +#include <stdio.h> +#include <stdlib.h> +#include <time.h> + +// the function f() does some time-consuming work +int f(void* thr_data) // return void* in POSIX +{ + (void) thr_data; + volatile double d = 0; + for (int n = 0; n < 10000; ++n) + for (int m = 0; m < 10000; ++m) + d += d * n * m; + return 0; +} + +int main(void) +{ + struct timespec ts1, tw1; // both C11 and POSIX + clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &ts1); // POSIX + clock_gettime(CLOCK_MONOTONIC, &tw1); // POSIX; use timespec_get in C11 + clock_t t1 = clock(); + +#ifndef __STDC_NO_THREADS__ + thrd_t thr1, thr2; // C11; use pthread_t in POSIX + thrd_create(&thr1, f, NULL); // C11; use pthread_create in POSIX + thrd_create(&thr2, f, NULL); + thrd_join(thr1, NULL); // C11; use pthread_join in POSIX + thrd_join(thr2, NULL); +#endif + + struct timespec ts2, tw2; + clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &ts2); + clock_gettime(CLOCK_MONOTONIC, &tw2); + clock_t t2 = clock(); + + double dur = 1000.0 * (t2 - t1) / CLOCKS_PER_SEC; + double posix_dur = 1000.0 * ts2.tv_sec + 1e-6 * ts2.tv_nsec + - (1000.0 * ts1.tv_sec + 1e-6 * ts1.tv_nsec); + double posix_wall = 1000.0 * tw2.tv_sec + 1e-6 * tw2.tv_nsec + - (1000.0 * tw1.tv_sec + 1e-6 * tw1.tv_nsec); + + printf("CPU time used (per clock()): %.2f ms\n", dur); + printf("CPU time used (per clock_gettime()): %.2f ms\n", posix_dur); + printf("Wall time passed: %.2f ms\n", posix_wall); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">CPU time used (per clock()): 1580.00 ms +CPU time used (per clock_gettime()): 1582.76 ms +Wall time passed: 792.13 ms</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.27.2.1 The clock function (p: 285) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.27.2.1 The clock function (p: 389) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.23.2.1 The clock function (p: 339) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.12.2.1 The clock function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="ctime" title="c/chrono/ctime"> <span class="t-lines"><span>ctime</span><span>ctime_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-deprecated-c23">(deprecated in C23)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a <code><a href="time_t" title="c/chrono/time t">time_t</a></code> object to a textual representation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="time" title="c/chrono/time"> <span class="t-lines"><span>time</span></span></a></div> </td> <td> returns the current calendar time of the system as time since epoch <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/chrono/c/clock" title="cpp/chrono/c/clock">C++ documentation</a></span> for <code>clock</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/chrono/clock" class="_attribution-link">https://en.cppreference.com/w/c/chrono/clock</a> + </p> +</div> diff --git a/devdocs/c/chrono%2Fclock_t.html b/devdocs/c/chrono%2Fclock_t.html new file mode 100644 index 00000000..5946393a --- /dev/null +++ b/devdocs/c/chrono%2Fclock_t.html @@ -0,0 +1,37 @@ + <h1 id="firstHeading" class="firstHeading">clock_t</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><time.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">typedef /* unspecified */ clock_t;</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p><span class="t-rev-inl t-until-c11"><span>Arithmetic</span><span><span class="t-mark-rev t-until-c11">(until C11)</span></span></span><span class="t-rev-inl t-since-c11"><span>Real</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> type capable of representing the processor time used by a process. It has implementation-defined range and precision.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <time.h> +#include <math.h> + +volatile double sink; +int main (void) +{ + clock_t start = clock(); + + for(size_t i=0; i<3141592; ++i) + sink+=sin(i); + + clock_t end = clock(); + double cpu_time_used = ((double) (end - start)) / CLOCKS_PER_SEC; + + printf("for loop took %f seconds to execute \n", cpu_time_used); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">for loop took 0.271828 seconds to execute</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.27.1/3 Components of time (p: 284) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.27.1/3 Components of time (p: 388) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.23.1/3 Components of time (p: 338) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.12.1 Components of time </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="clock" title="c/chrono/clock"> <span class="t-lines"><span>clock</span></span></a></div> </td> <td> returns raw processor clock time since the program is started <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="clocks_per_sec" title="c/chrono/CLOCKS PER SEC"> <span class="t-lines"><span>CLOCKS_PER_SEC</span></span></a></div> </td> <td> number of processor clock ticks per second <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/chrono/c/clock_t" title="cpp/chrono/c/clock t">C++ documentation</a></span> for <code>clock_t</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/chrono/clock_t" class="_attribution-link">https://en.cppreference.com/w/c/chrono/clock_t</a> + </p> +</div> diff --git a/devdocs/c/chrono%2Fclocks_per_sec.html b/devdocs/c/chrono%2Fclocks_per_sec.html new file mode 100644 index 00000000..a162b3ea --- /dev/null +++ b/devdocs/c/chrono%2Fclocks_per_sec.html @@ -0,0 +1,24 @@ + <h1 id="firstHeading" class="firstHeading">CLOCKS_PER_SEC</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><time.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define CLOCKS_PER_SEC /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Expands to an expression (not necessarily a compile-time constant) of type <code><a href="clock_t" title="c/chrono/clock t">clock_t</a></code> equal to the number of clock ticks per second, as returned by <code><a href="clock" title="c/chrono/clock">clock()</a></code>.</p> +<h3 id="Notes"> Notes</h3> <p>POSIX defines <code>CLOCKS_PER_SEC</code> as one million, regardless of the actual precision of <code><a href="clock" title="c/chrono/clock">clock</a></code>.</p> +<p>Until standardized as <code>CLOCKS_PER_SEC</code> in C89, this macro was sometimes known by its IEEE std 1003.1-1988 name <code>CLK_TCK</code>: that name was not included in C89 and was removed from POSIX itself in 1996 over ambiguity with <code>_SC_CLK_TCK</code>, which gives number of clocks per second for the function <a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/times.html"><code>times()</code></a>).</p> +<h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.27.1/2 Components of time (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.27.1/2 Components of time (p: 284) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.27.1/2 Components of time (p: 388) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.23.1/2 Components of time (p: 338) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.12.1 Components of time </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="clock" title="c/chrono/clock"> <span class="t-lines"><span>clock</span></span></a></div> </td> <td> returns raw processor clock time since the program is started <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="clock_t" title="c/chrono/clock t"> <span class="t-lines"><span>clock_t</span></span></a></div> </td> <td> processor time since era type <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/chrono/c/CLOCKS_PER_SEC" title="cpp/chrono/c/CLOCKS PER SEC">C++ documentation</a></span> for <code>CLOCKS_PER_SEC</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/chrono/CLOCKS_PER_SEC" class="_attribution-link">https://en.cppreference.com/w/c/chrono/CLOCKS_PER_SEC</a> + </p> +</div> diff --git a/devdocs/c/chrono%2Fctime.html b/devdocs/c/chrono%2Fctime.html new file mode 100644 index 00000000..f68df0e7 --- /dev/null +++ b/devdocs/c/chrono%2Fctime.html @@ -0,0 +1,79 @@ + <h1 id="firstHeading" class="firstHeading">ctime, ctime_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><time.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-until-c23"> <td><pre data-language="c">char* ctime( const time_t* timer );</pre></td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">[[deprecated]] char* ctime( const time_t* timer );</pre> +</td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t ctime_s( char *buf, rsize_t bufsz, const time_t* timer );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Converts given time since epoch to a calendar local time and then to a textual representation, as if by calling <code><a href="http://en.cppreference.com/w/c/chrono/asctime"><span class="kw515">asctime</span></a><span class="br0">(</span><a href="http://en.cppreference.com/w/c/chrono/localtime"><span class="kw519">localtime</span></a><span class="br0">(</span>timer<span class="br0">)</span><span class="br0">)</span></code><span class="t-rev-inl t-since-c23"><span> or <code><a href="http://en.cppreference.com/w/c/chrono/asctime"><span class="kw515">asctime</span></a><span class="br0">(</span>localtime_r<span class="br0">(</span>timer, <span class="sy3">&</span><span class="br0">(</span><span class="kw1">struct</span> <a href="http://en.cppreference.com/w/c/chrono/tm"><span class="kw522">tm</span></a><span class="br0">)</span><span class="br0">{</span><span class="nu0">0</span><span class="br0">}</span><span class="br0">)</span><span class="br0">)</span></code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>. <span class="t-rev-inl t-since-c23"><span>This function is deprecated and should not be used in new code.</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> +</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that the function is equivalent to <code>asctime_s<span class="br0">(</span>buf, bufsz, localtime_s<span class="br0">(</span>timer, <span class="sy3">&</span><span class="br0">(</span><span class="kw1">struct</span> <a href="http://en.cppreference.com/w/c/chrono/tm"><span class="kw522">tm</span></a><span class="br0">)</span><span class="br0">{</span><span class="nu0">0</span><span class="br0">}</span><span class="br0">)</span><span class="br0">)</span></code>, and the following errors are detected at runtime and call the currently installed <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> <code>buf</code> or <code>timer</code> is a null pointer </li> +<li> <code>bufsz</code> is less than <code>26</code> or greater than <code>RSIZE_MAX</code> </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>ctime_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../chrono" title="c/chrono"><code><time.h></code></a>.</dd> +</dl> +</div> <p>The resulting string has the following format:</p> +<div class="c source-c"><pre data-language="c">Www Mmm dd hh:mm:ss yyyy\n</pre></div> <ul> +<li> +<code>Www</code> - the day of the week (one of <code>Mon</code>, <code>Tue</code>, <code>Wed</code>, <code>Thu</code>, <code>Fri</code>, <code>Sat</code>, <code>Sun</code>). </li> +<li> +<code>Mmm</code> - the month (one of <code>Jan</code>, <code>Feb</code>, <code>Mar</code>, <code>Apr</code>, <code>May</code>, <code>Jun</code>, <code>Jul</code>, <code>Aug</code>, <code>Sep</code>, <code>Oct</code>, <code>Nov</code>, <code>Dec</code>). </li> +<li> +<code>dd</code> - the day of the month </li> +<li> +<code>hh</code> - hours </li> +<li> +<code>mm</code> - minutes </li> +<li> +<code>ss</code> - seconds </li> +<li> +<code>yyyy</code> - years </li> +</ul> <p>The function does not support localization.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> timer </td> <td> - </td> <td> pointer to a <code><a href="time_t" title="c/chrono/time t">time_t</a></code> object specifying the time to print </td> +</tr> <tr class="t-par"> <td> buf </td> <td> - </td> <td> pointer to the first element of a char array of size at least <code>bufsz</code> </td> +</tr> <tr class="t-par"> <td> bufsz </td> <td> - </td> <td> max number of bytes to output, typically the size of the buffer pointed to by <code>buf</code> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> pointer to a static null-terminated character string holding the textual representation of date and time. The string may be shared between <code><a href="asctime" title="c/chrono/asctime">asctime</a></code> and <code>ctime</code>, and may be overwritten on each invocation of any of those functions.</div> <div class="t-li1"> +<span class="t-li">2)</span> zero on success (in which case the string representation of time has been written out to the array pointed to by <code>buf</code>), or non-zero on failure (in which case, the terminating null character is always written to <code>buf[0]</code> unless <code>buf</code> is a null pointer or <code>bufsz</code> is zero or greater than <code>RSIZE_MAX</code>.</div> <h3 id="Notes"> Notes</h3> <p><code>ctime</code> returns a pointer to static data and is not thread-safe. In addition, it modifies the static <code><a href="tm" title="c/chrono/tm">tm</a></code> object which may be shared with <code><a href="gmtime" title="c/chrono/gmtime">gmtime</a></code> and <code><a href="localtime" title="c/chrono/localtime">localtime</a></code>. POSIX marks this function obsolete and recommends <code><a href="strftime" title="c/chrono/strftime">strftime</a></code> instead. The C standard also recommends <code><a href="strftime" title="c/chrono/strftime">strftime</a></code> instead of <code>ctime</code> and <code>ctime_s</code> because <code>strftime</code> is more flexible and locale-sensitive.</p> +<p>The behavior of <code>ctime</code> is undefined for the values of <code><a href="time_t" title="c/chrono/time t">time_t</a></code> that result in the string longer than 25 characters (e.g. year 10000).</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#define __STDC_WANT_LIB_EXT1__ 1 +#include <time.h> +#include <stdio.h> + +int main(void) +{ + time_t result = time(NULL); + printf("%s", ctime(&result)); + +#ifdef __STDC_LIB_EXT1__ + char str[26]; + ctime_s(str,sizeof str,&result); + printf("%s", str); +#endif +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Tue May 26 21:51:03 2015 +Tue May 26 21:51:03 2015</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.27.3.2 The ctime function (p: 287-288) </li> +<li> K.3.8.2.2 The ctime_s function (p: 454) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.27.3.2 The ctime function (p: 393) </li> +<li> K.3.8.2.2 The ctime_s function (p: 626) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.23.3.2 The ctime function (p: 342) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.12.3.2 The ctime function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="asctime" title="c/chrono/asctime"> <span class="t-lines"><span>asctime</span><span>asctime_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-deprecated-c23">(deprecated in C23)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a <code><a href="tm" title="c/chrono/tm">tm</a></code> object to a textual representation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strftime" title="c/chrono/strftime"> <span class="t-lines"><span>strftime</span></span></a></div> </td> <td> converts a <code><a href="tm" title="c/chrono/tm">tm</a></code> object to custom textual representation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/chrono/c/ctime" title="cpp/chrono/c/ctime">C++ documentation</a></span> for <code>ctime</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/chrono/ctime" class="_attribution-link">https://en.cppreference.com/w/c/chrono/ctime</a> + </p> +</div> diff --git a/devdocs/c/chrono%2Fdifftime.html b/devdocs/c/chrono%2Fdifftime.html new file mode 100644 index 00000000..d72402bb --- /dev/null +++ b/devdocs/c/chrono%2Fdifftime.html @@ -0,0 +1,45 @@ + <h1 id="firstHeading" class="firstHeading">difftime</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><time.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">double difftime( time_t time_end, time_t time_beg );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Computes difference between two calendar times as <code><a href="time_t" title="c/chrono/time t">time_t</a></code> objects (<code>time_end - time_beg</code>) in seconds. If <code>time_end</code> refers to time point before <code>time_beg</code> then the result is negative.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> time_beg, time_end </td> <td> - </td> <td> times to compare </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Difference between two times in seconds.</p> +<h3 id="Notes"> Notes</h3> <p>On POSIX systems, <code><a href="time_t" title="c/chrono/time t">time_t</a></code> is measured in seconds, and <code>difftime</code> is equivalent to arithmetic subtraction, but C and C++ allow fractional units for <code><a href="time_t" title="c/chrono/time t">time_t</a></code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>The following program computes the number of seconds that have passed since the beginning of the month.</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <time.h> + +int main(void) +{ + time_t now = time(0); + + struct tm beg = *localtime(&now); + + // set beg to the beginning of the month + beg.tm_hour = 0, + beg.tm_min = 0, + beg.tm_sec = 0, + beg.tm_mday = 1; + + double seconds = difftime(now, mktime(&beg)); + + printf("%.f seconds have passed since the beginning of the month.\n", seconds); + + return 0; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">1937968 seconds have passed since the beginning of the month.</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.27.2.2 The difftime function (p: 285) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.27.2.2 The difftime function (p: 390) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.23.2.2 The difftime function (p: 338) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 7.12.2.2 The difftime function (p: 171) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/chrono/c/difftime" title="cpp/chrono/c/difftime">C++ documentation</a></span> for <code>difftime</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/chrono/difftime" class="_attribution-link">https://en.cppreference.com/w/c/chrono/difftime</a> + </p> +</div> diff --git a/devdocs/c/chrono%2Fgmtime.html b/devdocs/c/chrono%2Fgmtime.html new file mode 100644 index 00000000..7aaae09c --- /dev/null +++ b/devdocs/c/chrono%2Fgmtime.html @@ -0,0 +1,71 @@ + <h1 id="firstHeading" class="firstHeading">gmtime, gmtime_r, gmtime_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><time.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">struct tm *gmtime ( const time_t *timer );</pre> +</td> <td> (1) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">struct tm *gmtime_r( const time_t *timer, struct tm *buf );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">struct tm *gmtime_s( const time_t *restrict timer, struct tm *restrict buf );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Converts given time since epoch (a <code><a href="time_t" title="c/chrono/time t">time_t</a></code> value pointed to by <code>timer</code>) into calendar time, expressed in Coordinated Universal Time (UTC) in the <a href="tm" title="c/chrono/tm"><code>struct tm</code></a> format. The result is stored in static storage and a pointer to that static storage is returned.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that the function uses user-provided storage <code>buf</code> for the result.</div> <div class="t-li1"> +<span class="t-li">3)</span> Same as <span class="t-v">(1)</span>, except that the function uses user-provided storage <code>buf</code> for the result and that the following errors are detected at runtime and call the currently installed <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul><li> <code>timer</code> or <code>buf</code> is a null pointer </li></ul> </dd> +<dd>As with all bounds-checked functions, <code>gmtime_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../chrono" title="c/chrono"><code><time.h></code></a>.</dd> +</dl> +</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> timer </td> <td> - </td> <td> pointer to a <code><a href="time_t" title="c/chrono/time t">time_t</a></code> object to convert </td> +</tr> <tr class="t-par"> <td> buf </td> <td> - </td> <td> pointer to a <code><span class="kw1">struct</span> <a href="http://en.cppreference.com/w/c/chrono/tm"><span class="kw522">tm</span></a></code> object to store the result </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> pointer to a static internal <code><a href="tm" title="c/chrono/tm">tm</a></code> object on success, or null pointer otherwise. The structure may be shared between <code>gmtime</code>, <code><a href="localtime" title="c/chrono/localtime">localtime</a></code>, and <code><a href="ctime" title="c/chrono/ctime">ctime</a></code> and may be overwritten on each invocation.</div> <div class="t-li1"> +<span class="t-li">2-3)</span> copy of the <code>buf</code> pointer, or null pointer on error (which may be a runtime constraint violation or a failure to convert the specified time to UTC)</div> <h3 id="Notes"> Notes</h3> <p><code>gmtime</code> may not be thread-safe.</p> +<p>POSIX requires that <code>gmtime</code> and <code>gmtime_r</code> set <code><a href="../error/errno" title="c/error/errno">errno</a></code> to <code><a href="../error/errno_macros" title="c/error/errno macros">EOVERFLOW</a></code> if they fail because the argument is too large.</p> +<p>The implementation of <code>gmtime_s</code> in <a rel="nofollow" class="external text" href="https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/gmtime-s-gmtime32-s-gmtime64-s?view=vs-2019">Microsoft CRT</a> is incompatible with the C standard since it has reversed parameter order.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#define __STDC_WANT_LIB_EXT1__ 1 +#define _XOPEN_SOURCE // for putenv +#include <time.h> +#include <stdio.h> +#include <stdlib.h> // for putenv + +int main(void) +{ + time_t t = time(NULL); + printf("UTC: %s", asctime(gmtime(&t))); + printf("local: %s", asctime(localtime(&t))); + // POSIX-specific + putenv("TZ=Asia/Singapore"); + printf("Singapore: %s", asctime(localtime(&t))); + +#ifdef __STDC_LIB_EXT1__ + struct tm buf; + char str[26]; + asctime_s(str,sizeof str,gmtime_s(&t, &buf)); + printf("UTC: %s", str); + asctime_s(str,sizeof str,localtime_s(&t, &buf)); + printf("local: %s", str); +#endif +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">UTC: Fri Sep 15 14:22:05 2017 +local: Fri Sep 15 14:22:05 2017 +Singapore: Fri Sep 15 22:22:05 2017 +UTC: Fri Sep 15 14:22:05 2017 +local: Fri Sep 15 14:22:05 2017</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.27.3.3 The gmtime function (p: 288) </li> +<li> K.3.8.2.3 The gmtime_s function (p: 454-455) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.27.3.3 The gmtime function (p: 393-394) </li> +<li> K.3.8.2.3 The gmtime_s function (p: 626-627) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.23.3.3 The gmtime function (p: 343) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.12.3.3 The gmtime function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="localtime" title="c/chrono/localtime"> <span class="t-lines"><span>localtime</span><span>localtime_r</span><span>localtime_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts time since epoch to calendar time expressed as local time <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/chrono/c/gmtime" title="cpp/chrono/c/gmtime">C++ documentation</a></span> for <code>gmtime</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/chrono/gmtime" class="_attribution-link">https://en.cppreference.com/w/c/chrono/gmtime</a> + </p> +</div> diff --git a/devdocs/c/chrono%2Flocaltime.html b/devdocs/c/chrono%2Flocaltime.html new file mode 100644 index 00000000..75756995 --- /dev/null +++ b/devdocs/c/chrono%2Flocaltime.html @@ -0,0 +1,72 @@ + <h1 id="firstHeading" class="firstHeading">localtime, localtime_r, localtime_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><time.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">struct tm *localtime ( const time_t *timer );</pre> +</td> <td> (1) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">struct tm *localtime_r( const time_t *timer, struct tm *buf );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">struct tm *localtime_s( const time_t *restrict timer, struct tm *restrict buf );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Converts given time since epoch (a <code><a href="time_t" title="c/chrono/time t">time_t</a></code> value pointed to by <code>timer</code>) into calendar time, expressed in local time, in the <a href="tm" title="c/chrono/tm"><code>struct tm</code></a> format. The result is stored in static storage and a pointer to that static storage is returned.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that the function uses user-provided storage <code>buf</code> for the result.</div> <div class="t-li1"> +<span class="t-li">3)</span> Same as <span class="t-v">(1)</span>, except that the function uses user-provided storage <code>buf</code> for the result and that the following errors are detected at runtime and call the currently installed <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul><li> <code>timer</code> or <code>buf</code> is a null pointer </li></ul> </dd> +<dd>As with all bounds-checked functions, <code>localtime_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../chrono" title="c/chrono"><code><time.h></code></a>.</dd> +</dl> +</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> timer </td> <td> - </td> <td> pointer to a <code><a href="time_t" title="c/chrono/time t">time_t</a></code> object to convert </td> +</tr> <tr class="t-par"> <td> buf </td> <td> - </td> <td> pointer to a <code><span class="kw1">struct</span> <a href="http://en.cppreference.com/w/c/chrono/tm"><span class="kw522">tm</span></a></code> object to store the result </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> pointer to a static internal <code><a href="tm" title="c/chrono/tm">tm</a></code> object on success, or null pointer otherwise. The structure may be shared between <code><a href="gmtime" title="c/chrono/gmtime">gmtime</a></code>, <code>localtime</code>, and <code><a href="ctime" title="c/chrono/ctime">ctime</a></code> and may be overwritten on each invocation.</div> <div class="t-li1"> +<span class="t-li">2-3)</span> copy of the <code>buf</code> pointer, or null pointer on error (which may be a runtime constraint violation or a failure to convert the specified time to local calendar time)</div> <h3 id="Notes"> Notes</h3> <p>The function <code>localtime</code> may not be thread-safe.</p> +<p>POSIX requires that <code>localtime</code> and <code>localtime_r</code> set <code><a href="../error/errno" title="c/error/errno">errno</a></code> to <code><a href="../error/errno_macros" title="c/error/errno macros">EOVERFLOW</a></code> if it fails because the argument is too large.</p> +<p><a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/localtime.html">POSIX specifies</a> that the timezone information is determined by <code>localtime</code> and <code>localtime_r</code> as if by calling <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/tzset.html"><code>tzset</code></a>, which reads the environment variable <code>TZ</code>.</p> +<p>The implementation of <code>localtime_s</code> in <a rel="nofollow" class="external text" href="https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/localtime-s-localtime32-s-localtime64-s?view=vs-2019">Microsoft CRT</a> is incompatible with the C standard since it has reversed parameter order and returns <code>errno_t</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#define __STDC_WANT_LIB_EXT1__ 1 +#define _XOPEN_SOURCE // for putenv +#include <time.h> +#include <stdio.h> +#include <stdlib.h> // for putenv + +int main(void) +{ + time_t t = time(NULL); + printf("UTC: %s", asctime(gmtime(&t))); + printf("local: %s", asctime(localtime(&t))); + // POSIX-specific + putenv("TZ=Asia/Singapore"); + printf("Singapore: %s", asctime(localtime(&t))); + +#ifdef __STDC_LIB_EXT1__ + struct tm buf; + char str[26]; + asctime_s(str,sizeof str,gmtime_s(&t, &buf)); + printf("UTC: %s", str); + asctime_s(str,sizeof str,localtime_s(&t, &buf)); + printf("local: %s", str); +#endif +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">UTC: Fri Sep 15 14:22:05 2017 +local: Fri Sep 15 14:22:05 2017 +Singapore: Fri Sep 15 22:22:05 2017 +UTC: Fri Sep 15 14:22:05 2017 +local: Fri Sep 15 14:22:05 2017</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.27.3.4 The localtime function (p: 288) </li> +<li> K.3.8.2.4 The localtime_s function (p: 455) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.27.3.4 The localtime function (p: 394) </li> +<li> K.3.8.2.4 The localtime_s function (p: 627) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.23.3.4 The localtime function (p: 343) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.12.3.4 The localtime function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="gmtime" title="c/chrono/gmtime"> <span class="t-lines"><span>gmtime</span><span>gmtime_r</span><span>gmtime_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts time since epoch to calendar time expressed as Coordinated Universal Time (UTC) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/chrono/c/localtime" title="cpp/chrono/c/localtime">C++ documentation</a></span> for <code>localtime</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/chrono/localtime" class="_attribution-link">https://en.cppreference.com/w/c/chrono/localtime</a> + </p> +</div> diff --git a/devdocs/c/chrono%2Fmktime.html b/devdocs/c/chrono%2Fmktime.html new file mode 100644 index 00000000..d4a34bc9 --- /dev/null +++ b/devdocs/c/chrono%2Fmktime.html @@ -0,0 +1,46 @@ + <h1 id="firstHeading" class="firstHeading">mktime</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><time.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">time_t mktime( struct tm *arg );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Renormalizes local calendar time expressed as a <code><a href="tm" title="c/chrono/tm">struct tm</a></code> object and also converts it to time since epoch as a <code><a href="time_t" title="c/chrono/time t">time_t</a></code> object. <code>arg->tm_wday</code> and <code>arg->tm_yday</code> are ignored. The values in <code>arg</code> are not checked for being out of range.</p> +<p>A negative value of <code>arg->tm_isdst</code> causes <code>mktime</code> to attempt to determine if Daylight Saving Time was in effect in the specified time.</p> +<p>If the conversion to <code>time_t</code> is successful, the <code>arg</code> object is modified. All fields of <code>arg</code> are updated to fit their proper ranges. <code>arg->tm_wday</code> and <code>arg->tm_yday</code> are recalculated using information available in other fields.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> pointer to a <code><a href="tm" title="c/chrono/tm">tm</a></code> object specifying local calendar time to convert </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>time since epoch as a <code><a href="time_t" title="c/chrono/time t">time_t</a></code> object on success, or <code>-1</code> if <code>arg</code> cannot be represented as a <code><a href="time_t" title="c/chrono/time t">time_t</a></code> object (POSIX also requires <code>EOVERFLOW</code> to be stored in <code><a href="../error/errno" title="c/error/errno">errno</a></code> in this case).</p> +<h3 id="Notes"> Notes</h3> <p>If the <code><span class="kw1">struct</span> <a href="http://en.cppreference.com/w/c/chrono/tm"><span class="kw522">tm</span></a></code> object was obtained from POSIX <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/009695399/functions/strptime.html"><code>strptime</code></a> or equivalent function, the value of <code>tm_isdst</code> is indeterminate, and needs to be set explicitly before calling <code>mktime</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#define _POSIX_C_SOURCE 200112L // for setenv on gcc +#include <stdlib.h> +#include <stdio.h> +#include <time.h> + +int main(void) +{ + setenv("TZ", "/usr/share/zoneinfo/America/New_York", 1); // POSIX-specific + + struct tm tm = *localtime(&(time_t){time(NULL)}); + printf("Today is %s", asctime(&tm)); + printf("(DST is %s)\n", tm.tm_isdst ? "in effect" : "not in effect"); + tm.tm_mon -= 100; // tm_mon is now outside its normal range + mktime(&tm); // tm_isdst is not set to -1; today's DST status is used + printf("100 months ago was %s", asctime(&tm)); + printf("(DST was %s)\n", tm.tm_isdst ? "in effect" : "not in effect"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Today is Fri Apr 22 11:53:36 2016 +(DST is in effect) +100 months ago was Sat Dec 22 10:53:36 2007 +(DST was not in effect)</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.27.2.3 The mktime function (p: 285-286) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.27.2.3 The mktime function (p: 390-391) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.23.2.3 The mktime function (p: 340-341) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.12.2.3 The mktime function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="localtime" title="c/chrono/localtime"> <span class="t-lines"><span>localtime</span><span>localtime_r</span><span>localtime_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts time since epoch to calendar time expressed as local time <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/chrono/c/mktime" title="cpp/chrono/c/mktime">C++ documentation</a></span> for <code>mktime</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/chrono/mktime" class="_attribution-link">https://en.cppreference.com/w/c/chrono/mktime</a> + </p> +</div> diff --git a/devdocs/c/chrono%2Fstrftime.html b/devdocs/c/chrono%2Fstrftime.html new file mode 100644 index 00000000..8cef9684 --- /dev/null +++ b/devdocs/c/chrono%2Fstrftime.html @@ -0,0 +1,146 @@ + <h1 id="firstHeading" class="firstHeading">strftime</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><time.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">size_t strftime( char* str, size_t count, + const char* format, const struct tm* tp );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">size_t strftime( char* restrict str, size_t count, + const char* restrict format, const struct tm* restrict tp );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Converts the date and time information from a given calendar time <code>tp</code> to a null-terminated multibyte character string <code>str</code> according to <a href="#Format_string">format string</a> <code>format</code>. Up to <code>count</code> bytes are written.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> pointer to the first element of the char array for output </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> maximum number of bytes to write </td> +</tr> <tr class="t-par"> <td> format </td> <td> - </td> <td> pointer to a null-terminated multibyte character string specifying the <a href="#Format_string">format of conversion</a> </td> +</tr> <tr class="t-par"> <td> tp </td> <td> - </td> <td> pointer to a <code><span class="kw1">struct</span> <a href="http://en.cppreference.com/w/c/chrono/tm"><span class="kw522">tm</span></a></code> object specifying the time to format </td> +</tr> +</table> <h3 id="Format_string"> Format string</h3> <p>The format string consists of zero or more conversion specifiers and ordinary characters (except <code>%</code>). All ordinary characters, including the terminating null character, are copied to the output string without modification. Each conversion specification begins with <code>%</code> character, optionally followed by <code>E</code> or <code>O</code> modifier (ignored if unsupported by the locale), followed by the character that determines the behavior of the specifier. The following format specifiers are available:</p> +<table class="wikitable"> <tr> <th> Conversion<br> specifier </th> <th> Explanation </th> <th> Used fields </th> +</tr> <tr> <th> <code>%</code> </th> <td> writes literal <code>%</code>. The full conversion specification must be <code>%%</code>. </td> <td> </td> +</tr> <tr> <th> <code>n</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes newline character </td> <td> </td> +</tr> <tr> <th> <code>t</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes horizontal tab character </td> <td> </td> +</tr> <tr> <th colspan="3"> Year </th> +</tr> <tr> <th> <code>Y</code> </th> <td> writes <b>year</b> as a decimal number, e.g. 2017 </td> <td> <code>tm_year</code> </td> +</tr> <tr> <th> <code>EY</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>year</b> in the alternative representation, e.g.平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale </td> <td> <code>tm_year</code> </td> +</tr> <tr> <th> <code>y</code> </th> <td> writes last 2 digits of <b>year</b> as a decimal number (range <code>[00,99]</code>) </td> <td> <code>tm_year</code> </td> +</tr> <tr> <th> <code>Oy</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes last 2 digits of <b>year</b> using the alternative numeric system, e.g. 十一 instead of 11 in ja_JP locale </td> <td> <code>tm_year</code> </td> +</tr> <tr> <th> <code>Ey</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>year</b> as offset from locale's alternative calendar period <code>%EC</code> (locale-dependent) </td> <td> <code>tm_year</code> </td> +</tr> <tr> <th> <code>C</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes first 2 digits of <b>year</b> as a decimal number (range <code>[00,99]</code>) </td> <td> <code>tm_year</code> </td> +</tr> <tr> <th> <code>EC</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes name of the <b>base year (period)</b> in the locale's alternative representation, e.g. 平成 (Heisei era) in ja_JP </td> <td> <code>tm_year</code> </td> +</tr> <tr> <th> <code>G</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>ISO 8601 week-based year</b>, i.e. the year that contains the specified week. <p>In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the following requirements:</p> +<ul> +<li> Includes January 4 </li> +<li> Includes first Thursday of the year </li> +</ul> </td> <td> <code>tm_year</code>, <code>tm_wday</code>, <code>tm_yday</code> </td> +</tr> <tr> <th> <code>g</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes last 2 digits of <b>ISO 8601 week-based year</b>, i.e. the year that contains the specified week (range <code>[00,99]</code>). <p>In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the following requirements:</p> +<ul> +<li> Includes January 4 </li> +<li> Includes first Thursday of the year </li> +</ul> </td> <td> <code>tm_year</code>, <code>tm_wday</code>, <code>tm_yday</code> </td> +</tr> <tr> <th colspan="3"> Month </th> +</tr> <tr> <th> <code>b</code> </th> <td> writes <b>abbreviated month</b> name, e.g. <code>Oct</code> (locale dependent) </td> <td> <code>tm_mon</code> </td> +</tr> <tr> <th> <code>Ob</code><br><span class="t-mark-rev t-since-c23">(C23)</span> </th> <td> writes <b>abbreviated month</b> name in the locale's alternative representation </td> <td> <code>tm_mon</code> </td> +</tr> <tr> <th> <code>h</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> synonym of <code>b</code> </td> <td> <code>tm_mon</code> </td> +</tr> <tr> <th> <code>B</code> </th> <td> writes <b>full month</b> name, e.g. <code>October</code> (locale dependent) </td> <td> <code>tm_mon</code> </td> +</tr> <tr> <th> <code>OB</code><br><span class="t-mark-rev t-since-c23">(C23)</span> </th> <td> writes appropriate <b>full month</b> name in the locale's alternative representation </td> <td> <code>tm_mon</code> </td> +</tr> <tr> <th> <code>m</code> </th> <td> writes <b>month</b> as a decimal number (range <code>[01,12]</code>) </td> <td> <code>tm_mon</code> </td> +</tr> <tr> <th> <code>Om</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>month</b> using the alternative numeric system, e.g. 十二 instead of 12 in ja_JP locale </td> <td> <code>tm_mon</code> </td> +</tr> <tr> <th colspan="3"> Week </th> +</tr> <tr> <th> <code>U</code> </th> <td> writes <b>week of the year</b> as a decimal number (Sunday is the first day of the week) (range <code>[00,53]</code>) </td> <td> <code>tm_year</code>, <code>tm_wday</code>, <code>tm_yday</code> </td> +</tr> <tr> <th> <code>OU</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>week of the year</b>, as by <code>%U</code>, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale </td> <td> <code>tm_year</code>, <code>tm_wday</code>, <code>tm_yday</code> </td> +</tr> <tr> <th> <code>W</code> </th> <td> writes <b>week of the year</b> as a decimal number (Monday is the first day of the week) (range <code>[00,53]</code>) </td> <td> <code>tm_year</code>, <code>tm_wday</code>, <code>tm_yday</code> </td> +</tr> <tr> <th> <code>OW</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>week of the year</b>, as by <code>%W</code>, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale </td> <td> <code>tm_year</code>, <code>tm_wday</code>, <code>tm_yday</code> </td> +</tr> <tr> <th> <code>V</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>ISO 8601 week of the year</b> (range <code>[01,53]</code>). <p>In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the following requirements:</p> +<ul> +<li> Includes January 4 </li> +<li> Includes first Thursday of the year </li> +</ul> </td> <td> <code>tm_year</code>, <code>tm_wday</code>, <code>tm_yday</code> </td> +</tr> <tr> <th> <code>OV</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>week of the year</b>, as by <code>%V</code>, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale </td> <td> <code>tm_year</code>, <code>tm_wday</code>, <code>tm_yday</code> </td> +</tr> <tr> <th colspan="3"> Day of the year/month </th> +</tr> <tr> <th> <code>j</code> </th> <td> writes <b>day of the year</b> as a decimal number (range <code>[001,366]</code>) </td> <td> <code>tm_yday</code> </td> +</tr> <tr> <th> <code>d</code> </th> <td> writes <b>day of the month</b> as a decimal number (range <code>[01,31]</code>) </td> <td> <code>tm_mday</code> </td> +</tr> <tr> <th> <code>Od</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes zero-based <b>day of the month</b> using the alternative numeric system, e.g. 二十七 instead of 27 in ja_JP locale <p>Single character is preceded by a space.</p> +</td> <td> <code>tm_mday</code> </td> +</tr> <tr> <th> <code>e</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>day of the month</b> as a decimal number (range <code>[1,31]</code>). <p>Single digit is preceded by a space.</p> +</td> <td> <code>tm_mday</code> </td> +</tr> <tr> <th> <code>Oe</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes one-based <b>day of the month</b> using the alternative numeric system, e.g. 二十七 instead of 27 in ja_JP locale <p>Single character is preceded by a space.</p> +</td> <td> <code>tm_mday</code> </td> +</tr> <tr> <th colspan="3"> Day of the week </th> +</tr> <tr> <th> <code>a</code> </th> <td> writes <b>abbreviated weekday</b> name, e.g. <code>Fri</code> (locale dependent) </td> <td> <code>tm_wday</code> </td> +</tr> <tr> <th> <code>A</code> </th> <td> writes <b>full weekday</b> name, e.g. <code>Friday</code> (locale dependent) </td> <td> <code>tm_wday</code> </td> +</tr> <tr> <th> <code>w</code> </th> <td> writes <b>weekday</b> as a decimal number, where Sunday is <code>0</code> (range <code>[0-6]</code>) </td> <td> <code>tm_wday</code> </td> +</tr> <tr> <th> <code>Ow</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>weekday</b>, where Sunday is <code>0</code>, using the alternative numeric system, e.g. 二 instead of 2 in ja_JP locale </td> <td> <code>tm_wday</code> </td> +</tr> <tr> <th> <code>u</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>weekday</b> as a decimal number, where Monday is <code>1</code> (ISO 8601 format) (range <code>[1-7]</code>) </td> <td> <code>tm_wday</code> </td> +</tr> <tr> <th> <code>Ou</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>weekday</b>, where Monday is <code>1</code>, using the alternative numeric system, e.g. 二 instead of 2 in ja_JP locale </td> <td> <code>tm_wday</code> </td> +</tr> <tr> <th colspan="3"> Hour, minute, second </th> +</tr> <tr> <th> <code>H</code> </th> <td> writes <b>hour</b> as a decimal number, 24 hour clock (range <code>[00-23]</code>) </td> <td> <code>tm_hour</code> </td> +</tr> <tr> <th> <code>OH</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>hour</b> from 24-hour clock using the alternative numeric system, e.g. 十八 instead of 18 in ja_JP locale </td> <td> <code>tm_hour</code> </td> +</tr> <tr> <th> <code>I</code> </th> <td> writes <b>hour</b> as a decimal number, 12 hour clock (range <code>[01,12]</code>) </td> <td> <code>tm_hour</code> </td> +</tr> <tr> <th> <code>OI</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>hour</b> from 12-hour clock using the alternative numeric system, e.g. 六 instead of 06 in ja_JP locale </td> <td> <code>tm_hour</code> </td> +</tr> <tr> <th> <code>M</code> </th> <td> writes <b>minute</b> as a decimal number (range <code>[00,59]</code>) </td> <td> <code>tm_min</code> </td> +</tr> <tr> <th> <code>OM</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>minute</b> using the alternative numeric system, e.g. 二十五 instead of 25 in ja_JP locale </td> <td> <code>tm_min</code> </td> +</tr> <tr> <th> <code>S</code> </th> <td> writes <b>second</b> as a decimal number (range <code>[00,60]</code>) </td> <td> <code>tm_sec</code> </td> +</tr> <tr> <th> <code>OS</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>second</b> using the alternative numeric system, e.g. 二十四 instead of 24 in ja_JP locale </td> <td> <code>tm_sec</code> </td> +</tr> <tr> <th colspan="3"> Other </th> +</tr> <tr> <th> <code>c</code> </th> <td> writes <b>standard date and time string</b>, e.g. <code>Sun Oct 17 04:41:13 2010</code> (locale dependent) </td> <td> all </td> +</tr> <tr> <th> <code>Ec</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>alternative date and time string</b>, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale </td> <td> all </td> +</tr> <tr> <th> <code>x</code> </th> <td> writes localized <b>date representation</b> (locale dependent) </td> <td> all </td> +</tr> <tr> <th> <code>Ex</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>alternative date representation</b>, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale </td> <td> all </td> +</tr> <tr> <th> <code>X</code> </th> <td> writes localized <b>time representation</b>, e.g. 18:40:20 or 6:40:20 PM (locale dependent) </td> <td> all </td> +</tr> <tr> <th> <code>EX</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>alternative time representation</b> (locale dependent) </td> <td> all </td> +</tr> <tr> <th> <code>D</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> equivalent to <b>"%m/%d/%y"</b> </td> <td> <code>tm_mon</code>, <code>tm_mday</code>, <code>tm_year</code> </td> +</tr> <tr> <th> <code>F</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> equivalent to <b>"%Y-%m-%d"</b> (the ISO 8601 date format) </td> <td> <code>tm_mon</code>, <code>tm_mday</code>, <code>tm_year</code> </td> +</tr> <tr> <th> <code>r</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes localized <b>12-hour clock</b> time (locale dependent) </td> <td> <code>tm_hour</code>, <code>tm_min</code>, <code>tm_sec</code> </td> +</tr> <tr> <th> <code>R</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> equivalent to <b>"%H:%M"</b> </td> <td> <code>tm_hour</code>, <code>tm_min</code> </td> +</tr> <tr> <th> <code>T</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> equivalent to <b>"%H:%M:%S"</b> (the ISO 8601 time format) </td> <td> <code>tm_hour</code>, <code>tm_min</code>, <code>tm_sec</code> </td> +</tr> <tr> <th> <code>p</code> </th> <td> writes localized <b>a.m. or p.m.</b> (locale dependent) </td> <td> <code>tm_hour</code> </td> +</tr> <tr> <th> <code>z</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>offset from UTC</b> in the ISO 8601 format (e.g. <code>-0430</code>), or no characters if the time zone information is not available </td> <td> <code>tm_isdst</code> </td> +</tr> <tr> <th> <code>Z</code> </th> <td> writes locale-dependent <b>time zone name or abbreviation</b>, or no characters if the time zone information is not available </td> <td> <code>tm_isdst</code> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The number of bytes written into the character array pointed to by <code>str</code> not including the terminating <code>'\0'</code> on success. If <code>count</code> was reached before the entire string could be stored, <code>0</code> is returned and the contents are indeterminate.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <time.h> + +int main(void) +{ + char buff[70]; + struct tm my_time = { .tm_year=112, // = year 2012 + .tm_mon=9, // = 10th month + .tm_mday=9, // = 9th day + .tm_hour=8, // = 8 hours + .tm_min=10, // = 10 minutes + .tm_sec=20 // = 20 secs + }; + + if (strftime(buff, sizeof buff, "%A %c", &my_time)) + puts(buff); + else + puts("strftime failed"); + + setlocale(LC_TIME, "el_GR.utf8"); + + if (strftime(buff, sizeof buff, "%A %c", &my_time)) + puts(buff); + else + puts("strftime failed"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Sunday Sun Oct 9 08:10:20 2012 +Κυριακή Κυρ 09 Οκτ 2012 08:10:20 πμ EST</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.27.3.5 The strftime function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.27.3.5 The strftime function (p: 288-291) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.27.3.5 The strftime function (p: 394-397) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.23.3.5 The strftime function (p: 343-347) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.12.3.5 The strftime function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="asctime" title="c/chrono/asctime"> <span class="t-lines"><span>asctime</span><span>asctime_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-deprecated-c23">(deprecated in C23)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a <code><a href="tm" title="c/chrono/tm">tm</a></code> object to a textual representation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ctime" title="c/chrono/ctime"> <span class="t-lines"><span>ctime</span><span>ctime_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-deprecated-c23">(deprecated in C23)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a <code><a href="time_t" title="c/chrono/time t">time_t</a></code> object to a textual representation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcsftime" title="c/chrono/wcsftime"> <span class="t-lines"><span>wcsftime</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> converts a <code><a href="tm" title="c/chrono/tm">tm</a></code> object to custom wide string textual representation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/chrono/c/strftime" title="cpp/chrono/c/strftime">C++ documentation</a></span> for <code>strftime</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/chrono/strftime" class="_attribution-link">https://en.cppreference.com/w/c/chrono/strftime</a> + </p> +</div> diff --git a/devdocs/c/chrono%2Ftime.html b/devdocs/c/chrono%2Ftime.html new file mode 100644 index 00000000..b7656af1 --- /dev/null +++ b/devdocs/c/chrono%2Ftime.html @@ -0,0 +1,40 @@ + <h1 id="firstHeading" class="firstHeading">time</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><time.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">time_t time( time_t *arg );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Returns the current calendar time encoded as a <code><a href="time_t" title="c/chrono/time t">time_t</a></code> object, and also stores it in the <code><a href="time_t" title="c/chrono/time t">time_t</a></code> object pointed to by <code>arg</code> (unless <code>arg</code> is a null pointer)</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> pointer to a <code><a href="time_t" title="c/chrono/time t">time_t</a></code> object where the time will be stored, or a null pointer </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Current calendar time encoded as <code><a href="time_t" title="c/chrono/time t">time_t</a></code> object on success, <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/chrono/time_t"><span class="kw523">time_t</span></a><span class="br0">)</span><span class="br0">(</span><span class="sy2">-</span><span class="nu0">1</span><span class="br0">)</span></code> on error. If <code>arg</code> is not a null pointer, the return value is also stored in the object pointed to by <code>arg</code>.</p> +<h3 id="Notes"> Notes</h3> <p>The encoding of calendar time in <code><a href="time_t" title="c/chrono/time t">time_t</a></code> is unspecified, but most systems conform to <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/time.html">POSIX specification</a> and return a value of integral type holding the number of seconds since <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_15">the Epoch</a>. Implementations in which <code><a href="time_t" title="c/chrono/time t">time_t</a></code> is a 32-bit signed integer (many historical implementations) fail in the year <a rel="nofollow" class="external text" href="http://en.wikipedia.org/wiki/Year_2038_problem">2038</a>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <time.h> +#include <stdint.h> + +int main(void) +{ + time_t result = time(NULL); + if(result != (time_t)(-1)) + printf("The current time is %s(%jd seconds since the Epoch)\n", + asctime(gmtime(&result)), (intmax_t)result); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">The current time is Fri Apr 24 15:05:25 2015 +(1429887925 seconds since the Epoch)</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.27.2.4 The time function (p: 286) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.27.2.4 The time function (p: 391) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.23.2.4 The time function (p: 341) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.12.2.4 The time function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="localtime" title="c/chrono/localtime"> <span class="t-lines"><span>localtime</span><span>localtime_r</span><span>localtime_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts time since epoch to calendar time expressed as local time <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="gmtime" title="c/chrono/gmtime"> <span class="t-lines"><span>gmtime</span><span>gmtime_r</span><span>gmtime_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts time since epoch to calendar time expressed as Coordinated Universal Time (UTC) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="timespec_get" title="c/chrono/timespec get"> <span class="t-lines"><span>timespec_get</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> returns the calendar time in seconds and nanoseconds based on a given time base <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/chrono/c/time" title="cpp/chrono/c/time">C++ documentation</a></span> for <code>time</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/chrono/time" class="_attribution-link">https://en.cppreference.com/w/c/chrono/time</a> + </p> +</div> diff --git a/devdocs/c/chrono%2Ftime_t.html b/devdocs/c/chrono%2Ftime_t.html new file mode 100644 index 00000000..d6e589de --- /dev/null +++ b/devdocs/c/chrono%2Ftime_t.html @@ -0,0 +1,38 @@ + <h1 id="firstHeading" class="firstHeading">time_t</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><time.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">typedef /* unspecified */ time_t;</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Real arithmetic type capable of representing times.</p> +<p>Although not defined by the C standard, this is almost always an integral value holding the number of seconds (not counting leap seconds) since 00:00, Jan 1 1970 UTC, corresponding to <a href="https://en.wikipedia.org/wiki/Unix_time" class="extiw" title="enwiki:Unix time"> POSIX time</a>.</p> +<h3 id="Notes"> Notes</h3> <p>The standard uses the term <i>calendar time</i> when referring to a value of type <code>time_t</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>Show the start of the epoch.</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <time.h> +#include <stdint.h> + +int main(void) +{ + time_t epoch = 0; + printf("%jd seconds since the epoch began\n", (intmax_t)epoch); + printf("%s", asctime(gmtime(&epoch))); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">0 seconds since the epoch began +Thu Jan 1 00:00:00 1970</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.27.1/3 Components of time (p: 284) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.27.1/3 Components of time (p: 388) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.23.1/3 Components of time (p: 338) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.12.1 Components of time </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="time" title="c/chrono/time"> <span class="t-lines"><span>time</span></span></a></div> </td> <td> returns the current calendar time of the system as time since epoch <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="localtime" title="c/chrono/localtime"> <span class="t-lines"><span>localtime</span><span>localtime_r</span><span>localtime_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts time since epoch to calendar time expressed as local time <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="gmtime" title="c/chrono/gmtime"> <span class="t-lines"><span>gmtime</span><span>gmtime_r</span><span>gmtime_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts time since epoch to calendar time expressed as Coordinated Universal Time (UTC) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/chrono/c/time_t" title="cpp/chrono/c/time t">C++ documentation</a></span> for <code>time_t</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/chrono/time_t" class="_attribution-link">https://en.cppreference.com/w/c/chrono/time_t</a> + </p> +</div> diff --git a/devdocs/c/chrono%2Ftimespec.html b/devdocs/c/chrono%2Ftimespec.html new file mode 100644 index 00000000..f799f3a3 --- /dev/null +++ b/devdocs/c/chrono%2Ftimespec.html @@ -0,0 +1,43 @@ + <h1 id="firstHeading" class="firstHeading">timespec</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><time.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">struct timespec;</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Structure holding an interval broken down into seconds and nanoseconds.</p> +<h3 id="Member_objects"> Member objects</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <code><a href="time_t" title="c/chrono/time t">time_t</a></code> <code>tv_sec</code> </td> <td> whole seconds (valid values are >= 0) </td> +</tr> <tr class="t-dsc"> <td> <code>/* see below */</code> <code>tv_nsec</code> </td> <td> nanoseconds (valid values are [0, 999999999]) </td> +</tr> </table> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>The type of <code>tv_nsec</code> is <code>long</code>.</p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td> <p>The type of <code>tv_nsec</code> is an implementation-defined signed integer type that can represent integers in [0, 999999999].</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <p>The declaration order of <code>tv_sec</code> and <code>tv_nsec</code> is unspecified. Implementation may add other members to <code>struct timespec</code>.</p> +<h3 id="Notes"> Notes</h3> <p>The type of <code>tv_nsec</code> is <code>long long</code> on some platforms, which is conforming only since C23.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <time.h> +#include <stdint.h> + +int main(void) +{ + struct timespec ts; + timespec_get(&ts, TIME_UTC); + char buff[100]; + strftime(buff, sizeof buff, "%D %T", gmtime(&ts.tv_sec)); + printf("Current time: %s.%09ld UTC\n", buff, ts.tv_nsec); + printf("Raw timespec.time_t: %jd\n", (intmax_t)ts.tv_sec); + printf("Raw timespec.tv_nsec: %09ld\n", ts.tv_nsec); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Current time: 11/24/21 03:10:50.408191283 UTC +Raw timespec.time_t: 1637723450 +Raw timespec.tv_nsec: 408191283</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.27.1/3 Components of time (p: 284) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.27.1/3 Components of time (p: 388) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="timespec_get" title="c/chrono/timespec get"> <span class="t-lines"><span>timespec_get</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> returns the calendar time in seconds and nanoseconds based on a given time base <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="tm" title="c/chrono/tm"> <span class="t-lines"><span>tm</span></span></a></div> </td> <td> calendar time type<br><span class="t-mark">(struct)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/chrono/c/timespec" title="cpp/chrono/c/timespec">C++ documentation</a></span> for <code>timespec</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/chrono/timespec" class="_attribution-link">https://en.cppreference.com/w/c/chrono/timespec</a> + </p> +</div> diff --git a/devdocs/c/chrono%2Ftimespec_get.html b/devdocs/c/chrono%2Ftimespec_get.html new file mode 100644 index 00000000..ab32e7f2 --- /dev/null +++ b/devdocs/c/chrono%2Ftimespec_get.html @@ -0,0 +1,43 @@ + <h1 id="firstHeading" class="firstHeading">timespec_get</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><time.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int timespec_get( struct timespec *ts, int base );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">#define TIME_UTC /* implementation-defined */</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Modifies the <code>timespec</code> object pointed to by <code>ts</code> to hold the current calendar time in the time base <code>base</code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Expands to a value suitable for use as the <code>base</code> argument of <code>timespec_get</code> +</div> <p>Other macro constants beginning with <code>TIME_</code> may be provided by the implementation to indicate additional time bases</p> +<p>If <code>base</code> is <code>TIME_UTC</code>, then</p> +<ul> +<li> <code>ts->tv_sec</code> is set to the number of seconds since an implementation defined epoch, truncated to a whole value </li> +<li> <code>ts->tv_nsec</code> member is set to the integral number of nanoseconds, rounded to the resolution of the system clock </li> +</ul> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ts </td> <td> - </td> <td> pointer to an object of type <code>struct timespec</code> </td> +</tr> <tr class="t-par"> <td> base </td> <td> - </td> <td> <code>TIME_UTC</code> or another nonzero integer value indicating the time base </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The value of <code>base</code> if successful, zero otherwise.</p> +<h3 id="Notes"> Notes</h3> <p>The POSIX function <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_getres.html"><code>clock_gettime(CLOCK_REALTIME, ts)</code></a> may also be used to populate a <code>timespec</code> with the time since the Epoch.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <time.h> + +int main(void) +{ + struct timespec ts; + timespec_get(&ts, TIME_UTC); + char buff[100]; + strftime(buff, sizeof buff, "%D %T", gmtime(&ts.tv_sec)); + printf("Current time: %s.%09ld UTC\n", buff, ts.tv_nsec); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Current time: 02/18/15 14:34:03.048508855 UTC</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.27.2.5 The timespec_get function (p: 286) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.27.2.5 The timespec_get function (p: 390) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="timespec" title="c/chrono/timespec"> <span class="t-lines"><span>timespec</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> time in seconds and nanoseconds <br><span class="t-mark">(struct)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="timespec_getres" title="c/chrono/timespec getres"> <span class="t-lines"><span>timespec_getres</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> returns the resolution of calendar time based on a given time base <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="time" title="c/chrono/time"> <span class="t-lines"><span>time</span></span></a></div> </td> <td> returns the current calendar time of the system as time since epoch <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/chrono/c/timespec_get" title="cpp/chrono/c/timespec get">C++ documentation</a></span> for <code>timespec_get</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/chrono/timespec_get" class="_attribution-link">https://en.cppreference.com/w/c/chrono/timespec_get</a> + </p> +</div> diff --git a/devdocs/c/chrono%2Ftimespec_getres.html b/devdocs/c/chrono%2Ftimespec_getres.html new file mode 100644 index 00000000..b40a3243 --- /dev/null +++ b/devdocs/c/chrono%2Ftimespec_getres.html @@ -0,0 +1,34 @@ + <h1 id="firstHeading" class="firstHeading">timespec_getres</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><time.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">int timespec_getres( struct timespec *ts, int base );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <p>If <code>ts</code> is non-null and <code>base</code> is supported by <code>timespec_get</code>, modifies <code>*ts</code> to hold the resolution of time provided by <code>timespec_get</code> for <code>base</code>. For each supported <code>base</code>, multiple calls to <code>timespec_getres</code> during the same program execution have identical results.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ts </td> <td> - </td> <td> pointer to an object of type <code>struct timespec</code> </td> +</tr> <tr class="t-par"> <td> base </td> <td> - </td> <td> <code>TIME_UTC</code> or another nonzero integer value indicating the time base </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The value of <code>base</code> if <code>base</code> is supported, zero otherwise.</p> +<h3 id="Notes"> Notes</h3> <p>The POSIX function <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_getres.html"><code>clock_getres(clock_id, ts)</code></a> may also be used to populate a <code>timespec</code> with the resolution of time identified by <code>clock_id</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <time.h> + +int main(void) +{ + char buff[128]; + struct timespec ts; + const int res = timespec_getres(&ts, TIME_UTC); + if (res == TIME_UTC) { + struct tm timer; + strftime(buff, sizeof buff, "%D %T", gmtime_r(&ts.tv_sec, &timer)); + printf("Time resolution info: %s.%09ld UTC\n", buff, ts.tv_nsec); + } else { + printf("TIME_UTC base is not supported."); + } +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Time resolution info: 01/01/70 00:00:00.000000001 UTC</pre></div> </div> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="timespec" title="c/chrono/timespec"> <span class="t-lines"><span>timespec</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> time in seconds and nanoseconds <br><span class="t-mark">(struct)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="timespec_get" title="c/chrono/timespec get"> <span class="t-lines"><span>timespec_get</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> returns the calendar time in seconds and nanoseconds based on a given time base <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="time" title="c/chrono/time"> <span class="t-lines"><span>time</span></span></a></div> </td> <td> returns the current calendar time of the system as time since epoch <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/chrono/timespec_getres" class="_attribution-link">https://en.cppreference.com/w/c/chrono/timespec_getres</a> + </p> +</div> diff --git a/devdocs/c/chrono%2Ftm.html b/devdocs/c/chrono%2Ftm.html new file mode 100644 index 00000000..f14a6474 --- /dev/null +++ b/devdocs/c/chrono%2Ftm.html @@ -0,0 +1,41 @@ + <h1 id="firstHeading" class="firstHeading">tm</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><time.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">struct tm;</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Structure holding a calendar date and time broken down into its components.</p> +<h3 id="Member_objects"> Member objects</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">int</span> tm_sec</span></span></div> </td> <td> seconds after the minute – <span class="t-rev-inl t-until-c99"><span>[0, 61]</span><span><span class="t-mark-rev t-until-c99">(until C99)</span></span></span><span class="t-rev-inl t-since-c99"><span>[0, 60]</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span><sup id="cite_ref-leapsecond_1-0" class="reference"><a href="#cite_note-leapsecond-1">[note 1]</a></sup> <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">int</span> tm_min</span></span></div> </td> <td> minutes after the hour – [0, 59] <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">int</span> tm_hour</span></span></div> </td> <td> hours since midnight – [0, 23] <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">int</span> tm_mday</span></span></div> </td> <td> day of the month – [1, 31] <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">int</span> tm_mon</span></span></div> </td> <td> months since January – [0, 11] <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">int</span> tm_year</span></span></div> </td> <td> years since 1900 <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">int</span> tm_wday</span></span></div> </td> <td> days since Sunday – [0, 6] <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">int</span> tm_yday</span></span></div> </td> <td> days since January 1 – [0, 365] <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">int</span> tm_isdst</span></span></div> </td> <td> Daylight Saving Time flag. The value is positive if DST is in effect, zero if not and negative if no information is available <br> <span class="t-mark">(public member object)</span> </td> +</tr> </table> <h6 id="Notes"> Notes</h6> <p>The Standard mandates only the presence of the aforementioned members in either order. The implementations usually add more data-members to this structure.</p> +<ol class="references"> <li id="cite_note-leapsecond-1"> <span class="reference-text">Range allows for a positive leap second. Two leap seconds in the same minute are not allowed (the C89 range 0..61 was a defect)</span> </li> </ol> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <time.h> + +int main(void) +{ + struct tm start = {.tm_year=2022-1900, .tm_mday=1}; + mktime(&start); + printf("%s", asctime(&start)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Sat Jan 1 00:00:00 2022</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.27.1/3 Components of time (p: 284) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.27.1/3 Components of time (p: 388) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.23.1/3 Components of time (p: 338) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.12.1 Components of time </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="localtime" title="c/chrono/localtime"> <span class="t-lines"><span>localtime</span><span>localtime_r</span><span>localtime_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts time since epoch to calendar time expressed as local time <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="gmtime" title="c/chrono/gmtime"> <span class="t-lines"><span>gmtime</span><span>gmtime_r</span><span>gmtime_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts time since epoch to calendar time expressed as Coordinated Universal Time (UTC) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/chrono/c/tm" title="cpp/chrono/c/tm">C++ documentation</a></span> for <code>tm</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/chrono/tm" class="_attribution-link">https://en.cppreference.com/w/c/chrono/tm</a> + </p> +</div> diff --git a/devdocs/c/chrono%2Fwcsftime.html b/devdocs/c/chrono%2Fwcsftime.html new file mode 100644 index 00000000..1b020763 --- /dev/null +++ b/devdocs/c/chrono%2Fwcsftime.html @@ -0,0 +1,136 @@ + <h1 id="firstHeading" class="firstHeading">wcsftime</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">size_t wcsftime( wchar_t* str, size_t count, const wchar_t* format, tm* time );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Converts the date and time information from a given calendar time <code>time</code> to a null-terminated wide character string <code>str</code> according to <a href="#Format_string">format string</a> <code>format</code>. Up to <code>count</code> bytes are written.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> pointer to the first element of the wchar_t array for output </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> maximum number of wide characters to write </td> +</tr> <tr class="t-par"> <td> format </td> <td> - </td> <td> pointer to a null-terminated wide character string specifying the <a href="#Format_string">format of conversion</a> </td> +</tr> +</table> <h3 id="Format_string"> Format string</h3> <p>The format string consists of zero or more conversion specifiers and ordinary characters (except <code>%</code>). All ordinary characters, including the terminating null character, are copied to the output string without modification. Each conversion specification begins with <code>%</code> character, optionally followed by <code>E</code> or <code>O</code> modifier (ignored if unsupported by the locale), followed by the character that determines the behavior of the specifier. The following format specifiers are available:</p> +<table class="wikitable"> <tr> <th> Conversion<br> specifier </th> <th> Explanation </th> <th> Used fields </th> +</tr> <tr> <th> <code>%</code> </th> <td> writes literal <code>%</code>. The full conversion specification must be <code>%%</code>. </td> <td> </td> +</tr> <tr> <th> <code>n</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes newline character </td> <td> </td> +</tr> <tr> <th> <code>t</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes horizontal tab character </td> <td> </td> +</tr> <tr> <th colspan="3"> Year </th> +</tr> <tr> <th> <code>Y</code> </th> <td> writes <b>year</b> as a decimal number, e.g. 2017 </td> <td> <code>tm_year</code> </td> +</tr> <tr> <th> <code>EY</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>year</b> in the alternative representation, e.g.平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale </td> <td> <code>tm_year</code> </td> +</tr> <tr> <th> <code>y</code> </th> <td> writes last 2 digits of <b>year</b> as a decimal number (range <code>[00,99]</code>) </td> <td> <code>tm_year</code> </td> +</tr> <tr> <th> <code>Oy</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes last 2 digits of <b>year</b> using the alternative numeric system, e.g. 十一 instead of 11 in ja_JP locale </td> <td> <code>tm_year</code> </td> +</tr> <tr> <th> <code>Ey</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>year</b> as offset from locale's alternative calendar period <code>%EC</code> (locale-dependent) </td> <td> <code>tm_year</code> </td> +</tr> <tr> <th> <code>C</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes first 2 digits of <b>year</b> as a decimal number (range <code>[00,99]</code>) </td> <td> <code>tm_year</code> </td> +</tr> <tr> <th> <code>EC</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes name of the <b>base year (period)</b> in the locale's alternative representation, e.g. 平成 (Heisei era) in ja_JP </td> <td> <code>tm_year</code> </td> +</tr> <tr> <th> <code>G</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>ISO 8601 week-based year</b>, i.e. the year that contains the specified week. <p>In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the following requirements:</p> +<ul> +<li> Includes January 4 </li> +<li> Includes first Thursday of the year </li> +</ul> </td> <td> <code>tm_year</code>, <code>tm_wday</code>, <code>tm_yday</code> </td> +</tr> <tr> <th> <code>g</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes last 2 digits of <b>ISO 8601 week-based year</b>, i.e. the year that contains the specified week (range <code>[00,99]</code>). <p>In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the following requirements:</p> +<ul> +<li> Includes January 4 </li> +<li> Includes first Thursday of the year </li> +</ul> </td> <td> <code>tm_year</code>, <code>tm_wday</code>, <code>tm_yday</code> </td> +</tr> <tr> <th colspan="3"> Month </th> +</tr> <tr> <th> <code>b</code> </th> <td> writes <b>abbreviated month</b> name, e.g. <code>Oct</code> (locale dependent) </td> <td> <code>tm_mon</code> </td> +</tr> <tr> <th> <code>Ob</code><br><span class="t-mark-rev t-since-c23">(C23)</span> </th> <td> writes <b>abbreviated month</b> name in the locale's alternative representation </td> <td> <code>tm_mon</code> </td> +</tr> <tr> <th> <code>h</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> synonym of <code>b</code> </td> <td> <code>tm_mon</code> </td> +</tr> <tr> <th> <code>B</code> </th> <td> writes <b>full month</b> name, e.g. <code>October</code> (locale dependent) </td> <td> <code>tm_mon</code> </td> +</tr> <tr> <th> <code>OB</code><br><span class="t-mark-rev t-since-c23">(C23)</span> </th> <td> writes appropriate <b>full month</b> name in the locale's alternative representation </td> <td> <code>tm_mon</code> </td> +</tr> <tr> <th> <code>m</code> </th> <td> writes <b>month</b> as a decimal number (range <code>[01,12]</code>) </td> <td> <code>tm_mon</code> </td> +</tr> <tr> <th> <code>Om</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>month</b> using the alternative numeric system, e.g. 十二 instead of 12 in ja_JP locale </td> <td> <code>tm_mon</code> </td> +</tr> <tr> <th colspan="3"> Week </th> +</tr> <tr> <th> <code>U</code> </th> <td> writes <b>week of the year</b> as a decimal number (Sunday is the first day of the week) (range <code>[00,53]</code>) </td> <td> <code>tm_year</code>, <code>tm_wday</code>, <code>tm_yday</code> </td> +</tr> <tr> <th> <code>OU</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>week of the year</b>, as by <code>%U</code>, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale </td> <td> <code>tm_year</code>, <code>tm_wday</code>, <code>tm_yday</code> </td> +</tr> <tr> <th> <code>W</code> </th> <td> writes <b>week of the year</b> as a decimal number (Monday is the first day of the week) (range <code>[00,53]</code>) </td> <td> <code>tm_year</code>, <code>tm_wday</code>, <code>tm_yday</code> </td> +</tr> <tr> <th> <code>OW</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>week of the year</b>, as by <code>%W</code>, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale </td> <td> <code>tm_year</code>, <code>tm_wday</code>, <code>tm_yday</code> </td> +</tr> <tr> <th> <code>V</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>ISO 8601 week of the year</b> (range <code>[01,53]</code>). <p>In ISO 8601 weeks begin with Monday and the first week of the year must satisfy the following requirements:</p> +<ul> +<li> Includes January 4 </li> +<li> Includes first Thursday of the year </li> +</ul> </td> <td> <code>tm_year</code>, <code>tm_wday</code>, <code>tm_yday</code> </td> +</tr> <tr> <th> <code>OV</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>week of the year</b>, as by <code>%V</code>, using the alternative numeric system, e.g. 五十二 instead of 52 in ja_JP locale </td> <td> <code>tm_year</code>, <code>tm_wday</code>, <code>tm_yday</code> </td> +</tr> <tr> <th colspan="3"> Day of the year/month </th> +</tr> <tr> <th> <code>j</code> </th> <td> writes <b>day of the year</b> as a decimal number (range <code>[001,366]</code>) </td> <td> <code>tm_yday</code> </td> +</tr> <tr> <th> <code>d</code> </th> <td> writes <b>day of the month</b> as a decimal number (range <code>[01,31]</code>) </td> <td> <code>tm_mday</code> </td> +</tr> <tr> <th> <code>Od</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes zero-based <b>day of the month</b> using the alternative numeric system, e.g. 二十七 instead of 27 in ja_JP locale <p>Single character is preceded by a space.</p> +</td> <td> <code>tm_mday</code> </td> +</tr> <tr> <th> <code>e</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>day of the month</b> as a decimal number (range <code>[1,31]</code>). <p>Single digit is preceded by a space.</p> +</td> <td> <code>tm_mday</code> </td> +</tr> <tr> <th> <code>Oe</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes one-based <b>day of the month</b> using the alternative numeric system, e.g. 二十七 instead of 27 in ja_JP locale <p>Single character is preceded by a space.</p> +</td> <td> <code>tm_mday</code> </td> +</tr> <tr> <th colspan="3"> Day of the week </th> +</tr> <tr> <th> <code>a</code> </th> <td> writes <b>abbreviated weekday</b> name, e.g. <code>Fri</code> (locale dependent) </td> <td> <code>tm_wday</code> </td> +</tr> <tr> <th> <code>A</code> </th> <td> writes <b>full weekday</b> name, e.g. <code>Friday</code> (locale dependent) </td> <td> <code>tm_wday</code> </td> +</tr> <tr> <th> <code>w</code> </th> <td> writes <b>weekday</b> as a decimal number, where Sunday is <code>0</code> (range <code>[0-6]</code>) </td> <td> <code>tm_wday</code> </td> +</tr> <tr> <th> <code>Ow</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>weekday</b>, where Sunday is <code>0</code>, using the alternative numeric system, e.g. 二 instead of 2 in ja_JP locale </td> <td> <code>tm_wday</code> </td> +</tr> <tr> <th> <code>u</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>weekday</b> as a decimal number, where Monday is <code>1</code> (ISO 8601 format) (range <code>[1-7]</code>) </td> <td> <code>tm_wday</code> </td> +</tr> <tr> <th> <code>Ou</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>weekday</b>, where Monday is <code>1</code>, using the alternative numeric system, e.g. 二 instead of 2 in ja_JP locale </td> <td> <code>tm_wday</code> </td> +</tr> <tr> <th colspan="3"> Hour, minute, second </th> +</tr> <tr> <th> <code>H</code> </th> <td> writes <b>hour</b> as a decimal number, 24 hour clock (range <code>[00-23]</code>) </td> <td> <code>tm_hour</code> </td> +</tr> <tr> <th> <code>OH</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>hour</b> from 24-hour clock using the alternative numeric system, e.g. 十八 instead of 18 in ja_JP locale </td> <td> <code>tm_hour</code> </td> +</tr> <tr> <th> <code>I</code> </th> <td> writes <b>hour</b> as a decimal number, 12 hour clock (range <code>[01,12]</code>) </td> <td> <code>tm_hour</code> </td> +</tr> <tr> <th> <code>OI</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>hour</b> from 12-hour clock using the alternative numeric system, e.g. 六 instead of 06 in ja_JP locale </td> <td> <code>tm_hour</code> </td> +</tr> <tr> <th> <code>M</code> </th> <td> writes <b>minute</b> as a decimal number (range <code>[00,59]</code>) </td> <td> <code>tm_min</code> </td> +</tr> <tr> <th> <code>OM</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>minute</b> using the alternative numeric system, e.g. 二十五 instead of 25 in ja_JP locale </td> <td> <code>tm_min</code> </td> +</tr> <tr> <th> <code>S</code> </th> <td> writes <b>second</b> as a decimal number (range <code>[00,60]</code>) </td> <td> <code>tm_sec</code> </td> +</tr> <tr> <th> <code>OS</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>second</b> using the alternative numeric system, e.g. 二十四 instead of 24 in ja_JP locale </td> <td> <code>tm_sec</code> </td> +</tr> <tr> <th colspan="3"> Other </th> +</tr> <tr> <th> <code>c</code> </th> <td> writes <b>standard date and time string</b>, e.g. <code>Sun Oct 17 04:41:13 2010</code> (locale dependent) </td> <td> all </td> +</tr> <tr> <th> <code>Ec</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>alternative date and time string</b>, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale </td> <td> all </td> +</tr> <tr> <th> <code>x</code> </th> <td> writes localized <b>date representation</b> (locale dependent) </td> <td> all </td> +</tr> <tr> <th> <code>Ex</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>alternative date representation</b>, e.g. using 平成23年 (year Heisei 23) instead of 2011年 (year 2011) in ja_JP locale </td> <td> all </td> +</tr> <tr> <th> <code>X</code> </th> <td> writes localized <b>time representation</b>, e.g. 18:40:20 or 6:40:20 PM (locale dependent) </td> <td> all </td> +</tr> <tr> <th> <code>EX</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>alternative time representation</b> (locale dependent) </td> <td> all </td> +</tr> <tr> <th> <code>D</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> equivalent to <b>"%m/%d/%y"</b> </td> <td> <code>tm_mon</code>, <code>tm_mday</code>, <code>tm_year</code> </td> +</tr> <tr> <th> <code>F</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> equivalent to <b>"%Y-%m-%d"</b> (the ISO 8601 date format) </td> <td> <code>tm_mon</code>, <code>tm_mday</code>, <code>tm_year</code> </td> +</tr> <tr> <th> <code>r</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes localized <b>12-hour clock</b> time (locale dependent) </td> <td> <code>tm_hour</code>, <code>tm_min</code>, <code>tm_sec</code> </td> +</tr> <tr> <th> <code>R</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> equivalent to <b>"%H:%M"</b> </td> <td> <code>tm_hour</code>, <code>tm_min</code> </td> +</tr> <tr> <th> <code>T</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> equivalent to <b>"%H:%M:%S"</b> (the ISO 8601 time format) </td> <td> <code>tm_hour</code>, <code>tm_min</code>, <code>tm_sec</code> </td> +</tr> <tr> <th> <code>p</code> </th> <td> writes localized <b>a.m. or p.m.</b> (locale dependent) </td> <td> <code>tm_hour</code> </td> +</tr> <tr> <th> <code>z</code><br><span class="t-mark-rev t-since-c99">(C99)</span> </th> <td> writes <b>offset from UTC</b> in the ISO 8601 format (e.g. <code>-0430</code>), or no characters if the time zone information is not available </td> <td> <code>tm_isdst</code> </td> +</tr> <tr> <th> <code>Z</code> </th> <td> writes locale-dependent <b>time zone name or abbreviation</b>, or no characters if the time zone information is not available </td> <td> <code>tm_isdst</code> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>number of wide characters written into the wide character array pointed to by <code>str</code> not including the terminating <code>L'\0'</code> on success. If <code>count</code> was reached before the entire string could be stored, <code>0</code> is returned and the contents are undefined.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <time.h> +#include <wchar.h> +#include <locale.h> + +int main(void) +{ + wchar_t buff[40]; + struct tm my_time = { .tm_year=112, // = year 2012 + .tm_mon=9, // = 10th month + .tm_mday=9, // = 9th day + .tm_hour=8, // = 8 hours + .tm_min=10, // = 10 minutes + .tm_sec=20 // = 20 secs + }; + + if (wcsftime(buff, sizeof buff, L"%A %c", &my_time)) { + printf("%ls\n", buff); + } else { + puts("wcsftime failed"); + } + + setlocale(LC_ALL, "ja_JP.utf8"); + + if (wcsftime(buff, sizeof buff, L"%A %c", &my_time)) { + printf("%ls\n", buff); + } else { + puts("wcsftime failed"); + } +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Sunday Sun Oct 9 08:10:20 2012 +日曜日 2012年10月09日 08時10分20秒</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.29.5.1 The wcsftime function (p: 230-231) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.5.1 The wcsftime function (p: 439-440) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.5.1 The wcsftime function (p: 385-386) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="strftime" title="c/chrono/strftime"> <span class="t-lines"><span>strftime</span></span></a></div> </td> <td> converts a <code><a href="tm" title="c/chrono/tm">tm</a></code> object to custom textual representation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/chrono/c/wcsftime" title="cpp/chrono/c/wcsftime">C++ documentation</a></span> for <code>wcsftime</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/chrono/wcsftime" class="_attribution-link">https://en.cppreference.com/w/c/chrono/wcsftime</a> + </p> +</div> diff --git a/devdocs/c/chrono.html b/devdocs/c/chrono.html new file mode 100644 index 00000000..2cd9fef6 --- /dev/null +++ b/devdocs/c/chrono.html @@ -0,0 +1,60 @@ + <h1 id="firstHeading" class="firstHeading">Date and time utilities</h1> <h3 id="Functions"> Functions</h3> <table class="t-dsc-begin"> <tr> <td colspan="2"> <h5 id="Time_manipulation"> Time manipulation </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><time.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="chrono/difftime" title="c/chrono/difftime"> <span class="t-lines"><span>difftime</span></span></a></div> </td> <td> computes the difference between times <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="chrono/time" title="c/chrono/time"> <span class="t-lines"><span>time</span></span></a></div> </td> <td> returns the current calendar time of the system as time since epoch <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="chrono/clock" title="c/chrono/clock"> <span class="t-lines"><span>clock</span></span></a></div> </td> <td> returns raw processor clock time since the program is started <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="chrono/timespec_get" title="c/chrono/timespec get"> <span class="t-lines"><span>timespec_get</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> returns the calendar time in seconds and nanoseconds based on a given time base <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="chrono/timespec_getres" title="c/chrono/timespec getres"> <span class="t-lines"><span>timespec_getres</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> returns the resolution of calendar time based on a given time base <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Format_conversions"> Format conversions </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><time.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="chrono/asctime" title="c/chrono/asctime"> <span class="t-lines"><span>asctime</span><span>asctime_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-deprecated-c23">(deprecated in C23)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a <code><a href="chrono/tm" title="c/chrono/tm">tm</a></code> object to a textual representation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="chrono/ctime" title="c/chrono/ctime"> <span class="t-lines"><span>ctime</span><span>ctime_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-deprecated-c23">(deprecated in C23)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a <code><a href="chrono/time_t" title="c/chrono/time t">time_t</a></code> object to a textual representation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="chrono/strftime" title="c/chrono/strftime"> <span class="t-lines"><span>strftime</span></span></a></div> </td> <td> converts a <code><a href="chrono/tm" title="c/chrono/tm">tm</a></code> object to custom textual representation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><wchar.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="chrono/wcsftime" title="c/chrono/wcsftime"> <span class="t-lines"><span>wcsftime</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> converts a <code><a href="chrono/tm" title="c/chrono/tm">tm</a></code> object to custom wide string textual representation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><time.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="chrono/gmtime" title="c/chrono/gmtime"> <span class="t-lines"><span>gmtime</span><span>gmtime_r</span><span>gmtime_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts time since epoch to calendar time expressed as Coordinated Universal Time (UTC) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="chrono/localtime" title="c/chrono/localtime"> <span class="t-lines"><span>localtime</span><span>localtime_r</span><span>localtime_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts time since epoch to calendar time expressed as local time <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="chrono/mktime" title="c/chrono/mktime"> <span class="t-lines"><span>mktime</span></span></a></div> </td> <td> converts calendar time to time since epoch <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <h3 id="Constants"> Constants</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><time.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="chrono/clocks_per_sec" title="c/chrono/CLOCKS PER SEC"> <span class="t-lines"><span>CLOCKS_PER_SEC</span></span></a></div> </td> <td> number of processor clock ticks per second <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> <h3 id="Types"> Types</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><time.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="chrono/tm" title="c/chrono/tm"> <span class="t-lines"><span>tm</span></span></a></div> </td> <td> calendar time type<br><span class="t-mark">(struct)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="chrono/time_t" title="c/chrono/time t"> <span class="t-lines"><span>time_t</span></span></a></div> </td> <td> calendar time since epoch type <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="chrono/clock_t" title="c/chrono/clock t"> <span class="t-lines"><span>clock_t</span></span></a></div> </td> <td> processor time since era type <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="chrono/timespec" title="c/chrono/timespec"> <span class="t-lines"><span>timespec</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> time in seconds and nanoseconds <br><span class="t-mark">(struct)</span> </td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.27 Date and time <time.h> (p: 284-291) </li> +<li> 7.29.5.1 The wcsftime function (p: 320-321) </li> +<li> 7.31.14 Date and time <time.h> (p: 333) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.27 Date and time <time.h> (p: 388-397) </li> +<li> 7.29.5.1 The wcsftime function (p: 439-440) </li> +<li> 7.31.14 Date and time <time.h> (p: 456) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.23 Date and time <time.h> (p: 338-347) </li> +<li> 7.24.5.1 The wcsftime function (p: 385-386) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.12 DATE AND TIME <time.h> </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/chrono/c" title="cpp/chrono/c">C++ documentation</a></span> for <span class=""><span>C Date and time utilities</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/chrono" class="_attribution-link">https://en.cppreference.com/w/c/chrono</a> + </p> +</div> diff --git a/devdocs/c/comment.html b/devdocs/c/comment.html new file mode 100644 index 00000000..07ac5f27 --- /dev/null +++ b/devdocs/c/comment.html @@ -0,0 +1,86 @@ + <h1 id="firstHeading" class="firstHeading">Comments</h1> <p>Comments serve as a sort of in-code documentation. When inserted into a program, they are effectively ignored by the compiler; they are solely intended to be used as notes by the humans that read source code.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>/*</code> <span class="t-spar">comment</span> <code>*/</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>//</code> <span class="t-spar">comment</span> </td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> Often known as "C-style" or "multi-line" comments.</div> <div class="t-li1"> +<span class="t-li">2)</span> Often known as "C++-style" or "single-line" comments.</div> <p>All comments are removed from the program at <a href="language/translation_phases" title="c/language/translation phases">translation phase 3</a> by replacing each comment with a single whitespace character.</p> +<h3 id="C-style"> C-style</h3> <p>C-style comments are usually used to comment large blocks of text or small fragments of code; however, they can be used to comment single lines. To insert text as a C-style comment, simply surround the text with <code>/*</code> and <code>*/</code>. C-style comments tell the compiler to ignore all content between <code>/*</code> and <code>*/</code>. Although it is not part of the C standard, <code>/**</code> and <code>**/</code> are often used to indicate documentation blocks; this is legal because the second asterisk is simply treated as part of the comment.</p> +<p>Except within a <a href="language/character_constant" title="c/language/character constant">character constant</a>, a <a href="language/string_literal" title="c/language/string literal">string literal</a>, or a comment, the characters <code>/*</code> introduce a comment. The contents of such a comment are examined only to identify multibyte characters and to find the characters <code>*/</code> that terminate the comment. C-style comments cannot be nested.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <h3 id="C.2B.2B-style"> C++-style</h3> <p>C++-style comments are usually used to comment single lines of text or code; however, they can be placed together to form multi-line comments. To insert text as a C++-style comment, simply precede the text with <code>//</code> and follow the text with the new line character. C++-style comments tell the compiler to ignore all content between <code>//</code> and a new line.</p> +<p>Except within a <a href="language/character_constant" title="c/language/character constant">character constant</a>, a <a href="language/string_literal" title="c/language/string literal">string literal</a>, or a comment, the characters <code>//</code> introduce a comment that includes all multibyte characters up to, but not including, the next new-line character. The contents of such a comment are examined only to identify multibyte characters and to find the new-line character that terminates the comment. C++-style comments can be nested:</p> +<div class="c source-c"><pre data-language="c">// y = f(x); // invoke algorithm</pre></div> <p>A C-style comment may appear within a C++-style comment:</p> +<div class="c source-c"><pre data-language="c">// y = f(x); /* invoke algorithm */</pre></div> <p>A C++-style comment may appear within a C-style comment; this is a mechanism for excluding a small block of source code:</p> +<div class="c source-c"><pre data-language="c">/* + y = f(x); // invoke algorithms + z = g(x); +*/</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>Because comments <a href="language/translation_phases" title="c/language/translation phases">are removed</a> before the preprocessor stage, a macro cannot be used to form a comment and an unterminated C-style comment doesn't spill over from an #include'd file.</p> +<div class="c source-c"><pre data-language="c">/* An attempt to use a macro to form a comment. */ +/* But, a space replaces characters "//". */ +#ifndef DEBUG + #define PRINTF // +#else + #define PRINTF printf +#endif +... +PRINTF("Error in file %s at line %i\n", __FILE__, __LINE__);</pre></div> <p>Besides commenting out, other mechanisms used for source code exclusion are:</p> +<div class="c source-c"><pre data-language="c">#if 0 + puts("this will not be compiled"); + /* no conflict with C-style comments */ + // no conflict with C++-style comments +#endif</pre></div> <p>and</p> +<div class="c source-c"><pre data-language="c">if(0) { + puts("this will be compiled but not be executed"); + /* no conflict with C-style comments */ + // no conflict with C++-style comments +}</pre></div> <p>The introduction of // comments in C99 was a breaking change in some rare circumstances:</p> +<div class="c source-c"><pre data-language="c">a = b //*divisor:*/ c ++ d; /* C89 compiles a = b / c + d; + C99 compiles a = b + d; */</pre></div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +/* +C-style comments can contain +multiple lines. +*/ + +/* Or, just one line. */ + +// C++-style comments can comment one line. + +// Or, they can +// be strung together. + +int main(void) +{ + // The below code won't be run + // puts("Hello"); + + // The below code will be run + puts("World"); + + // A note regarding backslash + newline. + // Despite belonging to translation phase 2 (vs phase 3 for comments), + // '\' still determines which portion of the source code is considered + // as 'comments': + // This comment will be promoted to the next line \ + puts("Won't be run"); // may issue a warning "multi-line comment" + puts("Hello, again"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">World +Hello, again</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.4.9 Comments (p: 54) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.4.9 Comments (p: 75) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.4.9 Comments (p: 66) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.1.9 Comments </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/comments" title="cpp/comments" class="mw-redirect">C++ documentation</a></span> for <span class=""><span>Comments</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/comment" class="_attribution-link">https://en.cppreference.com/w/c/comment</a> + </p> +</div> diff --git a/devdocs/c/current_status.html b/devdocs/c/current_status.html new file mode 100644 index 00000000..9108bd03 --- /dev/null +++ b/devdocs/c/current_status.html @@ -0,0 +1,11 @@ + <h1 id="firstHeading" class="firstHeading">Current Status</h1> <p><b>Recent milestones: C17 published, C23 underway</b></p> +<p>C17 has been published, and work is now underway on C23.</p> +<p><a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2984.pdf">The current schedule is in paper N2984</a>.</p> +<p>You can also visit <a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/documents">open-std.org</a> to get the latest C standards committee papers. Reading through those proposals, you can track the C developing trends and know how does a cool idea turned into the standard. However, those papers <b>ARE NOT</b> and also <b>SHOULD NOT BE TREATED AS</b> the standard documents.</p> +<h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/current_status" title="cpp/current status">C++ documentation</a></span> for <span class=""><span>Current status</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/current_status" class="_attribution-link">https://en.cppreference.com/w/c/current_status</a> + </p> +</div> diff --git a/devdocs/c/error%2Fabort_handler_s.html b/devdocs/c/error%2Fabort_handler_s.html new file mode 100644 index 00000000..dbf90720 --- /dev/null +++ b/devdocs/c/error%2Fabort_handler_s.html @@ -0,0 +1,51 @@ + <h1 id="firstHeading" class="firstHeading">abort_handler_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">void abort_handler_s( const char * restrict msg, + void * restrict ptr, + errno_t error + );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Writes an implementation-defined message to <code><a href="../io/std_streams" title="c/io/std streams">stderr</a></code> which must include the string pointed to by <code>msg</code> and calls <code><a href="../program/abort" title="c/program/abort">abort()</a></code>.</p> +<p>A pointer to this function can be passed to <a href="set_constraint_handler_s" title="c/error/set constraint handler s">set_constraint_handler_s</a> to establish a runtime constraints violation handler. As with all bounds-checked functions, <code>abort_handler_s</code> is only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <code><stdlib.h></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> msg </td> <td> - </td> <td> pointer to the message written to the standard error stream </td> +</tr> <tr class="t-par"> <td> ptr </td> <td> - </td> <td> pointer to an implementation-defined object or a null pointer. Examples of implementation-defined objects are objects that give the name of the function that detected the violation and the line number when the violation was detected </td> +</tr> <tr class="t-par"> <td> error </td> <td> - </td> <td> a positive value of type errno_t </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>none; this function does not return to its caller</p> +<h3 id="Notes"> Notes</h3> <p>If <code>set_constraint_handler_s</code> is never called, the default handler is implementation-defined: it may be <code>abort_handler_s</code>, <code>ignore_handler_s</code>, or some other implementation-defined handler.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#define __STDC_WANT_LIB_EXT1__ 1 +#include <string.h> +#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ +#ifdef __STDC_LIB_EXT1__ + char dst[2]; + set_constraint_handler_s(ignore_handler_s); + int r = strcpy_s(dst, sizeof dst, "Too long!"); + printf("dst = \"%s\", r = %d\n", dst, r); + set_constraint_handler_s(abort_handler_s); + r = strcpy_s(dst, sizeof dst, "Too long!"); + printf("dst = \"%s\", r = %d\n", dst, r); +#endif +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">dst = "", r = 22 +abort_handler_s was called in response to a runtime-constraint violation. + +The runtime-constraint violation was caused by the following expression in strcpy_s: +(s1max <= (s2_len=strnlen_s(s2, s1max)) ) (in string_s.c:62) + +Note to end users: This program was terminated as a result +of a bug present in the software. Please reach out to your +software's vendor to get more help. +Aborted</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> K.3.6.1.2 The abort_handler_s function (p: 605) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="ignore_handler_s" title="c/error/ignore handler s"> <span class="t-lines"><span>ignore_handler_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> ignore callback for the bounds-checked functions <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="set_constraint_handler_s" title="c/error/set constraint handler s"> <span class="t-lines"><span>set_constraint_handler_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> set the error callback for bounds-checked functions <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/error/abort_handler_s" class="_attribution-link">https://en.cppreference.com/w/c/error/abort_handler_s</a> + </p> +</div> diff --git a/devdocs/c/error%2Fassert.html b/devdocs/c/error%2Fassert.html new file mode 100644 index 00000000..d194a1b0 --- /dev/null +++ b/devdocs/c/error%2Fassert.html @@ -0,0 +1,48 @@ + <h1 id="firstHeading" class="firstHeading">assert</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><assert.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#ifdef NDEBUG +#define assert(condition) ((void)0) +#else +#define assert(condition) /*implementation defined*/ +#endif</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>The definition of the macro <code>assert</code> depends on another macro, <code>NDEBUG</code>, which is not defined by the standard library.</p> +<p>If <code>NDEBUG</code> is defined as a macro name at the point in the source code where <code><assert.h></code> is included, then <code>assert</code> does nothing.</p> +<p>If <code>NDEBUG</code> is not defined, then <code>assert</code> checks if its argument (which must have scalar type) compares equal to zero. If it does, <code>assert</code> outputs implementation-specific diagnostic information on the standard error output and calls <code><a href="http://en.cppreference.com/w/c/program/abort"><span class="kw486">abort</span></a><span class="br0">(</span><span class="br0">)</span></code>. The diagnostic information is required to include the text of <code>expression</code>, as well as the values of <span class="t-rev-inl t-since-c99"><span> the <a href="../language/function_definition" title="c/language/function definition">predefined variable</a> <code>__func__</code> and of</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> the <a href="../preprocessor/replace" title="c/preprocessor/replace">predefined macros</a> <code>__FILE__</code> and <code>__LINE__</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> condition </td> <td> - </td> <td> expression of scalar type </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="Notes"> Notes</h3> <p>There is no standardized interface to add an additional message to <code>assert</code> errors. A portable way to include one is to use a <a href="../language/operator_other#Comma_operator" title="c/language/operator other">comma operator</a>:</p> +<div class="c source-c"><pre data-language="c">assert(("There are five lights", 2 + 2 == 5));</pre></div> <p>The implementation of <code>assert</code> in <a rel="nofollow" class="external text" href="https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/assert-macro-assert-wassert?view=msvc-160">Microsoft CRT</a> does not conform to C99 and later revisions, because its underlying function (<code>_wassert</code>) takes neither <code>__func__</code> nor an equivalent replacement.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +// uncomment to disable assert() +// #define NDEBUG +#include <assert.h> +#include <math.h> + +int main(void) +{ + double x = -1.0; + assert(x >= 0.0); + printf("sqrt(x) = %f\n", sqrt(x)); + + return 0; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">output with NDEBUG not defined: +a.out: main.cpp:10: main: Assertion `x >= 0.0' failed. + +output with NDEBUG defined: +sqrt(x) = -nan</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.2.1.1 The assert macro (p: 135) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.2.1.1 The assert macro (p: 186-187) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.2.1.1 The assert macro (p: 169) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.2.1.1 The assert macro </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../program/abort" title="c/program/abort"> <span class="t-lines"><span>abort</span></span></a></div> </td> <td> causes abnormal program termination (without cleaning up) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/error/assert" title="cpp/error/assert">C++ documentation</a></span> for <code>assert</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/error/assert" class="_attribution-link">https://en.cppreference.com/w/c/error/assert</a> + </p> +</div> diff --git a/devdocs/c/error%2Ferrno.html b/devdocs/c/error%2Ferrno.html new file mode 100644 index 00000000..687e991b --- /dev/null +++ b/devdocs/c/error%2Ferrno.html @@ -0,0 +1,78 @@ + <h1 id="firstHeading" class="firstHeading">errno</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><errno.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define errno /*implementation-defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p><code>errno</code> is a preprocessor macro (but see note below) that expands to a <span class="t-rev-inl t-since-c11"><span>thread-local</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> modifiable lvalue of type <code>int</code>. Several standard library functions indicate errors by writing positive integers to <code>errno</code>. Typically, the value of <code>errno</code> is set to one of the error codes listed in <code><errno.h></code> as macro constants beginning with the letter <code>E</code> followed by uppercase letters or digits.</p> +<p>The value of <code>errno</code> is <code>0</code> at program startup, and although library functions are allowed to write positive integers to <code>errno</code> whether or not an error occurred, library functions never store <code>0</code> in <code>errno</code>.</p> +<p>Library functions <code><a href="../io/perror" title="c/io/perror">perror</a></code> and <code><a href="../string/byte/strerror" title="c/string/byte/strerror">strerror</a></code> can be used to obtain textual descriptions of the error conditions that correspond to the current <code>errno</code> value.</p> +<p>Note: Until C11, the C standards had contradictory requirements, in that they said that <code>errno</code> is a macro but <i>also</i> that "it is unspecified whether <code>errno</code> is a macro or an identifier declared with external linkage". C11 fixes this, requiring that it be defined as a macro (see also WG14 <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1338.htm">N1338</a>).</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <errno.h> + +void show_errno(void) +{ + const char *err_info = "unknown error"; + switch (errno) { + case EDOM: + err_info = "domain error"; + break; + case EILSEQ: + err_info = "illegal sequence"; + break; + case ERANGE: + err_info = "pole or range error"; + break; + case 0: + err_info = "no error"; + } + fputs(err_info, stdout); + puts(" occurred"); +} + +int main(void) +{ + fputs("MATH_ERRNO is ", stdout); + puts(math_errhandling & MATH_ERRNO ? "set" : "not set"); + + errno = 0; + 1.0/0.0; + show_errno(); + + errno = 0; + acos(+1.1); + show_errno(); + + errno = 0; + log(0.0); + show_errno(); + + errno = 0; + sin(0.0); + show_errno(); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">MATH_ERRNO is set +no error occurred +domain error occurred +pole or range error occurred +no error occurred</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.5 Errors <errno.h> (p: 205) </li> +<li> K.3.1.3 Use of errno (p: 584) </li> +<li> K.3.2 Errors <errno.h> (p: 585) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.5 Errors <errno.h> (p: 186) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.1.3 Errors <errno.h> </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="errno_macros" title="c/error/errno macros"> <span class="t-lines"><span>E2BIG, EACCES, ..., EXDEV</span></span></a></div> </td> <td> macros for standard POSIX-compatible error conditions <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../io/perror" title="c/io/perror"> <span class="t-lines"><span>perror</span></span></a></div> </td> <td> displays a character string corresponding of the current error to <code><a href="../io/std_streams" title="c/io/std streams">stderr</a></code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../string/byte/strerror" title="c/string/byte/strerror"> <span class="t-lines"><span>strerror</span><span>strerror_s</span><span>strerrorlen_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> returns a text version of a given error code <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../numeric/math/math_errhandling" title="c/numeric/math/math errhandling"> <span class="t-lines"><span>math_errhandling</span><span>MATH_ERRNO</span><span>MATH_ERREXCEPT</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> defines the error handling mechanism used by the common mathematical functions <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/error/errno" title="cpp/error/errno">C++ documentation</a></span> for <code>errno</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/error/errno" class="_attribution-link">https://en.cppreference.com/w/c/error/errno</a> + </p> +</div> diff --git a/devdocs/c/error%2Ferrno_macros.html b/devdocs/c/error%2Ferrno_macros.html new file mode 100644 index 00000000..5ecee98f --- /dev/null +++ b/devdocs/c/error%2Ferrno_macros.html @@ -0,0 +1,44 @@ + <h1 id="firstHeading" class="firstHeading">Error numbers</h1> <p>Each of the macros defined in <code><errno.h></code> expands to an integer constant expression with type <code>int</code> and with a unique positive value. The following constants are defined by ISO C. The implementation may define more, as long as they begin with <code>'E'</code> followed by digits or uppercase letters.</p> +<table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><errno.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>EDOM</span></span></div> </td> <td> Mathematics argument out of domain of function <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>EILSEQ</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> Illegal byte sequence <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>ERANGE</span></span></div> </td> <td> Result too large <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>Many additional errno constants are <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/errno.h.html">defined by POSIX</a> and by the <a href="https://en.cppreference.com/w/cpp/error/errno_macros" title="cpp/error/errno macros">C++ standard library</a>, and individual implementations may define even more, e.g. <code>errno(3)</code> on Linux or <code>intro(2)</code> on BSD and OS X.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <errno.h> +#include <string.h> + +int main(void) +{ + errno = 0; + printf("log(-1.0) = %f\n", log(-1.0)); + printf("%s\n\n",strerror(errno)); + + errno = 0; + printf("log(0.0) = %f\n", log(0.0)); + printf("%s\n",strerror(errno)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">log(-1.0) = nan +Numerical argument out of domain + +log(0.0) = -inf +Numerical result out of range</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.5/2 Errors <errno.h> (p: 205) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.5/2 Errors <errno.h> (p: 186) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.1.3 Errors <errno.h> </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="errno" title="c/error/errno"> <span class="t-lines"><span>errno</span></span></a></div> </td> <td> macro which expands to POSIX-compatible thread-local error number variable<br><span class="t-mark">(macro variable)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../io/perror" title="c/io/perror"> <span class="t-lines"><span>perror</span></span></a></div> </td> <td> displays a character string corresponding of the current error to <code><a href="../io/std_streams" title="c/io/std streams">stderr</a></code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../string/byte/strerror" title="c/string/byte/strerror"> <span class="t-lines"><span>strerror</span><span>strerror_s</span><span>strerrorlen_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> returns a text version of a given error code <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/error/errno_macros" title="cpp/error/errno macros">C++ documentation</a></span> for <span class=""><span>Error numbers</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/error/errno_macros" class="_attribution-link">https://en.cppreference.com/w/c/error/errno_macros</a> + </p> +</div> diff --git a/devdocs/c/error%2Fignore_handler_s.html b/devdocs/c/error%2Fignore_handler_s.html new file mode 100644 index 00000000..844d8b6b --- /dev/null +++ b/devdocs/c/error%2Fignore_handler_s.html @@ -0,0 +1,52 @@ + <h1 id="firstHeading" class="firstHeading">ignore_handler_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">void ignore_handler_s( const char * restrict msg, + void * restrict ptr, + errno_t error + );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>The function simply returns to the caller without performing any other action.</p> +<p>A pointer to this function can be passed to <a href="set_constraint_handler_s" title="c/error/set constraint handler s">set_constraint_handler_s</a> to establish a runtime constraints violation handler that does nothing. As with all bounds-checked functions, <code>ignore_handler_s</code> is only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <code><stdlib.h></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> msg </td> <td> - </td> <td> pointer to character string that describes the error </td> +</tr> <tr class="t-par"> <td> ptr </td> <td> - </td> <td> pointer to an implementation-defined object or a null pointer. Examples of implementation-defined objects are objects that give the name of the function that detected the violation and the line number when the violation was detected </td> +</tr> <tr class="t-par"> <td> error </td> <td> - </td> <td> the error about to be returned by the calling function, if it happens to be one of the functions that return errno_t </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="Notes"> Notes</h3> <p>If <code>ignore_handler_s</code> is used as a the runtime constraints handler, the violations may be detected by examining the results of the bounds-checked function calls, which may be different for different functions (non-zero <code>errno_t</code>, null character written to the first byte of the output string, etc)</p> +<p>If <code>set_constraint_handler_s</code> is never called, the default handler is implementation-defined: it may be <code>abort_handler_s</code>, <code>ignore_handler_s</code>, or some other implementation-defined handler.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#define __STDC_WANT_LIB_EXT1__ 1 +#include <string.h> +#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ +#ifdef __STDC_LIB_EXT1__ + char dst[2]; + set_constraint_handler_s(ignore_handler_s); + int r = strcpy_s(dst, sizeof dst, "Too long!"); + printf("dst = \"%s\", r = %d\n", dst, r); + set_constraint_handler_s(abort_handler_s); + r = strcpy_s(dst, sizeof dst, "Too long!"); + printf("dst = \"%s\", r = %d\n", dst, r); +#endif +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">dst = "", r = 22 +abort_handler_s was called in response to a runtime-constraint violation. + +The runtime-constraint violation was caused by the following expression in strcpy_s: +(s1max <= (s2_len=strnlen_s(s2, s1max)) ) (in string_s.c:62) + +Note to end users: This program was terminated as a result +of a bug present in the software. Please reach out to your +software's vendor to get more help. +Aborted</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> K.3.6.1.3 The ignore_handler_s function (p: 606) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="abort_handler_s" title="c/error/abort handler s"> <span class="t-lines"><span>abort_handler_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> abort callback for the bounds-checked functions <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="set_constraint_handler_s" title="c/error/set constraint handler s"> <span class="t-lines"><span>set_constraint_handler_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> set the error callback for bounds-checked functions <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/error/ignore_handler_s" class="_attribution-link">https://en.cppreference.com/w/c/error/ignore_handler_s</a> + </p> +</div> diff --git a/devdocs/c/error%2Fset_constraint_handler_s.html b/devdocs/c/error%2Fset_constraint_handler_s.html new file mode 100644 index 00000000..d8c0c19e --- /dev/null +++ b/devdocs/c/error%2Fset_constraint_handler_s.html @@ -0,0 +1,57 @@ + <h1 id="firstHeading" class="firstHeading">set_constraint_handler_s, constraint_handler_t</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">constraint_handler_t set_constraint_handler_s( constraint_handler_t handler );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Configures the handler to be called by all <a href="../error#Bounds_checking" title="c/error">bounds-checked functions</a> on a runtime constraint violation or restores the default handler (if <code>handler</code> is a null pointer)</p> +<p>The handler must be a pointer to function of type <code>constraint_handler_t</code>, which is defined as</p> +<table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">typedef void (*constraint_handler_t)( const char *restrict msg, + void *restrict ptr, + errno_t error);</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>On a runtime constraint violation, it is called with the following arguments:</p> +<div class="t-li1"> +<span class="t-li">1)</span> pointer to character string that describes the error</div> <div class="t-li1"> +<span class="t-li">2)</span> pointer to an implementation-defined object or a null pointer. Examples of implementation-defined objects are objects that give the name of the function that detected the violation and the line number when the violation was detected</div> <div class="t-li1"> +<span class="t-li">3)</span> the error about to be returned by the calling function, if it happens to be one of the functions that return <code>errno_t</code> +</div> <p>If <code>set_constraint_handler_s</code> is never called, the default handler is implementation-defined: it may be <code>abort_handler_s</code>, <code>ignore_handler_s</code>, or some other implementation-defined handler. As with all bounds-checked functions, <code>set_constraint_handler_s</code> and <code>constraint_handler_t</code> are only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <code><stdlib.h></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> handler </td> <td> - </td> <td> pointer to function of type <code>constraint_handler_t</code> or a null pointer </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>A pointer to the previously-installed runtime constraints handler. (note: this pointer is never a null pointer because calling <code>set_constraint_handler_s<span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/NULL"><span class="kw103">NULL</span></a><span class="br0">)</span></code> sets up the system default handler)</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#define __STDC_WANT_LIB_EXT1__ 1 +#include <string.h> +#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ +#ifdef __STDC_LIB_EXT1__ + char dst[2]; + set_constraint_handler_s(ignore_handler_s); + int r = strcpy_s(dst, sizeof dst, "Too long!"); + printf("dst = \"%s\", r = %d\n", dst, r); + set_constraint_handler_s(abort_handler_s); + r = strcpy_s(dst, sizeof dst, "Too long!"); + printf("dst = \"%s\", r = %d\n", dst, r); +#endif +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">dst = "", r = 22 +abort_handler_s was called in response to a runtime-constraint violation. + +The runtime-constraint violation was caused by the following expression in strcpy_s: +(s1max <= (s2_len=strnlen_s(s2, s1max)) ) (in string_s.c:62) + +Note to end users: This program was terminated as a result +of a bug present in the software. Please reach out to your +software's vendor to get more help. +Aborted</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> K.3.6/2 constraint_handler_t (p: 604) </li> +<li> K.3.6.1.1 The set_constraint_handler_s function (p: 604-605) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="abort_handler_s" title="c/error/abort handler s"> <span class="t-lines"><span>abort_handler_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> abort callback for the bounds-checked functions <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ignore_handler_s" title="c/error/ignore handler s"> <span class="t-lines"><span>ignore_handler_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> ignore callback for the bounds-checked functions <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/error/set_constraint_handler_s" class="_attribution-link">https://en.cppreference.com/w/c/error/set_constraint_handler_s</a> + </p> +</div> diff --git a/devdocs/c/error%2Fstatic_assert.html b/devdocs/c/error%2Fstatic_assert.html new file mode 100644 index 00000000..59b96576 --- /dev/null +++ b/devdocs/c/error%2Fstatic_assert.html @@ -0,0 +1,23 @@ + <h1 id="firstHeading" class="firstHeading">static_assert</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><assert.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11 t-until-c23"> <td> <pre data-language="c">#define static_assert _Static_assert</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> <br><span class="t-mark-rev t-until-c23">(removed in C23)</span> </td> </tr> </table> <p>This convenience macro expands to the keyword <a href="../keyword/_static_assert" title="c/keyword/ Static assert"><code>_Static_assert</code></a>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <assert.h> + +int main(void) +{ + static_assert(2 + 2 == 4, "2+2 isn't 4"); // well-formed + + static_assert(sizeof(int) < sizeof(char), // compile-time error + "this program requires that int is less than char"); +}</pre></div> </div> <h3 id="Notes"> Notes</h3> <p>Since C23, <a href="../language/_static_assert" title="c/language/ Static assert"><code>static_assert</code></a> is itself a keyword, which may also be a predefined macro, so <a href="../error" title="c/error"><code><assert.h></code></a> no longer provides it.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.2/3 Diagnostics <assert.h> (p: 135) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.2/3 Diagnostics <assert.h> (p: 186) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/static_assert" title="cpp/language/static assert">C++ documentation</a></span> for <code>Static Assertion</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/error/static_assert" class="_attribution-link">https://en.cppreference.com/w/c/error/static_assert</a> + </p> +</div> diff --git a/devdocs/c/error.html b/devdocs/c/error.html new file mode 100644 index 00000000..935abf5e --- /dev/null +++ b/devdocs/c/error.html @@ -0,0 +1,78 @@ + <h1 id="firstHeading" class="firstHeading">Error handling</h1> <h3 id="Error_numbers"> Error numbers</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><errno.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="error/errno" title="c/error/errno"> <span class="t-lines"><span>errno</span></span></a></div> </td> <td> macro which expands to POSIX-compatible thread-local error number variable<br><span class="t-mark">(macro variable)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="error/errno_macros" title="c/error/errno macros"> <span class="t-lines"><span>E2BIG, EACCES, ..., EXDEV</span></span></a></div> </td> <td> macros for standard POSIX-compatible error conditions <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> <h3 id="Assertions"> Assertions</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><assert.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="error/assert" title="c/error/assert"> <span class="t-lines"><span>assert</span></span></a></div> </td> <td> aborts the program if the user-specified condition is not <code>true</code>. May be disabled for release builds <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="error/static_assert" title="c/error/static assert"> <span class="t-lines"><span>static_assert</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span><span class="t-mark-rev t-until-c23">(removed in C23)</span></span></span></div> </td> <td> issues a compile-time diagnostic if the value of a constant expression is false <br> <span class="t-mark">(keyword macro)</span> </td> +</tr> </table> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <h3 id="Bounds_checking"> Bounds checking</h3> <p>The standard library provides bounds-checked versions of some existing functions (<code><a href="io/gets" title="c/io/gets">gets_s</a></code>, <code><a href="io/fopen" title="c/io/fopen">fopen_s</a></code>, <code><a href="io/fprintf" title="c/io/fprintf">printf_s</a></code>, <code><a href="string/byte/strcpy" title="c/string/byte/strcpy">strcpy_s</a></code>, <code><a href="string/wide/wcscpy" title="c/string/wide/wcscpy">wcscpy_s</a></code>, <code><a href="string/multibyte/mbstowcs" title="c/string/multibyte/mbstowcs">mbstowcs_s</a></code>, <code><a href="algorithm/qsort" title="c/algorithm/qsort">qsort_s</a></code>, <code><a href="program/getenv" title="c/program/getenv">getenv_s</a></code>, etc). This functionality is <i>optional</i> and is only available if <code>__STDC_LIB_EXT1__</code> is defined. The following macros and functions support this functionality.</p> +<table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><errno.h></code> </th> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdio.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>errno_t</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> a typedef for the type <code>int</code>, used to self-document functions that return <code><a href="error/errno" title="c/error/errno">errno</a></code> values <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stddef.h></code> </th> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdio.h></code> </th> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdlib.h></code> </th> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><string.h></code> </th> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><time.h></code> </th> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><wchar.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>rsize_t</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> a typedef for the same type as <code><a href="types/size_t" title="c/types/size t">size_t</a></code>, used to self-document functions that range-check their parameters at runtime <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdint.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>RSIZE_MAX</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> largest acceptable size for bounds-checked functions, expands to either constant or variable which may change at runtime (e.g. as the currently allocated memory size changes)<br><span class="t-mark">(macro variable)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdlib.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="error/set_constraint_handler_s" title="c/error/set constraint handler s"> <span class="t-lines"><span>set_constraint_handler_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> set the error callback for bounds-checked functions <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="error/abort_handler_s" title="c/error/abort handler s"> <span class="t-lines"><span>abort_handler_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> abort callback for the bounds-checked functions <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="error/ignore_handler_s" title="c/error/ignore handler s"> <span class="t-lines"><span>ignore_handler_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> ignore callback for the bounds-checked functions <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <p>Note: implementations of bounds-checked functions are available as open-source libraries <a rel="nofollow" class="external text" href="https://github.com/rurban/safeclib/">Safe C</a> and <a rel="nofollow" class="external text" href="https://code.google.com/archive/p/slibc/">Slibc</a>, and as part of Watcom C. There is also an incompatible set of bounds-checked functions available in Visual Studio.</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>Since C23, <a href="language/_static_assert" title="c/language/ Static assert"><code>static_assert</code></a> is itself a keyword, which may also be a predefined macro, so <code><assert.h></code> no longer provides it.</p> +<h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.2 Diagnostics <assert.h> (p: 186-187) </li> +<li> 7.5 Errors <errno.h> (p: 205) </li> +<li> 7.19 Common definitions <stddef.h> (p: 288) </li> +<li> 7.20 Integer types <stdint.h> (p: 289-295) </li> +<li> 7.21 Input/output <stdio.h> (p: 296-339) </li> +<li> 7.22 General utilities <stdlib.h> (p: 340-360) </li> +<li> K.3.1.3 Use of errno (p: 584) </li> +<li> K.3.2/2 errno_t (p: 585) </li> +<li> K.3.3/2 rsize_t (p: 585) </li> +<li> K.3.4/2 RSIZE_MAX (p: 585) </li> +<li> 7.31.3 Errors <errno.h> (p: 455) </li> +<li> 7.31.10 Integer types <stdint.h> (p: 456) </li> +<li> 7.31.11 Input/output <stdio.h> (p: 456) </li> +<li> 7.31.12 General utilities <stdlib.h> (p: 456) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.2 Diagnostics <assert.h> (p: 169) </li> +<li> 7.5 Errors <errno.h> (p: 186) </li> +<li> 7.26.3 Errors <errno.h> (p: 401) </li> +<li> 7.26.8 Integer types <stdint.h> (p: 401) </li> +<li> 7.26.9 Input/output <stdio.h> (p: 402) </li> +<li> 7.26.10 General utilities <stdlib.h> (p: 402) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 4.2 DIAGNOSTICS <assert.h> </li> +<li> 4.1.3 Errors <errno.h> </li> +<li> 4.13.1 Errors <errno.h> </li> +<li> 4.13.6 Input/output <stdio.h> </li> +<li> 4.13.7 General utilities <stdlib.h> </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="numeric/math/math_errhandling" title="c/numeric/math/math errhandling"> <span class="t-lines"><span>math_errhandling</span><span>MATH_ERRNO</span><span>MATH_ERREXCEPT</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> defines the error handling mechanism used by the common mathematical functions <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/error" title="cpp/error">C++ documentation</a></span> for <span class=""><span>Error handling</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/error" class="_attribution-link">https://en.cppreference.com/w/c/error</a> + </p> +</div> diff --git a/devdocs/c/index b/devdocs/c/index new file mode 100644 index 00000000..00a36344 --- /dev/null +++ b/devdocs/c/index @@ -0,0 +1 @@ +((pages . ["index" "language" "numeric/math" "types" "program" "variadic" "memory" "numeric/fenv" "types/limits" "language/_noreturn" "numeric/random" "string/multibyte" "numeric/tgmath" "string/wide" "keyword" "preprocessor" "string" "language/expressions" "language/initialization" "language/basic_concepts" "language/declarations" "language/functions" "language/history" "comment" "language/ascii" "language/charset" "error" "algorithm" "chrono" "language/translation_phases" "thread" "language/punctuators" "language/identifier" "language/scope" "language/arithmetic_types" "language/object" "language/main_function" "language/as_if" "language/behavior" "language/memory_model" "language/statements" "preprocessor/conditional" "preprocessor/replace" "preprocessor/include" "preprocessor/impl" "numeric" "locale" "language/lifetime" "preprocessor/line" "preprocessor/embed" "language/if" "language/switch" "string/byte" "language/while" "language/do" "language/continue" "language/goto" "language/return" "language/eval_order" "language/character_constant" "language/operator_alternative" "language/string_literal" "language/compound_literal" "io" "numeric/complex" "types/integer" "language/name_space" "preprocessor/error" "language/bool_constant" "language/nullptr" "language/type" "language/for" "language/break" "language/constant_expression" "language/conversion" "language/operator_member_access" "language/operator_logical" "language/operator_comparison" "language/operator_arithmetic" "language/operator_assignment" "language/value_category" "language/integer_constant" "language/floating_constant" "language/sizeof" "language/operator_precedence" "language/array_initialization" "language/struct_initialization" "language/pointer" "language/enum" "language/operator_other" "language/_alignof" "language/cast" "language/generic" "language/struct" "language/union" "language/bit_field" "language/_alignas" "language/_static_assert" "language/atomic" "language/extern" "language/attributes" "language/function_declaration" "language/inline" "language/analyzability" "language/function_definition" "language/operator_incdec" "language/typedef" "numeric/math/remquo" "numeric/math/fdim" "numeric/math/fma" "numeric/math/nan" "numeric/math/fmax" "numeric/math/fmin" "language/variadic" "language/conformance" "language/asm" "numeric/math/exp" "numeric/math/exp2" "numeric/math/div" "numeric/math/fmod" "numeric/math/log1p" "numeric/math/hypot" "numeric/math/pow" "language/scalar_initialization" "language/storage_duration" "language/const" "numeric/math/abs" "numeric/math/fabs" "numeric/math/remainder" "numeric/math/sqrt" "numeric/math/sin" "numeric/math/cos" "numeric/math/expm1" "numeric/math/log" "numeric/math/log2" "numeric/math/cbrt" "numeric/math/tan" "numeric/math/asin" "numeric/math/acos" "numeric/math/log10" "numeric/math/atan" "numeric/math/sinpi" "numeric/math/cosh" "numeric/math/tanh" "numeric/math/atan2" "numeric/math/sinh" "numeric/math/atanh" "numeric/math/erf" "numeric/math/erfc" "numeric/math/lgamma" "language/array" "language/volatile" "language/restrict" "numeric/math/cospi" "numeric/math/asinh" "numeric/math/acosh" "numeric/math/tgamma" "numeric/math/ceil" "numeric/math/floor" "numeric/math/round" "numeric/math/roundeven" "numeric/math/trunc" "numeric/math/nearbyint" "numeric/math/rint" "numeric/math/ldexp" "numeric/math/frexp" "numeric/math/scalbn" "numeric/math/ilogb" "numeric/math/logb" "numeric/math/modf" "numeric/math/copysign" "numeric/math/isfinite" "numeric/math/signbit" "numeric/math/isunordered" "numeric/math/fpclassify" "numeric/math/isnormal" "numeric/math/isgreaterequal" "numeric/math/isless" "numeric/math/float_t" "numeric/math/huge_val" "numeric/math/infinity" "types/size_t" "numeric/math/nextafter" "numeric/math/isinf" "numeric/math/isnan" "numeric/math/islessequal" "numeric/math/fp_categories" "numeric/math/math_errhandling" "types/ptrdiff_t" "types/nullptr_t" "types/null" "types/max_align_t" "keyword/_bool" "numeric/math/isgreater" "numeric/math/islessgreater" "program/_exit" "program/atexit" "program/at_quick_exit" "program/getenv" "program/sig_atomic_t" "program/sig_strategies" "program/sig_err" "program/sig_types" "variadic/va_start" "program/setjmp" "program/longjmp" "program/jmp_buf" "variadic/va_arg" "variadic/va_copy" "variadic/va_end" "variadic/va_list" "memory/malloc" "io/fprintf" "memory/calloc" "program/quick_exit" "program/unreachable" "program/raise" "memory/free" "memory/free_sized" "memory/free_aligned_sized" "memory/aligned_alloc" "language/types" "keyword/_alignas" "keyword/_alignof" "numeric/fenv/feclearexcept" "numeric/fenv/fetestexcept" "numeric/fenv/feenv" "numeric/fenv/fe_exceptions" "language/attributes/noreturn" "numeric/fenv/fe_round" "numeric/fenv/fe_dfl_env" "types/limits/flt_eval_method" "thread/thrd_exit" "numeric/random/rand" "string/multibyte/btowc" "string/multibyte/mbsrtowcs" "types/limits/flt_rounds" "string/multibyte/mbrtoc8" "program/system" "program/exit_status" "program/signal" "numeric/random/srand" "string/multibyte/c8rtomb" "types/offsetof" "keyword/_noreturn" "program/abort" "program/exit" "numeric/random/rand_max" "string/multibyte/mbsinit" "string/multibyte/mbstowcs" "string/multibyte/mbrtoc16" "numeric/fenv/feexceptflag" "string/multibyte/wctob" "string/multibyte/wcsrtombs" "string/multibyte/mbstate_t" "string/multibyte/mbrlen" "string/multibyte/char8_t" "string/multibyte/char16_t" "string/multibyte/char32_t" "keyword/_generic" "memory/realloc" "numeric/complex/cabs" "numeric/complex/cexp" "numeric/complex/clog" "numeric/complex/cpow" "string/multibyte/mbrtowc" "string/multibyte/c16rtomb" "numeric/complex/csqrt" "numeric/complex/csin" "numeric/complex/ctan" "numeric/fenv/feround" "string/multibyte/c32rtomb" "string/multibyte/mbrtoc32" "string/multibyte/mbtowc" "numeric/complex/ccos" "numeric/complex/casin" "numeric/complex/cacos" "numeric/complex/catan" "numeric/complex/csinh" "numeric/complex/ccosh" "numeric/complex/ctanh" "numeric/complex/cacosh" "numeric/complex/catanh" "numeric/complex/carg" "numeric/complex/creal" "string/wide/iswalnum" "numeric/fenv/feraiseexcept" "numeric/fenv/feholdexcept" "numeric/fenv/feupdateenv" "string/multibyte/mblen" "string/wide/iswlower" "string/wide/iswupper" "string/wide/iswdigit" "string/wide/iswxdigit" "numeric/complex/casinh" "numeric/complex/conj" "numeric/complex/cimag" "numeric/complex/cproj" "string/wide/iswblank" "string/wide/wctype" "string/wide/iswcntrl" "string/multibyte/wctomb" "string/multibyte/wcrtomb" "string/wide/iswalpha" "string/wide/iswgraph" "string/wide/iswspace" "string/wide/iswprint" "string/wide/iswpunct" "string/wide/towlower" "string/wide/towupper" "string/wide/wctrans" "string/wide/towctrans" "string/multibyte/wcstombs" "string/wide/iswctype" "string/wide/wcstol" "string/wide/wcstoul" "string/wide/wcstof" "string/wide/wcstoimax" "string/wide/wcslen" "string/wide/wcscpy" "string/wide/wcsncpy" "string/wide/wcscat" "string/wide/wcsncat" "string/wide/wcsstr" "string/wide/wcsncmp" "string/wide/wcscoll" "string/wide/wcsxfrm" "string/wide/wcschr" "string/wide/wcsrchr" "string/wide/wcspbrk" "string/wide/wcsspn" "string/wide/wcscmp" "string/wide/wcstok" "string/wide/wmemcpy" "string/wide/wmemmove" "locale/lc_categories" "string/byte/isspace" "string/byte/isblank" "string/byte/isgraph" "string/byte/isdigit" "string/wide/wcscspn" "string/wide/wmemcmp" "string/wide/wmemchr" "string/wide/wmemset" "string/byte/iscntrl" "string/byte/isxdigit" "keyword/alignas" "keyword/alignof" "keyword/auto" "keyword/bool" "string/byte/isprint" "string/byte/ispunct" "string/byte/isalpha" "keyword/break" "keyword/case" "keyword/char" "keyword/const" "keyword/continue" "keyword/double" "keyword/enum" "keyword/false" "keyword/if" "keyword/nullptr" "string/byte/isalnum" "string/byte/isupper" "string/byte/islower" "keyword/goto" "keyword/int" "keyword/constexpr" "keyword/default" "keyword/do" "keyword/for" "keyword/inline" "keyword/long" "keyword/restrict" "keyword/return" "keyword/signed" "keyword/sizeof" "keyword/else" "keyword/extern" "keyword/float" "keyword/register" "keyword/short" "keyword/static" "keyword/static_assert" "keyword/struct" "keyword/switch" "keyword/thread_local" "keyword/typedef" "keyword/typeof" "keyword/typeof_unqual" "keyword/unsigned" "keyword/_static_assert" "thread/thread_local" "language/typeof" "keyword/void" "keyword/true" "keyword/volatile" "keyword/_atomic" "locale/lconv" "io/tmpnam" "io/setvbuf" "chrono/strftime" "io/gets" "17" "keyword/_imaginary" "error/errno_macros" "23" "io/fopen" "string/byte/strcpy" "keyword/_decimal128" "keyword/fortran" "keyword/_thread_local" "algorithm/qsort" "algorithm/bsearch" "chrono/difftime" "chrono/time" "error/errno" "error/static_assert" "chrono/timespec_getres" "keyword/union" "language/constexpr" "error/assert" "error/set_constraint_handler_s" "chrono/asctime" "chrono/ctime" "chrono/gmtime" "chrono/localtime" "keyword/while" "chrono/clocks_per_sec" "chrono/tm" "chrono/time_t" "error/abort_handler_s" "chrono/clock_t" "language/escape" "thread/thrd_create" "thread/thrd_equal" "error/ignore_handler_s" "chrono/clock" "chrono/timespec_get" "thread/thrd_join" "thread/thrd_errors" "atomic/atomic_init" "atomic/atomic_var_init" "chrono/wcsftime" "atomic/atomic_lock_free_consts" "atomic/atomic_is_lock_free" "atomic/atomic_store" "atomic/atomic_load" "atomic/atomic_exchange" "keyword/_complex" "chrono/mktime" "atomic/atomic_compare_exchange" "atomic/atomic_fetch_add" "atomic/atomic_fetch_sub" "atomic/atomic_fetch_or" "atomic/atomic_fetch_xor" "chrono/timespec" "thread/thrd_current" "thread/thrd_sleep" "thread/thrd_yield" "thread/thrd_detach" "atomic/atomic_fetch_and" "atomic/atomic_flag" "atomic/atomic_flag_init" "atomic/atomic_flag_test_and_set" "atomic/atomic_flag_clear" "atomic/memory_order" "atomic/atomic_signal_fence" "thread/mtx_lock" "keyword/_decimal64" "thread/mtx_types" "thread/cnd_wait" "thread/cnd_timedwait" "thread/cnd_destroy" "thread/tss_dtor_iterations" "thread/tss_create" "thread/tss_get" "thread/tss_set" "atomic/kill_dependency" "atomic/atomic_thread_fence" "thread/mtx_init" "thread/tss_delete" "numeric/complex/imaginary_i" "numeric/complex/complex_i" "string/byte/memmove" "keyword/_decimal32" "numeric/complex/complex" "numeric/complex/imaginary" "thread/mtx_trylock" "thread/call_once" "thread/mtx_unlock" "thread/cnd_init" "string/byte/toupper" "string/byte/strfromf" "string/byte/strtoul" "string/byte/strtoimax" "string/byte/strtof" "numeric/complex/cmplx" "string/byte/memcpy" "string/byte/strcat" "string/byte/strtok" "io/tmpfile" "locale/setlocale" "string/byte/strdup" "thread/mtx_timedlock" "io/fread" "string/byte/tolower" "string/byte/strncat" "string/byte/strxfrm" "string/byte/strndup" "string/byte/strlen" "string/byte/strcmp" "string/byte/atoi" "string/byte/atof" "string/byte/strtol" "string/byte/strncpy" "string/byte/strncmp" "string/byte/strcoll" "string/byte/strchr" "string/byte/strrchr" "thread/mtx_destroy" "thread/cnd_signal" "thread/cnd_broadcast" "locale/localeconv" "string/byte/strspn" "string/byte/strcspn" "string/byte/strpbrk" "string/byte/memcmp" "io/fscanf" "io/fpos_t" "io/fgetc" "string/byte/memset" "string/byte/memccpy" "string/byte/strstr" "string/byte/memchr" "io/putchar" "io/puts" "io/ungetc" "io/fgetwc" "io/fgetws" "io/file" "io/freopen" "io/fwide" "io/setbuf" "io/fputwc" "io/fputws" "io/getwchar" "io/putwchar" "io/ungetwc" "io/fwscanf" "io/vfscanf" "io/vfwscanf" "io/fwprintf" "io/vfprintf" "io/vfwprintf" "string/byte/strerror" "io/std_streams" "io/fclose" "io/getchar" "io/rewind" "io/clearerr" "io/ftell" "io/fgetpos" "io/fseek" "io/fsetpos" "io/ferror" "io/perror" "io/remove" "io/rename" "io/fwrite" "io/fgets" "io/fputc" "io/fputs" "language/attributes/fallthrough" "language/attributes/deprecated" "language/attributes/maybe_unused" "language/attributes/unsequenced" "99" "io/feof" "numeric/complex/i" "language/attributes/nodiscard" "11" "current_status" "atomic" "io/fflush" "language/static_storage_duration" "language/thread_storage_duration" "95" "language/alignas" "language/file_scope" "language/static_assert" "language/attributes/reproducible" "language/alignof" "language/compatible_type"]) (entries . [((name . "#define directive") (path . "preprocessor/replace") (type . "C language")) ((name . "#elif directive") (path . "preprocessor/conditional") (type . "C language")) ((name . "#else directive") (path . "preprocessor/conditional") (type . "C language")) ((name . "#endif directive") (path . "preprocessor/conditional") (type . "C language")) ((name . "#if directive") (path . "preprocessor/conditional") (type . "C language")) ((name . "#ifdef directive") (path . "preprocessor/conditional") (type . "C language")) ((name . "#ifndef directive") (path . "preprocessor/conditional") (type . "C language")) ((name . "#include directive") (path . "preprocessor/include") (type . "C language")) ((name . "#line directive") (path . "preprocessor/line") (type . "C language")) ((name . "#pragma directive") (path . "preprocessor/impl") (type . "C language")) ((name . "_Alignas") (path . "language/_alignas") (type . "C language")) ((name . "_Alignas") (path . "language/alignas") (type . "C language")) ((name . "_Alignas") (path . "keyword/_alignas") (type . "C keywords")) ((name . "_Alignof") (path . "keyword/_alignof") (type . "C keywords")) ((name . "_Alignof operator") (path . "language/_alignof") (type . "C language")) ((name . "_Alignof operator") (path . "language/alignof") (type . "C language")) ((name . "_Atomic") (path . "keyword/_atomic") (type . "C keywords")) ((name . "_Bool") (path . "keyword/_bool") (type . "C keywords")) ((name . "_Complex") (path . "keyword/_complex") (type . "C keywords")) ((name . "_Complex_I") (path . "numeric/complex/complex_i") (type . "Numerics")) ((name . "_Decimal128") (path . "keyword/_decimal128") (type . "C keywords")) ((name . "_Decimal32") (path . "keyword/_decimal32") (type . "C keywords")) ((name . "_Decimal64") (path . "keyword/_decimal64") (type . "C keywords")) ((name . "_Exit") (path . "program/_exit") (type . "Program support")) ((name . "_Generic") (path . "keyword/_generic") (type . "C keywords")) ((name . "_Imaginary") (path . "keyword/_imaginary") (type . "C keywords")) ((name . "_Imaginary_I") (path . "numeric/complex/imaginary_i") (type . "Numerics")) ((name . "_Noreturn") (path . "keyword/_noreturn") (type . "C keywords")) ((name . "_Noreturn (since C23)") (path . "language/attributes/noreturn") (type . "C language")) ((name . "_Noreturn function specifier") (path . "language/_noreturn") (type . "C language")) ((name . "_Static_assert") (path . "keyword/_static_assert") (type . "C keywords")) ((name . "_Thread_local") (path . "keyword/_thread_local") (type . "C keywords")) ((name . "abort") (path . "program/abort") (type . "Program support")) ((name . "abort_handler_s") (path . "error/abort_handler_s") (type . "Error handling")) ((name . "abs") (path . "numeric/math/abs") (type . "Numerics")) ((name . "acos") (path . "numeric/math/acos") (type . "Numerics")) ((name . "acosf") (path . "numeric/math/acos") (type . "Numerics")) ((name . "acosh") (path . "numeric/math/acosh") (type . "Numerics")) ((name . "acoshf") (path . "numeric/math/acosh") (type . "Numerics")) ((name . "acoshl") (path . "numeric/math/acosh") (type . "Numerics")) ((name . "acosl") (path . "numeric/math/acos") (type . "Numerics")) ((name . "Algorithms") (path . "algorithm") (type . "Algorithms")) ((name . "alignas") (path . "keyword/alignas") (type . "C keywords")) ((name . "alignas (since C23)") (path . "language/alignas") (type . "C language")) ((name . "alignas (since C23)") (path . "language/_alignas") (type . "C language")) ((name . "aligned_alloc") (path . "memory/aligned_alloc") (type . "Dynamic memory management")) ((name . "alignof") (path . "keyword/alignof") (type . "C keywords")) ((name . "Alternative operators and tokens") (path . "language/operator_alternative") (type . "C language")) ((name . "Analyzability") (path . "language/analyzability") (type . "C language")) ((name . "Arithmetic operators") (path . "language/operator_arithmetic") (type . "C language")) ((name . "Arithmetic types") (path . "language/arithmetic_types") (type . "C language")) ((name . "Array declaration") (path . "language/array") (type . "C language")) ((name . "Array initialization") (path . "language/array_initialization") (type . "C language")) ((name . "As-if rule") (path . "language/as_if") (type . "C language")) ((name . "ASCII Chart") (path . "language/ascii") (type . "C language")) ((name . "asctime") (path . "chrono/asctime") (type . "Date and time")) ((name . "asctime_s") (path . "chrono/asctime") (type . "Date and time")) ((name . "asin") (path . "numeric/math/asin") (type . "Numerics")) ((name . "asinf") (path . "numeric/math/asin") (type . "Numerics")) ((name . "asinh") (path . "numeric/math/asinh") (type . "Numerics")) ((name . "asinhf") (path . "numeric/math/asinh") (type . "Numerics")) ((name . "asinhl") (path . "numeric/math/asinh") (type . "Numerics")) ((name . "asinl") (path . "numeric/math/asin") (type . "Numerics")) ((name . "assert") (path . "error/assert") (type . "Error handling")) ((name . "Assignment operators") (path . "language/operator_assignment") (type . "C language")) ((name . "at_quick_exit") (path . "program/at_quick_exit") (type . "Program support")) ((name . "atan") (path . "numeric/math/atan") (type . "Numerics")) ((name . "atan2") (path . "numeric/math/atan2") (type . "Numerics")) ((name . "atan2f") (path . "numeric/math/atan2") (type . "Numerics")) ((name . "atan2l") (path . "numeric/math/atan2") (type . "Numerics")) ((name . "atanf") (path . "numeric/math/atan") (type . "Numerics")) ((name . "atanh") (path . "numeric/math/atanh") (type . "Numerics")) ((name . "atanhf") (path . "numeric/math/atanh") (type . "Numerics")) ((name . "atanhl") (path . "numeric/math/atanh") (type . "Numerics")) ((name . "atanl") (path . "numeric/math/atan") (type . "Numerics")) ((name . "atexit") (path . "program/atexit") (type . "Program support")) ((name . "atof") (path . "string/byte/atof") (type . "Strings")) ((name . "atoi") (path . "string/byte/atoi") (type . "Strings")) ((name . "atol") (path . "string/byte/atoi") (type . "Strings")) ((name . "atoll") (path . "string/byte/atoi") (type . "Strings")) ((name . "Atomic operations library") (path . "atomic") (type . "Atomic operations")) ((name . "Atomic types") (path . "language/atomic") (type . "C language")) ((name . "ATOMIC_*_LOCK_FREE") (path . "atomic/atomic_lock_free_consts") (type . "Concurrency support")) ((name . "atomic_compare_exchange_strong") (path . "atomic/atomic_compare_exchange") (type . "Concurrency support")) ((name . "atomic_compare_exchange_strong_explicit") (path . "atomic/atomic_compare_exchange") (type . "Concurrency support")) ((name . "atomic_compare_exchange_weak") (path . "atomic/atomic_compare_exchange") (type . "Concurrency support")) ((name . "atomic_compare_exchange_weak_explicit") (path . "atomic/atomic_compare_exchange") (type . "Concurrency support")) ((name . "atomic_exchange") (path . "atomic/atomic_exchange") (type . "Concurrency support")) ((name . "atomic_exchange_explicit") (path . "atomic/atomic_exchange") (type . "Concurrency support")) ((name . "atomic_fetch_add") (path . "atomic/atomic_fetch_add") (type . "Concurrency support")) ((name . "atomic_fetch_add_explicit") (path . "atomic/atomic_fetch_add") (type . "Concurrency support")) ((name . "atomic_fetch_and") (path . "atomic/atomic_fetch_and") (type . "Concurrency support")) ((name . "atomic_fetch_and_explicit") (path . "atomic/atomic_fetch_and") (type . "Concurrency support")) ((name . "atomic_fetch_or") (path . "atomic/atomic_fetch_or") (type . "Concurrency support")) ((name . "atomic_fetch_or_explicit") (path . "atomic/atomic_fetch_or") (type . "Concurrency support")) ((name . "atomic_fetch_sub") (path . "atomic/atomic_fetch_sub") (type . "Concurrency support")) ((name . "atomic_fetch_sub_explicit") (path . "atomic/atomic_fetch_sub") (type . "Concurrency support")) ((name . "atomic_fetch_xor") (path . "atomic/atomic_fetch_xor") (type . "Concurrency support")) ((name . "atomic_fetch_xor_explicit") (path . "atomic/atomic_fetch_xor") (type . "Concurrency support")) ((name . "atomic_flag") (path . "atomic/atomic_flag") (type . "Concurrency support")) ((name . "atomic_flag_clear") (path . "atomic/atomic_flag_clear") (type . "Concurrency support")) ((name . "atomic_flag_clear_explicit") (path . "atomic/atomic_flag_clear") (type . "Concurrency support")) ((name . "ATOMIC_FLAG_INIT") (path . "atomic/atomic_flag_init") (type . "Concurrency support")) ((name . "atomic_flag_test_and_set") (path . "atomic/atomic_flag_test_and_set") (type . "Concurrency support")) ((name . "atomic_flag_test_and_set_explicit") (path . "atomic/atomic_flag_test_and_set") (type . "Concurrency support")) ((name . "atomic_init") (path . "atomic/atomic_init") (type . "Concurrency support")) ((name . "atomic_is_lock_free") (path . "atomic/atomic_is_lock_free") (type . "Concurrency support")) ((name . "atomic_load") (path . "atomic/atomic_load") (type . "Concurrency support")) ((name . "atomic_load_explicit") (path . "atomic/atomic_load") (type . "Concurrency support")) ((name . "atomic_signal_fence") (path . "atomic/atomic_signal_fence") (type . "Concurrency support")) ((name . "atomic_store") (path . "atomic/atomic_store") (type . "Concurrency support")) ((name . "atomic_store_explicit") (path . "atomic/atomic_store") (type . "Concurrency support")) ((name . "atomic_thread_fence") (path . "atomic/atomic_thread_fence") (type . "Concurrency support")) ((name . "ATOMIC_VAR_INIT") (path . "atomic/atomic_var_init") (type . "Concurrency support")) ((name . "Attribute specifier sequence(since C23)") (path . "language/attributes") (type . "C language")) ((name . "auto") (path . "keyword/auto") (type . "C keywords")) ((name . "Basic concepts") (path . "language/basic_concepts") (type . "C language")) ((name . "Binary resource inclusion") (path . "preprocessor/embed") (type . "C language")) ((name . "Bit-fields") (path . "language/bit_field") (type . "C language")) ((name . "bool") (path . "keyword/bool") (type . "C keywords")) ((name . "break") (path . "keyword/break") (type . "C keywords")) ((name . "break statement") (path . "language/break") (type . "C language")) ((name . "bsearch") (path . "algorithm/bsearch") (type . "Algorithms")) ((name . "bsearch_s") (path . "algorithm/bsearch") (type . "Algorithms")) ((name . "btowc") (path . "string/multibyte/btowc") (type . "Strings")) ((name . "C attribute: deprecated") (path . "language/attributes/deprecated") (type . "C language")) ((name . "C attribute: fallthrough") (path . "language/attributes/fallthrough") (type . "C language")) ((name . "C attribute: maybe_unused") (path . "language/attributes/maybe_unused") (type . "C language")) ((name . "C attribute: nodiscard") (path . "language/attributes/nodiscard") (type . "C language")) ((name . "C attribute: noreturn") (path . "language/attributes/noreturn") (type . "C language")) ((name . "C attribute: unsequenced") (path . "language/attributes/reproducible") (type . "C language")) ((name . "C attribute: unsequenced") (path . "language/attributes/unsequenced") (type . "C language")) ((name . "C keywords") (path . "keyword") (type . "C keywords")) ((name . "C language") (path . "language") (type . "C language")) ((name . "C Operator Precedence") (path . "language/operator_precedence") (type . "C language")) ((name . "C11") (path . "11") (type . "Versions")) ((name . "c16rtomb") (path . "string/multibyte/c16rtomb") (type . "Strings")) ((name . "C17") (path . "17") (type . "Versions")) ((name . "C23") (path . "23") (type . "Versions")) ((name . "c32rtomb") (path . "string/multibyte/c32rtomb") (type . "Strings")) ((name . "c8rtomb") (path . "string/multibyte/c8rtomb") (type . "Strings")) ((name . "C95") (path . "95") (type . "Versions")) ((name . "C99") (path . "99") (type . "Versions")) ((name . "cabs") (path . "numeric/complex/cabs") (type . "Numerics")) ((name . "cabsf") (path . "numeric/complex/cabs") (type . "Numerics")) ((name . "cabsl") (path . "numeric/complex/cabs") (type . "Numerics")) ((name . "cacos") (path . "numeric/complex/cacos") (type . "Numerics")) ((name . "cacosf") (path . "numeric/complex/cacos") (type . "Numerics")) ((name . "cacosh") (path . "numeric/complex/cacosh") (type . "Numerics")) ((name . "cacoshf") (path . "numeric/complex/cacosh") (type . "Numerics")) ((name . "cacoshl") (path . "numeric/complex/cacosh") (type . "Numerics")) ((name . "cacosl") (path . "numeric/complex/cacos") (type . "Numerics")) ((name . "call_once") (path . "thread/call_once") (type . "Concurrency support")) ((name . "calloc") (path . "memory/calloc") (type . "Dynamic memory management")) ((name . "carg") (path . "numeric/complex/carg") (type . "Numerics")) ((name . "cargf") (path . "numeric/complex/carg") (type . "Numerics")) ((name . "cargl") (path . "numeric/complex/carg") (type . "Numerics")) ((name . "case") (path . "keyword/case") (type . "C keywords")) ((name . "casin") (path . "numeric/complex/casin") (type . "Numerics")) ((name . "casinf") (path . "numeric/complex/casin") (type . "Numerics")) ((name . "casinh") (path . "numeric/complex/casinh") (type . "Numerics")) ((name . "casinhf") (path . "numeric/complex/casinh") (type . "Numerics")) ((name . "casinhl") (path . "numeric/complex/casinh") (type . "Numerics")) ((name . "casinl") (path . "numeric/complex/casin") (type . "Numerics")) ((name . "cast operator") (path . "language/cast") (type . "C language")) ((name . "catan") (path . "numeric/complex/catan") (type . "Numerics")) ((name . "catanf") (path . "numeric/complex/catan") (type . "Numerics")) ((name . "catanh") (path . "numeric/complex/catanh") (type . "Numerics")) ((name . "catanhf") (path . "numeric/complex/catanh") (type . "Numerics")) ((name . "catanhl") (path . "numeric/complex/catanh") (type . "Numerics")) ((name . "catanl") (path . "numeric/complex/catan") (type . "Numerics")) ((name . "cbrt") (path . "numeric/math/cbrt") (type . "Numerics")) ((name . "cbrtf") (path . "numeric/math/cbrt") (type . "Numerics")) ((name . "cbrtl") (path . "numeric/math/cbrt") (type . "Numerics")) ((name . "ccos") (path . "numeric/complex/ccos") (type . "Numerics")) ((name . "ccosf") (path . "numeric/complex/ccos") (type . "Numerics")) ((name . "ccosh") (path . "numeric/complex/ccosh") (type . "Numerics")) ((name . "ccoshf") (path . "numeric/complex/ccosh") (type . "Numerics")) ((name . "ccoshl") (path . "numeric/complex/ccosh") (type . "Numerics")) ((name . "ccosl") (path . "numeric/complex/ccos") (type . "Numerics")) ((name . "ceil") (path . "numeric/math/ceil") (type . "Numerics")) ((name . "ceilf") (path . "numeric/math/ceil") (type . "Numerics")) ((name . "ceill") (path . "numeric/math/ceil") (type . "Numerics")) ((name . "cexp") (path . "numeric/complex/cexp") (type . "Numerics")) ((name . "cexpf") (path . "numeric/complex/cexp") (type . "Numerics")) ((name . "cexpl") (path . "numeric/complex/cexp") (type . "Numerics")) ((name . "char") (path . "keyword/char") (type . "C keywords")) ((name . "char16_t") (path . "string/multibyte/char16_t") (type . "Strings")) ((name . "char32_t") (path . "string/multibyte/char32_t") (type . "Strings")) ((name . "char8_t") (path . "string/multibyte/char8_t") (type . "Strings")) ((name . "Character constant") (path . "language/character_constant") (type . "C language")) ((name . "Character sets and encodings") (path . "language/charset") (type . "C language")) ((name . "cimag") (path . "numeric/complex/cimag") (type . "Numerics")) ((name . "cimagf") (path . "numeric/complex/cimag") (type . "Numerics")) ((name . "cimagl") (path . "numeric/complex/cimag") (type . "Numerics")) ((name . "clearerr") (path . "io/clearerr") (type . "File input/output")) ((name . "clock") (path . "chrono/clock") (type . "Date and time")) ((name . "clock_t") (path . "chrono/clock_t") (type . "Date and time")) ((name . "CLOCKS_PER_SEC") (path . "chrono/clocks_per_sec") (type . "Date and time")) ((name . "clog") (path . "numeric/complex/clog") (type . "Numerics")) ((name . "clogf") (path . "numeric/complex/clog") (type . "Numerics")) ((name . "clogl") (path . "numeric/complex/clog") (type . "Numerics")) ((name . "CMPLX") (path . "numeric/complex/cmplx") (type . "Numerics")) ((name . "CMPLXF") (path . "numeric/complex/cmplx") (type . "Numerics")) ((name . "CMPLXL") (path . "numeric/complex/cmplx") (type . "Numerics")) ((name . "cnd_broadcast") (path . "thread/cnd_broadcast") (type . "Concurrency support")) ((name . "cnd_destroy") (path . "thread/cnd_destroy") (type . "Concurrency support")) ((name . "cnd_init") (path . "thread/cnd_init") (type . "Concurrency support")) ((name . "cnd_signal") (path . "thread/cnd_signal") (type . "Concurrency support")) ((name . "cnd_timedwait") (path . "thread/cnd_timedwait") (type . "Concurrency support")) ((name . "cnd_wait") (path . "thread/cnd_wait") (type . "Concurrency support")) ((name . "Comments") (path . "comment") (type . "C language")) ((name . "Common mathematical functions") (path . "numeric/math") (type . "Numerics")) ((name . "Comparison operators") (path . "language/operator_comparison") (type . "C language")) ((name . "complex") (path . "numeric/complex/complex") (type . "Numerics")) ((name . "Complex number arithmetic") (path . "numeric/complex") (type . "Numerics")) ((name . "Compound literals") (path . "language/compound_literal") (type . "C language")) ((name . "Concurrency support library") (path . "thread") (type . "Concurrency support")) ((name . "Conditional inclusion") (path . "preprocessor/conditional") (type . "C language")) ((name . "Conformance") (path . "language/conformance") (type . "C language")) ((name . "conj") (path . "numeric/complex/conj") (type . "Numerics")) ((name . "conjf") (path . "numeric/complex/conj") (type . "Numerics")) ((name . "conjl") (path . "numeric/complex/conj") (type . "Numerics")) ((name . "const") (path . "keyword/const") (type . "C keywords")) ((name . "const type qualifier") (path . "language/const") (type . "C language")) ((name . "Constant expressions") (path . "language/constant_expression") (type . "C language")) ((name . "constexpr") (path . "keyword/constexpr") (type . "C keywords")) ((name . "constexpr specifier") (path . "language/constexpr") (type . "C language")) ((name . "constraint_handler_t") (path . "error/set_constraint_handler_s") (type . "Error handling")) ((name . "continue") (path . "keyword/continue") (type . "C keywords")) ((name . "continue statement") (path . "language/continue") (type . "C language")) ((name . "copysign") (path . "numeric/math/copysign") (type . "Numerics")) ((name . "copysignf") (path . "numeric/math/copysign") (type . "Numerics")) ((name . "copysignl") (path . "numeric/math/copysign") (type . "Numerics")) ((name . "cos") (path . "numeric/math/cos") (type . "Numerics")) ((name . "cosf") (path . "numeric/math/cos") (type . "Numerics")) ((name . "cosh") (path . "numeric/math/cosh") (type . "Numerics")) ((name . "coshf") (path . "numeric/math/cosh") (type . "Numerics")) ((name . "coshl") (path . "numeric/math/cosh") (type . "Numerics")) ((name . "cosl") (path . "numeric/math/cos") (type . "Numerics")) ((name . "cospi") (path . "numeric/math/cospi") (type . "Numerics")) ((name . "cospid128") (path . "numeric/math/cospi") (type . "Numerics")) ((name . "cospid32") (path . "numeric/math/cospi") (type . "Numerics")) ((name . "cospid64") (path . "numeric/math/cospi") (type . "Numerics")) ((name . "cospif") (path . "numeric/math/cospi") (type . "Numerics")) ((name . "cospil") (path . "numeric/math/cospi") (type . "Numerics")) ((name . "cpow") (path . "numeric/complex/cpow") (type . "Numerics")) ((name . "cpowf") (path . "numeric/complex/cpow") (type . "Numerics")) ((name . "cpowl") (path . "numeric/complex/cpow") (type . "Numerics")) ((name . "cproj") (path . "numeric/complex/cproj") (type . "Numerics")) ((name . "cprojf") (path . "numeric/complex/cproj") (type . "Numerics")) ((name . "cprojl") (path . "numeric/complex/cproj") (type . "Numerics")) ((name . "creal") (path . "numeric/complex/creal") (type . "Numerics")) ((name . "crealf") (path . "numeric/complex/creal") (type . "Numerics")) ((name . "creall") (path . "numeric/complex/creal") (type . "Numerics")) ((name . "csin") (path . "numeric/complex/csin") (type . "Numerics")) ((name . "csinf") (path . "numeric/complex/csin") (type . "Numerics")) ((name . "csinh") (path . "numeric/complex/csinh") (type . "Numerics")) ((name . "csinhf") (path . "numeric/complex/csinh") (type . "Numerics")) ((name . "csinhl") (path . "numeric/complex/csinh") (type . "Numerics")) ((name . "csinl") (path . "numeric/complex/csin") (type . "Numerics")) ((name . "csqrt") (path . "numeric/complex/csqrt") (type . "Numerics")) ((name . "csqrtf") (path . "numeric/complex/csqrt") (type . "Numerics")) ((name . "csqrtl") (path . "numeric/complex/csqrt") (type . "Numerics")) ((name . "ctan") (path . "numeric/complex/ctan") (type . "Numerics")) ((name . "ctanf") (path . "numeric/complex/ctan") (type . "Numerics")) ((name . "ctanh") (path . "numeric/complex/ctanh") (type . "Numerics")) ((name . "ctanhf") (path . "numeric/complex/ctanh") (type . "Numerics")) ((name . "ctanhl") (path . "numeric/complex/ctanh") (type . "Numerics")) ((name . "ctanl") (path . "numeric/complex/ctan") (type . "Numerics")) ((name . "ctime") (path . "chrono/ctime") (type . "Date and time")) ((name . "ctime_s") (path . "chrono/ctime") (type . "Date and time")) ((name . "Current Status") (path . "current_status") (type . "Versions")) ((name . "Date and time utilities") (path . "chrono") (type . "Date and time")) ((name . "Declarations") (path . "language/declarations") (type . "C language")) ((name . "default") (path . "keyword/default") (type . "C keywords")) ((name . "Diagnostic directives") (path . "preprocessor/error") (type . "C language")) ((name . "difftime") (path . "chrono/difftime") (type . "Date and time")) ((name . "div") (path . "numeric/math/div") (type . "Numerics")) ((name . "do") (path . "keyword/do") (type . "C keywords")) ((name . "do-while loop") (path . "language/do") (type . "C language")) ((name . "double") (path . "keyword/double") (type . "C keywords")) ((name . "double_t") (path . "numeric/math/float_t") (type . "Numerics")) ((name . "Dynamic memory management") (path . "memory") (type . "Dynamic memory management")) ((name . "else") (path . "keyword/else") (type . "C keywords")) ((name . "enum") (path . "keyword/enum") (type . "C keywords")) ((name . "Enumerations") (path . "language/enum") (type . "C language")) ((name . "erf") (path . "numeric/math/erf") (type . "Numerics")) ((name . "erfc") (path . "numeric/math/erfc") (type . "Numerics")) ((name . "erfcf") (path . "numeric/math/erfc") (type . "Numerics")) ((name . "erfcl") (path . "numeric/math/erfc") (type . "Numerics")) ((name . "erff") (path . "numeric/math/erf") (type . "Numerics")) ((name . "erfl") (path . "numeric/math/erf") (type . "Numerics")) ((name . "errno") (path . "error/errno") (type . "Error handling")) ((name . "Error handling") (path . "error") (type . "Error handling")) ((name . "Error numbers") (path . "error/errno_macros") (type . "Error handling")) ((name . "Escape sequences") (path . "language/escape") (type . "C language")) ((name . "exit") (path . "program/exit") (type . "Program support")) ((name . "EXIT_FAILURE") (path . "program/exit_status") (type . "Program support")) ((name . "EXIT_SUCCESS") (path . "program/exit_status") (type . "Program support")) ((name . "exp") (path . "numeric/math/exp") (type . "Numerics")) ((name . "exp2") (path . "numeric/math/exp2") (type . "Numerics")) ((name . "exp2f") (path . "numeric/math/exp2") (type . "Numerics")) ((name . "exp2l") (path . "numeric/math/exp2") (type . "Numerics")) ((name . "expf") (path . "numeric/math/exp") (type . "Numerics")) ((name . "expl") (path . "numeric/math/exp") (type . "Numerics")) ((name . "expm1") (path . "numeric/math/expm1") (type . "Numerics")) ((name . "expm1f") (path . "numeric/math/expm1") (type . "Numerics")) ((name . "expm1l") (path . "numeric/math/expm1") (type . "Numerics")) ((name . "Expressions") (path . "language/expressions") (type . "C language")) ((name . "extern") (path . "keyword/extern") (type . "C keywords")) ((name . "External and tentative definitions") (path . "language/extern") (type . "C language")) ((name . "fabs") (path . "numeric/math/fabs") (type . "Numerics")) ((name . "fabsd128") (path . "numeric/math/fabs") (type . "Numerics")) ((name . "fabsd32") (path . "numeric/math/fabs") (type . "Numerics")) ((name . "fabsd64") (path . "numeric/math/fabs") (type . "Numerics")) ((name . "fabsf") (path . "numeric/math/fabs") (type . "Numerics")) ((name . "fabsl") (path . "numeric/math/fabs") (type . "Numerics")) ((name . "false") (path . "keyword/false") (type . "C keywords")) ((name . "fclose") (path . "io/fclose") (type . "File input/output")) ((name . "fdim") (path . "numeric/math/fdim") (type . "Numerics")) ((name . "fdimf") (path . "numeric/math/fdim") (type . "Numerics")) ((name . "fdiml") (path . "numeric/math/fdim") (type . "Numerics")) ((name . "FE_ALL_EXCEPT") (path . "numeric/fenv/fe_exceptions") (type . "Numerics")) ((name . "FE_DFL_ENV") (path . "numeric/fenv/fe_dfl_env") (type . "Numerics")) ((name . "FE_DIVBYZERO") (path . "numeric/fenv/fe_exceptions") (type . "Numerics")) ((name . "FE_DOWNWARD") (path . "numeric/fenv/fe_round") (type . "Numerics")) ((name . "FE_INEXACT") (path . "numeric/fenv/fe_exceptions") (type . "Numerics")) ((name . "FE_INVALID") (path . "numeric/fenv/fe_exceptions") (type . "Numerics")) ((name . "FE_OVERFLOW") (path . "numeric/fenv/fe_exceptions") (type . "Numerics")) ((name . "FE_TONEAREST") (path . "numeric/fenv/fe_round") (type . "Numerics")) ((name . "FE_TOWARDZERO") (path . "numeric/fenv/fe_round") (type . "Numerics")) ((name . "FE_UNDERFLOW") (path . "numeric/fenv/fe_exceptions") (type . "Numerics")) ((name . "FE_UPWARD") (path . "numeric/fenv/fe_round") (type . "Numerics")) ((name . "feclearexcept") (path . "numeric/fenv/feclearexcept") (type . "Numerics")) ((name . "fegetenv") (path . "numeric/fenv/feenv") (type . "Numerics")) ((name . "fegetexceptflag") (path . "numeric/fenv/feexceptflag") (type . "Numerics")) ((name . "fegetround") (path . "numeric/fenv/feround") (type . "Numerics")) ((name . "feholdexcept") (path . "numeric/fenv/feholdexcept") (type . "Numerics")) ((name . "feof") (path . "io/feof") (type . "File input/output")) ((name . "feraiseexcept") (path . "numeric/fenv/feraiseexcept") (type . "Numerics")) ((name . "ferror") (path . "io/ferror") (type . "File input/output")) ((name . "fesetenv") (path . "numeric/fenv/feenv") (type . "Numerics")) ((name . "fesetexceptflag") (path . "numeric/fenv/feexceptflag") (type . "Numerics")) ((name . "fesetround") (path . "numeric/fenv/feround") (type . "Numerics")) ((name . "fetestexcept") (path . "numeric/fenv/fetestexcept") (type . "Numerics")) ((name . "feupdateenv") (path . "numeric/fenv/feupdateenv") (type . "Numerics")) ((name . "fflush") (path . "io/fflush") (type . "File input/output")) ((name . "fgetc") (path . "io/fgetc") (type . "File input/output")) ((name . "fgetpos") (path . "io/fgetpos") (type . "File input/output")) ((name . "fgets") (path . "io/fgets") (type . "File input/output")) ((name . "fgetwc") (path . "io/fgetwc") (type . "File input/output")) ((name . "fgetws") (path . "io/fgetws") (type . "File input/output")) ((name . "FILE") (path . "io/file") (type . "File input/output")) ((name . "File input/output") (path . "io") (type . "File input/output")) ((name . "File scope") (path . "language/file_scope") (type . "C language")) ((name . "Fixed width integer types") (path . "types/integer") (type . "Type support")) ((name . "float") (path . "keyword/float") (type . "C keywords")) ((name . "float_t") (path . "numeric/math/float_t") (type . "Numerics")) ((name . "Floating constant") (path . "language/floating_constant") (type . "C language")) ((name . "Floating-point environment") (path . "numeric/fenv") (type . "Numerics")) ((name . "floor") (path . "numeric/math/floor") (type . "Numerics")) ((name . "floorf") (path . "numeric/math/floor") (type . "Numerics")) ((name . "floorl") (path . "numeric/math/floor") (type . "Numerics")) ((name . "FLT_EVAL_METHOD") (path . "types/limits/flt_eval_method") (type . "Type support")) ((name . "FLT_ROUNDS") (path . "types/limits/flt_rounds") (type . "Type support")) ((name . "fma") (path . "numeric/math/fma") (type . "Numerics")) ((name . "fmaf") (path . "numeric/math/fma") (type . "Numerics")) ((name . "fmal") (path . "numeric/math/fma") (type . "Numerics")) ((name . "fmax") (path . "numeric/math/fmax") (type . "Numerics")) ((name . "fmaxf") (path . "numeric/math/fmax") (type . "Numerics")) ((name . "fmaxl") (path . "numeric/math/fmax") (type . "Numerics")) ((name . "fmin") (path . "numeric/math/fmin") (type . "Numerics")) ((name . "fminf") (path . "numeric/math/fmin") (type . "Numerics")) ((name . "fminl") (path . "numeric/math/fmin") (type . "Numerics")) ((name . "fmod") (path . "numeric/math/fmod") (type . "Numerics")) ((name . "fmodf") (path . "numeric/math/fmod") (type . "Numerics")) ((name . "fmodl") (path . "numeric/math/fmod") (type . "Numerics")) ((name . "fopen") (path . "io/fopen") (type . "File input/output")) ((name . "fopen_s") (path . "io/fopen") (type . "File input/output")) ((name . "for") (path . "keyword/for") (type . "C keywords")) ((name . "for loop") (path . "language/for") (type . "C language")) ((name . "fortran") (path . "keyword/fortran") (type . "C keywords")) ((name . "FP_INFINITE") (path . "numeric/math/fp_categories") (type . "Numerics")) ((name . "FP_NAN") (path . "numeric/math/fp_categories") (type . "Numerics")) ((name . "FP_NORMAL") (path . "numeric/math/fp_categories") (type . "Numerics")) ((name . "FP_SUBNORMAL") (path . "numeric/math/fp_categories") (type . "Numerics")) ((name . "FP_ZERO") (path . "numeric/math/fp_categories") (type . "Numerics")) ((name . "fpclassify") (path . "numeric/math/fpclassify") (type . "Numerics")) ((name . "fpos_t") (path . "io/fpos_t") (type . "File input/output")) ((name . "fprintf") (path . "io/fprintf") (type . "File input/output")) ((name . "fprintf_s") (path . "io/fprintf") (type . "File input/output")) ((name . "fputc") (path . "io/fputc") (type . "File input/output")) ((name . "fputs") (path . "io/fputs") (type . "File input/output")) ((name . "fputwc") (path . "io/fputwc") (type . "File input/output")) ((name . "fputws") (path . "io/fputws") (type . "File input/output")) ((name . "fread") (path . "io/fread") (type . "File input/output")) ((name . "free") (path . "memory/free") (type . "Dynamic memory management")) ((name . "free_aligned_sized") (path . "memory/free_aligned_sized") (type . "Dynamic memory management")) ((name . "free_sized") (path . "memory/free_sized") (type . "Dynamic memory management")) ((name . "freopen") (path . "io/freopen") (type . "File input/output")) ((name . "freopen_s") (path . "io/freopen") (type . "File input/output")) ((name . "frexp") (path . "numeric/math/frexp") (type . "Numerics")) ((name . "frexpf") (path . "numeric/math/frexp") (type . "Numerics")) ((name . "frexpl") (path . "numeric/math/frexp") (type . "Numerics")) ((name . "fscanf") (path . "io/fscanf") (type . "File input/output")) ((name . "fscanf_s") (path . "io/fscanf") (type . "File input/output")) ((name . "fseek") (path . "io/fseek") (type . "File input/output")) ((name . "fsetpos") (path . "io/fsetpos") (type . "File input/output")) ((name . "ftell") (path . "io/ftell") (type . "File input/output")) ((name . "Function declarations") (path . "language/function_declaration") (type . "C language")) ((name . "Function definitions") (path . "language/function_definition") (type . "C language")) ((name . "Functions") (path . "language/functions") (type . "C language")) ((name . "fwide") (path . "io/fwide") (type . "File input/output")) ((name . "fwprintf") (path . "io/fwprintf") (type . "File input/output")) ((name . "fwprintf_s") (path . "io/fwprintf") (type . "File input/output")) ((name . "fwrite") (path . "io/fwrite") (type . "File input/output")) ((name . "fwscanf") (path . "io/fwscanf") (type . "File input/output")) ((name . "fwscanf_s") (path . "io/fwscanf") (type . "File input/output")) ((name . "Generic selection") (path . "language/generic") (type . "C language")) ((name . "getc") (path . "io/fgetc") (type . "File input/output")) ((name . "getchar") (path . "io/getchar") (type . "File input/output")) ((name . "getenv") (path . "program/getenv") (type . "Program support")) ((name . "getenv_s") (path . "program/getenv") (type . "Program support")) ((name . "gets") (path . "io/gets") (type . "File input/output")) ((name . "gets_s") (path . "io/gets") (type . "File input/output")) ((name . "getwc") (path . "io/fgetwc") (type . "File input/output")) ((name . "getwchar") (path . "io/getwchar") (type . "File input/output")) ((name . "gmtime") (path . "chrono/gmtime") (type . "Date and time")) ((name . "gmtime_r") (path . "chrono/gmtime") (type . "Date and time")) ((name . "gmtime_s") (path . "chrono/gmtime") (type . "Date and time")) ((name . "goto") (path . "keyword/goto") (type . "C keywords")) ((name . "goto statement") (path . "language/goto") (type . "C language")) ((name . "History of C") (path . "language/history") (type . "C language")) ((name . "HUGE_VAL") (path . "numeric/math/huge_val") (type . "Numerics")) ((name . "HUGE_VALF") (path . "numeric/math/huge_val") (type . "Numerics")) ((name . "HUGE_VALL") (path . "numeric/math/huge_val") (type . "Numerics")) ((name . "hypot") (path . "numeric/math/hypot") (type . "Numerics")) ((name . "hypotf") (path . "numeric/math/hypot") (type . "Numerics")) ((name . "hypotl") (path . "numeric/math/hypot") (type . "Numerics")) ((name . "I") (path . "numeric/complex/i") (type . "Numerics")) ((name . "Identifier") (path . "language/identifier") (type . "C language")) ((name . "if") (path . "keyword/if") (type . "C keywords")) ((name . "if statement") (path . "language/if") (type . "C language")) ((name . "ignore_handler_s") (path . "error/ignore_handler_s") (type . "Error handling")) ((name . "ilogb") (path . "numeric/math/ilogb") (type . "Numerics")) ((name . "ilogbf") (path . "numeric/math/ilogb") (type . "Numerics")) ((name . "ilogbl") (path . "numeric/math/ilogb") (type . "Numerics")) ((name . "imaginary") (path . "numeric/complex/imaginary") (type . "Numerics")) ((name . "imaxabs") (path . "numeric/math/abs") (type . "Numerics")) ((name . "imaxdiv") (path . "numeric/math/div") (type . "Numerics")) ((name . "Implicit conversions") (path . "language/conversion") (type . "C language")) ((name . "Increment/decrement operators") (path . "language/operator_incdec") (type . "C language")) ((name . "INFINITY") (path . "numeric/math/infinity") (type . "Numerics")) ((name . "Initialization") (path . "language/initialization") (type . "C language")) ((name . "inline") (path . "keyword/inline") (type . "C keywords")) ((name . "Inline assembly") (path . "language/asm") (type . "C language")) ((name . "inline function specifier") (path . "language/inline") (type . "C language")) ((name . "int") (path . "keyword/int") (type . "C keywords")) ((name . "Integer constant") (path . "language/integer_constant") (type . "C language")) ((name . "isalnum") (path . "string/byte/isalnum") (type . "Strings")) ((name . "isalpha") (path . "string/byte/isalpha") (type . "Strings")) ((name . "isblank") (path . "string/byte/isblank") (type . "Strings")) ((name . "iscntrl") (path . "string/byte/iscntrl") (type . "Strings")) ((name . "isdigit") (path . "string/byte/isdigit") (type . "Strings")) ((name . "isfinite") (path . "numeric/math/isfinite") (type . "Numerics")) ((name . "isgraph") (path . "string/byte/isgraph") (type . "Strings")) ((name . "isgreater") (path . "numeric/math/isgreater") (type . "Numerics")) ((name . "isgreaterequal") (path . "numeric/math/isgreaterequal") (type . "Numerics")) ((name . "isinf") (path . "numeric/math/isinf") (type . "Numerics")) ((name . "isless") (path . "numeric/math/isless") (type . "Numerics")) ((name . "islessequal") (path . "numeric/math/islessequal") (type . "Numerics")) ((name . "islessgreater") (path . "numeric/math/islessgreater") (type . "Numerics")) ((name . "islower") (path . "string/byte/islower") (type . "Strings")) ((name . "isnan") (path . "numeric/math/isnan") (type . "Numerics")) ((name . "isnormal") (path . "numeric/math/isnormal") (type . "Numerics")) ((name . "isprint") (path . "string/byte/isprint") (type . "Strings")) ((name . "ispunct") (path . "string/byte/ispunct") (type . "Strings")) ((name . "isspace") (path . "string/byte/isspace") (type . "Strings")) ((name . "isunordered") (path . "numeric/math/isunordered") (type . "Numerics")) ((name . "isupper") (path . "string/byte/isupper") (type . "Strings")) ((name . "iswalnum") (path . "string/wide/iswalnum") (type . "Strings")) ((name . "iswalpha") (path . "string/wide/iswalpha") (type . "Strings")) ((name . "iswblank") (path . "string/wide/iswblank") (type . "Strings")) ((name . "iswcntrl") (path . "string/wide/iswcntrl") (type . "Strings")) ((name . "iswctype") (path . "string/wide/iswctype") (type . "Strings")) ((name . "iswdigit") (path . "string/wide/iswdigit") (type . "Strings")) ((name . "iswgraph") (path . "string/wide/iswgraph") (type . "Strings")) ((name . "iswlower") (path . "string/wide/iswlower") (type . "Strings")) ((name . "iswprint") (path . "string/wide/iswprint") (type . "Strings")) ((name . "iswpunct") (path . "string/wide/iswpunct") (type . "Strings")) ((name . "iswspace") (path . "string/wide/iswspace") (type . "Strings")) ((name . "iswupper") (path . "string/wide/iswupper") (type . "Strings")) ((name . "iswxdigit") (path . "string/wide/iswxdigit") (type . "Strings")) ((name . "isxdigit") (path . "string/byte/isxdigit") (type . "Strings")) ((name . "jmp_buf") (path . "program/jmp_buf") (type . "Program support")) ((name . "kill_dependency") (path . "atomic/kill_dependency") (type . "Concurrency support")) ((name . "labs") (path . "numeric/math/abs") (type . "Numerics")) ((name . "LC_ALL") (path . "locale/lc_categories") (type . "Localization support")) ((name . "LC_COLLATE") (path . "locale/lc_categories") (type . "Localization support")) ((name . "LC_CTYPE") (path . "locale/lc_categories") (type . "Localization support")) ((name . "LC_MONETARY") (path . "locale/lc_categories") (type . "Localization support")) ((name . "LC_NUMERIC") (path . "locale/lc_categories") (type . "Localization support")) ((name . "LC_TIME") (path . "locale/lc_categories") (type . "Localization support")) ((name . "lconv") (path . "locale/lconv") (type . "Localization support")) ((name . "ldexp") (path . "numeric/math/ldexp") (type . "Numerics")) ((name . "ldexpf") (path . "numeric/math/ldexp") (type . "Numerics")) ((name . "ldexpl") (path . "numeric/math/ldexp") (type . "Numerics")) ((name . "ldiv") (path . "numeric/math/div") (type . "Numerics")) ((name . "lgamma") (path . "numeric/math/lgamma") (type . "Numerics")) ((name . "lgammaf") (path . "numeric/math/lgamma") (type . "Numerics")) ((name . "lgammal") (path . "numeric/math/lgamma") (type . "Numerics")) ((name . "Lifetime") (path . "language/lifetime") (type . "C language")) ((name . "llabs") (path . "numeric/math/abs") (type . "Numerics")) ((name . "lldiv") (path . "numeric/math/div") (type . "Numerics")) ((name . "llrint") (path . "numeric/math/rint") (type . "Numerics")) ((name . "llrintf") (path . "numeric/math/rint") (type . "Numerics")) ((name . "llrintl") (path . "numeric/math/rint") (type . "Numerics")) ((name . "llround") (path . "numeric/math/round") (type . "Numerics")) ((name . "llroundf") (path . "numeric/math/round") (type . "Numerics")) ((name . "llroundl") (path . "numeric/math/round") (type . "Numerics")) ((name . "localeconv") (path . "locale/localeconv") (type . "Localization support")) ((name . "Localization support") (path . "locale") (type . "Localization support")) ((name . "localtime") (path . "chrono/localtime") (type . "Date and time")) ((name . "localtime_r") (path . "chrono/localtime") (type . "Date and time")) ((name . "localtime_s") (path . "chrono/localtime") (type . "Date and time")) ((name . "log") (path . "numeric/math/log") (type . "Numerics")) ((name . "log10") (path . "numeric/math/log10") (type . "Numerics")) ((name . "log10f") (path . "numeric/math/log10") (type . "Numerics")) ((name . "log10l") (path . "numeric/math/log10") (type . "Numerics")) ((name . "log1p") (path . "numeric/math/log1p") (type . "Numerics")) ((name . "log1pf") (path . "numeric/math/log1p") (type . "Numerics")) ((name . "log1pl") (path . "numeric/math/log1p") (type . "Numerics")) ((name . "log2") (path . "numeric/math/log2") (type . "Numerics")) ((name . "log2f") (path . "numeric/math/log2") (type . "Numerics")) ((name . "log2l") (path . "numeric/math/log2") (type . "Numerics")) ((name . "logb") (path . "numeric/math/logb") (type . "Numerics")) ((name . "logbf") (path . "numeric/math/logb") (type . "Numerics")) ((name . "logbl") (path . "numeric/math/logb") (type . "Numerics")) ((name . "logf") (path . "numeric/math/log") (type . "Numerics")) ((name . "Logical operators") (path . "language/operator_logical") (type . "C language")) ((name . "logl") (path . "numeric/math/log") (type . "Numerics")) ((name . "long") (path . "keyword/long") (type . "C keywords")) ((name . "longjmp") (path . "program/longjmp") (type . "Program support")) ((name . "Lookup and name spaces") (path . "language/name_space") (type . "C language")) ((name . "lrint") (path . "numeric/math/rint") (type . "Numerics")) ((name . "lrintf") (path . "numeric/math/rint") (type . "Numerics")) ((name . "lrintl") (path . "numeric/math/rint") (type . "Numerics")) ((name . "lround") (path . "numeric/math/round") (type . "Numerics")) ((name . "lroundf") (path . "numeric/math/round") (type . "Numerics")) ((name . "lroundl") (path . "numeric/math/round") (type . "Numerics")) ((name . "Main function") (path . "language/main_function") (type . "C language")) ((name . "malloc") (path . "memory/malloc") (type . "Dynamic memory management")) ((name . "MATH_ERREXCEPT") (path . "numeric/math/math_errhandling") (type . "Numerics")) ((name . "math_errhandling") (path . "numeric/math/math_errhandling") (type . "Numerics")) ((name . "MATH_ERRNO") (path . "numeric/math/math_errhandling") (type . "Numerics")) ((name . "max_align_t") (path . "types/max_align_t") (type . "Type support")) ((name . "mblen") (path . "string/multibyte/mblen") (type . "Strings")) ((name . "mbrlen") (path . "string/multibyte/mbrlen") (type . "Strings")) ((name . "mbrtoc16") (path . "string/multibyte/mbrtoc16") (type . "Strings")) ((name . "mbrtoc32") (path . "string/multibyte/mbrtoc32") (type . "Strings")) ((name . "mbrtoc8") (path . "string/multibyte/mbrtoc8") (type . "Strings")) ((name . "mbrtowc") (path . "string/multibyte/mbrtowc") (type . "Strings")) ((name . "mbsinit") (path . "string/multibyte/mbsinit") (type . "Strings")) ((name . "mbsrtowcs") (path . "string/multibyte/mbsrtowcs") (type . "Strings")) ((name . "mbsrtowcs_s") (path . "string/multibyte/mbsrtowcs") (type . "Strings")) ((name . "mbstate_t") (path . "string/multibyte/mbstate_t") (type . "Strings")) ((name . "mbstowcs") (path . "string/multibyte/mbstowcs") (type . "Strings")) ((name . "mbstowcs_s") (path . "string/multibyte/mbstowcs") (type . "Strings")) ((name . "mbtowc") (path . "string/multibyte/mbtowc") (type . "Strings")) ((name . "Member access operators") (path . "language/operator_member_access") (type . "C language")) ((name . "memccpy") (path . "string/byte/memccpy") (type . "Strings")) ((name . "memchr") (path . "string/byte/memchr") (type . "Strings")) ((name . "memcmp") (path . "string/byte/memcmp") (type . "Strings")) ((name . "memcpy") (path . "string/byte/memcpy") (type . "Strings")) ((name . "memcpy_s") (path . "string/byte/memcpy") (type . "Strings")) ((name . "memmove") (path . "string/byte/memmove") (type . "Strings")) ((name . "memmove_s") (path . "string/byte/memmove") (type . "Strings")) ((name . "Memory model") (path . "language/memory_model") (type . "C language")) ((name . "memory_order") (path . "atomic/memory_order") (type . "Concurrency support")) ((name . "memset") (path . "string/byte/memset") (type . "Strings")) ((name . "memset_explicit") (path . "string/byte/memset") (type . "Strings")) ((name . "memset_s") (path . "string/byte/memset") (type . "Strings")) ((name . "mktime") (path . "chrono/mktime") (type . "Date and time")) ((name . "modf") (path . "numeric/math/modf") (type . "Numerics")) ((name . "modff") (path . "numeric/math/modf") (type . "Numerics")) ((name . "modfl") (path . "numeric/math/modf") (type . "Numerics")) ((name . "mtx_destroy") (path . "thread/mtx_destroy") (type . "Concurrency support")) ((name . "mtx_init") (path . "thread/mtx_init") (type . "Concurrency support")) ((name . "mtx_lock") (path . "thread/mtx_lock") (type . "Concurrency support")) ((name . "mtx_plain") (path . "thread/mtx_types") (type . "Concurrency support")) ((name . "mtx_recursive") (path . "thread/mtx_types") (type . "Concurrency support")) ((name . "mtx_timed") (path . "thread/mtx_types") (type . "Concurrency support")) ((name . "mtx_timedlock") (path . "thread/mtx_timedlock") (type . "Concurrency support")) ((name . "mtx_trylock") (path . "thread/mtx_trylock") (type . "Concurrency support")) ((name . "mtx_unlock") (path . "thread/mtx_unlock") (type . "Concurrency support")) ((name . "nan") (path . "numeric/math/nan") (type . "Numerics")) ((name . "nand128") (path . "numeric/math/nan") (type . "Numerics")) ((name . "nand32") (path . "numeric/math/nan") (type . "Numerics")) ((name . "nand64") (path . "numeric/math/nan") (type . "Numerics")) ((name . "nanf") (path . "numeric/math/nan") (type . "Numerics")) ((name . "nanl") (path . "numeric/math/nan") (type . "Numerics")) ((name . "nearbyint") (path . "numeric/math/nearbyint") (type . "Numerics")) ((name . "nearbyintf") (path . "numeric/math/nearbyint") (type . "Numerics")) ((name . "nearbyintl") (path . "numeric/math/nearbyint") (type . "Numerics")) ((name . "nextafter") (path . "numeric/math/nextafter") (type . "Numerics")) ((name . "nextafterf") (path . "numeric/math/nextafter") (type . "Numerics")) ((name . "nextafterl") (path . "numeric/math/nextafter") (type . "Numerics")) ((name . "nexttoward") (path . "numeric/math/nextafter") (type . "Numerics")) ((name . "nexttowardf") (path . "numeric/math/nextafter") (type . "Numerics")) ((name . "nexttowardl") (path . "numeric/math/nextafter") (type . "Numerics")) ((name . "NULL") (path . "types/null") (type . "Type support")) ((name . "Null-terminated byte strings") (path . "string/byte") (type . "Strings")) ((name . "Null-terminated multibyte strings") (path . "string/multibyte") (type . "Strings")) ((name . "Null-terminated wide strings") (path . "string/wide") (type . "Strings")) ((name . "nullptr") (path . "keyword/nullptr") (type . "C keywords")) ((name . "nullptr_t") (path . "types/nullptr_t") (type . "Type support")) ((name . "Numeric limits") (path . "types/limits") (type . "Type support")) ((name . "Numerics") (path . "numeric") (type . "Numerics")) ((name . "Objects and alignment") (path . "language/object") (type . "C language")) ((name . "offsetof") (path . "types/offsetof") (type . "Type support")) ((name . "once_flag") (path . "thread/call_once") (type . "Concurrency support")) ((name . "ONCE_FLAG_INIT") (path . "thread/call_once") (type . "Concurrency support")) ((name . "Order of evaluation") (path . "language/eval_order") (type . "C language")) ((name . "Other operators") (path . "language/operator_other") (type . "C language")) ((name . "perror") (path . "io/perror") (type . "File input/output")) ((name . "Phases of translation") (path . "language/translation_phases") (type . "C language")) ((name . "Pointer declaration") (path . "language/pointer") (type . "C language")) ((name . "pow") (path . "numeric/math/pow") (type . "Numerics")) ((name . "powf") (path . "numeric/math/pow") (type . "Numerics")) ((name . "powl") (path . "numeric/math/pow") (type . "Numerics")) ((name . "Predefined Boolean constants") (path . "language/bool_constant") (type . "C language")) ((name . "Predefined null pointer constant") (path . "language/nullptr") (type . "C language")) ((name . "Preprocessor") (path . "preprocessor") (type . "C language")) ((name . "printf") (path . "io/fprintf") (type . "File input/output")) ((name . "printf_s") (path . "io/fprintf") (type . "File input/output")) ((name . "Program support utilities") (path . "program") (type . "Program support")) ((name . "Pseudo-random number generation") (path . "numeric/random") (type . "Numerics")) ((name . "ptrdiff_t") (path . "types/ptrdiff_t") (type . "Type support")) ((name . "Punctuation") (path . "language/punctuators") (type . "C language")) ((name . "putc") (path . "io/fputc") (type . "File input/output")) ((name . "putchar") (path . "io/putchar") (type . "File input/output")) ((name . "puts") (path . "io/puts") (type . "File input/output")) ((name . "putwc") (path . "io/fputwc") (type . "File input/output")) ((name . "putwchar") (path . "io/putwchar") (type . "File input/output")) ((name . "qsort") (path . "algorithm/qsort") (type . "Algorithms")) ((name . "qsort_s") (path . "algorithm/qsort") (type . "Algorithms")) ((name . "quick_exit") (path . "program/quick_exit") (type . "Program support")) ((name . "raise") (path . "program/raise") (type . "Program support")) ((name . "rand") (path . "numeric/random/rand") (type . "Numerics")) ((name . "RAND_MAX") (path . "numeric/random/rand_max") (type . "Numerics")) ((name . "realloc") (path . "memory/realloc") (type . "Dynamic memory management")) ((name . "register") (path . "keyword/register") (type . "C keywords")) ((name . "remainder") (path . "numeric/math/remainder") (type . "Numerics")) ((name . "remainderf") (path . "numeric/math/remainder") (type . "Numerics")) ((name . "remainderl") (path . "numeric/math/remainder") (type . "Numerics")) ((name . "remove") (path . "io/remove") (type . "File input/output")) ((name . "remquo") (path . "numeric/math/remquo") (type . "Numerics")) ((name . "remquof") (path . "numeric/math/remquo") (type . "Numerics")) ((name . "remquol") (path . "numeric/math/remquo") (type . "Numerics")) ((name . "rename") (path . "io/rename") (type . "File input/output")) ((name . "reproducible (since C23)") (path . "language/attributes/unsequenced") (type . "C language")) ((name . "reproducible (since C23)") (path . "language/attributes/reproducible") (type . "C language")) ((name . "restrict") (path . "keyword/restrict") (type . "C keywords")) ((name . "restrict type qualifier") (path . "language/restrict") (type . "C language")) ((name . "return") (path . "keyword/return") (type . "C keywords")) ((name . "return statement") (path . "language/return") (type . "C language")) ((name . "rewind") (path . "io/rewind") (type . "File input/output")) ((name . "rint") (path . "numeric/math/rint") (type . "Numerics")) ((name . "rintf") (path . "numeric/math/rint") (type . "Numerics")) ((name . "rintl") (path . "numeric/math/rint") (type . "Numerics")) ((name . "round") (path . "numeric/math/round") (type . "Numerics")) ((name . "roundeven") (path . "numeric/math/roundeven") (type . "Numerics")) ((name . "roundevenf") (path . "numeric/math/roundeven") (type . "Numerics")) ((name . "roundevenl") (path . "numeric/math/roundeven") (type . "Numerics")) ((name . "roundf") (path . "numeric/math/round") (type . "Numerics")) ((name . "roundl") (path . "numeric/math/round") (type . "Numerics")) ((name . "Scalar initialization") (path . "language/scalar_initialization") (type . "C language")) ((name . "scalbln") (path . "numeric/math/scalbn") (type . "Numerics")) ((name . "scalblnf") (path . "numeric/math/scalbn") (type . "Numerics")) ((name . "scalblnl") (path . "numeric/math/scalbn") (type . "Numerics")) ((name . "scalbn") (path . "numeric/math/scalbn") (type . "Numerics")) ((name . "scalbnf") (path . "numeric/math/scalbn") (type . "Numerics")) ((name . "scalbnl") (path . "numeric/math/scalbn") (type . "Numerics")) ((name . "scanf") (path . "io/fscanf") (type . "File input/output")) ((name . "scanf_s") (path . "io/fscanf") (type . "File input/output")) ((name . "Scope") (path . "language/scope") (type . "C language")) ((name . "set_constraint_handler_s") (path . "error/set_constraint_handler_s") (type . "Error handling")) ((name . "setbuf") (path . "io/setbuf") (type . "File input/output")) ((name . "setjmp") (path . "program/setjmp") (type . "Program support")) ((name . "setlocale") (path . "locale/setlocale") (type . "Localization support")) ((name . "setvbuf") (path . "io/setvbuf") (type . "File input/output")) ((name . "short") (path . "keyword/short") (type . "C keywords")) ((name . "sig_atomic_t") (path . "program/sig_atomic_t") (type . "Program support")) ((name . "SIG_DFL") (path . "program/sig_strategies") (type . "Program support")) ((name . "SIG_ERR") (path . "program/sig_err") (type . "Program support")) ((name . "SIG_IGN") (path . "program/sig_strategies") (type . "Program support")) ((name . "SIGABRT") (path . "program/sig_types") (type . "Program support")) ((name . "SIGFPE") (path . "program/sig_types") (type . "Program support")) ((name . "SIGILL") (path . "program/sig_types") (type . "Program support")) ((name . "SIGINT") (path . "program/sig_types") (type . "Program support")) ((name . "signal") (path . "program/signal") (type . "Program support")) ((name . "signbit") (path . "numeric/math/signbit") (type . "Numerics")) ((name . "signed") (path . "keyword/signed") (type . "C keywords")) ((name . "SIGSEGV") (path . "program/sig_types") (type . "Program support")) ((name . "SIGTERM") (path . "program/sig_types") (type . "Program support")) ((name . "sin") (path . "numeric/math/sin") (type . "Numerics")) ((name . "sinf") (path . "numeric/math/sin") (type . "Numerics")) ((name . "sinh") (path . "numeric/math/sinh") (type . "Numerics")) ((name . "sinhf") (path . "numeric/math/sinh") (type . "Numerics")) ((name . "sinhl") (path . "numeric/math/sinh") (type . "Numerics")) ((name . "sinl") (path . "numeric/math/sin") (type . "Numerics")) ((name . "sinpi") (path . "numeric/math/sinpi") (type . "Numerics")) ((name . "sinpid128") (path . "numeric/math/sinpi") (type . "Numerics")) ((name . "sinpid32") (path . "numeric/math/sinpi") (type . "Numerics")) ((name . "sinpid64") (path . "numeric/math/sinpi") (type . "Numerics")) ((name . "sinpif") (path . "numeric/math/sinpi") (type . "Numerics")) ((name . "sinpil") (path . "numeric/math/sinpi") (type . "Numerics")) ((name . "size_t") (path . "types/size_t") (type . "Type support")) ((name . "sizeof") (path . "keyword/sizeof") (type . "C keywords")) ((name . "sizeof operator") (path . "language/sizeof") (type . "C language")) ((name . "snprintf") (path . "io/fprintf") (type . "File input/output")) ((name . "snprintf_s") (path . "io/fprintf") (type . "File input/output")) ((name . "snwprintf_s") (path . "io/fwprintf") (type . "File input/output")) ((name . "sprintf") (path . "io/fprintf") (type . "File input/output")) ((name . "sprintf_s") (path . "io/fprintf") (type . "File input/output")) ((name . "sqrt") (path . "numeric/math/sqrt") (type . "Numerics")) ((name . "sqrtf") (path . "numeric/math/sqrt") (type . "Numerics")) ((name . "sqrtl") (path . "numeric/math/sqrt") (type . "Numerics")) ((name . "srand") (path . "numeric/random/srand") (type . "Numerics")) ((name . "sscanf") (path . "io/fscanf") (type . "File input/output")) ((name . "sscanf_s") (path . "io/fscanf") (type . "File input/output")) ((name . "Statements") (path . "language/statements") (type . "C language")) ((name . "static") (path . "keyword/static") (type . "C keywords")) ((name . "Static assertion") (path . "language/_static_assert") (type . "C language")) ((name . "Static assertion") (path . "language/static_assert") (type . "C language")) ((name . "Static storage duration") (path . "language/static_storage_duration") (type . "C language")) ((name . "static_assert") (path . "keyword/static_assert") (type . "C keywords")) ((name . "static_assert") (path . "error/static_assert") (type . "Error handling")) ((name . "stderr") (path . "io/std_streams") (type . "File input/output")) ((name . "stdin") (path . "io/std_streams") (type . "File input/output")) ((name . "stdout") (path . "io/std_streams") (type . "File input/output")) ((name . "Storage-class specifiers") (path . "language/storage_duration") (type . "C language")) ((name . "strcat") (path . "string/byte/strcat") (type . "Strings")) ((name . "strcat_s") (path . "string/byte/strcat") (type . "Strings")) ((name . "strchr") (path . "string/byte/strchr") (type . "Strings")) ((name . "strcmp") (path . "string/byte/strcmp") (type . "Strings")) ((name . "strcoll") (path . "string/byte/strcoll") (type . "Strings")) ((name . "strcpy") (path . "string/byte/strcpy") (type . "Strings")) ((name . "strcpy_s") (path . "string/byte/strcpy") (type . "Strings")) ((name . "strcspn") (path . "string/byte/strcspn") (type . "Strings")) ((name . "strdup") (path . "string/byte/strdup") (type . "Strings")) ((name . "strerror") (path . "string/byte/strerror") (type . "Strings")) ((name . "strerror_s") (path . "string/byte/strerror") (type . "Strings")) ((name . "strerrorlen_s") (path . "string/byte/strerror") (type . "Strings")) ((name . "strfromd") (path . "string/byte/strfromf") (type . "Strings")) ((name . "strfromf") (path . "string/byte/strfromf") (type . "Strings")) ((name . "strfromld") (path . "string/byte/strfromf") (type . "Strings")) ((name . "strftime") (path . "chrono/strftime") (type . "Date and time")) ((name . "String literals") (path . "language/string_literal") (type . "C language")) ((name . "Strings library") (path . "string") (type . "Strings")) ((name . "strlen") (path . "string/byte/strlen") (type . "Strings")) ((name . "strncat") (path . "string/byte/strncat") (type . "Strings")) ((name . "strncat_s") (path . "string/byte/strncat") (type . "Strings")) ((name . "strncmp") (path . "string/byte/strncmp") (type . "Strings")) ((name . "strncpy") (path . "string/byte/strncpy") (type . "Strings")) ((name . "strncpy_s") (path . "string/byte/strncpy") (type . "Strings")) ((name . "strndup") (path . "string/byte/strndup") (type . "Strings")) ((name . "strnlen_s") (path . "string/byte/strlen") (type . "Strings")) ((name . "strpbrk") (path . "string/byte/strpbrk") (type . "Strings")) ((name . "strrchr") (path . "string/byte/strrchr") (type . "Strings")) ((name . "strspn") (path . "string/byte/strspn") (type . "Strings")) ((name . "strstr") (path . "string/byte/strstr") (type . "Strings")) ((name . "strtod") (path . "string/byte/strtof") (type . "Strings")) ((name . "strtof") (path . "string/byte/strtof") (type . "Strings")) ((name . "strtoimax") (path . "string/byte/strtoimax") (type . "Strings")) ((name . "strtok") (path . "string/byte/strtok") (type . "Strings")) ((name . "strtok_s") (path . "string/byte/strtok") (type . "Strings")) ((name . "strtol") (path . "string/byte/strtol") (type . "Strings")) ((name . "strtold") (path . "string/byte/strtof") (type . "Strings")) ((name . "strtoll") (path . "string/byte/strtol") (type . "Strings")) ((name . "strtoul") (path . "string/byte/strtoul") (type . "Strings")) ((name . "strtoull") (path . "string/byte/strtoul") (type . "Strings")) ((name . "strtoumax") (path . "string/byte/strtoimax") (type . "Strings")) ((name . "struct") (path . "keyword/struct") (type . "C keywords")) ((name . "Struct and union initialization") (path . "language/struct_initialization") (type . "C language")) ((name . "Struct declaration") (path . "language/struct") (type . "C language")) ((name . "strxfrm") (path . "string/byte/strxfrm") (type . "Strings")) ((name . "switch") (path . "keyword/switch") (type . "C keywords")) ((name . "switch statement") (path . "language/switch") (type . "C language")) ((name . "swprintf") (path . "io/fwprintf") (type . "File input/output")) ((name . "swprintf_s") (path . "io/fwprintf") (type . "File input/output")) ((name . "swscanf") (path . "io/fwscanf") (type . "File input/output")) ((name . "swscanf_s") (path . "io/fwscanf") (type . "File input/output")) ((name . "system") (path . "program/system") (type . "Program support")) ((name . "tan") (path . "numeric/math/tan") (type . "Numerics")) ((name . "tanf") (path . "numeric/math/tan") (type . "Numerics")) ((name . "tanh") (path . "numeric/math/tanh") (type . "Numerics")) ((name . "tanhf") (path . "numeric/math/tanh") (type . "Numerics")) ((name . "tanhl") (path . "numeric/math/tanh") (type . "Numerics")) ((name . "tanl") (path . "numeric/math/tan") (type . "Numerics")) ((name . "tgamma") (path . "numeric/math/tgamma") (type . "Numerics")) ((name . "tgammaf") (path . "numeric/math/tgamma") (type . "Numerics")) ((name . "tgammal") (path . "numeric/math/tgamma") (type . "Numerics")) ((name . "thrd_busy") (path . "thread/thrd_errors") (type . "Concurrency support")) ((name . "thrd_create") (path . "thread/thrd_create") (type . "Concurrency support")) ((name . "thrd_current") (path . "thread/thrd_current") (type . "Concurrency support")) ((name . "thrd_detach") (path . "thread/thrd_detach") (type . "Concurrency support")) ((name . "thrd_equal") (path . "thread/thrd_equal") (type . "Concurrency support")) ((name . "thrd_error") (path . "thread/thrd_errors") (type . "Concurrency support")) ((name . "thrd_exit") (path . "thread/thrd_exit") (type . "Concurrency support")) ((name . "thrd_join") (path . "thread/thrd_join") (type . "Concurrency support")) ((name . "thrd_nomem") (path . "thread/thrd_errors") (type . "Concurrency support")) ((name . "thrd_sleep") (path . "thread/thrd_sleep") (type . "Concurrency support")) ((name . "thrd_success") (path . "thread/thrd_errors") (type . "Concurrency support")) ((name . "thrd_timedout") (path . "thread/thrd_errors") (type . "Concurrency support")) ((name . "thrd_yield") (path . "thread/thrd_yield") (type . "Concurrency support")) ((name . "Thread storage duration") (path . "language/thread_storage_duration") (type . "C language")) ((name . "thread_local") (path . "keyword/thread_local") (type . "C keywords")) ((name . "thread_local") (path . "thread/thread_local") (type . "Concurrency support")) ((name . "time") (path . "chrono/time") (type . "Date and time")) ((name . "time_t") (path . "chrono/time_t") (type . "Date and time")) ((name . "timespec") (path . "chrono/timespec") (type . "Date and time")) ((name . "timespec_get") (path . "chrono/timespec_get") (type . "Date and time")) ((name . "timespec_getres") (path . "chrono/timespec_getres") (type . "Date and time")) ((name . "tm") (path . "chrono/tm") (type . "Date and time")) ((name . "tmpfile") (path . "io/tmpfile") (type . "File input/output")) ((name . "tmpfile_s") (path . "io/tmpfile") (type . "File input/output")) ((name . "tmpnam") (path . "io/tmpnam") (type . "File input/output")) ((name . "tmpnam_s") (path . "io/tmpnam") (type . "File input/output")) ((name . "tolower") (path . "string/byte/tolower") (type . "Strings")) ((name . "toupper") (path . "string/byte/toupper") (type . "Strings")) ((name . "towctrans") (path . "string/wide/towctrans") (type . "Strings")) ((name . "towlower") (path . "string/wide/towlower") (type . "Strings")) ((name . "towupper") (path . "string/wide/towupper") (type . "Strings")) ((name . "true") (path . "keyword/true") (type . "C keywords")) ((name . "trunc") (path . "numeric/math/trunc") (type . "Numerics")) ((name . "truncf") (path . "numeric/math/trunc") (type . "Numerics")) ((name . "truncl") (path . "numeric/math/trunc") (type . "Numerics")) ((name . "tss_create") (path . "thread/tss_create") (type . "Concurrency support")) ((name . "tss_delete") (path . "thread/tss_delete") (type . "Concurrency support")) ((name . "TSS_DTOR_ITERATIONS") (path . "thread/tss_dtor_iterations") (type . "Concurrency support")) ((name . "tss_get") (path . "thread/tss_get") (type . "Concurrency support")) ((name . "tss_set") (path . "thread/tss_set") (type . "Concurrency support")) ((name . "Type") (path . "language/compatible_type") (type . "C language")) ((name . "Type") (path . "language/types") (type . "C language")) ((name . "Type") (path . "language/type") (type . "C language")) ((name . "Type support") (path . "types") (type . "Type support")) ((name . "Type-generic math") (path . "numeric/tgmath") (type . "Numerics")) ((name . "typedef") (path . "keyword/typedef") (type . "C keywords")) ((name . "Typedef declaration") (path . "language/typedef") (type . "C language")) ((name . "typeof") (path . "keyword/typeof") (type . "C keywords")) ((name . "typeof operators") (path . "language/typeof") (type . "C language")) ((name . "typeof_unqual") (path . "keyword/typeof_unqual") (type . "C keywords")) ((name . "Undefined behavior") (path . "language/behavior") (type . "C language")) ((name . "ungetc") (path . "io/ungetc") (type . "File input/output")) ((name . "ungetwc") (path . "io/ungetwc") (type . "File input/output")) ((name . "union") (path . "keyword/union") (type . "C keywords")) ((name . "Union declaration") (path . "language/union") (type . "C language")) ((name . "unreachable") (path . "program/unreachable") (type . "Program support")) ((name . "unsigned") (path . "keyword/unsigned") (type . "C keywords")) ((name . "va_arg") (path . "variadic/va_arg") (type . "Variadic functions")) ((name . "va_copy") (path . "variadic/va_copy") (type . "Variadic functions")) ((name . "va_end") (path . "variadic/va_end") (type . "Variadic functions")) ((name . "va_list") (path . "variadic/va_list") (type . "Variadic functions")) ((name . "va_start") (path . "variadic/va_start") (type . "Variadic functions")) ((name . "Value categories") (path . "language/value_category") (type . "C language")) ((name . "Variadic arguments") (path . "language/variadic") (type . "C language")) ((name . "Variadic functions") (path . "variadic") (type . "Variadic functions")) ((name . "vfprintf") (path . "io/vfprintf") (type . "File input/output")) ((name . "vfprintf_s") (path . "io/vfprintf") (type . "File input/output")) ((name . "vfscanf") (path . "io/vfscanf") (type . "File input/output")) ((name . "vfscanf_s") (path . "io/vfscanf") (type . "File input/output")) ((name . "vfwprintf") (path . "io/vfwprintf") (type . "File input/output")) ((name . "vfwprintf_s") (path . "io/vfwprintf") (type . "File input/output")) ((name . "vfwscanf") (path . "io/vfwscanf") (type . "File input/output")) ((name . "vfwscanf_s") (path . "io/vfwscanf") (type . "File input/output")) ((name . "void") (path . "keyword/void") (type . "C keywords")) ((name . "volatile") (path . "keyword/volatile") (type . "C keywords")) ((name . "volatile type qualifier") (path . "language/volatile") (type . "C language")) ((name . "vprintf") (path . "io/vfprintf") (type . "File input/output")) ((name . "vprintf_s") (path . "io/vfprintf") (type . "File input/output")) ((name . "vscanf") (path . "io/vfscanf") (type . "File input/output")) ((name . "vscanf_s") (path . "io/vfscanf") (type . "File input/output")) ((name . "vsnprintf") (path . "io/vfprintf") (type . "File input/output")) ((name . "vsnprintf_s") (path . "io/vfprintf") (type . "File input/output")) ((name . "vsnwprintf_s") (path . "io/vfwprintf") (type . "File input/output")) ((name . "vsprintf") (path . "io/vfprintf") (type . "File input/output")) ((name . "vsprintf_s") (path . "io/vfprintf") (type . "File input/output")) ((name . "vsscanf") (path . "io/vfscanf") (type . "File input/output")) ((name . "vsscanf_s") (path . "io/vfscanf") (type . "File input/output")) ((name . "vswprintf") (path . "io/vfwprintf") (type . "File input/output")) ((name . "vswprintf_s") (path . "io/vfwprintf") (type . "File input/output")) ((name . "vswscanf") (path . "io/vfwscanf") (type . "File input/output")) ((name . "vswscanf_s") (path . "io/vfwscanf") (type . "File input/output")) ((name . "vwprintf") (path . "io/vfwprintf") (type . "File input/output")) ((name . "vwprintf_s") (path . "io/vfwprintf") (type . "File input/output")) ((name . "vwscanf") (path . "io/vfwscanf") (type . "File input/output")) ((name . "vwscanf_s") (path . "io/vfwscanf") (type . "File input/output")) ((name . "wcrtomb") (path . "string/multibyte/wcrtomb") (type . "Strings")) ((name . "wcrtomb_s") (path . "string/multibyte/wcrtomb") (type . "Strings")) ((name . "wcscat") (path . "string/wide/wcscat") (type . "Strings")) ((name . "wcscat_s") (path . "string/wide/wcscat") (type . "Strings")) ((name . "wcschr") (path . "string/wide/wcschr") (type . "Strings")) ((name . "wcscmp") (path . "string/wide/wcscmp") (type . "Strings")) ((name . "wcscoll") (path . "string/wide/wcscoll") (type . "Strings")) ((name . "wcscpy") (path . "string/wide/wcscpy") (type . "Strings")) ((name . "wcscpy_s") (path . "string/wide/wcscpy") (type . "Strings")) ((name . "wcscspn") (path . "string/wide/wcscspn") (type . "Strings")) ((name . "wcsftime") (path . "chrono/wcsftime") (type . "Date and time")) ((name . "wcslen") (path . "string/wide/wcslen") (type . "Strings")) ((name . "wcsncat") (path . "string/wide/wcsncat") (type . "Strings")) ((name . "wcsncat_s") (path . "string/wide/wcsncat") (type . "Strings")) ((name . "wcsncmp") (path . "string/wide/wcsncmp") (type . "Strings")) ((name . "wcsncpy") (path . "string/wide/wcsncpy") (type . "Strings")) ((name . "wcsncpy_s") (path . "string/wide/wcsncpy") (type . "Strings")) ((name . "wcsnlen_s") (path . "string/wide/wcslen") (type . "Strings")) ((name . "wcspbrk") (path . "string/wide/wcspbrk") (type . "Strings")) ((name . "wcsrchr") (path . "string/wide/wcsrchr") (type . "Strings")) ((name . "wcsrtombs") (path . "string/multibyte/wcsrtombs") (type . "Strings")) ((name . "wcsrtombs_s") (path . "string/multibyte/wcsrtombs") (type . "Strings")) ((name . "wcsspn") (path . "string/wide/wcsspn") (type . "Strings")) ((name . "wcsstr") (path . "string/wide/wcsstr") (type . "Strings")) ((name . "wcstod") (path . "string/wide/wcstof") (type . "Strings")) ((name . "wcstof") (path . "string/wide/wcstof") (type . "Strings")) ((name . "wcstoimax") (path . "string/wide/wcstoimax") (type . "Strings")) ((name . "wcstok") (path . "string/wide/wcstok") (type . "Strings")) ((name . "wcstok_s") (path . "string/wide/wcstok") (type . "Strings")) ((name . "wcstol") (path . "string/wide/wcstol") (type . "Strings")) ((name . "wcstold") (path . "string/wide/wcstof") (type . "Strings")) ((name . "wcstoll") (path . "string/wide/wcstol") (type . "Strings")) ((name . "wcstombs") (path . "string/multibyte/wcstombs") (type . "Strings")) ((name . "wcstombs_s") (path . "string/multibyte/wcstombs") (type . "Strings")) ((name . "wcstoul") (path . "string/wide/wcstoul") (type . "Strings")) ((name . "wcstoull") (path . "string/wide/wcstoul") (type . "Strings")) ((name . "wcstoumax") (path . "string/wide/wcstoimax") (type . "Strings")) ((name . "wcsxfrm") (path . "string/wide/wcsxfrm") (type . "Strings")) ((name . "wctob") (path . "string/multibyte/wctob") (type . "Strings")) ((name . "wctomb") (path . "string/multibyte/wctomb") (type . "Strings")) ((name . "wctomb_s") (path . "string/multibyte/wctomb") (type . "Strings")) ((name . "wctrans") (path . "string/wide/wctrans") (type . "Strings")) ((name . "wctype") (path . "string/wide/wctype") (type . "Strings")) ((name . "while") (path . "keyword/while") (type . "C keywords")) ((name . "while loop") (path . "language/while") (type . "C language")) ((name . "wmemchr") (path . "string/wide/wmemchr") (type . "Strings")) ((name . "wmemcmp") (path . "string/wide/wmemcmp") (type . "Strings")) ((name . "wmemcpy") (path . "string/wide/wmemcpy") (type . "Strings")) ((name . "wmemcpy_s") (path . "string/wide/wmemcpy") (type . "Strings")) ((name . "wmemmove") (path . "string/wide/wmemmove") (type . "Strings")) ((name . "wmemmove_s") (path . "string/wide/wmemmove") (type . "Strings")) ((name . "wmemset") (path . "string/wide/wmemset") (type . "Strings")) ((name . "wprintf") (path . "io/fwprintf") (type . "File input/output")) ((name . "wprintf_s") (path . "io/fwprintf") (type . "File input/output")) ((name . "wscanf") (path . "io/fwscanf") (type . "File input/output")) ((name . "wscanf_s") (path . "io/fwscanf") (type . "File input/output"))]) (types . [((name . "Algorithms") (count . 5) (slug . "algorithms")) ((name . "Atomic operations") (count . 1) (slug . "atomic-operations")) ((name . "C keywords") (count . 60) (slug . "c-keywords")) ((name . "C language") (count . 121) (slug . "c-language")) ((name . "Concurrency support") (count . 72) (slug . "concurrency-support")) ((name . "Date and time") (count . 24) (slug . "date-and-time")) ((name . "Dynamic memory management") (count . 8) (slug . "dynamic-memory-management")) ((name . "Error handling") (count . 9) (slug . "error-handling")) ((name . "File input/output") (count . 107) (slug . "file-input-output")) ((name . "Localization support") (count . 10) (slug . "localization-support")) ((name . "Numerics") (count . 331) (slug . "numerics")) ((name . "Program support") (count . 28) (slug . "program-support")) ((name . "Strings") (count . 156) (slug . "strings")) ((name . "Type support") (count . 11) (slug . "type-support")) ((name . "Variadic functions") (count . 6) (slug . "variadic-functions")) ((name . "Versions") (count . 6) (slug . "versions"))]))
\ No newline at end of file diff --git a/devdocs/c/index.html b/devdocs/c/index.html new file mode 100644 index 00000000..9e6f2236 --- /dev/null +++ b/devdocs/c/index.html @@ -0,0 +1,50 @@ +<h1>C Programming Language</h1> <p>The interface of C standard library is defined by the following collection of headers.</p> +<table class="t-dsc-begin"> <tr class="t-dsc"> <td> <a href="error" title="c/error"><code><assert.h></code></a> </td> <td> <a href="error" title="c/error">Conditionally compiled macro that compares its argument to zero</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="numeric/complex" title="c/numeric/complex"><code><complex.h></code></a> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> <td> <a href="numeric/complex" title="c/numeric/complex">Complex number arithmetic</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="string/byte" title="c/string/byte"><code><ctype.h></code></a> </td> <td> <a href="string/byte" title="c/string/byte">Functions to determine the type contained in character data</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="error" title="c/error"><code><errno.h></code></a> </td> <td> <a href="error" title="c/error">Macros reporting error conditions</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="numeric/fenv" title="c/numeric/fenv"><code><fenv.h></code></a> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> <td> <a href="numeric/fenv" title="c/numeric/fenv">Floating-point environment</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="types/limits#Limits_of_floating_point_types" title="c/types/limits"><code><float.h></code></a> </td> <td> <a href="types/limits#Limits_of_floating_point_types" title="c/types/limits">Limits of floating-point types</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="types/integer" title="c/types/integer"><code><inttypes.h></code></a> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> <td> <a href="types/integer" title="c/types/integer">Format conversion of integer types</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="language/operator_alternative" title="c/language/operator alternative"><code><iso646.h></code></a> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> <td> <a href="language/operator_alternative" title="c/language/operator alternative">Alternative operator spellings</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="types/limits" title="c/types/limits"><code><limits.h></code></a> </td> <td> <a href="types/limits" title="c/types/limits">Ranges of integer types</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="locale" title="c/locale"><code><locale.h></code></a> </td> <td> <a href="locale" title="c/locale">Localization utilities</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="numeric/math" title="c/numeric/math"><code><math.h></code></a> </td> <td> <a href="numeric/math" title="c/numeric/math">Common mathematics functions</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="program" title="c/program"><code><setjmp.h></code></a> </td> <td> <a href="program" title="c/program">Nonlocal jumps</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="program" title="c/program"><code><signal.h></code></a> </td> <td> <a href="program" title="c/program">Signal handling</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="types" title="c/types"><code><stdalign.h></code></a> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> <td> <a href="types" title="c/types"><code>alignas</code> and <code>alignof</code></a> convenience macros </td> +</tr> <tr class="t-dsc"> <td> <a href="variadic" title="c/variadic"><code><stdarg.h></code></a> </td> <td> <a href="variadic" title="c/variadic">Variable arguments</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="thread#Atomic_operations" title="c/thread"><code><stdatomic.h></code></a> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> <td> <a href="thread#Atomic_operations" title="c/thread">Atomic operations</a> </td> +</tr> <tr class="t-dsc"> <td> <code><stdbit.h></code> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> <td> Macros to work with the byte and bit representations of types </td> +</tr> <tr class="t-dsc"> <td> <a href="types" title="c/types"><code><stdbool.h></code></a> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> <td> <a href="types" title="c/types">Macros for boolean type</a> </td> +</tr> <tr class="t-dsc"> <td> <code><stdckdint.h></code> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> <td> macros for performing checked integer arithmetic </td> +</tr> <tr class="t-dsc"> <td> <a href="types" title="c/types"><code><stddef.h></code></a> </td> <td> <a href="types" title="c/types">Common macro definitions</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="types/integer" title="c/types/integer"><code><stdint.h></code></a> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> <td> <a href="types/integer" title="c/types/integer">Fixed-width integer types</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="io" title="c/io"><code><stdio.h></code></a> </td> <td> <a href="io" title="c/io">Input/output</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="program" title="c/program"><code><stdlib.h></code></a> </td> <td> General utilities: <a href="memory" title="c/memory">memory management</a>, <a href="program" title="c/program">program utilities</a>, <a href="string" title="c/string">string conversions</a>, <a href="numeric/random" title="c/numeric/random">random numbers</a>, <a href="algorithm" title="c/algorithm">algorithms</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="language/_noreturn" title="c/language/ Noreturn"><code><stdnoreturn.h></code></a> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> <td> <a href="language/_noreturn" title="c/language/ Noreturn"><code>noreturn</code></a> convenience macro </td> +</tr> <tr class="t-dsc"> <td> <a href="string/byte" title="c/string/byte"><code><string.h></code></a> </td> <td> <a href="string/byte" title="c/string/byte">String handling</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="numeric/tgmath" title="c/numeric/tgmath"><code><tgmath.h></code></a> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> <td> <a href="numeric/tgmath" title="c/numeric/tgmath">Type-generic math</a> (macros wrapping math.h and complex.h) </td> +</tr> <tr class="t-dsc"> <td> <a href="thread" title="c/thread"><code><threads.h></code></a> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> <td> <a href="thread" title="c/thread">Thread library</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="chrono" title="c/chrono"><code><time.h></code></a> </td> <td> <a href="chrono" title="c/chrono">Time/date utilities</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="string/multibyte" title="c/string/multibyte"><code><uchar.h></code></a> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> <td> <a href="string/multibyte" title="c/string/multibyte">UTF-16 and UTF-32 character utilities</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="string/wide" title="c/string/wide"><code><wchar.h></code></a> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> <td> <a href="string/wide" title="c/string/wide">Extended multibyte and wide character utilities</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="string/wide" title="c/string/wide"><code><wctype.h></code></a> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> <td> <a href="string/wide" title="c/string/wide">Functions to determine the type contained in wide character data</a> </td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.1.2 Standard headers </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.1.2 Standard headers (p: 131-132) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.1.2 Standard headers (p: 181-182) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.1.2 Standard headers (p: 165) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.1.2 Standard headers </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/header" title="cpp/header">C++ documentation</a></span> for <span class=""><span>C++ Standard Library header files</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/header" class="_attribution-link">https://en.cppreference.com/w/c/header</a> + </p> +</div> diff --git a/devdocs/c/io%2Fclearerr.html b/devdocs/c/io%2Fclearerr.html new file mode 100644 index 00000000..0b82bfed --- /dev/null +++ b/devdocs/c/io%2Fclearerr.html @@ -0,0 +1,45 @@ + <h1 id="firstHeading" class="firstHeading">clearerr</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">void clearerr( FILE *stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Resets the error flags and the <a href="../io#Macro_constants" title="c/io"><code>EOF</code></a> indicator for the given file stream.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> the file to reset the error flags for </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <assert.h> + +int main(void) +{ + FILE* tmpf = tmpfile(); + fputs("cppreference.com\n", tmpf); + rewind(tmpf); + + for (int ch; (ch = fgetc(tmpf)) != EOF; putchar(ch)) { } + + assert(feof(tmpf)); // the loop is expected to terminate by EOF + puts("End of file reached"); + + clearerr(tmpf); // clear EOF + + puts(feof(tmpf) ? "EOF indicator set" + : "EOF indicator cleared"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">cppreference.com +End of file reached +EOF indicator cleared</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.21.10.1 The clearerr function (p: 246) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.10.1 The clearerr function (p: 338) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.10.1 The clearerr function (p: 304) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.10.1 The clearerr function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="feof" title="c/io/feof"> <span class="t-lines"><span>feof</span></span></a></div> </td> <td> checks for the end-of-file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="perror" title="c/io/perror"> <span class="t-lines"><span>perror</span></span></a></div> </td> <td> displays a character string corresponding of the current error to <code><a href="std_streams" title="c/io/std streams">stderr</a></code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ferror" title="c/io/ferror"> <span class="t-lines"><span>ferror</span></span></a></div> </td> <td> checks for a file error <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/clearerr" title="cpp/io/c/clearerr">C++ documentation</a></span> for <code>clearerr</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/clearerr" class="_attribution-link">https://en.cppreference.com/w/c/io/clearerr</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffclose.html b/devdocs/c/io%2Ffclose.html new file mode 100644 index 00000000..2c80600a --- /dev/null +++ b/devdocs/c/io%2Ffclose.html @@ -0,0 +1,57 @@ + <h1 id="firstHeading" class="firstHeading">fclose</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int fclose( FILE *stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Closes the given file stream. Any unwritten buffered data are flushed to the OS. Any unread buffered data are discarded.</p> +<p>Whether or not the operation succeeds, the stream is no longer associated with a file, and the buffer allocated by <code><a href="setbuf" title="c/io/setbuf">setbuf</a></code> or <code><a href="setvbuf" title="c/io/setvbuf">setvbuf</a></code>, if any, is also disassociated and deallocated if automatic allocation was used.</p> +<p>The behavior is undefined if the value of the pointer <code>stream</code> is used after <code>fclose</code> returns.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> the file stream to close </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>0</code> on success, <code><a href="../io" title="c/io">EOF</a></code> otherwise</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + const char* fname = "/tmp/unique_name.txt"; // or tmpnam(NULL); + int is_ok = EXIT_FAILURE; + + FILE* fp = fopen(fname, "w+"); + if (!fp) { + perror("File opening failed"); + return is_ok; + } + fputs("Hello, world!\n", fp); + rewind(fp); + + int c; // note: int, not char, required to handle EOF + while ((c = fgetc(fp)) != EOF) // standard C I/O file reading loop + putchar(c); + + if (ferror(fp)) + puts("I/O error when reading"); + else if (feof(fp)) { + puts("End of file is reached successfully"); + is_ok = EXIT_SUCCESS; + } + + fclose(fp); + remove(fname); + return is_ok; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Hello, world! +End of file is reached successfully</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.5.1 The fclose function (p: 304) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.5.1 The fclose function (p: 270) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.5.1 The fclose function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fopen" title="c/io/fopen"> <span class="t-lines"><span>fopen</span><span>fopen_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> opens a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="freopen" title="c/io/freopen"> <span class="t-lines"><span>freopen</span><span>freopen_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> open an existing stream with a different name <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fclose" title="cpp/io/c/fclose">C++ documentation</a></span> for <code>fclose</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fclose" class="_attribution-link">https://en.cppreference.com/w/c/io/fclose</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffeof.html b/devdocs/c/io%2Ffeof.html new file mode 100644 index 00000000..088f217b --- /dev/null +++ b/devdocs/c/io%2Ffeof.html @@ -0,0 +1,56 @@ + <h1 id="firstHeading" class="firstHeading">feof</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int feof( FILE *stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Checks if the end of the given file stream has been reached.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> the file stream to check </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>nonzero value if the end of the stream has been reached, otherwise <code>0</code></p> +<h3 id="Notes"> Notes</h3> <p>This function only reports the stream state as reported by the most recent I/O operation, it does not examine the associated data source. For example, if the most recent I/O was a <code><a href="fgetc" title="c/io/fgetc">fgetc</a></code>, which returned the last byte of a file, <code>feof</code> returns zero. The next <code><a href="fgetc" title="c/io/fgetc">fgetc</a></code> fails and changes the stream state to <i>end-of-file</i>. Only then <code>feof</code> returns non-zero.</p> +<p>In typical usage, input stream processing stops on any error; <code>feof</code> and <code><a href="ferror" title="c/io/ferror">ferror</a></code> are then used to distinguish between different error conditions.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + const char* fname = "/tmp/unique_name.txt"; // or tmpnam(NULL); + int is_ok = EXIT_FAILURE; + + FILE* fp = fopen(fname, "w+"); + if (!fp) { + perror("File opening failed"); + return is_ok; + } + fputs("Hello, world!\n", fp); + rewind(fp); + + int c; // note: int, not char, required to handle EOF + while ((c = fgetc(fp)) != EOF) // standard C I/O file reading loop + putchar(c); + + if (ferror(fp)) + puts("I/O error when reading"); + else if (feof(fp)) { + puts("End of file is reached successfully"); + is_ok = EXIT_SUCCESS; + } + + fclose(fp); + remove(fname); + return is_ok; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Hello, world! +End of file is reached successfully</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.10.2 The feof function (p: 339) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.10.2 The feof function (p: 305) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.10.2 The feof function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="clearerr" title="c/io/clearerr"> <span class="t-lines"><span>clearerr</span></span></a></div> </td> <td> clears errors <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="perror" title="c/io/perror"> <span class="t-lines"><span>perror</span></span></a></div> </td> <td> displays a character string corresponding of the current error to <code><a href="std_streams" title="c/io/std streams">stderr</a></code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ferror" title="c/io/ferror"> <span class="t-lines"><span>ferror</span></span></a></div> </td> <td> checks for a file error <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/feof" title="cpp/io/c/feof">C++ documentation</a></span> for <code>feof</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/feof" class="_attribution-link">https://en.cppreference.com/w/c/io/feof</a> + </p> +</div> diff --git a/devdocs/c/io%2Fferror.html b/devdocs/c/io%2Fferror.html new file mode 100644 index 00000000..4742b467 --- /dev/null +++ b/devdocs/c/io%2Fferror.html @@ -0,0 +1,44 @@ + <h1 id="firstHeading" class="firstHeading">ferror</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int ferror( FILE *stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Checks the given stream for errors.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> the file stream to check </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Nonzero value if the file stream has errors occurred, <code>0</code> otherwise</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> +#include <locale.h> +#include <wchar.h> + +int main(void) +{ + char* fname = tmpnam(NULL); + FILE* f = fopen(fname, "wb"); + fputs("\xff\xff\n", f); // not a valid UTF-8 character sequence + fclose(f); + + setlocale(LC_ALL, "en_US.utf8"); + f = fopen(fname, "rb"); + wint_t ch; + while ((ch=fgetwc(f)) != WEOF) // attempt to read as UTF-8 fails + printf("%#x ", ch); + + if (feof(f)) + puts("EOF indicator set"); + if (ferror(f)) + puts("Error indicator set"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Error indicator set</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.10.3 The ferror function (p: 339) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.10.3 The ferror function (p: 305) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.10.3 The ferror function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="clearerr" title="c/io/clearerr"> <span class="t-lines"><span>clearerr</span></span></a></div> </td> <td> clears errors <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="feof" title="c/io/feof"> <span class="t-lines"><span>feof</span></span></a></div> </td> <td> checks for the end-of-file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/ferror" title="cpp/io/c/ferror">C++ documentation</a></span> for <code>ferror</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/ferror" class="_attribution-link">https://en.cppreference.com/w/c/io/ferror</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffflush.html b/devdocs/c/io%2Ffflush.html new file mode 100644 index 00000000..b3ba8716 --- /dev/null +++ b/devdocs/c/io%2Ffflush.html @@ -0,0 +1,26 @@ + <h1 id="firstHeading" class="firstHeading">fflush</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int fflush( FILE *stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>For output streams (and for update streams on which the last operation was output), writes any unwritten data from the <code>stream</code>'s buffer to the associated output device.</p> +<p>For input streams (and for update streams on which the last operation was input), the behavior is undefined.</p> +<p>If <code>stream</code> is a null pointer, all open output streams are flushed, including the ones manipulated within library packages or otherwise not directly accessible to the program.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> the file stream to write out </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Returns zero on success. Otherwise <code><a href="../io" title="c/io">EOF</a></code> is returned and the error indicator of the file stream is set.</p> +<h3 id="Notes"> Notes</h3> <p>POSIX <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/fflush.html">extends the specification of fflush</a> by defining its effects on an input stream, as long as that stream represents a file or another seekable device: in that case the POSIX file pointer is repositioned to match the C stream pointer (which effectively undoes any read buffering) and the effects of any <code><a href="ungetc" title="c/io/ungetc">ungetc</a></code> or <code><a href="ungetwc" title="c/io/ungetwc">ungetwc</a></code> that weren't yet read back from the stream are discarded.</p> +<p>Microsoft also extends the specification of fflush by defining its effects on an input stream: in Visual Studio 2013 and prior, it <a rel="nofollow" class="external text" href="https://docs.microsoft.com/en-us/previous-versions/visualstudio/visual-studio-2013/9yky46tz(v=vs.120)">discarded the input buffer</a>, in Visual Studio 2015 and newer, it <a rel="nofollow" class="external text" href="https://msdn.microsoft.com/en-us/library/9yky46tz.aspx">has no effect, buffers are retained</a>.</p> +<h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.5.2 The fflush function (p: 305) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.5.2 The fflush function (p: 270-271) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.5.2 The fflush function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fopen" title="c/io/fopen"> <span class="t-lines"><span>fopen</span><span>fopen_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> opens a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fclose" title="c/io/fclose"> <span class="t-lines"><span>fclose</span></span></a></div> </td> <td> closes a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fflush" title="cpp/io/c/fflush">C++ documentation</a></span> for <code>fflush</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fflush" class="_attribution-link">https://en.cppreference.com/w/c/io/fflush</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffgetc.html b/devdocs/c/io%2Ffgetc.html new file mode 100644 index 00000000..0f73cb25 --- /dev/null +++ b/devdocs/c/io%2Ffgetc.html @@ -0,0 +1,73 @@ + <h1 id="firstHeading" class="firstHeading">fgetc, getc</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int fgetc( FILE *stream );</pre> +</td> <td> (1) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int getc( FILE *stream );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Reads the next character from the given input stream.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <code>fgetc</code>, except that if <code>getc</code> is implemented as a macro, it may evaluate stream more than once, so the corresponding argument should never be an expression with side effects.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> to read the character from </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>On success, returns the obtained character as an <code>unsigned char</code> converted to an <code>int</code>. On failure, returns <code><a href="../io" title="c/io">EOF</a></code>.</p> +<p>If the failure has been caused by end-of-file condition, additionally sets the <i>eof</i> indicator (see <code><a href="feof" title="c/io/feof">feof()</a></code>) on <code>stream</code>. If the failure has been caused by some other error, sets the <i>error</i> indicator (see <code><a href="ferror" title="c/io/ferror">ferror()</a></code>) on <code>stream</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + const char* fname = "/tmp/unique_name.txt"; // or tmpnam(NULL); + int is_ok = EXIT_FAILURE; + + FILE* fp = fopen(fname, "w+"); + if (!fp) { + perror("File opening failed"); + return is_ok; + } + fputs("Hello, world!\n", fp); + rewind(fp); + + int c; // note: int, not char, required to handle EOF + while ((c = fgetc(fp)) != EOF) // standard C I/O file reading loop + putchar(c); + + if (ferror(fp)) + puts("I/O error when reading"); + else if (feof(fp)) { + puts("End of file is reached successfully"); + is_ok = EXIT_SUCCESS; + } + + fclose(fp); + remove(fname); + return is_ok; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Hello, world! +End of file is reached successfully</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.21.7.1 The fgetc function (p: 240-241) </li> +<li> 7.21.7.5 The getc function (p: 242) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.21.7.1 The fgetc function (p: 330) </li> +<li> 7.21.7.5 The getc function (p: 332) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.19.7.1 The fgetc function (p: 296) </li> +<li> 7.19.7.5 The getc function (p: 297-298) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 4.9.7.1 The fgetc function </li> +<li> 4.9.7.5 The getc function </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="getchar" title="c/io/getchar"> <span class="t-lines"><span>getchar</span></span></a></div> </td> <td> reads a character from <code><a href="std_streams" title="c/io/std streams">stdin</a></code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="gets" title="c/io/gets"> <span class="t-lines"><span>gets</span><span>gets_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-until-c11">(removed in C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads a character string from <code>stdin</code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fputc" title="c/io/fputc"> <span class="t-lines"><span>fputc</span><span>putc</span></span></a></div> </td> <td> writes a character to a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ungetc" title="c/io/ungetc"> <span class="t-lines"><span>ungetc</span></span></a></div> </td> <td> puts a character back into a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fgetc" title="cpp/io/c/fgetc">C++ documentation</a></span> for <code>fgetc, getc</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fgetc" class="_attribution-link">https://en.cppreference.com/w/c/io/fgetc</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffgetpos.html b/devdocs/c/io%2Ffgetpos.html new file mode 100644 index 00000000..4a403e25 --- /dev/null +++ b/devdocs/c/io%2Ffgetpos.html @@ -0,0 +1,58 @@ + <h1 id="firstHeading" class="firstHeading">fgetpos</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">int fgetpos( FILE *stream, fpos_t *pos );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int fgetpos( FILE *restrict stream, fpos_t *restrict pos );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Obtains the file position indicator and the current parse state (if any) for the file stream <code>stream</code> and stores them in the object pointed to by <code>pos</code>. The value stored is only meaningful as the input to <code><a href="fsetpos" title="c/io/fsetpos">fsetpos</a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> file stream to examine </td> +</tr> <tr class="t-par"> <td> pos </td> <td> - </td> <td> pointer to a <code><a href="fpos_t" title="c/io/fpos t">fpos_t</a></code> object to store the file position indicator to </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>0</code> upon success, nonzero value otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> +#include <assert.h> + +int main(void) +{ + // prepare a file holding 4 values of type double + enum {SIZE = 4}; + FILE* fp = fopen("test.bin", "wb"); + assert(fp); + int rc = fwrite((double[SIZE]){1.1, 2.2, 3.3, 4.4}, sizeof(double), SIZE, fp); + assert(rc == SIZE); + fclose(fp); + + // demo using fsetpos to return to the beginning of a file + fp = fopen("test.bin", "rb"); + fpos_t pos; + fgetpos(fp, &pos); // store start of file in pos + double d; + rc = fread(&d, sizeof d, 1, fp); // read the first double + assert(rc == 1); + printf("First value in the file: %.1f\n", d); + fsetpos(fp,&pos); // move file position back to the start of the file + rc = fread(&d, sizeof d, 1, fp); // read the first double again + assert(rc == 1); + printf("First value in the file again: %.1f\n", d); + fclose(fp); + + // demo error handling + rc = fsetpos(stdin, &pos); + if(rc) perror("could not fsetpos stdin"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">First value in the file: 1.1 +First value in the file again: 1.1 +could not fsetpos stdin: Illegal seek</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.9.1 The fgetpos function (p: 336) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.9.1 The fgetpos function (p: 302) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.9.1 The fgetpos function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="ftell" title="c/io/ftell"> <span class="t-lines"><span>ftell</span></span></a></div> </td> <td> returns the current file position indicator <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fseek" title="c/io/fseek"> <span class="t-lines"><span>fseek</span></span></a></div> </td> <td> moves the file position indicator to a specific location in a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fsetpos" title="c/io/fsetpos"> <span class="t-lines"><span>fsetpos</span></span></a></div> </td> <td> moves the file position indicator to a specific location in a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fgetpos" title="cpp/io/c/fgetpos">C++ documentation</a></span> for <code>fgetpos</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fgetpos" class="_attribution-link">https://en.cppreference.com/w/c/io/fgetpos</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffgets.html b/devdocs/c/io%2Ffgets.html new file mode 100644 index 00000000..c6178a7d --- /dev/null +++ b/devdocs/c/io%2Ffgets.html @@ -0,0 +1,71 @@ + <h1 id="firstHeading" class="firstHeading">fgets</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">char *fgets( char *str, int count, FILE *stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">char *fgets( char *restrict str, int count, FILE *restrict stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Reads at most <code>count - 1</code> characters from the given file stream and stores them in the character array pointed to by <code>str</code>. Parsing stops if a newline character is found, in which case <code>str</code> will contain that newline character, or if end-of-file occurs. If bytes are read and no errors occur, writes a null character at the position immediately after the last character written to <code>str</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> pointer to an element of a char array </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> maximum number of characters to write (typically the length of <code>str</code>) </td> +</tr> <tr class="t-par"> <td> stream </td> <td> - </td> <td> file stream to read the data from </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>str</code> on success, null pointer on failure.</p> +<p>If the end-of-file condition is encountered, sets the <i>eof</i> indicator on <code>stream</code> (see <code><a href="feof" title="c/io/feof">feof()</a></code>). This is only a failure if it causes no bytes to be read, in which case a null pointer is returned and the contents of the array pointed to by <code>str</code> are not altered (i.e. the first byte is not overwritten with a null character).</p> +<p>If the failure has been caused by some other error, sets the <i>error</i> indicator (see <code><a href="ferror" title="c/io/ferror">ferror()</a></code>) on <code>stream</code>. The contents of the array pointed to by <code>str</code> are indeterminate (it may not even be null-terminated).</p> +<h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/fgets.html">POSIX additionally requires</a> that <code>fgets</code> sets <code><a href="../error/errno" title="c/error/errno">errno</a></code> if a read error occurs.</p> +<p>Although the standard specification is <a rel="nofollow" class="external text" href="https://stackoverflow.com/questions/23388620">unclear</a> in the cases where <code>count<=1</code>, common implementations do</p> +<ul> +<li> if <code>count < 1</code>, do nothing, report error </li> +<li> if <code>count == 1</code>, </li> +<ul> +<li> some implementations do nothing, report error, </li> +<li> others read nothing, store zero in <code>str[0]</code>, report success </li> +</ul> +</ul> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + FILE* tmpf = tmpfile(); + fputs("Alan Turing\n", tmpf); + fputs("John von Neumann\n", tmpf); + fputs("Alonzo Church\n", tmpf); + + rewind(tmpf); + + char buf[8]; + while (fgets(buf, sizeof buf, tmpf) != NULL) + printf("\"%s\"\n", buf); + + if (feof(tmpf)) + puts("End of file reached"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">"Alan Tu" +"ring +" +"John vo" +"n Neuma" +"nn +" +"Alonzo " +"Church +" +End of file reached</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.21.7.2 The fgets function (p: 241) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.7.2 The fgets function (p: 331) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.7.2 The fgets function (p: 296) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.7.2 The fgets function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fscanf" title="c/io/fscanf"> <span class="t-lines"><span>scanf</span><span>fscanf</span><span>sscanf</span><span>scanf_s</span><span>fscanf_s</span><span>sscanf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads formatted input from <code><a href="std_streams" title="c/io/std streams">stdin</a></code>, a file stream or a buffer <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="gets" title="c/io/gets"> <span class="t-lines"><span>gets</span><span>gets_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-until-c11">(removed in C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads a character string from <code>stdin</code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fputs" title="c/io/fputs"> <span class="t-lines"><span>fputs</span></span></a></div> </td> <td> writes a character string to a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="https://en.cppreference.com/w/c/experimental/dynamic/getline" title="c/experimental/dynamic/getline"> <span class="t-lines"><span>getline</span><span>getwline</span><span>getdelim</span><span>getwdelim</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-dynamic-tr t-mark-ts">(dynamic memory TR)</span></span></span></div> </td> <td> read from a stream into an automatically resized buffer until delimiter/end of line <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fgets" title="cpp/io/c/fgets">C++ documentation</a></span> for <code>fgets</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fgets" class="_attribution-link">https://en.cppreference.com/w/c/io/fgets</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffgetwc.html b/devdocs/c/io%2Ffgetwc.html new file mode 100644 index 00000000..c17f187d --- /dev/null +++ b/devdocs/c/io%2Ffgetwc.html @@ -0,0 +1,75 @@ + <h1 id="firstHeading" class="firstHeading">fgetwc, getwc</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">wint_t fgetwc( FILE *stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">wint_t getwc( FILE *stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Reads the next wide character from the given input stream. <code>getwc()</code> may be implemented as a macro and may evaluate <code>stream</code> more than once.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> to read the wide character from </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The next wide character from the stream or <code>WEOF</code> on failure.</p> +<p>If the failure has been caused by end-of-file condition, additionally sets the <i>eof</i> indicator (see <code><a href="feof" title="c/io/feof">feof()</a></code>) on <code>stream</code>. If the failure has been caused by some other error, sets the <i>error</i> indicator (see <code><a href="ferror" title="c/io/ferror">ferror()</a></code>) on <code>stream</code>.</p> +<p>If an encoding error occurred, additionally sets <code><a href="../error/errno" title="c/error/errno">errno</a></code> to <code>EILSEQ</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> +#include <wchar.h> +#include <errno.h> +#include <locale.h> + +int main(void) +{ + setlocale(LC_ALL, "en_US.utf8"); + FILE *fp = fopen("fgetwc.dat", "w"); + if(!fp) { + perror("Can't open file for writing"); + return EXIT_FAILURE; + } + fputs("кошка\n", fp); + fclose(fp); + + fp = fopen("fgetwc.dat", "r"); + if(!fp) { + perror("Can't open file for reading"); + return EXIT_FAILURE; + } + wint_t wc; + errno = 0; + while ((wc = fgetwc(fp)) != WEOF) + putwchar(wc); + + if (ferror(fp)) { + if (errno == EILSEQ) + puts("Character encoding error while reading."); + else + puts("I/O error when reading"); + } else if (feof(fp)) + puts("End of file reached successfully"); + + fclose(fp); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">кошка</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.29.3.1 The fgetwc function (p: 307-308) </li> +<li> 7.29.3.6 The getwc function (p: 309) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.29.3.1 The fgetwc function (p: 421-422) </li> +<li> 7.29.3.6 The getwc function (p: 424) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.24.3.1 The fgetwc function (p: 367) </li> +<li> 7.24.3.6 The getwc function (p: 369) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fgetc" title="c/io/fgetc"> <span class="t-lines"><span>fgetc</span><span>getc</span></span></a></div> </td> <td> gets a character from a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fgetws" title="c/io/fgetws"> <span class="t-lines"><span>fgetws</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> gets a wide string from a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fputwc" title="c/io/fputwc"> <span class="t-lines"><span>fputwc</span><span>putwc</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> writes a wide character to a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ungetwc" title="c/io/ungetwc"> <span class="t-lines"><span>ungetwc</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> puts a wide character back into a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fgetwc" title="cpp/io/c/fgetwc">C++ documentation</a></span> for <code>fgetwc</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fgetwc" class="_attribution-link">https://en.cppreference.com/w/c/io/fgetwc</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffgetws.html b/devdocs/c/io%2Ffgetws.html new file mode 100644 index 00000000..acd7f5bb --- /dev/null +++ b/devdocs/c/io%2Ffgetws.html @@ -0,0 +1,32 @@ + <h1 id="firstHeading" class="firstHeading">fgetws</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td> <pre data-language="c">wchar_t* fgetws( wchar_t* str, int count, FILE* stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">wchar_t* fgetws( wchar_t* restrict str, int count, FILE* restrict stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Reads at most <code>count - 1</code> wide characters from the given file stream and stores them in <code>str</code>. The produced wide string is always null-terminated. Parsing stops if end-of-file occurs or a newline wide character is found, in which case <code>str</code> will contain that wide newline character.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> wide string to read the characters to </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> the length of <code>str</code> </td> +</tr> <tr class="t-par"> <td> stream </td> <td> - </td> <td> file stream to read the data from </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>str</code> on success, a null pointer on an error</p> +<h3 id="Example"> Example</h3> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.29.3.2 The fgetws function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.29.3.2 The fgetws function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.3.2 The fgetws function (p: 422) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.3.2 The fgetws function (p: 367-368) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fwscanf" title="c/io/fwscanf"> <span class="t-lines"><span>wscanf</span><span>fwscanf</span><span>swscanf</span><span>wscanf_s</span><span>fwscanf_s</span><span>swscanf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads formatted wide character input from <code><a href="std_streams" title="c/io/std streams">stdin</a></code>, a file stream or a buffer <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fgetwc" title="c/io/fgetwc"> <span class="t-lines"><span>fgetwc</span><span>getwc</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> gets a wide character from a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fputws" title="c/io/fputws"> <span class="t-lines"><span>fputws</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> writes a wide string to a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="https://en.cppreference.com/w/c/experimental/dynamic/getline" title="c/experimental/dynamic/getline"> <span class="t-lines"><span>getline</span><span>getwline</span><span>getdelim</span><span>getwdelim</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-dynamic-tr t-mark-ts">(dynamic memory TR)</span></span></span></div> </td> <td> read from a stream into an automatically resized buffer until delimiter/end of line <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fgetws" title="cpp/io/c/fgetws">C++ documentation</a></span> for <code>fgetws</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fgetws" class="_attribution-link">https://en.cppreference.com/w/c/io/fgetws</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffile.html b/devdocs/c/io%2Ffile.html new file mode 100644 index 00000000..2f7b23df --- /dev/null +++ b/devdocs/c/io%2Ffile.html @@ -0,0 +1,53 @@ + <h1 id="firstHeading" class="firstHeading">FILE</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">typedef /* unspecified */ FILE;</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Each <code>FILE</code> object denotes a C stream.</p> +<p>C standard does not specify whether <code>FILE</code> is a complete object type. While it may be possible to copy a valid <code>FILE</code>, using a pointer to such a copy as an argument for an I/O function invokes unspecified behavior. In other words, <code>FILE</code> may be semantically non-copyable.</p> +<p>I/O streams can be used for both unformatted and formatted input and output. Furthermore, the functions that handle input and output can also be locale-sensitive, such that wide/multibyte conversions are performed as necessary.</p> +<h3 id="Stream_state"> Stream state</h3> <p>Besides the system-specific information necessary to access the device (<i>e.g.,</i> a POSIX file descriptor), each <code>FILE</code> object directly or indirectly holds the following:</p> +<ol> +<li> <span class="t-mark-rev t-since-c95">(C95)</span> Character width: unset, narrow, or wide. </li> +<li> <span class="t-mark-rev t-since-c95">(C95)</span> Parse state for conversions between multibyte and wide characters (an object of type <code><a href="../string/multibyte/mbstate_t" title="c/string/multibyte/mbstate t">mbstate_t</a></code>) </li> +<li> Buffering state: unbuffered, line-buffered, fully buffered. </li> +<li> The buffer, which may be replaced by an external, user-provided buffer. </li> +<li> I/O mode: input, output, or update (both input and output). </li> +<li> Binary/text mode indicator. </li> +<li> End-of-file status indicator. </li> +<li> Error status indicator. </li> +<li> File position indicator, accessible as an object of type <code><a href="fpos_t" title="c/io/fpos t">fpos_t</a></code>, which, for wide streams, includes parse state. </li> +<li> <span class="t-mark-rev t-since-c11">(C11)</span> Reentrant lock used to prevent data races when multiple threads read, write, position, or query the position of a stream. </li> +</ol> <h4 id="Narrow_and_wide_orientation"> Narrow and wide orientation</h4> <p>A newly opened stream has no orientation. The first call to <code>fwide</code> or to any I/O function establishes the orientation: a wide I/O function makes the stream wide-oriented; a narrow I/O function makes the stream narrow-oriented. Once set, the orientation can be changed with only <code><a href="freopen" title="c/io/freopen">freopen</a></code>. Narrow I/O functions cannot be called on a wide-oriented stream; wide I/O functions cannot be called on a narrow-oriented stream. Wide I/O functions convert between wide and multibyte characters as if by calling <code><a href="../string/multibyte/mbrtowc" title="c/string/multibyte/mbrtowc">mbrtowc</a></code> or <code><a href="../string/multibyte/wcrtomb" title="c/string/multibyte/wcrtomb">wcrtomb</a></code> with the conversion state as described by the stream. Unlike the multibyte character strings that are valid in a program, multibyte character sequences in the file may contain embedded nulls and do not have to begin or end in the initial shift state.</p> +<p>The conversion state of a stream with wide orientation is established by the C locale that is installed at the time the stream's orientation is set.</p> +<h4 id="Binary_and_text_modes"> Binary and text modes</h4> <p>A <i>text stream</i> is an ordered sequence of characters that can be composed into lines; a line can be decomposed into zero or more characters plus a terminating <code>'\n'</code> (“newline”) character. Whether the last line requires a terminating <code>'\n'</code> is implementation-defined. Furthermore, characters may have to be added, altered, or deleted on input and output to conform to the conventions for representing text in the OS (in particular, C streams on Windows OS convert <code>'\n'</code> to <code>'\r\n'</code> on output, and convert <code>'\r\n'</code> to <code>'\n'</code> on input).</p> +<p>Data read in from a text stream is guaranteed to compare equal to the data that were earlier written out to that stream only if each of the following is true:</p> +<ul> +<li> The data consist of only printing characters and/or the control characters <code>'\t'</code> and <code>'\n'</code> (in particular, on Windows OS, the character <code>'\0x1A'</code> terminates input). </li> +<li> No <code>'\n'</code> character is immediately preceded by space characters (such space characters may disappear when such output is later read as input). </li> +<li> The last character is <code>'\n'</code>. </li> +</ul> <p>A <i>binary stream</i> is an ordered sequence of characters that can transparently record internal data. Data read in from a binary stream always equal the data that were earlier written out to that stream, except that an implementation is allowed to append an indeterminate number of null characters to the end of the stream. A wide binary stream doesn't need to end in the initial shift state.</p> +<h3 id="Notes"> Notes</h3> <p>POSIX explicitly requires that the <code>LC_CTYPE</code> facet of the currently installed C locale be stored within the <code>FILE</code> object the moment the stream's orientation becomes wide; POSIX requires that this <code>LC_CTYPE</code> facet be used for all future I/O on this stream until the orientation is changed, regardless of any subsequent call to <code><a href="../locale/setlocale" title="c/locale/setlocale">setlocale</a></code>.</p> +<p>It is intended that each line of text be composed of data that are essentially human-readable. POSIX implementations do not distinguish between text and binary streams (there is no special mapping for <code>'\n'</code> or any other characters).</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.21 Input/output <stdio.h> (p: 217-247) </li> +<li> 7.29 Extended multibyte and wide character utilities <wchar.h> (p: 295-325) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.21 Input/output <stdio.h> (p: 296-339) </li> +<li> 7.29 Extended multibyte and wide character utilities <wchar.h> (p: 402-446) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.19 Input/output <stdio.h> (p: 262-305) </li> +<li> 7.24 Extended multibyte and wide character utilities <wchar.h> (p: 348-392) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9 INPUT/OUTPUT <stdio.h> </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="std_streams" title="c/io/std streams"> <span class="t-lines"><span>stdin</span><span>stdout</span><span>stderr</span></span></a></div> </td> <td> expression of type <code>FILE*</code> associated with the input stream<br>expression of type <code>FILE*</code> associated with the output stream<br>expression of type <code>FILE*</code> associated with the error output stream <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/FILE" title="cpp/io/c/FILE">C++ documentation</a></span> for <code>FILE</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/FILE" class="_attribution-link">https://en.cppreference.com/w/c/io/FILE</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffopen.html b/devdocs/c/io%2Ffopen.html new file mode 100644 index 00000000..802ab3fc --- /dev/null +++ b/devdocs/c/io%2Ffopen.html @@ -0,0 +1,89 @@ + <h1 id="firstHeading" class="firstHeading">fopen, fopen_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">FILE *fopen( const char *filename, const char *mode );</pre> +</td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">FILE *fopen( const char *restrict filename, const char *restrict mode );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t fopen_s( FILE *restrict *restrict streamptr, + const char *restrict filename, + const char *restrict mode );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Opens a file indicated by <code>filename</code> and returns a pointer to the file stream associated with that file. <code>mode</code> is used to determine the file access mode. </div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that the pointer to the file stream is written to <code>streamptr</code> and the following errors are detected at runtime and call the currently installed <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <ul> +<li> <code>streamptr</code> is a null pointer </li> +<li> <code>filename</code> is a null pointer </li> +<li> <code>mode</code> is a null pointer </li> +</ul> As with all bounds-checked functions, <code>fopen_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../io" title="c/io"><code><stdio.h></code></a>.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> filename </td> <td> - </td> <td> file name to associate the file stream to </td> +</tr> <tr class="t-par"> <td> mode </td> <td> - </td> <td> null-terminated character string determining <a href="#File_access_flags">file access mode</a> </td> +</tr> <tr class="t-par"> <td> streamptr </td> <td> - </td> <td> pointer to a pointer where the function stores the result (an out-parameter) </td> +</tr> +</table> <h3 id="File_access_flags"> File access flags</h3> <table class="wikitable"> <tr> <th> File access <br>mode string </th> <th> Meaning </th> <th> Explanation </th> <th> Action if file <br> already exists </th> <th> Action if file <br> does not exist </th> +</tr> <tr> <td> <code>"r"</code> </td> <td> read </td> <td> Open a file for reading </td> <td> read from start </td> <td> failure to open </td> +</tr> <tr> <td> <code>"w"</code> </td> <td> write </td> <td> Create a file for writing </td> <td> destroy contents </td> <td> create new </td> +</tr> <tr> <td> <code>"a"</code> </td> <td> append </td> <td> Append to a file </td> <td> write to end </td> <td> create new </td> +</tr> <tr> <td> <code>"r+"</code> </td> <td> read extended </td> <td> Open a file for read/write </td> <td> read from start </td> <td> error </td> +</tr> <tr> <td> <code>"w+"</code> </td> <td> write extended </td> <td> Create a file for read/write </td> <td> destroy contents </td> <td> create new </td> +</tr> <tr> <td> <code>"a+"</code> </td> <td> append extended </td> <td> Open a file for read/write </td> <td> write to end </td> <td> create new </td> +</tr> <tr> <td colspan="5"> File access mode flag <code>"b"</code> can optionally be specified to open a file in binary mode. This flag has no effect on POSIX systems, but on Windows it disables special handling of <code>'\n'</code> and <code>'\x1A'</code>. <br> On the append file access modes, data is written to the end of the file regardless of the current position of the file position indicator. </td> +</tr> <tr> <td colspan="5"> The behavior is undefined if the mode is not one of the strings listed above. Some implementations define additional supported modes (e.g. <a rel="nofollow" class="external text" href="https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/fopen-wfopen">Windows</a>). </td> +</tr> <tr> <td colspan="5"> In update mode (<code>'+'</code>), both input and output may be performed, but output cannot be followed by input without an intervening call to <code><a href="fflush" title="c/io/fflush">fflush</a></code>, <code><a href="fseek" title="c/io/fseek">fseek</a></code>, <code><a href="fsetpos" title="c/io/fsetpos">fsetpos</a></code> or <code><a href="rewind" title="c/io/rewind">rewind</a></code>, and input cannot be followed by output without an intervening call to <code><a href="fseek" title="c/io/fseek">fseek</a></code>, <code><a href="fsetpos" title="c/io/fsetpos">fsetpos</a></code> or <code><a href="rewind" title="c/io/rewind">rewind</a></code>, unless the input operation encountered end of file. In update mode, implementations are permitted to use binary mode even when text mode is specified. </td> +</tr> <tr> <td colspan="5"> File access mode flag <code>"x"</code> can optionally be appended to <code>"w"</code> or <code>"w+"</code> specifiers. This flag forces the function to fail if the file exists, instead of overwriting it. <span class="t-mark-rev t-since-c11">(C11)</span> </td> +</tr> <tr> <td colspan="5"> When using <code>fopen_s</code> or <code>freopen_s</code>, file access permissions for any file created with <code>"w"</code> or <code>"a"</code> prevents other users from accessing it. File access mode flag <code>"u"</code> can optionally be prepended to any specifier that begins with <code>"w"</code> or <code>"a"</code>, to enable the default <code>fopen</code> permissions. <span class="t-mark-rev t-since-c11">(C11)</span> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> If successful, returns a pointer to the new file stream. The stream is fully buffered unless <code>filename</code> refers to an interactive device. On error, returns a null pointer. <a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/fopen.html">POSIX requires</a> that <code><a href="../error/errno" title="c/error/errno">errno</a></code> be set in this case.</div> <div class="t-li1"> +<span class="t-li">2)</span> If successful, returns zero and a pointer to the new file stream is written to <code>*streamptr</code>. On error, returns a non-zero error code and writes the null pointer to <code>*streamptr</code> (unless <code>streamptr</code> is a null pointer itself).</div> <h3 id="Notes"> Notes</h3> <p>The format of <code>filename</code> is implementation-defined, and does not necessarily refer to a file (e.g. it may be the console or another device accessible though filesystem API). On platforms that support them, <code>filename</code> may include absolute or relative filesystem path.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + const char* fname = "/tmp/unique_name.txt"; // or tmpnam(NULL); + int is_ok = EXIT_FAILURE; + + FILE* fp = fopen(fname, "w+"); + if (!fp) { + perror("File opening failed"); + return is_ok; + } + fputs("Hello, world!\n", fp); + rewind(fp); + + int c; // note: int, not char, required to handle EOF + while ((c = fgetc(fp)) != EOF) // standard C I/O file reading loop + putchar(c); + + if (ferror(fp)) + puts("I/O error when reading"); + else if (feof(fp)) { + puts("End of file is reached successfully"); + is_ok = EXIT_SUCCESS; + } + + fclose(fp); + remove(fname); + return is_ok; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Hello, world! +End of file is reached successfully</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.21.5.3 The fopen function (p: 223-224) </li> +<li> K.3.5.2.1 The fopen_s function (p: 428-429) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.21.5.3 The fopen function (p: 305-306) </li> +<li> K.3.5.2.1 The fopen_s function (p: 588-590) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.5.3 The fopen function (p: 271-272) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.5.3 The fopen function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fclose" title="c/io/fclose"> <span class="t-lines"><span>fclose</span></span></a></div> </td> <td> closes a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fflush" title="c/io/fflush"> <span class="t-lines"><span>fflush</span></span></a></div> </td> <td> synchronizes an output stream with the actual file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="freopen" title="c/io/freopen"> <span class="t-lines"><span>freopen</span><span>freopen_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> open an existing stream with a different name <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fopen" title="cpp/io/c/fopen">C++ documentation</a></span> for <code>fopen</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fopen" class="_attribution-link">https://en.cppreference.com/w/c/io/fopen</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffpos_t.html b/devdocs/c/io%2Ffpos_t.html new file mode 100644 index 00000000..7bbe71bb --- /dev/null +++ b/devdocs/c/io%2Ffpos_t.html @@ -0,0 +1,37 @@ + <h1 id="firstHeading" class="firstHeading">fpos_t</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">typedef /* implementation-defined */ fpos_t;</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p><code>fpos_t</code> is a non-array complete object type, can be used to store (by <code><a href="fgetpos" title="c/io/fgetpos">fgetpos</a></code>) and restore (by <code><a href="fsetpos" title="c/io/fsetpos">fsetpos</a></code>) the position and multibyte parser state (if any) for a C stream.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c95"> +<td> <p>The multibyte parser state of a wide-oriented C stream is represented by a <code><a href="../string/multibyte/mbstate_t" title="c/string/multibyte/mbstate t">mbstate_t</a></code> object, whose value is stored as part of the value of a <code>fpos_t</code> object by <code><a href="fgetpos" title="c/io/fgetpos">fgetpos</a></code>.</p> +</td> <td><span class="t-mark-rev t-since-c95">(since C95)</span></td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.21.1 Introduction (p: 217-218) </li> +<li> 7.21.2 Streams (p: 218-219) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.21.1 Introduction (p: 296-298) </li> +<li> 7.21.2 Streams (p: 298-299) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.19.1 Introduction (p: 262-264) </li> +<li> 7.19.2 Streams (p: 264-265) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 4.9.1 Introduction </li> +<li> 4.9.2 Streams </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fgetpos" title="c/io/fgetpos"> <span class="t-lines"><span>fgetpos</span></span></a></div> </td> <td> gets the file position indicator <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fsetpos" title="c/io/fsetpos"> <span class="t-lines"><span>fsetpos</span></span></a></div> </td> <td> moves the file position indicator to a specific location in a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../string/multibyte/mbstate_t" title="c/string/multibyte/mbstate t"> <span class="t-lines"><span>mbstate_t</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> conversion state information necessary to iterate multibyte character strings <br> <span class="t-mark">(class)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fpos_t" title="cpp/io/c/fpos t">C++ documentation</a></span> for <code>fpos_t</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fpos_t" class="_attribution-link">https://en.cppreference.com/w/c/io/fpos_t</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffprintf.html b/devdocs/c/io%2Ffprintf.html new file mode 100644 index 00000000..c0309821 --- /dev/null +++ b/devdocs/c/io%2Ffprintf.html @@ -0,0 +1,278 @@ + <h1 id="firstHeading" class="firstHeading">printf, fprintf, sprintf, snprintf, printf_s, fprintf_s, sprintf_s, snprintf_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">int printf( const char *format, ... );</pre> +</td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int printf( const char *restrict format, ... );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(2)</td> <td></td> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">int fprintf( FILE *stream, const char *format, ... );</pre> +</td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int fprintf( FILE *restrict stream, const char *restrict format, ... );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(3)</td> <td></td> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">int sprintf( char *buffer, const char *format, ... );</pre> +</td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int sprintf( char *restrict buffer, const char *restrict format, ... );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int snprintf( char *restrict buffer, size_t bufsz, + const char *restrict format, ... );</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int printf_s( const char *restrict format, ... );</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int fprintf_s( FILE *restrict stream, const char *restrict format, ... );</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int sprintf_s( char *restrict buffer, rsize_t bufsz, + const char *restrict format, ... );</pre> +</td> <td> (7) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int snprintf_s( char *restrict buffer, rsize_t bufsz, + const char *restrict format, ... );</pre> +</td> <td> (8) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Loads the data from the given locations, converts them to character string equivalents and writes the results to a variety of sinks/streams:</p> +<div class="t-li1"> +<span class="t-li">1)</span> Writes the results to the output stream <code><a href="std_streams" title="c/io/std streams">stdout</a></code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Writes the results to the output stream <code>stream</code>.</div> <div class="t-li1"> +<span class="t-li">3)</span> Writes the results to a character string <code>buffer</code>. The behavior is undefined if the string to be written (plus the terminating null character) exceeds the size of the array pointed to by <code>buffer</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Writes the results to a character string <code>buffer</code>. At most <code>bufsz</code> - 1 characters are written. The resulting character string will be terminated with a null character, unless <code>bufsz</code> is zero. If <code>bufsz</code> is zero, nothing is written and <code>buffer</code> may be a null pointer, however the return value (number of bytes that would be written not including the null terminator) is still calculated and returned.</div> <div class="t-li1"> +<span class="t-li">5-8)</span> Same as <span class="t-v">(1-4)</span>, except that the following errors are detected at runtime and call the currently installed <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> the conversion specifier <code>%n</code> is present in <code>format</code> </li> +<li> any of the arguments corresponding to <code>%s</code> is a null pointer </li> +<li> <code>stream</code> or <code>format</code> or <code>buffer</code> is a null pointer </li> +<li> <code>bufsz</code> is zero or greater than <code>RSIZE_MAX</code> </li> +<li> encoding errors occur in any of string and character conversion specifiers </li> +<li> (for <code>sprintf_s</code> only), the string to be stored in <code>buffer</code> (including the trailing null) would exceed <code>bufsz</code> </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>printf_s</code> , <code>fprintf_s</code>, <code>sprintf_s</code>, and <code>snprintf_s</code> are only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../io" title="c/io"><code><stdio.h></code></a>.</dd> +</dl> +</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> output file stream to write to </td> +</tr> <tr class="t-par"> <td> buffer </td> <td> - </td> <td> pointer to a character string to write to </td> +</tr> <tr class="t-par"> <td> bufsz </td> <td> - </td> <td> up to bufsz - 1 characters may be written, plus the null terminator </td> +</tr> <tr class="t-par"> <td> format </td> <td> - </td> <td> pointer to a null-terminated byte string specifying how to interpret the data </td> +</tr> <tr class="t-par"> <td> ... </td> <td> - </td> <td> arguments specifying data to print. If any argument after <a href="../language/conversion#Default_argument_promotions" title="c/language/conversion">default argument promotions</a> is not the type expected by the corresponding conversion specifier, or if there are fewer arguments than required by <code>format</code>, the behavior is undefined. If there are more arguments than required by <code>format</code>, the extraneous arguments are evaluated and ignored. </td> +</tr> +</table> <p><br> The <b>format</b> string consists of ordinary byte characters (except <code>%</code>), which are copied unchanged into the output stream, and conversion specifications. Each conversion specification has the following format:</p> +<ul> +<li> introductory <code>%</code> character. </li> +<li> <span class="t-mark">(optional)</span> one or more flags that modify the behavior of the conversion: </li> +<ul> +<li> <code>-</code>: the result of the conversion is left-justified within the field (by default it is right-justified). </li> +<li> <code>+</code>: the sign of signed conversions is always prepended to the result of the conversion (by default the result is preceded by minus only when it is negative). </li> +<li> <i>space</i>: if the result of a signed conversion does not start with a sign character, or is empty, space is prepended to the result. It is ignored if <code>+</code> flag is present. </li> +<li> <code>#</code>: <i>alternative form</i> of the conversion is performed. See the table below for exact effects otherwise the behavior is undefined. </li> +<li> <code>0</code>: for integer and floating point number conversions, leading zeros are used to pad the field instead of <i>space</i> characters. For integer numbers it is ignored if the precision is explicitly specified. For other conversions using this flag results in undefined behavior. It is ignored if <code>-</code> flag is present. </li> +</ul> +<li> <span class="t-mark">(optional)</span> integer value or <code>*</code> that specifies minimum field width. The result is padded with <i>space</i> characters (by default), if required, on the left when right-justified, or on the right if left-justified. In the case when <code>*</code> is used, the width is specified by an additional argument of type <code>int</code>, which appears before the argument to be converted and the argument supplying precision if one is supplied. If the value of the argument is negative, it results with the <code>-</code> flag specified and positive field width (Note: This is the minimum width: The value is never truncated.). </li> +<ul> +<li> <span class="t-mark">(optional)</span> <code>.</code> followed by integer number or <code>*</code>, or neither that specifies <i>precision</i> of the conversion. In the case when <code>*</code> is used, the <i>precision</i> is specified by an additional argument of type <code>int</code>, which appears before the argument to be converted, but after the argument supplying minimum field width if one is supplied. If the value of this argument is negative, it is ignored. If neither a number nor <code>*</code> is used, the precision is taken as zero. See the table below for exact effects of <i>precision</i>. </li> +<li> <span class="t-mark">(optional)</span> <i>length modifier</i> that specifies the size of the argument (in combination with the conversion format specifier, it specifies the type of the corresponding argument). </li> +<li> conversion format specifier. </li> +</ul> +</ul> <p>The following format specifiers are available:</p> +<table class="wikitable"> <tr> <th rowspan="1">Conversion<br>Specifier </th> <th rowspan="1">Explanation </th> <th colspan="9">Expected<br>Argument Type </th> +</tr> <tr> <th colspan="2"> +<b>Length<br>Modifier</b><b>→</b> </th> <th> +<code>hh</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>h</code> </th> <th>(none) </th> <th> +<code>l</code> </th> <th> +<code>ll</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>j</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>z</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>t</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>L</code> </th> +</tr> <tr> <th> +<code>%</code> </th> <td>Writes literal <code>%</code>. The full conversion specification must be <code>%%</code>. </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>c</code> </th> <td> Writes a <b>single character</b>. <p>The argument is first converted to <code>unsigned char</code>. If the <b>l</b> modifier is used, the argument is first converted to a character string as if by <b>%ls</b> with a <code>wchar_t[2]</code> argument.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<div><code>int</code></div> </td> <td> +<div><code>wint_t</code></div> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>s</code> </th> <td> Writes a <b>character string</b> <p>The argument must be a pointer to the initial element of an array of characters. <i>Precision</i> specifies the maximum number of bytes to be written. If <i>Precision</i> is not specified, writes every byte up to and not including the first null terminator. If the <b>l</b> specifier is used, the argument must be a pointer to the initial element of an array of <code>wchar_t</code>, which is converted to char array as if by a call to <code><a href="../string/multibyte/wcrtomb" title="c/string/multibyte/wcrtomb">wcrtomb</a></code> with zero-initialized conversion state.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<div><code>char*</code></div> </td> <td> +<div><code>wchar_t*</code></div> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>d</code><br><code>i</code> </th> <td> Converts a <b>signed integer</b> into decimal representation <i>[-]dddd</i>. <p><i>Precision</i> specifies the minimum number of digits to appear. The default precision is <code>1</code>.<br><br> If both the converted value and the precision are <code>0</code> the conversion results in no characters.<br><br></p> +</td> <td rowspan="1"> +<div><code>signed char</code></div> </td> <td rowspan="1"> +<div><code>short</code></div> </td> <td rowspan="1"> +<div><code>int</code></div> </td> <td rowspan="1"> +<div><code>long</code></div> </td> <td rowspan="1"> +<div><code>long long</code></div> </td> <td rowspan="1"> +<div><code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw118">intmax_t</span></a></code></div> </td> <td rowspan="1"> +<div>signed <code><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a></code> +</div> </td> <td rowspan="1"> +<div><code><a href="http://en.cppreference.com/w/c/types/ptrdiff_t"><span class="kw101">ptrdiff_t</span></a></code></div> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>o</code> </th> <td> Converts an <b>unsigned integer</b> into octal representation <i>oooo</i>. <p><i>Precision</i> specifies the minimum number of digits to appear. The default precision is <code>1</code>. If both the converted value and the precision are <code>0</code> the conversion results in no characters. In the <i>alternative implementation</i> precision is increased if necessary, to write one leading zero. In that case if both the converted value and the precision are <code>0</code>, single <code>0</code> is written.</p> +</td> <td rowspan="3"> +<div><code>unsigned char</code></div> </td> <td rowspan="3"> +<div><code>unsigned short</code></div> </td> <td rowspan="3"> +<div><code>unsigned int</code></div> </td> <td rowspan="3"> +<div><code>unsigned long</code></div> </td> <td rowspan="3"> +<div><code>unsigned long long</code></div> </td> <td rowspan="3"> +<div><code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw132">uintmax_t</span></a></code></div> </td> <td rowspan="3"> +<div><code><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a></code></div> </td> <td rowspan="3"> +<div>unsigned version of <code><a href="http://en.cppreference.com/w/c/types/ptrdiff_t"><span class="kw101">ptrdiff_t</span></a></code> +</div> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>x</code><br><code>X</code> </th> <td> Converts an <b>unsigned integer</b> into hexadecimal representation <i>hhhh</i>. <p>For the <code>x</code> conversion letters <code>abcdef</code> are used.<br> For the <code>X</code> conversion letters <code>ABCDEF</code> are used.<br> <i>Precision</i> specifies the minimum number of digits to appear. The default precision is <code>1</code>. If both the converted value and the precision are <code>0</code> the conversion results in no characters. In the <i>alternative implementation</i> <code>0x</code> or <code>0X</code> is prefixed to results if the converted value is nonzero.</p> +</td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>u</code> </th> <td> Converts an <b>unsigned integer</b> into decimal representation <i>dddd</i>. <p><i>Precision</i> specifies the minimum number of digits to appear. The default precision is <code>1</code>. If both the converted value and the precision are <code>0</code> the conversion results in no characters.</p> +</td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>f</code><br><code>F</code> </th> <td> Converts <b>floating-point number</b> to the decimal notation in the style <i>[-]ddd.ddd</i>. <p><i>Precision</i> specifies the exact number of digits to appear after the decimal point character. The default precision is <code>6</code>. In the <i>alternative implementation</i> decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td rowspan="4"> +<div><code>double</code></div> </td> <td rowspan="4"> +<div> +<code>double</code><span class="t-mark-rev t-since-c99">(C99)</span> +</div> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td rowspan="4"> +<div><code>long double</code></div> </td> +</tr> <tr> <th> +<code>e</code><br><code>E</code> </th> <td> Converts <b>floating-point number</b> to the decimal exponent notation. <p>For the <code>e</code> conversion style <i>[-]d.ddd</i><code>e</code><i>±dd</i> is used.<br> For the <code>E</code> conversion style <i>[-]d.ddd</i><code>E</code><i>±dd</i> is used.<br> The exponent contains at least two digits, more digits are used only if necessary. If the value is <code>0</code>, the exponent is also <code>0</code>. <i>Precision</i> specifies the exact number of digits to appear after the decimal point character. The default precision is <code>6</code>. In the <i>alternative implementation</i> decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>a</code><br><code>A</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <td> Converts <b>floating-point number</b> to the hexadecimal exponent notation. <p>For the <code>a</code> conversion style <i>[-]</i><code>0x</code><i>h.hhh</i><code>p</code><i>±d</i> is used.<br> For the <code>A</code> conversion style <i>[-]</i><code>0X</code><i>h.hhh</i><code>P</code><i>±d</i> is used.<br> The first hexadecimal digit is not <code>0</code> if the argument is a normalized floating point value. If the value is <code>0</code>, the exponent is also <code>0</code>. <i>Precision</i> specifies the exact number of digits to appear after the hexadecimal point character. The default precision is sufficient for exact representation of the value. In the <i>alternative implementation</i> decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>g</code><br><code>G</code> </th> <td> Converts <b>floating-point number</b> to decimal or decimal exponent notation depending on the value and the <i>precision</i>. <p>For the <code>g</code> conversion style conversion with style <code>e</code> or <code>f</code> will be performed.<br> For the <code>G</code> conversion style conversion with style <code>E</code> or <code>F</code> will be performed.<br> Let <code>P</code> equal the precision if nonzero, <code>6</code> if the precision is not specified, or <code>1</code> if the precision is <code>0</code>. Then, if a conversion with style <code>E</code> would have an exponent of <code>X</code>:</p> +<ul> +<li> if <i>P > X ≥ −4</i>, the conversion is with style <code>f</code> or <code>F</code> and precision <i>P − 1 − X</i>. </li> +<li> otherwise, the conversion is with style <code>e</code> or <code>E</code> and precision <i>P − 1</i>. </li> +</ul> <p>Unless <i>alternative representation</i> is requested the trailing zeros are removed, also the decimal point character is removed if no fractional part is left. For infinity and not-a-number conversion style see notes.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>n</code> </th> <td> Returns the <b>number of characters written</b> so far by this call to the function. <p>The result is <i>written</i> to the value pointed to by the argument. The specification may not contain any <i>flag</i>, <i>field width</i>, or <i>precision</i>.<br><br><br><br></p> +</td> <td> +<div><code>signed char*</code></div> </td> <td> +<div><code>short*</code></div> </td> <td> +<div><code>int*</code></div> </td> <td> +<div><code>long*</code></div> </td> <td> +<div><code>long long*</code></div> </td> <td> +<div><code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw118">intmax_t</span></a><span class="sy2">*</span></code></div> </td> <td> +<div>signed <code><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="sy2">*</span></code> +</div> </td> <td> +<div><code><a href="http://en.cppreference.com/w/c/types/ptrdiff_t"><span class="kw101">ptrdiff_t</span></a><span class="sy2">*</span></code></div> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>p</code> </th> <td>Writes an implementation defined character sequence defining a <b>pointer</b>. </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<code>void*</code> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> +</table> <p>The floating point conversion functions convert infinity to <code>inf</code> or <code>infinity</code>. Which one is used is implementation defined.</p> +<p>Not-a-number is converted to <code>nan</code> or <code>nan(<i>char_sequence</i>)</code>. Which one is used is implementation defined.</p> +<p>The conversions <code>F</code>, <code>E</code>, <code>G</code>, <code>A</code> output <code>INF</code>, <code>INFINITY</code>, <code>NAN</code> instead.</p> +<p>Even though <code>%c</code> expects <code>int</code> argument, it is safe to pass a <code>char</code> because of the integer promotion that takes place when a variadic function is called.</p> +<p>The correct conversion specifications for the fixed-width character types (<code><a href="../types/integer" title="c/types/integer">int8_t</a></code>, etc) are defined in the header <a href="../types/integer" title="c/types/integer"><code><inttypes.h></code></a> (although <code><a href="../types/integer" title="c/types/integer">PRIdMAX</a></code>, <code><a href="../types/integer" title="c/types/integer">PRIuMAX</a></code>, etc is synonymous with <code>%jd</code>, <code>%ju</code>, etc).</p> +<p>The memory-writing conversion specifier <code>%n</code> is a common target of security exploits where format strings depend on user input and is not supported by the bounds-checked <code>printf_s</code> family of functions.</p> +<p>There is a <a href="../language/eval_order" title="c/language/eval order">sequence point</a> after the action of each conversion specifier; this permits storing multiple <code>%n</code> results in the same variable or, as an edge case, printing a string modified by an earlier <code>%n</code> within the same call.</p> +<p>If a conversion specification is invalid, the behavior is undefined.</p> +<h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1,2)</span> number of characters transmitted to the output stream or negative value if an output error or an encoding error (for string and character conversion specifiers) occurred</div> <div class="t-li1"> +<span class="t-li">3)</span> number of characters written to <code>buffer</code> (not counting the terminating null character), or a negative value if an encoding error (for string and character conversion specifiers) occurred</div> <div class="t-li1"> +<span class="t-li">4)</span> number of characters (not including the terminating null character) which would have been written to <code>buffer</code> if <code>bufsz</code> was ignored, or a negative value if an encoding error (for string and character conversion specifiers) occurred</div> <div class="t-li1"> +<span class="t-li">5,6)</span> number of characters transmitted to the output stream or negative value if an output error, a runtime constraints violation error, or an encoding error occurred.</div> <div class="t-li1"> +<span class="t-li">7)</span> number of characters written to <code>buffer</code>, not counting the null character (which is always written as long as <code>buffer</code> is not a null pointer and <code>bufsz</code> is not zero and not greater than <code>RSIZE_MAX</code>), or zero on runtime constraint violations, and negative value on encoding errors</div> <div class="t-li1"> +<span class="t-li">8)</span> number of characters not including the terminating null character (which is always written as long as <code>buffer</code> is not a null pointer and <code>bufsz</code> is not zero and not greater than <code>RSIZE_MAX</code>), which would have been written to <code>buffer</code> if <code>bufsz</code> was ignored, or a negative value if a runtime constraints violation or an encoding error occurred</div> <h3 id="Notes"> Notes</h3> <p>The C standard and <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/fprintf.html">POSIX</a> specify that the behavior of <code>sprintf</code> and its variants is undefined when an argument overlaps with the destination buffer. Example:</p> +<div class="c source-c"><pre data-language="c">sprintf(dst, "%s and %s", dst, t); // <- broken: undefined behavior</pre></div> <p><a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/fprintf.html">POSIX specifies</a> that <code><a href="../error/errno" title="c/error/errno">errno</a></code> is set on error. It also specifies additional conversion specifications, most notably support for argument reordering (<code>n$</code> immediately after <code>%</code> indicates <code>n</code><sup>th</sup> argument).</p> +<p>Calling <code>snprintf</code> with zero <code>bufsz</code> and null pointer for <code>buffer</code> is useful to determine the necessary buffer size to contain the output:</p> +<div class="c source-c"><pre data-language="c">const char fmt[] = "sqrt(2) = %f"; +int sz = snprintf(NULL, 0, fmt, sqrt(2)); +char buf[sz + 1]; // note +1 for terminating null byte +snprintf(buf, sizeof buf, fmt, sqrt(2));</pre></div> <p><code>snprintf_s</code>, just like <code>snprintf</code>, but unlike <code>sprintf_s</code>, will truncate the output to fit in <code>bufsz-1</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdint.h> +#include <inttypes.h> + +int main(void) +{ + const char* s = "Hello"; + printf("Strings:\n"); // same as puts("Strings"); + printf(" padding:\n"); + printf("\t[%10s]\n", s); + printf("\t[%-10s]\n", s); + printf("\t[%*s]\n", 10, s); + printf(" truncating:\n"); + printf("\t%.4s\n", s); + printf("\t%.*s\n", 3, s); + + printf("Characters:\t%c %%\n", 'A'); + + printf("Integers:\n"); + printf("\tDecimal:\t%i %d %.6i %i %.0i %+i %i\n", + 1, 2, 3, 0, 0, 4,-4); + printf("\tHexadecimal:\t%x %x %X %#x\n", 5, 10, 10, 6); + printf("\tOctal:\t\t%o %#o %#o\n", 10, 10, 4); + + printf("Floating point:\n"); + printf("\tRounding:\t%f %.0f %.32f\n", 1.5, 1.5, 1.3); + printf("\tPadding:\t%05.2f %.2f %5.2f\n", 1.5, 1.5, 1.5); + printf("\tScientific:\t%E %e\n", 1.5, 1.5); + printf("\tHexadecimal:\t%a %A\n", 1.5, 1.5); + printf("\tSpecial values:\t0/0=%g 1/0=%g\n", 0.0/0.0, 1.0/0.0); + + printf("Fixed-width types:\n"); + printf("\tLargest 32-bit value is %" PRIu32 " or %#" PRIx32 "\n", + UINT32_MAX, UINT32_MAX ); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Strings: + padding: + [ Hello] + [Hello ] + [ Hello] + truncating: + Hell + Hel +Characters: A % +Integers: + Decimal: 1 2 000003 0 +4 -4 + Hexadecimal: 5 a A 0x6 + Octal: 12 012 04 +Floating point: + Rounding: 1.500000 2 1.30000000000000004440892098500626 + Padding: 01.50 1.50 1.50 + Scientific: 1.500000E+00 1.500000e+00 + Hexadecimal: 0x1.8p+0 0X1.8P+0 + Special values: 0/0=-nan 1/0=inf +Fixed-width types: + Largest 32-bit value is 4294967295 or 0xffffffff</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.21.6.1 The fprintf function (p: 225-230) </li> +<li> 7.21.6.3 The printf function (p: 236) </li> +<li> 7.21.6.5 The snprintf function (p: 237) </li> +<li> 7.21.6.6 The sprintf function (p: 237) </li> +<li> K.3.5.3.1 The fprintf_s function (p: 430) </li> +<li> K.3.5.3.3 The printf_s function (p: 432) </li> +<li> K.3.5.3.5 The snprintf_s function (p: 432-433) </li> +<li> K.3.5.3.6 The sprintf_s function (p: 433) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.21.6.1 The fprintf function (p: 309-316) </li> +<li> 7.21.6.3 The printf function (p: 324) </li> +<li> 7.21.6.5 The snprintf function (p: 325) </li> +<li> 7.21.6.6 The sprintf function (p: 325-326) </li> +<li> K.3.5.3.1 The fprintf_s function (p: 591) </li> +<li> K.3.5.3.3 The printf_s function (p: 593-594) </li> +<li> K.3.5.3.5 The snprintf_s function (p: 594-595) </li> +<li> K.3.5.3.6 The sprintf_s function (p: 595-596) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.19.6.1 The fprintf function (p: 274-282) </li> +<li> 7.19.6.3 The printf function (p: 290) </li> +<li> 7.19.6.5 The snprintf function (p: 290-291) </li> +<li> 7.19.6.6 The sprintf function (p: 291) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 4.9.6.1 The fprintf function </li> +<li> 4.9.6.3 The printf function </li> +<li> 4.9.6.5 The sprintf function </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fwprintf" title="c/io/fwprintf"> <span class="t-lines"><span>wprintf</span><span>fwprintf</span><span>swprintf</span><span>wprintf_s</span><span>fwprintf_s</span><span>swprintf_s</span><span>snwprintf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> prints formatted wide character output to <code><a href="std_streams" title="c/io/std streams">stdout</a></code>, a file stream or a buffer <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="vfprintf" title="c/io/vfprintf"> <span class="t-lines"><span>vprintf</span><span>vfprintf</span><span>vsprintf</span><span>vsnprintf</span><span>vprintf_s</span><span>vfprintf_s</span><span>vsprintf_s</span><span>vsnprintf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> prints formatted output to <code><a href="std_streams" title="c/io/std streams">stdout</a></code>, a file stream or a buffer<br> using variable argument list <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fputs" title="c/io/fputs"> <span class="t-lines"><span>fputs</span></span></a></div> </td> <td> writes a character string to a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fscanf" title="c/io/fscanf"> <span class="t-lines"><span>scanf</span><span>fscanf</span><span>sscanf</span><span>scanf_s</span><span>fscanf_s</span><span>sscanf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads formatted input from <code><a href="std_streams" title="c/io/std streams">stdin</a></code>, a file stream or a buffer <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fprintf" title="cpp/io/c/fprintf">C++ documentation</a></span> for <code>printf, fprintf, sprintf, snprintf</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fprintf" class="_attribution-link">https://en.cppreference.com/w/c/io/fprintf</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffputc.html b/devdocs/c/io%2Ffputc.html new file mode 100644 index 00000000..d3993152 --- /dev/null +++ b/devdocs/c/io%2Ffputc.html @@ -0,0 +1,66 @@ + <h1 id="firstHeading" class="firstHeading">fputc, putc</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int fputc( int ch, FILE* stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int putc( int ch, FILE* stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Writes a character <code>ch</code> to the given output stream <code>stream</code>. <code>putc()</code> may be implemented as a macro and evaluate <code>stream</code> more than once, so the corresponding argument should never be an expression with side effects.</p> +<p>Internally, the character is converted to <code>unsigned char</code> just before being written.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> character to be written </td> +</tr> <tr class="t-par"> <td> stream </td> <td> - </td> <td> output stream </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>On success, returns the written character.</p> +<p>On failure, returns <code><a href="../io" title="c/io">EOF</a></code> and sets the <i>error</i> indicator (see <code><a href="ferror" title="c/io/ferror">ferror()</a></code>) on <code>stream</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>Shows <code>putc</code> with error checking</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + int ret_code = 0; + for (char c = 'a'; (ret_code != EOF) && (c != 'z'); c++) + ret_code = putc(c, stdout); + + // Test whether EOF was reached. + if (ret_code == EOF && ferror(stdout)) + { + perror("putc()"); + fprintf(stderr, "putc() failed in file %s at line # %d\n", + __FILE__, __LINE__ - 7); + exit(EXIT_FAILURE); + } + putc('\n', stdout); + + return EXIT_SUCCESS; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">abcdefghijklmnopqrstuvwxy</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.21.7.3 The fputc function (p: TBD) </li> +<li> 7.21.7.7 The putc function (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.21.7.3 The fputc function (p: TBD) </li> +<li> 7.21.7.7 The putc function (p: TBD) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.21.7.3 The fputc function (p: 331) </li> +<li> 7.21.7.7 The putc function (p: 333) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.19.7.3 The fputc function (p: 297) </li> +<li> 7.19.7.8 The putc function (p: 299) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 4.9.7.3 The fputc function </li> +<li> 4.9.7.8 The putc function </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="putchar" title="c/io/putchar"> <span class="t-lines"><span>putchar</span></span></a></div> </td> <td> writes a character to <code>stdout</code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fputc" title="cpp/io/c/fputc">C++ documentation</a></span> for <code>fputc, putc</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fputc" class="_attribution-link">https://en.cppreference.com/w/c/io/fputc</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffputs.html b/devdocs/c/io%2Ffputs.html new file mode 100644 index 00000000..99726ec7 --- /dev/null +++ b/devdocs/c/io%2Ffputs.html @@ -0,0 +1,38 @@ + <h1 id="firstHeading" class="firstHeading">fputs</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">int fputs( const char *str, FILE *stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int fputs( const char *restrict str, FILE *restrict stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Writes every character from the null-terminated string <code>str</code> to the output stream <code>stream</code>, as if by repeatedly executing <code><a href="fputc" title="c/io/fputc">fputc</a></code>.</p> +<p>The terminating null character from <code>str</code> is not written.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> null-terminated character string to be written </td> +</tr> <tr class="t-par"> <td> stream </td> <td> - </td> <td> output stream </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>On success, returns a non-negative value</p> +<p>On failure, returns <code><a href="../io" title="c/io">EOF</a></code> and sets the <i>error</i> indicator (see <code><a href="ferror" title="c/io/ferror">ferror()</a></code>) on <code>stream</code>.</p> +<h3 id="Notes"> Notes</h3> <p>The related function <code><a href="puts" title="c/io/puts">puts</a></code> appends a newline character to the output, while <code>fputs</code> writes the string unmodified.</p> +<p>Different implementations return different non-negative numbers: some return the last character written, some return the number of characters written (or INT_MAX if the string was longer than that), some simply return a non-negative constant such as zero.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +int main(void) +{ + int rc = fputs("Hello World", stdout); + + if (rc == EOF) + perror("fputs()"); // POSIX requires that errno is set +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Hello World</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.7.4 The fputs function (p: 331-332) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.7.4 The fputs function (p: 297) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.7.4 The fputs function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fprintf" title="c/io/fprintf"> <span class="t-lines"><span>printf</span><span>fprintf</span><span>sprintf</span><span>snprintf</span><span>printf_s</span><span>fprintf_s</span><span>sprintf_s</span><span>snprintf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> prints formatted output to <code><a href="std_streams" title="c/io/std streams">stdout</a></code>, a file stream or a buffer <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="puts" title="c/io/puts"> <span class="t-lines"><span>puts</span></span></a></div> </td> <td> writes a character string to <code><a href="std_streams" title="c/io/std streams">stdout</a></code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fgets" title="c/io/fgets"> <span class="t-lines"><span>fgets</span></span></a></div> </td> <td> gets a character string from a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fputs" title="cpp/io/c/fputs">C++ documentation</a></span> for <code>fputs</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fputs" class="_attribution-link">https://en.cppreference.com/w/c/io/fputs</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffputwc.html b/devdocs/c/io%2Ffputwc.html new file mode 100644 index 00000000..c309e8f7 --- /dev/null +++ b/devdocs/c/io%2Ffputwc.html @@ -0,0 +1,63 @@ + <h1 id="firstHeading" class="firstHeading">fputwc, putwc</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">wint_t fputwc( wchar_t ch, FILE* stream );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">wint_t putwc( wchar_t ch, FILE* stream );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Writes a wide character <code>ch</code> to the given output stream <code>stream</code>.</p> +<div class="t-li1"> +<span class="t-li">2)</span> May be implemented as a macro and may evaluate <code>stream</code> more than once.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> wide character to be written </td> +</tr> <tr class="t-par"> <td> stream </td> <td> - </td> <td> the output stream </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Returns a copy of <code>ch</code> on success.</p> +<p>On failure, returns <code>WEOF</code> and sets the <i>error</i> indicator (see <code><a href="ferror" title="c/io/ferror">ferror()</a></code>) on <code>stream</code>.</p> +<p>If an encoding error occurred, additionally sets <code><a href="../error/errno" title="c/error/errno">errno</a></code> to <code><a href="../error/errno_macros" title="c/error/errno macros">EILSEQ</a></code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <errno.h> +#include <locale.h> +#include <stdio.h> +#include <stdlib.h> +#include <wchar.h> + +int main(void) +{ + setlocale(LC_ALL, "en_US.utf8"); + + errno = 0; + if (fputwc(L'🍌', stdout) == WEOF) + { + if (errno == EILSEQ) + puts("Encoding error in fputwc."); + else + puts("I/O error in fputwc."); + return EXIT_FAILURE; + } +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">🍌</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.31.3.3 The fputwc function (p: 430) </li> +<li> 7.31.3.8 The putwc function (p: 431-432) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.29.3.3 The fputwc function (p: 308) </li> +<li> 7.29.3.8 The putwc function (p: 310) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.29.3.3 The fputwc function (p: 422-423) </li> +<li> 7.29.3.8 The putwc function (p: 424) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.24.3.3 The fputwc function (p: 368) </li> +<li> 7.24.3.8 The putwc function (p: 370) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fputc" title="c/io/fputc"> <span class="t-lines"><span>fputc</span><span>putc</span></span></a></div> </td> <td> writes a character to a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fputws" title="c/io/fputws"> <span class="t-lines"><span>fputws</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> writes a wide string to a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fgetwc" title="c/io/fgetwc"> <span class="t-lines"><span>fgetwc</span><span>getwc</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> gets a wide character from a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fputwc" title="cpp/io/c/fputwc">C++ documentation</a></span> for <code>fputwc</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fputwc" class="_attribution-link">https://en.cppreference.com/w/c/io/fputwc</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffputws.html b/devdocs/c/io%2Ffputws.html new file mode 100644 index 00000000..04e2ddf9 --- /dev/null +++ b/devdocs/c/io%2Ffputws.html @@ -0,0 +1,40 @@ + <h1 id="firstHeading" class="firstHeading">fputws</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td> <pre data-language="c">int fputws( const wchar_t *str, FILE *stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int fputws( const wchar_t * restrict str, FILE * restrict stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Writes every character from the null-terminated wide string <code>str</code> to the output stream <code>stream</code>, as if by repeatedly executing <code><a href="fputwc" title="c/io/fputwc">fputwc</a></code>.</p> +<p>The terminating null wide character from <code>str</code> is not written.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> null-terminated wide string to be written </td> +</tr> <tr class="t-par"> <td> stream </td> <td> - </td> <td> output stream </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>On success, returns a non-negative value</p> +<p>On failure, returns <code><a href="../io" title="c/io">EOF</a></code> and sets the <i>error</i> indicator (see <code><a href="ferror" title="c/io/ferror">ferror</a></code>) on <code>stream</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <wchar.h> + +int main(void) +{ + setlocale(LC_ALL, "en_US.utf8"); + int rc = fputws(L"御休みなさい", stdout); + + if (rc == EOF) + perror("fputws()"); // POSIX requires that errno is set +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">御休みなさい</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.3.4 The fputws function (p: 423) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.3.4 The fputws function (p: 368) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fputs" title="c/io/fputs"> <span class="t-lines"><span>fputs</span></span></a></div> </td> <td> writes a character string to a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fwprintf" title="c/io/fwprintf"> <span class="t-lines"><span>wprintf</span><span>fwprintf</span><span>swprintf</span><span>wprintf_s</span><span>fwprintf_s</span><span>swprintf_s</span><span>snwprintf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> prints formatted wide character output to <code><a href="std_streams" title="c/io/std streams">stdout</a></code>, a file stream or a buffer <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><strong class="selflink"> <span class="t-lines"><span>fputws</span></span></strong></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> writes a wide string to a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fgetws" title="c/io/fgetws"> <span class="t-lines"><span>fgetws</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> gets a wide string from a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fputws" title="cpp/io/c/fputws">C++ documentation</a></span> for <code>fputws</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fputws" class="_attribution-link">https://en.cppreference.com/w/c/io/fputws</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffread.html b/devdocs/c/io%2Ffread.html new file mode 100644 index 00000000..890f4374 --- /dev/null +++ b/devdocs/c/io%2Ffread.html @@ -0,0 +1,70 @@ + <h1 id="firstHeading" class="firstHeading">fread</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">size_t fread( void *buffer, size_t size, size_t count, + FILE *stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">size_t fread( void *restrict buffer, size_t size, size_t count, + FILE *restrict stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Reads up to <code>count</code> objects into the array <code>buffer</code> from the given input stream <code>stream</code> as if by calling <code><a href="fgetc" title="c/io/fgetc">fgetc</a></code> <code>size</code> times for each object, and storing the results, in the order obtained, into the successive positions of <code>buffer</code>, which is reinterpreted as an array of <code>unsigned char</code>. The file position indicator for the stream is advanced by the number of characters read.</p> +<p>If an error occurs, the resulting value of the file position indicator for the stream is indeterminate. If a partial element is read, its value is indeterminate.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> buffer </td> <td> - </td> <td> pointer to the array where the read objects are stored </td> +</tr> <tr class="t-par"> <td> size </td> <td> - </td> <td> size of each object in bytes </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> the number of the objects to be read </td> +</tr> <tr class="t-par"> <td> stream </td> <td> - </td> <td> the stream to read </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Number of objects read successfully, which may be less than <code>count</code> if an error or end-of-file condition occurs.</p> +<p>If <code>size</code> or <code>count</code> is zero, <code>fread</code> returns zero and performs no other action.</p> +<p><code>fread</code> does not distinguish between end-of-file and error, and callers must use <code><a href="feof" title="c/io/feof">feof</a></code> and <code><a href="ferror" title="c/io/ferror">ferror</a></code> to determine which occurred.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +enum { SIZE = 5 }; + +int main(void) +{ + const double a[SIZE] = {1.0, 2.0, 3.0, 4.0, 5.0}; + printf("Array has size %ld bytes, element size: %ld\n", sizeof a, sizeof *a); + FILE *fp = fopen("test.bin", "wb"); // must use binary mode + fwrite(a, sizeof *a, SIZE, fp); // writes an array of doubles + fclose(fp); + + double b[SIZE]; + fp = fopen("test.bin","rb"); + const size_t ret_code = fread(b, sizeof b[0], SIZE, fp); // reads an array of doubles + if (ret_code == SIZE) + { + printf("Array at %p read successfully, contents:\n", (void*)&a); + for (int n = 0; n != SIZE; ++n) + printf("%f ", b[n]); + putchar('\n'); + } + else // error handling + { + if (feof(fp)) + printf("Error reading test.bin: unexpected end of file\n"); + else if (ferror(fp)) + perror("Error reading test.bin"); + } + + fclose(fp); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Array has size 40 bytes, element size: 8 +Array at 0x1337f00d6960 read successfully, contents: +1.000000 2.000000 3.000000 4.000000 5.000000</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.21.8.1 The fread function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.21.8.1 The fread function (p: 243-244) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.8.1 The fread function (p: 335) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.8.1 The fread function (p: 301) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.8.1 The fread function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fscanf" title="c/io/fscanf"> <span class="t-lines"><span>scanf</span><span>fscanf</span><span>sscanf</span><span>scanf_s</span><span>fscanf_s</span><span>sscanf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads formatted input from <code><a href="std_streams" title="c/io/std streams">stdin</a></code>, a file stream or a buffer <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fgets" title="c/io/fgets"> <span class="t-lines"><span>fgets</span></span></a></div> </td> <td> gets a character string from a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fwrite" title="c/io/fwrite"> <span class="t-lines"><span>fwrite</span></span></a></div> </td> <td> writes to a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fread" title="cpp/io/c/fread">C++ documentation</a></span> for <code>fread</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fread" class="_attribution-link">https://en.cppreference.com/w/c/io/fread</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffreopen.html b/devdocs/c/io%2Ffreopen.html new file mode 100644 index 00000000..74c69f8a --- /dev/null +++ b/devdocs/c/io%2Ffreopen.html @@ -0,0 +1,82 @@ + <h1 id="firstHeading" class="firstHeading">freopen, freopen_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">FILE *freopen( const char *filename, const char *mode, + FILE *stream );</pre> +</td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">FILE *freopen( const char *restrict filename, const char *restrict mode, + FILE *restrict stream );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t freopen_s( FILE *restrict *restrict newstreamptr, + const char *restrict filename, const char *restrict mode, + FILE *restrict stream );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> First, attempts to close the file associated with <code>stream</code>, ignoring any errors. Then, if <code>filename</code> is not null, attempts to open the file specified by <code>filename</code> using <code>mode</code> as if by <code><a href="fopen" title="c/io/fopen">fopen</a></code>, and associates that file with the file stream pointed to by <code>stream</code>. If <code>filename</code> is a null pointer, then the function attempts to reopen the file that is already associated with <code>stream</code> (it is implementation defined which mode changes are allowed in this case).</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that <code>mode</code> is treated as in <code>fopen_s</code> and that the pointer to the file stream is written to <code>newstreamptr</code> and the following errors are detected at runtime and call the currently installed <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> <code>newstreamptr</code> is a null pointer </li> +<li> <code>stream</code> is a null pointer </li> +<li> <code>mode</code> is a null pointer </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>freopen_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../io" title="c/io"><code><stdio.h></code></a>.</dd> +</dl> +</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> filename </td> <td> - </td> <td> file name to associate the file stream to </td> +</tr> <tr class="t-par"> <td> mode </td> <td> - </td> <td> null-terminated character string determining new <a href="#File_access_flags">file access mode</a> </td> +</tr> <tr class="t-par"> <td> stream </td> <td> - </td> <td> the file stream to modify </td> +</tr> <tr class="t-par"> <td> newstreamptr </td> <td> - </td> <td> pointer to a pointer where the function stores the result (an out-parameter) </td> +</tr> +</table> <h3 id="File_access_flags"> File access flags</h3> <table class="wikitable"> <tr> <th> File access <br>mode string </th> <th> Meaning </th> <th> Explanation </th> <th> Action if file <br> already exists </th> <th> Action if file <br> does not exist </th> +</tr> <tr> <td> <code>"r"</code> </td> <td> read </td> <td> Open a file for reading </td> <td> read from start </td> <td> failure to open </td> +</tr> <tr> <td> <code>"w"</code> </td> <td> write </td> <td> Create a file for writing </td> <td> destroy contents </td> <td> create new </td> +</tr> <tr> <td> <code>"a"</code> </td> <td> append </td> <td> Append to a file </td> <td> write to end </td> <td> create new </td> +</tr> <tr> <td> <code>"r+"</code> </td> <td> read extended </td> <td> Open a file for read/write </td> <td> read from start </td> <td> error </td> +</tr> <tr> <td> <code>"w+"</code> </td> <td> write extended </td> <td> Create a file for read/write </td> <td> destroy contents </td> <td> create new </td> +</tr> <tr> <td> <code>"a+"</code> </td> <td> append extended </td> <td> Open a file for read/write </td> <td> write to end </td> <td> create new </td> +</tr> <tr> <td colspan="5"> File access mode flag <code>"b"</code> can optionally be specified to open a file in binary mode. This flag has no effect on POSIX systems, but on Windows it disables special handling of <code>'\n'</code> and <code>'\x1A'</code>. <br> On the append file access modes, data is written to the end of the file regardless of the current position of the file position indicator. </td> +</tr> <tr> <td colspan="5"> The behavior is undefined if the mode is not one of the strings listed above. Some implementations define additional supported modes (e.g. <a rel="nofollow" class="external text" href="https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/fopen-wfopen">Windows</a>). </td> +</tr> <tr> <td colspan="5"> In update mode (<code>'+'</code>), both input and output may be performed, but output cannot be followed by input without an intervening call to <code><a href="fflush" title="c/io/fflush">fflush</a></code>, <code><a href="fseek" title="c/io/fseek">fseek</a></code>, <code><a href="fsetpos" title="c/io/fsetpos">fsetpos</a></code> or <code><a href="rewind" title="c/io/rewind">rewind</a></code>, and input cannot be followed by output without an intervening call to <code><a href="fseek" title="c/io/fseek">fseek</a></code>, <code><a href="fsetpos" title="c/io/fsetpos">fsetpos</a></code> or <code><a href="rewind" title="c/io/rewind">rewind</a></code>, unless the input operation encountered end of file. In update mode, implementations are permitted to use binary mode even when text mode is specified. </td> +</tr> <tr> <td colspan="5"> File access mode flag <code>"x"</code> can optionally be appended to <code>"w"</code> or <code>"w+"</code> specifiers. This flag forces the function to fail if the file exists, instead of overwriting it. <span class="t-mark-rev t-since-c11">(C11)</span> </td> +</tr> <tr> <td colspan="5"> When using <code>fopen_s</code> or <code>freopen_s</code>, file access permissions for any file created with <code>"w"</code> or <code>"a"</code> prevents other users from accessing it. File access mode flag <code>"u"</code> can optionally be prepended to any specifier that begins with <code>"w"</code> or <code>"a"</code>, to enable the default <code><a href="fopen" title="c/io/fopen">fopen</a></code> permissions. <span class="t-mark-rev t-since-c11">(C11)</span> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> A copy of the value of <code>stream</code> on success, null pointer on failure.</div> <div class="t-li1"> +<span class="t-li">2)</span> zero on success (and a copy of the value of <code>stream</code> is written to <code>*newstreamptr</code>, non-zero on error (and null pointer is written to <code>*newstreamptr</code> unless <code>newstreamptr</code> is itself a null pointer).</div> <h3 id="Notes"> Notes</h3> <p><code>freopen</code> is the only way to change the narrow/wide orientation of a stream once it has been established by an I/O operation or by <code>fwide</code>.</p> +<p>Microsoft CRT version of <code>freopen</code> does not support any mode changes when <code>filename</code> is a null pointer and treats this as an error (see <a rel="nofollow" class="external text" href="https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/freopen-wfreopen">documentation</a>). A possible workaround is the non-standard function <a rel="nofollow" class="external text" href="https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/setmode"><code>_setmode()</code></a>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>The following code redirects <code>stdout</code> to a file.</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + puts("stdout is printed to console"); + if (freopen("redir.txt", "w", stdout) == NULL) + { + perror("freopen() failed"); + return EXIT_FAILURE; + } + puts("stdout is redirected to a file"); // this is written to redir.txt + fclose(stdout); + return EXIT_SUCCESS; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">stdout is printed to console</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.21.5.4 The freopen function (p: 224-225) </li> +<li> K.3.5.2.2 The freopen_s function (p: 429-430) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.21.5.4 The freopen function (p: 307) </li> +<li> K.3.5.2.2 The freopen_s function (p: 590) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.5.4 The freopen function (p: 272-273) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.5.4 The freopen function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fopen" title="c/io/fopen"> <span class="t-lines"><span>fopen</span><span>fopen_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> opens a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fclose" title="c/io/fclose"> <span class="t-lines"><span>fclose</span></span></a></div> </td> <td> closes a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/freopen" title="cpp/io/c/freopen">C++ documentation</a></span> for <code>freopen</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/freopen" class="_attribution-link">https://en.cppreference.com/w/c/io/freopen</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffscanf.html b/devdocs/c/io%2Ffscanf.html new file mode 100644 index 00000000..9dbe321e --- /dev/null +++ b/devdocs/c/io%2Ffscanf.html @@ -0,0 +1,232 @@ + <h1 id="firstHeading" class="firstHeading">scanf, fscanf, sscanf, scanf_s, fscanf_s, sscanf_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">int scanf( const char *format, ... );</pre> +</td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int scanf( const char *restrict format, ... );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(2)</td> <td></td> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">int fscanf( FILE *stream, const char *format, ... );</pre> +</td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int fscanf( FILE *restrict stream, const char *restrict format, ... );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(3)</td> <td></td> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">int sscanf( const char *buffer, const char *format, ... );</pre> +</td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int sscanf( const char *restrict buffer, const char *restrict format, ... );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int scanf_s(const char *restrict format, ...);</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int fscanf_s(FILE *restrict stream, const char *restrict format, ...);</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int sscanf_s(const char *restrict buffer, const char *restrict format, ...);</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Reads data from a variety of sources, interprets it according to <code>format</code> and stores the results into given locations.</p> +<div class="t-li1"> +<span class="t-li">1)</span> reads the data from <code><a href="std_streams" title="c/io/std streams">stdin</a></code> +</div> <div class="t-li1"> +<span class="t-li">2)</span> reads the data from file stream <code>stream</code> +</div> <div class="t-li1"> +<span class="t-li">3)</span> reads the data from null-terminated character string <code>buffer</code>. Reaching the end of the string is equivalent to reaching the end-of-file condition for <code>fscanf</code> +</div> <div class="t-li1"> +<span class="t-li">4-6)</span> Same as <span class="t-v">(1-3)</span>, except that <code>%c</code>, <code>%s</code>, and <code>%[</code> conversion specifiers each expect two arguments (the usual pointer and a value of type <code>rsize_t</code> indicating the size of the receiving array, which may be <code>1</code> when reading with a <code>%c</code> into a single char) and except that the following errors are detected at runtime and call the currently installed <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> any of the arguments of pointer type is a null pointer </li> +<li> <code>format</code>, <code>stream</code>, or <code>buffer</code> is a null pointer </li> +<li> the number of characters that would be written by <code>%c</code>, <code>%s</code>, or <code>%[</code>, plus the terminating null character, would exceed the second (<code>rsize_t</code>) argument provided for each of those conversion specifiers </li> +<li> optionally, any other detectable error, such as unknown conversion specifier </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>scanf_s</code> , <code>fscanf_s</code>, and <code>sscanf_s</code> are only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../io" title="c/io"><code><stdio.h></code></a>.</dd> +</dl> +</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> input file stream to read from </td> +</tr> <tr class="t-par"> <td> buffer </td> <td> - </td> <td> pointer to a null-terminated character string to read from </td> +</tr> <tr class="t-par"> <td> format </td> <td> - </td> <td> pointer to a null-terminated character string specifying how to read the input </td> +</tr> <tr class="t-par"> <td> ... </td> <td> - </td> <td> receiving arguments. </td> +</tr> +</table> <p><br> The <b>format</b> string consists of</p> +<ul> +<li> non-whitespace multibyte characters except <code>%</code>: each such character in the format string consumes exactly one identical character from the input stream, or causes the function to fail if the next character on the stream does not compare equal. </li> +<li> whitespace characters: any single whitespace character in the format string consumes all available consecutive whitespace characters from the input (determined as if by calling <a href="../string/byte/isspace" title="c/string/byte/isspace"><code>isspace</code></a> in a loop). Note that there is no difference between <code>"\n"</code>, <code>" "</code>, <code>"\t\t"</code>, or other whitespace in the format string. </li> +<li> conversion specifications. Each conversion specification has the following format: </li> +<ul> +<li> introductory <code>%</code> character. </li> +<li> <span class="t-mark">(optional)</span> assignment-suppressing character <code>*</code>. If this option is present, the function does not assign the result of the conversion to any receiving argument. </li> +<li> <span class="t-mark">(optional)</span> integer number (greater than zero) that specifies <i>maximum field width</i>, that is, the maximum number of characters that the function is allowed to consume when doing the conversion specified by the current conversion specification. Note that <code>%s</code> and <code>%[</code> may lead to buffer overflow if the width is not provided. </li> +<li> <span class="t-mark">(optional)</span> <i>length modifier</i> that specifies the size of the receiving argument, that is, the actual destination type. This affects the conversion accuracy and overflow rules. The default destination type is different for each conversion type (see table below). </li> +<li> conversion format specifier. </li> +</ul> +</ul> <p>The following format specifiers are available:</p> +<table class="wikitable"> <tr> <th rowspan="1">Conversion<br>specifier </th> <th rowspan="1">Explanation </th> <th colspan="9">Argument type </th> +</tr> <tr> <th colspan="2"> +<b>Length modifier →</b> </th> <th> +<code>hh</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>h</code> </th> <th>(none) </th> <th> +<code>l</code> </th> <th> +<code>ll</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>j</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>z</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>t</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>L</code> </th> +</tr> <tr> <th> +<code>%</code> </th> <td>Matches literal <code>%</code>. </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>c</code> </th> <td> Matches a <b>character</b> or a sequence of <b>characters</b>. <p>If a width specifier is used, matches exactly <i>width</i> characters (the argument must be a pointer to an array with sufficient room). Unlike %s and %[, does not append the null character to the array.</p> +</td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3"> +<div><code>char*</code></div> </td> <td rowspan="3"> +<div><code>wchar_t*</code></div> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>s</code> </th> <td> Matches a sequence of non-whitespace characters (a <b>string</b>). <p>If width specifier is used, matches up to <i>width</i> or until the first whitespace character, whichever appears first. Always stores a null character in addition to the characters matched (so the argument array must have room for at least <i>width+1</i> characters)</p> +</td> +</tr> <tr> <th> +<code>[</code><span class="t-spar">set</span><code>]</code> </th> <td> Matches a non-empty sequence of character from <span class="t-spar">set</span> of characters. <p>If the first character of the set is <code>^</code>, then all characters not in the set are matched. If the set begins with <code>]</code> or <code>^]</code> then the <code>]</code> character is also included into the set. It is implementation-defined whether the character <code>-</code> in the non-initial position in the scanset may be indicating a range, as in <code>[0-9]</code>. If width specifier is used, matches only up to <i>width</i>. Always stores a null character in addition to the characters matched (so the argument array must have room for at least <i>width+1</i> characters)</p> +</td> +</tr> <tr> <th> +<code>d</code> </th> <td> Matches a <b>decimal integer</b>. <p>The format of the number is the same as expected by <a href="../string/byte/strtol" title="c/string/byte/strtol"><code>strtol</code></a> with the value <code>10</code> for the <code>base</code> argument</p> +</td> <td rowspan="6"> +<div> +<code>signed char*</code> or <code>unsigned char*</code> +</div> </td> <td rowspan="6"> +<div> +<code>signed short*</code> or <code>unsigned short*</code> +</div> </td> <td rowspan="6"> +<div> +<code>signed int*</code> or <code>unsigned int*</code> +</div> </td> <td rowspan="6"> +<div> +<code>signed long*</code> or <code>unsigned long*</code> +</div> </td> <td rowspan="6"> +<div> +<code>signed long long*</code> or <code>unsigned long long*</code> +</div> </td> <td rowspan="6"> +<div> +<code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw118">intmax_t</span></a><span class="sy2">*</span></code> or <code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw132">uintmax_t</span></a><span class="sy2">*</span></code> +</div> </td> <td rowspan="6"> +<div><code><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="sy2">*</span></code></div> </td> <td rowspan="6"> +<div><code><a href="http://en.cppreference.com/w/c/types/ptrdiff_t"><span class="kw101">ptrdiff_t</span></a><span class="sy2">*</span></code></div> </td> <td rowspan="6" class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>i</code> </th> <td> Matches an <b>integer</b>. <p>The format of the number is the same as expected by <a href="../string/byte/strtol" title="c/string/byte/strtol"><code>strtol</code></a> with the value <code>0</code> for the <code>base</code> argument (base is determined by the first characters parsed)</p> +</td> +</tr> <tr> <th> +<code>u</code> </th> <td> Matches an unsigned <b>decimal integer</b>. <p>The format of the number is the same as expected by <a href="../string/byte/strtoul" title="c/string/byte/strtoul"><code>strtoul</code></a> with the value <code>10</code> for the <code>base</code> argument.</p> +</td> +</tr> <tr> <th> +<code>o</code> </th> <td> Matches an unsigned <b>octal integer</b>. <p>The format of the number is the same as expected by <a href="../string/byte/strtoul" title="c/string/byte/strtoul"><code>strtoul</code></a> with the value <code>8</code> for the <code>base</code> argument</p> +</td> +</tr> <tr> <th> +<code>x</code>, <code>X</code> </th> <td> Matches an unsigned <b>hexadecimal integer</b>. <p>The format of the number is the same as expected by <a href="../string/byte/strtoul" title="c/string/byte/strtoul"><code>strtoul</code></a> with the value <code>16</code> for the <code>base</code> argument</p> +</td> +</tr> <tr> <th> +<code>n</code> </th> <td> Returns the <b>number of characters read so far</b>. <p>No input is consumed. Does not increment the assignment count. If the specifier has assignment-suppressing operator defined, the behavior is undefined</p> +</td> +</tr> <tr> <th> +<code>a</code>, <code>A</code><span class="t-mark-rev t-since-c99">(C99)</span><br><code>e</code>, <code>E</code><br><code>f</code>, <code>F</code><span class="t-mark-rev t-since-c99">(C99)</span><br><code>g</code>, <code>G</code> </th> <td> Matches a <b>floating-point number</b>. <p>The format of the number is the same as expected by <a href="../string/byte/strtof" title="c/string/byte/strtof"><code>strtof</code></a></p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<div><code>float*</code></div> </td> <td> +<div><code>double*</code></div> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<div><code>long double*</code></div> </td> +</tr> <tr> <th> +<code>p</code> </th> <td> Matches implementation defined character sequence defining a <b>pointer</b>. <p><code>printf</code> family of functions should produce the same sequence using <code>%p</code> format specifier</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<div><code>void**</code></div> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> +</table> <p>For every conversion specifier other than <code>n</code>, the longest sequence of input characters which does not exceed any specified field width and which either is exactly what the conversion specifier expects or is a prefix of a sequence it would expect, is what's consumed from the stream. The first character, if any, after this consumed sequence remains unread. If the consumed sequence has length zero or if the consumed sequence cannot be converted as specified above, the matching failure occurs unless end-of-file, an encoding error, or a read error prevented input from the stream, in which case it is an input failure.</p> +<p>All conversion specifiers other than <code>[</code>, <code>c</code>, and <code>n</code> consume and discard all leading whitespace characters (determined as if by calling <a href="../string/byte/isspace" title="c/string/byte/isspace"><code>isspace</code></a>) before attempting to parse the input. These consumed characters do not count towards the specified maximum field width.</p> +<p>The conversion specifiers <code>lc</code>, <code>ls</code>, and <code>l[</code> perform multibyte-to-wide character conversion as if by calling <a href="../string/multibyte/mbrtowc" title="c/string/multibyte/mbrtowc"><code>mbrtowc</code></a> with an <a href="../string/multibyte/mbstate_t" title="c/string/multibyte/mbstate t"><code>mbstate_t</code></a> object initialized to zero before the first character is converted.</p> +<p>The conversion specifiers <code>s</code> and <code>[</code> always store the null terminator in addition to the matched characters. The size of the destination array must be at least one greater than the specified field width. The use of <code>%s</code> or <code>%[</code>, without specifying the destination array size, is as unsafe as <code><a href="gets" title="c/io/gets">gets</a></code>.</p> +<p>The correct conversion specifications for the <a href="../types/integer" title="c/types/integer">fixed-width integer types</a> (<code><a href="../types/integer" title="c/types/integer">int8_t</a></code>, etc) are defined in the header <a href="../types/integer" title="c/types/integer"><code><inttypes.h></code></a> (although <a href="../types/integer" title="c/types/integer"><code>SCNdMAX</code></a>, <a href="../types/integer" title="c/types/integer"><code>SCNuMAX</code></a>, etc is synonymous with <code>%jd</code>, <code>%ju</code>, etc).</p> +<p>There is a <a href="../language/eval_order" title="c/language/eval order">sequence point</a> after the action of each conversion specifier; this permits storing multiple fields in the same "sink" variable.</p> +<p>When parsing an incomplete floating-point value that ends in the exponent with no digits, such as parsing <code>"100er"</code> with the conversion specifier <code>%f</code>, the sequence <code>"100e"</code> (the longest prefix of a possibly valid floating-point number) is consumed, resulting in a matching error (the consumed sequence cannot be converted to a floating-point number), with <code>"r"</code> remaining. Some existing implementations do not follow this rule and roll back to consume only <code>"100"</code>, leaving <code>"er"</code>, e.g. <a rel="nofollow" class="external text" href="https://sourceware.org/bugzilla/show_bug.cgi?id=1765">glibc bug 1765</a>.</p> +<p>If a conversion specification is invalid, the behavior is undefined.</p> +<h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1-3)</span> Number of receiving arguments successfully assigned (which may be zero in case a matching failure occurred before the first receiving argument was assigned), or <code><a href="../io" title="c/io">EOF</a></code> if input failure occurs before the first receiving argument was assigned.</div> <div class="t-li1"> +<span class="t-li">4-6)</span> Same as <span class="t-v">(1-3)</span>, except that <code><a href="../io" title="c/io">EOF</a></code> is also returned if there is a runtime constraint violation.</div> <h3 id="Complexity"> Complexity</h3> <p>Not guaranteed. Notably, some implementations of <code>sscanf</code> are O(N), where <code>N <span class="sy1">=</span> <a href="http://en.cppreference.com/w/c/string/byte/strlen"><span class="kw558">strlen</span></a><span class="br0">(</span>buffer<span class="br0">)</span></code> <a rel="nofollow" class="external autonumber" href="https://sourceware.org/bugzilla/show_bug.cgi?id=17577">[1]</a>.</p> +<h3 id="Notes"> Notes</h3> <p>Because most conversion specifiers first consume all consecutive whitespace, code such as</p> +<div class="c source-c"><pre data-language="c">scanf("%d", &a); +scanf("%d", &b);</pre></div> <p>will read two integers that are entered on different lines (second <code>%d</code> will consume the newline left over by the first) or on the same line, separated by spaces or tabs (second <code>%d</code> will consume the spaces or tabs). The conversion specifiers that do not consume leading whitespace, such as <code>%c</code>, can be made to do so by using a whitespace character in the format string:</p> +<div class="c source-c"><pre data-language="c">scanf("%d", &a); +scanf(" %c", &c); // consume all consecutive whitespace after %d, then read a char</pre></div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#define __STDC_WANT_LIB_EXT1__ 1 +#include <stdio.h> +#include <stddef.h> +#include <locale.h> + +int main(void) +{ + int i, j; + float x, y; + char str1[10], str2[4]; + wchar_t warr[2]; + setlocale(LC_ALL, "en_US.utf8"); + + char input[] = "25 54.32E-1 Thompson 56789 0123 56ß水"; + /* parse as follows: + %d: an integer + %f: a floating-point value + %9s: a string of at most 9 non-whitespace characters + %2d: two-digit integer (digits 5 and 6) + %f: a floating-point value (digits 7, 8, 9) + %*d: an integer which isn't stored anywhere + ' ': all consecutive whitespace + %3[0-9]: a string of at most 3 decimal digits (digits 5 and 6) + %2lc: two wide characters, using multibyte to wide conversion */ + int ret = sscanf(input, "%d%f%9s%2d%f%*d %3[0-9]%2lc", + &i, &x, str1, &j, &y, str2, warr); + + printf("Converted %d fields:\n" + "i = %d\n" + "x = %f\n" + "str1 = %s\n" + "j = %d\n" + "y = %f\n" + "str2 = %s\n" + "warr[0] = U+%x\n" + "warr[1] = U+%x\n", + ret, i, x, str1, j, y, str2, warr[0], warr[1]); + +#ifdef __STDC_LIB_EXT1__ + int n = sscanf_s(input, "%d%f%s", &i, &x, str1, (rsize_t)sizeof str1); + // writes 25 to i, 5.432 to x, the 9 bytes "Thompson\0" to str1, and 3 to n. +#endif +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Converted 7 fields: +i = 25 +x = 5.432000 +str1 = Thompson +j = 56 +y = 789.000000 +str2 = 56 +warr[0] = U+df +warr[1] = U+6c34</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.21.6.2 The fscanf function (p: 231-236) </li> +<li> 7.21.6.4 The scanf function (p: 236-237) </li> +<li> 7.21.6.7 The sscanf function (p: 238-239) </li> +<li> K.3.5.3.2 The fscanf_s function (p: 430-431) </li> +<li> K.3.5.3.4 The scanf_s function (p: 432) </li> +<li> K.3.5.3.7 The sscanf_s function (p: 433) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.21.6.2 The fscanf function (p: 317-324) </li> +<li> 7.21.6.4 The scanf function (p: 325) </li> +<li> 7.21.6.7 The sscanf function (p: 326) </li> +<li> K.3.5.3.2 The fscanf_s function (p: 592-593) </li> +<li> K.3.5.3.4 The scanf_s function (p: 594) </li> +<li> K.3.5.3.7 The sscanf_s function (p: 596) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.19.6.2 The fscanf function (p: 282-289) </li> +<li> 7.19.6.4 The scanf function (p: 290) </li> +<li> 7.19.6.7 The sscanf function (p: 291) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 4.9.6.2 The fscanf function </li> +<li> 4.9.6.4 The scanf function </li> +<li> 4.9.6.6 The sscanf function </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="vfscanf" title="c/io/vfscanf"> <span class="t-lines"><span>vscanf</span><span>vfscanf</span><span>vsscanf</span><span>vscanf_s</span><span>vfscanf_s</span><span>vsscanf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads formatted input from <code><a href="std_streams" title="c/io/std streams">stdin</a></code>, a file stream or a buffer<br> using variable argument list <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fgets" title="c/io/fgets"> <span class="t-lines"><span>fgets</span></span></a></div> </td> <td> gets a character string from a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fprintf" title="c/io/fprintf"> <span class="t-lines"><span>printf</span><span>fprintf</span><span>sprintf</span><span>snprintf</span><span>printf_s</span><span>fprintf_s</span><span>sprintf_s</span><span>snprintf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> prints formatted output to <code><a href="std_streams" title="c/io/std streams">stdout</a></code>, a file stream or a buffer <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fscanf" title="cpp/io/c/fscanf">C++ documentation</a></span> for <code>scanf, fscanf, sscanf</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fscanf" class="_attribution-link">https://en.cppreference.com/w/c/io/fscanf</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffseek.html b/devdocs/c/io%2Ffseek.html new file mode 100644 index 00000000..0d57a3fe --- /dev/null +++ b/devdocs/c/io%2Ffseek.html @@ -0,0 +1,74 @@ + <h1 id="firstHeading" class="firstHeading">fseek</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int fseek( FILE *stream, long offset, int origin );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define SEEK_SET /*unspecified*/ +#define SEEK_CUR /*unspecified*/ +#define SEEK_END /*unspecified*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Sets the file position indicator for the file stream <code>stream</code> to the value pointed to by <code>offset</code>.</p> +<p>If the <code>stream</code> is open in binary mode, the new position is exactly <code>offset</code> bytes measured from the beginning of the file if <code>origin</code> is <code><a href="../io" title="c/io">SEEK_SET</a></code>, from the current file position if <code>origin</code> is <code><a href="../io" title="c/io">SEEK_CUR</a></code>, and from the end of the file if <code>origin</code> is <code><a href="../io" title="c/io">SEEK_END</a></code>. Binary streams are not required to support <code><a href="../io" title="c/io">SEEK_END</a></code>, in particular if additional null bytes are output.</p> +<p>If the <code>stream</code> is open in text mode, the only supported values for <code>offset</code> are zero (which works with any <code>origin</code>) and a value returned by an earlier call to <code><a href="ftell" title="c/io/ftell">ftell</a></code> on a stream associated with the same file (which only works with <code>origin</code> of <code><a href="../io" title="c/io">SEEK_SET</a></code>).</p> +<p>If the <code>stream</code> is wide-oriented, the restrictions of both text and binary streams apply (result of <code><a href="ftell" title="c/io/ftell">ftell</a></code> is allowed with <code><a href="../io" title="c/io">SEEK_SET</a></code> and zero offset is allowed from <code><a href="../io" title="c/io">SEEK_SET</a></code> and <code><a href="../io" title="c/io">SEEK_CUR</a></code>, but not <code><a href="../io" title="c/io">SEEK_END</a></code>).</p> +<p>In addition to changing the file position indicator, <code>fseek</code> undoes the effects of <code><a href="ungetc" title="c/io/ungetc">ungetc</a></code> and clears the end-of-file status, if applicable.</p> +<p>If a read or write error occurs, the error indicator for the stream (<code><a href="ferror" title="c/io/ferror">ferror</a></code>) is set and the file position is unaffected.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> file stream to modify </td> +</tr> <tr class="t-par"> <td> offset </td> <td> - </td> <td> number of characters to shift the position relative to origin </td> +</tr> <tr class="t-par"> <td> origin </td> <td> - </td> <td> position to which <code>offset</code> is added. It can have one of the following values: <code><a href="../io" title="c/io">SEEK_SET</a></code>, <code><a href="../io" title="c/io">SEEK_CUR</a></code>, <code><a href="../io" title="c/io">SEEK_END</a></code> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>0</code> upon success, nonzero value otherwise.</p> +<h3 id="Notes"> Notes</h3> <p>After seeking to a non-end position in a wide stream, the next call to any output function may render the remainder of the file undefined, e.g. by outputting a multibyte sequence of a different length.</p> +<p>For text streams, the only valid values of <code>offset</code> are <code>0</code> (applicable to any <code>origin</code>) and a value returned by an earlier call to <code><a href="ftell" title="c/io/ftell">ftell</a></code> (only applicable to <code>SEEK_SET</code>).</p> +<p>POSIX allows seeking beyond the existing end of file. If an output is performed after this seek, any read from the gap will return zero bytes. Where supported by the filesystem, this creates a <i>sparse file</i>.</p> +<p>POSIX also requires that fseek first performs <code><a href="fflush" title="c/io/fflush">fflush</a></code> if there are any unwritten data (but whether the shift state is restored is implementation-defined).</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p><code>fseek</code> with error checking:</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + /* Prepare an array of double values. */ + #define SIZE 5 + double A[SIZE] = {1.0, 2.0, 3.0, 4.0, 5.0}; + /* Write array to a file. */ + FILE * fp = fopen("test.bin", "wb"); + fwrite(A, sizeof(double), SIZE, fp); + fclose (fp); + + /* Read the double values into array B. */ + double B[SIZE]; + fp = fopen("test.bin", "rb"); + + /* Set the file position indicator in front of third double value. */ + if (fseek(fp, sizeof(double) * 2L, SEEK_SET) != 0) + { + fprintf(stderr, "fseek() failed in file %s at line # %d\n", __FILE__, __LINE__ - 2); + fclose(fp); + return EXIT_FAILURE; + } + + int ret_code = fread(B, sizeof(double), 1, fp); /* read one double value */ + printf("ret_code == %d\n", ret_code); /* print the number of values read */ + printf("B[0] == %.1f\n", B[0]); /* print one value */ + + fclose(fp); + return EXIT_SUCCESS; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">ret_code == 1 +B[0] == 3.0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.21.9.2 The fseek function (p: 245) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.9.2 The fseek function (p: 336-337) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.9.2 The fseek function (p: 302-303) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.9.2 The fseek function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fsetpos" title="c/io/fsetpos"> <span class="t-lines"><span>fsetpos</span></span></a></div> </td> <td> moves the file position indicator to a specific location in a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fgetpos" title="c/io/fgetpos"> <span class="t-lines"><span>fgetpos</span></span></a></div> </td> <td> gets the file position indicator <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ftell" title="c/io/ftell"> <span class="t-lines"><span>ftell</span></span></a></div> </td> <td> returns the current file position indicator <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="rewind" title="c/io/rewind"> <span class="t-lines"><span>rewind</span></span></a></div> </td> <td> moves the file position indicator to the beginning in a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fseek" title="cpp/io/c/fseek">C++ documentation</a></span> for <code>fseek</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fseek" class="_attribution-link">https://en.cppreference.com/w/c/io/fseek</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffsetpos.html b/devdocs/c/io%2Ffsetpos.html new file mode 100644 index 00000000..3ef15100 --- /dev/null +++ b/devdocs/c/io%2Ffsetpos.html @@ -0,0 +1,73 @@ + <h1 id="firstHeading" class="firstHeading">fsetpos</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int fsetpos( FILE *stream, const fpos_t *pos );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Sets the file position indicator and the multibyte parsing state (if any) for the file stream <code>stream</code> according to the value pointed to by <code>pos</code>.</p> +<p>Besides establishing new parse state and position, a call to this function undoes the effects of <code><a href="ungetc" title="c/io/ungetc">ungetc</a></code> and clears the end-of-file state, if it is set.</p> +<p>If a read or write error occurs, the error indicator (<code><a href="ferror" title="c/io/ferror">ferror</a></code>) for the stream is set.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> file stream to modify </td> +</tr> <tr class="t-par"> <td> pos </td> <td> - </td> <td> pointer to a <code><a href="fpos_t" title="c/io/fpos t">fpos_t</a></code> object to use as new value of file position indicator </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>0</code> upon success, nonzero value otherwise.</p> +<h3 id="Notes"> Notes</h3> <p>After seeking to a non-end position in a wide stream, the next call to any output function may render the remainder of the file undefined, e.g. by outputting a multibyte sequence of a different length.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>fsetpos with error checking</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + /* Prepare an array of f-p values. */ + #define SIZE 5 + double A[SIZE] = {1.,2.,3.,4.,5.}; + /* Write array to a file. */ + FILE * fp = fopen("test.bin", "wb"); + fwrite(A,sizeof(double),SIZE,fp); + fclose (fp); + + /* Read the f-p values into array B. */ + double B[SIZE]; + fp = fopen("test.bin","rb"); + fpos_t pos; + if (fgetpos(fp,&pos) != 0) /* current position: start of file */ + { + perror("fgetpos()"); + fprintf(stderr,"fgetpos() failed in file %s at line # %d\n", __FILE__,__LINE__-3); + exit(EXIT_FAILURE); + } + + int ret_code = fread(B,sizeof(double),1,fp); /* read one f-p value */ + /* current position: after reading one f-p value */ + printf("%.1f; read count = %d\n", B[0], ret_code); /* print one f-p value and ret_code */ + + if (fsetpos(fp,&pos) != 0) /* reset current position to start of file */ + { + if (ferror(fp)) + { + perror("fsetpos()"); + fprintf(stderr,"fsetpos() failed in file %s at line # %d\n", __FILE__,__LINE__-5); + exit(EXIT_FAILURE); + } + } + + ret_code = fread(B,sizeof(double),1,fp); /* reread first f-p value */ + printf("%.1f; read count = %d\n", B[0], ret_code); /* print one f-p value and ret_code */ + fclose(fp); + + return EXIT_SUCCESS; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">1.0; read count = 1 +1.0; read count = 1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.9.3 The fsetpos function (p: 337) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.9.3 The fsetpos function (p: 303) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.9.3 The fsetpos function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fgetpos" title="c/io/fgetpos"> <span class="t-lines"><span>fgetpos</span></span></a></div> </td> <td> gets the file position indicator <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ftell" title="c/io/ftell"> <span class="t-lines"><span>ftell</span></span></a></div> </td> <td> returns the current file position indicator <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fseek" title="c/io/fseek"> <span class="t-lines"><span>fseek</span></span></a></div> </td> <td> moves the file position indicator to a specific location in a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fsetpos" title="cpp/io/c/fsetpos">C++ documentation</a></span> for <code>fsetpos</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fsetpos" class="_attribution-link">https://en.cppreference.com/w/c/io/fsetpos</a> + </p> +</div> diff --git a/devdocs/c/io%2Fftell.html b/devdocs/c/io%2Fftell.html new file mode 100644 index 00000000..c2696fde --- /dev/null +++ b/devdocs/c/io%2Fftell.html @@ -0,0 +1,77 @@ + <h1 id="firstHeading" class="firstHeading">ftell</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">long ftell( FILE *stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Returns the file position indicator for the file stream <code>stream</code>.</p> +<p>If the stream is open in binary mode, the value obtained by this function is the number of bytes from the beginning of the file.</p> +<p>If the stream is open in text mode, the value returned by this function is unspecified and is only meaningful as the input to <code><a href="fseek" title="c/io/fseek">fseek()</a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> file stream to examine </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>File position indicator on success or <code>-1L</code> if failure occurs.</p> +<p>On error, the <code>errno</code> variable is set to implementation-defined positive value.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>Demonstrates <code>ftell()</code> with error checking. Writes then reads a few floating-point (FP) values to/from a file.</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +/* If the condition is not met then exit the program with error message. */ +void check(_Bool condition, const char* func, int line) +{ + if (condition) + return; + perror(func); + fprintf(stderr, "%s failed in file %s at line # %d\n", func, __FILE__, line - 1); + exit(EXIT_FAILURE); +} + +int main(void) +{ + /* Prepare an array of FP values. */ + #define SIZE 5 + double A[SIZE] = {1.1,2.,3.,4.,5.}; + + /* Write array to a file. */ + const char* fname = "/tmp/test.bin"; + FILE* file = fopen(fname, "wb"); + check(file != NULL, "fopen()", __LINE__); + + const int write_count = fwrite(A, sizeof(double), SIZE, file); + check(write_count == SIZE, "fwrite()", __LINE__); + + fclose(file); + + /* Read the FP values into array B. */ + double B[SIZE]; + file = fopen(fname, "rb"); + check(file != NULL, "fopen()", __LINE__); + + long int pos = ftell(file); /* position indicator at start of file */ + check(pos != -1L, "ftell()", __LINE__); + printf("pos: %ld\n", pos); + + const int read_count = fread(B, sizeof(double), 1, file); /* read one FP value */ + check(read_count == 1, "fread()", __LINE__); + + pos = ftell(file); /* position indicator after reading one FP value */ + check(pos != -1L, "ftell()", __LINE__); + printf("pos: %ld\n", pos); + printf("B[0]: %.1f\n", B[0]); /* print one FP value */ + + return EXIT_SUCCESS; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">pos: 0 +pos: 8 +B[0]: 1.1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.9.4 The ftell function (p: 337-338) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.9.4 The ftell function (p: 303-304) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.9.4 The ftell function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fgetpos" title="c/io/fgetpos"> <span class="t-lines"><span>fgetpos</span></span></a></div> </td> <td> gets the file position indicator <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fseek" title="c/io/fseek"> <span class="t-lines"><span>fseek</span></span></a></div> </td> <td> moves the file position indicator to a specific location in a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fsetpos" title="c/io/fsetpos"> <span class="t-lines"><span>fsetpos</span></span></a></div> </td> <td> moves the file position indicator to a specific location in a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/ftell" title="cpp/io/c/ftell">C++ documentation</a></span> for <code>ftell</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/ftell" class="_attribution-link">https://en.cppreference.com/w/c/io/ftell</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffwide.html b/devdocs/c/io%2Ffwide.html new file mode 100644 index 00000000..4918f246 --- /dev/null +++ b/devdocs/c/io%2Ffwide.html @@ -0,0 +1,97 @@ + <h1 id="firstHeading" class="firstHeading">fwide</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int fwide( FILE *stream, int mode );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>If <code>mode > 0</code>, attempts to make <code>stream</code> wide-oriented. If <code>mode < 0</code>, attempts to make <code>stream</code> byte-oriented. If <code>mode==0</code>, only queries the current orientation of the stream.</p> +<p>If the orientation of the stream has already been decided (by executing output or by an earlier call to fwide), this function does nothing.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> pointer to the C I/O stream to modify or query </td> +</tr> <tr class="t-par"> <td> mode </td> <td> - </td> <td> integer value greater than zero to set the stream wide, less than zero to set the stream narrow, or zero to query only </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>An integer greater than zero if the stream is wide-oriented after this call, less than zero if the stream is byte-oriented after this call, and zero if the stream has no orientation.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>The following code sets and resets the stream orientation.</p> +<div class="c source-c"><pre data-language="c">#include <wchar.h> +#include <stdio.h> +#include <stdlib.h> + +void show_orientation(int n) +{ + n < 0 ? puts("\tnarrow orientation"): + n > 0 ? puts("\twide orientation"): + puts("\tno orientation"); +} + +void try_read(FILE* fp) +{ + int c = fgetc(fp); + if(c == EOF) + puts("\tnarrow character read failed"); + else + printf("\tnarrow character read '%c'\n", c); + + wint_t wc = fgetwc(fp); + if(wc == WEOF) + puts("\twide character read failed"); + else + printf("\twide character read '%lc'\n", wc); +} + +int main(void) +{ + enum fwide_orientation { narrow = -1, query, wide }; + + FILE* fp = fopen("main.cpp", "r"); + if (!fp) + { + perror("fopen() failed"); + return EXIT_FAILURE; + } + + puts("1) A newly opened stream has no orientation."); + show_orientation(fwide(fp, query)); + + puts("2) Establish byte orientation."); + show_orientation(fwide(fp, narrow)); + try_read(fp); + + puts("3) Only freopen() can reset stream orientation."); + if (freopen("main.cpp", "r", fp) == NULL) + { + perror("freopen() failed"); + return EXIT_FAILURE; + } + + puts("4) A reopened stream has no orientation."); + show_orientation(fwide(fp, query)); + + puts("5) Establish wide orientation."); + show_orientation(fwide(fp, wide)); + try_read(fp); + + fclose(fp); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">1) A newly opened stream has no orientation. + no orientation +2) Establish byte orientation. + narrow orientation + narrow character read '#' + wide character read failed +3) Only freopen() can reset stream orientation. +4) A reopened stream has no orientation. + no orientation +5) Establish wide orientation. + wide orientation + narrow character read failed + wide character read '#'</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.29.3.5 The fwide function (p: 309) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.3.5 The fwide function (p: 423) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.3.5 The fwide function (p: 369) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fopen" title="c/io/fopen"> <span class="t-lines"><span>fopen</span><span>fopen_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> opens a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fwide" title="cpp/io/c/fwide">C++ documentation</a></span> for <code>fwide</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fwide" class="_attribution-link">https://en.cppreference.com/w/c/io/fwide</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffwprintf.html b/devdocs/c/io%2Ffwprintf.html new file mode 100644 index 00000000..5ed5fda8 --- /dev/null +++ b/devdocs/c/io%2Ffwprintf.html @@ -0,0 +1,208 @@ + <h1 id="firstHeading" class="firstHeading">wprintf, fwprintf, swprintf, wprintf_s, fwprintf_s, swprintf_s, snwprintf_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td> <pre data-language="c">int wprintf( const wchar_t *format, ... );</pre> +</td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int wprintf( const wchar_t *restrict format, ... );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(2)</td> <td></td> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td> <pre data-language="c">int fwprintf( FILE *stream, const wchar_t *format, ... );</pre> +</td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int fwprintf( FILE *restrict stream, + const wchar_t *restrict format, ... );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(3)</td> <td></td> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td> <pre data-language="c">int swprintf( wchar_t *buffer, size_t bufsz, + const wchar_t *format, ... );</pre> +</td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int swprintf( wchar_t *restrict buffer, size_t bufsz, + const wchar_t *restrict format, ... );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int wprintf_s( const wchar_t *restrict format, ... );</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int fwprintf_s( FILE *restrict stream, + const wchar_t *restrict format, ... );</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int swprintf_s( wchar_t *restrict buffer, rsize_t bufsz, + const wchar_t *restrict format, ... );</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int snwprintf_s( wchar_t *restrict s, rsize_t n, + const wchar_t *restrict format, ... );</pre> +</td> <td> (7) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Loads the data from the given locations, converts them to wide string equivalents and writes the results to a variety of sinks.</p> +<div class="t-li1"> +<span class="t-li">1)</span> Writes the results to <code><a href="std_streams" title="c/io/std streams">stdout</a></code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Writes the results to a file stream <code>stream</code>.</div> <div class="t-li1"> +<span class="t-li">3)</span> If <code>bufsz</code> is greater than zero, writes the results to a wide string <code>buffer</code>. At most <code>bufsz-1</code> wide characters are written followed by null wide character. If <code>bufsz</code> is zero, nothing is written (and <code>buffer</code> may be a null pointer).</div> <div class="t-li1"> +<span class="t-li">4-6)</span> Same as <span class="t-v">(1-3)</span>, except that the following errors are detected at runtime and call the currently installed <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <ul> +<li> the conversion specifier <code>%n</code> is present in <code>format</code> </li> +<li> any of the arguments corresponding to <code>%s</code> is a null pointer </li> +<li> <code>format</code> or <code>buffer</code> is a null pointer </li> +<li> <code>bufsz</code> is zero or greater than <code>RSIZE_MAX/sizeof(wchar_t)</code> </li> +<li> encoding errors occur in any of string and character conversion specifiers </li> +<li> (only for <code>swprintf_s</code>) the number of wide characters to be written, including the null, would exceed <code>bufsz</code>.</li> +</ul> +</div> <div class="t-li1"> +<span class="t-li">7)</span> Same as <span class="t-v">(6)</span>, except it will truncate the result to fit within the array pointed to by s. As with all bounds-checked functions, <code>wprintf_s</code> , <code>fwprintf_s</code>, <code>swprintf_s</code>, and <code>snwprintf_s</code> are only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../io" title="c/io"><code><stdio.h></code></a>.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> output file stream to write to </td> +</tr> <tr class="t-par"> <td> buffer </td> <td> - </td> <td> pointer to a wide character string to write to </td> +</tr> <tr class="t-par"> <td> bufsz </td> <td> - </td> <td> up to <code>bufsz-1</code> wide characters may be written, plus the null terminator </td> +</tr> <tr class="t-par"> <td> format </td> <td> - </td> <td> pointer to a null-terminated wide string specifying how to interpret the data </td> +</tr> <tr class="t-par"> <td> ... </td> <td> - </td> <td> arguments specifying data to print. If any argument after <a href="../language/conversion#Default_argument_promotions" title="c/language/conversion">default argument promotions</a> is not the type expected by the corresponding conversion specifier, or if there are fewer arguments than required by <code>format</code>, the behavior is undefined. If there are more arguments than required by <code>format</code>, the extraneous arguments are evaluated and ignored. </td> +</tr> +</table> <p><br> The <b>format</b> string consists of ordinary wide characters (except <code>%</code>), which are copied unchanged into the output stream, and conversion specifications. Each conversion specification has the following format:</p> +<ul> +<li> introductory <code>%</code> character. </li> +<li> <span class="t-mark">(optional)</span> one or more flags that modify the behavior of the conversion: </li> +<ul> +<li> <code>-</code>: the result of the conversion is left-justified within the field (by default it is right-justified). </li> +<li> <code>+</code>: the sign of signed conversions is always prepended to the result of the conversion (by default the result is preceded by minus only when it is negative). </li> +<li> <i>space</i>: if the result of a signed conversion does not start with a sign character, or is empty, space is prepended to the result. It is ignored if <code>+</code> flag is present. </li> +<li> <code>#</code>: <i>alternative form</i> of the conversion is performed. See the table below for exact effects otherwise the behavior is undefined. </li> +<li> <code>0</code>: for integer and floating point number conversions, leading zeros are used to pad the field instead of <i>space</i> characters. For integer numbers it is ignored if the precision is explicitly specified. For other conversions using this flag results in undefined behavior. It is ignored if <code>-</code> flag is present. </li> +</ul> +<li> <span class="t-mark">(optional)</span> integer value or <code>*</code> that specifies minimum field width. The result is padded with <i>space</i> characters (by default), if required, on the left when right-justified, or on the right if left-justified. In the case when <code>*</code> is used, the width is specified by an additional argument of type <code>int</code>, which appears before the argument to be converted and the argument supplying precision if one is supplied. If the value of the argument is negative, it results with the <code>-</code> flag specified and positive field width (Note: This is the minimum width: The value is never truncated.). </li> +<ul> +<li> <span class="t-mark">(optional)</span> <code>.</code> followed by integer number or <code>*</code>, or neither that specifies <i>precision</i> of the conversion. In the case when <code>*</code> is used, the <i>precision</i> is specified by an additional argument of type <code>int</code>, which appears before the argument to be converted, but after the argument supplying minimum field width if one is supplied. If the value of this argument is negative, it is ignored. If neither a number nor <code>*</code> is used, the precision is taken as zero. See the table below for exact effects of <i>precision</i>. </li> +<li> <span class="t-mark">(optional)</span> <i>length modifier</i> that specifies the size of the argument (in combination with the conversion format specifier, it specifies the type of the corresponding argument). </li> +<li> conversion format specifier. </li> +</ul> +</ul> <p>The following format specifiers are available:</p> +<table class="wikitable"> <tr> <th rowspan="1">Conversion<br>Specifier </th> <th rowspan="1">Explanation </th> <th colspan="9">Expected<br>Argument Type </th> +</tr> <tr> <th colspan="2"> +<b>Length<br>Modifier</b><b>→</b> </th> <th> +<code>hh</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>h</code> </th> <th>(none) </th> <th> +<code>l</code> </th> <th> +<code>ll</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>j</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>z</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>t</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>L</code> </th> +</tr> <tr> <th> +<code>%</code> </th> <td>Writes literal <code>%</code>. The full conversion specification must be <code>%%</code>. </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>c</code> </th> <td> Writes a <b>single character</b>. <p>The argument is first converted to <code>wchar_t</code> as if by calling <code><a href="../string/multibyte/btowc" title="c/string/multibyte/btowc">btowc</a></code>. If the <b>l</b> modifier is used, the <code>wint_t</code> argument is first converted to <code>wchar_t</code>.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<div><code>int</code></div> </td> <td> +<div><code>wint_t</code></div> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>s</code> </th> <td> Writes a <b>character string</b> <p>The argument must be a pointer to the initial element of a character array containing a multibyte character sequence beginning in the initial shift state, which is converted to wide character array as if by a call to <code><a href="../string/multibyte/mbrtowc" title="c/string/multibyte/mbrtowc">mbrtowc</a></code> with zero-initialized conversion state. <i>Precision</i> specifies the maximum number of wide characters to be written. If <i>Precision</i> is not specified, writes every wide characters up to and not including the first null terminator. If the <b>l</b> specifier is used, the argument must be a pointer to the initial element of an array of <code>wchar_t</code>.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<div><code>char*</code></div> </td> <td> +<div><code>wchar_t*</code></div> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>d</code><br><code>i</code> </th> <td> Converts a <b>signed integer</b> into decimal representation <i>[-]dddd</i>. <p><i>Precision</i> specifies the minimum number of digits to appear. The default precision is <code>1</code>.<br><br> If both the converted value and the precision are <code>0</code> the conversion results in no characters.<br><br></p> +</td> <td rowspan="1"> +<div><code>signed char</code></div> </td> <td rowspan="1"> +<div><code>short</code></div> </td> <td rowspan="1"> +<div><code>int</code></div> </td> <td rowspan="1"> +<div><code>long</code></div> </td> <td rowspan="1"> +<div><code>long long</code></div> </td> <td rowspan="1"> +<div><code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw118">intmax_t</span></a></code></div> </td> <td rowspan="1"> +<div>signed <code><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a></code> +</div> </td> <td rowspan="1"> +<div><code><a href="http://en.cppreference.com/w/c/types/ptrdiff_t"><span class="kw101">ptrdiff_t</span></a></code></div> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>o</code> </th> <td> Converts an <b>unsigned integer</b> into octal representation <i>oooo</i>. <p><i>Precision</i> specifies the minimum number of digits to appear. The default precision is <code>1</code>. If both the converted value and the precision are <code>0</code> the conversion results in no characters. In the <i>alternative implementation</i> precision is increased if necessary, to write one leading zero. In that case if both the converted value and the precision are <code>0</code>, single <code>0</code> is written.</p> +</td> <td rowspan="3"> +<div><code>unsigned char</code></div> </td> <td rowspan="3"> +<div><code>unsigned short</code></div> </td> <td rowspan="3"> +<div><code>unsigned int</code></div> </td> <td rowspan="3"> +<div><code>unsigned long</code></div> </td> <td rowspan="3"> +<div><code>unsigned long long</code></div> </td> <td rowspan="3"> +<div><code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw132">uintmax_t</span></a></code></div> </td> <td rowspan="3"> +<div><code><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a></code></div> </td> <td rowspan="3"> +<div>unsigned version of <code><a href="http://en.cppreference.com/w/c/types/ptrdiff_t"><span class="kw101">ptrdiff_t</span></a></code> +</div> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>x</code><br><code>X</code> </th> <td> Converts an <b>unsigned integer</b> into hexadecimal representation <i>hhhh</i>. <p>For the <code>x</code> conversion letters <code>abcdef</code> are used.<br> For the <code>X</code> conversion letters <code>ABCDEF</code> are used.<br> <i>Precision</i> specifies the minimum number of digits to appear. The default precision is <code>1</code>. If both the converted value and the precision are <code>0</code> the conversion results in no characters. In the <i>alternative implementation</i> <code>0x</code> or <code>0X</code> is prefixed to results if the converted value is nonzero.</p> +</td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>u</code> </th> <td> Converts an <b>unsigned integer</b> into decimal representation <i>dddd</i>. <p><i>Precision</i> specifies the minimum number of digits to appear. The default precision is <code>1</code>. If both the converted value and the precision are <code>0</code> the conversion results in no characters.</p> +</td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>f</code><br><code>F</code> </th> <td> Converts <b>floating-point number</b> to the decimal notation in the style <i>[-]ddd.ddd</i>. <p><i>Precision</i> specifies the exact number of digits to appear after the decimal point character. The default precision is <code>6</code>. In the <i>alternative implementation</i> decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td rowspan="4"> +<div><code>double</code></div> </td> <td rowspan="4"> +<div> +<code>double</code><span class="t-mark-rev t-since-c99">(C99)</span> +</div> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td rowspan="4"> +<div><code>long double</code></div> </td> +</tr> <tr> <th> +<code>e</code><br><code>E</code> </th> <td> Converts <b>floating-point number</b> to the decimal exponent notation. <p>For the <code>e</code> conversion style <i>[-]d.ddd</i><code>e</code><i>±dd</i> is used.<br> For the <code>E</code> conversion style <i>[-]d.ddd</i><code>E</code><i>±dd</i> is used.<br> The exponent contains at least two digits, more digits are used only if necessary. If the value is <code>0</code>, the exponent is also <code>0</code>. <i>Precision</i> specifies the exact number of digits to appear after the decimal point character. The default precision is <code>6</code>. In the <i>alternative implementation</i> decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>a</code><br><code>A</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <td> Converts <b>floating-point number</b> to the hexadecimal exponent notation. <p>For the <code>a</code> conversion style <i>[-]</i><code>0x</code><i>h.hhh</i><code>p</code><i>±d</i> is used.<br> For the <code>A</code> conversion style <i>[-]</i><code>0X</code><i>h.hhh</i><code>P</code><i>±d</i> is used.<br> The first hexadecimal digit is not <code>0</code> if the argument is a normalized floating point value. If the value is <code>0</code>, the exponent is also <code>0</code>. <i>Precision</i> specifies the exact number of digits to appear after the hexadecimal point character. The default precision is sufficient for exact representation of the value. In the <i>alternative implementation</i> decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>g</code><br><code>G</code> </th> <td> Converts <b>floating-point number</b> to decimal or decimal exponent notation depending on the value and the <i>precision</i>. <p>For the <code>g</code> conversion style conversion with style <code>e</code> or <code>f</code> will be performed.<br> For the <code>G</code> conversion style conversion with style <code>E</code> or <code>F</code> will be performed.<br> Let <code>P</code> equal the precision if nonzero, <code>6</code> if the precision is not specified, or <code>1</code> if the precision is <code>0</code>. Then, if a conversion with style <code>E</code> would have an exponent of <code>X</code>:</p> +<ul> +<li> if <i>P > X ≥ −4</i>, the conversion is with style <code>f</code> or <code>F</code> and precision <i>P − 1 − X</i>. </li> +<li> otherwise, the conversion is with style <code>e</code> or <code>E</code> and precision <i>P − 1</i>. </li> +</ul> <p>Unless <i>alternative representation</i> is requested the trailing zeros are removed, also the decimal point character is removed if no fractional part is left. For infinity and not-a-number conversion style see notes.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>n</code> </th> <td> Returns the <b>number of characters written</b> so far by this call to the function. <p>The result is <i>written</i> to the value pointed to by the argument. The specification may not contain any <i>flag</i>, <i>field width</i>, or <i>precision</i>.<br><br><br><br></p> +</td> <td> +<div><code>signed char*</code></div> </td> <td> +<div><code>short*</code></div> </td> <td> +<div><code>int*</code></div> </td> <td> +<div><code>long*</code></div> </td> <td> +<div><code>long long*</code></div> </td> <td> +<div><code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw118">intmax_t</span></a><span class="sy2">*</span></code></div> </td> <td> +<div>signed <code><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="sy2">*</span></code> +</div> </td> <td> +<div><code><a href="http://en.cppreference.com/w/c/types/ptrdiff_t"><span class="kw101">ptrdiff_t</span></a><span class="sy2">*</span></code></div> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>p</code> </th> <td>Writes an implementation defined character sequence defining a <b>pointer</b>. </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<code>void*</code> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> +</table> <p>The floating point conversion functions convert infinity to <code>inf</code> or <code>infinity</code>. Which one is used is implementation defined.</p> +<p>Not-a-number is converted to <code>nan</code> or <code>nan(<i>char_sequence</i>)</code>. Which one is used is implementation defined.</p> +<p>The conversions <code>F</code>, <code>E</code>, <code>G</code>, <code>A</code> output <code>INF</code>, <code>INFINITY</code>, <code>NAN</code> instead.</p> +<p>Even though <code>%c</code> expects <code>int</code> argument, it is safe to pass a <code>char</code> because of the integer promotion that takes place when a variadic function is called.</p> +<p>The correct conversion specifications for the fixed-width character types (<code><a href="../types/integer" title="c/types/integer">int8_t</a></code>, etc) are defined in the header <a href="../types/integer" title="c/types/integer"><code><inttypes.h></code></a> (although <code><a href="../types/integer" title="c/types/integer">PRIdMAX</a></code>, <code><a href="../types/integer" title="c/types/integer">PRIuMAX</a></code>, etc is synonymous with <code>%jd</code>, <code>%ju</code>, etc).</p> +<p>The memory-writing conversion specifier <code>%n</code> is a common target of security exploits where format strings depend on user input and is not supported by the bounds-checked <code>printf_s</code> family of functions.</p> +<p>There is a <a href="../language/eval_order" title="c/language/eval order">sequence point</a> after the action of each conversion specifier; this permits storing multiple <code>%n</code> results in the same variable or, as an edge case, printing a string modified by an earlier <code>%n</code> within the same call.</p> +<p>If a conversion specification is invalid, the behavior is undefined.</p> +<h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1,2)</span> Number of wide characters written if successful or negative value if an error occurred.</div> <div class="t-li1"> +<span class="t-li">3)</span> Number of wide characters written (not counting the terminating null wide character) if successful or negative value if an encoding error occurred or if the number of characters to be generated was equal or greater than <code>size</code> (including when <code>size</code> is zero).</div> <div class="t-li1"> +<span class="t-li">4,5)</span> Number of wide characters written if successful or negative value if an error occurred.</div> <div class="t-li1"> +<span class="t-li">6)</span> Number of wide characters (not counting the terminating null) that were written to <code>buffer</code>. Returns a negative value on encoding errors and on overflow. Returns zero on all other errors.</div> <div class="t-li1"> +<span class="t-li">7)</span> Number of wide characters (not counting the terminating null) that would have been written to <code>buffer</code> had <code>bufsz</code> been sufficiently large, or a negative value if an error occurs. (meaning, write was successful and complete only if the return is nonnegative and less than <code>bufsz</code>)</div> <h3 id="Notes"> Notes</h3> <p>While narrow strings provide <code><a href="fprintf" title="c/io/fprintf">snprintf</a></code>, which makes it possible to determine the required output buffer size, there is no equivalent for wide strings<span class="t-rev-inl t-since-c11"><span> (until <code>snwprintf_s</code>)</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span>, and in order to determine the buffer size, the program may need to call <code>swprintf</code>, check the result value, and reallocate a larger buffer, trying again until successful.</p> +<p><code>snwprintf_s</code>, unlike <code>swprintf_s</code>, will truncate the result to fit within the array pointed to by <code>buffer</code>, even though truncation is treated as an error by most bounds-checked functions.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <wchar.h> + +int main(void) +{ + char narrow_str[] = "z\u00df\u6c34\U0001f34c"; + // or "zß水🍌" + // or "\x7a\xc3\x9f\xe6\xb0\xb4\xf0\x9f\x8d\x8c"; + wchar_t warr[29]; // the expected string is 28 characters plus 1 null terminator + setlocale(LC_ALL, "en_US.utf8"); + swprintf(warr, sizeof warr/sizeof *warr, + L"Converted from UTF-8: '%s'", narrow_str); + wprintf(L"%ls\n", warr); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Converted from UTF-8: 'zß水🍌'</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.29.2.1 The fwprintf function (p: 403-410) </li> +<li> 7.29.2.3 The swprintf function (p: 416) </li> +<li> 7.29.2.11 The wprintf function (p: 421) </li> +<li> K.3.9.1.1 The fwprintf_s function (p: 628) </li> +<li> K.3.9.1.4 The swprintf_s function (p: 630-631) </li> +<li> K.3.9.1.13 The wprintf_s function (p: 637-638) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.24.2.1 The fwprintf function (p: 349-356) </li> +<li> 7.24.2.3 The swprintf function (p: 362) </li> +<li> 7.24.2.11 The wprintf function (p: 366) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fprintf" title="c/io/fprintf"> <span class="t-lines"><span>printf</span><span>fprintf</span><span>sprintf</span><span>snprintf</span><span>printf_s</span><span>fprintf_s</span><span>sprintf_s</span><span>snprintf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> prints formatted output to <code><a href="std_streams" title="c/io/std streams">stdout</a></code>, a file stream or a buffer <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="vfwprintf" title="c/io/vfwprintf"> <span class="t-lines"><span>vwprintf</span><span>vfwprintf</span><span>vswprintf</span><span>vwprintf_s</span><span>vfwprintf_s</span><span>vswprintf_s</span><span>vsnwprintf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> prints formatted wide character output to <code><a href="std_streams" title="c/io/std streams">stdout</a></code>, a file stream<br> or a buffer using variable argument list <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fputws" title="c/io/fputws"> <span class="t-lines"><span>fputws</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> writes a wide string to a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fwprintf" title="cpp/io/c/fwprintf">C++ documentation</a></span> for <code>wprintf, fwprintf, swprintf</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fwprintf" class="_attribution-link">https://en.cppreference.com/w/c/io/fwprintf</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffwrite.html b/devdocs/c/io%2Ffwrite.html new file mode 100644 index 00000000..35104178 --- /dev/null +++ b/devdocs/c/io%2Ffwrite.html @@ -0,0 +1,59 @@ + <h1 id="firstHeading" class="firstHeading">fwrite</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">size_t fwrite( const void* buffer, size_t size, size_t count, + FILE* stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">size_t fwrite( const void* restrict buffer, size_t size, size_t count, + FILE* restrict stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Writes <code>count</code> of objects from the given array <code>buffer</code> to the output stream <code>stream</code>. The objects are written as if by reinterpreting each object as an array of <code>unsigned char</code> and calling <code><a href="fputc" title="c/io/fputc">fputc</a></code> <code>size</code> times for each object to write those <code>unsigned char</code>s into <code>stream</code>, in order. The file position indicator for the stream is advanced by the number of characters written.</p> +<p>If an error occurs, the resulting value of the file position indicator for the stream is indeterminate.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> buffer </td> <td> - </td> <td> pointer to the first object in the array to be written </td> +</tr> <tr class="t-par"> <td> size </td> <td> - </td> <td> size of each object </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> the number of the objects to be written </td> +</tr> <tr class="t-par"> <td> stream </td> <td> - </td> <td> pointer to the output stream </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The number of objects written successfully, which may be less than <code>count</code> if an error occurs.</p> +<p>If <code>size</code> or <code>count</code> is zero, <code>fwrite</code> returns zero and performs no other action.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +enum { SIZE = 5 }; + +int main(void) +{ + double a[SIZE] = {1, 2, 3, 4, 5}; + FILE* f1 = fopen("file.bin", "wb"); + assert(f1); + size_t r1 = fwrite(a, sizeof a[0], SIZE, f1); + printf("wrote %zu elements out of %d requested\n", r1, SIZE); + fclose(f1); + + double b[SIZE]; + FILE* f2 = fopen("file.bin", "rb"); + size_t r2 = fread(b, sizeof b[0], SIZE, f2); + fclose(f2); + printf("read back: "); + for (size_t i = 0; i < r2; ++i) + printf("%0.2f ", b[i]); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">wrote 5 elements out of 5 requested +read back: 1.00 2.00 3.00 4.00 5.00</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.21.8.2 The fwrite function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.21.8.2 The fwrite function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.8.2 The fwrite function (p: 335-336) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.8.2 The fwrite function (p: 301-302) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.8.2 The fwrite function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fprintf" title="c/io/fprintf"> <span class="t-lines"><span>printf</span><span>fprintf</span><span>sprintf</span><span>snprintf</span><span>printf_s</span><span>fprintf_s</span><span>sprintf_s</span><span>snprintf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> prints formatted output to <code><a href="std_streams" title="c/io/std streams">stdout</a></code>, a file stream or a buffer <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fputs" title="c/io/fputs"> <span class="t-lines"><span>fputs</span></span></a></div> </td> <td> writes a character string to a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fread" title="c/io/fread"> <span class="t-lines"><span>fread</span></span></a></div> </td> <td> reads from a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fwrite" title="cpp/io/c/fwrite">C++ documentation</a></span> for <code>fwrite</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fwrite" class="_attribution-link">https://en.cppreference.com/w/c/io/fwrite</a> + </p> +</div> diff --git a/devdocs/c/io%2Ffwscanf.html b/devdocs/c/io%2Ffwscanf.html new file mode 100644 index 00000000..69582d63 --- /dev/null +++ b/devdocs/c/io%2Ffwscanf.html @@ -0,0 +1,216 @@ + <h1 id="firstHeading" class="firstHeading">wscanf, fwscanf, swscanf, wscanf_s, fwscanf_s, swscanf_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td> <pre data-language="c">int wscanf( const wchar_t *format, ... );</pre> +</td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int wscanf( const wchar_t *restrict format, ... );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(2)</td> <td></td> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td> <pre data-language="c">int fwscanf( FILE *stream, const wchar_t *format, ... );</pre> +</td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int fwscanf( FILE *restrict stream, + const wchar_t *restrict format, ... );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(3)</td> <td></td> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td> <pre data-language="c">int swscanf( const wchar_t *buffer, const wchar_t *format, ... );</pre> +</td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int swscanf( const wchar_t *restrict buffer, + const wchar_t *restrict format, ... );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int wscanf_s( const wchar_t *restrict format, ...);</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int fwscanf_s( FILE *restrict stream, + const wchar_t *restrict format, ...);</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int swscanf_s( const wchar_t *restrict s, + const wchar_t *restrict format, ...);</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Reads data from the a variety of sources, interprets it according to <code>format</code> and stores the results into given locations.</p> +<div class="t-li1"> +<span class="t-li">1)</span> Reads the data from <code><a href="std_streams" title="c/io/std streams">stdin</a></code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Reads the data from file stream <code>stream</code>.</div> <div class="t-li1"> +<span class="t-li">3)</span> Reads the data from null-terminated wide string <code>buffer</code>. Reaching the end of the string is equivalent to reaching the end-of-file condition for <code>fwscanf</code> +</div> <div class="t-li1"> +<span class="t-li">4-6)</span> Same as <span class="t-v">(1-3)</span>, except that <code>%c</code>, <code>%s</code>, and <code>%[</code> conversion specifiers each expect two arguments (the usual pointer and a value of type <code>rsize_t</code> indicating the size of the receiving array, which may be <code>1</code> when reading with a <code>%lc</code> into a single wide character) and except that the following errors are detected at runtime and call the currently installed <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> any of the arguments of pointer type is a null pointer </li> +<li> <code>format</code>, <code>stream</code>, or <code>buffer</code> is a null pointer </li> +<li> the number of characters that would be written by <code>%c</code>, <code>%s</code>, or <code>%[</code>, plus the terminating null character, would exceed the second (<code>rsize_t</code>) argument provided for each of those conversion specifiers </li> +<li> optionally, any other detectable error, such as unknown conversion specifier </li> +</ul> </dd> +<dd>As all bounds-checked functions, <code>wscanf_s</code>, <code>fwscanf_s</code>, and <code>swscanf_s</code> are only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../string/wide" title="c/string/wide"><code><wchar.h></code></a>.</dd> +</dl> +</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> input file stream to read from </td> +</tr> <tr class="t-par"> <td> buffer </td> <td> - </td> <td> pointer to a null-terminated wide string to read from </td> +</tr> <tr class="t-par"> <td> format </td> <td> - </td> <td> pointer to a null-terminated wide string specifying how to read the input </td> +</tr> <tr class="t-par"> <td> ... </td> <td> - </td> <td> receiving arguments. </td> +</tr> +</table> <p><br> The <b>format</b> string consists of</p> +<ul> +<li> non-whitespace wide characters except <code>%</code>: each such character in the format string consumes exactly one identical character from the input stream, or causes the function to fail if the next character on the stream does not compare equal. </li> +<li> whitespace characters: any single whitespace character in the format string consumes all available consecutive whitespace characters from the input (determined as if by calling <a href="../string/wide/iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a> in a loop). Note that there is no difference between <code>"\n"</code>, <code>" "</code>, <code>"\t\t"</code>, or other whitespace in the format string. </li> +<li> conversion specifications. Each conversion specification has the following format: </li> +<ul> +<li> introductory <code>%</code> character. </li> +<li> <span class="t-mark">(optional)</span> assignment-suppressing character <code>*</code>. If this option is present, the function does not assign the result of the conversion to any receiving argument. </li> +<li> <span class="t-mark">(optional)</span> integer number (greater than zero) that specifies <i>maximum field width</i>, that is, the maximum number of characters that the function is allowed to consume when doing the conversion specified by the current conversion specification. Note that <code>%s</code> and <code>%[</code> may lead to buffer overflow if the width is not provided. </li> +<li> <span class="t-mark">(optional)</span> <i>length modifier</i> that specifies the size of the receiving argument, that is, the actual destination type. This affects the conversion accuracy and overflow rules. The default destination type is different for each conversion type (see table below). </li> +<li> conversion format specifier. </li> +</ul> +</ul> <p>The following format specifiers are available:</p> +<table class="wikitable"> <tr> <th rowspan="1">Conversion<br>specifier </th> <th rowspan="1">Explanation </th> <th colspan="9">Argument type </th> +</tr> <tr> <th colspan="2"> +<b>Length modifier →</b> </th> <th> +<code>hh</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>h</code> </th> <th>(none) </th> <th> +<code>l</code> </th> <th> +<code>ll</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>j</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>z</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>t</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>L</code> </th> +</tr> <tr> <th> +<code>%</code> </th> <td>Matches literal <code>%</code>. </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>c</code> </th> <td> Matches a <b>character</b> or a sequence of <b>characters</b>. <p>If a width specifier is used, matches exactly <i>width</i> wide characters (the argument must be a pointer to an array with sufficient room). Unlike %s and %[, does not append the null character to the array.</p> +</td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3"> +<div><code>char*</code></div> </td> <td rowspan="3"> +<div><code>wchar_t*</code></div> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>s</code> </th> <td> Matches a sequence of non-whitespace characters (a <b>string</b>). <p>If width specifier is used, matches up to <i>width</i> or until the first whitespace character, whichever appears first. Always stores a null character in addition to the characters matched (so the argument array must have room for at least <i>width+1</i> characters)</p> +</td> +</tr> <tr> <th> +<code>[</code><span class="t-spar">set</span><code>]</code> </th> <td> Matches a non-empty sequence of character from <span class="t-spar">set</span> of characters. <p>If the first character of the set is <code>^</code>, then all characters not in the set are matched. If the set begins with <code>]</code> or <code>^]</code> then the <code>]</code> character is also included into the set. It is implementation-defined whether the character <code>-</code> in the non-initial position in the scanset may be indicating a range, as in <code>[0-9]</code>. If width specifier is used, matches only up to <i>width</i>. Always stores a null character in addition to the characters matched (so the argument array must have room for at least <i>width+1</i> characters)</p> +</td> +</tr> <tr> <th> +<code>d</code> </th> <td> Matches a <b>decimal integer</b>. <p>The format of the number is the same as expected by <a href="../string/wide/wcstol" title="c/string/wide/wcstol"><code>wcstol</code></a> with the value <code>10</code> for the <code>base</code> argument</p> +</td> <td rowspan="6"> +<div> +<code>signed char*</code> or <code>unsigned char*</code> +</div> </td> <td rowspan="6"> +<div> +<code>signed short*</code> or <code>unsigned short*</code> +</div> </td> <td rowspan="6"> +<div> +<code>signed int*</code> or <code>unsigned int*</code> +</div> </td> <td rowspan="6"> +<div> +<code>signed long*</code> or <code>unsigned long*</code> +</div> </td> <td rowspan="6"> +<div> +<code>signed long long*</code> or <code>unsigned long long*</code> +</div> </td> <td rowspan="6"> +<div> +<code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw118">intmax_t</span></a><span class="sy2">*</span></code> or <code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw132">uintmax_t</span></a><span class="sy2">*</span></code> +</div> </td> <td rowspan="6"> +<div><code><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="sy2">*</span></code></div> </td> <td rowspan="6"> +<div><code><a href="http://en.cppreference.com/w/c/types/ptrdiff_t"><span class="kw101">ptrdiff_t</span></a><span class="sy2">*</span></code></div> </td> <td rowspan="6" class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>i</code> </th> <td> Matches an <b>integer</b>. <p>The format of the number is the same as expected by <a href="../string/wide/wcstol" title="c/string/wide/wcstol"><code>wcstol</code></a> with the value <code>0</code> for the <code>base</code> argument (base is determined by the first characters parsed)</p> +</td> +</tr> <tr> <th> +<code>u</code> </th> <td> Matches an unsigned <b>decimal integer</b>. <p>The format of the number is the same as expected by <a href="../string/wide/wcstoul" title="c/string/wide/wcstoul"><code>wcstoul</code></a> with the value <code>10</code> for the <code>base</code> argument.</p> +</td> +</tr> <tr> <th> +<code>o</code> </th> <td> Matches an unsigned <b>octal integer</b>. <p>The format of the number is the same as expected by <a href="../string/wide/wcstoul" title="c/string/wide/wcstoul"><code>wcstoul</code></a> with the value <code>8</code> for the <code>base</code> argument</p> +</td> +</tr> <tr> <th> +<code>x</code>, <code>X</code> </th> <td> Matches an unsigned <b>hexadecimal integer</b>. <p>The format of the number is the same as expected by <a href="../string/wide/wcstoul" title="c/string/wide/wcstoul"><code>wcstoul</code></a> with the value <code>16</code> for the <code>base</code> argument</p> +</td> +</tr> <tr> <th> +<code>n</code> </th> <td> Returns the <b>number of characters read so far</b>. <p>No input is consumed. Does not increment the assignment count. If the specifier has assignment-suppressing operator defined, the behavior is undefined</p> +</td> +</tr> <tr> <th> +<code>a</code>, <code>A</code><span class="t-mark-rev t-since-c99">(C99)</span><br><code>e</code>, <code>E</code><br><code>f</code>, <code>F</code><span class="t-mark-rev t-since-c99">(C99)</span><br><code>g</code>, <code>G</code> </th> <td> Matches a <b>floating-point number</b>. <p>The format of the number is the same as expected by <a href="../string/wide/wcstof" title="c/string/wide/wcstof"><code>wcstof</code></a></p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<div><code>float*</code></div> </td> <td> +<div><code>double*</code></div> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<div><code>long double*</code></div> </td> +</tr> <tr> <th> +<code>p</code> </th> <td> Matches implementation defined character sequence defining a <b>pointer</b>. <p><code>printf</code> family of functions should produce the same sequence using <code>%p</code> format specifier</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<div><code>void**</code></div> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> +</table> <p>For every conversion specifier other than <code>n</code>, the longest sequence of input characters which does not exceed any specified field width and which either is exactly what the conversion specifier expects or is a prefix of a sequence it would expect, is what's consumed from the stream. The first character, if any, after this consumed sequence remains unread. If the consumed sequence has length zero or if the consumed sequence cannot be converted as specified above, the matching failure occurs unless end-of-file, an encoding error, or a read error prevented input from the stream, in which case it is an input failure.</p> +<p>All conversion specifiers other than <code>[</code>, <code>c</code>, and <code>n</code> consume and discard all leading whitespace characters (determined as if by calling <a href="../string/wide/iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a>) before attempting to parse the input. These consumed characters do not count towards the specified maximum field width.</p> +<p>If the length specifier <code>l</code> is not used, the conversion specifiers <code>c</code>, <code>s</code>, and <code>[</code> perform wide-to-multibyte character conversion as if by calling <a href="../string/multibyte/wcrtomb" title="c/string/multibyte/wcrtomb"><code>wcrtomb</code></a> with an <a href="../string/multibyte/mbstate_t" title="c/string/multibyte/mbstate t"><code>mbstate_t</code></a> object initialized to zero before the first character is converted.</p> +<p>The conversion specifiers <code>s</code> and <code>[</code> always store the null terminator in addition to the matched characters. The size of the destination array must be at least one greater than the specified field width. The use of <code>%s</code> or <code>%[</code>, without specifying the destination array size, is as unsafe as <code><a href="gets" title="c/io/gets">gets</a></code>.</p> +<p>The correct conversion specifications for the <a href="../types/integer" title="c/types/integer">fixed-width integer types</a> (<code><a href="../types/integer" title="c/types/integer">int8_t</a></code>, etc) are defined in the header <a href="../types/integer" title="c/types/integer"><code><inttypes.h></code></a> (although <a href="../types/integer" title="c/types/integer"><code>SCNdMAX</code></a>, <a href="../types/integer" title="c/types/integer"><code>SCNuMAX</code></a>, etc is synonymous with <code>%jd</code>, <code>%ju</code>, etc).</p> +<p>There is a <a href="../language/eval_order" title="c/language/eval order">sequence point</a> after the action of each conversion specifier; this permits storing multiple fields in the same "sink" variable.</p> +<p>When parsing an incomplete floating-point value that ends in the exponent with no digits, such as parsing <code>"100er"</code> with the conversion specifier <code>%f</code>, the sequence <code>"100e"</code> (the longest prefix of a possibly valid floating-point number) is consumed, resulting in a matching error (the consumed sequence cannot be converted to a floating-point number), with <code>"r"</code> remaining. Some existing implementations do not follow this rule and roll back to consume only <code>"100"</code>, leaving <code>"er"</code>, e.g. <a rel="nofollow" class="external text" href="https://sourceware.org/bugzilla/show_bug.cgi?id=1765">glibc bug 1765</a>.</p> +<h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1-3)</span> Number of receiving arguments successfully assigned, or <code><a href="../io" title="c/io">EOF</a></code> if read failure occurs before the first receiving argument was assigned.</div> <div class="t-li1"> +<span class="t-li">4-6)</span> Same as <span class="t-v">(1-3)</span>, except that <code><a href="../io" title="c/io">EOF</a></code> is also returned if there is a runtime constraint violation.</div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <wchar.h> +#include <string.h> + +#define NUM_VARS 3 +#define ERR_READ 2 +#define ERR_WRITE 3 + +int main(void) { + wchar_t state[64]; + wchar_t capital[64]; + unsigned int population = 0; + int elevation = 0; + int age = 0; + float pi = 0; + +#if INTERACTIVE_MODE + wprintf(L"Enter state, age, and pi value: "); + if (wscanf(L"%ls%d%f", state, &age, &pi) != NUM_VARS) { + fprintf(stderr, "Error reading input.\n"); + return ERR_READ; + } +#else + wchar_t* input = L"California 170 3.141592"; + if (swscanf(input, L"%ls%d%f", state, &age, &pi) != NUM_VARS) { + fprintf(stderr, "Error reading input.\n"); + return ERR_READ; + } +#endif + wprintf(L"State: %ls\nAge : %d years\nPi : %.5f\n\n", state, age, pi); + + FILE* fp = tmpfile(); + if (fp) { + // write some data to temp file + if (!fwprintf(fp, L"Mississippi Jackson 420000 807")) { + fprintf(stderr, "Error writing to file.\n"); + fclose(fp); + return ERR_WRITE; + } + // rewind file pointer + rewind(fp); + + // read data into variables + fwscanf(fp, L"%ls%ls%u%d", state, capital, &population, &elevation); + wprintf(L"State : %ls\nCapital: %ls\nJackson population (in 2020): %u\n" + L"Highest elevation: %dft\n", + state, capital, population, elevation); + fclose(fp); + } +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">State: California +Age : 170 years +Pi : 3.14159 + +State : Mississippi +Capital: Jackson +Jackson population (in 2020): 420000 +Highest elevation: 807ft</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.29.2.2 The fwscanf function (p: 410-416) </li> +<li> 7.29.2.4 The swscanf function (p: 417) </li> +<li> 7.29.2.12 The wscanf function (p: 421) </li> +<li> K.3.9.1.2 The fwscanf_s function (p: 628-629) </li> +<li> K.3.9.1.5 The swscanf_s function (p: 631) </li> +<li> K.3.9.1.14 The wscanf_s function (p: 638) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.24.2.2 The fwscanf function (p: 356-362) </li> +<li> 7.24.2.4 The swscanf function (p: 362) </li> +<li> 7.24.2.12 The wscanf function (p: 366-367) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="vfwscanf" title="c/io/vfwscanf"> <span class="t-lines"><span>vwscanf</span><span>vfwscanf</span><span>vswscanf</span><span>vwscanf_s</span><span>vfwscanf_s</span><span>vswscanf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads formatted wide character input from <code><a href="std_streams" title="c/io/std streams">stdin</a></code>, a file stream<br> or a buffer using variable argument list <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fwscanf" title="cpp/io/c/fwscanf">C++ documentation</a></span> for <code>wscanf, fwscanf, swscanf</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fwscanf" class="_attribution-link">https://en.cppreference.com/w/c/io/fwscanf</a> + </p> +</div> diff --git a/devdocs/c/io%2Fgetchar.html b/devdocs/c/io%2Fgetchar.html new file mode 100644 index 00000000..51e96aa8 --- /dev/null +++ b/devdocs/c/io%2Fgetchar.html @@ -0,0 +1,49 @@ + <h1 id="firstHeading" class="firstHeading">getchar</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int getchar( void );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Reads the next character from <code><a href="std_streams" title="c/io/std streams">stdin</a></code>.</p> +<p>Equivalent to <code><a href="http://en.cppreference.com/w/c/io/fgetc"><span class="kw828">getc</span></a><span class="br0">(</span><a href="http://en.cppreference.com/w/c/io/std_streams"><span class="kw885">stdin</span></a><span class="br0">)</span></code>.</p> +<h3 id="Parameters"> Parameters</h3> <p>(none)</p> +<h3 id="Return_value"> Return value</h3> <p>The obtained character on success or <code><a href="../io" title="c/io">EOF</a></code> on failure.</p> +<p>If the failure has been caused by end-of-file condition, additionally sets the <i>eof</i> indicator (see <code><a href="feof" title="c/io/feof">feof()</a></code>) on <code><a href="std_streams" title="c/io/std streams">stdin</a></code>. If the failure has been caused by some other error, sets the <i>error</i> indicator (see <code><a href="ferror" title="c/io/ferror">ferror()</a></code>) on <code><a href="std_streams" title="c/io/std streams">stdin</a></code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>Demonstrates <code>getchar</code> with error checking</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + for (int ch; (ch = getchar()) != EOF;) // read/print "abcde" from stdin + printf("%c", ch); + + // Test reason for reaching EOF. + if (feof(stdin)) // if failure caused by end-of-file condition + puts("End of file reached"); + else if (ferror(stdin)) // if failure caused by some other error + { + perror("getchar()"); + fprintf(stderr, "getchar() failed in file %s at line # %d\n", + __FILE__, __LINE__ - 9); + exit(EXIT_FAILURE); + } + + return EXIT_SUCCESS; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">abcde +End of file reached</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.21.7.6 The getchar function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.21.7.6 The getchar function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.7.6 The getchar function (p: 332) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.7.6 The getchar function (p: 298) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.7.6 The getchar function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fgetc" title="c/io/fgetc"> <span class="t-lines"><span>fgetc</span><span>getc</span></span></a></div> </td> <td> gets a character from a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/getchar" title="cpp/io/c/getchar">C++ documentation</a></span> for <code>getchar</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/getchar" class="_attribution-link">https://en.cppreference.com/w/c/io/getchar</a> + </p> +</div> diff --git a/devdocs/c/io%2Fgets.html b/devdocs/c/io%2Fgets.html new file mode 100644 index 00000000..3dfd399d --- /dev/null +++ b/devdocs/c/io%2Fgets.html @@ -0,0 +1,40 @@ + <h1 id="firstHeading" class="firstHeading">gets, gets_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-until-c11"> <td> <pre data-language="c">char *gets( char *str );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-until-c11">(removed in C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">char *gets_s( char *str, rsize_t n );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Reads <code><a href="std_streams" title="c/io/std streams">stdin</a></code> into the character array pointed to by <code>str</code> until a newline character is found or end-of-file occurs. A null character is written immediately after the last character read into the array. The newline character is discarded but not stored in the buffer.</div> <div class="t-li1"> +<span class="t-li">2)</span> Reads characters from <code><a href="std_streams" title="c/io/std streams">stdin</a></code> until a newline is found or end-of-file occurs. Writes only at most <code>n-1</code> characters into the array pointed to by <code>str</code>, and always writes the terminating null character (unless str is a null pointer). The newline character, if found, is discarded and does not count toward the number of characters written to the buffer. <dl> +<dd>The following errors are detected at runtime and call the currently installed <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <ul> +<li> <code>n</code> is zero </li> +<li> <code>n</code> is greater than <code>RSIZE_MAX</code> </li> +<li> <code>str</code> is a null pointer </li> +<li> endline or eof not encountered after storing <code>n-1</code> characters to the buffer. </li> +</ul> </dd> +<dd>In any case, <code>gets_s</code> first finishes reading and discarding the characters from <code><a href="std_streams" title="c/io/std streams">stdin</a></code> until new-line character, end-of-file condition, or read error before calling the constraint handler. </dd> +<dd>As with all bounds-checked functions, <code>gets_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../io" title="c/io"><code><stdio.h></code></a>.</dd> +</dl> +</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> character string to be written </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>str</code> on success, a null pointer on failure.</p> +<p>If the failure has been caused by end of file condition, additionally sets the <i>eof</i> indicator (see <code><a href="feof" title="c/io/feof">feof()</a></code>) on <code><a href="std_streams" title="c/io/std streams">stdin</a></code>. If the failure has been caused by some other error, sets the <i>error</i> indicator (see <code><a href="ferror" title="c/io/ferror">ferror()</a></code>) on <code><a href="std_streams" title="c/io/std streams">stdin</a></code>.</p> +<h3 id="Notes"> Notes</h3> <p>The <code>gets()</code> function does not perform bounds checking, therefore this function is extremely vulnerable to buffer-overflow attacks. It cannot be used safely (unless the program runs in an environment which restricts what can appear on <code>stdin</code>). For this reason, the function has been deprecated in the third corrigendum to the C99 standard and removed altogether in the C11 standard. <code><a href="fgets" title="c/io/fgets">fgets()</a></code> and <code>gets_s()</code> are the recommended replacements.</p> +<p><b>Never use <code>gets()</code>.</b></p> +<h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> K.3.5.4.1 The gets_s function (p: 602-603) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.7.7 The gets function (p: 298) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.7.7 The gets function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fscanf" title="c/io/fscanf"> <span class="t-lines"><span>scanf</span><span>fscanf</span><span>sscanf</span><span>scanf_s</span><span>fscanf_s</span><span>sscanf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads formatted input from <code><a href="std_streams" title="c/io/std streams">stdin</a></code>, a file stream or a buffer <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fgets" title="c/io/fgets"> <span class="t-lines"><span>fgets</span></span></a></div> </td> <td> gets a character string from a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fputs" title="c/io/fputs"> <span class="t-lines"><span>fputs</span></span></a></div> </td> <td> writes a character string to a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="https://en.cppreference.com/w/c/experimental/dynamic/getline" title="c/experimental/dynamic/getline"> <span class="t-lines"><span>getline</span><span>getwline</span><span>getdelim</span><span>getwdelim</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-dynamic-tr t-mark-ts">(dynamic memory TR)</span></span></span></div> </td> <td> read from a stream into an automatically resized buffer until delimiter/end of line <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/gets" title="cpp/io/c/gets">C++ documentation</a></span> for <code>gets</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/gets" class="_attribution-link">https://en.cppreference.com/w/c/io/gets</a> + </p> +</div> diff --git a/devdocs/c/io%2Fgetwchar.html b/devdocs/c/io%2Fgetwchar.html new file mode 100644 index 00000000..072a1648 --- /dev/null +++ b/devdocs/c/io%2Fgetwchar.html @@ -0,0 +1,19 @@ + <h1 id="firstHeading" class="firstHeading">getwchar</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">wint_t getwchar(void);</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Reads the next wide character from <code><a href="std_streams" title="c/io/std streams">stdin</a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <p>(none)</p> +<h3 id="Return_value"> Return value</h3> <p>the obtained wide character or <code>WEOF</code> if an error has occurred or the end of file reached</p> +<h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.3.7 The getwchar function (p: 424) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.3.7 The getwchar function (p: 369-370) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="getchar" title="c/io/getchar"> <span class="t-lines"><span>getchar</span></span></a></div> </td> <td> reads a character from <code><a href="std_streams" title="c/io/std streams">stdin</a></code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fgetwc" title="c/io/fgetwc"> <span class="t-lines"><span>fgetwc</span><span>getwc</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> gets a wide character from a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/getwchar" title="cpp/io/c/getwchar">C++ documentation</a></span> for <code>getwchar</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/getwchar" class="_attribution-link">https://en.cppreference.com/w/c/io/getwchar</a> + </p> +</div> diff --git a/devdocs/c/io%2Fperror.html b/devdocs/c/io%2Fperror.html new file mode 100644 index 00000000..914c9153 --- /dev/null +++ b/devdocs/c/io%2Fperror.html @@ -0,0 +1,36 @@ + <h1 id="firstHeading" class="firstHeading">perror</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">void perror( const char *s );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Prints a textual description of the error code currently stored in the system variable <code><a href="../error/errno" title="c/error/errno">errno</a></code> to <code><a href="std_streams" title="c/io/std streams">stderr</a></code>.</p> +<p>The description is formed by concatenating the following components:</p> +<ul> +<li> the contents of the null-terminated byte string pointed to by <code>s</code>, followed by <code>": "</code> (unless <code>s</code> is a null pointer or the character pointed to by <code>s</code> is the null character) </li> +<li> implementation-defined error message string describing the error code stored in <code>errno</code>, followed by <code>'\n'</code>. The error message string is identical to the result of <code><a href="http://en.cppreference.com/w/c/string/byte/strerror"><span class="kw574">strerror</span></a><span class="br0">(</span><span class="kw2">errno</span><span class="br0">)</span></code>. </li> +</ul> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> s </td> <td> - </td> <td> pointer to a null-terminated string with explanatory message </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +int main(void) +{ + FILE *f = fopen("non_existent", "r"); + if (f == NULL) { + perror("fopen() failed"); + } else { + fclose(f); + } +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">fopen() failed: No such file or directory</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.10.4 The perror function (p: 339) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.10.4 The perror function (p: 305) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.10.4 The perror function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../string/byte/strerror" title="c/string/byte/strerror"> <span class="t-lines"><span>strerror</span><span>strerror_s</span><span>strerrorlen_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> returns a text version of a given error code <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/perror" title="cpp/io/c/perror">C++ documentation</a></span> for <code>perror</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/perror" class="_attribution-link">https://en.cppreference.com/w/c/io/perror</a> + </p> +</div> diff --git a/devdocs/c/io%2Fputchar.html b/devdocs/c/io%2Fputchar.html new file mode 100644 index 00000000..aa070ceb --- /dev/null +++ b/devdocs/c/io%2Fputchar.html @@ -0,0 +1,57 @@ + <h1 id="firstHeading" class="firstHeading">putchar</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int putchar( int ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Writes a character <code>ch</code> to <code><a href="std_streams" title="c/io/std streams">stdout</a></code>. Internally, the character is converted to <code>unsigned char</code> just before being written.</p> +<p>Equivalent to <code><a href="http://en.cppreference.com/w/c/io/fputc"><span class="kw831">putc</span></a><span class="br0">(</span>ch, <a href="http://en.cppreference.com/w/c/io/std_streams"><span class="kw886">stdout</span></a><span class="br0">)</span></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> character to be written </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>On success, returns the written character.</p> +<p>On failure, returns <code><a href="../io" title="c/io">EOF</a></code> and sets the <i>error</i> indicator (see <code><a href="ferror" title="c/io/ferror">ferror()</a></code>) on <code><a href="std_streams" title="c/io/std streams">stdout</a></code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>Shows <code>putchar</code> with error checking</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + int ret_code = 0; + for (char c = 'a'; (ret_code != EOF) && (c != 'z'); c++) + ret_code = putchar(c); + + // Test whether EOF was reached. + if (ret_code == EOF && ferror(stdout)) + { + fprintf(stderr, "putchar() failed in file %s at line # %d\n", + __FILE__, __LINE__ - 6); + perror("putchar()"); + exit(EXIT_FAILURE); + } + putchar('\n'); + + // putchar return value is not equal to the argument + int r = 0x1070; + printf("\n0x%x\n", r); + r = putchar(r); + printf("\n0x%x\n", r); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">abcdefghijklmnopqrstuvwxy + +0x1070 +p +0x70</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.21.7.8 The putchar function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.21.7.8 The putchar function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.7.8 The putchar function (p: 333) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.7.9 The putchar function (p: 299) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.7.9 The putchar function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fputc" title="c/io/fputc"> <span class="t-lines"><span>fputc</span><span>putc</span></span></a></div> </td> <td> writes a character to a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/putchar" title="cpp/io/c/putchar">C++ documentation</a></span> for <code>putchar</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/putchar" class="_attribution-link">https://en.cppreference.com/w/c/io/putchar</a> + </p> +</div> diff --git a/devdocs/c/io%2Fputs.html b/devdocs/c/io%2Fputs.html new file mode 100644 index 00000000..40c78ddb --- /dev/null +++ b/devdocs/c/io%2Fputs.html @@ -0,0 +1,40 @@ + <h1 id="firstHeading" class="firstHeading">puts</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int puts( const char* str );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Writes every character from the null-terminated string <code>str</code> and one additional newline character <span class="st0">'<span class="es1">\n</span>'</span> to the output stream <code><a href="std_streams" title="c/io/std streams">stdout</a></code>, as if by repeatedly executing <code><a href="fputc" title="c/io/fputc">fputc</a></code>.</p> +<p>The terminating null character from <code>str</code> is not written.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> character string to be written </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>On success, returns a non-negative value.</p> +<p>On failure, returns <code><a href="../io" title="c/io">EOF</a></code> and sets the <i>error</i> indicator (see <code><a href="ferror" title="c/io/ferror">ferror()</a></code>) on <code>stream</code>.</p> +<h3 id="Notes"> Notes</h3> <p>The <code>puts</code> function appends the newline character to the output, while <code><a href="fputs" title="c/io/fputs">fputs</a></code> function does not.</p> +<p>Different implementations return different non-negative numbers: some return the last character written, some return the number of characters written (or <code><a href="../types/limits" title="c/types/limits">INT_MAX</a></code> if the string was longer than that), some simply return a non-negative constant.</p> +<p>A typical cause of failure for <code>puts</code> is running out of space on the file system, when <code><a href="std_streams" title="c/io/std streams">stdout</a></code> is redirected to a file.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +int main(void) +{ + int rc = puts("Hello World"); + + if (rc == EOF) + perror("puts()"); // POSIX requires that errno is set +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Hello World</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.21.7.9 The puts function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.21.7.9 The puts function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.7.9 The puts function (p: 333) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.7.10 The puts function (p: 299) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 7.9.7.10 The puts function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fputs" title="c/io/fputs"> <span class="t-lines"><span>fputs</span></span></a></div> </td> <td> writes a character string to a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fprintf" title="c/io/fprintf"> <span class="t-lines"><span>printf</span><span>fprintf</span><span>sprintf</span><span>snprintf</span><span>printf_s</span><span>fprintf_s</span><span>sprintf_s</span><span>snprintf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> prints formatted output to <code><a href="std_streams" title="c/io/std streams">stdout</a></code>, a file stream or a buffer <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/puts" title="cpp/io/c/puts">C++ documentation</a></span> for <code>puts</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/puts" class="_attribution-link">https://en.cppreference.com/w/c/io/puts</a> + </p> +</div> diff --git a/devdocs/c/io%2Fputwchar.html b/devdocs/c/io%2Fputwchar.html new file mode 100644 index 00000000..9c73d395 --- /dev/null +++ b/devdocs/c/io%2Fputwchar.html @@ -0,0 +1,51 @@ + <h1 id="firstHeading" class="firstHeading">putwchar</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">wint_t putwchar( wchar_t ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Writes a wide character <code>ch</code> to <code>stdout</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> wide character to be written </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>ch</code> on success, <code>WEOF</code> on failure.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <stdlib.h> +#include <wchar.h> + +int main() +{ + setlocale(LC_ALL, "en_US.utf8"); + + const wchar_t data[] = + { + L'\u2200', // Unicode name: "FOR ALL" + L'∀', + L'\n', + }; + + for (size_t t = 0; t != (sizeof data / sizeof(wchar_t)); ++t) + { + if (putwchar(data[t]) == WEOF) + { + puts("I/O error in putwchar"); + return EXIT_FAILURE; + } + } + + return EXIT_SUCCESS; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">∀∀</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.31.3.9 The putwchar function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.29.3.9 The putwchar function (p: 310) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.3.9 The putwchar function (p: 425) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.3.9 The putwchar function (p: 370) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="putchar" title="c/io/putchar"> <span class="t-lines"><span>putchar</span></span></a></div> </td> <td> writes a character to <code>stdout</code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fputwc" title="c/io/fputwc"> <span class="t-lines"><span>fputwc</span><span>putwc</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> writes a wide character to a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/putwchar" title="cpp/io/c/putwchar">C++ documentation</a></span> for <code>putwchar</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/putwchar" class="_attribution-link">https://en.cppreference.com/w/c/io/putwchar</a> + </p> +</div> diff --git a/devdocs/c/io%2Fremove.html b/devdocs/c/io%2Fremove.html new file mode 100644 index 00000000..5813a48f --- /dev/null +++ b/devdocs/c/io%2Fremove.html @@ -0,0 +1,61 @@ + <h1 id="firstHeading" class="firstHeading">remove</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int remove( const char* fname );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Deletes the file identified by character string pointed to by <code>fname</code>.</p> +<p>If the file is currently open by this or another process, the behavior of this function is implementation-defined (in particular, POSIX systems unlink the file name although the file system space is not reclaimed until the last running process closes the file; Windows does not allow the file to be deleted).</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> fname </td> <td> - </td> <td> pointer to a null-terminated string containing the path identifying the file to delete </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>0</code> upon success or non-zero value on error.</p> +<h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/remove.html">POSIX specifies</a> many additional details for the behavior of this function.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + FILE* fp = fopen("file1.txt", "w"); // create file + if (!fp) + { + perror("file1.txt"); + return EXIT_FAILURE; + } + puts("Created file1.txt"); + fclose(fp); + + int rc = remove("file1.txt"); + if (rc) + { + perror("remove"); + return EXIT_FAILURE; + } + puts("Removed file1.txt"); + + fp = fopen("file1.txt", "r"); // Failure: file does not exist + if (!fp) + perror("Opening removed file failed"); + + rc = remove("file1.txt"); // Failure: file does not exist + if (rc) + perror("Double-remove failed"); + + return EXIT_SUCCESS; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Created file1.txt +Removed file1.txt +Opening removed file failed: No such file or directory +Double-remove failed: No such file or directory</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.21.4.1 The remove function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.21.4.1 The remove function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.4.1 The remove function (p: 302) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.4.1 The remove function (p: 268) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.4.1 The remove function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="rename" title="c/io/rename"> <span class="t-lines"><span>rename</span></span></a></div> </td> <td> renames a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/remove" title="cpp/io/c/remove">C++ documentation</a></span> for <code>remove</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/remove" class="_attribution-link">https://en.cppreference.com/w/c/io/remove</a> + </p> +</div> diff --git a/devdocs/c/io%2Frename.html b/devdocs/c/io%2Frename.html new file mode 100644 index 00000000..3997966b --- /dev/null +++ b/devdocs/c/io%2Frename.html @@ -0,0 +1,59 @@ + <h1 id="firstHeading" class="firstHeading">rename</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int rename( const char* old_filename, const char* new_filename );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Changes the filename of a file. The file is identified by character string pointed to by <code>old_filename</code>. The new filename is identified by character string pointed to by <code>new_filename</code>.</p> +<p>If <code>new_filename</code> exists, the behavior is implementation-defined.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> old_filename </td> <td> - </td> <td> pointer to a null-terminated string containing the path identifying the file to rename </td> +</tr> <tr class="t-par"> <td> new_filename </td> <td> - </td> <td> pointer to a null-terminated string containing the new path of the file </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>0</code> upon success or non-zero value on error.</p> +<h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/rename.html">POSIX</a> specifies many additional details on the semantics of this function.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + FILE* fp = fopen("from.txt", "w"); // create file "from.txt" + if (!fp) + { + perror("from.txt"); + return EXIT_FAILURE; + } + fputc('a', fp); // write to "from.txt" + fclose(fp); + + int rc = rename("from.txt", "to.txt"); + if (rc) + { + perror("rename"); + return EXIT_FAILURE; + } + + fp = fopen("to.txt", "r"); + if(!fp) + { + perror("to.txt"); + return EXIT_FAILURE; + } + printf("%c\n", fgetc(fp)); // read from "to.txt" + fclose(fp); + + return EXIT_SUCCESS; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">a</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.21.4.2 The rename function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.21.4.2 The rename function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.4.2 The rename function (p: 302-303) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.4.2 The rename function (p: 268-269) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.4.2 The rename function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="remove" title="c/io/remove"> <span class="t-lines"><span>remove</span></span></a></div> </td> <td> erases a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/rename" title="cpp/io/c/rename">C++ documentation</a></span> for <code>rename</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/rename" class="_attribution-link">https://en.cppreference.com/w/c/io/rename</a> + </p> +</div> diff --git a/devdocs/c/io%2Frewind.html b/devdocs/c/io%2Frewind.html new file mode 100644 index 00000000..103aceef --- /dev/null +++ b/devdocs/c/io%2Frewind.html @@ -0,0 +1,51 @@ + <h1 id="firstHeading" class="firstHeading">rewind</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">void rewind( FILE *stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Moves the file position indicator to the beginning of the given file stream.</p> +<p>The function is equivalent to <code><a href="http://en.cppreference.com/w/c/io/fseek"><span class="kw873">fseek</span></a><span class="br0">(</span>stream, <span class="nu0">0</span>, <a href="http://en.cppreference.com/w/c/io"><span class="kw895">SEEK_SET</span></a><span class="br0">)</span><span class="sy4">;</span></code>, except that end-of-file and error indicators are cleared.</p> +<p>The function drops any effects from previous calls to <code><a href="ungetc" title="c/io/ungetc">ungetc</a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> file stream to modify </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>This example shows how to read a file twice</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> + +char str[20]; + +int main(void) +{ + FILE *f; + char ch; + + f = fopen("file.txt", "w"); + for (ch = '0'; ch <= '9'; ch++) { + fputc(ch, f); + } + fclose(f); + + f = fopen("file.txt", "r"); + fread(str, 1, 10, f); + puts(str); + + rewind(f); + fread(str, 1, 10, f); + puts(str); + fclose(f); + + return 0; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">0123456789 +0123456789</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.9.5 The rewind function (p: 338) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.9.5 The rewind function (p: 304) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.9.5 The rewind function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fseek" title="c/io/fseek"> <span class="t-lines"><span>fseek</span></span></a></div> </td> <td> moves the file position indicator to a specific location in a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/rewind" title="cpp/io/c/rewind">C++ documentation</a></span> for <code>rewind</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/rewind" class="_attribution-link">https://en.cppreference.com/w/c/io/rewind</a> + </p> +</div> diff --git a/devdocs/c/io%2Fsetbuf.html b/devdocs/c/io%2Fsetbuf.html new file mode 100644 index 00000000..fb5c4a93 --- /dev/null +++ b/devdocs/c/io%2Fsetbuf.html @@ -0,0 +1,46 @@ + <h1 id="firstHeading" class="firstHeading">setbuf</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">void setbuf( FILE *stream, char *buffer );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">void setbuf( FILE *restrict stream, char *restrict buffer );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define BUFSIZ /*unspecified*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Sets the internal buffer to use for stream operations. It should be at least <code>BUFSIZ</code> characters long.</p> +<p>If <code>buffer</code> is not null, equivalent to <code><a href="http://en.cppreference.com/w/c/io/setvbuf"><span class="kw823">setvbuf</span></a><span class="br0">(</span>stream, buffer, <a href="http://en.cppreference.com/w/c/io"><span class="kw892">_IOFBF</span></a>, <a href="http://en.cppreference.com/w/c/io"><span class="kw891">BUFSIZ</span></a><span class="br0">)</span></code>.</p> +<p>If <code>buffer</code> is null, equivalent to <code><a href="http://en.cppreference.com/w/c/io/setvbuf"><span class="kw823">setvbuf</span></a><span class="br0">(</span>stream, <a href="http://en.cppreference.com/w/c/types/NULL"><span class="kw103">NULL</span></a>, <a href="http://en.cppreference.com/w/c/io"><span class="kw894">_IONBF</span></a>, <span class="nu0">0</span><span class="br0">)</span></code>, which turns off buffering.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> the file stream to set the buffer to </td> +</tr> <tr class="t-par"> <td> buffer </td> <td> - </td> <td> pointer to a buffer for the stream to use. If a null pointer is supplied, the buffering is turned off </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>None.</p> +<h3 id="Notes"> Notes</h3> <p>If <code><a href="../io" title="c/io">BUFSIZ</a></code> is not the appropriate buffer size, <code><a href="setvbuf" title="c/io/setvbuf">setvbuf</a></code> can be used to change it.</p> +<p><code><a href="setvbuf" title="c/io/setvbuf">setvbuf</a></code> should also be used to detect errors, since <code>setbuf</code> does not indicate success or failure.</p> +<p>This function may only be used after <code>stream</code> has been associated with an open file, but before any other operation (other than a failed call to <code>setbuf</code>/<code>setvbuf</code>).</p> +<p>A common error is setting the buffer of stdin or stdout to an array whose lifetime ends before the program terminates:</p> +<div class="c source-c"><pre data-language="c">int main(void) { + char buf[BUFSIZ]; + setbuf(stdin, buf); +} // lifetime of buf ends, undefined behavior</pre></div> <h3 id="Example"> Example</h3> <div class="t-example"> +<p><code>setbuf</code> may be used to disable buffering on streams that require immediate output.</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <threads.h> + +int main(void) +{ + setbuf(stdout, NULL); // unbuffered stdout + putchar('a'); // 'a' appears immediately if stdout is unbuffered + thrd_sleep(&(struct timespec){.tv_sec=1}, NULL); // sleep 1 sec + putchar('b'); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">ab</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.21.5.5 The setbuf function (p: 225) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.5.5 The setbuf function (p: 307-308) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.5.5 The setbuf function (p: 273) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.5.5 The setbuf function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="setvbuf" title="c/io/setvbuf"> <span class="t-lines"><span>setvbuf</span></span></a></div> </td> <td> sets the buffer and its size for a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/setbuf" title="cpp/io/c/setbuf">C++ documentation</a></span> for <code>setbuf</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/setbuf" class="_attribution-link">https://en.cppreference.com/w/c/io/setbuf</a> + </p> +</div> diff --git a/devdocs/c/io%2Fsetvbuf.html b/devdocs/c/io%2Fsetvbuf.html new file mode 100644 index 00000000..25309406 --- /dev/null +++ b/devdocs/c/io%2Fsetvbuf.html @@ -0,0 +1,85 @@ + <h1 id="firstHeading" class="firstHeading">setvbuf</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">int setvbuf( FILE * stream, char * buffer, + int mode, size_t size );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int setvbuf( FILE *restrict stream, char *restrict buffer, + int mode, size_t size );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define _IOFBF /*unspecified*/ +#define _IOLBF /*unspecified*/ +#define _IONBF /*unspecified*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Changes the buffering mode of the given file stream <code>stream</code> as indicated by the argument <code>mode</code>. In addition,</p> +<ul> +<li> If <code>buffer</code> is a null pointer, resizes the internal buffer to <code>size</code>. </li> +<li> If <code>buffer</code> is not a null pointer, instructs the stream to use the user-provided buffer of size <code>size</code> beginning at <code>buffer</code>. The stream must be closed (with <code><a href="fclose" title="c/io/fclose">fclose</a></code>) before the <a href="../language/lifetime" title="c/language/lifetime">lifetime</a> of the array pointed to by <code>buffer</code> ends. The contents of the array after a successful call to <code>setvbuf</code> are indeterminate and any attempt to use it is undefined behavior. </li> +</ul> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> the file stream to set the buffer to </td> +</tr> <tr class="t-par"> <td> buffer </td> <td> - </td> <td> pointer to a buffer for the stream to use or null pointer to change size and mode only </td> +</tr> <tr class="t-par"> <td> mode </td> <td> - </td> <td> buffering mode to use. It can be one of the following values: <table class="wikitable"> <tr> <td> <a href="http://en.cppreference.com/w/c/io"><span class="kw892">_IOFBF</span></a> </td> <td> full buffering </td> +</tr> <tr> <td> <a href="http://en.cppreference.com/w/c/io"><span class="kw893">_IOLBF</span></a> </td> <td> line buffering </td> +</tr> <tr> <td> <a href="http://en.cppreference.com/w/c/io"><span class="kw894">_IONBF</span></a> </td> <td> no buffering </td> +</tr> +</table> </td> +</tr> <tr class="t-par"> <td> size </td> <td> - </td> <td> size of the buffer </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>0</code> on success or nonzero on failure.</p> +<h3 id="Notes"> Notes</h3> <p>This function may only be used after <code>stream</code> has been associated with an open file, but before any other operation (other than a failed call to <code><a href="setbuf" title="c/io/setbuf">setbuf</a></code>/<code>setvbuf</code>).</p> +<p>Not all <code>size</code> bytes will necessarily be used for buffering: the actual buffer size is usually rounded down to a multiple of 2, a multiple of page size, etc.</p> +<p>On many implementations, line buffering is only available for terminal input streams.</p> +<p>A common error is setting the buffer of stdin or stdout to an array whose lifetime ends before the program terminates:</p> +<div class="c source-c"><pre data-language="c">int main(void) { + char buf[BUFSIZ]; + setbuf(stdin, buf); +} // lifetime of buf ends, undefined behavior</pre></div> <p>The default buffer size <code><a href="../io" title="c/io">BUFSIZ</a></code> is expected to be the most efficient buffer size for file I/O on the implementation, but POSIX <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/fstat.html">fstat</a> often provides a better estimate.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>One use case for changing buffer size is when a better size is known. (This example uses some POSIX function, e.g. <a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/7908799/xsh/fileno.html"><code>fileno</code></a>. See also SO: <a rel="nofollow" class="external text" href="https://stackoverflow.com/questions/15749184/fileno-not-available">#1</a> and <a rel="nofollow" class="external text" href="https://stackoverflow.com/questions/44622827/why-am-i-getting-error-implicit-declaration-of-function-fileno-when-i-try-t">#2</a>).</p> +<div class="c source-c"><pre data-language="c">// Make some POSIX functions, such as `int fileno(FILE*)`, visible: +#define _POSIX_SOURCE + +#include <stdio.h> +#include <stdlib.h> +#include <sys/stat.h> + +int main(void) +{ + FILE* fp = fopen("/tmp/test.txt", "w+"); + if (fp == NULL) + { + perror("fopen"); + return EXIT_FAILURE; + } + + struct stat stats; + if (fstat(fileno(fp), &stats) == -1) // POSIX only + { + perror("fstat"); + return EXIT_FAILURE; + } + + printf("BUFSIZ is %d, but optimal block size is %ld\n", BUFSIZ, stats.st_blksize); + if (setvbuf(fp, NULL, _IOFBF, stats.st_blksize) != 0) + { + perror("setvbuf failed"); // POSIX version sets errno + return EXIT_FAILURE; + } + + int ch; + while((ch=fgetc(fp)) != EOF); // read entire file: use truss/strace to + // observe the read(2) syscalls used + + fclose(fp); + return EXIT_SUCCESS; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">BUFSIZ is 8192, but optimal block size is 65536</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.21.5.6 The setvbuf function (p: 225) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.5.6 The setvbuf function (p: 308) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.5.6 The setvbuf function (p: 273-274) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.5.6 The setvbuf function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="setbuf" title="c/io/setbuf"> <span class="t-lines"><span>setbuf</span></span></a></div> </td> <td> sets the buffer for a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/setvbuf" title="cpp/io/c/setvbuf">C++ documentation</a></span> for <code>setvbuf</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/setvbuf" class="_attribution-link">https://en.cppreference.com/w/c/io/setvbuf</a> + </p> +</div> diff --git a/devdocs/c/io%2Fstd_streams.html b/devdocs/c/io%2Fstd_streams.html new file mode 100644 index 00000000..be45707e --- /dev/null +++ b/devdocs/c/io%2Fstd_streams.html @@ -0,0 +1,68 @@ + <h1 id="firstHeading" class="firstHeading">stdin, stdout, stderr</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">#define stdin /* implementation-defined */</pre> +</td> <td> (1) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">#define stdout /* implementation-defined */</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">#define stderr /* implementation-defined */</pre> +</td> <td> (3) </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Three text streams are predefined. These streams are implicitly opened and unoriented at program startup.</p> +<div class="t-li1"> +<span class="t-li">1)</span> Associated with the <i>standard input</i> stream, used for reading conventional input. At program startup, the stream is fully buffered if and only if the stream can be determined to not refer to an interactive device.</div> <div class="t-li1"> +<span class="t-li">2)</span> Associated with the <i>standard output</i> stream, used for writing conventional output. At program startup, the stream is fully buffered if and only if the stream can be determined to not refer to an interactive device.</div> <div class="t-li1"> +<span class="t-li">3)</span> Associated with the <i>standard error</i> stream, used for writing diagnostic output. At program startup, the stream is not fully buffered.</div> <p>What constitutes an interactive device is implementation-defined.</p> +<p>These macros are expanded to expressions of type <code><a href="http://en.cppreference.com/w/c/io/FILE"><span class="kw884">FILE</span></a><span class="sy2">*</span></code>.</p> +<h3 id="Notes"> Notes</h3> <p>Although not mandated by POSIX, the UNIX convention is that <code>stdin</code> and <code>stdout</code> are line-buffered if associated with a terminal and <code>stderr</code> is unbuffered.</p> +<p>These macros may be expanded to modifiable lvalues. If any of these <code><a href="http://en.cppreference.com/w/c/io/FILE"><span class="kw884">FILE</span></a><span class="sy2">*</span></code> lvalue is modified, subsequent operations on the corresponding stream result in unspecified or undefined behavior.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>This example shows a function equivalent to <code><a href="fprintf" title="c/io/fprintf">printf</a></code>.</p> +<div class="c source-c"><pre data-language="c">#include <stdarg.h> +#include <stdio.h> + +int my_printf(const char * restrict fmt, ...) +{ + va_list vl; + va_start(vl, fmt); + int ret = vfprintf(stdout, fmt, vl); + va_end(vl); + return ret; +} + +int main(void) +{ + my_printf("Rounding:\t%f %.0f %.32f\n", 1.5, 1.5, 1.3); + my_printf("Padding:\t%05.2f %.2f %5.2f\n", 1.5, 1.5, 1.5); + my_printf("Scientific:\t%E %e\n", 1.5, 1.5); + my_printf("Hexadecimal:\t%a %A\n", 1.5, 1.5); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Rounding: 1.500000 2 1.30000000000000004440892098500626 +Padding: 01.50 1.50 1.50 +Scientific: 1.500000E+00 1.500000e+00 +Hexadecimal: 0x1.8p+0 0X1.8P+0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.21.1 Introduction (p: 217-218) </li> +<li> 7.21.2 Streams (p: 217-219) </li> +<li> 7.21.2 Files (p: 219-221) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.21.1 Introduction (p: 296-298) </li> +<li> 7.21.2 Streams (p: 298-299) </li> +<li> 7.21.2 Files (p: 300-302) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.19.1 Introduction (p: 262-264) </li> +<li> 7.19.2 Streams (p: 264-265) </li> +<li> 7.19.2 Files (p: 266-268) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 7.9.1 Introduction </li> +<li> 7.9.2 Streams </li> +<li> 7.9.3 Files </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="file" title="c/io/FILE"> <span class="t-lines"><span>FILE</span></span></a></div> </td> <td> object type, capable of holding all information needed to control a C I/O stream <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/std_streams" title="cpp/io/c/std streams">C++ documentation</a></span> for <code>stdin, stdout, stderr</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/std_streams" class="_attribution-link">https://en.cppreference.com/w/c/io/std_streams</a> + </p> +</div> diff --git a/devdocs/c/io%2Ftmpfile.html b/devdocs/c/io%2Ftmpfile.html new file mode 100644 index 00000000..63b7e5e7 --- /dev/null +++ b/devdocs/c/io%2Ftmpfile.html @@ -0,0 +1,62 @@ + <h1 id="firstHeading" class="firstHeading">tmpfile, tmpfile_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">FILE* tmpfile( void );</pre> +</td> <td> (1) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t tmpfile_s( FILE* restrict* restrict streamptr );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Creates and opens a temporary file. The file is opened as binary file for update (as if by <code><a href="fopen" title="c/io/fopen">fopen</a></code> with <span class="st0">"wb+"</span> mode). The filename of the file is guaranteed to be unique within the filesystem. At least <code><a href="../io" title="c/io">TMP_MAX</a></code> files may be opened during the lifetime of a program (this limit may be shared with <code><a href="tmpnam" title="c/io/tmpnam">tmpnam</a></code> and may be further limited by <code><a href="../io" title="c/io">FOPEN_MAX</a></code>).</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that at least <code>TMP_MAX_S</code> files may be opened (the limit may be shared with <code>tmpnam_s</code>), and if <code>streamptr</code> is a null pointer, the currently installed <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function is called. As with all bounds-checked functions, <code>tmpfile_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../io" title="c/io"><code><stdio.h></code></a>.</div> <p>The temporary file created by this function is closed and deleted when the program exits normally. Whether it's deleted on abnormal termination is implementation-defined.</p> +<h3 id="Parameters"> Parameters</h3> <div class="t-li1"> +<span class="t-li">1)</span> (none)</div> <div class="t-li1"> +<span class="t-li">2)</span> pointer to a pointer that will be updated by this function call</div> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> Pointer to the file stream associated with the file or null pointer if an error has occurred.</div> <div class="t-li1"> +<span class="t-li">2)</span> Zero if the file was created and open successfully, non-zero if the file was not created or open or if <code>streamptr</code> was a null pointer. In addition, pointer to the associated file stream is stored in <code>*streamptr</code> on success, and a null pointer value is stored in <code>*streamptr</code> on error.</div> <h3 id="Notes"> Notes</h3> <p>On some implementations (e.g. older Linux), this function actually creates, opens, and immediately deletes the file from the file system: as long as an open file descriptor to a deleted file is held by a program, the file exists, but since it was deleted, its name does not appear in any directory, so that no other process can open it. Once the file descriptor is closed, or once the program terminates (normally or abnormally), the space occupied by the file is reclaimed by the filesystem. Newer Linux (since 3.11 or later, depending on filesystem) creates such invisible temporary files in one step, via special flag in the <a rel="nofollow" class="external text" href="https://man7.org/linux/man-pages/man2/open.2.html"><code>open()</code></a> syscall.</p> +<p>On some implementations (e.g. Windows), elevated privileges are required as the function may create the temporary file in a system directory.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#define _POSIX_C_SOURCE 200112L +#include <stdio.h> +#include <unistd.h> + +int main(void) +{ + printf("TMP_MAX = %d, FOPEN_MAX = %d\n", TMP_MAX, FOPEN_MAX); + FILE* tmpf = tmpfile(); + fputs("Hello, world", tmpf); + rewind(tmpf); + char buf[6]; + fgets(buf, sizeof buf, tmpf); + printf("got back from the file: '%s'\n", buf); + + // Linux-specific method to display the tmpfile name + char fname[FILENAME_MAX], link[FILENAME_MAX] = {0}; + sprintf(fname, "/proc/self/fd/%d", fileno(tmpf)); + if (readlink(fname, link, sizeof link - 1) > 0) + printf("File name: %s\n", link); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">TMP_MAX = 238328, FOPEN_MAX = 16 +got back from the file: 'Hello' +File name: /tmp/tmpfjptPe5 (deleted)</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.21.4.3 The tmpfile function (p: TBD) </li> +<li> K.3.5.1.1 The tmpfile_s function (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.21.4.3 The tmpfile function (p: 222) </li> +<li> K.3.5.1.1 The tmpfile_s function (p: 427) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.21.4.3 The tmpfile function (p: 303) </li> +<li> K.3.5.1.1 The tmpfile_s function (p: 586-587) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.4.3 The tmpfile function (p: 269) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.4.3 The tmpfile function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="tmpnam" title="c/io/tmpnam"> <span class="t-lines"><span>tmpnam</span><span>tmpnam_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> returns a unique filename <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/tmpfile" title="cpp/io/c/tmpfile">C++ documentation</a></span> for <code>tmpfile</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/tmpfile" class="_attribution-link">https://en.cppreference.com/w/c/io/tmpfile</a> + </p> +</div> diff --git a/devdocs/c/io%2Ftmpnam.html b/devdocs/c/io%2Ftmpnam.html new file mode 100644 index 00000000..0285bdf5 --- /dev/null +++ b/devdocs/c/io%2Ftmpnam.html @@ -0,0 +1,83 @@ + <h1 id="firstHeading" class="firstHeading">tmpnam, tmpnam_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">char *tmpnam( char *filename );</pre> +</td> <td> (1) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t tmpnam_s(char *filename_s, rsize_t maxsize);</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define TMP_MAX /*unspecified*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">#define TMP_MAX_S /*unspecified*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define L_tmpnam /*unspecified*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">#define L_tmpnam_s /*unspecified*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Creates a unique valid file name (no longer than <code><a href="../io" title="c/io">L_tmpnam</a></code> in length) and stores it in character string pointed to by <code>filename</code>. The function is capable of generating up to <code><a href="../io" title="c/io">TMP_MAX</a></code> of unique filenames, but some or all of them may be in use in the filesystem and thus not suitable return values.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that up to <code>TMP_MAX_S</code> names may be generated, no longer than <code>L_tmpnam_s</code> in length, and the following errors are detected at runtime and call the currently installed <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> <code>filename_s</code> is a null pointer </li> +<li> <code>maxsize</code> is greater than <code>RSIZE_MAX</code> </li> +<li> <code>maxsize</code> is less than the generated file name string </li> +</ul> </dd> +<dd> As with all bounds-checked functions, <code>tmpnam_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../io" title="c/io"><code><stdio.h></code></a>.</dd> +</dl> +</div> <p><code>tmpnam</code> and <code>tmpnam_s</code> modify static state (which may be shared between these functions) and are not required to be thread-safe.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> filename </td> <td> - </td> <td> pointer to the character array capable of holding at least <code><a href="../io" title="c/io">L_tmpnam</a></code> bytes, to be used as a result buffer. If null pointer is passed, a pointer to an internal static buffer is returned. </td> +</tr> <tr class="t-par"> <td> filename_s </td> <td> - </td> <td> pointer to the character array capable of holding at least <code>L_tmpnam_s</code> bytes, to be used as a result buffer. </td> +</tr> <tr class="t-par"> <td> maxsize </td> <td> - </td> <td> maximum number of characters the function is allowed to write (typically the size of the <code>filename_s</code> array). </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> <code>filename</code> if <code>filename</code> was not a null pointer. Otherwise a pointer to an internal static buffer is returned. If no suitable filename can be generated, null pointer is returned.</div> <div class="t-li1"> +<span class="t-li">2)</span> Returns zero and writes the file name to <code>filename_s</code> on success. On error, returns non-zero and writes the null character to <code>filename_s[0]</code> (only if <code>filename_s</code> is not null and <code>maxsize</code> is not zero and is not greater than <code>RSIZE_MAX</code>).</div> <h3 id="Notes"> Notes</h3> <p>Although the names generated by <code>tmpnam</code> are difficult to guess, it is possible that a file with that name is created by another process between the moment <code>tmpnam</code> returns and the moment this program attempts to use the returned name to create a file. The standard function <code><a href="tmpfile" title="c/io/tmpfile">tmpfile</a></code> and the POSIX function <a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/mkdtemp.html"><code>mkstemp</code></a> do not have this problem (creating a unique directory using only the standard C library still requires the use of <code>tmpnam</code>).</p> +<p>POSIX systems additionally define the similarly named function <a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/tempnam.html"><code>tempnam</code></a>, which offers the choice of a directory (which defaults to the optionally defined macro <a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/stdio.h.html"><code>P_tmpdir</code></a>).</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> +#include <string.h> + +int main(void) +{ + // Note, the compiler/linker may issue a security warning, e.g. GCC: + // "warning: the use of `tmpnam' is dangerous, better use `mkstemp'" + char* name1 = tmpnam(NULL); + printf("temporary file name: %s\n", name1); + + char name2[L_tmpnam]; + if (tmpnam(name2)) + printf("temporary file name: %s\n", name2); + + // POSIX offers mkstemp. The following declaration might be + // necessary as mkstemp is absent in the standard C <stdlib.h>. + int mkstemp(char*); + + char name3[] = "/tmp/fileXXXXXX"; // at least six 'X' required ^_^ + int file_descriptor = mkstemp(name3); + if (file_descriptor != -1) + printf("temporary file name: %s\n", name3); + else + perror("mkstemp"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">temporary file name: /tmp/file90dLlR +temporary file name: /tmp/fileY9LWAg +temporary file name: /tmp/filexgv8PF</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.21.4.4 The tmpnam function (p: TBD) </li> +<li> K.3.5.1.2 The tmpnam_s function (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.21.4.4 The tmpnam function (p: 222) </li> +<li> K.3.5.1.2 The tmpnam_s function (p: 427-428) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.21.4.4 The tmpnam function (p: 303-304) </li> +<li> K.3.5.1.2 The tmpnam_s function (p: 587-588) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.4.4 The tmpnam function (p: 269-270) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.4.4 The tmpnam function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="tmpfile" title="c/io/tmpfile"> <span class="t-lines"><span>tmpfile</span><span>tmpfile_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> returns a pointer to a temporary file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/tmpnam" title="cpp/io/c/tmpnam">C++ documentation</a></span> for <code>tmpnam</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/tmpnam" class="_attribution-link">https://en.cppreference.com/w/c/io/tmpnam</a> + </p> +</div> diff --git a/devdocs/c/io%2Fungetc.html b/devdocs/c/io%2Fungetc.html new file mode 100644 index 00000000..ace91ea5 --- /dev/null +++ b/devdocs/c/io%2Fungetc.html @@ -0,0 +1,76 @@ + <h1 id="firstHeading" class="firstHeading">ungetc</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int ungetc( int ch, FILE *stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>If <code>ch</code> does not equal <code><a href="../io" title="c/io">EOF</a></code>, pushes the character <code>ch</code> (reinterpreted as <code>unsigned char</code>) into the input buffer associated with the stream <code>stream</code> in such a manner that subsequent read operation from <code>stream</code> will retrieve that character. The external device associated with the stream is not modified.</p> +<p>Stream repositioning operations <code><a href="fseek" title="c/io/fseek">fseek</a></code>, <code><a href="fsetpos" title="c/io/fsetpos">fsetpos</a></code>, and <code><a href="rewind" title="c/io/rewind">rewind</a></code> discard the effects of <code>ungetc</code>.</p> +<p>If <code>ungetc</code> is called more than once without an intervening read or repositioning, it may fail (in other words, a pushback buffer of size 1 is guaranteed, but any larger buffer is implementation-defined). If multiple successful <code>ungetc</code> were performed, read operations retrieve the pushed-back characters in reverse order of <code>ungetc</code>.</p> +<p>If <code>ch</code> equals <code><a href="../io" title="c/io">EOF</a></code>, the operation fails and the stream is not affected.</p> +<p>A successful call to <code>ungetc</code> clears the end of file status flag <code><a href="feof" title="c/io/feof">feof</a></code>.</p> +<p>A successful call to <code>ungetc</code> on a binary stream decrements the stream position indicator by one (the behavior is indeterminate if the stream position indicator was zero).</p> +<p>A successful call to <code>ungetc</code> on a text stream modifies the stream position indicator in unspecified manner but guarantees that after all pushed-back characters are retrieved with a read operation, the stream position indicator is equal to its value before <code>ungetc</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> character to be pushed into the input stream buffer </td> +</tr> <tr class="t-par"> <td> stream </td> <td> - </td> <td> file stream to put the character back to </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>On success <code>ch</code> is returned.</p> +<p>On failure <code><a href="../io" title="c/io">EOF</a></code> is returned and the given stream remains unchanged.</p> +<h3 id="Notes"> Notes</h3> <p>The size of the pushback buffer varies in practice from 4k (Linux, MacOS) to as little as 4 (Solaris) or the guaranteed minimum 1 (HPUX, AIX).</p> +<p>The apparent size of the pushback buffer may be larger if the character that is pushed back equals the character existing at that location in the external character sequence (the implementation may simply decrement the read file position indicator and avoid maintaining a pushback buffer).</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>demonstrates the original purpose of <code>ungetc</code>: implementation of <code><a href="fscanf" title="c/io/fscanf">scanf</a></code></p> +<div class="c source-c"><pre data-language="c">#include <ctype.h> +#include <stdio.h> + +void demo_scanf(const char* fmt, FILE* s) +{ + while (*fmt != '\0') { + if (*fmt == '%') { + int c; + switch (*++fmt) { + case 'u': + while (isspace(c=getc(s))) {} + unsigned int num = 0; + while (isdigit(c)) { + num = num*10 + c-'0'; + c = getc(s); + } + printf("%%u scanned %u\n", num); + ungetc(c, s); + break; + case 'c': + c = getc(s); + printf("%%c scanned '%c'\n", c); + break; + } + } else { + ++fmt; + } + } +} + +int main(void) +{ + FILE* f = fopen("input.txt", "w+"); + if (f != NULL) { + fputs("123x", f); + rewind(f); + demo_scanf("%u%c", f); + fclose(f); + } + return 0; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">%u scanned 123 +%c scanned 'x'</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.21.7.10 The ungetc function (p: 243) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.7.10 The ungetc function (p: 334) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.7.11 The ungetc function (p: 300) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.7.11 The ungetc function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fgetc" title="c/io/fgetc"> <span class="t-lines"><span>fgetc</span><span>getc</span></span></a></div> </td> <td> gets a character from a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/ungetc" title="cpp/io/c/ungetc">C++ documentation</a></span> for <code>ungetc</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/ungetc" class="_attribution-link">https://en.cppreference.com/w/c/io/ungetc</a> + </p> +</div> diff --git a/devdocs/c/io%2Fungetwc.html b/devdocs/c/io%2Fungetwc.html new file mode 100644 index 00000000..88d39fd7 --- /dev/null +++ b/devdocs/c/io%2Fungetwc.html @@ -0,0 +1,27 @@ + <h1 id="firstHeading" class="firstHeading">ungetwc</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">wint_t ungetwc( wint_t ch, FILE *stream );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>If <code>ch</code> does not equal <code>WEOF</code>, pushes the wide character <code>ch</code> into the input buffer associated with the stream <code>stream</code> in such a manner that subsequent read operation from <code>stream</code> will retrieve that wide character. The external device associated with the stream is not modified.</p> +<p>Stream repositioning operations <code><a href="fseek" title="c/io/fseek">fseek</a></code>, <code><a href="fsetpos" title="c/io/fsetpos">fsetpos</a></code>, and <code><a href="rewind" title="c/io/rewind">rewind</a></code> discard the effects of <code>ungetwc</code>.</p> +<p>If <code>ungetwc</code> is called more than once without an intervening read or repositioning, it may fail (in other words, a pushback buffer of size 1 is guaranteed, but any larger buffer is implementation-defined). If multiple successful <code>ungetwc</code> were performed, read operations retrieve the pushed-back wide characters in reverse order of <code>ungetwc</code></p> +<p>If <code>ch</code> equals <code>WEOF</code>, the operation fails and the stream is not affected.</p> +<p>A successful call to <code>ungetwc</code> clears the end of file status flag <code><a href="feof" title="c/io/feof">feof</a></code>.</p> +<p>A successful call to <code>ungetwc</code> on a stream (whether text or binary) modifies the stream position indicator in unspecified manner but guarantees that after all pushed-back wide characters are retrieved with a read operation, the stream position indicator is equal to its value before <code>ungetwc</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> wide character to be put back </td> +</tr> <tr class="t-par"> <td> stream </td> <td> - </td> <td> file stream to put the wide character back to </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>On success <code>ch</code> is returned.</p> +<p>On failure <code>WEOF</code> is returned and the given stream remains unchanged.</p> +<h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.3.10 The ungetwc function (p: 425-426) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.3.10 The ungetwc function (p: 370-371) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="ungetc" title="c/io/ungetc"> <span class="t-lines"><span>ungetc</span></span></a></div> </td> <td> puts a character back into a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fgetwc" title="c/io/fgetwc"> <span class="t-lines"><span>fgetwc</span><span>getwc</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> gets a wide character from a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/ungetwc" title="cpp/io/c/ungetwc">C++ documentation</a></span> for <code>ungetwc</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/ungetwc" class="_attribution-link">https://en.cppreference.com/w/c/io/ungetwc</a> + </p> +</div> diff --git a/devdocs/c/io%2Fvfprintf.html b/devdocs/c/io%2Fvfprintf.html new file mode 100644 index 00000000..923d109e --- /dev/null +++ b/devdocs/c/io%2Fvfprintf.html @@ -0,0 +1,242 @@ + <h1 id="firstHeading" class="firstHeading">vprintf, vfprintf, vsprintf, vsnprintf, vprintf_s, vfprintf_s, vsprintf_s, vsnprintf_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">int vprintf( const char *format, va_list vlist );</pre> +</td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int vprintf( const char *restrict format, va_list vlist );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(2)</td> <td></td> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">int vfprintf( FILE *stream, const char *format, va_list vlist );</pre> +</td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int vfprintf( FILE *restrict stream, const char *restrict format, + va_list vlist );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(3)</td> <td></td> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">int vsprintf( char *buffer, const char *format, va_list vlist );</pre> +</td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int vsprintf( char *restrict buffer, const char *restrict format, + va_list vlist );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int vsnprintf( char *restrict buffer, size_t bufsz, + const char *restrict format, va_list vlist );</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int vprintf_s( const char *restrict format, va_list vlist );</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int vfprintf_s( FILE *restrict stream, const char *restrict format, + va_list vlist );</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int vsprintf_s( char *restrict buffer, rsize_t bufsz, + const char *restrict format, va_list vlist );</pre> +</td> <td> (7) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int vsnprintf_s( char *restrict buffer, rsize_t bufsz, + const char *restrict format, va_list vlist );</pre> +</td> <td> (8) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Loads the data from the locations, defined by <code>vlist</code>, converts them to character string equivalents and writes the results to a variety of sinks.</p> +<div class="t-li1"> +<span class="t-li">1)</span> Writes the results to <code><a href="std_streams" title="c/io/std streams">stdout</a></code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Writes the results to a file stream <code>stream</code>.</div> <div class="t-li1"> +<span class="t-li">3)</span> Writes the results to a character string <code>buffer</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Writes the results to a character string <code>buffer</code>. At most <code>bufsz - 1</code> characters are written. The resulting character string will be terminated with a null character, unless <code>bufsz</code> is zero. If <code>bufsz</code> is zero, nothing is written and <code>buffer</code> may be a null pointer, however the return value (number of bytes that would be written not including the null terminator) is still calculated and returned.</div> <div class="t-li1"> +<span class="t-li">5-8)</span> Same as <span class="t-v">(1-4)</span>, except that the following errors are detected at runtime and call the currently installed <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <ul> +<li> the conversion specifier <code>%n</code> is present in <code>format</code> </li> +<li> any of the arguments corresponding to <code>%s</code> is a null pointer </li> +<li> <code>format</code> or <code>buffer</code> is a null pointer </li> +<li> <code>bufsz</code> is zero or greater than <code>RSIZE_MAX</code> </li> +<li> encoding errors occur in any of string and character conversion specifiers </li> +<li> (for <code>vsprintf_s</code> only), the string to be stored in <code>buffer</code> (including the trailing null)) would be exceed <code>bufsz</code> </li> +</ul> As with all bounds-checked functions, <code>vprintf_s</code> , <code>vfprintf_s</code>, <code>vsprintf_s</code>, and <code>vsnprintf_s</code> are only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../io" title="c/io"><code><stdio.h></code></a>.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> output file stream to write to </td> +</tr> <tr class="t-par"> <td> buffer </td> <td> - </td> <td> pointer to a character string to write to </td> +</tr> <tr class="t-par"> <td> bufsz </td> <td> - </td> <td> up to bufsz - 1 characters may be written, plus the null terminator </td> +</tr> <tr class="t-par"> <td> format </td> <td> - </td> <td> pointer to a null-terminated character string specifying how to interpret the data </td> +</tr> <tr class="t-par"> <td> vlist </td> <td> - </td> <td> variable argument list containing the data to print. </td> +</tr> +</table> <p><br> The <b>format</b> string consists of ordinary byte characters (except <code>%</code>), which are copied unchanged into the output stream, and conversion specifications. Each conversion specification has the following format:</p> +<ul> +<li> introductory <code>%</code> character. </li> +<li> <span class="t-mark">(optional)</span> one or more flags that modify the behavior of the conversion: </li> +<ul> +<li> <code>-</code>: the result of the conversion is left-justified within the field (by default it is right-justified). </li> +<li> <code>+</code>: the sign of signed conversions is always prepended to the result of the conversion (by default the result is preceded by minus only when it is negative). </li> +<li> <i>space</i>: if the result of a signed conversion does not start with a sign character, or is empty, space is prepended to the result. It is ignored if <code>+</code> flag is present. </li> +<li> <code>#</code>: <i>alternative form</i> of the conversion is performed. See the table below for exact effects otherwise the behavior is undefined. </li> +<li> <code>0</code>: for integer and floating point number conversions, leading zeros are used to pad the field instead of <i>space</i> characters. For integer numbers it is ignored if the precision is explicitly specified. For other conversions using this flag results in undefined behavior. It is ignored if <code>-</code> flag is present. </li> +</ul> +<li> <span class="t-mark">(optional)</span> integer value or <code>*</code> that specifies minimum field width. The result is padded with <i>space</i> characters (by default), if required, on the left when right-justified, or on the right if left-justified. In the case when <code>*</code> is used, the width is specified by an additional argument of type <code>int</code>, which appears before the argument to be converted and the argument supplying precision if one is supplied. If the value of the argument is negative, it results with the <code>-</code> flag specified and positive field width (Note: This is the minimum width: The value is never truncated.). </li> +<ul> +<li> <span class="t-mark">(optional)</span> <code>.</code> followed by integer number or <code>*</code>, or neither that specifies <i>precision</i> of the conversion. In the case when <code>*</code> is used, the <i>precision</i> is specified by an additional argument of type <code>int</code>, which appears before the argument to be converted, but after the argument supplying minimum field width if one is supplied. If the value of this argument is negative, it is ignored. If neither a number nor <code>*</code> is used, the precision is taken as zero. See the table below for exact effects of <i>precision</i>. </li> +<li> <span class="t-mark">(optional)</span> <i>length modifier</i> that specifies the size of the argument (in combination with the conversion format specifier, it specifies the type of the corresponding argument). </li> +<li> conversion format specifier. </li> +</ul> +</ul> <p>The following format specifiers are available:</p> +<table class="wikitable"> <tr> <th rowspan="1">Conversion<br>Specifier </th> <th rowspan="1">Explanation </th> <th colspan="9">Expected<br>Argument Type </th> +</tr> <tr> <th colspan="2"> +<b>Length<br>Modifier</b><b>→</b> </th> <th> +<code>hh</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>h</code> </th> <th>(none) </th> <th> +<code>l</code> </th> <th> +<code>ll</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>j</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>z</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>t</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>L</code> </th> +</tr> <tr> <th> +<code>%</code> </th> <td>Writes literal <code>%</code>. The full conversion specification must be <code>%%</code>. </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>c</code> </th> <td> Writes a <b>single character</b>. <p>The argument is first converted to <code>unsigned char</code>. If the <b>l</b> modifier is used, the argument is first converted to a character string as if by <b>%ls</b> with a <code>wchar_t[2]</code> argument.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<div><code>int</code></div> </td> <td> +<div><code>wint_t</code></div> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>s</code> </th> <td> Writes a <b>character string</b> <p>The argument must be a pointer to the initial element of an array of characters. <i>Precision</i> specifies the maximum number of bytes to be written. If <i>Precision</i> is not specified, writes every byte up to and not including the first null terminator. If the <b>l</b> specifier is used, the argument must be a pointer to the initial element of an array of <code>wchar_t</code>, which is converted to char array as if by a call to <code><a href="../string/multibyte/wcrtomb" title="c/string/multibyte/wcrtomb">wcrtomb</a></code> with zero-initialized conversion state.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<div><code>char*</code></div> </td> <td> +<div><code>wchar_t*</code></div> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>d</code><br><code>i</code> </th> <td> Converts a <b>signed integer</b> into decimal representation <i>[-]dddd</i>. <p><i>Precision</i> specifies the minimum number of digits to appear. The default precision is <code>1</code>.<br><br> If both the converted value and the precision are <code>0</code> the conversion results in no characters.<br><br></p> +</td> <td rowspan="1"> +<div><code>signed char</code></div> </td> <td rowspan="1"> +<div><code>short</code></div> </td> <td rowspan="1"> +<div><code>int</code></div> </td> <td rowspan="1"> +<div><code>long</code></div> </td> <td rowspan="1"> +<div><code>long long</code></div> </td> <td rowspan="1"> +<div><code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw118">intmax_t</span></a></code></div> </td> <td rowspan="1"> +<div>signed <code><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a></code> +</div> </td> <td rowspan="1"> +<div><code><a href="http://en.cppreference.com/w/c/types/ptrdiff_t"><span class="kw101">ptrdiff_t</span></a></code></div> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>o</code> </th> <td> Converts an <b>unsigned integer</b> into octal representation <i>oooo</i>. <p><i>Precision</i> specifies the minimum number of digits to appear. The default precision is <code>1</code>. If both the converted value and the precision are <code>0</code> the conversion results in no characters. In the <i>alternative implementation</i> precision is increased if necessary, to write one leading zero. In that case if both the converted value and the precision are <code>0</code>, single <code>0</code> is written.</p> +</td> <td rowspan="3"> +<div><code>unsigned char</code></div> </td> <td rowspan="3"> +<div><code>unsigned short</code></div> </td> <td rowspan="3"> +<div><code>unsigned int</code></div> </td> <td rowspan="3"> +<div><code>unsigned long</code></div> </td> <td rowspan="3"> +<div><code>unsigned long long</code></div> </td> <td rowspan="3"> +<div><code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw132">uintmax_t</span></a></code></div> </td> <td rowspan="3"> +<div><code><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a></code></div> </td> <td rowspan="3"> +<div>unsigned version of <code><a href="http://en.cppreference.com/w/c/types/ptrdiff_t"><span class="kw101">ptrdiff_t</span></a></code> +</div> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>x</code><br><code>X</code> </th> <td> Converts an <b>unsigned integer</b> into hexadecimal representation <i>hhhh</i>. <p>For the <code>x</code> conversion letters <code>abcdef</code> are used.<br> For the <code>X</code> conversion letters <code>ABCDEF</code> are used.<br> <i>Precision</i> specifies the minimum number of digits to appear. The default precision is <code>1</code>. If both the converted value and the precision are <code>0</code> the conversion results in no characters. In the <i>alternative implementation</i> <code>0x</code> or <code>0X</code> is prefixed to results if the converted value is nonzero.</p> +</td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>u</code> </th> <td> Converts an <b>unsigned integer</b> into decimal representation <i>dddd</i>. <p><i>Precision</i> specifies the minimum number of digits to appear. The default precision is <code>1</code>. If both the converted value and the precision are <code>0</code> the conversion results in no characters.</p> +</td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>f</code><br><code>F</code> </th> <td> Converts <b>floating-point number</b> to the decimal notation in the style <i>[-]ddd.ddd</i>. <p><i>Precision</i> specifies the exact number of digits to appear after the decimal point character. The default precision is <code>6</code>. In the <i>alternative implementation</i> decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td rowspan="4"> +<div><code>double</code></div> </td> <td rowspan="4"> +<div> +<code>double</code><span class="t-mark-rev t-since-c99">(C99)</span> +</div> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td rowspan="4"> +<div><code>long double</code></div> </td> +</tr> <tr> <th> +<code>e</code><br><code>E</code> </th> <td> Converts <b>floating-point number</b> to the decimal exponent notation. <p>For the <code>e</code> conversion style <i>[-]d.ddd</i><code>e</code><i>±dd</i> is used.<br> For the <code>E</code> conversion style <i>[-]d.ddd</i><code>E</code><i>±dd</i> is used.<br> The exponent contains at least two digits, more digits are used only if necessary. If the value is <code>0</code>, the exponent is also <code>0</code>. <i>Precision</i> specifies the exact number of digits to appear after the decimal point character. The default precision is <code>6</code>. In the <i>alternative implementation</i> decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>a</code><br><code>A</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <td> Converts <b>floating-point number</b> to the hexadecimal exponent notation. <p>For the <code>a</code> conversion style <i>[-]</i><code>0x</code><i>h.hhh</i><code>p</code><i>±d</i> is used.<br> For the <code>A</code> conversion style <i>[-]</i><code>0X</code><i>h.hhh</i><code>P</code><i>±d</i> is used.<br> The first hexadecimal digit is not <code>0</code> if the argument is a normalized floating point value. If the value is <code>0</code>, the exponent is also <code>0</code>. <i>Precision</i> specifies the exact number of digits to appear after the hexadecimal point character. The default precision is sufficient for exact representation of the value. In the <i>alternative implementation</i> decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>g</code><br><code>G</code> </th> <td> Converts <b>floating-point number</b> to decimal or decimal exponent notation depending on the value and the <i>precision</i>. <p>For the <code>g</code> conversion style conversion with style <code>e</code> or <code>f</code> will be performed.<br> For the <code>G</code> conversion style conversion with style <code>E</code> or <code>F</code> will be performed.<br> Let <code>P</code> equal the precision if nonzero, <code>6</code> if the precision is not specified, or <code>1</code> if the precision is <code>0</code>. Then, if a conversion with style <code>E</code> would have an exponent of <code>X</code>:</p> +<ul> +<li> if <i>P > X ≥ −4</i>, the conversion is with style <code>f</code> or <code>F</code> and precision <i>P − 1 − X</i>. </li> +<li> otherwise, the conversion is with style <code>e</code> or <code>E</code> and precision <i>P − 1</i>. </li> +</ul> <p>Unless <i>alternative representation</i> is requested the trailing zeros are removed, also the decimal point character is removed if no fractional part is left. For infinity and not-a-number conversion style see notes.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>n</code> </th> <td> Returns the <b>number of characters written</b> so far by this call to the function. <p>The result is <i>written</i> to the value pointed to by the argument. The specification may not contain any <i>flag</i>, <i>field width</i>, or <i>precision</i>.<br><br><br><br></p> +</td> <td> +<div><code>signed char*</code></div> </td> <td> +<div><code>short*</code></div> </td> <td> +<div><code>int*</code></div> </td> <td> +<div><code>long*</code></div> </td> <td> +<div><code>long long*</code></div> </td> <td> +<div><code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw118">intmax_t</span></a><span class="sy2">*</span></code></div> </td> <td> +<div>signed <code><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="sy2">*</span></code> +</div> </td> <td> +<div><code><a href="http://en.cppreference.com/w/c/types/ptrdiff_t"><span class="kw101">ptrdiff_t</span></a><span class="sy2">*</span></code></div> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>p</code> </th> <td>Writes an implementation defined character sequence defining a <b>pointer</b>. </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<code>void*</code> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> +</table> <p>The floating point conversion functions convert infinity to <code>inf</code> or <code>infinity</code>. Which one is used is implementation defined.</p> +<p>Not-a-number is converted to <code>nan</code> or <code>nan(<i>char_sequence</i>)</code>. Which one is used is implementation defined.</p> +<p>The conversions <code>F</code>, <code>E</code>, <code>G</code>, <code>A</code> output <code>INF</code>, <code>INFINITY</code>, <code>NAN</code> instead.</p> +<p>Even though <code>%c</code> expects <code>int</code> argument, it is safe to pass a <code>char</code> because of the integer promotion that takes place when a variadic function is called.</p> +<p>The correct conversion specifications for the fixed-width character types (<code><a href="../types/integer" title="c/types/integer">int8_t</a></code>, etc) are defined in the header <a href="../types/integer" title="c/types/integer"><code><inttypes.h></code></a> (although <code><a href="../types/integer" title="c/types/integer">PRIdMAX</a></code>, <code><a href="../types/integer" title="c/types/integer">PRIuMAX</a></code>, etc is synonymous with <code>%jd</code>, <code>%ju</code>, etc).</p> +<p>The memory-writing conversion specifier <code>%n</code> is a common target of security exploits where format strings depend on user input and is not supported by the bounds-checked <code>printf_s</code> family of functions.</p> +<p>There is a <a href="../language/eval_order" title="c/language/eval order">sequence point</a> after the action of each conversion specifier; this permits storing multiple <code>%n</code> results in the same variable or, as an edge case, printing a string modified by an earlier <code>%n</code> within the same call.</p> +<p>If a conversion specification is invalid, the behavior is undefined.</p> +<h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1-3)</span> The number of characters written if successful or negative value if an error occurred.</div> <div class="t-li1"> +<span class="t-li">4)</span> The number of characters written if successful or negative value if an error occurred. If the resulting string gets truncated due to <code>buf_size</code> limit, function returns the total number of characters (not including the terminating null-byte) which would have been written, if the limit was not imposed. </div> <div class="t-li1"> +<span class="t-li">5,6)</span> number of characters transmitted to the output stream or negative value if an output error, a runtime constrants violation error, or an encoding error occurred.</div> <div class="t-li1"> +<span class="t-li">7)</span> number of characters written to <code>buffer</code>, not counting the null character (which is always written as long as <code>buffer</code> is not a null pointer and <code>bufsz</code> is not zero and not greater than <code>RSIZE_MAX</code>), or zero on runtime constraint violations, and negative value on encoding errors</div> <div class="t-li1"> +<span class="t-li">8)</span> number of characters not including the terminating null character (which is always written as long as <code>buffer</code> is not a null pointer and <code>bufsz</code> is not zero and not greater than <code>RSIZE_MAX</code>), which would have been written to <code>buffer</code> if <code>bufsz</code> was ignored, or a negative value if a runtime constraints violation or an encoding error occurred</div> <h3 id="Notes"> Notes</h3> <p>All these functions invoke <code>va_arg</code> at least once, the value of <code>arg</code> is indeterminate after the return. These functions do not invoke <code>va_end</code>, and it must be done by the caller.</p> +<p><code>vsnprintf_s</code>, unlike <code>vsprintf_s</code>, will truncate the result to fit within the array pointed to by <code>buffer</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdarg.h> +#include <time.h> + +void debug_log(const char *fmt, ...) +{ + struct timespec ts; + timespec_get(&ts, TIME_UTC); + char time_buf[100]; + size_t rc = strftime(time_buf, sizeof time_buf, "%D %T", gmtime(&ts.tv_sec)); + snprintf(time_buf + rc, sizeof time_buf - rc, ".%06ld UTC", ts.tv_nsec / 1000); + + va_list args1; + va_start(args1, fmt); + va_list args2; + va_copy(args2, args1); + char buf[1+vsnprintf(NULL, 0, fmt, args1)]; + va_end(args1); + vsnprintf(buf, sizeof buf, fmt, args2); + va_end(args2); + + printf("%s [debug]: %s\n", time_buf, buf); +} + +int main(void) +{ + debug_log("Logging, %d, %d, %d", 1, 2, 3); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">02/20/15 21:58:09.072683 UTC [debug]: Logging, 1, 2, 3</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.21.6.8 The vfprintf function (p: 238) </li> +<li> 7.21.6.10 The vprintf function (p: 239) </li> +<li> 7.21.6.12 The vsnprintf function (p: 239-240) </li> +<li> 7.21.6.13 The vsprintf function (p: 240) </li> +<li> K.3.5.3.8 The vfprintf_s function (p: 434) </li> +<li> K.3.5.3.10 The vprintf_s function (p: 435) </li> +<li> K.3.5.3.12 The vsnprintf_s function (p: 436-437) </li> +<li> K.3.5.3.13 The vsprintf_s function (p: 437) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.21.6.8 The vfprintf function (p: 326-327) </li> +<li> 7.21.6.10 The vprintf function (p: 328) </li> +<li> 7.21.6.12 The vsnprintf function (p: 329) </li> +<li> 7.21.6.13 The vsprintf function (p: 329) </li> +<li> K.3.5.3.8 The vfprintf_s function (p: 597) </li> +<li> K.3.5.3.10 The vprintf_s function (p: 598-599) </li> +<li> K.3.5.3.12 The vsnprintf_s function (p: 600) </li> +<li> K.3.5.3.13 The vsprintf_s function (p: 601) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.19.6.8 The vfprintf function (p: 292) </li> +<li> 7.19.6.10 The vprintf function (p: 293) </li> +<li> 7.19.6.12 The vsnprintf function (p: 294) </li> +<li> 7.19.6.13 The vsprintf function (p: 295) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 4.9.6.7 The vfprintf function </li> +<li> 4.9.6.8 The vprintf function </li> +<li> 4.9.6.9 The vsprintf function </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="vfwprintf" title="c/io/vfwprintf"> <span class="t-lines"><span>vwprintf</span><span>vfwprintf</span><span>vswprintf</span><span>vwprintf_s</span><span>vfwprintf_s</span><span>vswprintf_s</span><span>vsnwprintf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> prints formatted wide character output to <code><a href="std_streams" title="c/io/std streams">stdout</a></code>, a file stream<br> or a buffer using variable argument list <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fprintf" title="c/io/fprintf"> <span class="t-lines"><span>printf</span><span>fprintf</span><span>sprintf</span><span>snprintf</span><span>printf_s</span><span>fprintf_s</span><span>sprintf_s</span><span>snprintf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> prints formatted output to <code><a href="std_streams" title="c/io/std streams">stdout</a></code>, a file stream or a buffer <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="vfscanf" title="c/io/vfscanf"> <span class="t-lines"><span>vscanf</span><span>vfscanf</span><span>vsscanf</span><span>vscanf_s</span><span>vfscanf_s</span><span>vsscanf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads formatted input from <code><a href="std_streams" title="c/io/std streams">stdin</a></code>, a file stream or a buffer<br> using variable argument list <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/vfprintf" title="cpp/io/c/vfprintf">C++ documentation</a></span> for <code>vprintf, vfprintf, vsprintf, vsnprintf</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/vfprintf" class="_attribution-link">https://en.cppreference.com/w/c/io/vfprintf</a> + </p> +</div> diff --git a/devdocs/c/io%2Fvfscanf.html b/devdocs/c/io%2Fvfscanf.html new file mode 100644 index 00000000..04e4f6b8 --- /dev/null +++ b/devdocs/c/io%2Fvfscanf.html @@ -0,0 +1,191 @@ + <h1 id="firstHeading" class="firstHeading">vscanf, vfscanf, vsscanf, vscanf_s, vfscanf_s, vsscanf_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int vscanf( const char *restrict format, va_list vlist );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int vfscanf( FILE *restrict stream, const char *restrict format, + va_list vlist );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int vsscanf( const char *restrict buffer, const char *restrict format, + va_list vlist );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int vscanf_s(const char *restrict format, va_list vlist);</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int vfscanf_s( FILE *restrict stream, const char *restrict format, + va_list vlist);</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int vsscanf_s( const char *restrict buffer, const char *restrict format, + va_list vlist);</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Reads data from the a variety of sources, interprets it according to <code>format</code> and stores the results into locations defined by <code>vlist</code>.</p> +<div class="t-li1"> +<span class="t-li">1)</span> Reads the data from <code><a href="std_streams" title="c/io/std streams">stdin</a></code> +</div> <div class="t-li1"> +<span class="t-li">2)</span> Reads the data from file stream <code>stream</code> +</div> <div class="t-li1"> +<span class="t-li">3)</span> Reads the data from null-terminated character string <code>buffer</code>. Reaching the end of the string is equivalent to reaching the end-of-file condition for <code>fscanf</code> +</div> <div class="t-li1"> +<span class="t-li">4-6)</span> Same as <span class="t-v">(1-3)</span>, except that <code>%c</code>, <code>%s</code>, and <code>%[</code> conversion specifiers each expect two arguments (the usual pointer and a value of type <code>rsize_t</code> indicating the size of the receiving array, which may be 1 when reading with a %c into a single char) and except that the following errors are detected at runtime and call the currently installed <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> any of the arguments of pointer type is a null pointer </li> +<li> <code>format</code>, <code>stream</code>, or <code>buffer</code> is a null pointer </li> +<li> the number of characters that would be written by %c, %s, or %[, plus the terminating null character, would exceed the second (rsize_t) argument provided for each of those conversion specifiers </li> +<li> optionally, any other detectable error, such as unknown conversion specifier </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>vscanf_s</code> , <code>vfscanf_s</code>, and <code>vsscanf_s</code> are only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../io" title="c/io"><code><stdio.h></code></a>.</dd> +</dl> +</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> input file stream to read from </td> +</tr> <tr class="t-par"> <td> buffer </td> <td> - </td> <td> pointer to a null-terminated character string to read from </td> +</tr> <tr class="t-par"> <td> format </td> <td> - </td> <td> pointer to a null-terminated character string specifying how to read the input </td> +</tr> <tr class="t-par"> <td> vlist </td> <td> - </td> <td> variable argument list containing the receiving arguments. </td> +</tr> +</table> <p><br> The <b>format</b> string consists of</p> +<ul> +<li> non-whitespace multibyte characters except <code>%</code>: each such character in the format string consumes exactly one identical character from the input stream, or causes the function to fail if the next character on the stream does not compare equal. </li> +<li> whitespace characters: any single whitespace character in the format string consumes all available consecutive whitespace characters from the input (determined as if by calling <a href="../string/byte/isspace" title="c/string/byte/isspace"><code>isspace</code></a> in a loop). Note that there is no difference between <code>"\n"</code>, <code>" "</code>, <code>"\t\t"</code>, or other whitespace in the format string. </li> +<li> conversion specifications. Each conversion specification has the following format: </li> +<ul> +<li> introductory <code>%</code> character. </li> +<li> <span class="t-mark">(optional)</span> assignment-suppressing character <code>*</code>. If this option is present, the function does not assign the result of the conversion to any receiving argument. </li> +<li> <span class="t-mark">(optional)</span> integer number (greater than zero) that specifies <i>maximum field width</i>, that is, the maximum number of characters that the function is allowed to consume when doing the conversion specified by the current conversion specification. Note that <code>%s</code> and <code>%[</code> may lead to buffer overflow if the width is not provided. </li> +<li> <span class="t-mark">(optional)</span> <i>length modifier</i> that specifies the size of the receiving argument, that is, the actual destination type. This affects the conversion accuracy and overflow rules. The default destination type is different for each conversion type (see table below). </li> +<li> conversion format specifier. </li> +</ul> +</ul> <p>The following format specifiers are available:</p> +<table class="wikitable"> <tr> <th rowspan="1">Conversion<br>specifier </th> <th rowspan="1">Explanation </th> <th colspan="9">Argument type </th> +</tr> <tr> <th colspan="2"> +<b>Length modifier →</b> </th> <th> +<code>hh</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>h</code> </th> <th>(none) </th> <th> +<code>l</code> </th> <th> +<code>ll</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>j</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>z</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>t</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>L</code> </th> +</tr> <tr> <th> +<code>%</code> </th> <td>Matches literal <code>%</code>. </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>c</code> </th> <td> Matches a <b>character</b> or a sequence of <b>characters</b>. <p>If a width specifier is used, matches exactly <i>width</i> characters (the argument must be a pointer to an array with sufficient room). Unlike %s and %[, does not append the null character to the array.</p> +</td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3"> +<div><code>char*</code></div> </td> <td rowspan="3"> +<div><code>wchar_t*</code></div> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>s</code> </th> <td> Matches a sequence of non-whitespace characters (a <b>string</b>). <p>If width specifier is used, matches up to <i>width</i> or until the first whitespace character, whichever appears first. Always stores a null character in addition to the characters matched (so the argument array must have room for at least <i>width+1</i> characters)</p> +</td> +</tr> <tr> <th> +<code>[</code><span class="t-spar">set</span><code>]</code> </th> <td> Matches a non-empty sequence of character from <span class="t-spar">set</span> of characters. <p>If the first character of the set is <code>^</code>, then all characters not in the set are matched. If the set begins with <code>]</code> or <code>^]</code> then the <code>]</code> character is also included into the set. It is implementation-defined whether the character <code>-</code> in the non-initial position in the scanset may be indicating a range, as in <code>[0-9]</code>. If width specifier is used, matches only up to <i>width</i>. Always stores a null character in addition to the characters matched (so the argument array must have room for at least <i>width+1</i> characters)</p> +</td> +</tr> <tr> <th> +<code>d</code> </th> <td> Matches a <b>decimal integer</b>. <p>The format of the number is the same as expected by <a href="../string/byte/strtol" title="c/string/byte/strtol"><code>strtol</code></a> with the value <code>10</code> for the <code>base</code> argument</p> +</td> <td rowspan="6"> +<div> +<code>signed char*</code> or <code>unsigned char*</code> +</div> </td> <td rowspan="6"> +<div> +<code>signed short*</code> or <code>unsigned short*</code> +</div> </td> <td rowspan="6"> +<div> +<code>signed int*</code> or <code>unsigned int*</code> +</div> </td> <td rowspan="6"> +<div> +<code>signed long*</code> or <code>unsigned long*</code> +</div> </td> <td rowspan="6"> +<div> +<code>signed long long*</code> or <code>unsigned long long*</code> +</div> </td> <td rowspan="6"> +<div> +<code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw118">intmax_t</span></a><span class="sy2">*</span></code> or <code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw132">uintmax_t</span></a><span class="sy2">*</span></code> +</div> </td> <td rowspan="6"> +<div><code><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="sy2">*</span></code></div> </td> <td rowspan="6"> +<div><code><a href="http://en.cppreference.com/w/c/types/ptrdiff_t"><span class="kw101">ptrdiff_t</span></a><span class="sy2">*</span></code></div> </td> <td rowspan="6" class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>i</code> </th> <td> Matches an <b>integer</b>. <p>The format of the number is the same as expected by <a href="../string/byte/strtol" title="c/string/byte/strtol"><code>strtol</code></a> with the value <code>0</code> for the <code>base</code> argument (base is determined by the first characters parsed)</p> +</td> +</tr> <tr> <th> +<code>u</code> </th> <td> Matches an unsigned <b>decimal integer</b>. <p>The format of the number is the same as expected by <a href="../string/byte/strtoul" title="c/string/byte/strtoul"><code>strtoul</code></a> with the value <code>10</code> for the <code>base</code> argument.</p> +</td> +</tr> <tr> <th> +<code>o</code> </th> <td> Matches an unsigned <b>octal integer</b>. <p>The format of the number is the same as expected by <a href="../string/byte/strtoul" title="c/string/byte/strtoul"><code>strtoul</code></a> with the value <code>8</code> for the <code>base</code> argument</p> +</td> +</tr> <tr> <th> +<code>x</code>, <code>X</code> </th> <td> Matches an unsigned <b>hexadecimal integer</b>. <p>The format of the number is the same as expected by <a href="../string/byte/strtoul" title="c/string/byte/strtoul"><code>strtoul</code></a> with the value <code>16</code> for the <code>base</code> argument</p> +</td> +</tr> <tr> <th> +<code>n</code> </th> <td> Returns the <b>number of characters read so far</b>. <p>No input is consumed. Does not increment the assignment count. If the specifier has assignment-suppressing operator defined, the behavior is undefined</p> +</td> +</tr> <tr> <th> +<code>a</code>, <code>A</code><span class="t-mark-rev t-since-c99">(C99)</span><br><code>e</code>, <code>E</code><br><code>f</code>, <code>F</code><span class="t-mark-rev t-since-c99">(C99)</span><br><code>g</code>, <code>G</code> </th> <td> Matches a <b>floating-point number</b>. <p>The format of the number is the same as expected by <a href="../string/byte/strtof" title="c/string/byte/strtof"><code>strtof</code></a></p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<div><code>float*</code></div> </td> <td> +<div><code>double*</code></div> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<div><code>long double*</code></div> </td> +</tr> <tr> <th> +<code>p</code> </th> <td> Matches implementation defined character sequence defining a <b>pointer</b>. <p><code>printf</code> family of functions should produce the same sequence using <code>%p</code> format specifier</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<div><code>void**</code></div> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> +</table> <p>For every conversion specifier other than <code>n</code>, the longest sequence of input characters which does not exceed any specified field width and which either is exactly what the conversion specifier expects or is a prefix of a sequence it would expect, is what's consumed from the stream. The first character, if any, after this consumed sequence remains unread. If the consumed sequence has length zero or if the consumed sequence cannot be converted as specified above, the matching failure occurs unless end-of-file, an encoding error, or a read error prevented input from the stream, in which case it is an input failure.</p> +<p>All conversion specifiers other than <code>[</code>, <code>c</code>, and <code>n</code> consume and discard all leading whitespace characters (determined as if by calling <a href="../string/byte/isspace" title="c/string/byte/isspace"><code>isspace</code></a>) before attempting to parse the input. These consumed characters do not count towards the specified maximum field width.</p> +<p>The conversion specifiers <code>lc</code>, <code>ls</code>, and <code>l[</code> perform multibyte-to-wide character conversion as if by calling <a href="../string/multibyte/mbrtowc" title="c/string/multibyte/mbrtowc"><code>mbrtowc</code></a> with an <a href="../string/multibyte/mbstate_t" title="c/string/multibyte/mbstate t"><code>mbstate_t</code></a> object initialized to zero before the first character is converted.</p> +<p>The conversion specifiers <code>s</code> and <code>[</code> always store the null terminator in addition to the matched characters. The size of the destination array must be at least one greater than the specified field width. The use of <code>%s</code> or <code>%[</code>, without specifying the destination array size, is as unsafe as <code><a href="gets" title="c/io/gets">gets</a></code>.</p> +<p>The correct conversion specifications for the <a href="../types/integer" title="c/types/integer">fixed-width integer types</a> (<code><a href="../types/integer" title="c/types/integer">int8_t</a></code>, etc) are defined in the header <a href="../types/integer" title="c/types/integer"><code><inttypes.h></code></a> (although <a href="../types/integer" title="c/types/integer"><code>SCNdMAX</code></a>, <a href="../types/integer" title="c/types/integer"><code>SCNuMAX</code></a>, etc is synonymous with <code>%jd</code>, <code>%ju</code>, etc).</p> +<p>There is a <a href="../language/eval_order" title="c/language/eval order">sequence point</a> after the action of each conversion specifier; this permits storing multiple fields in the same "sink" variable.</p> +<p>When parsing an incomplete floating-point value that ends in the exponent with no digits, such as parsing <code>"100er"</code> with the conversion specifier <code>%f</code>, the sequence <code>"100e"</code> (the longest prefix of a possibly valid floating-point number) is consumed, resulting in a matching error (the consumed sequence cannot be converted to a floating-point number), with <code>"r"</code> remaining. Some existing implementations do not follow this rule and roll back to consume only <code>"100"</code>, leaving <code>"er"</code>, e.g. <a rel="nofollow" class="external text" href="https://sourceware.org/bugzilla/show_bug.cgi?id=1765">glibc bug 1765</a>.</p> +<h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1-3)</span> Number of receiving arguments successfully assigned, or <code><a href="../io" title="c/io">EOF</a></code> if read failure occurs before the first receiving argument was assigned.</div> <div class="t-li1"> +<span class="t-li">4-6)</span> Same as <span class="t-v">(1-3)</span>, except that <code><a href="../io" title="c/io">EOF</a></code> is also returned if there is a runtime constraint violation.</div> <h3 id="Notes"> Notes</h3> <p>All these functions invoke <code>va_arg</code> at least once, the value of <code>arg</code> is indeterminate after the return. These functions to not invoke <code>va_end</code>, and it must be done by the caller.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdbool.h> +#include <stdarg.h> + +bool checked_sscanf(int count, const char* buf, const char *fmt, ...) +{ + va_list ap; + va_start(ap, fmt); + int rc = vsscanf(buf, fmt, ap); + va_end(ap); + return rc == count; +} + +int main(void) +{ + int n, m; + + printf("Parsing '1 2'..."); + if(checked_sscanf(2, "1 2", "%d %d", &n, &m)) + puts("success"); + else + puts("failure"); + + printf("Parsing '1 a'..."); + if(checked_sscanf(2, "1 a", "%d %d", &n, &m)) + puts("success"); + else + puts("failure"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Parsing '1 2'...success +Parsing '1 a'...failure</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.21.6.9 The vfscanf function (p: 327) </li> +<li> 7.21.6.11 The vscanf function (p: 328) </li> +<li> 7.21.6.14 The vsscanf function (p: 330) </li> +<li> K.3.5.3.9 The vfscanf_s function (p: 597-598) </li> +<li> K.3.5.3.11 The vscanf_s function (p: 599) </li> +<li> K.3.5.3.14 The vsscanf_s function (p: 602) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.19.6.9 The vfscanf function (p: 293) </li> +<li> 7.19.6.11 The vscanf function (p: 294) </li> +<li> 7.19.6.14 The vsscanf function (p: 295) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fscanf" title="c/io/fscanf"> <span class="t-lines"><span>scanf</span><span>fscanf</span><span>sscanf</span><span>scanf_s</span><span>fscanf_s</span><span>sscanf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads formatted input from <code><a href="std_streams" title="c/io/std streams">stdin</a></code>, a file stream or a buffer <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="vfprintf" title="c/io/vfprintf"> <span class="t-lines"><span>vprintf</span><span>vfprintf</span><span>vsprintf</span><span>vsnprintf</span><span>vprintf_s</span><span>vfprintf_s</span><span>vsprintf_s</span><span>vsnprintf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> prints formatted output to <code><a href="std_streams" title="c/io/std streams">stdout</a></code>, a file stream or a buffer<br> using variable argument list <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/vfscanf" title="cpp/io/c/vfscanf">C++ documentation</a></span> for <code>vscanf, vfscanf, vsscanf</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/vfscanf" class="_attribution-link">https://en.cppreference.com/w/c/io/vfscanf</a> + </p> +</div> diff --git a/devdocs/c/io%2Fvfwprintf.html b/devdocs/c/io%2Fvfwprintf.html new file mode 100644 index 00000000..4fbbfa0c --- /dev/null +++ b/devdocs/c/io%2Fvfwprintf.html @@ -0,0 +1,227 @@ + <h1 id="firstHeading" class="firstHeading">vwprintf, vfwprintf, vswprintf, vwprintf_s, vfwprintf_s, vswprintf_s, vsnwprintf_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td> <pre data-language="c">int vwprintf( const wchar_t *format, va_list vlist );</pre> +</td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int vwprintf( const wchar_t *restrict format, va_list vlist );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(2)</td> <td></td> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td> <pre data-language="c">int vfwprintf( FILE* stream, const wchar_t *format, va_list vlist );</pre> +</td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int vfwprintf( FILE *restrict stream, + const wchar_t *restrict format, va_list vlist );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(3)</td> <td></td> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td> <pre data-language="c">int vswprintf( wchar_t *buffer, size_t bufsz, + const wchar_t *format, va_list vlist );</pre> +</td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int vswprintf( wchar_t *restrict buffer, size_t bufsz, + const wchar_t *restrict format, va_list vlist );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int vwprintf_s( const wchar_t *restrict format, va_list vlist);</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int vfwprintf_s( FILE * restrict stream, + const wchar_t *restrict format, va_list vlist);</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int vswprintf_s( wchar_t *restrict buffer, rsize_t bufsz, + const wchar_t * restrict format, va_list vlist);</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int vsnwprintf_s( wchar_t *restrict buffer, rsize_t bufsz, + const wchar_t *restrict format, va_list vlist);</pre> +</td> <td> (7) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Loads the data from locations, defined by <code>vlist</code>, converts them to wide string equivalents and writes the results to a variety of sinks.</p> +<div class="t-li1"> +<span class="t-li">1)</span> Writes the results to <code><a href="std_streams" title="c/io/std streams">stdout</a></code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Writes the results to a file stream <code>stream</code>.</div> <div class="t-li1"> +<span class="t-li">3)</span> Writes the results to a wide string <code>buffer</code>. At most <code>bufsz-1</code> wide characters are written followed by null wide character. The resulting wide character string will be terminated with a null wide character, unless <code>bufsz</code> is zero.</div> <div class="t-li1"> +<span class="t-li">4-6)</span> Same as <span class="t-v">(1-3)</span>, except that the following errors are detected at runtime and call the currently installed <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <ul> +<li> the conversion specifier <code>%n</code> is present in <code>format</code> </li> +<li> any of the arguments corresponding to <code>%s</code> is a null pointer </li> +<li> <code>format</code> or <code>buffer</code> is a null pointer </li> +<li> <code>bufsz</code> is zero or greater than <code>RSIZE_MAX/sizeof(wchar_t)</code> </li> +<li> encoding errors occur in any of string and character conversion specifiers </li> +<li> (for <code>vswprintf_s</code> only), the string to be stored in <code>buffer</code> (including the trailing wide null) would be exceed <code>bufsz</code> +</li> +</ul> +</div> <div class="t-li1"> +<span class="t-li">7)</span> Same as <span class="t-v">(6)</span>, except it will truncate the result to fit within the array pointed to by <code>buffer</code>. As with all bounds-checked functions, <code>vwprintf_s</code> , <code>vfwprintf_s</code>, <code>vswprintf_s</code>, and <code>vsnwprintf_s</code> are only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../io" title="c/io"><code><stdio.h></code></a>.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> output wide stream to write to </td> +</tr> <tr class="t-par"> <td> buffer </td> <td> - </td> <td> pointer to a wide string to write to </td> +</tr> <tr class="t-par"> <td> bufsz </td> <td> - </td> <td> maximum number of wide characters to write </td> +</tr> <tr class="t-par"> <td> format </td> <td> - </td> <td> pointer to a null-terminated wide string specifying how to interpret the data </td> +</tr> <tr class="t-par"> <td> vlist </td> <td> - </td> <td> <a href="../language/variadic" title="c/language/variadic">variable argument list</a> containing the data to print. </td> +</tr> +</table> <p><br> The <b>format</b> string consists of ordinary wide characters (except <code>%</code>), which are copied unchanged into the output stream, and conversion specifications. Each conversion specification has the following format:</p> +<ul> +<li> introductory <code>%</code> character. </li> +<li> <span class="t-mark">(optional)</span> one or more flags that modify the behavior of the conversion: </li> +<ul> +<li> <code>-</code>: the result of the conversion is left-justified within the field (by default it is right-justified). </li> +<li> <code>+</code>: the sign of signed conversions is always prepended to the result of the conversion (by default the result is preceded by minus only when it is negative). </li> +<li> <i>space</i>: if the result of a signed conversion does not start with a sign character, or is empty, space is prepended to the result. It is ignored if <code>+</code> flag is present. </li> +<li> <code>#</code>: <i>alternative form</i> of the conversion is performed. See the table below for exact effects otherwise the behavior is undefined. </li> +<li> <code>0</code>: for integer and floating point number conversions, leading zeros are used to pad the field instead of <i>space</i> characters. For integer numbers it is ignored if the precision is explicitly specified. For other conversions using this flag results in undefined behavior. It is ignored if <code>-</code> flag is present. </li> +</ul> +<li> <span class="t-mark">(optional)</span> integer value or <code>*</code> that specifies minimum field width. The result is padded with <i>space</i> characters (by default), if required, on the left when right-justified, or on the right if left-justified. In the case when <code>*</code> is used, the width is specified by an additional argument of type <code>int</code>, which appears before the argument to be converted and the argument supplying precision if one is supplied. If the value of the argument is negative, it results with the <code>-</code> flag specified and positive field width (Note: This is the minimum width: The value is never truncated.). </li> +<ul> +<li> <span class="t-mark">(optional)</span> <code>.</code> followed by integer number or <code>*</code>, or neither that specifies <i>precision</i> of the conversion. In the case when <code>*</code> is used, the <i>precision</i> is specified by an additional argument of type <code>int</code>, which appears before the argument to be converted, but after the argument supplying minimum field width if one is supplied. If the value of this argument is negative, it is ignored. If neither a number nor <code>*</code> is used, the precision is taken as zero. See the table below for exact effects of <i>precision</i>. </li> +<li> <span class="t-mark">(optional)</span> <i>length modifier</i> that specifies the size of the argument (in combination with the conversion format specifier, it specifies the type of the corresponding argument). </li> +<li> conversion format specifier. </li> +</ul> +</ul> <p>The following format specifiers are available:</p> +<table class="wikitable"> <tr> <th rowspan="1">Conversion<br>Specifier </th> <th rowspan="1">Explanation </th> <th colspan="9">Expected<br>Argument Type </th> +</tr> <tr> <th colspan="2"> +<b>Length<br>Modifier</b><b>→</b> </th> <th> +<code>hh</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>h</code> </th> <th>(none) </th> <th> +<code>l</code> </th> <th> +<code>ll</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>j</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>z</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>t</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>L</code> </th> +</tr> <tr> <th> +<code>%</code> </th> <td>Writes literal <code>%</code>. The full conversion specification must be <code>%%</code>. </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>c</code> </th> <td> Writes a <b>single character</b>. <p>The argument is first converted to <code>wchar_t</code> as if by calling <code><a href="../string/multibyte/btowc" title="c/string/multibyte/btowc">btowc</a></code>. If the <b>l</b> modifier is used, the <code>wint_t</code> argument is first converted to <code>wchar_t</code>.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<div><code>int</code></div> </td> <td> +<div><code>wint_t</code></div> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>s</code> </th> <td> Writes a <b>character string</b> <p>The argument must be a pointer to the initial element of a character array containing a multibyte character sequence beginning in the initial shift state, which is converted to wide character array as if by a call to <code><a href="../string/multibyte/mbrtowc" title="c/string/multibyte/mbrtowc">mbrtowc</a></code> with zero-initialized conversion state. <i>Precision</i> specifies the maximum number of wide characters to be written. If <i>Precision</i> is not specified, writes every wide characters up to and not including the first null terminator. If the <b>l</b> specifier is used, the argument must be a pointer to the initial element of an array of <code>wchar_t</code>.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<div><code>char*</code></div> </td> <td> +<div><code>wchar_t*</code></div> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>d</code><br><code>i</code> </th> <td> Converts a <b>signed integer</b> into decimal representation <i>[-]dddd</i>. <p><i>Precision</i> specifies the minimum number of digits to appear. The default precision is <code>1</code>.<br><br> If both the converted value and the precision are <code>0</code> the conversion results in no characters.<br><br></p> +</td> <td rowspan="1"> +<div><code>signed char</code></div> </td> <td rowspan="1"> +<div><code>short</code></div> </td> <td rowspan="1"> +<div><code>int</code></div> </td> <td rowspan="1"> +<div><code>long</code></div> </td> <td rowspan="1"> +<div><code>long long</code></div> </td> <td rowspan="1"> +<div><code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw118">intmax_t</span></a></code></div> </td> <td rowspan="1"> +<div>signed <code><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a></code> +</div> </td> <td rowspan="1"> +<div><code><a href="http://en.cppreference.com/w/c/types/ptrdiff_t"><span class="kw101">ptrdiff_t</span></a></code></div> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>o</code> </th> <td> Converts an <b>unsigned integer</b> into octal representation <i>oooo</i>. <p><i>Precision</i> specifies the minimum number of digits to appear. The default precision is <code>1</code>. If both the converted value and the precision are <code>0</code> the conversion results in no characters. In the <i>alternative implementation</i> precision is increased if necessary, to write one leading zero. In that case if both the converted value and the precision are <code>0</code>, single <code>0</code> is written.</p> +</td> <td rowspan="3"> +<div><code>unsigned char</code></div> </td> <td rowspan="3"> +<div><code>unsigned short</code></div> </td> <td rowspan="3"> +<div><code>unsigned int</code></div> </td> <td rowspan="3"> +<div><code>unsigned long</code></div> </td> <td rowspan="3"> +<div><code>unsigned long long</code></div> </td> <td rowspan="3"> +<div><code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw132">uintmax_t</span></a></code></div> </td> <td rowspan="3"> +<div><code><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a></code></div> </td> <td rowspan="3"> +<div>unsigned version of <code><a href="http://en.cppreference.com/w/c/types/ptrdiff_t"><span class="kw101">ptrdiff_t</span></a></code> +</div> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>x</code><br><code>X</code> </th> <td> Converts an <b>unsigned integer</b> into hexadecimal representation <i>hhhh</i>. <p>For the <code>x</code> conversion letters <code>abcdef</code> are used.<br> For the <code>X</code> conversion letters <code>ABCDEF</code> are used.<br> <i>Precision</i> specifies the minimum number of digits to appear. The default precision is <code>1</code>. If both the converted value and the precision are <code>0</code> the conversion results in no characters. In the <i>alternative implementation</i> <code>0x</code> or <code>0X</code> is prefixed to results if the converted value is nonzero.</p> +</td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>u</code> </th> <td> Converts an <b>unsigned integer</b> into decimal representation <i>dddd</i>. <p><i>Precision</i> specifies the minimum number of digits to appear. The default precision is <code>1</code>. If both the converted value and the precision are <code>0</code> the conversion results in no characters.</p> +</td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>f</code><br><code>F</code> </th> <td> Converts <b>floating-point number</b> to the decimal notation in the style <i>[-]ddd.ddd</i>. <p><i>Precision</i> specifies the exact number of digits to appear after the decimal point character. The default precision is <code>6</code>. In the <i>alternative implementation</i> decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td rowspan="4"> +<div><code>double</code></div> </td> <td rowspan="4"> +<div> +<code>double</code><span class="t-mark-rev t-since-c99">(C99)</span> +</div> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td rowspan="4"> +<div><code>long double</code></div> </td> +</tr> <tr> <th> +<code>e</code><br><code>E</code> </th> <td> Converts <b>floating-point number</b> to the decimal exponent notation. <p>For the <code>e</code> conversion style <i>[-]d.ddd</i><code>e</code><i>±dd</i> is used.<br> For the <code>E</code> conversion style <i>[-]d.ddd</i><code>E</code><i>±dd</i> is used.<br> The exponent contains at least two digits, more digits are used only if necessary. If the value is <code>0</code>, the exponent is also <code>0</code>. <i>Precision</i> specifies the exact number of digits to appear after the decimal point character. The default precision is <code>6</code>. In the <i>alternative implementation</i> decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>a</code><br><code>A</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <td> Converts <b>floating-point number</b> to the hexadecimal exponent notation. <p>For the <code>a</code> conversion style <i>[-]</i><code>0x</code><i>h.hhh</i><code>p</code><i>±d</i> is used.<br> For the <code>A</code> conversion style <i>[-]</i><code>0X</code><i>h.hhh</i><code>P</code><i>±d</i> is used.<br> The first hexadecimal digit is not <code>0</code> if the argument is a normalized floating point value. If the value is <code>0</code>, the exponent is also <code>0</code>. <i>Precision</i> specifies the exact number of digits to appear after the hexadecimal point character. The default precision is sufficient for exact representation of the value. In the <i>alternative implementation</i> decimal point character is written even if no digits follow it. For infinity and not-a-number conversion style see notes.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>g</code><br><code>G</code> </th> <td> Converts <b>floating-point number</b> to decimal or decimal exponent notation depending on the value and the <i>precision</i>. <p>For the <code>g</code> conversion style conversion with style <code>e</code> or <code>f</code> will be performed.<br> For the <code>G</code> conversion style conversion with style <code>E</code> or <code>F</code> will be performed.<br> Let <code>P</code> equal the precision if nonzero, <code>6</code> if the precision is not specified, or <code>1</code> if the precision is <code>0</code>. Then, if a conversion with style <code>E</code> would have an exponent of <code>X</code>:</p> +<ul> +<li> if <i>P > X ≥ −4</i>, the conversion is with style <code>f</code> or <code>F</code> and precision <i>P − 1 − X</i>. </li> +<li> otherwise, the conversion is with style <code>e</code> or <code>E</code> and precision <i>P − 1</i>. </li> +</ul> <p>Unless <i>alternative representation</i> is requested the trailing zeros are removed, also the decimal point character is removed if no fractional part is left. For infinity and not-a-number conversion style see notes.</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>n</code> </th> <td> Returns the <b>number of characters written</b> so far by this call to the function. <p>The result is <i>written</i> to the value pointed to by the argument. The specification may not contain any <i>flag</i>, <i>field width</i>, or <i>precision</i>.<br><br><br><br></p> +</td> <td> +<div><code>signed char*</code></div> </td> <td> +<div><code>short*</code></div> </td> <td> +<div><code>int*</code></div> </td> <td> +<div><code>long*</code></div> </td> <td> +<div><code>long long*</code></div> </td> <td> +<div><code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw118">intmax_t</span></a><span class="sy2">*</span></code></div> </td> <td> +<div>signed <code><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="sy2">*</span></code> +</div> </td> <td> +<div><code><a href="http://en.cppreference.com/w/c/types/ptrdiff_t"><span class="kw101">ptrdiff_t</span></a><span class="sy2">*</span></code></div> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>p</code> </th> <td>Writes an implementation defined character sequence defining a <b>pointer</b>. </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<code>void*</code> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> +</table> <p>The floating point conversion functions convert infinity to <code>inf</code> or <code>infinity</code>. Which one is used is implementation defined.</p> +<p>Not-a-number is converted to <code>nan</code> or <code>nan(<i>char_sequence</i>)</code>. Which one is used is implementation defined.</p> +<p>The conversions <code>F</code>, <code>E</code>, <code>G</code>, <code>A</code> output <code>INF</code>, <code>INFINITY</code>, <code>NAN</code> instead.</p> +<p>Even though <code>%c</code> expects <code>int</code> argument, it is safe to pass a <code>char</code> because of the integer promotion that takes place when a variadic function is called.</p> +<p>The correct conversion specifications for the fixed-width character types (<code><a href="../types/integer" title="c/types/integer">int8_t</a></code>, etc) are defined in the header <a href="../types/integer" title="c/types/integer"><code><inttypes.h></code></a> (although <code><a href="../types/integer" title="c/types/integer">PRIdMAX</a></code>, <code><a href="../types/integer" title="c/types/integer">PRIuMAX</a></code>, etc is synonymous with <code>%jd</code>, <code>%ju</code>, etc).</p> +<p>The memory-writing conversion specifier <code>%n</code> is a common target of security exploits where format strings depend on user input and is not supported by the bounds-checked <code>printf_s</code> family of functions.</p> +<p>There is a <a href="../language/eval_order" title="c/language/eval order">sequence point</a> after the action of each conversion specifier; this permits storing multiple <code>%n</code> results in the same variable or, as an edge case, printing a string modified by an earlier <code>%n</code> within the same call.</p> +<p>If a conversion specification is invalid, the behavior is undefined.</p> +<h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1,4)</span> The number of wide characters written if successful or negative value if an error occurred.</div> <div class="t-li1"> +<span class="t-li">3)</span> The number of wide characters written if successful or negative value if an error occurred. If the resulting string gets truncated due to <code>bufsz</code> limit, function returns the total number of characters (not including the terminating null wide character) which would have been written, if the limit were not imposed. </div> <div class="t-li1"> +<span class="t-li">2,5)</span> number of wide characters transmitted to the output stream or negative value if an output error, a runtime constraints violation error, or an encoding error occurred.</div> <div class="t-li1"> +<span class="t-li">6)</span> number of wide characters written to <code>buffer</code>, not counting the null wide character (which is always written as long as <code>buffer</code> is not a null pointer and <code>bufsz</code> is not zero and not greater than <code>RSIZE_MAX/sizeof(wchar_t)</code>), or zero on runtime constraint violations, and negative value on encoding errors.</div> <div class="t-li1"> +<span class="t-li">7)</span> number of wide characters not including the terminating null character (which is always written as long as <code>buffer</code> is not a null pointer and <code>bufsz</code> is not zero and not greater than <code>RSIZE_MAX/sizeof(wchar_t)</code>), which would have been written to <code>buffer</code> if <code>bufsz</code> was ignored, or a negative value if a runtime constraints violation or an encoding error occurred.</div> <h3 id="Notes"> Notes</h3> <p>All these functions invoke <code>va_arg</code> at least once, the value of <code>arg</code> is indeterminate after the return. These functions to not invoke <code>va_end</code>, and it must be done by the caller.</p> +<p>While narrow strings provide <code><a href="vfprintf" title="c/io/vfprintf">vsnprintf</a></code>, which makes it possible to determine the required output buffer size, there is no equivalent for wide strings (until C11's vsnwprintf_s), and in order to determine the buffer size, the program may need to call <code>vswprintf</code>, check the result value, and reallocate a larger buffer, trying again until successful.</p> +<p><code>vsnwprintf_s</code>, unlike <code>vswprintf_s</code>, will truncate the result to fit within the array pointed to by <code>buffer</code>, even though truncation is treated as an error by most bounds-checked functions.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <time.h> +#include <locale.h> +#include <stdarg.h> +#include <stddef.h> +#include <wchar.h> + +void debug_wlog(const wchar_t *fmt, ...) +{ + struct timespec ts; + timespec_get(&ts, TIME_UTC); + char time_buf[100]; + size_t rc = strftime(time_buf, sizeof time_buf, "%D %T", gmtime(&ts.tv_sec)); + snprintf(time_buf + rc, sizeof time_buf - rc, ".%06ld UTC", ts.tv_nsec / 1000); + + va_list args; + va_start(args, fmt); + wchar_t buf[1024]; + int rc2 = vswprintf(buf, sizeof buf / sizeof *buf, fmt, args); + va_end(args); + + if(rc2 > 0) + wprintf(L"%s [debug]: %ls\n", time_buf, buf); + else + wprintf(L"%s [debug]: (string too long)\n", time_buf); +} + +int main(void) +{ + setlocale(LC_ALL, ""); + debug_wlog(L"Logging, %d, %d, %d", 1, 2, 3); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">02/20/15 22:12:38.476575 UTC [debug]: Logging, 1, 2, 3</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.29.2.5 The vfwprintf function (p: 417-418) </li> +<li> 7.29.2.7 The vswprintf function (p: 419) </li> +<li> 7.29.2.9 The vwprintf function (p: 420) </li> +<li> K.3.9.1.6 The vfwprintf_s function (p: 632) </li> +<li> K.3.9.1.8 The vsnwprintf_s function (p: 633-634) </li> +<li> K.3.9.1.9 The vswprintf_s function (p: 634-635) </li> +<li> K.3.9.1.11 The vwprintf_s function (p: 636) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.24.2.5 The vfwprintf function (p: 363) </li> +<li> 7.24.2.7 The vswprintf function (p: 364) </li> +<li> 7.24.2.9 The vwprintf function (p: 365) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="vfprintf" title="c/io/vfprintf"> <span class="t-lines"><span>vprintf</span><span>vfprintf</span><span>vsprintf</span><span>vsnprintf</span><span>vprintf_s</span><span>vfprintf_s</span><span>vsprintf_s</span><span>vsnprintf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> prints formatted output to <code><a href="std_streams" title="c/io/std streams">stdout</a></code>, a file stream or a buffer<br> using variable argument list <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fwprintf" title="c/io/fwprintf"> <span class="t-lines"><span>wprintf</span><span>fwprintf</span><span>swprintf</span><span>wprintf_s</span><span>fwprintf_s</span><span>swprintf_s</span><span>snwprintf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> prints formatted wide character output to <code><a href="std_streams" title="c/io/std streams">stdout</a></code>, a file stream or a buffer <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/vfwprintf" title="cpp/io/c/vfwprintf">C++ documentation</a></span> for <code>vwprintf, vfwprintf, vswprintf</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/vfwprintf" class="_attribution-link">https://en.cppreference.com/w/c/io/vfwprintf</a> + </p> +</div> diff --git a/devdocs/c/io%2Fvfwscanf.html b/devdocs/c/io%2Fvfwscanf.html new file mode 100644 index 00000000..dd3e9ae2 --- /dev/null +++ b/devdocs/c/io%2Fvfwscanf.html @@ -0,0 +1,157 @@ + <h1 id="firstHeading" class="firstHeading">vwscanf, vfwscanf, vswscanf, vwscanf_s, vfwscanf_s, vswscanf_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int vwscanf( const wchar_t *restrict format, va_list vlist );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int vfwscanf( FILE *restrict stream, + const wchar_t *restrict format, va_list vlist );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int vswscanf( const wchar_t *restrict buffer, + const wchar_t *restrict format, va_list vlist );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int vwscanf_s( const wchar_t *restrict format, va_list vlist );</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int vfwscanf_s( FILE *restrict stream, + const wchar_t *restrict format, va_list vlist );</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int vswscanf_s( const wchar_t *restrict buffer, + const wchar_t *restrict format, va_list vlist );</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Reads data from the a variety of sources, interprets it according to <code>format</code> and stores the results into locations defined by <code>vlist</code>.</p> +<div class="t-li1"> +<span class="t-li">1)</span> Reads the data from <code><a href="std_streams" title="c/io/std streams">stdin</a></code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Reads the data from file stream <code>stream</code>.</div> <div class="t-li1"> +<span class="t-li">3)</span> Reads the data from null-terminated wide string <code>buffer</code>. Reaching the end of the string is equivalent to reaching the end-of-file condition for <code>fwscanf</code> +</div> <div class="t-li1"> +<span class="t-li">4-6)</span> Same as <span class="t-v">(1-3)</span>, except that <code>%c</code>, <code>%s</code>, and <code>%[</code> conversion specifiers each expect two arguments (the usual pointer and a value of type <code>rsize_t</code> indicating the size of the receiving array, which may be 1 when reading with a %lc into a single wide character) and except that the following errors are detected at runtime and call the currently installed <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> any of the arguments of pointer type is a null pointer </li> +<li> <code>format</code>, <code>stream</code>, or <code>buffer</code> is a null pointer </li> +<li> the number of characters that would be written by %c, %s, or %[, plus the terminating null character, would exceed the second (rsize_t) argument provided for each of those conversion specifiers </li> +<li> optionally, any other detectable error, such as unknown conversion specifier </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>vwscanf_s</code> , <code>vfwscanf_s</code>, and <code>vswscanf_s</code> are only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../io" title="c/io"><code><stdio.h></code></a>.</dd> +</dl> +</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> input file stream to read from </td> +</tr> <tr class="t-par"> <td> buffer </td> <td> - </td> <td> pointer to a null-terminated wide string to read from </td> +</tr> <tr class="t-par"> <td> format </td> <td> - </td> <td> pointer to a null-terminated wide string specifying how to read the input </td> +</tr> <tr class="t-par"> <td> vlist </td> <td> - </td> <td> variable argument list containing the receiving arguments. </td> +</tr> +</table> <p><br> The <b>format</b> string consists of</p> +<ul> +<li> non-whitespace wide characters except <code>%</code>: each such character in the format string consumes exactly one identical character from the input stream, or causes the function to fail if the next character on the stream does not compare equal. </li> +<li> whitespace characters: any single whitespace character in the format string consumes all available consecutive whitespace characters from the input (determined as if by calling <a href="../string/wide/iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a> in a loop). Note that there is no difference between <code>"\n"</code>, <code>" "</code>, <code>"\t\t"</code>, or other whitespace in the format string. </li> +<li> conversion specifications. Each conversion specification has the following format: </li> +<ul> +<li> introductory <code>%</code> character. </li> +<li> <span class="t-mark">(optional)</span> assignment-suppressing character <code>*</code>. If this option is present, the function does not assign the result of the conversion to any receiving argument. </li> +<li> <span class="t-mark">(optional)</span> integer number (greater than zero) that specifies <i>maximum field width</i>, that is, the maximum number of characters that the function is allowed to consume when doing the conversion specified by the current conversion specification. Note that <code>%s</code> and <code>%[</code> may lead to buffer overflow if the width is not provided. </li> +<li> <span class="t-mark">(optional)</span> <i>length modifier</i> that specifies the size of the receiving argument, that is, the actual destination type. This affects the conversion accuracy and overflow rules. The default destination type is different for each conversion type (see table below). </li> +<li> conversion format specifier. </li> +</ul> +</ul> <p>The following format specifiers are available:</p> +<table class="wikitable"> <tr> <th rowspan="1">Conversion<br>specifier </th> <th rowspan="1">Explanation </th> <th colspan="9">Argument type </th> +</tr> <tr> <th colspan="2"> +<b>Length modifier →</b> </th> <th> +<code>hh</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>h</code> </th> <th>(none) </th> <th> +<code>l</code> </th> <th> +<code>ll</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>j</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>z</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>t</code> <p><span class="t-mark-rev t-since-c99">(C99)</span></p> +</th> <th> +<code>L</code> </th> +</tr> <tr> <th> +<code>%</code> </th> <td>Matches literal <code>%</code>. </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>c</code> </th> <td> Matches a <b>character</b> or a sequence of <b>characters</b>. <p>If a width specifier is used, matches exactly <i>width</i> wide characters (the argument must be a pointer to an array with sufficient room). Unlike %s and %[, does not append the null character to the array.</p> +</td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3"> +<div><code>char*</code></div> </td> <td rowspan="3"> +<div><code>wchar_t*</code></div> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> <td rowspan="3" class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>s</code> </th> <td> Matches a sequence of non-whitespace characters (a <b>string</b>). <p>If width specifier is used, matches up to <i>width</i> or until the first whitespace character, whichever appears first. Always stores a null character in addition to the characters matched (so the argument array must have room for at least <i>width+1</i> characters)</p> +</td> +</tr> <tr> <th> +<code>[</code><span class="t-spar">set</span><code>]</code> </th> <td> Matches a non-empty sequence of character from <span class="t-spar">set</span> of characters. <p>If the first character of the set is <code>^</code>, then all characters not in the set are matched. If the set begins with <code>]</code> or <code>^]</code> then the <code>]</code> character is also included into the set. It is implementation-defined whether the character <code>-</code> in the non-initial position in the scanset may be indicating a range, as in <code>[0-9]</code>. If width specifier is used, matches only up to <i>width</i>. Always stores a null character in addition to the characters matched (so the argument array must have room for at least <i>width+1</i> characters)</p> +</td> +</tr> <tr> <th> +<code>d</code> </th> <td> Matches a <b>decimal integer</b>. <p>The format of the number is the same as expected by <a href="../string/wide/wcstol" title="c/string/wide/wcstol"><code>wcstol</code></a> with the value <code>10</code> for the <code>base</code> argument</p> +</td> <td rowspan="6"> +<div> +<code>signed char*</code> or <code>unsigned char*</code> +</div> </td> <td rowspan="6"> +<div> +<code>signed short*</code> or <code>unsigned short*</code> +</div> </td> <td rowspan="6"> +<div> +<code>signed int*</code> or <code>unsigned int*</code> +</div> </td> <td rowspan="6"> +<div> +<code>signed long*</code> or <code>unsigned long*</code> +</div> </td> <td rowspan="6"> +<div> +<code>signed long long*</code> or <code>unsigned long long*</code> +</div> </td> <td rowspan="6"> +<div> +<code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw118">intmax_t</span></a><span class="sy2">*</span></code> or <code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw132">uintmax_t</span></a><span class="sy2">*</span></code> +</div> </td> <td rowspan="6"> +<div><code><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="sy2">*</span></code></div> </td> <td rowspan="6"> +<div><code><a href="http://en.cppreference.com/w/c/types/ptrdiff_t"><span class="kw101">ptrdiff_t</span></a><span class="sy2">*</span></code></div> </td> <td rowspan="6" class="table-na"> <small>N/A</small> </td> +</tr> <tr> <th> +<code>i</code> </th> <td> Matches an <b>integer</b>. <p>The format of the number is the same as expected by <a href="../string/wide/wcstol" title="c/string/wide/wcstol"><code>wcstol</code></a> with the value <code>0</code> for the <code>base</code> argument (base is determined by the first characters parsed)</p> +</td> +</tr> <tr> <th> +<code>u</code> </th> <td> Matches an unsigned <b>decimal integer</b>. <p>The format of the number is the same as expected by <a href="../string/wide/wcstoul" title="c/string/wide/wcstoul"><code>wcstoul</code></a> with the value <code>10</code> for the <code>base</code> argument.</p> +</td> +</tr> <tr> <th> +<code>o</code> </th> <td> Matches an unsigned <b>octal integer</b>. <p>The format of the number is the same as expected by <a href="../string/wide/wcstoul" title="c/string/wide/wcstoul"><code>wcstoul</code></a> with the value <code>8</code> for the <code>base</code> argument</p> +</td> +</tr> <tr> <th> +<code>x</code>, <code>X</code> </th> <td> Matches an unsigned <b>hexadecimal integer</b>. <p>The format of the number is the same as expected by <a href="../string/wide/wcstoul" title="c/string/wide/wcstoul"><code>wcstoul</code></a> with the value <code>16</code> for the <code>base</code> argument</p> +</td> +</tr> <tr> <th> +<code>n</code> </th> <td> Returns the <b>number of characters read so far</b>. <p>No input is consumed. Does not increment the assignment count. If the specifier has assignment-suppressing operator defined, the behavior is undefined</p> +</td> +</tr> <tr> <th> +<code>a</code>, <code>A</code><span class="t-mark-rev t-since-c99">(C99)</span><br><code>e</code>, <code>E</code><br><code>f</code>, <code>F</code><span class="t-mark-rev t-since-c99">(C99)</span><br><code>g</code>, <code>G</code> </th> <td> Matches a <b>floating-point number</b>. <p>The format of the number is the same as expected by <a href="../string/wide/wcstof" title="c/string/wide/wcstof"><code>wcstof</code></a></p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<div><code>float*</code></div> </td> <td> +<div><code>double*</code></div> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<div><code>long double*</code></div> </td> +</tr> <tr> <th> +<code>p</code> </th> <td> Matches implementation defined character sequence defining a <b>pointer</b>. <p><code>printf</code> family of functions should produce the same sequence using <code>%p</code> format specifier</p> +</td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td> +<div><code>void**</code></div> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> +</table> <p>For every conversion specifier other than <code>n</code>, the longest sequence of input characters which does not exceed any specified field width and which either is exactly what the conversion specifier expects or is a prefix of a sequence it would expect, is what's consumed from the stream. The first character, if any, after this consumed sequence remains unread. If the consumed sequence has length zero or if the consumed sequence cannot be converted as specified above, the matching failure occurs unless end-of-file, an encoding error, or a read error prevented input from the stream, in which case it is an input failure.</p> +<p>All conversion specifiers other than <code>[</code>, <code>c</code>, and <code>n</code> consume and discard all leading whitespace characters (determined as if by calling <a href="../string/wide/iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a>) before attempting to parse the input. These consumed characters do not count towards the specified maximum field width.</p> +<p>If the length specifier <code>l</code> is not used, the conversion specifiers <code>c</code>, <code>s</code>, and <code>[</code> perform wide-to-multibyte character conversion as if by calling <a href="../string/multibyte/wcrtomb" title="c/string/multibyte/wcrtomb"><code>wcrtomb</code></a> with an <a href="../string/multibyte/mbstate_t" title="c/string/multibyte/mbstate t"><code>mbstate_t</code></a> object initialized to zero before the first character is converted.</p> +<p>The conversion specifiers <code>s</code> and <code>[</code> always store the null terminator in addition to the matched characters. The size of the destination array must be at least one greater than the specified field width. The use of <code>%s</code> or <code>%[</code>, without specifying the destination array size, is as unsafe as <code><a href="gets" title="c/io/gets">gets</a></code>.</p> +<p>The correct conversion specifications for the <a href="../types/integer" title="c/types/integer">fixed-width integer types</a> (<code><a href="../types/integer" title="c/types/integer">int8_t</a></code>, etc) are defined in the header <a href="../types/integer" title="c/types/integer"><code><inttypes.h></code></a> (although <a href="../types/integer" title="c/types/integer"><code>SCNdMAX</code></a>, <a href="../types/integer" title="c/types/integer"><code>SCNuMAX</code></a>, etc is synonymous with <code>%jd</code>, <code>%ju</code>, etc).</p> +<p>There is a <a href="../language/eval_order" title="c/language/eval order">sequence point</a> after the action of each conversion specifier; this permits storing multiple fields in the same "sink" variable.</p> +<p>When parsing an incomplete floating-point value that ends in the exponent with no digits, such as parsing <code>"100er"</code> with the conversion specifier <code>%f</code>, the sequence <code>"100e"</code> (the longest prefix of a possibly valid floating-point number) is consumed, resulting in a matching error (the consumed sequence cannot be converted to a floating-point number), with <code>"r"</code> remaining. Some existing implementations do not follow this rule and roll back to consume only <code>"100"</code>, leaving <code>"er"</code>, e.g. <a rel="nofollow" class="external text" href="https://sourceware.org/bugzilla/show_bug.cgi?id=1765">glibc bug 1765</a>.</p> +<h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1-3)</span> Number of receiving arguments successfully assigned, or <code><a href="../io" title="c/io">EOF</a></code> if read failure occurs before the first receiving argument was assigned.</div> <div class="t-li1"> +<span class="t-li">4-6)</span> Same as <span class="t-v">(1-3)</span>, except that <code><a href="../io" title="c/io">EOF</a></code> is also returned if there is a runtime constraint violation.</div> <h3 id="Notes"> Notes</h3> <p>All these functions may invoke <code>va_arg</code>, the value of <code>arg</code> is indeterminate after the return. These functions to not invoke <code>va_end</code>, and it must be done by the caller.</p> +<h3 id="Example"> Example</h3> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.29.2.6 The vfwscanf function (p: 418) </li> +<li> 7.29.2.8 The vswscanf function (p: 419) </li> +<li> 7.29.2.10 The vwscanf function (p: 420) </li> +<li> K.3.9.1.7 The vfwscanf_s function (p: 632-633) </li> +<li> K.3.9.1.10 The vswscanf_s function (p: 635-636) </li> +<li> K.3.9.1.12 The vwscanf_s function (p: 637) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.24.2.6 The vfwscanf function (p: 364) </li> +<li> 7.24.2.8 The vswscanf function (p: 365) </li> +<li> 7.24.2.10 The vwscanf function (p: 366) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fwscanf" title="c/io/fwscanf"> <span class="t-lines"><span>wscanf</span><span>fwscanf</span><span>swscanf</span><span>wscanf_s</span><span>fwscanf_s</span><span>swscanf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads formatted wide character input from <code><a href="std_streams" title="c/io/std streams">stdin</a></code>, a file stream or a buffer <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/vfwscanf" title="cpp/io/c/vfwscanf">C++ documentation</a></span> for <code>vwscanf, vfwscanf, vswscanf</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/vfwscanf" class="_attribution-link">https://en.cppreference.com/w/c/io/vfwscanf</a> + </p> +</div> diff --git a/devdocs/c/io.html b/devdocs/c/io.html new file mode 100644 index 00000000..fb93bb9d --- /dev/null +++ b/devdocs/c/io.html @@ -0,0 +1,155 @@ + <h1 id="firstHeading" class="firstHeading">File input/output</h1> <p>The <code><stdio.h></code> header provides generic file operation support and supplies functions with narrow character input/output capabilities.</p> +<p>The <a href="string/wide" title="c/string/wide"><code><wchar.h></code></a> header supplies functions with wide character input/output capabilities.</p> +<p>I/O streams are denoted by objects of type <code><a href="io/file" title="c/io/FILE">FILE</a></code> that can only be accessed and manipulated through pointers of type <code><a href="http://en.cppreference.com/w/c/io/FILE"><span class="kw884">FILE</span></a><span class="sy2">*</span></code>. Each stream is associated with an external physical device (file, standard input stream, printer, serial port, etc).</p> +<h3 id="Types"> Types</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdio.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="io/file" title="c/io/FILE"> <span class="t-lines"><span>FILE</span></span></a></div> </td> <td> object type, capable of holding all information needed to control a C I/O stream <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fpos_t" title="c/io/fpos t"> <span class="t-lines"><span>fpos_t</span></span></a></div> </td> <td> non-array complete object type, capable of uniquely specifying a position and multibyte parser state in a file <br> <span class="t-mark">(typedef)</span> </td> +</tr> </table> <h3 id="Predefined_standard_streams"> Predefined standard streams</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdio.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="io/std_streams" title="c/io/std streams"> <span class="t-lines"><span>stdin</span><span>stdout</span><span>stderr</span></span></a></div> </td> <td> expression of type <code><a href="http://en.cppreference.com/w/c/io/FILE"><span class="kw884">FILE</span></a><span class="sy2">*</span></code> associated with the input stream<br>expression of type <code><a href="http://en.cppreference.com/w/c/io/FILE"><span class="kw884">FILE</span></a><span class="sy2">*</span></code> associated with the output stream<br>expression of type <code><a href="http://en.cppreference.com/w/c/io/FILE"><span class="kw884">FILE</span></a><span class="sy2">*</span></code> associated with the error output stream <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> <h3 id="Functions"> Functions</h3> <table class="t-dsc-begin"> <tr> <td colspan="2"> <h5 id="File_access"> File access </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdio.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fopen" title="c/io/fopen"> <span class="t-lines"><span>fopen</span><span>fopen_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> opens a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/freopen" title="c/io/freopen"> <span class="t-lines"><span>freopen</span><span>freopen_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> open an existing stream with a different name <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fclose" title="c/io/fclose"> <span class="t-lines"><span>fclose</span></span></a></div> </td> <td> closes a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fflush" title="c/io/fflush"> <span class="t-lines"><span>fflush</span></span></a></div> </td> <td> synchronizes an output stream with the actual file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/setbuf" title="c/io/setbuf"> <span class="t-lines"><span>setbuf</span></span></a></div> </td> <td> sets the buffer for a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/setvbuf" title="c/io/setvbuf"> <span class="t-lines"><span>setvbuf</span></span></a></div> </td> <td> sets the buffer and its size for a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><wchar.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fwide" title="c/io/fwide"> <span class="t-lines"><span>fwide</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> switches a file stream between wide character I/O and narrow character I/O <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Direct_input.2Foutput"> Direct input/output </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdio.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fread" title="c/io/fread"> <span class="t-lines"><span>fread</span></span></a></div> </td> <td> reads from a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fwrite" title="c/io/fwrite"> <span class="t-lines"><span>fwrite</span></span></a></div> </td> <td> writes to a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Unformatted_input.2Foutput"> Unformatted input/output </h5> </td> +</tr> <tr> <td colspan="2"> +<h6 id="Narrow_character"> Narrow character</h6> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdio.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fgetc" title="c/io/fgetc"> <span class="t-lines"><span>fgetc</span><span>getc</span></span></a></div> </td> <td> gets a character from a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fgets" title="c/io/fgets"> <span class="t-lines"><span>fgets</span></span></a></div> </td> <td> gets a character string from a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fputc" title="c/io/fputc"> <span class="t-lines"><span>fputc</span><span>putc</span></span></a></div> </td> <td> writes a character to a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fputs" title="c/io/fputs"> <span class="t-lines"><span>fputs</span></span></a></div> </td> <td> writes a character string to a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/getchar" title="c/io/getchar"> <span class="t-lines"><span>getchar</span></span></a></div> </td> <td> reads a character from <code><a href="io/std_streams" title="c/io/std streams">stdin</a></code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/gets" title="c/io/gets"> <span class="t-lines"><span>gets</span><span>gets_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-until-c11">(removed in C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads a character string from <code>stdin</code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/putchar" title="c/io/putchar"> <span class="t-lines"><span>putchar</span></span></a></div> </td> <td> writes a character to <code>stdout</code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/puts" title="c/io/puts"> <span class="t-lines"><span>puts</span></span></a></div> </td> <td> writes a character string to <code><a href="io/std_streams" title="c/io/std streams">stdout</a></code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/ungetc" title="c/io/ungetc"> <span class="t-lines"><span>ungetc</span></span></a></div> </td> <td> puts a character back into a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> +<h6 id="Wide_character"> Wide character</h6> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><wchar.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fgetwc" title="c/io/fgetwc"> <span class="t-lines"><span>fgetwc</span><span>getwc</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> gets a wide character from a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fgetws" title="c/io/fgetws"> <span class="t-lines"><span>fgetws</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> gets a wide string from a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fputwc" title="c/io/fputwc"> <span class="t-lines"><span>fputwc</span><span>putwc</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> writes a wide character to a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fputws" title="c/io/fputws"> <span class="t-lines"><span>fputws</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> writes a wide string to a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/getwchar" title="c/io/getwchar"> <span class="t-lines"><span>getwchar</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> reads a wide character from <code>stdin</code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/putwchar" title="c/io/putwchar"> <span class="t-lines"><span>putwchar</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> writes a wide character to <code><a href="io/std_streams" title="c/io/std streams">stdout</a></code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/ungetwc" title="c/io/ungetwc"> <span class="t-lines"><span>ungetwc</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> puts a wide character back into a file stream <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Formatted_input.2Foutput"> Formatted input/output </h5> </td> +</tr> <tr> <td colspan="2"> +<h6 id="Narrow_character_2"> Narrow character</h6> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdio.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fscanf" title="c/io/fscanf"> <span class="t-lines"><span>scanf</span><span>fscanf</span><span>sscanf</span><span>scanf_s</span><span>fscanf_s</span><span>sscanf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads formatted input from <code><a href="io/std_streams" title="c/io/std streams">stdin</a></code>, a file stream or a buffer <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/vfscanf" title="c/io/vfscanf"> <span class="t-lines"><span>vscanf</span><span>vfscanf</span><span>vsscanf</span><span>vscanf_s</span><span>vfscanf_s</span><span>vsscanf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads formatted input from <code><a href="io/std_streams" title="c/io/std streams">stdin</a></code>, a file stream or a buffer<br> using variable argument list <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fprintf" title="c/io/fprintf"> <span class="t-lines"><span>printf</span><span>fprintf</span><span>sprintf</span><span>snprintf</span><span>printf_s</span><span>fprintf_s</span><span>sprintf_s</span><span>snprintf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> prints formatted output to <code><a href="io/std_streams" title="c/io/std streams">stdout</a></code>, a file stream or a buffer <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/vfprintf" title="c/io/vfprintf"> <span class="t-lines"><span>vprintf</span><span>vfprintf</span><span>vsprintf</span><span>vsnprintf</span><span>vprintf_s</span><span>vfprintf_s</span><span>vsprintf_s</span><span>vsnprintf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> prints formatted output to <code><a href="io/std_streams" title="c/io/std streams">stdout</a></code>, a file stream or a buffer<br> using variable argument list <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> +<h6 id="Wide_character_2"> Wide character</h6> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><wchar.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fwscanf" title="c/io/fwscanf"> <span class="t-lines"><span>wscanf</span><span>fwscanf</span><span>swscanf</span><span>wscanf_s</span><span>fwscanf_s</span><span>swscanf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads formatted wide character input from <code><a href="io/std_streams" title="c/io/std streams">stdin</a></code>, a file stream or a buffer <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/vfwscanf" title="c/io/vfwscanf"> <span class="t-lines"><span>vwscanf</span><span>vfwscanf</span><span>vswscanf</span><span>vwscanf_s</span><span>vfwscanf_s</span><span>vswscanf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads formatted wide character input from <code><a href="io/std_streams" title="c/io/std streams">stdin</a></code>, a file stream<br> or a buffer using variable argument list <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fwprintf" title="c/io/fwprintf"> <span class="t-lines"><span>wprintf</span><span>fwprintf</span><span>swprintf</span><span>wprintf_s</span><span>fwprintf_s</span><span>swprintf_s</span><span>snwprintf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> prints formatted wide character output to <code><a href="io/std_streams" title="c/io/std streams">stdout</a></code>, a file stream or a buffer <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/vfwprintf" title="c/io/vfwprintf"> <span class="t-lines"><span>vwprintf</span><span>vfwprintf</span><span>vswprintf</span><span>vwprintf_s</span><span>vfwprintf_s</span><span>vswprintf_s</span><span>vsnwprintf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> prints formatted wide character output to <code><a href="io/std_streams" title="c/io/std streams">stdout</a></code>, a file stream<br> or a buffer using variable argument list <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="File_positioning"> File positioning </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdio.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="io/ftell" title="c/io/ftell"> <span class="t-lines"><span>ftell</span></span></a></div> </td> <td> returns the current file position indicator <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fgetpos" title="c/io/fgetpos"> <span class="t-lines"><span>fgetpos</span></span></a></div> </td> <td> gets the file position indicator <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fseek" title="c/io/fseek"> <span class="t-lines"><span>fseek</span></span></a></div> </td> <td> moves the file position indicator to a specific location in a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/fsetpos" title="c/io/fsetpos"> <span class="t-lines"><span>fsetpos</span></span></a></div> </td> <td> moves the file position indicator to a specific location in a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/rewind" title="c/io/rewind"> <span class="t-lines"><span>rewind</span></span></a></div> </td> <td> moves the file position indicator to the beginning in a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Error_handling"> Error handling </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdio.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="io/clearerr" title="c/io/clearerr"> <span class="t-lines"><span>clearerr</span></span></a></div> </td> <td> clears errors <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/feof" title="c/io/feof"> <span class="t-lines"><span>feof</span></span></a></div> </td> <td> checks for the end-of-file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/ferror" title="c/io/ferror"> <span class="t-lines"><span>ferror</span></span></a></div> </td> <td> checks for a file error <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/perror" title="c/io/perror"> <span class="t-lines"><span>perror</span></span></a></div> </td> <td> displays a character string corresponding of the current error to <code><a href="io/std_streams" title="c/io/std streams">stderr</a></code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Operations_on_files"> Operations on files </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdio.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="io/remove" title="c/io/remove"> <span class="t-lines"><span>remove</span></span></a></div> </td> <td> erases a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/rename" title="c/io/rename"> <span class="t-lines"><span>rename</span></span></a></div> </td> <td> renames a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/tmpfile" title="c/io/tmpfile"> <span class="t-lines"><span>tmpfile</span><span>tmpfile_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> returns a pointer to a temporary file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="io/tmpnam" title="c/io/tmpnam"> <span class="t-lines"><span>tmpnam</span><span>tmpnam_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> returns a unique filename <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <h3 id="Macro_constants"> Macro constants</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdio.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>EOF</span></span></div> </td> <td> integer constant expression of type <code>int</code> and negative value <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>FOPEN_MAX</span></span></div> </td> <td> maximum number of files that can be open simultaneously <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>FILENAME_MAX</span></span></div> </td> <td> size needed for an array of <code>char</code> to hold the longest supported file name <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>BUFSIZ</span></span></div> </td> <td> size of the buffer used by <code><a href="io/setbuf" title="c/io/setbuf">setbuf</a></code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>_IOFBF</span><span>_IOLBF</span><span>_IONBF</span></span></div> </td> <td> argument to <code><a href="io/setvbuf" title="c/io/setvbuf">setvbuf</a></code> indicating fully buffered I/O<br>argument to <code><a href="io/setvbuf" title="c/io/setvbuf">setvbuf</a></code> indicating line buffered I/O<br>argument to <code><a href="io/setvbuf" title="c/io/setvbuf">setvbuf</a></code> indicating unbuffered I/O <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>SEEK_SET</span><span>SEEK_CUR</span><span>SEEK_END</span></span></div> </td> <td> argument to <code><a href="io/fseek" title="c/io/fseek">fseek</a></code> indicating seeking from beginning of the file<br>argument to <code><a href="io/fseek" title="c/io/fseek">fseek</a></code> indicating seeking from the current file position<br>argument to <code><a href="io/fseek" title="c/io/fseek">fseek</a></code> indicating seeking from end of the file <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>TMP_MAX</span><span>TMP_MAX_S</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> maximum number of unique filenames that can be generated by <code><a href="io/tmpnam" title="c/io/tmpnam">tmpnam</a></code><br>maximum number of unique filenames that can be generated by <code>tmpnam_s</code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>L_tmpnam</span><span>L_tmpnam_s</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> size needed for an array of <code>char</code> to hold the result of <code><a href="io/tmpnam" title="c/io/tmpnam">tmpnam</a></code><br>size needed for an array of <code>char</code> to hold the result of <code>tmpnam_s</code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.21 Input/output <stdio.h> (p: TBD) </li> +<li> 7.29 Extended multibyte and wide character utilities <wchar.h> (p: TBD) </li> +<li> 7.31.11 Input/output <stdio.h> (p: TBD) </li> +<li> 7.31.16 Extended multibyte and wide character utilities <wchar.h> (p: TBD) </li> +<li> K.3.5 Input/output <stdio.h> (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.21 Input/output <stdio.h> (p: TBD) </li> +<li> 7.29 Extended multibyte and wide character utilities <wchar.h> (p: TBD) </li> +<li> 7.31.11 Input/output <stdio.h> (p: TBD) </li> +<li> 7.31.16 Extended multibyte and wide character utilities <wchar.h> (p: TBD) </li> +<li> K.3.5 Input/output <stdio.h> (p: TBD) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.21 Input/output <stdio.h> (p: 296-339) </li> +<li> 7.29 Extended multibyte and wide character utilities <wchar.h> (p: 402-446) </li> +<li> 7.31.11 Input/output <stdio.h> (p: 456) </li> +<li> 7.31.16 Extended multibyte and wide character utilities <wchar.h> (p: 456) </li> +<li> K.3.5 Input/output <stdio.h> (p: 586-603) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.19 Input/output <stdio.h> (p: 262-305) </li> +<li> 7.24 Extended multibyte and wide character utilities <wchar.h> (p: 348-392) </li> +<li> 7.26.9 Input/output <stdio.h> (p: 402) </li> +<li> 7.26.12 Extended multibyte and wide character utilities <wchar.h> (p: 402) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 4.9 INPUT/OUTPUT <stdio.h> </li> +<li> 4.13.6 Input/output <stdio.h> </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c" title="cpp/io/c">C++ documentation</a></span> for <span class=""><span>C-style file input/output</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io" class="_attribution-link">https://en.cppreference.com/w/c/io</a> + </p> +</div> diff --git a/devdocs/c/keyword%2F_alignas.html b/devdocs/c/keyword%2F_alignas.html new file mode 100644 index 00000000..bde2435b --- /dev/null +++ b/devdocs/c/keyword%2F_alignas.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: _Alignas <span class="t-mark-rev t-since-c11">(since C11)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/_alignas" title="c/language/ Alignas"><code>_Alignas</code></a> alignment specifier. <span class="t-mark-rev t-since-c11">(since C11)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/_Alignas" class="_attribution-link">https://en.cppreference.com/w/c/keyword/_Alignas</a> + </p> +</div> diff --git a/devdocs/c/keyword%2F_alignof.html b/devdocs/c/keyword%2F_alignof.html new file mode 100644 index 00000000..1b375956 --- /dev/null +++ b/devdocs/c/keyword%2F_alignof.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: _Alignof <span class="t-mark-rev t-since-c11">(since C11)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/_alignof" title="c/language/ Alignof"><code>_Alignof</code> operator</a> <span class="t-mark-rev t-since-c11">(since C11)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/_Alignof" class="_attribution-link">https://en.cppreference.com/w/c/keyword/_Alignof</a> + </p> +</div> diff --git a/devdocs/c/keyword%2F_atomic.html b/devdocs/c/keyword%2F_atomic.html new file mode 100644 index 00000000..55a2aa4f --- /dev/null +++ b/devdocs/c/keyword%2F_atomic.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: _Atomic <span class="t-mark-rev t-since-c11">(since C11)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/atomic" title="c/language/atomic">atomic type specifier and qualifier</a> <span class="t-mark-rev t-since-c11">(since C11)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/_Atomic" class="_attribution-link">https://en.cppreference.com/w/c/keyword/_Atomic</a> + </p> +</div> diff --git a/devdocs/c/keyword%2F_bool.html b/devdocs/c/keyword%2F_bool.html new file mode 100644 index 00000000..d55eedca --- /dev/null +++ b/devdocs/c/keyword%2F_bool.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: _Bool <span class="t-mark-rev t-since-c99">(since C99)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/arithmetic_types#Boolean_type" title="c/language/arithmetic types">boolean type</a>: as the declaration of the type <span class="t-mark-rev t-since-c99">(since C99)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/_Bool" class="_attribution-link">https://en.cppreference.com/w/c/keyword/_Bool</a> + </p> +</div> diff --git a/devdocs/c/keyword%2F_complex.html b/devdocs/c/keyword%2F_complex.html new file mode 100644 index 00000000..0e2e8d93 --- /dev/null +++ b/devdocs/c/keyword%2F_complex.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: _Complex <span class="t-mark-rev t-since-c99">(since C99)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/arithmetic_types#Complex_floating_types" title="c/language/arithmetic types"><code>_Complex</code> type</a>: as the declaration of the type <span class="t-mark-rev t-since-c99">(since C99)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/_Complex" class="_attribution-link">https://en.cppreference.com/w/c/keyword/_Complex</a> + </p> +</div> diff --git a/devdocs/c/keyword%2F_decimal128.html b/devdocs/c/keyword%2F_decimal128.html new file mode 100644 index 00000000..87b08096 --- /dev/null +++ b/devdocs/c/keyword%2F_decimal128.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: _Decimal128 <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/types" title="c/language/types" class="mw-redirect"><code>_Decimal128</code> type</a>: as the declaration of the type <span class="t-mark-rev t-since-c23">(since C23)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/_Decimal128" class="_attribution-link">https://en.cppreference.com/w/c/keyword/_Decimal128</a> + </p> +</div> diff --git a/devdocs/c/keyword%2F_decimal32.html b/devdocs/c/keyword%2F_decimal32.html new file mode 100644 index 00000000..928701a0 --- /dev/null +++ b/devdocs/c/keyword%2F_decimal32.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: _Decimal32 <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/types" title="c/language/types" class="mw-redirect"><code>_Decimal32</code> type</a>: as the declaration of the type <span class="t-mark-rev t-since-c23">(since C23)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/_Decimal32" class="_attribution-link">https://en.cppreference.com/w/c/keyword/_Decimal32</a> + </p> +</div> diff --git a/devdocs/c/keyword%2F_decimal64.html b/devdocs/c/keyword%2F_decimal64.html new file mode 100644 index 00000000..b87c110e --- /dev/null +++ b/devdocs/c/keyword%2F_decimal64.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: _Decimal64 <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/types" title="c/language/types" class="mw-redirect"><code>_Decimal64</code> type</a>: as the declaration of the type <span class="t-mark-rev t-since-c23">(since C23)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/_Decimal64" class="_attribution-link">https://en.cppreference.com/w/c/keyword/_Decimal64</a> + </p> +</div> diff --git a/devdocs/c/keyword%2F_generic.html b/devdocs/c/keyword%2F_generic.html new file mode 100644 index 00000000..f03c65f1 --- /dev/null +++ b/devdocs/c/keyword%2F_generic.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: _Generic <span class="t-mark-rev t-since-c11">(since C11)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/generic" title="c/language/generic">Type-generic expression</a> <span class="t-mark-rev t-since-c11">(since C11)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/_Generic" class="_attribution-link">https://en.cppreference.com/w/c/keyword/_Generic</a> + </p> +</div> diff --git a/devdocs/c/keyword%2F_imaginary.html b/devdocs/c/keyword%2F_imaginary.html new file mode 100644 index 00000000..10c0e039 --- /dev/null +++ b/devdocs/c/keyword%2F_imaginary.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: _Imaginary <span class="t-mark-rev t-since-c99">(since C99)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/arithmetic_types#Imaginary_floating_types" title="c/language/arithmetic types">imaginary floating type</a> specifier <span class="t-mark-rev t-since-c99">(since C99)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/_Imaginary" class="_attribution-link">https://en.cppreference.com/w/c/keyword/_Imaginary</a> + </p> +</div> diff --git a/devdocs/c/keyword%2F_noreturn.html b/devdocs/c/keyword%2F_noreturn.html new file mode 100644 index 00000000..c3748ec2 --- /dev/null +++ b/devdocs/c/keyword%2F_noreturn.html @@ -0,0 +1,11 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: _Noreturn <span class="t-mark-rev t-since-c11">(since C11)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul> +<li> <a href="../language/_noreturn" title="c/language/ Noreturn"> <code>_Noreturn</code> function specifier</a><span class="t-mark-rev t-deprecated-c23">(deprecated in C23)</span> </li> +<li> <a href="../language/attributes/noreturn" title="c/language/attributes/noreturn"> <code>_Noreturn</code> attribute-token</a><span class="t-mark-rev t-since-c23">(since C23)</span><span class="t-mark-rev t-deprecated-c23">(deprecated in C23)</span> </li> +</ul> <h3 id="Notes"> Notes</h3> <p>Since C23, <code>_Noreturn</code> is also <a href="../language/attributes/noreturn" title="c/language/attributes/noreturn">attribute token</a>. Its usage is deprecated and <code>noreturn</code> should be used instead.</p> +<div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/_Noreturn" class="_attribution-link">https://en.cppreference.com/w/c/keyword/_Noreturn</a> + </p> +</div> diff --git a/devdocs/c/keyword%2F_static_assert.html b/devdocs/c/keyword%2F_static_assert.html new file mode 100644 index 00000000..b4f9e344 --- /dev/null +++ b/devdocs/c/keyword%2F_static_assert.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: _Static_assert <span class="t-mark-rev t-since-c11">(since C11)</span><span class="t-mark-rev t-deprecated-c23">(deprecated in C23)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/_static_assert" title="c/language/ Static assert">static assert declaration</a> <span class="t-mark-rev t-since-c11">(since C11)</span><span class="t-mark-rev t-deprecated-c23">(deprecated in C23)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/_Static_assert" class="_attribution-link">https://en.cppreference.com/w/c/keyword/_Static_assert</a> + </p> +</div> diff --git a/devdocs/c/keyword%2F_thread_local.html b/devdocs/c/keyword%2F_thread_local.html new file mode 100644 index 00000000..79e40060 --- /dev/null +++ b/devdocs/c/keyword%2F_thread_local.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: _Thread_local <span class="t-mark-rev t-since-c11">(since C11)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/storage_duration" title="c/language/storage duration">thread storage-class specifier</a> <span class="t-mark-rev t-since-c11">(since C11)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/_Thread_local" class="_attribution-link">https://en.cppreference.com/w/c/keyword/_Thread_local</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Falignas.html b/devdocs/c/keyword%2Falignas.html new file mode 100644 index 00000000..78e65700 --- /dev/null +++ b/devdocs/c/keyword%2Falignas.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: alignas <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/alignas" title="c/language/alignas" class="mw-redirect"><code>alignas</code></a> alignment specifier. <span class="t-mark-rev t-since-c23">(since C23)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/alignas" class="_attribution-link">https://en.cppreference.com/w/c/keyword/alignas</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Falignof.html b/devdocs/c/keyword%2Falignof.html new file mode 100644 index 00000000..41b8b990 --- /dev/null +++ b/devdocs/c/keyword%2Falignof.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: alignof <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/alignof" title="c/language/alignof" class="mw-redirect"><code>alignof</code> operator</a> <span class="t-mark-rev t-since-c23">(since C23)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/alignof" class="_attribution-link">https://en.cppreference.com/w/c/keyword/alignof</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fauto.html b/devdocs/c/keyword%2Fauto.html new file mode 100644 index 00000000..6cad61f3 --- /dev/null +++ b/devdocs/c/keyword%2Fauto.html @@ -0,0 +1,9 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: auto</h1> <h3 id="Usage"> Usage</h3> <ul> +<li> <a href="../language/storage_duration" title="c/language/storage duration"> automatic duration storage-class specifier</a> with no linkage. </li> +<li> type inference <span class="t-mark-rev t-since-c23">(since C23)</span> </li> +</ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/auto" class="_attribution-link">https://en.cppreference.com/w/c/keyword/auto</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fbool.html b/devdocs/c/keyword%2Fbool.html new file mode 100644 index 00000000..4407f54c --- /dev/null +++ b/devdocs/c/keyword%2Fbool.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: bool <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/arithmetic_types#Boolean_type" title="c/language/arithmetic types">boolean type</a>: as the declaration of the type <span class="t-mark-rev t-since-c23">(since C23)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/bool" class="_attribution-link">https://en.cppreference.com/w/c/keyword/bool</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fbreak.html b/devdocs/c/keyword%2Fbreak.html new file mode 100644 index 00000000..6d735959 --- /dev/null +++ b/devdocs/c/keyword%2Fbreak.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: break</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/break" title="c/language/break"> <code>break</code> statement</a>: as the declaration of the statement </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/break" class="_attribution-link">https://en.cppreference.com/w/c/keyword/break</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fcase.html b/devdocs/c/keyword%2Fcase.html new file mode 100644 index 00000000..5aab6fe8 --- /dev/null +++ b/devdocs/c/keyword%2Fcase.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: case</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/switch" title="c/language/switch"> <code>switch</code> statement</a>: as the declaration of the case labels </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/case" class="_attribution-link">https://en.cppreference.com/w/c/keyword/case</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fchar.html b/devdocs/c/keyword%2Fchar.html new file mode 100644 index 00000000..b33defe4 --- /dev/null +++ b/devdocs/c/keyword%2Fchar.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: char</h1> <h3 id="Usage"> Usage</h3> <ul><li> <i>type specifier</i> for the <a href="../language/arithmetic_types#Character_types" title="c/language/arithmetic types"> character types</a> (<code>char</code>, <code>signed char</code>, and <code>unsigned char</code>). </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/char" class="_attribution-link">https://en.cppreference.com/w/c/keyword/char</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fconst.html b/devdocs/c/keyword%2Fconst.html new file mode 100644 index 00000000..91847f44 --- /dev/null +++ b/devdocs/c/keyword%2Fconst.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: const</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/const" title="c/language/const"> <code>const</code> type qualifier</a> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/const" class="_attribution-link">https://en.cppreference.com/w/c/keyword/const</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fconstexpr.html b/devdocs/c/keyword%2Fconstexpr.html new file mode 100644 index 00000000..dbda609e --- /dev/null +++ b/devdocs/c/keyword%2Fconstexpr.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: constexpr <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/constexpr" title="c/language/constexpr"><code>constexpr</code> specifier</a> <span class="t-mark-rev t-since-c23">(since C23)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/constexpr" class="_attribution-link">https://en.cppreference.com/w/c/keyword/constexpr</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fcontinue.html b/devdocs/c/keyword%2Fcontinue.html new file mode 100644 index 00000000..6abe8667 --- /dev/null +++ b/devdocs/c/keyword%2Fcontinue.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: continue</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/continue" title="c/language/continue"> <code>continue</code> statement</a>: as the declaration of the statement </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/continue" class="_attribution-link">https://en.cppreference.com/w/c/keyword/continue</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fdefault.html b/devdocs/c/keyword%2Fdefault.html new file mode 100644 index 00000000..fc0a6ffc --- /dev/null +++ b/devdocs/c/keyword%2Fdefault.html @@ -0,0 +1,9 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: default</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/switch" title="c/language/switch"> <code>switch</code> statement</a>: as the declaration of the default case label </li></ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <ul><li> <a href="../language/generic" title="c/language/generic"> type-generic expression</a>: as the declaration of the default generic association </li></ul> </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/default" class="_attribution-link">https://en.cppreference.com/w/c/keyword/default</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fdo.html b/devdocs/c/keyword%2Fdo.html new file mode 100644 index 00000000..00569117 --- /dev/null +++ b/devdocs/c/keyword%2Fdo.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: do</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/do" title="c/language/do"> <code>do-while</code> loop</a>: as the declaration of the loop </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/do" class="_attribution-link">https://en.cppreference.com/w/c/keyword/do</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fdouble.html b/devdocs/c/keyword%2Fdouble.html new file mode 100644 index 00000000..00ca703b --- /dev/null +++ b/devdocs/c/keyword%2Fdouble.html @@ -0,0 +1,9 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: double</h1> <h3 id="Usage"> Usage</h3> <ul> +<li> <a href="../language/types" title="c/language/types" class="mw-redirect"> <code>double</code> type</a>: as the declaration of the type </li> +<li> <a href="../language/types" title="c/language/types" class="mw-redirect"> <code>long double</code> type</a>: as the declaration of the type when combined with <a href="long" title="c/keyword/long"><code>long</code></a> </li> +</ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/double" class="_attribution-link">https://en.cppreference.com/w/c/keyword/double</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Felse.html b/devdocs/c/keyword%2Felse.html new file mode 100644 index 00000000..ccdbf159 --- /dev/null +++ b/devdocs/c/keyword%2Felse.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: else</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/if" title="c/language/if"> <code>if</code> statement</a>: as the declaration of the alternative branch </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/else" class="_attribution-link">https://en.cppreference.com/w/c/keyword/else</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fenum.html b/devdocs/c/keyword%2Fenum.html new file mode 100644 index 00000000..0d1bf040 --- /dev/null +++ b/devdocs/c/keyword%2Fenum.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: enum</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/enum" title="c/language/enum"> declaration of an enumeration type</a> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/enum" class="_attribution-link">https://en.cppreference.com/w/c/keyword/enum</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fextern.html b/devdocs/c/keyword%2Fextern.html new file mode 100644 index 00000000..aeb3612f --- /dev/null +++ b/devdocs/c/keyword%2Fextern.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: extern</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/storage_duration" title="c/language/storage duration"> static duration storage-class specifier</a> with either internal or more usually external linkage. </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/extern" class="_attribution-link">https://en.cppreference.com/w/c/keyword/extern</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Ffalse.html b/devdocs/c/keyword%2Ffalse.html new file mode 100644 index 00000000..4653d07c --- /dev/null +++ b/devdocs/c/keyword%2Ffalse.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: false <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/bool_constant" title="c/language/bool constant"> predefined boolean constant</a> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/false" class="_attribution-link">https://en.cppreference.com/w/c/keyword/false</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Ffloat.html b/devdocs/c/keyword%2Ffloat.html new file mode 100644 index 00000000..e64ee539 --- /dev/null +++ b/devdocs/c/keyword%2Ffloat.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: float</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/types" title="c/language/types" class="mw-redirect"> <code>float</code> type</a>: as the declaration of the type </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/float" class="_attribution-link">https://en.cppreference.com/w/c/keyword/float</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Ffor.html b/devdocs/c/keyword%2Ffor.html new file mode 100644 index 00000000..0d679e7e --- /dev/null +++ b/devdocs/c/keyword%2Ffor.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: for</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/for" title="c/language/for"> <code>for</code> loop</a>: as the declaration of the loop </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/for" class="_attribution-link">https://en.cppreference.com/w/c/keyword/for</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Ffortran.html b/devdocs/c/keyword%2Ffortran.html new file mode 100644 index 00000000..f037b456 --- /dev/null +++ b/devdocs/c/keyword%2Ffortran.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: fortran</h1> <h3 id="Usage"> Usage</h3> <ul><li> conditionally-supported type specifier for Fortran language linkage. May be used with <a href="../language/function_declaration" title="c/language/function declaration">function declarations</a> and other <a href="../language/extern" title="c/language/extern">external declarations</a> to indicate that the calling convention and name mangling is suitable for linking with translation units written in the Fortran programming language. </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/fortran" class="_attribution-link">https://en.cppreference.com/w/c/keyword/fortran</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fgoto.html b/devdocs/c/keyword%2Fgoto.html new file mode 100644 index 00000000..0fd18ac3 --- /dev/null +++ b/devdocs/c/keyword%2Fgoto.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: goto</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/goto" title="c/language/goto"> <code>goto</code> statement</a>: as the declaration of the statement </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/goto" class="_attribution-link">https://en.cppreference.com/w/c/keyword/goto</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fif.html b/devdocs/c/keyword%2Fif.html new file mode 100644 index 00000000..b873d649 --- /dev/null +++ b/devdocs/c/keyword%2Fif.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: if</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/if" title="c/language/if"> <code>if</code> statement</a>: as the declaration of the <code>if</code> statement </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/if" class="_attribution-link">https://en.cppreference.com/w/c/keyword/if</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Finline.html b/devdocs/c/keyword%2Finline.html new file mode 100644 index 00000000..5367ee73 --- /dev/null +++ b/devdocs/c/keyword%2Finline.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: inline <span class="t-mark-rev t-since-c99">(since C99)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/inline" title="c/language/inline">inline function specifier</a> <span class="t-mark-rev t-since-c99">(since C99)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/inline" class="_attribution-link">https://en.cppreference.com/w/c/keyword/inline</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fint.html b/devdocs/c/keyword%2Fint.html new file mode 100644 index 00000000..8d181ebb --- /dev/null +++ b/devdocs/c/keyword%2Fint.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: int</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/types" title="c/language/types" class="mw-redirect"> <code>int</code> type</a>: as the declaration of the type </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/int" class="_attribution-link">https://en.cppreference.com/w/c/keyword/int</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Flong.html b/devdocs/c/keyword%2Flong.html new file mode 100644 index 00000000..6e559f1f --- /dev/null +++ b/devdocs/c/keyword%2Flong.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: long</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/types" title="c/language/types" class="mw-redirect"> <code>long</code> type modifier</a> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/long" class="_attribution-link">https://en.cppreference.com/w/c/keyword/long</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fnullptr.html b/devdocs/c/keyword%2Fnullptr.html new file mode 100644 index 00000000..16b3ddd4 --- /dev/null +++ b/devdocs/c/keyword%2Fnullptr.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: nullptr <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/nullptr" title="c/language/nullptr"><code>nullptr</code> pointer constant</a> <span class="t-mark-rev t-since-c23">(since C23)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/nullptr" class="_attribution-link">https://en.cppreference.com/w/c/keyword/nullptr</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fregister.html b/devdocs/c/keyword%2Fregister.html new file mode 100644 index 00000000..a834474b --- /dev/null +++ b/devdocs/c/keyword%2Fregister.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: register</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/storage_duration" title="c/language/storage duration"> automatic duration storage-class specifier</a> with no linkage. Hints that the variable will be used heavily. </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/register" class="_attribution-link">https://en.cppreference.com/w/c/keyword/register</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Frestrict.html b/devdocs/c/keyword%2Frestrict.html new file mode 100644 index 00000000..49912f71 --- /dev/null +++ b/devdocs/c/keyword%2Frestrict.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: restrict <span class="t-mark-rev t-since-c99">(since C99)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/restrict" title="c/language/restrict"><code>restrict</code> type qualifier</a> <span class="t-mark-rev t-since-c99">(since C99)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/restrict" class="_attribution-link">https://en.cppreference.com/w/c/keyword/restrict</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Freturn.html b/devdocs/c/keyword%2Freturn.html new file mode 100644 index 00000000..071d7eed --- /dev/null +++ b/devdocs/c/keyword%2Freturn.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: return</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/return" title="c/language/return"> <code>return</code> statement</a>: as the declaration of the statement </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/return" class="_attribution-link">https://en.cppreference.com/w/c/keyword/return</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fshort.html b/devdocs/c/keyword%2Fshort.html new file mode 100644 index 00000000..09e595ea --- /dev/null +++ b/devdocs/c/keyword%2Fshort.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: short</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/types" title="c/language/types" class="mw-redirect"> <code>short</code> type modifier</a> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/short" class="_attribution-link">https://en.cppreference.com/w/c/keyword/short</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fsigned.html b/devdocs/c/keyword%2Fsigned.html new file mode 100644 index 00000000..c82e12e4 --- /dev/null +++ b/devdocs/c/keyword%2Fsigned.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: signed</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/types" title="c/language/types" class="mw-redirect"> <code>signed</code> type modifier</a> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/signed" class="_attribution-link">https://en.cppreference.com/w/c/keyword/signed</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fsizeof.html b/devdocs/c/keyword%2Fsizeof.html new file mode 100644 index 00000000..d1d25e39 --- /dev/null +++ b/devdocs/c/keyword%2Fsizeof.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: sizeof</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/sizeof" title="c/language/sizeof"> <code>sizeof</code> operator</a> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/sizeof" class="_attribution-link">https://en.cppreference.com/w/c/keyword/sizeof</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fstatic.html b/devdocs/c/keyword%2Fstatic.html new file mode 100644 index 00000000..b76c7dc4 --- /dev/null +++ b/devdocs/c/keyword%2Fstatic.html @@ -0,0 +1,12 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: static</h1> <h3 id="Usage"> Usage</h3> <ul> +<li> <a href="../language/storage_duration" title="c/language/storage duration">declarations of file scope with static storage duration and internal linkage</a> </li> +<li> <a href="../language/storage_duration#Static_local_variables" title="c/language/storage duration">definitions of block scope variables with static storage duration and initialized once</a> </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <ul><li> static <a href="../language/array" title="c/language/array">array indices</a> in function parameter declarations. </li></ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/static" class="_attribution-link">https://en.cppreference.com/w/c/keyword/static</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fstatic_assert.html b/devdocs/c/keyword%2Fstatic_assert.html new file mode 100644 index 00000000..c3244b1b --- /dev/null +++ b/devdocs/c/keyword%2Fstatic_assert.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: static_assert <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/_static_assert" title="c/language/ Static assert">static assert declaration</a> <span class="t-mark-rev t-since-c23">(since C23)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/static_assert" class="_attribution-link">https://en.cppreference.com/w/c/keyword/static_assert</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fstruct.html b/devdocs/c/keyword%2Fstruct.html new file mode 100644 index 00000000..a9487bb0 --- /dev/null +++ b/devdocs/c/keyword%2Fstruct.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: struct</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/struct" title="c/language/struct"> declaration of a compound type</a> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/struct" class="_attribution-link">https://en.cppreference.com/w/c/keyword/struct</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fswitch.html b/devdocs/c/keyword%2Fswitch.html new file mode 100644 index 00000000..d8ffb988 --- /dev/null +++ b/devdocs/c/keyword%2Fswitch.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: switch</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/switch" title="c/language/switch"> <code>switch</code> statement</a>: as the declaration of the statement </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/switch" class="_attribution-link">https://en.cppreference.com/w/c/keyword/switch</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fthread_local.html b/devdocs/c/keyword%2Fthread_local.html new file mode 100644 index 00000000..3995ff16 --- /dev/null +++ b/devdocs/c/keyword%2Fthread_local.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: thread_local <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/storage_duration" title="c/language/storage duration">thread storage-class specifier</a> <span class="t-mark-rev t-since-c23">(since C23)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/thread_local" class="_attribution-link">https://en.cppreference.com/w/c/keyword/thread_local</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Ftrue.html b/devdocs/c/keyword%2Ftrue.html new file mode 100644 index 00000000..be5beda8 --- /dev/null +++ b/devdocs/c/keyword%2Ftrue.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: true <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/bool_constant" title="c/language/bool constant"> predefined boolean constant</a> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/true" class="_attribution-link">https://en.cppreference.com/w/c/keyword/true</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Ftypedef.html b/devdocs/c/keyword%2Ftypedef.html new file mode 100644 index 00000000..bed6e86e --- /dev/null +++ b/devdocs/c/keyword%2Ftypedef.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: typedef</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/typedef" title="c/language/typedef"> <code>typedef</code> declaration</a> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/typedef" class="_attribution-link">https://en.cppreference.com/w/c/keyword/typedef</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Ftypeof.html b/devdocs/c/keyword%2Ftypeof.html new file mode 100644 index 00000000..8bfdee21 --- /dev/null +++ b/devdocs/c/keyword%2Ftypeof.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: typeof <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/typeof" title="c/language/typeof"><code>typeof</code> operator</a> <span class="t-mark-rev t-since-c23">(since C23)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/typeof" class="_attribution-link">https://en.cppreference.com/w/c/keyword/typeof</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Ftypeof_unqual.html b/devdocs/c/keyword%2Ftypeof_unqual.html new file mode 100644 index 00000000..b328be5d --- /dev/null +++ b/devdocs/c/keyword%2Ftypeof_unqual.html @@ -0,0 +1,7 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: typeof_unqual <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/typeof" title="c/language/typeof"><code>typeof</code> operator</a> that removes qualifiers <span class="t-mark-rev t-since-c23">(since C23)</span> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/typeof_unqual" class="_attribution-link">https://en.cppreference.com/w/c/keyword/typeof_unqual</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Funion.html b/devdocs/c/keyword%2Funion.html new file mode 100644 index 00000000..92b91d8c --- /dev/null +++ b/devdocs/c/keyword%2Funion.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: union</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/union" title="c/language/union"> declaration of a union type</a> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/union" class="_attribution-link">https://en.cppreference.com/w/c/keyword/union</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Funsigned.html b/devdocs/c/keyword%2Funsigned.html new file mode 100644 index 00000000..069a53c0 --- /dev/null +++ b/devdocs/c/keyword%2Funsigned.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: unsigned</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/types" title="c/language/types" class="mw-redirect"> <code>unsigned</code> type modifier</a> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/unsigned" class="_attribution-link">https://en.cppreference.com/w/c/keyword/unsigned</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fvoid.html b/devdocs/c/keyword%2Fvoid.html new file mode 100644 index 00000000..9e6b2301 --- /dev/null +++ b/devdocs/c/keyword%2Fvoid.html @@ -0,0 +1,9 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: void</h1> <h3 id="Usage"> Usage</h3> <ul> +<li> <a href="../language/types" title="c/language/types" class="mw-redirect"> <code>void</code> type</a>: as the declaration of the incomplete type </li> +<li> <a href="../language/function_declaration" title="c/language/function declaration"> <code>void</code></a>: in a function with no parameter or no return value </li> +</ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/void" class="_attribution-link">https://en.cppreference.com/w/c/keyword/void</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fvolatile.html b/devdocs/c/keyword%2Fvolatile.html new file mode 100644 index 00000000..808b0dd2 --- /dev/null +++ b/devdocs/c/keyword%2Fvolatile.html @@ -0,0 +1,6 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: volatile</h1> <h3 id="Usage"> Usage</h3> <ul><li> <a href="../language/volatile" title="c/language/volatile"> <code>volatile</code> type qualifier</a> </li></ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/volatile" class="_attribution-link">https://en.cppreference.com/w/c/keyword/volatile</a> + </p> +</div> diff --git a/devdocs/c/keyword%2Fwhile.html b/devdocs/c/keyword%2Fwhile.html new file mode 100644 index 00000000..d66bcaac --- /dev/null +++ b/devdocs/c/keyword%2Fwhile.html @@ -0,0 +1,9 @@ + <h1 id="firstHeading" class="firstHeading">C keywords: while</h1> <h3 id="Usage"> Usage</h3> <ul> +<li> <a href="../language/while" title="c/language/while"> <code>while</code> loop</a>: as the declaration of the loop </li> +<li> <a href="../language/do" title="c/language/do"> <code>do-while</code> loop</a>: as the declaration of the terminating condition of the loop </li> +</ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword/while" class="_attribution-link">https://en.cppreference.com/w/c/keyword/while</a> + </p> +</div> diff --git a/devdocs/c/keyword.html b/devdocs/c/keyword.html new file mode 100644 index 00000000..eff12747 --- /dev/null +++ b/devdocs/c/keyword.html @@ -0,0 +1,111 @@ + <h1 id="firstHeading" class="firstHeading">C keywords</h1> <p>This is a list of reserved keywords in C. Since they are used by the language, these keywords are not available for re-definition. <span class="t-rev-inl t-since-c23"><span>As an exception, they are not considered reserved in <a href="language/attributes" title="c/language/attributes"><span class="t-spar">attribute-token</span>s</a></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span></p> +<table class="wikitable"> <tr> <td> <p><a href="keyword/alignas" title="c/keyword/alignas"><code>alignas</code></a> <span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="keyword/alignof" title="c/keyword/alignof"><code>alignof</code></a> <span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="keyword/auto" title="c/keyword/auto"><code>auto</code></a><br> <a href="keyword/bool" title="c/keyword/bool"><code>bool</code></a> <span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="keyword/break" title="c/keyword/break"><code>break</code></a><br> <a href="keyword/case" title="c/keyword/case"><code>case</code></a><br> <a href="keyword/char" title="c/keyword/char"><code>char</code></a><br> <a href="keyword/const" title="c/keyword/const"><code>const</code></a><br> <a href="keyword/constexpr" title="c/keyword/constexpr"><code>constexpr</code></a> <span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="keyword/continue" title="c/keyword/continue"><code>continue</code></a><br> <a href="keyword/default" title="c/keyword/default"><code>default</code></a><br> <a href="keyword/do" title="c/keyword/do"><code>do</code></a><br> <a href="keyword/double" title="c/keyword/double"><code>double</code></a><br> <a href="keyword/else" title="c/keyword/else"><code>else</code></a><br> <a href="keyword/enum" title="c/keyword/enum"><code>enum</code></a><br></p> +</td> <td> <p><a href="keyword/extern" title="c/keyword/extern"><code>extern</code></a><br> <a href="keyword/false" title="c/keyword/false"><code>false</code></a> <span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="keyword/float" title="c/keyword/float"><code>float</code></a><br> <a href="keyword/for" title="c/keyword/for"><code>for</code></a><br> <a href="keyword/goto" title="c/keyword/goto"><code>goto</code></a><br> <a href="keyword/if" title="c/keyword/if"><code>if</code></a><br> <a href="keyword/inline" title="c/keyword/inline"><code>inline</code></a> <span class="t-mark-rev t-since-c99">(C99)</span><br> <a href="keyword/int" title="c/keyword/int"><code>int</code></a><br> <a href="keyword/long" title="c/keyword/long"><code>long</code></a><br> <a href="keyword/nullptr" title="c/keyword/nullptr"><code>nullptr</code></a> <span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="keyword/register" title="c/keyword/register"><code>register</code></a><br> <a href="keyword/restrict" title="c/keyword/restrict"><code>restrict</code></a> <span class="t-mark-rev t-since-c99">(C99)</span><br> <a href="keyword/return" title="c/keyword/return"><code>return</code></a><br> <a href="keyword/short" title="c/keyword/short"><code>short</code></a><br> <a href="keyword/signed" title="c/keyword/signed"><code>signed</code></a><br></p> +</td> <td> <p><a href="keyword/sizeof" title="c/keyword/sizeof"><code>sizeof</code></a><br> <a href="keyword/static" title="c/keyword/static"><code>static</code></a><br> <a href="keyword/static_assert" title="c/keyword/static assert"><code>static_assert</code></a> <span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="keyword/struct" title="c/keyword/struct"><code>struct</code></a><br> <a href="keyword/switch" title="c/keyword/switch"><code>switch</code></a><br> <a href="keyword/thread_local" title="c/keyword/thread local"><code>thread_local</code></a> <span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="keyword/true" title="c/keyword/true"><code>true</code></a> <span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="keyword/typedef" title="c/keyword/typedef"><code>typedef</code></a><br> <a href="keyword/typeof" title="c/keyword/typeof"><code>typeof</code></a> <span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="keyword/typeof_unqual" title="c/keyword/typeof unqual"><code>typeof_unqual</code></a> <span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="keyword/union" title="c/keyword/union"><code>union</code></a><br> <a href="keyword/unsigned" title="c/keyword/unsigned"><code>unsigned</code></a><br> <a href="keyword/void" title="c/keyword/void"><code>void</code></a><br> <a href="keyword/volatile" title="c/keyword/volatile"><code>volatile</code></a><br> <a href="keyword/while" title="c/keyword/while"><code>while</code></a><br></p> +</td> <td> <p><a href="keyword/_alignas" title="c/keyword/ Alignas"><code>_Alignas</code></a> <span class="t-mark-rev t-since-c11">(C11)</span><br> <a href="keyword/_alignof" title="c/keyword/ Alignof"><code>_Alignof</code></a> <span class="t-mark-rev t-since-c11">(C11)</span><br> <a href="keyword/_atomic" title="c/keyword/ Atomic"><code>_Atomic</code></a> <span class="t-mark-rev t-since-c11">(C11)</span><br> <a href="https://en.cppreference.com/mwiki/index.php?title=c/keyword/_BitInt&action=edit&redlink=1" class="new" title="c/keyword/ BitInt (page does not exist)"><code>_BitInt</code></a> <span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="keyword/_bool" title="c/keyword/ Bool"><code>_Bool</code></a> <span class="t-mark-rev t-since-c99">(C99)</span><br> <a href="keyword/_complex" title="c/keyword/ Complex"><code>_Complex</code></a> <span class="t-mark-rev t-since-c99">(C99)</span><br> <a href="keyword/_decimal128" title="c/keyword/ Decimal128"><code>_Decimal128</code></a> <span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="keyword/_decimal32" title="c/keyword/ Decimal32"><code>_Decimal32</code></a> <span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="keyword/_decimal64" title="c/keyword/ Decimal64"><code>_Decimal64</code></a> <span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="keyword/_generic" title="c/keyword/ Generic"><code>_Generic</code></a> <span class="t-mark-rev t-since-c11">(C11)</span><br> <a href="keyword/_imaginary" title="c/keyword/ Imaginary"><code>_Imaginary</code></a> <span class="t-mark-rev t-since-c99">(C99)</span><br> <a href="keyword/_noreturn" title="c/keyword/ Noreturn"><code>_Noreturn</code></a> <span class="t-mark-rev t-since-c11">(C11)</span><br> <a href="keyword/_static_assert" title="c/keyword/ Static assert"><code>_Static_assert</code></a> <span class="t-mark-rev t-since-c11">(C11)</span><br> <a href="keyword/_thread_local" title="c/keyword/ Thread local"><code>_Thread_local</code></a> <span class="t-mark-rev t-since-c11">(C11)</span><br></p> +</td> +</tr> +</table> <p>The most common keywords that begin with an underscore are generally used through their convenience macros:</p> +<table class="wikitable"> <tr> <td>keyword </td> <td>used as </td> <td>defined in </td> +</tr> <tr> <td> +<a href="keyword/_alignas" title="c/keyword/ Alignas"><code>_Alignas</code></a> <span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> +<a href="types" title="c/types"><code>alignas</code></a> <span class="t-mark-rev t-until-c23">(removed in C23)</span> </td> <td> +<code>stdalign.h</code> </td> +</tr> <tr> <td> +<a href="keyword/_alignof" title="c/keyword/ Alignof"><code>_Alignof</code></a> <span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> +<a href="types" title="c/types"><code>alignof</code></a> <span class="t-mark-rev t-until-c23">(removed in C23)</span> </td> <td> +<code>stdalign.h</code> </td> +</tr> <tr> <td> +<a href="keyword/_atomic" title="c/keyword/ Atomic"><code>_Atomic</code></a> <span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> +<a href="thread" title="c/thread"><code>atomic_bool, atomic_int, ...</code></a> </td> <td> +<code>stdatomic.h</code> </td> +</tr> <tr> <td> +<a href="https://en.cppreference.com/mwiki/index.php?title=c/keyword/_BitInt&action=edit&redlink=1" class="new" title="c/keyword/ BitInt (page does not exist)"><code>_BitInt</code></a> <span class="t-mark-rev t-since-c23">(C23)</span> </td> <td>(no macro) </td> <td> </td> +</tr> <tr> <td> +<a href="keyword/_bool" title="c/keyword/ Bool"><code>_Bool</code></a> <span class="t-mark-rev t-since-c99">(C99)</span> </td> <td> +<a href="types" title="c/types"><code>bool</code></a> <span class="t-mark-rev t-until-c23">(removed in C23)</span> </td> <td> +<code>stdbool.h</code> </td> +</tr> <tr> <td> +<a href="keyword/_complex" title="c/keyword/ Complex"><code>_Complex</code></a> <span class="t-mark-rev t-since-c99">(C99)</span> </td> <td> +<a href="numeric/complex/complex" title="c/numeric/complex/complex"><code>complex</code></a> </td> <td> +<code>complex.h</code> </td> +</tr> <tr> <td> +<a href="keyword/_decimal128" title="c/keyword/ Decimal128"><code>_Decimal128</code></a> <span class="t-mark-rev t-since-c23">(C23)</span> </td> <td>(no macro) </td> <td> </td> +</tr> <tr> <td> +<a href="keyword/_decimal32" title="c/keyword/ Decimal32"><code>_Decimal32</code></a> <span class="t-mark-rev t-since-c23">(C23)</span> </td> <td>(no macro) </td> <td> </td> +</tr> <tr> <td> +<a href="keyword/_decimal64" title="c/keyword/ Decimal64"><code>_Decimal64</code></a> <span class="t-mark-rev t-since-c23">(C23)</span> </td> <td>(no macro) </td> <td> </td> +</tr> <tr> <td> +<a href="keyword/_generic" title="c/keyword/ Generic"><code>_Generic</code></a> <span class="t-mark-rev t-since-c11">(C11)</span> </td> <td>(no macro) </td> <td> </td> +</tr> <tr> <td> +<a href="keyword/_imaginary" title="c/keyword/ Imaginary"><code>_Imaginary</code></a> <span class="t-mark-rev t-since-c99">(C99)</span> </td> <td> +<a href="numeric/complex/imaginary" title="c/numeric/complex/imaginary"><code>imaginary</code></a> </td> <td> +<code>complex.h</code> </td> +</tr> <tr> <td> +<a href="keyword/_noreturn" title="c/keyword/ Noreturn"><code>_Noreturn</code></a> <span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> +<a href="types" title="c/types"><code>noreturn</code></a> </td> <td> +<code>stdnoreturn.h</code> </td> +</tr> <tr> <td> +<a href="keyword/_static_assert" title="c/keyword/ Static assert"><code>_Static_assert</code></a> <span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> +<a href="error/static_assert" title="c/error/static assert"><code>static_assert</code></a> <span class="t-mark-rev t-until-c23">(removed in C23)</span> </td> <td> +<code>assert.h</code> </td> +</tr> <tr> <td> +<a href="keyword/_thread_local" title="c/keyword/ Thread local"><code>_Thread_local</code></a> <span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> +<a href="thread/thread_local" title="c/thread/thread local"><code>thread_local</code></a> <span class="t-mark-rev t-until-c23">(removed in C23)</span> </td> <td> +<code>threads.h</code> </td> +</tr> +</table> <p>Also, each name that begins with a double underscore <code>__</code> or an underscore <code>_</code> followed by an uppercase letter is reserved: see <a href="language/identifier#Reserved_identifiers" title="c/language/identifier">identifier</a> for details.</p> +<p>Note that digraphs <code><%</code>, <code>%></code>, <code><:</code>, <code>:></code>, <code>%:</code>, and <code>%:%:</code> provide an <a href="language/operator_alternative" title="c/language/operator alternative">alternative way to represent standard tokens</a>.</p> +<p>The following tokens are recognized by the <a href="preprocessor" title="c/preprocessor">preprocessor</a> when they are used <i>within</i> the context of a preprocessor directive:</p> +<table class="wikitable"> <tr> <td> <p><a href="preprocessor/conditional" title="c/preprocessor/conditional"><code>if</code></a><br> <a href="preprocessor/conditional" title="c/preprocessor/conditional"><code>elif</code></a><br> <a href="preprocessor/conditional" title="c/preprocessor/conditional"><code>else</code></a><br> <a href="preprocessor/conditional" title="c/preprocessor/conditional"><code>endif</code></a><br></p> +</td> <td> <p><a href="preprocessor/conditional" title="c/preprocessor/conditional"><code>ifdef</code></a><br> <a href="preprocessor/conditional" title="c/preprocessor/conditional"><code>ifndef</code></a><br> <a href="preprocessor/conditional" title="c/preprocessor/conditional"><code>elifdef</code></a> <span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="preprocessor/conditional" title="c/preprocessor/conditional"><code>elifndef</code></a> <span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="preprocessor/replace" title="c/preprocessor/replace"><code>define</code></a><br> <a href="preprocessor/replace" title="c/preprocessor/replace"><code>undef</code></a><br></p> +</td> <td> <p><a href="preprocessor/include" title="c/preprocessor/include"><code>include</code></a><br> <a href="preprocessor/embed" title="c/preprocessor/embed"><code>embed</code></a> <span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="preprocessor/line" title="c/preprocessor/line"><code>line</code></a><br> <a href="preprocessor/error" title="c/preprocessor/error"><code>error</code></a><br> <a href="preprocessor/error" title="c/preprocessor/error"><code>warning</code></a> <span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="preprocessor/impl" title="c/preprocessor/impl"><code>pragma</code></a><br></p> +</td> <td> <p><a href="preprocessor/conditional" title="c/preprocessor/conditional"><code>defined</code></a><br> <a href="preprocessor/include" title="c/preprocessor/include"><code>__has_include</code></a> <span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="preprocessor/embed" title="c/preprocessor/embed"><code>__has_embed</code></a> <span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="language/attributes#Attribute_testing" title="c/language/attributes"><code>__has_c_attribute</code></a> <span class="t-mark-rev t-since-c23">(C23)</span></p> +</td> +</tr> +</table> <p>The following tokens are recognized by the preprocessor when they are used <i>outside</i> the context of a preprocessor directive:</p> +<table class="wikitable"> <tr> <td> <p><a href="preprocessor/impl" title="c/preprocessor/impl"><code>_Pragma</code></a> <span class="t-mark-rev t-since-c99">(C99)</span></p> +</td> +</tr> +</table> <p>The following additional keywords are classified as extensions and conditionally-supported:</p> +<table class="wikitable"> <tr> <td> <p><a href="language/asm" title="c/language/asm"><code>asm</code></a><br> <a href="keyword/fortran" title="c/keyword/fortran"><code>fortran</code></a></p> +</td> +</tr> +</table> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 6.4.1 Keywords (p: TBD) </li> +<li> J.5.9 The fortran keyword (p: TBD) </li> +<li> J.5.10 The asm keyword (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.4.1 Keywords (p: 42-43) </li> +<li> J.5.9 The fortran keyword (p: 422) </li> +<li> J.5.10 The asm keyword (p: 422) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.4.1 Keywords (p: 58-59) </li> +<li> J.5.9 The fortran keyword (p: 580) </li> +<li> J.5.10 The asm keyword (p: 580) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 6.4.1 Keywords (p: 50) </li> +<li> J.5.9 The fortran keyword (p: 514) </li> +<li> J.5.10 The asm keyword (p: 514) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 3.1.1 Keywords </li> +<li> G.5.9 The fortran keyword </li> +<li> G.5.10 The asm keyword </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/keyword" title="cpp/keyword">C++ documentation</a></span> for <span class=""><span>C++ keywords</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/keyword" class="_attribution-link">https://en.cppreference.com/w/c/keyword</a> + </p> +</div> diff --git a/devdocs/c/language%2F_alignas.html b/devdocs/c/language%2F_alignas.html new file mode 100644 index 00000000..ea0b1aa4 --- /dev/null +++ b/devdocs/c/language%2F_alignas.html @@ -0,0 +1,85 @@ + <h1 id="firstHeading" class="firstHeading">_Alignas <span class="t-mark-rev t-since-c11">(since C11)</span>, alignas <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <p>Appears in the <a href="declarations" title="c/language/declarations">declaration</a> syntax as one of the type specifiers to modify the <a href="object#Alignment" title="c/language/object">alignment requirement</a> of the object being declared.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>_Alignas</code> <code>(</code> <span class="t-spar">expression</span> <code>)</code> </td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>alignas</code> <code>(</code> <span class="t-spar">expression</span> <code>)</code> </td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>_Alignas</code> <code>(</code> <span class="t-spar">type</span> <code>)</code> </td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>alignas</code> <code>(</code> <span class="t-spar">type</span> <code>)</code> </td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">expression</span> </td> <td> - </td> <td> any <a href="constant_expression" title="c/language/constant expression">integer constant expression</a> whose value is a valid <a href="object#Alignment" title="c/language/object">alignment</a> or zero </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">type</span> </td> <td> - </td> <td> any <a href="type#Type_names" title="c/language/type">type name</a> </td> +</tr> +</table> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>The keyword <code>_Alignas</code> is also available as convenience macro <a href="../types" title="c/types"><code>alignas</code></a>, available in the header <a href="../types" title="c/types"><code><stdalign.h></code></a>.</p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> </table> <h3 id="Explanation"> Explanation</h3> <p>The <span class="t-rev-inl t-until-c23"><span><code>_Alignas</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignas</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> specifier can only be used when declaring objects that are not <a href="bit_field" title="c/language/bit field">bit-fields</a>, and don't have the <a href="storage_duration" title="c/language/storage duration">register</a> storage class. It cannot be used in function parameter declarations, and cannot be used in a typedef.</p> +<p>When used in a declaration, the declared object will have its <a href="object#Alignment" title="c/language/object">alignment requirement</a> set to</p> +<div class="t-li1"> +<span class="t-li">1,2)</span> the result of the <span class="t-spar">expression</span>, unless it is zero</div> <div class="t-li1"> +<span class="t-li">3,4)</span> the alignment requirement of <span class="t-spar">type</span>, that is, to <span class="t-rev-inl t-until-c23"><span><code>_Alignof(type)</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignof(type)</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> +</div> <p>except when this would weaken the alignment the type would have had naturally.</p> +<p>If <span class="t-spar">expression</span> evaluates to zero, this specifier has no effect.</p> +<p>When multiple <span class="t-rev-inl t-until-c23"><span><code>_Alignas</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignas</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> specifiers appear in the same declaration, the strictest one is used.</p> +<p><span class="t-rev-inl t-until-c23"><span><code>_Alignas</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignas</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> specifier only needs to appear on the <a href="declarations#Definitions" title="c/language/declarations">definition</a> of an object, but if any declaration uses <span class="t-rev-inl t-until-c23"><span><code>_Alignas</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignas</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, it must specify the same alignment as the <span class="t-rev-inl t-until-c23"><span><code>_Alignas</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignas</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> on the definition. The behavior is undefined if different translation units specify different alignments for the same object.</p> +<h3 id="Notes"> Notes</h3> <p>In C++, the <code>alignas</code> specifier may also be applied to the declarations of class/struct/union types and enumerations. This is not supported in C, but the alignment of a struct type can be controlled by using <span class="t-rev-inl t-until-c23"><span><code>_Alignas</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignas</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> in a member declaration.</p> +<h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/alignas" title="c/keyword/alignas"><code>alignas</code></a>, <a href="../keyword/_alignas" title="c/keyword/ Alignas"><code>_Alignas</code></a></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdalign.h> +#include <stdio.h> + +// every object of type struct sse_t will be aligned to 16-byte boundary +// (note: needs support for DR 444) +struct sse_t +{ + alignas(16) float sse_data[4]; +}; + +// every object of type struct data will be aligned to 128-byte boundary +struct data +{ + char x; + alignas(128) char cacheline[128]; // over-aligned array of char, + // not array of over-aligned chars +}; + +int main(void) +{ + printf("sizeof(data) = %zu (1 byte + 127 bytes padding + 128-byte array)\n", + sizeof(struct data)); + + printf("alignment of sse_t is %zu\n", alignof(struct sse_t)); + + alignas(2048) struct data d; // this instance of data is aligned even stricter + (void)d; // suppresses "maybe unused" warning +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">sizeof(data) = 256 (1 byte + 127 bytes padding + 128-byte array) +alignment of sse_t is 16</pre></div> </div> <h3 id="Defect_reports"> Defect reports</h3> <p>The following behavior-changing defect reports were applied retroactively to previously published C standards.</p> +<table class="dsctable"> <tr> <th>DR </th> <th>Applied to </th> <th>Behavior as published </th> <th>Correct behavior </th> +</tr> <tr> <td> +<a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_444">DR 444</a> </td> <td>C11 </td> <td> +<code>_Alignas</code> was not allowed in struct and union members </td> <td>allowed </td> +</tr> +</table> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 6.7.5 Alignment specifier (p: TBD) </li> +<li> 6.2.8 Alignment of objects (p: TBD) </li> +<li> 7.15 Alignment <stdalign.h> (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.7.5 Alignment specifier (p: 92) </li> +<li> 6.2.8 Alignment of objects (p: 36-37) </li> +<li> 7.15 Alignment <stdalign.h> (p: 196) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.7.5 Alignment specifier (p: 127-128) </li> +<li> 6.2.8 Alignment of objects (p: 48-49) </li> +<li> 7.15 Alignment <stdalign.h> (p: 268) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/alignas" title="cpp/language/alignas">C++ documentation</a></span> for <span class=""><span><code>alignas</code> specifier</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/_Alignas" class="_attribution-link">https://en.cppreference.com/w/c/language/_Alignas</a> + </p> +</div> diff --git a/devdocs/c/language%2F_alignof.html b/devdocs/c/language%2F_alignof.html new file mode 100644 index 00000000..1a478589 --- /dev/null +++ b/devdocs/c/language%2F_alignof.html @@ -0,0 +1,51 @@ + <h1 id="firstHeading" class="firstHeading">_Alignof operator <span class="t-mark-rev t-since-c11">(since C11)</span> +</h1> <p>Queries the alignment requirement of its operand type.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>_Alignof(</code> <span class="t-spar">type-name</span> <code>)</code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>alignof(</code> <span class="t-spar">type-name</span> <code>)</code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>This operator is typically used through the convenience macro <a href="../types" title="c/types"><code>alignof</code></a>, which is provided in the header <a href="../types" title="c/types"><code><stdalign.h></code></a></p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> </table> <h3 id="Explanation"> Explanation</h3> <p>Returns the <a href="object#Alignment" title="c/language/object">alignment requirement</a> of the type <a href="type#Type_names" title="c/language/type">named</a> by <span class="t-spar">type-name</span>. If <span class="t-spar">type-name</span> is an array type, the result is the alignment requirement of the array element type. The <span class="t-spar">type-name</span> cannot be function type or an incomplete type.</p> +<p>The result is an integer constant of type <code><a href="../types/size_t" title="c/types/size t">size_t</a></code>.</p> +<p>The operand is not evaluated (so external identifiers used in the operand do not have to be defined).</p> +<p>If <span class="t-spar">type-name</span> is a <a href="array" title="c/language/array">VLA</a> type, its size expression is not evaluated.</p> +<h3 id="Notes"> Notes</h3> <p>The use of <span class="t-rev-inl t-until-c23"><span><code>_Alignof</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignof</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> with expressions is allowed by some C compilers as a non-standard extension.</p> +<h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/alignof" title="c/keyword/alignof"><code>alignof</code></a>, <a href="../keyword/_alignof" title="c/keyword/ Alignof"><code>_Alignof</code></a></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdalign.h> +#include <stddef.h> +#include <stdio.h> + +int main(void) +{ + printf("Alignment of char = %zu\n", alignof(char)); + printf("Alignment of max_align_t = %zu\n", alignof(max_align_t)); + printf("alignof(float[10]) = %zu\n", alignof(float[10])); + printf("alignof(struct{char c; int n;}) = %zu\n", + alignof(struct {char c; int n;})); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Alignment of char = 1 +Alignment of max_align_t = 16 +alignof(float[10]) = 4 +alignof(struct{char c; int n;}) = 4</pre></div> </div> <h3 id="Defect_reports"> Defect reports</h3> <p>The following behavior-changing defect reports were applied retroactively to previously published C standards.</p> +<table class="dsctable"> <tr> <th>DR </th> <th>Applied to </th> <th>Behavior as published </th> <th>Correct behavior </th> +</tr> <tr> <td> +<a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_494">DR 494</a> </td> <td>C11 </td> <td>whether the size expression in a VLA is evaluated in <code>_Alignof</code> was unspecified </td> <td>it is unevaluated </td> +</tr> +</table> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.5.3.4 The sizeof and alignof operators (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.5.3.4 The sizeof and _Alignof operators (p: 64-65) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.5.3.4 The sizeof and _Alignof operators (p: 90-91) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../types/max_align_t" title="c/types/max align t"> <span class="t-lines"><span>max_align_t</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> a type with alignment requirement as great as any other scalar type <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td> <a href="_alignas" title="c/language/ Alignas"><code>_Alignas</code> specifier</a><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> sets alignment requirements of an object </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/alignof" title="cpp/language/alignof">C++ documentation</a></span> for <code>alignof operator</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/_Alignof" class="_attribution-link">https://en.cppreference.com/w/c/language/_Alignof</a> + </p> +</div> diff --git a/devdocs/c/language%2F_noreturn.html b/devdocs/c/language%2F_noreturn.html new file mode 100644 index 00000000..ff87fe14 --- /dev/null +++ b/devdocs/c/language%2F_noreturn.html @@ -0,0 +1,61 @@ + <h1 id="firstHeading" class="firstHeading">_Noreturn function specifier</h1> <p>Specifies that the function does not return to its point of invocation.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>_Noreturn</code> <span class="t-spar">function_declaration</span> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span><span class="t-mark-rev t-deprecated-c23">(deprecated in C23)</span> </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>The <code>_Noreturn</code> keyword appears in a function declaration and specifies that the function does not return by executing the return statement or by reaching the end of the function body (it may return by executing <code><a href="../program/longjmp" title="c/program/longjmp">longjmp</a></code>). If the function declared <code>_Noreturn</code> returns, the behavior is undefined. A compiler diagnostic is recommended if this can be detected.</p> +<p>The <code>_Noreturn</code> specifier may appear more than once in the same function declaration, the behavior is the same as if it appeared once.</p> +<p>This specifier is typically used through the convenience macro <a href="../types" title="c/types"><code>noreturn</code></a>, which is provided in the header <code><stdnoreturn.h></code>.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p><code>_Noreturn</code> function specifier is deprecated. <code>[[<a href="attributes/noreturn" title="c/language/attributes/noreturn">noreturn</a>]]</code> attribute should be used instead.</p> +<p>The macro <code>noreturn</code> is also deprecated.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/_noreturn" title="c/keyword/ Noreturn"><code>_Noreturn</code></a></p> +<h3 id="Standard_library"> Standard library</h3> <p>The following functions are <code>noreturn</code> in the standard library:</p> +<ul> +<li> <code><a href="../program/abort" title="c/program/abort">abort()</a></code> </li> +<li> <code><a href="../program/exit" title="c/program/exit">exit()</a></code> </li> +<li> <code><a href="../program/_exit" title="c/program/ Exit">_Exit()</a></code> </li> +<li> <code><a href="../program/quick_exit" title="c/program/quick exit">quick_exit()</a></code> </li> +<li> <code><a href="../thread/thrd_exit" title="c/thread/thrd exit">thrd_exit()</a></code> </li> +<li> <code><a href="../program/longjmp" title="c/program/longjmp">longjmp()</a></code> </li> +</ul> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> +#include <stdnoreturn.h> + +// causes undefined behavior if i <= 0 +// exits if i > 0 +noreturn void exit_now(int i) // or _Noreturn void exit_now(int i) +{ + if (i > 0) + exit(i); +} + +int main(void) +{ + puts("Preparing to exit..."); + exit_now(2); + puts("This code is never executed."); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Preparing to exit...</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 6.7.4 Function specifiers (p: TBD) </li> +<li> 7.23 _Noreturn <stdnoreturn.h> (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.7.4 Function specifiers (p: 90-91) </li> +<li> 7.23 _Noreturn <stdnoreturn.h> (p: 263) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.7.4 Function specifiers (p: 125-127) </li> +<li> 7.23 _Noreturn <stdnoreturn.h> (p: 361) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <code>[[<a href="attributes/noreturn" title="c/language/attributes/noreturn">noreturn</a>]]</code><span class="t-mark-rev t-since-c23">(C23)</span><br><code>[[<a href="attributes/noreturn" title="c/language/attributes/noreturn">_Noreturn</a>]]</code><span class="t-mark-rev t-since-c23">(C23)</span><span class="t-mark">(deprecated)</span> </td> <td> indicates that the function does not return<br><span class="t-mark">(attribute specifier)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/attributes/noreturn" title="cpp/language/attributes/noreturn">C++ documentation</a></span> for <code>[[noreturn]]</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/_Noreturn" class="_attribution-link">https://en.cppreference.com/w/c/language/_Noreturn</a> + </p> +</div> diff --git a/devdocs/c/language%2F_static_assert.html b/devdocs/c/language%2F_static_assert.html new file mode 100644 index 00000000..9ceeb593 --- /dev/null +++ b/devdocs/c/language%2F_static_assert.html @@ -0,0 +1,58 @@ + <h1 id="firstHeading" class="firstHeading">Static assertion <span class="t-mark-rev t-since-c11">(since C11)</span> +</h1> <h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>_Static_assert</code> <code>(</code> <span class="t-spar">expression</span> <code>,</code> <span class="t-spar">message</span> <code>)</code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span><span class="t-mark-rev t-deprecated-c23">(deprecated in C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>static_assert</code> <code>(</code> <span class="t-spar">expression</span> <code>,</code> <span class="t-spar">message</span> <code>)</code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>_Static_assert</code> <code>(</code> <span class="t-spar">expression</span> <code>)</code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span><span class="t-mark-rev t-deprecated-c23">(deprecated in C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>static_assert</code> <code>(</code> <span class="t-spar">expression</span> <code>)</code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">expression</span> </td> <td> - </td> <td> any <a href="constant_expression" title="c/language/constant expression">integer constant expression</a> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">message</span> </td> <td> - </td> <td> any <a href="string_literal" title="c/language/string literal">string literal</a> </td> +</tr> +</table> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>This keyword is also available as convenience macro <a href="../error/static_assert" title="c/error/static assert"><code>static_assert</code></a>, available in the header <a href="../error" title="c/error"><code><assert.h></code></a>.</p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td> <p>Both of <code>static_assert</code> and <code>_Static_assert</code> have the same effects. <code>_Static_assert</code> is a deprecated spelling that is kept for compatibility.</p> +<p>An implementation may also define <code>static_assert</code> and/or <code>_Static_assert</code> as predefined macros, and <code>static_assert</code> is no longer provided by <a href="../error" title="c/error"><code><assert.h></code></a>.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Explanation"> Explanation</h3> <p>The constant expression is evaluated at compile time and compared to zero. If it compares equal to zero, a compile-time error occurs and the compiler <span class="t-rev-inl t-until-c23"><span>must display <span class="t-spar">message</span> as part of the error message (except that characters not in <a href="charset" title="c/language/charset">basic character set</a> are not required to be displayed)</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span>should display <span class="t-spar">message</span> (if provided) as part of the error message</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>.</p> +<p>Otherwise, if <span class="t-spar">expression</span> does not equal zero, nothing happens; no code is emitted.</p> +<h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/_static_assert" title="c/keyword/ Static assert"><code>_Static_assert</code></a>, <a href="../keyword/static_assert" title="c/keyword/static assert"><code>static_assert</code></a></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <assert.h> // no longer needed since C23 + +int main(void) +{ + // Test if math works, C23: + static_assert((2 + 2) % 3 == 1, "Whoa dude, you knew!"); + // Pre-C23 alternative: + _Static_assert(2 + 2 * 2 == 6, "Lucky guess!?"); + + // This will produce an error at compile time. + // static_assert(sizeof(int) < sizeof(char), "Unmet condition!"); + + constexpr int _42 = 2 * 3 * 2 * 3 + 2 * 3; + static_assert(_42 == 42); // the message string can be omitted. + + // const int _13 = 13; + // Compile time error - not an integer constant expression: + // static_assert(_13 == 13); +}</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.7.11 Static assertions (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.7.10 Static assertions (p: 105) </li> +<li> 7.2 Diagnostics <assert.h> (p: 135) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.7.10 Static assertions (p: 145) </li> +<li> 7.2 Diagnostics <assert.h> (p: 186-187) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../error/assert" title="c/error/assert"> <span class="t-lines"><span>assert</span></span></a></div> </td> <td> aborts the program if the user-specified condition is not <code>true</code>. May be disabled for release builds <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/static_assert" title="cpp/language/static assert">C++ documentation</a></span> for <span class=""><span><code>static_assert</code> declaration</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/_Static_assert" class="_attribution-link">https://en.cppreference.com/w/c/language/_Static_assert</a> + </p> +</div> diff --git a/devdocs/c/language%2Falignas.html b/devdocs/c/language%2Falignas.html new file mode 100644 index 00000000..7ea68a4b --- /dev/null +++ b/devdocs/c/language%2Falignas.html @@ -0,0 +1,85 @@ + <h1 id="firstHeading" class="firstHeading">_Alignas <span class="t-mark-rev t-since-c11">(since C11)</span>, alignas <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <p>Appears in the <a href="declarations" title="c/language/declarations">declaration</a> syntax as one of the type specifiers to modify the <a href="object#Alignment" title="c/language/object">alignment requirement</a> of the object being declared.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>_Alignas</code> <code>(</code> <span class="t-spar">expression</span> <code>)</code> </td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>alignas</code> <code>(</code> <span class="t-spar">expression</span> <code>)</code> </td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>_Alignas</code> <code>(</code> <span class="t-spar">type</span> <code>)</code> </td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>alignas</code> <code>(</code> <span class="t-spar">type</span> <code>)</code> </td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">expression</span> </td> <td> - </td> <td> any <a href="constant_expression" title="c/language/constant expression">integer constant expression</a> whose value is a valid <a href="object#Alignment" title="c/language/object">alignment</a> or zero </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">type</span> </td> <td> - </td> <td> any <a href="type#Type_names" title="c/language/type">type name</a> </td> +</tr> +</table> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>The keyword <code>_Alignas</code> is also available as convenience macro <a href="../types" title="c/types"><code>alignas</code></a>, available in the header <a href="../types" title="c/types"><code><stdalign.h></code></a>.</p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> </table> <h3 id="Explanation"> Explanation</h3> <p>The <span class="t-rev-inl t-until-c23"><span><code>_Alignas</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignas</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> specifier can only be used when declaring objects that are not <a href="bit_field" title="c/language/bit field">bit-fields</a>, and don't have the <a href="storage_duration" title="c/language/storage duration">register</a> storage class. It cannot be used in function parameter declarations, and cannot be used in a typedef.</p> +<p>When used in a declaration, the declared object will have its <a href="object#Alignment" title="c/language/object">alignment requirement</a> set to</p> +<div class="t-li1"> +<span class="t-li">1,2)</span> the result of the <span class="t-spar">expression</span>, unless it is zero</div> <div class="t-li1"> +<span class="t-li">3,4)</span> the alignment requirement of <span class="t-spar">type</span>, that is, to <span class="t-rev-inl t-until-c23"><span><code>_Alignof(type)</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignof(type)</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> +</div> <p>except when this would weaken the alignment the type would have had naturally.</p> +<p>If <span class="t-spar">expression</span> evaluates to zero, this specifier has no effect.</p> +<p>When multiple <span class="t-rev-inl t-until-c23"><span><code>_Alignas</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignas</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> specifiers appear in the same declaration, the strictest one is used.</p> +<p><span class="t-rev-inl t-until-c23"><span><code>_Alignas</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignas</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> specifier only needs to appear on the <a href="declarations#Definitions" title="c/language/declarations">definition</a> of an object, but if any declaration uses <span class="t-rev-inl t-until-c23"><span><code>_Alignas</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignas</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, it must specify the same alignment as the <span class="t-rev-inl t-until-c23"><span><code>_Alignas</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignas</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> on the definition. The behavior is undefined if different translation units specify different alignments for the same object.</p> +<h3 id="Notes"> Notes</h3> <p>In C++, the <code>alignas</code> specifier may also be applied to the declarations of class/struct/union types and enumerations. This is not supported in C, but the alignment of a struct type can be controlled by using <span class="t-rev-inl t-until-c23"><span><code>_Alignas</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignas</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> in a member declaration.</p> +<h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/alignas" title="c/keyword/alignas"><code>alignas</code></a>, <a href="../keyword/_alignas" title="c/keyword/ Alignas"><code>_Alignas</code></a></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdalign.h> +#include <stdio.h> + +// every object of type struct sse_t will be aligned to 16-byte boundary +// (note: needs support for DR 444) +struct sse_t +{ + alignas(16) float sse_data[4]; +}; + +// every object of type struct data will be aligned to 128-byte boundary +struct data +{ + char x; + alignas(128) char cacheline[128]; // over-aligned array of char, + // not array of over-aligned chars +}; + +int main(void) +{ + printf("sizeof(data) = %zu (1 byte + 127 bytes padding + 128-byte array)\n", + sizeof(struct data)); + + printf("alignment of sse_t is %zu\n", alignof(struct sse_t)); + + alignas(2048) struct data d; // this instance of data is aligned even stricter + (void)d; // suppresses "maybe unused" warning +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">sizeof(data) = 256 (1 byte + 127 bytes padding + 128-byte array) +alignment of sse_t is 16</pre></div> </div> <h3 id="Defect_reports"> Defect reports</h3> <p>The following behavior-changing defect reports were applied retroactively to previously published C standards.</p> +<table class="dsctable"> <tr> <th>DR </th> <th>Applied to </th> <th>Behavior as published </th> <th>Correct behavior </th> +</tr> <tr> <td> +<a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_444">DR 444</a> </td> <td>C11 </td> <td> +<code>_Alignas</code> was not allowed in struct and union members </td> <td>allowed </td> +</tr> +</table> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 6.7.5 Alignment specifier (p: TBD) </li> +<li> 6.2.8 Alignment of objects (p: TBD) </li> +<li> 7.15 Alignment <stdalign.h> (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.7.5 Alignment specifier (p: 92) </li> +<li> 6.2.8 Alignment of objects (p: 36-37) </li> +<li> 7.15 Alignment <stdalign.h> (p: 196) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.7.5 Alignment specifier (p: 127-128) </li> +<li> 6.2.8 Alignment of objects (p: 48-49) </li> +<li> 7.15 Alignment <stdalign.h> (p: 268) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/alignas" title="cpp/language/alignas">C++ documentation</a></span> for <span class=""><span><code>alignas</code> specifier</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/alignas" class="_attribution-link">https://en.cppreference.com/w/c/language/alignas</a> + </p> +</div> diff --git a/devdocs/c/language%2Falignof.html b/devdocs/c/language%2Falignof.html new file mode 100644 index 00000000..3319be77 --- /dev/null +++ b/devdocs/c/language%2Falignof.html @@ -0,0 +1,51 @@ + <h1 id="firstHeading" class="firstHeading">_Alignof operator <span class="t-mark-rev t-since-c11">(since C11)</span> +</h1> <p>Queries the alignment requirement of its operand type.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>_Alignof(</code> <span class="t-spar">type-name</span> <code>)</code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>alignof(</code> <span class="t-spar">type-name</span> <code>)</code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>This operator is typically used through the convenience macro <a href="../types" title="c/types"><code>alignof</code></a>, which is provided in the header <a href="../types" title="c/types"><code><stdalign.h></code></a></p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> </table> <h3 id="Explanation"> Explanation</h3> <p>Returns the <a href="object#Alignment" title="c/language/object">alignment requirement</a> of the type <a href="type#Type_names" title="c/language/type">named</a> by <span class="t-spar">type-name</span>. If <span class="t-spar">type-name</span> is an array type, the result is the alignment requirement of the array element type. The <span class="t-spar">type-name</span> cannot be function type or an incomplete type.</p> +<p>The result is an integer constant of type <code><a href="../types/size_t" title="c/types/size t">size_t</a></code>.</p> +<p>The operand is not evaluated (so external identifiers used in the operand do not have to be defined).</p> +<p>If <span class="t-spar">type-name</span> is a <a href="array" title="c/language/array">VLA</a> type, its size expression is not evaluated.</p> +<h3 id="Notes"> Notes</h3> <p>The use of <span class="t-rev-inl t-until-c23"><span><code>_Alignof</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignof</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> with expressions is allowed by some C compilers as a non-standard extension.</p> +<h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/alignof" title="c/keyword/alignof"><code>alignof</code></a>, <a href="../keyword/_alignof" title="c/keyword/ Alignof"><code>_Alignof</code></a></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdalign.h> +#include <stddef.h> +#include <stdio.h> + +int main(void) +{ + printf("Alignment of char = %zu\n", alignof(char)); + printf("Alignment of max_align_t = %zu\n", alignof(max_align_t)); + printf("alignof(float[10]) = %zu\n", alignof(float[10])); + printf("alignof(struct{char c; int n;}) = %zu\n", + alignof(struct {char c; int n;})); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Alignment of char = 1 +Alignment of max_align_t = 16 +alignof(float[10]) = 4 +alignof(struct{char c; int n;}) = 4</pre></div> </div> <h3 id="Defect_reports"> Defect reports</h3> <p>The following behavior-changing defect reports were applied retroactively to previously published C standards.</p> +<table class="dsctable"> <tr> <th>DR </th> <th>Applied to </th> <th>Behavior as published </th> <th>Correct behavior </th> +</tr> <tr> <td> +<a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_494">DR 494</a> </td> <td>C11 </td> <td>whether the size expression in a VLA is evaluated in <code>_Alignof</code> was unspecified </td> <td>it is unevaluated </td> +</tr> +</table> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.5.3.4 The sizeof and alignof operators (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.5.3.4 The sizeof and _Alignof operators (p: 64-65) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.5.3.4 The sizeof and _Alignof operators (p: 90-91) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../types/max_align_t" title="c/types/max align t"> <span class="t-lines"><span>max_align_t</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> a type with alignment requirement as great as any other scalar type <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td> <a href="_alignas" title="c/language/ Alignas"><code>_Alignas</code> specifier</a><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> sets alignment requirements of an object </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/alignof" title="cpp/language/alignof">C++ documentation</a></span> for <code>alignof operator</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/alignof" class="_attribution-link">https://en.cppreference.com/w/c/language/alignof</a> + </p> +</div> diff --git a/devdocs/c/language%2Fanalyzability.html b/devdocs/c/language%2Fanalyzability.html new file mode 100644 index 00000000..5a8213a0 --- /dev/null +++ b/devdocs/c/language%2Fanalyzability.html @@ -0,0 +1,49 @@ + <h1 id="firstHeading" class="firstHeading">Analyzability</h1> <p>This optional extension to the C language limits the potential results of executing some forms of undefined behavior, which improves the effectiveness of static analysis of such programs. Analyzability is only guaranteed to be enabled if the <a href="../preprocessor/replace" title="c/preprocessor/replace">predefined macro constant</a> <code>__STDC_ANALYZABLE__</code><span class="t-mark-rev t-since-c11">(C11)</span> is defined by the compiler.</p> +<p>If the compiler supports analyzability, any language or library construct whose behavior is undefined is further classified between <i>critical</i> and <i>bounded</i> undefined behavior, and the behavior of all bounded UB cases is limited as specified below.</p> +<h3 id="Critical_undefined_behavior"> Critical undefined behavior</h3> <p>Critical UB is undefined behavior that might perform a memory write or a volatile memory read out of bounds of any object. A program that has critical undefined behavior may be susceptible to security exploits.</p> +<p>Only the following undefined behaviors are critical:</p> +<ul> +<li> access to an object outside of its <a href="lifetime" title="c/language/lifetime">lifetime</a> (e.g. through a dangling pointer) </li> +<li> write to an object whose declarations are not <a href="type#Compatible_types" title="c/language/type">compatible</a> </li> +<li> function call through a function pointer whose type is not <a href="type#Compatible_types" title="c/language/type">compatible</a> with the type of the function it points to </li> +<li> <a href="value_category" title="c/language/value category">lvalue expression</a> is evaluated, but does not designate an object </li> +<li> attempted modification of a <a href="string_literal" title="c/language/string literal">string literal</a> </li> +<li> <a href="operator_member_access" title="c/language/operator member access">dereferencing</a> an invalid (null, indeterminate, etc) or <a href="operator_arithmetic" title="c/language/operator arithmetic">past-the-end</a> pointer </li> +<li> modification of a <a href="const" title="c/language/const">const object</a> through a non-const pointer </li> +<li> call to a standard library function or macro with an invalid argument </li> +<li> call to a variadic standard library function with unexpected argument type (e.g. call to <code><a href="../io/fprintf" title="c/io/fprintf">printf</a></code> with an argument of the type that doesn't match its conversion specifier) </li> +<li> <code><a href="../program/longjmp" title="c/program/longjmp">longjmp</a></code> where there is no <code><a href="../program/setjmp" title="c/program/setjmp">setjmp</a></code> up the calling scope, across threads, or from within the scope of a VM type. </li> +<li> any use of the pointer that was deallocated by <code><a href="../memory/free" title="c/memory/free">free</a></code> or <code><a href="../memory/realloc" title="c/memory/realloc">realloc</a></code> </li> +<li> any <a href="../string/byte" title="c/string/byte">string</a> or <a href="../string/wide" title="c/string/wide">wide string</a> library function accesses an array out of bounds </li> +</ul> <h3 id="Bounded_undefined_behavior"> Bounded undefined behavior</h3> <p>Bounded UB is undefined behavior that cannot perform an illegal memory write, although it may trap and may produce or store indeterminate values.</p> +<ul> +<li> All undefined behavior not listed as critical is bounded, including </li> +<ul> +<li> multithreaded data races </li> +<li> use of a <a href="initialization" title="c/language/initialization">indeterminate values</a> with automatic storage duration </li> +<li> <a href="object#Strict_aliasing" title="c/language/object">strict aliasing</a> violations </li> +<li> <a href="object#alignment" title="c/language/object">misaligned</a> object access </li> +<li> signed integer overflow </li> +<li> <a href="eval_order" title="c/language/eval order">unsequenced side-effects</a> modify the same scalar or modify and read the same scalar </li> +<li> floating-to-integer or pointer-to-integer <a href="conversion" title="c/language/conversion">conversion</a> overflow </li> +<li> <a href="operator_arithmetic" title="c/language/operator arithmetic">bitwise shift</a> by a negative or too large bit count </li> +<li> <a href="operator_arithmetic" title="c/language/operator arithmetic">integer division</a> by zero </li> +<li> use of a void expression </li> +<li> direct <a href="operator_assignment" title="c/language/operator assignment">assignment</a> or <code><a href="../string/byte/memcpy" title="c/string/byte/memcpy">memcpy</a></code> of inexactly-overlapped objects </li> +<li> <a href="restrict" title="c/language/restrict">restrict</a> violations </li> +<li> etc.. ALL undefined behavior that's not in the critical list. </li> +</ul> +</ul> <h3 id="Notes"> Notes</h3> <p>Bounded undefined behavior disables certain optimizations: compilation with analyzability enabled preserves source-code causality, which <a href="as_if" title="c/language/as if">may be violated</a> by undefined behavior otherwise.</p> +<p>Analyzability extension permits, as a form of implementation-defined behavior, for the <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">runtime constraint handler</a> to be invoked when a trap occurs.</p> +<h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.10.8.3/1 Conditional feature macros (p: 177) </li> +<li> Annex L Analyzability (p: 652-653) </li> +</ul> +</ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/analyzability" class="_attribution-link">https://en.cppreference.com/w/c/language/analyzability</a> + </p> +</div> diff --git a/devdocs/c/language%2Farithmetic_types.html b/devdocs/c/language%2Farithmetic_types.html new file mode 100644 index 00000000..d3423d5a --- /dev/null +++ b/devdocs/c/language%2Farithmetic_types.html @@ -0,0 +1,302 @@ + <h1 id="firstHeading" class="firstHeading">Arithmetic types</h1> <p><small>(See also <a href="type" title="c/language/type">type</a> for type system overview and <a href="../types" title="c/types">the list of type-related utilities</a> that are provided by the C library.)</small></p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <h3 id="Boolean_type"> Boolean type</h3> <ul><li> <span class="t-rev-inl t-until-c23"><span><code>_Bool</code> (also accessible as the macro <a href="../types" title="c/types"><code>bool</code></a>)</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>bool</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> - type, capable of holding one of the two values: <span class="t-rev-inl t-until-c23"><span><code>1</code> and <code>0</code> (also accessible as the macros <a href="../types" title="c/types"><code>true</code></a> and <a href="../types" title="c/types"><code>false</code></a>)</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>true</code> and <code>false</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>. </li></ul> <p>Note that <a href="conversion" title="c/language/conversion">conversion</a> to <span class="t-rev-inl t-until-c23"><span>_Bool</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span>bool</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> does not work the same as conversion to other integer types: <code>(bool)0.5</code> evaluates to <code>true</code>, whereas <code>(int)0.5</code> evaluates to <code>0</code>.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Character_types"> Character types</h3> <ul> +<li> +<code>signed char</code> - type for signed character representation. </li> +<li> +<code>unsigned char</code> - type for unsigned character representation. Also used to inspect <a href="object" title="c/language/object">object representations</a> (raw memory). </li> +<li> +<code>char</code> - type for character representation. Equivalent to either <code>signed char</code> or <code>unsigned char</code> (which one is implementation-defined and may be controlled by a compiler commandline switch), but <code>char</code> is a distinct type, different from both <code>signed char</code> and <code>unsigned char</code>. </li> +</ul> <p>Note that the standard library also defines <a href="typedef" title="c/language/typedef">typedef</a> names <a href="../string/wide" title="c/string/wide"><code>wchar_t</code></a> <span class="t-rev-inl t-since-c11"><span>, <a href="../string/multibyte" title="c/string/multibyte"><code>char16_t</code></a> and <a href="../string/multibyte" title="c/string/multibyte"><code>char32_t</code></a></span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> to represent wide characters <span class="t-rev-inl t-since-c23"><span>and <a href="../string/multibyte" title="c/string/multibyte"><code>char8_t</code></a> for UTF-8 characters</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>.</p> +<h3 id="Integer_types"> Integer types</h3> <ul> +<li> +<code>short int</code> (also accessible as <code>short</code>, may use the keyword <code>signed</code>) </li> +<li> +<code>unsigned short int</code> (also accessible as <code>unsigned short</code>) </li> +<li> +<code>int</code> (also accessible as <code>signed int</code>) </li> +<li> +<code>unsigned int</code> (also accessible as <code>unsigned</code>), the unsigned counterpart of <code>int</code>, implementing modulo arithmetic. Suitable for bit manipulations. </li> +<li> +<code>long int</code> (also accessible as <code>long</code>) </li> +<li> +<code>unsigned long int</code> (also accessible as <code>unsigned long</code>) </li> +</ul> This is the most optimal integer type for the platform, and is guaranteed to be at least 16 bits. Most current systems use 32 bits (see Data models below). <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <ul> +<li> +<code>long long int</code> (also accessible as <code>long long</code>) </li> +<li> +<code>unsigned long long int</code> (also accessible as <code>unsigned long long</code>) </li> +</ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td> <ul> +<li> +<code>_BitInt(n)</code> (also accessible as <code>signed _BitInt(n)</code>), the bit-precise signed integer types (where <code>n</code> is replaced by an integer constant expression denoting the precise width (including the sign bit), that cannot be larger than <code>BITINT_MAXWIDTH</code> from <a href="../types/limits" title="c/types/limits"><code><limits.h></code></a>) </li> +<li> +<code>unsigned _BitInt(n)</code>, the bit-precise unsigned integer types (where <code>n</code> is replaced by an integer constant expression denoting the precise width, that cannot be larger than <code>BITINT_MAXWIDTH</code> from <a href="../types/limits" title="c/types/limits"><code><limits.h></code></a>) </li> +</ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <p>Note: as with all type specifiers, any order is permitted: <code>unsigned long long int</code> and <code>long int unsigned long</code> name the same type.</p> +<p>The following table summarizes all available integer types and their properties:</p> +<table class="wikitable"> <tr> <th rowspan="2"> Type specifier </th> <th rowspan="2"> Equivalent type </th> <th colspan="5"> Width in bits by data model </th> +</tr> <tr> <th> C standard </th> <th> LP32 </th> <th> ILP32 </th> <th> LLP64 </th> <th> LP64 </th> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">char</pre> </td> <td> <span class="kw4">char</span> </td> <td rowspan="3"> at least<br> <b>8</b> </td> <td rowspan="3"> <b>8</b> </td> <td rowspan="3"> <b>8</b> </td> <td rowspan="3"> <b>8</b> </td> <td rowspan="3"> <b>8</b> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">signed char</pre> </td> <td> <span class="kw4">signed</span> <span class="kw4">char</span> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">unsigned char</pre> </td> <td> <span class="kw4">unsigned</span> <span class="kw4">char</span> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">short</pre> </td> <td rowspan="4"> <span class="kw4">short</span> <span class="kw4">int</span> </td> <td rowspan="6"> at least<br> <b>16</b> </td> <td rowspan="6"> <b>16</b> </td> <td rowspan="6"> <b>16</b> </td> <td rowspan="6"> <b>16</b> </td> <td rowspan="6"> <b>16</b> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">short int</pre> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">signed short</pre> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">signed short int</pre> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">unsigned short</pre> </td> <td rowspan="2"> <span class="kw4">unsigned</span> <span class="kw4">short</span> <span class="kw4">int</span> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">unsigned short int</pre> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">int</pre> </td> <td rowspan="3"> <span class="kw4">int</span> </td> <td rowspan="5"> at least<br> <b>16</b> </td> <td rowspan="5"> <b>16</b> </td> <td rowspan="5"> <b>32</b> </td> <td rowspan="5"> <b>32</b> </td> <td rowspan="5"> <b>32</b> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">signed</pre> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">signed int</pre> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">unsigned</pre> </td> <td rowspan="2"> <span class="kw4">unsigned</span> <span class="kw4">int</span> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">unsigned int</pre> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">long</pre> </td> <td rowspan="4"> <span class="kw4">long</span> <span class="kw4">int</span> </td> <td rowspan="6"> at least<br> <b>32</b> </td> <td rowspan="6"> <b>32</b> </td> <td rowspan="6"> <b>32</b> </td> <td rowspan="6"> <b>32</b> </td> <td rowspan="6"> <b>64</b> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">long int</pre> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">signed long</pre> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">signed long int</pre> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">unsigned long</pre> </td> <td rowspan="2"> <span class="kw4">unsigned</span> <span class="kw4">long</span> <span class="kw4">int</span> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">unsigned long int</pre> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">long long</pre> </td> <td rowspan="4"> <span class="kw4">long</span> <span class="kw4">long</span> <span class="kw4">int</span><br> <span class="t-mark-rev t-since-c99">(C99)</span> </td> <td rowspan="6"> at least<br> <b>64</b> </td> <td rowspan="6"> <b>64</b> </td> <td rowspan="6"> <b>64</b> </td> <td rowspan="6"> <b>64</b> </td> <td rowspan="6"> <b>64</b> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">long long int</pre> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">signed long long</pre> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">signed long long int</pre> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">unsigned long long</pre> </td> <td rowspan="2"> <span class="kw4">unsigned</span> <span class="kw4">long</span> <span class="kw4">long</span> <span class="kw4">int</span><br> <span class="t-mark-rev t-since-c99">(C99)</span> </td> +</tr> <tr> <td> <pre style="text-align:left; width:auto; margin-left:auto; margin-right:auto;" data-language="c">unsigned long long int</pre> </td> +</tr> +</table> <p>Besides the minimal bit counts, the C Standard guarantees that <code>1</code> == <code>sizeof(char)</code> ≤ <code>sizeof(short)</code> ≤ <code>sizeof(int)</code> ≤ <code>sizeof(long)</code> ≤ <code>sizeof(long long)</code>.</p> +<p>Note: this allows the extreme case in which <a href="https://en.wikipedia.org/wiki/byte" class="extiw" title="enwiki:byte">byte</a> are sized 64 bits, all types (including <code>char</code>) are 64 bits wide, and <code>sizeof</code> returns 1 for every type.</p> +<p>Note: integer arithmetic is defined differently for the signed and unsigned integer types. See <a href="operator_arithmetic" title="c/language/operator arithmetic">arithmetic operators</a>, in particular <a href="operator_arithmetic#Overflows" title="c/language/operator arithmetic">integer overflows</a>.</p> +<h4 id="Data_models"> Data models</h4> <p>The choices made by each implementation about the sizes of the fundamental types are collectively known as <i>data model</i>. Four data models found wide acceptance:</p> +<p>32 bit systems:</p> +<ul> +<li> +<b>LP32</b> or <b>2/4/4</b> (int is 16-bit, long and pointer are 32-bit) </li> +<ul><li> Win16 API </li></ul> +<li> +<b>ILP32</b> or <b>4/4/4</b> (int, long, and pointer are 32-bit); </li> +<ul> +<li> Win32 API </li> +<li> Unix and Unix-like systems (Linux, Mac OS X) </li> +</ul> +</ul> <p>64 bit systems:</p> +<ul> +<li> <b>LLP64</b> or <b>4/4/8</b> (int and long are 32-bit, pointer is 64-bit) </li> +<ul><li> Win64 API </li></ul> +<li> <b>LP64</b> or <b>4/8/8</b> (int is 32-bit, long and pointer are 64-bit) </li> +<ul><li> Unix and Unix-like systems (Linux, Mac OS X) </li></ul> +</ul> <p>Other models are very rare. For example, <b>ILP64</b> (<b>8/8/8</b>: int, long, and pointer are 64-bit) only appeared in some early 64-bit Unix systems (e.g. Unicos on Cray).</p> +<p>Note that exact-width integer types are available in <a href="../types/integer" title="c/types/integer"><code><stdint.h></code></a> since C99.</p> +<h3 id="Real_floating_types"> Real floating types</h3> <p>C has three <span class="t-rev-inl t-since-c23"><span>or six</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> types for representing real floating-point values:</p> +<ul> +<li> +<code>float</code> - single precision floating-point type. Matches <a href="https://en.wikipedia.org/wiki/Single-precision_floating-point_format" class="extiw" title="enwiki:Single-precision floating-point format">IEEE-754 binary32 format</a> if supported. </li> +<li> +<code>double</code> - double precision floating-point type. Matches <a href="https://en.wikipedia.org/wiki/Double-precision_floating-point_format" class="extiw" title="enwiki:Double-precision floating-point format">IEEE-754 binary64 format</a> if supported. </li> +<li> +<code>long double</code> - extended precision floating-point type. Matches <a href="https://en.wikipedia.org/wiki/Quadruple-precision_floating-point_format" class="extiw" title="enwiki:Quadruple-precision floating-point format">IEEE-754 binary128 format</a> if supported, otherwise matches <a href="https://en.wikipedia.org/wiki/Extended_precision" class="extiw" title="enwiki:Extended precision">IEEE-754 binary64-extended format</a> if supported, otherwise matches some non-IEEE-754 extended floating-point format as long as its precision is better than binary64 and range is at least as good as binary64, otherwise matches IEEE-754 binary64 format. <ul> +<li> binary128 format is used by some HP-UX, SPARC, MIPS, ARM64, and z/OS implementations. </li> +<li> The most well known IEEE-754 binary64-extended format is 80-bit x87 extended precision format. It is used by many x86 and x86-64 implementations (a notable exception is MSVC, which implements <code>long double</code> in the same format as <code>double</code>, i.e. binary64). </li> +</ul> </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <dl> +<dd> If the implementation predefines the macro constant <code>__STDC_IEC_60559_DFP__</code>, the following decimal floating-point types are also supported. <ul> +<li> +<code>_Decimal32</code> - Represents <a href="https://en.wikipedia.org/wiki/decimal32_floating-point_format" class="extiw" title="enwiki:decimal32 floating-point format">IEEE-754 decimal32 format</a>. </li> +<li> +<code>_Decimal64</code> - Represents <a href="https://en.wikipedia.org/wiki/decimal64_floating-point_format" class="extiw" title="enwiki:decimal64 floating-point format">IEEE-754 decimal64 format</a>. </li> +<li> +<code>_Decimal128</code> - Represents <a href="https://en.wikipedia.org/wiki/decimal128_floating-point_format" class="extiw" title="enwiki:decimal128 floating-point format">IEEE-754 decimal128 format</a>. </li> +</ul> </dd> +<dd> Otherwise, these decimal floating-point types are not supported. </dd> +</dl> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <p>Floating-point types may support special values:</p> +<ul> +<li> <i>infinity</i> (positive and negative), see <a href="../numeric/math/infinity" title="c/numeric/math/INFINITY"><code>INFINITY</code></a> </li> +<li> the <i>negative zero</i>, <code>-0.0</code>. It compares equal to the positive zero, but is meaningful in some arithmetic operations, e.g. <code>1.0/0.0 == INFINITY</code>, but <code>1.0/-0.0 == -INFINITY</code>) </li> +<li> <i>not-a-number</i> (NaN), which does not compare equal with anything (including itself). Multiple bit patterns represent NaNs, see <code><a href="../numeric/math/nan" title="c/numeric/math/nan">nan</a></code>, <a href="../numeric/math/nan" title="c/numeric/math/NAN"><code>NAN</code></a>. Note that C takes no special notice of signaling NaNs (specified by IEEE-754), and treats all NaNs as quiet. </li> +</ul> <p>Real floating-point numbers may be used with <a href="operator_arithmetic" title="c/language/operator arithmetic">arithmetic operators</a> + - / * and various mathematical functions from <a href="../numeric/math" title="c/numeric/math"><code><math.h></code></a>. Both built-in operators and library functions may raise floating-point exceptions and set <code><a href="../error/errno" title="c/error/errno">errno</a></code> as described in <a href="../numeric/math/math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>Floating-point expressions may have greater range and precision than indicated by their types, see <code><a href="../types/limits/flt_eval_method" title="c/types/limits/FLT EVAL METHOD">FLT_EVAL_METHOD</a></code>. <a href="operator_assignment" title="c/language/operator assignment">Assignment</a>, <a href="return" title="c/language/return">return</a>, and <a href="cast" title="c/language/cast">cast</a> force the range and precision to the one associated with the declared type.</p> +<p>Floating-point expressions may also be <i>contracted</i>, that is, calculated as if all intermediate values have infinite range and precision, see <a href="../preprocessor/impl#Standard_pragmas" title="c/preprocessor/impl"><code> #pragma STDC FP_CONTRACT</code></a>.</p> +<p>Some operations on floating-point numbers are affected by and modify the state of <a href="../numeric/fenv" title="c/numeric/fenv">the floating-point environment</a> (most notably, the rounding direction).</p> +<p><a href="conversion" title="c/language/conversion">Implicit conversions</a> are defined between real floating types and integer, complex, and imaginary types.</p> +<p>See <a href="../types/limits#Limits_of_floating-point_types" title="c/types/limits">Limits of floating-point types</a> and the <a href="../numeric/math" title="c/numeric/math"><code><math.h></code></a> library for additional details, limits, and properties of the floating-point types.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <h3 id="Complex_floating_types"> Complex floating types</h3> <p>Complex floating types model the mathematical <a href="https://en.wikipedia.org/wiki/complex_number" class="extiw" title="enwiki:complex number">complex number</a>, that is the numbers that can be written as a sum of a real number and a real number multiplied by the imaginary unit: a + bi</p> +<p>The three complex types are</p> +<ul> +<li> <code>float _Complex</code> (also available as <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code> if <a href="../numeric/complex" title="c/numeric/complex"><code><complex.h></code></a> is included) </li> +<li> <code>double _Complex</code> (also available as <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code> if <a href="../numeric/complex" title="c/numeric/complex"><code><complex.h></code></a> is included) </li> +<li> <code>long double _Complex</code> (also available as <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code> if <a href="../numeric/complex" title="c/numeric/complex"><code><complex.h></code></a> is included) </li> +</ul> <p>Note: as with all type specifiers, any order is permitted: <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a> <span class="kw4">long</span> <span class="kw4">double</span></code>, and even <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a> <span class="kw4">long</span></code> name the same type.</p> +<div class="c source-c"><pre data-language="c">#include <complex.h> +#include <stdio.h> + +int main(void) +{ + double complex z = 1 + 2*I; + z = 1 / z; + printf("1/(1.0+2.0i) = %.1f%+.1fi\n", creal(z), cimag(z)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">1/(1.0+2.0i) = 0.2-0.4i</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <p>If the macro constant <code>__STDC_NO_COMPLEX__</code> is defined by the implementation, the complex types (as well as the library header <a href="../numeric/complex" title="c/numeric/complex"><code><complex.h></code></a>) are not provided.</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <p>Each complex type has the same <a href="object" title="c/language/object">object representation</a> and <a href="object" title="c/language/object">alignment requirements</a> as an <a href="array" title="c/language/array">array</a> of two elements of the corresponding real type (<code>float</code> for <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>double</code> for <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>long double</code> for <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>). The first element of the array holds the real part, and the second element of the array holds the imaginary component.</p> +<div class="c source-c"><pre data-language="c">float a[4] = {1, 2, 3, 4}; +float complex z1, z2; +memcpy(&z1, a, sizeof z1); // z1 becomes 1.0 + 2.0i +memcpy(&z2, a+2, sizeof z2); // z2 becomes 3.0 + 4.0i</pre></div> <p>Complex numbers may be used with <a href="operator_arithmetic" title="c/language/operator arithmetic">arithmetic operators</a> + - * and /, possibly mixed with imaginary and real numbers. There are many mathematical functions defined for complex numbers in <a href="../numeric/complex" title="c/numeric/complex"><code><complex.h></code></a>. Both built-in operators and library functions may raise floating-point exceptions and set <code><a href="../error/errno" title="c/error/errno">errno</a></code> as described in <a href="../numeric/math/math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>Increment and decrement are not defined for complex types.</p> +<p>Relational operators are not defined for complex types (there is no notion of "less than"). <a href="conversion" title="c/language/conversion">Implicit conversions</a> are defined between complex types and other arithmetic types.</p> +<p>In order to support the one-infinity model of complex number arithmetic, C regards any complex value with at least one infinite part as an infinity even if its other part is a NaN, guarantees that all operators and functions honor basic properties of infinities and provides <code><a href="../numeric/complex/cproj" title="c/numeric/complex/cproj">cproj</a></code> to map all infinities to the canonical one (see <a href="operator_arithmetic" title="c/language/operator arithmetic">arithmetic operators</a> for the exact rules).</p> +<div class="c source-c"><pre data-language="c">#include <complex.h> +#include <math.h> +#include <stdio.h> + +int main(void) +{ + double complex z = (1 + 0*I) * (INFINITY + I*INFINITY); +// textbook formula would give +// (1+i0)(∞+i∞) ⇒ (1×∞ – 0×∞) + i(0×∞+1×∞) ⇒ NaN + I*NaN +// but C gives a complex infinity + printf("%f%+f*i\n", creal(z), cimag(z)); + +// textbook formula would give +// cexp(∞+iNaN) ⇒ exp(∞)×(cis(NaN)) ⇒ NaN + I*NaN +// but C gives ±∞+i*nan + double complex y = cexp(INFINITY + I*NAN); + printf("%f%+f*i\n", creal(y), cimag(y)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">inf+inf*i +inf+nan*i</pre></div> <p>C also treats multiple infinities so as to preserve directional information where possible, despite the inherent limitations of the Cartesian representation:</p> +<p>multiplying the imaginary unit by real infinity gives the correctly-signed imaginary infinity: i × ∞ = i∞. Also, i × (∞ – i∞) = ∞ + i∞ indicates the reasonable quadrant.</p> +<h3 id="Imaginary_floating_types"> Imaginary floating types</h3> <p>Imaginary floating types model the mathematical <a href="https://en.wikipedia.org/wiki/imaginary_numbers" class="extiw" title="enwiki:imaginary numbers">imaginary numbers</a>, that is numbers that can be written as a real number multiplied by the imaginary unit: bi The three imaginary types are</p> +<ul> +<li> <code>float _Imaginary</code> (also available as <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code> if <a href="../numeric/complex" title="c/numeric/complex"><code><complex.h></code></a> is included) </li> +<li> <code>double _Imaginary</code> (also available as <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code> if <a href="../numeric/complex" title="c/numeric/complex"><code><complex.h></code></a> is included) </li> +<li> <code>long double _Imaginary</code> (also available as <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code> if <a href="../numeric/complex" title="c/numeric/complex"><code><complex.h></code></a> is included) </li> +</ul> <p>Note: as with all type specifiers, any order is permitted: <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a> <span class="kw4">long</span> <span class="kw4">double</span></code>, and even <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a> <span class="kw4">long</span></code> name the same type.</p> +<div class="c source-c"><pre data-language="c">#include <complex.h> +#include <stdio.h> + +int main(void) +{ + double imaginary z = 3*I; + z = 1 / z; + printf("1/(3.0i) = %+.1fi\n", cimag(z)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">1/(3.0i) = -0.3i</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-until-c11"> +<td> <p>An implementation that defines <code>__STDC_IEC_559_COMPLEX__</code> is recommended, but not required to support imaginary numbers. POSIX recommends checking if the macro <code><a href="../numeric/complex/imaginary_i" title="c/numeric/complex/Imaginary I">_Imaginary_I</a></code> is defined to identify imaginary number support.</p> +</td> <td><span class="t-mark-rev t-until-c11">(until C11)</span></td> +</tr> <tr class="t-rev t-since-c11"> +<td> <p>Imaginary numbers are supported if <span class="t-rev-inl t-until-c23"><span><code>__STDC_IEC_559_COMPLEX__</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>__STDC_IEC_60559_COMPLEX__</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> is defined.</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <p>Each of the three imaginary types has the same <a href="object" title="c/language/object">object representation</a> and <a href="object" title="c/language/object">alignment requirement</a> as its <i>corresponding real type</i> (<code>float</code> for <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, <code>double</code> for <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, <code>long double</code> for <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>).</p> +<p>Note: despite that, imaginary types are distinct and <a href="type#Compatible_types" title="c/language/type">not compatible</a> with their corresponding real types, which prohibits aliasing.</p> +<p>Imaginary numbers may be used with <a href="operator_arithmetic" title="c/language/operator arithmetic">arithmetic operators</a> + - * and /, possibly mixed with complex and real numbers. There are many mathematical functions defined for imaginary numbers in <a href="../numeric/complex" title="c/numeric/complex"><code><complex.h></code></a>. Both built-in operators and library functions may raise floating-point exceptions and set <code><a href="../error/errno" title="c/error/errno">errno</a></code> as described in <a href="../numeric/math/math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>Increment and decrement are not defined for imaginary types. <a href="conversion" title="c/language/conversion">Implicit conversions</a> are defined between imaginary types and other arithmetic types.</p> +<p>The imaginary numbers make it possible to express all complex numbers using the natural notation <code>x + I*y</code> (where <code>I</code> is defined as <code><a href="../numeric/complex/imaginary_i" title="c/numeric/complex/Imaginary I">_Imaginary_I</a></code>). Without imaginary types, certain special complex values cannot be created naturally. For example, if <code>I</code> is defined as <code><a href="../numeric/complex/complex_i" title="c/numeric/complex/Complex I">_Complex_I</a></code>, then writing <code>0.0 + I*INFINITY</code> gives NaN as the real part, and <code><a href="http://en.cppreference.com/w/c/numeric/complex/CMPLX"><span class="kw748">CMPLX</span></a><span class="br0">(</span><span class="nu16">0.0</span>, INFINITY<span class="br0">)</span></code> must be used instead. Same goes for the numbers with the negative zero imaginary component, which are meaningful when working with the library functions with branch cuts, such as <code><a href="../numeric/complex/csqrt" title="c/numeric/complex/csqrt">csqrt</a></code>: <code>1.0 - 0.0*I</code> results in the positive zero imaginary component if <code>I</code> is defined as <code><a href="../numeric/complex/complex_i" title="c/numeric/complex/Complex I">_Complex_I</a></code> and the negative zero imaginary part requires the use of <code><a href="../numeric/complex/cmplx" title="c/numeric/complex/CMPLX">CMPLX</a></code> or <code><a href="../numeric/complex/conj" title="c/numeric/complex/conj">conj</a></code>.</p> +<p>Imaginary types also simplify implementations; multiplication of an imaginary by a complex can be implemented straightforwardly with two multiplications if the imaginary types are supported, instead of four multiplications and two additions.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Keywords"> Keywords</h3> <ul> +<li> <a href="../keyword/bool" title="c/keyword/bool"><code>bool</code></a>, <a href="../keyword/true" title="c/keyword/true"><code>true</code></a>, <a href="../keyword/false" title="c/keyword/false"><code>false</code></a>, <a href="../keyword/char" title="c/keyword/char"><code>char</code></a>, <a href="../keyword/int" title="c/keyword/int"><code>int</code></a>, <a href="../keyword/short" title="c/keyword/short"><code>short</code></a>, <a href="../keyword/long" title="c/keyword/long"><code>long</code></a>, <a href="../keyword/signed" title="c/keyword/signed"><code>signed</code></a>, <a href="../keyword/unsigned" title="c/keyword/unsigned"><code>unsigned</code></a>, <a href="../keyword/float" title="c/keyword/float"><code>float</code></a>, <a href="../keyword/double" title="c/keyword/double"><code>double</code></a>. </li> +<li> <a href="../keyword/_bool" title="c/keyword/ Bool"><code>_Bool</code></a>, <a href="https://en.cppreference.com/mwiki/index.php?title=c/keyword/_BitInt&action=edit&redlink=1" class="new" title="c/keyword/ BitInt (page does not exist)"><code>_BitInt</code></a>, <a href="../keyword/_complex" title="c/keyword/ Complex"><code>_Complex</code></a>, <a href="../keyword/_imaginary" title="c/keyword/ Imaginary"><code>_Imaginary</code></a>, <a href="../keyword/_decimal32" title="c/keyword/ Decimal32"><code>_Decimal32</code></a>, <a href="../keyword/_decimal64" title="c/keyword/ Decimal64"><code>_Decimal64</code></a>, <a href="../keyword/_decimal128" title="c/keyword/ Decimal128"><code>_Decimal128</code></a>. </li> +</ul> <h3 id="Range_of_values"> Range of values</h3> <p>The following table provides a reference for the limits of common numeric representations.</p> +<p>Prior to C23, the C Standard allowed any signed integer representation, and the minimum guaranteed range of N-bit signed integers was from \(\scriptsize -(2^{N-1}-1)\)-(2<sup class="t-su">N-1</sup>-1) to \(\scriptsize +2^{N-1}-1\)+2<sup class="t-su">N-1</sup>-1 (e.g. <b>-127</b> to <b>127</b> for a signed 8-bit type), which corresponds to the limits of <a href="https://en.wikipedia.org/wiki/one%27s_complement" class="extiw" title="enwiki:one's complement">one's complement</a> or <a href="https://en.wikipedia.org/wiki/Signed_number_representations#Sign-and-magnitude_method" class="extiw" title="enwiki:Signed number representations">sign-and-magnitude</a>.</p> +<p>However, all popular data models (including all of ILP32, LP32, LP64, LLP64) and almost all C compilers use <a href="https://en.wikipedia.org/wiki/two%27s_complement" class="extiw" title="enwiki:two's complement">two's complement</a> representation (the only known exceptions are some compliers for UNISYS), and as of C23, it is the only representation allowed by the standard, with the guaranteed range from \(\scriptsize -2^{N-1}\)-2<sup class="t-su">N-1</sup> to \(\scriptsize +2^{N-1}-1\)+2<sup class="t-su">N-1</sup>-1 (e.g. <b>-128</b> to <b>127</b> for a signed 8-bit type).</p> +<table class="wikitable"> <tr> <th rowspan="2">Type </th> <th rowspan="2">Size in bits </th> <th rowspan="2">Format </th> <th colspan="2">Value range </th> +</tr> <tr> <th> Approximate </th> <th> Exact </th> +</tr> <tr> <th rowspan="4">character </th> <td rowspan="2">8 </td> <td>signed </td> <td> </td> <td> +<b>−128</b> to <b>127</b> </td> +</tr> <tr> <td>unsigned </td> <td> </td> <td> +<b>0</b> to <b>255</b> </td> +</tr> <tr> <td>16 </td> <td>UTF-16 </td> <td> </td> <td> +<b>0</b> to <b>65535</b> </td> +</tr> <tr> <td>32 </td> <td>UTF-32 </td> <td> </td> <td> +<b>0</b> to <b>1114111</b> (<b>0x10ffff</b>) </td> +</tr> <tr> <th rowspan="6">integer </th> <td rowspan="2">16 </td> <td>signed </td> <td> +<b>± 3.27 · 10<sup>4</sup></b> </td> <td> +<b>−32768</b> to <b>32767</b> </td> +</tr> <tr> <td>unsigned </td> <td> +<b>0</b> to <b>6.55 · 10<sup>4</sup></b> </td> <td> +<b>0</b> to <b>65535</b> </td> +</tr> <tr> <td rowspan="2">32 </td> <td>signed </td> <td> +<b>± 2.14 · 10<sup>9</sup></b> </td> <td> +<b>−2,147,483,648</b> to <b>2,147,483,647</b> </td> +</tr> <tr> <td>unsigned </td> <td> +<b>0</b> to <b>4.29 · 10<sup>9</sup></b> </td> <td> +<b>0</b> to <b>4,294,967,295</b> </td> +</tr> <tr> <td rowspan="2">64 </td> <td>signed </td> <td> +<b>± 9.22 · 10<sup>18</sup></b> </td> <td> +<b>−9,223,372,036,854,775,808</b> to <b>9,223,372,036,854,775,807</b> </td> +</tr> <tr> <td>unsigned </td> <td> +<b>0</b> to <b>1.84 · 10<sup>19</sup></b> </td> <td> +<b>0</b> to <b>18,446,744,073,709,551,615</b> </td> +</tr> <tr> <th rowspan="4">binary<br> floating<br> point </th> <td>32 </td> <td> +<a href="https://en.wikipedia.org/wiki/Single-precision_floating-point_format" class="extiw" title="enwiki:Single-precision floating-point format">IEEE-754</a> </td> <td> <ul> +<li>min subnormal:<br><b>± 1.401,298,4 · 10<sup>−45</sup></b> </li> +<li>min normal:<br><b>± 1.175,494,3 · 10<sup>−38</sup></b> </li> +<li>max:<br><b>± 3.402,823,4 · 10<sup>38</sup></b> </li> +</ul> </td> <td> <ul> +<li>min subnormal:<br><b>±0x1p−149</b> </li> +<li>min normal:<br><b>±0x1p−126</b> </li> +<li>max:<br><b>±0x1.fffffep+127</b> </li> +</ul> </td> +</tr> <tr> <td>64 </td> <td> +<a href="https://en.wikipedia.org/wiki/Double-precision_floating-point_format" class="extiw" title="enwiki:Double-precision floating-point format">IEEE-754</a> </td> <td> <ul> +<li>min subnormal:<br><b>± 4.940,656,458,412 · 10<sup>−324</sup></b> </li> +<li>min normal:<br><b>± 2.225,073,858,507,201,4 · 10<sup>−308</sup></b> </li> +<li>max:<br><b>± 1.797,693,134,862,315,7 · 10<sup>308</sup></b> </li> +</ul> </td> <td> <ul> +<li>min subnormal:<br><b>±0x1p−1074</b> </li> +<li>min normal:<br><b>±0x1p−1022</b> </li> +<li>max:<br><b>±0x1.fffffffffffffp+1023</b> </li> +</ul> </td> +</tr> <tr> <td>80<sup id="cite_ref-1" class="reference"><a href="#cite_note-1">[note 1]</a></sup> </td> <td> +<a href="https://en.wikipedia.org/wiki/Extended_precision" class="extiw" title="enwiki:Extended precision">x86</a> </td> <td> <ul> +<li>min subnormal:<br><b>± 3.645,199,531,882,474,602,528<br> · 10<sup>−4951</sup></b> </li> +<li>min normal:<br><b>± 3.362,103,143,112,093,506,263<br> · 10<sup>−4932</sup></b> </li> +<li>max:<br><b>± 1.189,731,495,357,231,765,021<br> · 10<sup>4932</sup></b> </li> +</ul> </td> <td> <ul> +<li>min subnormal:<br><b>±0x1p−16445</b> </li> +<li>min normal:<br><b>±0x1p−16382</b> </li> +<li>max:<br><b>±0x1.fffffffffffffffep+16383</b> </li> +</ul> </td> +</tr> <tr> <td>128 </td> <td> +<a href="https://en.wikipedia.org/wiki/Quadruple-precision_floating-point_format" class="extiw" title="enwiki:Quadruple-precision floating-point format">IEEE-754</a> </td> <td> <ul> +<li>min subnormal:<br><b>± 6.475,175,119,438,025,110,924,<br>438,958,227,646,552,5 · 10<sup>−4966</sup></b> </li> +<li>min normal:<br><b>± 3.362,103,143,112,093,506,262,<br>677,817,321,752,602,6 · 10<sup>−4932</sup></b> </li> +<li>max:<br><b>± 1.189,731,495,357,231,765,085,<br>759,326,628,007,016,2 · 10<sup>4932</sup></b> </li> +</ul> </td> <td> <ul> +<li>min subnormal:<br><b>±0x1p−16494</b> </li> +<li>min normal:<br><b>±0x1p−16382</b> </li> +<li>max:<br><b>±0x1.ffffffffffffffffffffffffffff<br>p+16383</b> </li> +</ul> </td> +</tr> <tr> <th rowspan="3"> decimal<br> floating<br> point </th> <td> 32 </td> <td> <a href="https://en.wikipedia.org/wiki/decimal32_floating-point_format" class="extiw" title="enwiki:decimal32 floating-point format">IEEE-754</a> </td> <td> </td> <td> <ul> +<li>min subnormal:<br><b>± 1 · 10<sup>-101</sup></b> </li> +<li>min normal:<br><b>± 1 · 10<sup>-95</sup></b> </li> +<li>max:<br><b>± 9.999'999 · 10<sup>96</sup></b> </li> +</ul> </td> +</tr> <tr> <td> 64 </td> <td> <a href="https://en.wikipedia.org/wiki/decimal64_floating-point_format" class="extiw" title="enwiki:decimal64 floating-point format">IEEE-754</a> </td> <td> </td> <td> <ul> +<li>min subnormal:<br><b>± 1 · 10<sup>-398</sup></b> </li> +<li>min normal:<br><b>± 1 · 10<sup>-383</sup></b> </li> +<li>max:<br><b>± 9.999'999'999'999'999 · 10<sup>384</sup></b> </li> +</ul> </td> +</tr> <tr> <td> 128 </td> <td> <a href="https://en.wikipedia.org/wiki/decimal128_floating-point_format" class="extiw" title="enwiki:decimal128 floating-point format">IEEE-754</a> </td> <td> </td> <td> <ul> +<li>min subnormal:<br><b>± 1 · 10<sup>-6176</sup></b> </li> +<li>min normal:<br><b>± 1 · 10<sup>-6143</sup></b> </li> +<li>max:<br><b>± 9.999'999'999'999'999'999'<br>999'999'999'999'999 · 10<sup>6144</sup></b> </li> +</ul> </td> +</tr> +</table> <ol class="references"> <li id="cite_note-1"> <span class="reference-text">The object representation usually occupies 96/128 bits on 32/64-bit platforms respectively.</span> </li> </ol> <p>Note: actual (as opposed to guaranteed minimal) ranges are available in the library headers <a href="../types/limits" title="c/types/limits"><code><limits.h></code></a> and <a href="../types/limits#Limits_of_floating_point_types" title="c/types/limits"><code><float.h></code></a>.</p> +<h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/types" title="cpp/language/types">C++ documentation</a></span> for <span class=""><span>Fundamental types</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/arithmetic_types" class="_attribution-link">https://en.cppreference.com/w/c/language/arithmetic_types</a> + </p> +</div> diff --git a/devdocs/c/language%2Farray.html b/devdocs/c/language%2Farray.html new file mode 100644 index 00000000..34623494 --- /dev/null +++ b/devdocs/c/language%2Farray.html @@ -0,0 +1,198 @@ + <h1 id="firstHeading" class="firstHeading">Array declaration</h1> <p>Array is a type consisting of a contiguously allocated nonempty sequence of objects with a particular <i>element type</i>. The number of those objects (the array size) never changes during the array lifetime.</p> +<h3 id="Syntax"> Syntax</h3> <p>In the <a href="declarations" title="c/language/declarations">declaration grammar</a> of an array declaration, the <i>type-specifier</i> sequence designates the <i>element type</i> (which must be a complete object type), and the <i>declarator</i> has the form:</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>[</code> <code>static</code><span class="t-mark">(optional)</span> <span class="t-spar">qualifiers</span> <span class="t-mark">(optional)</span> <span class="t-spar">expression</span> <span class="t-mark">(optional)</span> <code>]</code> <span class="t-spar">attr-spec-seq</span> <span class="t-mark">(optional)</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>[</code> <span class="t-spar">qualifiers</span> <span class="t-mark">(optional)</span> <code>static</code><span class="t-mark">(optional)</span> <span class="t-spar">expression</span> <span class="t-mark">(optional)</span> <code>]</code> <span class="t-spar">attr-spec-seq</span> <span class="t-mark">(optional)</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>[</code> <span class="t-spar">qualifiers</span> <span class="t-mark">(optional)</span> <code>*</code> <code>]</code> <span class="t-spar">attr-spec-seq</span> <span class="t-mark">(optional)</span> </td> <td> (3) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1,2)</span> General array declarator syntax</div> <div class="t-li1"> +<span class="t-li">3)</span> Declarator for VLA of unspecified size (can appear in function prototype scope only) where</div> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">expression</span> </td> <td> - </td> <td> any expression other than <a href="operator_other#Comma_operator" title="c/language/operator other">comma operator</a>, designates the number of elements in the array </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">qualifiers</span> </td> <td> - </td> <td> any combination of <a href="const" title="c/language/const"><code>const</code></a>, <a href="restrict" title="c/language/restrict"><code>restrict</code></a>, or <a href="volatile" title="c/language/volatile"><code>volatile</code></a> qualifiers, only allowed in function parameter lists; this qualifies the pointer type to which this array parameter is transformed </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">attr-spec-seq</span> </td> <td> - </td> <td> <span class="t-mark-rev t-since-c23">(C23)</span>optional list of <a href="attributes" title="c/language/attributes">attributes</a>, applied to the declared array </td> +</tr> +</table> <div class="c source-c"><pre data-language="c">float fa[11], *afp[17]; // fa is an array of 11 floats + // afp is an array of 17 pointers to floats</pre></div> <h3 id="Explanation"> Explanation</h3> <p>There are several variations of array types: arrays of known constant size, variable-length arrays, and arrays of unknown size.</p> +<h4 id="Arrays_of_constant_known_size"> Arrays of constant known size</h4> <p>If <span class="t-spar">expression</span> in an array declarator is an <a href="constant_expression#Integer_constant_expression" title="c/language/constant expression">integer constant expression</a> with a value greater than zero <span class="t-rev-inl t-since-c99"><span>and the element type is a type with a known constant size (that is, elements are not VLA)</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>, then the declarator declares an array of constant known size:</p> +<div class="c source-c"><pre data-language="c">int n[10]; // integer constants are constant expressions +char o[sizeof(double)]; // sizeof is a constant expression +enum { MAX_SZ=100 }; +int n[MAX_SZ]; // enum constants are constant expressions</pre></div> <p>Arrays of constant known size can use <a href="array_initialization" title="c/language/array initialization">array initializers</a> to provide their initial values:</p> +<div class="c source-c"><pre data-language="c">int a[5] = {1,2,3}; // declares int[5] initialized to 1,2,3,0,0 +char str[] = "abc"; // declares char[4] initialized to 'a','b','c','\0'</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>In function parameter lists, additional syntax elements are allowed within the array declarators: the keyword <code>static</code> and <span class="t-spar">qualifiers</span>, which may appear in any order before the size expression (they may also appear even when the size expression is omitted).</p> +<p>In each <a href="operator_other#Function_call" title="c/language/operator other">function call</a> to a function where an array parameter uses the keyword <code>static</code> between <code>[</code> and <code>]</code>, the value of the actual parameter must be a valid pointer to the first element of an array with at least as many elements as specified by <span class="t-spar">expression</span>:</p> +<div class="c source-c"><pre data-language="c">void fadd(double a[static 10], const double b[static 10]) +{ + for (int i = 0; i < 10; i++) + { + if (a[i] < 0.0) return; + a[i] += b[i]; + } +} +// a call to fadd may perform compile-time bounds checking +// and also permits optimizations such as prefetching 10 doubles +int main(void) +{ + double a[10] = {0}, b[20] = {0}; + fadd(a, b); // OK + double x[5] = {0}; + fadd(x, b); // undefined behavior: array argument is too small +}</pre></div> <p>If <span class="t-spar">qualifiers</span> are present, they qualify the pointer type to which the array parameter type is transformed:</p> +<div class="c source-c"><pre data-language="c">int f(const int a[20]) +{ + // in this function, a has type const int* (pointer to const int) +} +int g(const int a[const 20]) +{ + // in this function, a has type const int* const (const pointer to const int) +}</pre></div> <p>This is commonly used with the <a href="restrict" title="c/language/restrict"><code>restrict</code></a> type qualifier:</p> +<div class="c source-c"><pre data-language="c">void fadd(double a[static restrict 10], + const double b[static restrict 10]) +{ + for (int i = 0; i < 10; i++) // loop can be unrolled and reordered + { + if (a[i] < 0.0) + break; + a[i] += b[i]; + } +}</pre></div> <h4 id="Variable-length_arrays"> Variable-length arrays</h4> <p>If <span class="t-spar">expression</span> is not an <a href="constant_expression#Integer_constant_expression" title="c/language/constant expression">integer constant expression</a>, the declarator is for an array of variable size.</p> +<p>Each time the flow of control passes over the declaration, <span class="t-spar">expression</span> is evaluated (and it must always evaluate to a value greater than zero), and the array is allocated (correspondingly, <a href="lifetime" title="c/language/lifetime">lifetime</a> of a VLA ends when the declaration goes out of scope). The size of each VLA instance does not change during its lifetime, but on another pass over the same code, it may be allocated with a different size.</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> + +int main(void) +{ + int n = 1; +label:; + int a[n]; // re-allocated 10 times, each with a different size + printf("The array has %zu elements\n", sizeof a / sizeof *a); + if (n++ < 10) + goto label; // leaving the scope of a VLA ends its lifetime +}</pre></div> <p>If the size is <code>*</code>, the declaration is for a VLA of unspecified size. Such declaration may only appear in a function prototype scope, and declares an array of a complete type. In fact, all VLA declarators in function prototype scope are treated as if <span class="t-spar">expression</span> were replaced by <code>*</code>.</p> +<div class="c source-c"><pre data-language="c">void foo(size_t x, int a[*]); +void foo(size_t x, int a[x]) +{ + printf("%zu\n", sizeof a); // same as sizeof(int*) +}</pre></div> <p>Variable-length arrays and the types derived from them (pointers to them, etc) are commonly known as "variably-modified types" (VM). Objects of any variably-modified type may only be declared at block scope or function prototype scope.</p> +<div class="c source-c"><pre data-language="c">extern int n; +int A[n]; // Error: file scope VLA +extern int (*p2)[n]; // Error: file scope VM +int B[100]; // OK: file-scope array of constant known size +void fvla(int m, int C[m][m]); // OK: prototype-scope VLA</pre></div> <p>VLA must have automatic or allocated storage duration. Pointers to VLA, but not VLA themselves may also have static storage duration. No VM type may have linkage.</p> +<div class="c source-c"><pre data-language="c">void fvla(int m, int C[m][m]) // OK: block scope/auto duration pointer to VLA +{ + typedef int VLA[m][m]; // OK: block scope VLA + int D[m]; // OK: block scope/auto duration VLA +// static int E[m]; // Error: static duration VLA +// extern int F[m]; // Error: VLA with linkage + int (*s)[m]; // OK: block scope/auto duration VM + s = malloc(m * sizeof(int)); // OK: s points to VLA in allocated storage +// extern int (*r)[m]; // Error: VM with linkage + static int (*q)[m] = &B; // OK: block scope/static duration VM} +}</pre></div> <p>Variably-modified types cannot be members of structs or unions.</p> +<div class="c source-c"><pre data-language="c">struct tag +{ + int z[n]; // Error: VLA struct member + int (*y)[n]; // Error: VM struct member +};</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> <tr class="t-rev t-since-c11 t-until-c23"> +<td> <p>If the compiler defines the macro constant <code>__STDC_NO_VLA__</code> to integer constant <code>1</code>, then VLA and VM types are not supported.</p> +</td> <td> +<span class="t-mark-rev t-since-c11">(since C11)</span><br><span class="t-mark-rev t-until-c23">(until C23)</span> +</td> +</tr> <tr class="t-rev t-since-c23"> +<td> <p>If the compiler defines the macro constant <code>__STDC_NO_VLA__</code> to integer constant <code>1</code>, then VLA objects with automatic storage duration are not supported.</p> +<p>The support for VM types and VLAs with allocated storage durations is mandated.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h4 id="Arrays_of_unknown_size"> Arrays of unknown size</h4> <p>If <span class="t-spar">expression</span> in an array declarator is omitted, it declares an array of unknown size. Except in function parameter lists (where such arrays are transformed to pointers) and when an <a href="array_initialization" title="c/language/array initialization">initializer</a> is available, such type is an <a href="type#Incomplete_types" title="c/language/type">incomplete type</a><span class="t-rev-inl t-since-c99"><span> (note that VLA of unspecified size, declared with <code>*</code> as the size, is a complete type)</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>:</p> +<div class="c source-c"><pre data-language="c">extern int x[]; // the type of x is "array of unknown bound of int" +int a[] = {1,2,3}; // the type of a is "array of 3 int"</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>Within a <a href="struct" title="c/language/struct">struct</a> definition, an array of unknown size may appear as the last member (as long as there is at least one other named member), in which case it is a special case known as <i>flexible array member</i>. See <a href="struct" title="c/language/struct">struct</a> for details:</p> +<div class="c source-c"><pre data-language="c">struct s { int n; double d[]; }; // s.d is a flexible array member +struct s *s1 = malloc(sizeof (struct s) + (sizeof (double) * 8)); // as if d was double d[8]</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h4 id="Qualifiers"> Qualifiers</h4> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>If an array type is declared with a <a href="const" title="c/language/const"><code>const</code></a>, <a href="volatile" title="c/language/volatile"><code>volatile</code></a><span class="t-rev-inl t-since-c99"><span>, or <a href="restrict" title="c/language/restrict"><code>restrict</code></a></span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> qualifier (which is possible through the use of <a href="typedef" title="c/language/typedef">typedef</a>), the array type is not qualified, but its element type is:</p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td> <p>An array type and its element type are always considered to be identically qualified, except that an array type is never considered to be <a href="atomic" title="c/language/atomic"><code>_Atomic</code></a>-qualified.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <div class="c source-c"><pre data-language="c">typedef int A[2][3]; +const A a = {{4, 5, 6}, {7, 8, 9}}; // array of array of const int +int* pi = a[0]; // Error: a[0] has type const int* +void* unqual_ptr = a; // OK until C23; error since C23 +// Notes: clang applies the rule in C++/C23 even in C89-C17 modes</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <p><a href="atomic" title="c/language/atomic"><code>_Atomic</code></a> is not allowed to be applied to an array type, although an array of atomic type is allowed.</p> +<div class="c source-c"><pre data-language="c">typedef int A[2]; +// _Atomic A a0 = {0}; // Error +// _Atomic(A) a1 = {0}; // Error +_Atomic int a2[2] = {0}; // OK +_Atomic(int) a3[2] = {0}; // OK</pre></div> </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <h4 id="Assignment"> Assignment</h4> <p>Objects of array type are not <a href="value_category" title="c/language/value category">modifiable lvalues</a>, and although their address may be taken, they cannot appear on the left hand side of an assignment operator. However, structs with array members are modifiable lvalues and can be assigned:</p> +<div class="c source-c"><pre data-language="c">int a[3] = {1,2,3}, b[3] = {4,5,6}; +int (*p)[3] = &a; // okay, address of a can be taken +// a = b; // error, a is an array +struct { int c[3]; } s1, s2 = {3,4,5}; +s1 = s2; // okay: can assign structs holding array members</pre></div> <h4 id="Array_to_pointer_conversion"> Array to pointer conversion</h4> <p>Any <a href="value_category" title="c/language/value category">lvalue expression</a> of array type, when used in any context other than</p> +<ul> +<li> as the operand of the <a href="operator_member_access" title="c/language/operator member access">address-of operator</a> </li> +<li> as the operand of <a href="sizeof" title="c/language/sizeof"><code>sizeof</code></a> </li> +<li> as the operand of <a href="typeof" title="c/language/typeof"><code>typeof</code></a> and <a href="https://en.cppreference.com/mwiki/index.php?title=c/language/typeof_unqual&action=edit&redlink=1" class="new" title="c/language/typeof unqual (page does not exist)"><code>typeof_unqual</code></a> <span class="t-mark-rev t-since-c23">(since C23)</span> </li> +<li> as the string literal used for <a href="array_initialization" title="c/language/array initialization">array initialization</a> </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <ul><li> as the operand of <a href="_alignof" title="c/language/ Alignof"><code>_Alignof</code></a> </li></ul> </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <p>undergoes an <a href="conversion" title="c/language/conversion">implicit conversion</a> to the pointer to its first element. The result is not an lvalue.</p> +<p>If the array was declared <a href="storage_duration" title="c/language/storage duration"><code>register</code></a>, the behavior of the program that attempts such conversion is undefined.</p> +<div class="c source-c"><pre data-language="c">int a[3] = {1,2,3}; +int* p = a; +printf("%zu\n", sizeof a); // prints size of array +printf("%zu\n", sizeof p); // prints size of a pointer</pre></div> <p>When an array type is used in a function parameter list, it is transformed to the corresponding pointer type: <code>int f(int a[2])</code> and <code>int f(int* a)</code> declare the same function. Since the function's actual parameter type is pointer type, a function call with an array argument performs array-to-pointer conversion; the size of the argument array is not available to the called function and must be passed explicitly:</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +void f(int a[], int sz) // actually declares void f(int* a, int sz) +{ + for (int i = 0; i < sz; ++i) + printf("%d\n", a[i]); +} + +void g(int (*a)[10]) // pointer to array parameter is not transformed +{ + for (int i = 0; i < 10; ++i) + printf("%d\n", (*a)[i]); +} + +int main(void) +{ + int a[10] = {0}; + f(a, 10); // converts a to int*, passes the pointer + g(&a); // passes a pointer to the array (no need to pass the size) +}</pre></div> </div> <h4 id="Multidimensional_arrays"> Multidimensional arrays</h4> <p>When the element type of an array is another array, it is said that the array is multidimensional:</p> +<div class="c source-c"><pre data-language="c">// array of 2 arrays of 3 ints each +int a[2][3] = {{1,2,3}, // can be viewed as a 2x3 matrix + {4,5,6}}; // with row-major layout</pre></div> <p>Note that when array-to-pointer conversion is applied, a multidimensional array is converted to a pointer to its first element, e.g., pointer to the first row:</p> +<div class="c source-c"><pre data-language="c">int a[2][3]; // 2x3 matrix +int (*p1)[3] = a; // pointer to the first 3-element row +int b[3][3][3]; // 3x3x3 cube +int (*p2)[3][3] = b; // pointer to the first 3x3 plane</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>Multidimensional arrays may be variably modified in every dimension<span class="t-rev-inl t-since-c11"><span> if VLAs are supported</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span>:</p> +<div class="c source-c"><pre data-language="c">int n = 10; +int a[n][2*n];</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>Zero-length array declarations are not allowed, even though some compilers offer them as extensions (typically as a pre-C99 implementation of <a href="struct" title="c/language/struct">flexible array members</a>).</p> +<p>If the size <span class="t-spar">expression</span> of a VLA has side effects, they are guaranteed to be produced except when it is a part of a sizeof expression whose result doesn't depend on it:</p> +<div class="c source-c"><pre data-language="c">int n = 5; +size_t sz = sizeof(int (*)[n++]); // may or may not increment n</pre></div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.7.6.2 Array declarators (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.7.6.2 Array declarators (p: 94-96) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.7.6.2 Array declarators (p: 130-132) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.7.5.2 Array declarators (p: 116-118) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.5.4.2 Array declarators </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/array" title="cpp/language/array">C++ documentation</a></span> for <span class=""><span>Array declaration</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/array" class="_attribution-link">https://en.cppreference.com/w/c/language/array</a> + </p> +</div> diff --git a/devdocs/c/language%2Farray_initialization.html b/devdocs/c/language%2Farray_initialization.html new file mode 100644 index 00000000..c740231b --- /dev/null +++ b/devdocs/c/language%2Farray_initialization.html @@ -0,0 +1,127 @@ + <h1 id="firstHeading" class="firstHeading">Array initialization</h1> <p>When <a href="initialization" title="c/language/initialization">initializing</a> an object of <a href="array" title="c/language/array">array</a> type, the initializer must be either a <a href="string_literal" title="c/language/string literal">string literal</a> (optionally enclosed in braces) or be a brace-enclosed list of initialized for array members:</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>=</code> <span class="t-spar">string-literal</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>=</code> <code>{</code> <span class="t-spar">expression</span> <code>,</code> <code>...</code> <code>}</code> </td> <td> (2) </td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>=</code> <code>{</code> <span class="t-spar">designator</span><span class="t-mark">(optional)</span> <span class="t-spar">expression</span> <code>,</code> <code>...</code> <code>}</code> </td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>=</code> <code>{</code> <code>}</code> </td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> string literal initializer for character and wide character arrays</div> <div class="t-li1"> +<span class="t-li">2)</span> comma-separated list of <span class="t-rev-inl t-until-c99"><span>constant</span><span><span class="t-mark-rev t-until-c99">(until C99)</span></span></span> expressions that are initializers for array elements<span class="t-rev-inl t-since-c99"><span>, optionally using array designators of the form <code>[</code> <span class="t-spar">constant-expression</span> <code>]</code> <code>=</code> </span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> +</div> <div class="t-li1"> +<span class="t-li">3)</span> empty initializer empty-initializes every element of the array</div> <p>Arrays of known size and arrays of unknown size may be initialized<span class="t-rev-inl t-since-c99 t-until-c23"><span>, but not VLAs</span><span><span class="t-mark-rev t-since-c99">(since C99)</span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span>.<span class="t-rev-inl t-since-c23"><span> A VLA can only be empty-initialized.</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span></p> +<p>All array elements that are not initialized explicitly are <a href="initialization#Empty_initialization" title="c/language/initialization">empty-initialized</a>.</p> +<h3 id="Initialization_from_strings"> Initialization from strings</h3> <p><a href="string_literal" title="c/language/string literal">String literal</a> (optionally enclosed in braces) may be used as the initializer for an array of matching type:</p> +<ul> +<li> ordinary string literals<span class="t-rev-inl t-since-c11"><span> and UTF-8 string literals</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> can initialize arrays of any character type (<code>char</code>, <code>signed char</code>, <code>unsigned char</code>) </li> +<li> L-prefixed wide string literals can be used to initialize arrays of any type compatible with (ignoring cv-qualifications) <code>wchar_t</code> </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <ul> +<li> u-prefixed wide string literals can be used to initialize arrays of any type compatible with (ignoring cv-qualifications) <code>char16_t</code> </li> +<li> U-prefixed wide string literals can be used to initialize arrays of any type compatible with (ignoring cv-qualifications) <code>char32_t</code> </li> +</ul> </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <p>Successive bytes of the string literal or wide characters of the wide string literal, including the terminating null byte/character, initialize the elements of the array:</p> +<div class="c source-c"><pre data-language="c">char str[] = "abc"; // str has type char[4] and holds 'a', 'b', 'c', '\0' +wchar_t wstr[4] = L"猫"; // str has type wchar_t[4] and holds L'猫', '\0', '\0', '\0'</pre></div> <p>If the size of the array is known, it may be one less than the size of the string literal, in which case the terminating null character is ignored:</p> +<div class="c source-c"><pre data-language="c">char str[3] = "abc"; // str has type char[3] and holds 'a', 'b', 'c'</pre></div> <p>Note that the contents of such array are modifiable, unlike when accessing a string literal directly with <code>char* str = "abc";</code>.</p> +<h3 id="Initialization_from_brace-enclosed_lists"> Initialization from brace-enclosed lists</h3> <p>When an array is initialized with a brace-enclosed list of initializers, the first initializer in the list initializes the array element at index zero<span class="t-rev-inl t-since-c99"><span> (unless a designator is specified)</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>, and each subsequent initializer <span class="t-rev-inl t-since-c99"><span>without a designator </span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>initializes the array element at index one greater than the one initialized by the previous initializer.</p> +<div class="c source-c"><pre data-language="c">int x[] = {1,2,3}; // x has type int[3] and holds 1,2,3 +int y[5] = {1,2,3}; // y has type int[5] and holds 1,2,3,0,0 +int z[4] = {1}; // z has type int[4] and holds 1,0,0,0 +int w[3] = {0}; // w has type int[3] and holds all zeroes</pre></div> <p>It's an error to provide more initializers than elements when initializing an array of known size (except when initializing character arrays from string literals).</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>A designator causes the following initializer to initialize of the array element described by the designator. Initialization then continues forward in order, beginning with the next element after the one described by the designator.</p> +<div class="c source-c"><pre data-language="c">int n[5] = {[4]=5,[0]=1,2,3,4}; // holds 1,2,3,4,5 + +int a[MAX] = { // starts initializing a[0] = 1, a[1] = 3, ... + 1, 3, 5, 7, 9, [MAX-5] = 8, 6, 4, 2, 0 +}; +// for MAX=6, array holds 1,8,6,4,2,0 +// for MAX=13, array holds 1,3,5,7,9,0,0,0,8,6,4,2,0 ("sparse array")</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <p>When initializing an array of unknown size, the largest subscript for which an initializer is specified determines the size of the array being declared.</p> +<h3 id="Nested_arrays"> Nested arrays</h3> <p>If the elements of an array are arrays, structs, or unions, the corresponding initializers in the brace-enclosed list of initializers are any initializers that are valid for those members, except that their braces may be omitted as follows:</p> +<p>If the nested initializer begins with an opening brace, the entire nested initializer up to its closing brace initializes the corresponding array element:</p> +<div class="c source-c"><pre data-language="c">int y[4][3] = { // array of 4 arrays of 3 ints each (4x3 matrix) + { 1 }, // row 0 initialized to {1, 0, 0} + { 0, 1 }, // row 1 initialized to {0, 1, 0} + { [2]=1 }, // row 2 initialized to {0, 0, 1} +}; // row 3 initialized to {0, 0, 0}</pre></div> <p>If the nested initializer does not begin with an opening brace, only enough initializers from the list are taken to account for the elements or members of the sub-array, struct or union; any remaining initializers are left to initialize the next array element:</p> +<div class="c source-c"><pre data-language="c">int y[4][3] = { // array of 4 arrays of 3 ints each (4x3 matrix) +1, 3, 5, 2, 4, 6, 3, 5, 7 // row 0 initialized to {1, 3, 5} +}; // row 1 initialized to {2, 4, 6} + // row 2 initialized to {3, 5, 7} + // row 3 initialized to {0, 0, 0} + +struct { int a[3], b; } w[] = { { 1 }, 2 }; // array of structs + // { 1 } is taken to be a fully-braced initializer for element #0 of the array + // that element is initialized to { {1, 0, 0}, 0} + // 2 is taken to be the first initialized for element #1 of the array + // that element is initialized { {2, 0, 0}, 0}</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>Array designators may be nested; the bracketed constant expression for nested arrays follows the bracketed constant expression for the outer array:</p> +<div class="c source-c"><pre data-language="c">int y[4][3] = {[0][0]=1, [1][1]=1, [2][0]=1}; // row 0 initialized to {1, 0, 0} + // row 1 initialized to {0, 1, 0} + // row 2 initialized to {1, 0, 0} + // row 3 initialized to {0, 0, 0}</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>The <a href="eval_order" title="c/language/eval order">order of evaluation</a> of subexpressions in an array initializer is indeterminately sequenced in C (but not in C++ since C++11):</p> +<div class="c source-c"><pre data-language="c">int n = 1; +int a[2] = {n++, n++}; // unspecified, but well-defined behavior, + // n is incremented twice (in arbitrary order) + // a initialized to {1, 2} and to {2, 1} are both valid +puts((char[4]){'0'+n} + n++); // undefined behavior: + // increment and read from n are unsequenced</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>In C, the braced list of an initializer cannot be empty. C++ allows empty list:</p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td> <p>An empty initializer can be used to initialize an array:</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <div class="c source-c"><pre data-language="c">int a[3] = {0}; // valid C and C++ way to zero-out a block-scope array +int a[3] = {}; // valid C++ way to zero-out a block-scope array; valid in C since C23</pre></div> <p>As with all other <a href="initialization" title="c/language/initialization">initialization</a>, every expression in the initializer list must be a <a href="constant_expression" title="c/language/constant expression">constant expression</a> when initializing arrays of static or thread-local <a href="storage_duration" title="c/language/storage duration">storage duration</a>:</p> +<div class="c source-c"><pre data-language="c">static char* p[2] = {malloc(1), malloc(2)}; // error</pre></div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">int main(void) +{ + // The following four array declarations are the same + short q1[4][3][2] = { + { 1 }, + { 2, 3 }, + { 4, 5, 6 } + }; + + short q2[4][3][2] = {1, 0, 0, 0, 0, 0, 2, 3, 0, 0, 0, 0, 4, 5, 6}; + + short q3[4][3][2] = { + { + { 1 }, + }, + { + { 2, 3 }, + }, + { + { 4, 5 }, + { 6 }, + } + }; + + short q4[4][3][2] = {1, [1]=2, 3, [2]=4, 5, 6}; + + + // Character names can be associated with enumeration constants + // using arrays with designators: + enum { RED, GREEN, BLUE }; + const char *nm[] = { + [RED] = "red", + [GREEN] = "green", + [BLUE] = "blue", + }; +}</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.7.9/12-39 Initialization (p: 101-105) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.7.9/12-38 Initialization (p: 140-144) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.7.8/12-38 Initialization (p: 126-130) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 6.5.7 Initialization </li></ul> +</ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/array_initialization" class="_attribution-link">https://en.cppreference.com/w/c/language/array_initialization</a> + </p> +</div> diff --git a/devdocs/c/language%2Fas_if.html b/devdocs/c/language%2Fas_if.html new file mode 100644 index 00000000..19cace76 --- /dev/null +++ b/devdocs/c/language%2Fas_if.html @@ -0,0 +1,20 @@ + <h1 id="firstHeading" class="firstHeading">As-if rule</h1> <p>Allows any and all code transformations that do not change the observable behavior of the program.</p> +<h3 id="Explanation"> Explanation</h3> <p>The C compiler is permitted to perform any changes to the program as long as the following remains true:</p> +<table class="t-rev-begin"> <tr class="t-rev t-until-c11"> +<td> <span class="t-li">1)</span> At every <a href="eval_order" title="c/language/eval order">sequence point</a>, the values of all <a href="volatile" title="c/language/volatile">volatile</a> objects are stable (previous evaluations are complete, new evaluations not started). </td> <td><span class="t-mark-rev t-until-c11">(until C11)</span></td> +</tr> <tr class="t-rev t-since-c11"> +<td> <span class="t-li">1)</span> Accesses (reads and writes) to <a href="volatile" title="c/language/volatile">volatile</a> objects occur strictly according to the semantics of the expressions in which they occur. In particular, they are <a href="../atomic/memory_order" title="c/atomic/memory order">not reordered</a> with respect to other volatile accesses on the same thread. </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <div class="t-li1"> +<span class="t-li">2)</span> At program termination, data written to files is exactly as if the program was executed as written.</div> <div class="t-li1"> +<span class="t-li">3)</span> Prompting text which is sent to interactive devices will be shown before the program waits for input.</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <span class="t-li">4)</span> If the pragma <a href="../preprocessor/impl#Standard_pragmas" title="c/preprocessor/impl"><code> #pragma STDC FENV_ACCESS</code></a> is supported and is set to <code>ON</code>, the changes to the <a href="../numeric/fenv" title="c/numeric/fenv">floating-point environment</a> (floating-point exceptions and rounding modes) are guaranteed to be observed by the floating-point arithmetic operators and function calls as if executed as written, except that <ul> +<li> the result of any floating-point expression other than cast and assignment may have range and precision of a floating-point type different from the type of the expression (see <code><a href="../types/limits/flt_eval_method" title="c/types/limits/FLT EVAL METHOD">FLT_EVAL_METHOD</a></code>), </li> +<li> notwithstanding the above, intermediate results of any floating-point expression may be calculated as if to infinite range and precision (unless <a href="../preprocessor/impl#Standard_pragmas" title="c/preprocessor/impl"><code> #pragma STDC FP_CONTRACT</code></a> is <code>OFF</code>).</li> +</ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <h3 id="See_also"> See also</h3> <ul><li> <a href="eval_order" title="c/language/eval order">Order of evaluation</a> </li></ul> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/as_if" title="cpp/language/as if">C++ documentation</a></span> for <span class=""><span>as-if rule</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/as_if" class="_attribution-link">https://en.cppreference.com/w/c/language/as_if</a> + </p> +</div> diff --git a/devdocs/c/language%2Fascii.html b/devdocs/c/language%2Fascii.html new file mode 100644 index 00000000..696f68cf --- /dev/null +++ b/devdocs/c/language%2Fascii.html @@ -0,0 +1,131 @@ + <h1 id="firstHeading" class="firstHeading">ASCII Chart</h1> <p>The following chart contains all 128 ASCII decimal <b>(dec)</b>, octal <b>(oct)</b>, hexadecimal <b>(hex)</b> and character <b>(ch)</b> codes.</p> +<table class="wikitable"> <tr> <th><code>dec</code></th> <th><code>oct</code></th> <th> +<code>hex</code> </th> <th> +<code>ch</code> </th> <td rowspan="33"> </td> <th><code>dec</code></th> <th><code>oct</code></th> <th> +<code>hex</code> </th> <th> +<code>ch</code> </th> <td rowspan="33"> </td> <th><code>dec</code></th> <th><code>oct</code></th> <th> +<code>hex</code> </th> <th> +<code>ch</code> </th> <td rowspan="33"> </td> <th><code>dec</code></th> <th><code>oct</code></th> <th> +<code>hex</code> </th> <th> +<code>ch</code> </th> +</tr> <tr> <td><code>0</code></td> <td><code>0</code></td> <td><code>00</code></td> <td> +<code>NUL</code> (null)</td> <td><code>32</code></td> <td><code>40</code></td> <td><code>20</code></td> <td>(space)</td> <td><code>64</code></td> <td><code>100</code></td> <td><code>40</code></td> <td><code>@</code></td> <td><code>96</code></td> <td><code>140</code></td> <td><code>60</code></td> <td> +<code>`</code> </td> +</tr> <tr> <td><code>1</code></td> <td><code>1</code></td> <td><code>01</code></td> <td> +<code>SOH</code> (start of header)</td> <td><code>33</code></td> <td><code>41</code></td> <td><code>21</code></td> <td><code>!</code></td> <td><code>65</code></td> <td><code>101</code></td> <td><code>41</code></td> <td><code>A</code></td> <td><code>97</code></td> <td><code>141</code></td> <td><code>61</code></td> <td> +<code>a</code> </td> +</tr> <tr> <td><code>2</code></td> <td><code>2</code></td> <td><code>02</code></td> <td> +<code>STX</code> (start of text)</td> <td><code>34</code></td> <td><code>42</code></td> <td><code>22</code></td> <td><code>"</code></td> <td><code>66</code></td> <td><code>102</code></td> <td><code>42</code></td> <td><code>B</code></td> <td><code>98</code></td> <td><code>142</code></td> <td><code>62</code></td> <td> +<code>b</code> </td> +</tr> <tr> <td><code>3</code></td> <td><code>3</code></td> <td><code>03</code></td> <td> +<code>ETX</code> (end of text)</td> <td><code>35</code></td> <td><code>43</code></td> <td><code>23</code></td> <td><code>#</code></td> <td><code>67</code></td> <td><code>103</code></td> <td><code>43</code></td> <td><code>C</code></td> <td><code>99</code></td> <td><code>143</code></td> <td><code>63</code></td> <td> +<code>c</code> </td> +</tr> <tr> <td><code>4</code></td> <td><code>4</code></td> <td><code>04</code></td> <td> +<code>EOT</code> (end of transmission)</td> <td><code>36</code></td> <td><code>44</code></td> <td><code>24</code></td> <td><code>$</code></td> <td><code>68</code></td> <td><code>104</code></td> <td><code>44</code></td> <td><code>D</code></td> <td><code>100</code></td> <td><code>144</code></td> <td><code>64</code></td> <td> +<code>d</code> </td> +</tr> <tr> <td><code>5</code></td> <td><code>5</code></td> <td><code>05</code></td> <td> +<code>ENQ</code> (enquiry)</td> <td><code>37</code></td> <td><code>45</code></td> <td><code>25</code></td> <td><code>%</code></td> <td><code>69</code></td> <td><code>105</code></td> <td><code>45</code></td> <td><code>E</code></td> <td><code>101</code></td> <td><code>145</code></td> <td><code>65</code></td> <td> +<code>e</code> </td> +</tr> <tr> <td><code>6</code></td> <td><code>6</code></td> <td><code>06</code></td> <td> +<code>ACK</code> (acknowledge)</td> <td><code>38</code></td> <td><code>46</code></td> <td><code>26</code></td> <td><code>&</code></td> <td><code>70</code></td> <td><code>106</code></td> <td><code>46</code></td> <td><code>F</code></td> <td><code>102</code></td> <td><code>146</code></td> <td><code>66</code></td> <td> +<code>f</code> </td> +</tr> <tr> <td><code>7</code></td> <td><code>7</code></td> <td><code>07</code></td> <td> +<code>BEL</code> (bell)</td> <td><code>39</code></td> <td><code>47</code></td> <td><code>27</code></td> <td><code>'</code></td> <td><code>71</code></td> <td><code>107</code></td> <td><code>47</code></td> <td><code>G</code></td> <td><code>103</code></td> <td><code>147</code></td> <td><code>67</code></td> <td> +<code>g</code> </td> +</tr> <tr> <td><code>8</code></td> <td><code>10</code></td> <td><code>08</code></td> <td> +<code>BS</code> (backspace)</td> <td><code>40</code></td> <td><code>50</code></td> <td><code>28</code></td> <td><code>(</code></td> <td><code>72</code></td> <td><code>110</code></td> <td><code>48</code></td> <td><code>H</code></td> <td><code>104</code></td> <td><code>150</code></td> <td><code>68</code></td> <td> +<code>h</code> </td> +</tr> <tr> <td><code>9</code></td> <td><code>11</code></td> <td><code>09</code></td> <td> +<code>HT</code> (horizontal tab)</td> <td><code>41</code></td> <td><code>51</code></td> <td><code>29</code></td> <td><code>)</code></td> <td><code>73</code></td> <td><code>111</code></td> <td><code>49</code></td> <td><code>I</code></td> <td><code>105</code></td> <td><code>151</code></td> <td><code>69</code></td> <td> +<code>i</code> </td> +</tr> <tr> <td><code>10</code></td> <td><code>12</code></td> <td><code>0a</code></td> <td> +<code>LF</code> (line feed - new line)</td> <td><code>42</code></td> <td><code>52</code></td> <td><code>2a</code></td> <td><code>*</code></td> <td><code>74</code></td> <td><code>112</code></td> <td><code>4a</code></td> <td><code>J</code></td> <td><code>106</code></td> <td><code>152</code></td> <td><code>6a</code></td> <td> +<code>j</code> </td> +</tr> <tr> <td><code>11</code></td> <td><code>13</code></td> <td><code>0b</code></td> <td> +<code>VT</code> (vertical tab)</td> <td><code>43</code></td> <td><code>53</code></td> <td><code>2b</code></td> <td><code>+</code></td> <td><code>75</code></td> <td><code>113</code></td> <td><code>4b</code></td> <td><code>K</code></td> <td><code>107</code></td> <td><code>153</code></td> <td><code>6b</code></td> <td> +<code>k</code> </td> +</tr> <tr> <td><code>12</code></td> <td><code>14</code></td> <td><code>0c</code></td> <td> +<code>FF</code> (form feed - new page)</td> <td><code>44</code></td> <td><code>54</code></td> <td><code>2c</code></td> <td><code>,</code></td> <td><code>76</code></td> <td><code>114</code></td> <td><code>4c</code></td> <td><code>L</code></td> <td><code>108</code></td> <td><code>154</code></td> <td><code>6c</code></td> <td> +<code>l</code> </td> +</tr> <tr> <td><code>13</code></td> <td><code>15</code></td> <td><code>0d</code></td> <td> +<code>CR</code> (carriage return)</td> <td><code>45</code></td> <td><code>55</code></td> <td><code>2d</code></td> <td><code>-</code></td> <td><code>77</code></td> <td><code>115</code></td> <td><code>4d</code></td> <td><code>M</code></td> <td><code>109</code></td> <td><code>155</code></td> <td><code>6d</code></td> <td> +<code>m</code> </td> +</tr> <tr> <td><code>14</code></td> <td><code>16</code></td> <td><code>0e</code></td> <td> +<code>SO</code> (shift out)</td> <td><code>46</code></td> <td><code>56</code></td> <td><code>2e</code></td> <td><code>.</code></td> <td><code>78</code></td> <td><code>116</code></td> <td><code>4e</code></td> <td><code>N</code></td> <td><code>110</code></td> <td><code>156</code></td> <td><code>6e</code></td> <td> +<code>n</code> </td> +</tr> <tr> <td><code>15</code></td> <td><code>17</code></td> <td><code>0f</code></td> <td> +<code>SI</code> (shift in)</td> <td><code>47</code></td> <td><code>57</code></td> <td><code>2f</code></td> <td><code>/</code></td> <td><code>79</code></td> <td><code>117</code></td> <td><code>4f</code></td> <td><code>O</code></td> <td><code>111</code></td> <td><code>157</code></td> <td><code>6f</code></td> <td> +<code>o</code> </td> +</tr> <tr> <td><code>16</code></td> <td><code>20</code></td> <td><code>10</code></td> <td> +<code>DLE</code> (data link escape)</td> <td><code>48</code></td> <td><code>60</code></td> <td><code>30</code></td> <td><code>0</code></td> <td><code>80</code></td> <td><code>120</code></td> <td><code>50</code></td> <td><code>P</code></td> <td><code>112</code></td> <td><code>160</code></td> <td><code>70</code></td> <td> +<code>p</code> </td> +</tr> <tr> <td><code>17</code></td> <td><code>21</code></td> <td><code>11</code></td> <td> +<code>DC1</code> (device control 1)</td> <td><code>49</code></td> <td><code>61</code></td> <td><code>31</code></td> <td><code>1</code></td> <td><code>81</code></td> <td><code>121</code></td> <td><code>51</code></td> <td><code>Q</code></td> <td><code>113</code></td> <td><code>161</code></td> <td><code>71</code></td> <td> +<code>q</code> </td> +</tr> <tr> <td><code>18</code></td> <td><code>22</code></td> <td><code>12</code></td> <td> +<code>DC2</code> (device control 2)</td> <td><code>50</code></td> <td><code>62</code></td> <td><code>32</code></td> <td><code>2</code></td> <td><code>82</code></td> <td><code>122</code></td> <td><code>52</code></td> <td><code>R</code></td> <td><code>114</code></td> <td><code>162</code></td> <td><code>72</code></td> <td> +<code>r</code> </td> +</tr> <tr> <td><code>19</code></td> <td><code>23</code></td> <td><code>13</code></td> <td> +<code>DC3</code> (device control 3)</td> <td><code>51</code></td> <td><code>63</code></td> <td><code>33</code></td> <td><code>3</code></td> <td><code>83</code></td> <td><code>123</code></td> <td><code>53</code></td> <td><code>S</code></td> <td><code>115</code></td> <td><code>163</code></td> <td><code>73</code></td> <td> +<code>s</code> </td> +</tr> <tr> <td><code>20</code></td> <td><code>24</code></td> <td><code>14</code></td> <td> +<code>DC4</code> (device control 4)</td> <td><code>52</code></td> <td><code>64</code></td> <td><code>34</code></td> <td><code>4</code></td> <td><code>84</code></td> <td><code>124</code></td> <td><code>54</code></td> <td><code>T</code></td> <td><code>116</code></td> <td><code>164</code></td> <td><code>74</code></td> <td> +<code>t</code> </td> +</tr> <tr> <td><code>21</code></td> <td><code>25</code></td> <td><code>15</code></td> <td> +<code>NAK</code> (negative acknowledge)</td> <td><code>53</code></td> <td><code>65</code></td> <td><code>35</code></td> <td><code>5</code></td> <td><code>85</code></td> <td><code>125</code></td> <td><code>55</code></td> <td><code>U</code></td> <td><code>117</code></td> <td><code>165</code></td> <td><code>75</code></td> <td> +<code>u</code> </td> +</tr> <tr> <td><code>22</code></td> <td><code>26</code></td> <td><code>16</code></td> <td> +<code>SYN</code> (synchronous idle)</td> <td><code>54</code></td> <td><code>66</code></td> <td><code>36</code></td> <td><code>6</code></td> <td><code>86</code></td> <td><code>126</code></td> <td><code>56</code></td> <td><code>V</code></td> <td><code>118</code></td> <td><code>166</code></td> <td><code>76</code></td> <td> +<code>v</code> </td> +</tr> <tr> <td><code>23</code></td> <td><code>27</code></td> <td><code>17</code></td> <td> +<code>ETB</code> (end of transmission block)</td> <td><code>55</code></td> <td><code>67</code></td> <td><code>37</code></td> <td><code>7</code></td> <td><code>87</code></td> <td><code>127</code></td> <td><code>57</code></td> <td><code>W</code></td> <td><code>119</code></td> <td><code>167</code></td> <td><code>77</code></td> <td> +<code>w</code> </td> +</tr> <tr> <td><code>24</code></td> <td><code>30</code></td> <td><code>18</code></td> <td> +<code>CAN</code> (cancel)</td> <td><code>56</code></td> <td><code>70</code></td> <td><code>38</code></td> <td><code>8</code></td> <td><code>88</code></td> <td><code>130</code></td> <td><code>58</code></td> <td><code>X</code></td> <td><code>120</code></td> <td><code>170</code></td> <td><code>78</code></td> <td> +<code>x</code> </td> +</tr> <tr> <td><code>25</code></td> <td><code>31</code></td> <td><code>19</code></td> <td> +<code>EM</code> (end of medium)</td> <td><code>57</code></td> <td><code>71</code></td> <td><code>39</code></td> <td><code>9</code></td> <td><code>89</code></td> <td><code>131</code></td> <td><code>59</code></td> <td><code>Y</code></td> <td><code>121</code></td> <td><code>171</code></td> <td><code>79</code></td> <td> +<code>y</code> </td> +</tr> <tr> <td><code>26</code></td> <td><code>32</code></td> <td><code>1a</code></td> <td> +<code>SUB</code> (substitute)</td> <td><code>58</code></td> <td><code>72</code></td> <td><code>3a</code></td> <td><code>:</code></td> <td><code>90</code></td> <td><code>132</code></td> <td><code>5a</code></td> <td><code>Z</code></td> <td><code>122</code></td> <td><code>172</code></td> <td><code>7a</code></td> <td> +<code>z</code> </td> +</tr> <tr> <td><code>27</code></td> <td><code>33</code></td> <td><code>1b</code></td> <td> +<code>ESC</code> (escape)</td> <td><code>59</code></td> <td><code>73</code></td> <td><code>3b</code></td> <td><code>;</code></td> <td><code>91</code></td> <td><code>133</code></td> <td><code>5b</code></td> <td><code>[</code></td> <td><code>123</code></td> <td><code>173</code></td> <td><code>7b</code></td> <td> +<code>{</code> </td> +</tr> <tr> <td><code>28</code></td> <td><code>34</code></td> <td><code>1c</code></td> <td> +<code>FS</code> (file separator)</td> <td><code>60</code></td> <td><code>74</code></td> <td><code>3c</code></td> <td><code><</code></td> <td><code>92</code></td> <td><code>134</code></td> <td><code>5c</code></td> <td><code>\ </code></td> <td><code>124</code></td> <td><code>174</code></td> <td><code>7c</code></td> <td> +<code>|</code> </td> +</tr> <tr> <td><code>29</code></td> <td><code>35</code></td> <td><code>1d</code></td> <td> +<code>GS</code> (group separator)</td> <td><code>61</code></td> <td><code>75</code></td> <td><code>3d</code></td> <td><code>=</code></td> <td><code>93</code></td> <td><code>135</code></td> <td><code>5d</code></td> <td><code>]</code></td> <td><code>125</code></td> <td><code>175</code></td> <td><code>7d</code></td> <td> +<code>}</code> </td> +</tr> <tr> <td><code>30</code></td> <td><code>36</code></td> <td><code>1e</code></td> <td> +<code>RS</code> (record separator)</td> <td><code>62</code></td> <td><code>76</code></td> <td><code>3e</code></td> <td><code>></code></td> <td><code>94</code></td> <td><code>136</code></td> <td><code>5e</code></td> <td><code>^</code></td> <td><code>126</code></td> <td><code>176</code></td> <td><code>7e</code></td> <td> +<code>~</code> </td> +</tr> <tr> <td><code>31</code></td> <td><code>37</code></td> <td><code>1f</code></td> <td> +<code>US</code> (unit separator)</td> <td><code>63</code></td> <td><code>77</code></td> <td><code>3f</code></td> <td><code>?</code></td> <td><code>95</code></td> <td><code>137</code></td> <td><code>5f</code></td> <td><code>_</code></td> <td><code>127</code></td> <td><code>177</code></td> <td><code>7f</code></td> <td> +<code>DEL</code> (delete) </td> +</tr> +</table> <p>Note: in Unicode, the ASCII character block is known as <a rel="nofollow" class="external text" href="https://www.unicode.org/charts/PDF/U0000.pdf"><code>U+0000..U+007F</code> Basic Latin</a>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +int main(void) +{ + puts("Printable ASCII:"); + for (int i = 32; i < 127; ++i) { + putchar(i); + putchar(i % 16 == 15 ? '\n' : ' '); + } +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Printable ASCII: + ! " # $ % & ' ( ) * + , - . / +0 1 2 3 4 5 6 7 8 9 : ; < = > ? +@ A B C D E F G H I J K L M N O +P Q R S T U V W X Y Z [ \ ] ^ _ +` a b c d e f g h i j k l m n o +p q r s t u v w x y z { | } ~</pre></div> </div> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/ascii" title="cpp/language/ascii">C++ documentation</a></span> for <span class=""><span>ASCII Chart</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/ascii" class="_attribution-link">https://en.cppreference.com/w/c/language/ascii</a> + </p> +</div> diff --git a/devdocs/c/language%2Fasm.html b/devdocs/c/language%2Fasm.html new file mode 100644 index 00000000..d222cf59 --- /dev/null +++ b/devdocs/c/language%2Fasm.html @@ -0,0 +1,68 @@ + <h1 id="firstHeading" class="firstHeading">Inline assembly</h1> <p>Inline assembly (typically introduced by the <code>asm</code> keyword) gives the ability to embed assembly language source code within a C program.</p> +<p>Unlike in C++, inline assembly is treated as an extension in C. It is conditionally supported and implementation defined, meaning that it may not be present and, even when provided by the implementation, it does not have a fixed meaning.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <code>asm (</code> <span class="t-spar">string_literal</span> <code>)</code> <code>;</code> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>This kind of inline assembly syntax is accepted by the C++ standard and called <i>asm-declaration</i> in C++. The <span class="t-spar">string_literal</span> is typically a short program written in assembly language, which is executed whenever this declaration is executed. Different C compilers have wildly varying rules for asm-declarations, and different conventions for the interaction with the surrounding C code.</p> +<p>asm-declaration can appear inside a block (a function body or another compound statement), and, as all other declarations, this declaration can also appear outside a block.</p> +<h3 id="Notes"> Notes</h3> <p>MSVC does not support inline assembly on the ARM and x64 processors, and only support the form introduced by <code>__asm</code> on x86 processors.</p> +<p>When compiling in ISO C mode by GCC or Clang (e.g. with option <code>-std=c11</code>), <code>__asm__</code> must be used instead of <code>asm</code>.</p> +<h3 id="Examples"> Examples</h3> <div class="t-example"> +<p>Demonstrates two kinds of inline assembly syntax offered by the GCC compiler. This program will only work correctly on x86-64 platform under Linux. Note that the "standard inline assembly" is also treated as an extension in the C standard.</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> + +extern int func(void); +// the definition of func is written in assembly language +__asm__(".globl func\n\t" + ".type func, @function\n\t" + "func:\n\t" + ".cfi_startproc\n\t" + "movl $7, %eax\n\t" + "ret\n\t" + ".cfi_endproc"); + +int main(void) +{ + int n = func(); + // gcc's extended inline assembly + __asm__ ("leal (%0,%0,4),%0" + : "=r" (n) + : "0" (n)); + printf("7*5 = %d\n", n); + fflush(stdout); // flush is intentional + + // standard inline assembly in C++ + __asm__ ("movq $60, %rax\n\t" // the exit syscall number on Linux + "movq $2, %rdi\n\t" // this program returns 2 + "syscall"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">7*5 = 35</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> J.5.10 The asm keyword (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> J.5.10 The asm keyword (p: 422) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> J.5.10 The asm keyword (p: 580) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> J.5.10 The asm keyword (p: 512) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> G.5.10 The asm keyword </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/asm" title="cpp/language/asm">C++ documentation</a></span> for <span class=""><span><code>asm</code> declaration</span></span> </td> +</tr> </table> <h3 id="External_links"> External links</h3> <table> <tr style="vertical-align:top;"> <td>1. </td> <td> +<a rel="nofollow" class="external text" href="https://www.ibiblio.org/gferg/ldp/GCC-Inline-Assembly-HOWTO.html">GCC Inline Assembly HOWTO</a> </td> +</tr> <tr style="vertical-align:top;"> <td>2. </td> <td> +<a rel="nofollow" class="external text" href="https://pic.dhe.ibm.com/infocenter/comphelp/v121v141/topic/com.ibm.xlcpp121.aix.doc/language_ref/asm.html">IBM XL C/C++ Inline Assembly</a> </td> +</tr> <tr style="vertical-align:top;"> <td>3. </td> <td> +<a rel="nofollow" class="external text" href="https://software.intel.com/en-us/cpp-compiler-developer-guide-and-reference-inline-assembly">Intel C++ Inline Assembly</a> </td> +</tr> <tr style="vertical-align:top;"> <td>4. </td> <td> +<a rel="nofollow" class="external text" href="https://learn.microsoft.com/en-us/cpp/assembler/inline/inline-assembler.aspx">Visual Studio Inline Assembler</a> </td> +</tr> <tr style="vertical-align:top;"> <td>5. </td> <td> +<a rel="nofollow" class="external text" href="https://blogs.oracle.com/x86be/entry/gcc_style_asm_inlining_support">Sun Studio 12 Asm Statements</a> </td> +</tr> <tr style="vertical-align:top;"> <td>6. </td> <td> +<a rel="nofollow" class="external text" href="https://h21007.www2.hp.com/portal/site/dspp/menuitem.863c3e4cbcdc3f3515b49c108973a801?ciid=4308e2f5bde02110e2f5bde02110275d6e10RCRD">Inline assembly for Itanium-based HP-UX</a> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/asm" class="_attribution-link">https://en.cppreference.com/w/c/language/asm</a> + </p> +</div> diff --git a/devdocs/c/language%2Fatomic.html b/devdocs/c/language%2Fatomic.html new file mode 100644 index 00000000..5b8daa7a --- /dev/null +++ b/devdocs/c/language%2Fatomic.html @@ -0,0 +1,77 @@ + <h1 id="firstHeading" class="firstHeading">Atomic types</h1> <h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>_Atomic</code> <code>(</code> <span class="t-spar">type-name</span> <code>)</code> </td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>_Atomic</code> <span class="t-spar">type-name</span> </td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> Use as a type specifier; this designates a new atomic type</div> <div class="t-li1"> +<span class="t-li">2)</span> Use as a type qualifier; this designates the atomic version of <span class="t-spar">type-name</span>. In this role, it may be mixed with <a href="const" title="c/language/const">const</a>, <a href="volatile" title="c/language/volatile">volatile</a>, and <a href="restrict" title="c/language/restrict">restrict</a>, although unlike other qualifiers, the atomic version of <span class="t-spar">type-name</span> may have a different size, alignment, and object representation.</div> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">type-name</span> </td> <td> - </td> <td> any type other than array or function. For <span class="t-v">(1)</span>, <span class="t-spar">type-name</span> also cannot be atomic or cvr-qualified </td> +</tr> +</table> <p>The header <code><stdatomic.h></code> defines <a href="../thread#Atomic_operations" title="c/thread">37 convenience type aliases</a>, from <a href="../thread#Atomic_operations" title="c/thread"><code>atomic_bool</code></a> to <a href="../thread#Atomic_operations" title="c/thread"><code>atomic_uintmax_t</code></a>, which simplify the use of this keyword with built-in and library types.</p> +<div class="c source-c"><pre data-language="c">_Atomic const int * p1; // p is a pointer to an atomic const int +const atomic_int * p2; // same +const _Atomic(int) * p3; // same</pre></div> <p>If the macro constant <code>__STDC_NO_ATOMICS__</code> is defined by the compiler, the keyword <code>_Atomic</code> is not provided.</p> +<h3 id="Explanation"> Explanation</h3> <p>Objects of atomic types are the only objects that are free from <a href="memory_model" title="c/language/memory model">data races</a>; that is, they may be modified by two threads concurrently or modified by one and read by another.</p> +<p>Each atomic object has its own associated <i>modification order</i>, which is a total order of modifications made to that object. If, from some thread's point of view, modification <code>A</code> of some atomic M <a href="../atomic/memory_order" title="c/atomic/memory order">happens-before</a> modification <code>B</code> of the same atomic M, then in the modification order of M, A occurs before B.</p> +<p>Note that although each atomic object has its own modification order, there is no single total order; different threads may observe modifications to different atomic objects in different orders.</p> +<p>There are four coherences that are guaranteed for all atomic operations:</p> +<ul> +<li> <b>write-write coherence</b>: If an operation A that modifies an atomic object M <i>happens-before</i> an operation B that modifies M, then A appears earlier than B in the modification order of M. </li> +<li> <b>read-read coherence</b>: If a value computation A of an atomic object M happens before a value computation B of M, and A takes its value from a side effect X on M, then the value computed by B is either the value stored by X or is the value stored by a side effect Y on M, where Y appears later than X in the modification order of M. </li> +<li> <b>read-write coherence</b>: If a value computation A of an atomic object M <i>happens-before</i> an operation B on M, then A takes its value from a side effect X on M, where X appears before B in the modification order of M. </li> +<li> <b>write-read coherence</b>: If a side effect X on an atomic object M <i>happens-before</i> a value computation B of M, then the evaluation B takes its value from X or from a side effect Y that appears after X in the modification order of M. </li> +</ul> <p>Some atomic operations are also synchronization operations; they may have additional release semantics, acquire semantics, or sequentially-consistent semantics. See <code><a href="../atomic/memory_order" title="c/atomic/memory order">memory_order</a></code>.</p> +<p>Built-in <a href="operator_incdec" title="c/language/operator incdec">increment and decrement operators</a> and <a href="operator_assignment" title="c/language/operator assignment">compound assignment</a> are read-modify-write atomic operations with total sequentially consistent ordering (as if using <code><a href="../atomic/memory_order" title="c/atomic/memory order">memory_order_seq_cst</a></code>). If less strict synchronization semantics are desired, the <a href="../thread#Atomic_operations" title="c/thread">standard library functions</a> may be used instead.</p> +<p>Atomic properties are only meaningful for <a href="value_category" title="c/language/value category">lvalue expressions</a>. Lvalue-to-rvalue conversion (which models a memory read from an atomic location to a CPU register) strips atomicity along with other qualifiers.</p> +<h3 id="Notes"> Notes</h3> <p>Accessing a member of an atomic struct/union is undefined behavior.</p> +<p>The library type <code><a href="http://en.cppreference.com/w/c/program/sig_atomic_t"><span class="kw499">sig_atomic_t</span></a></code> does not provide inter-thread synchronization or memory ordering, only atomicity.</p> +<p>The <a href="volatile" title="c/language/volatile">volatile</a> types do not provide inter-thread synchronization, memory ordering, or atomicity.</p> +<p>Implementations are recommended to ensure that the representation of <code>_Atomic(T)</code> in C is same as that of <code>std::atomic<T></code> in C++ for every possible type <code>T</code>. The mechanisms used to ensure atomicity and memory ordering should be compatible.</p> +<h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/_atomic" title="c/keyword/ Atomic"><code>_Atomic</code></a></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <threads.h> +#include <stdatomic.h> + +atomic_int acnt; +int cnt; + +int f(void* thr_data) +{ + for(int n = 0; n < 1000; ++n) { + ++cnt; + ++acnt; + // for this example, relaxed memory order is sufficient, e.g. + // atomic_fetch_add_explicit(&acnt, 1, memory_order_relaxed); + } + return 0; +} + +int main(void) +{ + thrd_t thr[10]; + for(int n = 0; n < 10; ++n) + thrd_create(&thr[n], f, NULL); + for(int n = 0; n < 10; ++n) + thrd_join(thr[n], NULL); + + printf("The atomic counter is %u\n", acnt); + printf("The non-atomic counter is %u\n", cnt); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">The atomic counter is 10000 +The non-atomic counter is 8644</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.7.2.4 Atomic type specifiers (p: 87) </li> +<li> 7.17 Atomics <stdatomic.h> (p: 200-209) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.7.2.4 Atomic type specifiers (p: 121) </li> +<li> 7.17 Atomics <stdatomic.h> (p: 273-286) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="../thread" title="c/thread">C documentation</a></span> for <code>thread (Concurrency support library)</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/atomic/atomic" title="cpp/atomic/atomic">C++ documentation</a></span> for <code>atomic</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/atomic" class="_attribution-link">https://en.cppreference.com/w/c/language/atomic</a> + </p> +</div> diff --git a/devdocs/c/language%2Fattributes%2Fdeprecated.html b/devdocs/c/language%2Fattributes%2Fdeprecated.html new file mode 100644 index 00000000..d53195d3 --- /dev/null +++ b/devdocs/c/language%2Fattributes%2Fdeprecated.html @@ -0,0 +1,65 @@ + <h1 id="firstHeading" class="firstHeading">C attribute: deprecated <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <p>Indicates that the name or entity declared with this attribute is <a href="https://en.wikipedia.org/wiki/Deprecation" class="extiw" title="enwiki:Deprecation">deprecated</a>, that is, the use is allowed, but discouraged for some reason.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>[[</code> <code>deprecated</code> <code>]]</code><br><code>[[</code> <code>__deprecated__</code> <code>]]</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>[[</code> <code>deprecated</code> <code>(</code> <span class="t-spar">string-literal</span> <code>)</code> <code>]]</code><br><code>[[</code> <code>__deprecated__</code> <code>(</code> <span class="t-spar">string-literal</span> <code>)</code> <code>]]</code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">string-literal</span> </td> <td> - </td> <td> text that could be used to explain the rationale for deprecation and/or to suggest a replacing entity </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>Indicates that the use of the name or entity declared with this attribute is allowed, but discouraged for some reason. Compilers typically issue warnings on such uses. The <span class="t-spar">string-literal</span>, if specified, is usually included in the warnings.</p> +<p>This attribute is allowed in declarations of the following names or entities:</p> +<ul> +<li> <a href="../struct" title="c/language/struct">struct</a>/<a href="../union" title="c/language/union">union</a>: <code>struct [[deprecated]] S;</code>, </li> +<li> <a href="../typedef" title="c/language/typedef">typedef-name</a>: <code>[[deprecated]] typedef S* PS;</code>, </li> +<li> objects: <code>[[deprecated]] int x;</code>, </li> +<li> struct/union member: <code>union U { [[deprecated]] int n; };</code>, </li> +<li> <a href="../function_definition" title="c/language/function definition">function</a>: <code>[[deprecated]] void f(void);</code>, </li> +<li> <a href="../enum" title="c/language/enum">enumeration</a>: <code>enum [[deprecated]] E {};</code>, </li> +<li> enumerator: <code>enum { A [[deprecated]], B [[deprecated]] = 42 };</code>. </li> +</ul> <p>A name declared non-deprecated may be redeclared deprecated. A name declared deprecated cannot be un-deprecated by redeclaring it without this attribute.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +[[deprecated]] +void TriassicPeriod(void) +{ + puts("Triassic Period: [251.9 - 208.5] million years ago."); +} + +[[deprecated("Use NeogenePeriod() instead.")]] +void JurassicPeriod(void) +{ + puts("Jurassic Period: [201.3 - 152.1] million years ago."); +} + +[[deprecated("Use calcSomethingDifferently(int).")]] +int calcSomething(int x) +{ + return x * 2; +} + +int main(void) +{ + TriassicPeriod(); + JurassicPeriod(); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Triassic Period: [251.9 - 208.5] million years ago. +Jurassic Period: [201.3 - 152.1] million years ago. + +prog.c:23:5: warning: 'TriassicPeriod' is deprecated [-Wdeprecated-declarations] + TriassicPeriod(); + ^ +prog.c:3:3: note: 'TriassicPeriod' has been explicitly marked deprecated here +[[deprecated]] + ^ +prog.c:24:5: warning: 'JurassicPeriod' is deprecated: Use NeogenePeriod() instead. [-Wdeprecated-declarations] + JurassicPeriod(); + ^ +prog.c:9:3: note: 'JurassicPeriod' has been explicitly marked deprecated here +[[deprecated("Use NeogenePeriod() instead.")]] + ^ +2 warnings generated.</pre></div> </div> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/attributes/deprecated" title="cpp/language/attributes/deprecated">C++ documentation</a></span> for <code>deprecated</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/attributes/deprecated" class="_attribution-link">https://en.cppreference.com/w/c/language/attributes/deprecated</a> + </p> +</div> diff --git a/devdocs/c/language%2Fattributes%2Ffallthrough.html b/devdocs/c/language%2Fattributes%2Ffallthrough.html new file mode 100644 index 00000000..c1c06f6b --- /dev/null +++ b/devdocs/c/language%2Fattributes%2Ffallthrough.html @@ -0,0 +1,45 @@ + <h1 id="firstHeading" class="firstHeading">C attribute: fallthrough <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <p>Indicates that the fall through from the previous case label is intentional and should not be diagnosed by a compiler that warns on fallthrough.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <code>[[</code> <code>fallthrough</code> <code>]]</code><br><code>[[</code> <code>__fallthrough__</code> <code>]]</code> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>May only be used in an <a href="../declarations" title="c/language/declarations">attribute declaration</a> to create a <i>fallthrough declaration</i> (<code>[[fallthrough]];</code>).</p> +<p>A fallthrough declaration may only be used in a <a href="../switch" title="c/language/switch"><code>switch</code></a> statement, where the next block item (statement, declaration, or label) to be encounted is a statement with a <code>case</code> or <code>default</code> label for that switch statement.</p> +<p>Indicates that the fall through from the previous case label is intentional and should not be diagnosed by a compiler that warns on fallthrough.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdbool.h> + +void g(void) {} +void h(void) {} +void i(void) {} + +void f(int n) { + switch (n) { + case 1: + case 2: + g(); + [[fallthrough]]; + case 3: // no warning on fallthrough + h(); + case 4: // compiler may warn on fallthrough + if(n < 3) { + i(); + [[fallthrough]]; // OK + } + else { + return; + } + case 5: + while (false) { + [[fallthrough]]; // ill-formed: no subsequent case or default label + } + case 6: + [[fallthrough]]; // ill-formed: no subsequent case or default label + } +} + +int main(void) {}</pre></div> </div> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/attributes/fallthrough" title="cpp/language/attributes/fallthrough">C++ documentation</a></span> for <code>fallthrough</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/attributes/fallthrough" class="_attribution-link">https://en.cppreference.com/w/c/language/attributes/fallthrough</a> + </p> +</div> diff --git a/devdocs/c/language%2Fattributes%2Fmaybe_unused.html b/devdocs/c/language%2Fattributes%2Fmaybe_unused.html new file mode 100644 index 00000000..e8af27c7 --- /dev/null +++ b/devdocs/c/language%2Fattributes%2Fmaybe_unused.html @@ -0,0 +1,33 @@ + <h1 id="firstHeading" class="firstHeading">C attribute: maybe_unused <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <p>Suppresses warnings on unused entities.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <code>[[</code> <code>maybe_unused</code> <code>]]</code><br><code>[[</code> <code>__maybe_unused__</code> <code>]]</code> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>This attribute can appear in the declaration of the following entities:</p> +<ul> +<li> <a href="../struct" title="c/language/struct">struct</a>/<a href="../union" title="c/language/union">union</a>: <code>struct [[maybe_unused]] S;</code>, </li> +<li> <a href="../typedef" title="c/language/typedef">typedef name</a>: <code>[[maybe_unused]] typedef S* PS;</code>, </li> +<li> object: <code>[[maybe_unused]] int x;</code>, </li> +<li> struct/union member: <code>union U { [[maybe_unused]] int n; };</code>, </li> +<li> <a href="../function_definition" title="c/language/function definition">function</a>: <code>[[maybe_unused]] void f(void);</code>, </li> +<li> <a href="../enum" title="c/language/enum">enumeration</a>: <code>enum [[maybe_unused]] E {};</code>, </li> +<li> enumerator: <code>enum { A [[maybe_unused]], B [[maybe_unused]] = 42 };</code>. </li> +</ul> <p>If the compiler issues warnings on unused entities, that warning is suppressed for any entity declared <code>maybe_unused</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <assert.h> + +[[maybe_unused]] void f([[maybe_unused]] _Bool cond1, [[maybe_unused]] _Bool cond2) +{ + [[maybe_unused]] _Bool b = cond1 && cond2; + assert(b); // in release mode, assert is compiled out, and b is unused + // no warning because it is declared [[maybe_unused]] +} // parameters cond1 and cond2 are not used, no warning + +int main(void) +{ + f(1, 1); +}</pre></div> </div> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/attributes/maybe_unused" title="cpp/language/attributes/maybe unused">C++ documentation</a></span> for <code>maybe_unused</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/attributes/maybe_unused" class="_attribution-link">https://en.cppreference.com/w/c/language/attributes/maybe_unused</a> + </p> +</div> diff --git a/devdocs/c/language%2Fattributes%2Fnodiscard.html b/devdocs/c/language%2Fattributes%2Fnodiscard.html new file mode 100644 index 00000000..35c94f7d --- /dev/null +++ b/devdocs/c/language%2Fattributes%2Fnodiscard.html @@ -0,0 +1,42 @@ + <h1 id="firstHeading" class="firstHeading">C attribute: nodiscard <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <p>If a function declared <code>nodiscard</code> or a function returning a struct/union/enum declared <code>nodiscard</code> by value is called from a <a href="../expressions" title="c/language/expressions">discarded-value expression</a> other than a cast to <code>void</code>, the compiler is encouraged to issue a warning.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>[[</code> <code>nodiscard</code> <code>]]</code><br><code>[[</code> <code>__nodiscard__</code> <code>]]</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>[[</code> <code>nodiscard</code> <code>(</code> <span class="t-spar">string-literal</span> <code>)</code> <code>]]</code><br><code>[[</code> <code>__nodiscard__</code> <code>(</code> <span class="t-spar">string-literal</span> <code>)</code> <code>]]</code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">string-literal</span> </td> <td> - </td> <td> text that could be used to explain the rationale for why the result should not be discarded </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>Appears in a function declaration, enumeration declaration, or struct/union declaration.</p> +<p>If, from a <a href="../expressions" title="c/language/expressions">discarded-value expression</a> other than a cast to <code>void</code>,</p> +<ul> +<li> a function declared <code>nodiscard</code> is called, or </li> +<li> a function returning a struct/union/enum declared <code>nodiscard</code> is called, </li> +</ul> <p>the compiler is encouraged to issue a warning.</p> +<p>The <span class="t-spar">string-literal</span>, if specified, is usually included in the warnings.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">struct [[nodiscard]] error_info { int status; /*...*/ }; +struct error_info enable_missile_safety_mode() { /*...*/ return (struct error_info){0}; } +void launch_missiles() { /*...*/ } +void test_missiles() { + enable_missile_safety_mode(); // compiler may warn on discarding a nodiscard value + launch_missiles(); +} +struct error_info* foo() { static struct error_info e; /*...*/ return &e; } +void f1() { + foo(); // nodiscard type itself is not returned, no warning +} +// nodiscard( string-literal ): +[[nodiscard("PURE FUN")]] int strategic_value(int x, int y) { return x ^ y; } + +int main() +{ + strategic_value(4,2); // compiler may warn on discarding a nodiscard value + int z = strategic_value(0,0); // OK: return value is not discarded + return z; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">game.cpp:5:4: warning: ignoring return value of function declared with 'nodiscard' attribute +game.cpp:17:5: warning: ignoring return value of function declared with 'nodiscard' attribute: PURE FUN</pre></div> </div> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/attributes/nodiscard" title="cpp/language/attributes/nodiscard">C++ documentation</a></span> for <code>nodiscard</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/attributes/nodiscard" class="_attribution-link">https://en.cppreference.com/w/c/language/attributes/nodiscard</a> + </p> +</div> diff --git a/devdocs/c/language%2Fattributes%2Fnoreturn.html b/devdocs/c/language%2Fattributes%2Fnoreturn.html new file mode 100644 index 00000000..6d75ac4c --- /dev/null +++ b/devdocs/c/language%2Fattributes%2Fnoreturn.html @@ -0,0 +1,24 @@ + <h1 id="firstHeading" class="firstHeading">C attribute: noreturn, _Noreturn <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <p>Indicates that the function does not return.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>[[</code> <code>noreturn</code> <code>]]</code><br><code>[[</code> <code>__noreturn__</code> <code>]]</code> </td> <td class="t-sdsc-nopad"> </td> <td> </td> +</tr> <tr class="t-sdsc"> <td> <code>[[</code> <code>_Noreturn</code> <code>]]</code><br><code>[[</code> <code>___Noreturn__</code> <code>]]</code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark">(deprecated)</span> </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>Indicates that the function does not return.</p> +<p>This attribute applies to the name of the function and specifies that the function does not return by executing the return statement or by reaching the end of the function body (it may return by executing <code><a href="../../program/longjmp" title="c/program/longjmp">longjmp</a></code>). The behavior is undefined if the function with this attribute actually returns. A compiler diagnostic is recommended if this can be detected.</p> +<p>It has been previously denoted by the keyword <a href="../_noreturn" title="c/language/ Noreturn"><code>_Noreturn</code></a> until it was deprecated since C23 and replaced by this attribute.</p> +<h3 id="Standard_library"> Standard library</h3> <p>The following standard functions are declared with <code>noreturn</code> attribute (they used to be declared with <a href="../_noreturn" title="c/language/ Noreturn"><code>_Noreturn</code></a> specifier until C23):</p> +<ul> +<li> <code><a href="../../program/abort" title="c/program/abort">abort()</a></code> </li> +<li> <code><a href="../../program/exit" title="c/program/exit">exit()</a></code> </li> +<li> <code><a href="../../program/_exit" title="c/program/ Exit">_Exit()</a></code> </li> +<li> <code><a href="../../program/quick_exit" title="c/program/quick exit">quick_exit()</a></code> </li> +<li> <code><a href="../../thread/thrd_exit" title="c/thread/thrd exit">thrd_exit()</a></code> </li> +<li> <code><a href="../../program/longjmp" title="c/program/longjmp">longjmp()</a></code> </li> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="../_noreturn" title="c/language/ Noreturn">C documentation</a></span> for <code>_Noreturn</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/attributes/noreturn" title="cpp/language/attributes/noreturn">C++ documentation</a></span> for <code>[[noreturn]]</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/attributes/noreturn" class="_attribution-link">https://en.cppreference.com/w/c/language/attributes/noreturn</a> + </p> +</div> diff --git a/devdocs/c/language%2Fattributes%2Freproducible.html b/devdocs/c/language%2Fattributes%2Freproducible.html new file mode 100644 index 00000000..fa0bc584 --- /dev/null +++ b/devdocs/c/language%2Fattributes%2Freproducible.html @@ -0,0 +1,22 @@ + <h1 id="firstHeading" class="firstHeading">C attribute: unsequenced, reproducible <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <p>Provides the compiler with information about the access of objects by a function such that certain properties of function calls can be deduced.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>[[</code> <code>unsequenced</code> <code>]]</code><br><code>[[</code> <code>__unsequenced__</code> <code>]]</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>[[</code> <code>reproducible</code> <code>]]</code><br><code>[[</code> <code>__reproducible__</code> <code>]]</code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> Indicates that a function is effectless, idempotent, stateless, and independent</div> <div class="t-li1"> +<span class="t-li">2)</span> Indicates that a function is effectless and idempotent</div> <h3 id="Explanation"> Explanation</h3> <p>These attributes apply to a function declarator or to a type specifier that has a function type. The corresponding attribute is a property of the function type.</p> +<h4 id="Effectless"> Effectless</h4> <p>An evaluation of a function call is effectless if any store operation that is sequenced during the call is the modification of an object that synchronizes with the call; if additionally the operation is observable, all access to the object must be based on a unique pointer parameter of the function.</p> +<h4 id="Idempotent"> Idempotent</h4> <p>An evaluation <span class="t-spar">E</span> is idempotent if a second evaluation of <span class="t-spar">E</span> can be sequenced immediately after the original one without changing the resulting value, if any, or the observable state of the execution.</p> +<h4 id="Stateless"> Stateless</h4> <p>A function <span class="t-spar">F</span> is stateless if any definition of an object of static or thread <a href="../storage_duration" title="c/language/storage duration">storage duration</a> in <span class="t-spar">F</span> or in a function that is called by <span class="t-spar">F</span> is <code>const</code> but not <code>volatile</code> qualified.</p> +<h4 id="Independent"> Independent</h4> <p>A function <span class="t-spar">F</span> is independent if for any object <span class="t-spar">X</span> that is observed by a call to <span class="t-spar">F</span> through an lvalue that is not based on a parameter of the call, all accesses to <span class="t-spar">X</span> in all calls to <span class="t-spar">F</span> during the same program execution observe the same value; otherwise if the access is based on a pointer parameter, there shall be a unique such pointer parameter <span class="t-spar">P</span> such that any access to <span class="t-spar">X</span> shall be to an lvalue that is based on <span class="t-spar">P</span>.</p> +<p>An object <span class="t-spar">X</span> is observed by a function call if both synchronize, if <span class="t-spar">X</span> is not local to the call, if <span class="t-spar">X</span> has a lifetime that starts before the function call, and if an access of <span class="t-spar">X</span> is sequenced during the call; the last value of <span class="t-spar">X</span>, if any, that is stored before the call is said to be the value of <span class="t-spar">X</span> that is observed by the call.</p> +<h3 id="Notes"> Notes</h3> <p>These attributes exist for the purpose of compiler optimization.</p> +<p>If a function is reproducible, multiple subsequent calls can be treated as a single call.</p> +<p>If a function is unsequenced, multiple subsequent calls can be treated as a single call, and the calls can be parallelized and reordered arbitrarily.</p> +<div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/attributes/reproducible" class="_attribution-link">https://en.cppreference.com/w/c/language/attributes/reproducible</a> + </p> +</div> diff --git a/devdocs/c/language%2Fattributes%2Funsequenced.html b/devdocs/c/language%2Fattributes%2Funsequenced.html new file mode 100644 index 00000000..cf247a64 --- /dev/null +++ b/devdocs/c/language%2Fattributes%2Funsequenced.html @@ -0,0 +1,22 @@ + <h1 id="firstHeading" class="firstHeading">C attribute: unsequenced, reproducible <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <p>Provides the compiler with information about the access of objects by a function such that certain properties of function calls can be deduced.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>[[</code> <code>unsequenced</code> <code>]]</code><br><code>[[</code> <code>__unsequenced__</code> <code>]]</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>[[</code> <code>reproducible</code> <code>]]</code><br><code>[[</code> <code>__reproducible__</code> <code>]]</code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> Indicates that a function is effectless, idempotent, stateless, and independent</div> <div class="t-li1"> +<span class="t-li">2)</span> Indicates that a function is effectless and idempotent</div> <h3 id="Explanation"> Explanation</h3> <p>These attributes apply to a function declarator or to a type specifier that has a function type. The corresponding attribute is a property of the function type.</p> +<h4 id="Effectless"> Effectless</h4> <p>An evaluation of a function call is effectless if any store operation that is sequenced during the call is the modification of an object that synchronizes with the call; if additionally the operation is observable, all access to the object must be based on a unique pointer parameter of the function.</p> +<h4 id="Idempotent"> Idempotent</h4> <p>An evaluation <span class="t-spar">E</span> is idempotent if a second evaluation of <span class="t-spar">E</span> can be sequenced immediately after the original one without changing the resulting value, if any, or the observable state of the execution.</p> +<h4 id="Stateless"> Stateless</h4> <p>A function <span class="t-spar">F</span> is stateless if any definition of an object of static or thread <a href="../storage_duration" title="c/language/storage duration">storage duration</a> in <span class="t-spar">F</span> or in a function that is called by <span class="t-spar">F</span> is <code>const</code> but not <code>volatile</code> qualified.</p> +<h4 id="Independent"> Independent</h4> <p>A function <span class="t-spar">F</span> is independent if for any object <span class="t-spar">X</span> that is observed by a call to <span class="t-spar">F</span> through an lvalue that is not based on a parameter of the call, all accesses to <span class="t-spar">X</span> in all calls to <span class="t-spar">F</span> during the same program execution observe the same value; otherwise if the access is based on a pointer parameter, there shall be a unique such pointer parameter <span class="t-spar">P</span> such that any access to <span class="t-spar">X</span> shall be to an lvalue that is based on <span class="t-spar">P</span>.</p> +<p>An object <span class="t-spar">X</span> is observed by a function call if both synchronize, if <span class="t-spar">X</span> is not local to the call, if <span class="t-spar">X</span> has a lifetime that starts before the function call, and if an access of <span class="t-spar">X</span> is sequenced during the call; the last value of <span class="t-spar">X</span>, if any, that is stored before the call is said to be the value of <span class="t-spar">X</span> that is observed by the call.</p> +<h3 id="Notes"> Notes</h3> <p>These attributes exist for the purpose of compiler optimization.</p> +<p>If a function is reproducible, multiple subsequent calls can be treated as a single call.</p> +<p>If a function is unsequenced, multiple subsequent calls can be treated as a single call, and the calls can be parallelized and reordered arbitrarily.</p> +<div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/attributes/unsequenced" class="_attribution-link">https://en.cppreference.com/w/c/language/attributes/unsequenced</a> + </p> +</div> diff --git a/devdocs/c/language%2Fattributes.html b/devdocs/c/language%2Fattributes.html new file mode 100644 index 00000000..2aa35067 --- /dev/null +++ b/devdocs/c/language%2Fattributes.html @@ -0,0 +1,102 @@ + <h1 id="firstHeading" class="firstHeading">Attribute specifier sequence<span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <p>Introduces implementation-defined attributes for types, objects, expressions, etc.</p> +<h3 id="Syntax"> Syntax</h3> <code>[[</code><span class="t-spar">attr</span> <code>]]</code> <code>[[</code><span class="t-spar">attr1</span>, <span class="t-spar">attr2</span>, <span class="t-spar">attr3</span><code>(</code><span class="t-spar">args</span><code>)</code><code>]]</code> <code>[[</code><span class="t-spar">attribute-prefix</span><code>::</code><span class="t-spar">attr</span> <code>(</code><span class="t-spar">args</span><code>)</code><code>]]</code> <p>Formally, the syntax is</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>[[</code> <span class="t-spar">attribute-list</span> <code>]]</code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <p>where <span class="t-spar">attribute-list</span> is a comma-separated sequence of zero or more <span class="t-spar">attribute-token</span> s</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="t-spar">standard-attribute</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">attribute-prefix</span> <code>::</code> <span class="t-spar">identifier</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">standard-attribute</span> <code>(</code> <span class="t-spar">argument-list</span> <span class="t-mark">(optional)</span> <code>)</code> </td> <td> (3) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">attribute-prefix</span> <code>::</code> <span class="t-spar">identifier</span> <code>(</code> <span class="t-spar">argument-list</span> <span class="t-mark">(optional)</span> <code>)</code> </td> <td> (4) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>where <span class="t-spar">attribute-prefix</span> is an <span class="t-spar">identifier</span> and <span class="t-spar">argument-list</span> is a sequence of tokens where parentheses, brackets and braces are balanced (<span class="t-spar">balanced-token-sequence</span>).</p> +<div class="t-li1"> +<span class="t-li">1)</span> standard attribute, such as <span class="t-cc"><span class="br0">[</span><span class="br0">[</span>fallthrough<span class="br0">]</span><span class="br0">]</span></span> +</div> <div class="t-li1"> +<span class="t-li">2)</span> attribute with a namespace, such as <span class="t-cc"><span class="br0">[</span><span class="br0">[</span>gnu<span class="sy4">::</span><span class="me2">unused</span><span class="br0">]</span><span class="br0">]</span></span> +</div> <div class="t-li1"> +<span class="t-li">3)</span> standard attribute with arguments, such as <span class="t-cc"><span class="br0">[</span><span class="br0">[</span>deprecated<span class="br0">(</span><span class="st0">"reason"</span><span class="br0">)</span><span class="br0">]</span><span class="br0">]</span></span> +</div> <div class="t-li1"> +<span class="t-li">4)</span> attribute with both a namespace and an argument list, such as <span class="t-cc"><span class="br0">[</span><span class="br0">[</span>gnu<span class="sy4">::</span><span class="me2">nonnull</span><span class="br0">(</span><span class="nu0">1</span><span class="br0">)</span><span class="br0">]</span><span class="br0">]</span></span> +</div> <h3 id="Explanation"> Explanation</h3> <p>Attributes provide the unified standard syntax for implementation-defined language extensions, such as the GNU and IBM language extensions <code>__attribute__((...))</code>, Microsoft extension <code>__declspec()</code>, etc.</p> +<p>An attribute can be used almost everywhere in the C program, and can be applied to almost everything: to types, to variables, to functions, to names, to code blocks, to entire translation units, although each particular attribute is only valid where it is permitted by the implementation: <code>[[expect_true]]</code> could be an attribute that can only be used with an <code>if</code>, and not with a class declaration. <code>[[omp::parallel()]]</code> could be an attribute that applies to a code block or to a <code>for</code> loop, but not to the type <code>int</code>, etc. (note these two attributes are fictional examples, see below for the standard and some non-standard attributes)</p> +<p>In declarations, attributes may appear both before the whole declaration and directly after the name of the entity that is declared, in which case they are combined. In most other situations, attributes apply to the directly preceding entity.</p> +<p>Two consecutive left square bracket tokens (<code>[[</code>) may only appear when introducing an attribute-specifier or inside an attribute argument.</p> +<p>Besides the standard attributes listed below, implementations may support arbitrary non-standard attributes with implementation-defined behavior. All attributes unknown to an implementation are ignored without causing an error.</p> +<p>Every <span class="t-spar">standard-attribute</span> is reserved for standardization. That is, every non-standard attribute is prefixed by a <span class="t-spar">attribute-prefix</span> provided by the implementation, e.g. <code>[[gnu::may_alias]]</code> and <code>[[clang::no_sanitize]]</code>.</p> +<h3 id="Standard_attributes"> Standard attributes</h3> <p>Only the following attributes are defined by the C standard. Every standard attribute whose name is of form <code>attr</code> can be also spelled as <code>__attr__</code> and its meaning is not changed.</p> +<table class="t-dsc-begin"> <tr class="t-dsc"> <td> <code>[[<a href="attributes/deprecated" title="c/language/attributes/deprecated">deprecated</a>]]</code><span class="t-mark-rev t-since-c23">(C23)</span><br><code>[[<a href="attributes/deprecated" title="c/language/attributes/deprecated">deprecated</a>("<i>reason</i>")]]</code><span class="t-mark-rev t-since-c23">(C23)</span> </td> <td> indicates that the use of the name or entity declared with this attribute is allowed, but discouraged for some <span class="t-spar">reason</span><br><span class="t-mark">(attribute specifier)</span> </td> +</tr> <tr class="t-dsc"> <td> <code>[[<a href="attributes/fallthrough" title="c/language/attributes/fallthrough">fallthrough</a>]]</code><span class="t-mark-rev t-since-c23">(C23)</span> </td> <td> indicates that the fall through from the previous case label is intentional and should not be diagnosed by a compiler that warns on fall-through<br><span class="t-mark">(attribute specifier)</span> </td> +</tr> <tr class="t-dsc"> <td> <code>[[<a href="attributes/nodiscard" title="c/language/attributes/nodiscard">nodiscard</a>]]</code><span class="t-mark-rev t-since-c23">(C23)</span><br><code>[[<a href="attributes/nodiscard" title="c/language/attributes/nodiscard">nodiscard</a>("<i>reason</i>")]]</code><span class="t-mark-rev t-since-c23">(C23)</span> </td> <td> encourages the compiler to issue a warning if the return value is discarded<br><span class="t-mark">(attribute specifier)</span> </td> +</tr> <tr class="t-dsc"> <td> <code>[[<a href="attributes/maybe_unused" title="c/language/attributes/maybe unused">maybe_unused</a>]]</code><span class="t-mark-rev t-since-c23">(C23)</span> </td> <td> suppresses compiler warnings on unused entities, if any<br><span class="t-mark">(attribute specifier)</span> </td> +</tr> <tr class="t-dsc"> <td> <code>[[<a href="attributes/noreturn" title="c/language/attributes/noreturn">noreturn</a>]]</code><span class="t-mark-rev t-since-c23">(C23)</span><br><code>[[<a href="attributes/noreturn" title="c/language/attributes/noreturn">_Noreturn</a>]]</code><span class="t-mark-rev t-since-c23">(C23)</span><span class="t-mark">(deprecated)</span> </td> <td> indicates that the function does not return<br><span class="t-mark">(attribute specifier)</span> </td> +</tr> <tr class="t-dsc"> <td> <code>[[<a href="attributes/unsequenced" title="c/language/attributes/unsequenced">unsequenced</a>]]</code><span class="t-mark-rev t-since-c23">(C23)</span> </td> <td> indicates that a function is stateless, effectless, idempotent and independent<br><span class="t-mark">(attribute specifier)</span> </td> +</tr> <tr class="t-dsc"> <td> <code>[[<a href="attributes/reproducible" title="c/language/attributes/reproducible" class="mw-redirect">reproducible</a>]]</code><span class="t-mark-rev t-since-c23">(C23)</span> </td> <td> indicates that a function is effectless and idempotent<br><span class="t-mark">(attribute specifier)</span> </td> +</tr> </table> <h3 id="Attribute_testing"> Attribute testing</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <code>__has_c_attribute(</code> <span class="t-spar">attribute-token</span> <code>)</code> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>Checks for the presence of an attribute token named by <span class="t-spar">attribute-token</span>.</p> +<p>For standard attributes, it will expand to the year and month in which the attribute was added to the working draft (see table below), the presence of vendor-specific attributes is determined by a non-zero integer constant.</p> +<p><code>__has_c_attribute</code> can be expanded in the expression of <a href="../preprocessor/conditional" title="c/preprocessor/conditional"><code> #if</code></a> and <a href="../preprocessor/conditional" title="c/preprocessor/conditional"><code> #elif</code></a>. It is treated as a defined macro by <a href="../preprocessor/conditional" title="c/preprocessor/conditional"><code> #ifdef</code></a>, <a href="../preprocessor/conditional" title="c/preprocessor/conditional"><code> #ifndef</code></a> and <a href="../preprocessor/conditional" title="c/preprocessor/conditional"><code>defined</code></a> but cannot be used anywhere else.</p> +<table class="wikitable sortable"> <tr> <th> <span class="t-spar">attribute-token</span> </th> <th> Attribute </th> <th> Value </th> <th> <span title="Standard in which the feature is introduced">Standard</span> </th> +</tr> <tr> <td> +<code>deprecated</code> </td> <td> +<code>[[<a href="attributes/deprecated" title="c/language/attributes/deprecated">deprecated</a>]]</code> </td> <td> +<code>201904L</code> </td> <td> +<span class="t-mark-rev t-since-c23">(C23)</span> </td> +</tr> <tr> <td> +<code>fallthrough</code> </td> <td> +<code>[[<a href="attributes/fallthrough" title="c/language/attributes/fallthrough">fallthrough</a>]]</code> </td> <td> +<code>201904L</code> </td> <td> +<span class="t-mark-rev t-since-c23">(C23)</span> </td> +</tr> <tr> <td> +<code>maybe_unused</code> </td> <td> +<code>[[<a href="attributes/maybe_unused" title="c/language/attributes/maybe unused">maybe_unused</a>]]</code> </td> <td> +<code>201904L</code> </td> <td> +<span class="t-mark-rev t-since-c23">(C23)</span> </td> +</tr> <tr> <td> +<code>nodiscard</code> </td> <td> +<code>[[<a href="attributes/nodiscard" title="c/language/attributes/nodiscard">nodiscard</a>]]</code> </td> <td> +<code>202003L</code> </td> <td> +<span class="t-mark-rev t-since-c23">(C23)</span> </td> +</tr> <tr> <td> +<code>noreturn</code><br><code>_Noreturn</code> </td> <td> +<code>[[<a href="attributes/noreturn" title="c/language/attributes/noreturn">noreturn</a>]]</code><br><code>[[<a href="attributes/noreturn" title="c/language/attributes/noreturn">_Noreturn</a>]]</code> </td> <td> +<code>202202L</code> </td> <td> +<span class="t-mark-rev t-since-c23">(C23)</span> </td> +</tr> <tr> <td> +<code>unsequenced</code> </td> <td> +<code>[[<a href="attributes/unsequenced" title="c/language/attributes/unsequenced">unsequenced</a>]]</code> </td> <td> +<code>202207L</code> </td> <td> +<span class="t-mark-rev t-since-c23">(C23)</span> </td> +</tr> <tr> <td> +<code>reproducible</code> </td> <td> +<code>[[<a href="attributes/reproducible" title="c/language/attributes/reproducible" class="mw-redirect">reproducible</a>]]</code> </td> <td> +<code>202207L</code> </td> <td> +<span class="t-mark-rev t-since-c23">(C23)</span> </td> +</tr> +</table> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">[[gnu::hot]] [[gnu::const]] [[nodiscard]] +int f(void); // declare f with three attributes + +[[gnu::const, gnu::hot, nodiscard]] +int f(void); // the same as above, but uses a single attr + // specifier that contains three attributes + +int f(void) { return 0; } + +int main(void) +{ +}</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.7.12 Attributes (p: TBD) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/attributes" title="cpp/language/attributes">C++ documentation</a></span> for <span class=""><span>Attribute specifier sequence</span></span> </td> +</tr> </table> <h3 id="External_links"> External links</h3> <table> <tr style="vertical-align:top;"> <td>1. </td> <td> +<a rel="nofollow" class="external text" href="https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html#Attribute-Syntax">Attributes in GCC</a> </td> +</tr> <tr style="vertical-align:top;"> <td>2. </td> <td> +<a rel="nofollow" class="external text" href="https://clang.llvm.org/docs/AttributeReference.html">Attributes in Clang</a> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/attributes" class="_attribution-link">https://en.cppreference.com/w/c/language/attributes</a> + </p> +</div> diff --git a/devdocs/c/language%2Fbasic_concepts.html b/devdocs/c/language%2Fbasic_concepts.html new file mode 100644 index 00000000..f5f9fa6a --- /dev/null +++ b/devdocs/c/language%2Fbasic_concepts.html @@ -0,0 +1,13 @@ + <h1 id="firstHeading" class="firstHeading">Basic concepts</h1> <p>This section provides definitions for the specific terminology and the concepts used when describing the C programming language.</p> +<p>A C program is a sequence of text files (typically header and source files) that contain <a href="declarations" title="c/language/declarations">declarations</a>. They undergo <a href="translation_phases" title="c/language/translation phases">translation</a> to become an executable program, which is executed when the OS calls its <a href="main_function" title="c/language/main function">main function</a> (unless it is itself the OS or another <i>freestanding</i> program, in which case the entry point is implementation-defined).</p> +<p>Certain words in a C program have special meaning, they are <a href="../keyword" title="c/keyword">keywords</a>. Others can be used as <a href="identifier" title="c/language/identifier">identifiers</a>, which may be used to identify <a href="object" title="c/language/object">objects</a>, <a href="functions" title="c/language/functions">functions</a>, <a href="struct" title="c/language/struct">struct</a>, <a href="union" title="c/language/union">union</a>, or <a href="enum" title="c/language/enum">enumeration</a> tags, their members, <a href="typedef" title="c/language/typedef">typedef</a> names, <a href="statements#Labels" title="c/language/statements">labels</a>, or <a href="../preprocessor/replace" title="c/preprocessor/replace">macros</a>.</p> +<p>Each identifier (other than macro) is only valid within a part of the program called its <a href="scope" title="c/language/scope">scope</a> and belongs to one of four kinds of <a href="name_space" title="c/language/name space">name spaces</a>. Some identifiers have <a href="storage_duration" title="c/language/storage duration">linkage</a> which makes them refer to the same entities when they appear in different scopes or translation units.</p> +<p>Definitions of functions include sequences of <a href="statements" title="c/language/statements">statements</a> and <a href="declarations" title="c/language/declarations">declarations</a>, some of which include <a href="expressions" title="c/language/expressions">expressions</a>, which specify the computations to be performed by the program.</p> +<p><a href="declarations" title="c/language/declarations">Declarations</a> and <a href="expressions" title="c/language/expressions">expressions</a> create, destroy, access, and manipulate <a href="object" title="c/language/object">objects</a>. Each <a href="object" title="c/language/object">object</a>, <a href="functions" title="c/language/functions">function</a>, and <a href="expressions" title="c/language/expressions">expression</a> in C is associated with a <a href="type" title="c/language/type">type</a>.</p> +<h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/basic_concepts" title="cpp/language/basic concepts">C++ documentation</a></span> for <span class=""><span>Basic concepts</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/basic_concepts" class="_attribution-link">https://en.cppreference.com/w/c/language/basic_concepts</a> + </p> +</div> diff --git a/devdocs/c/language%2Fbehavior.html b/devdocs/c/language%2Fbehavior.html new file mode 100644 index 00000000..0a883ffc --- /dev/null +++ b/devdocs/c/language%2Fbehavior.html @@ -0,0 +1,166 @@ + <h1 id="firstHeading" class="firstHeading">Undefined behavior</h1> <p>The C language standard precisely specifies the <a href="as_if" title="c/language/as if">observable behavior</a> of C language programs, except for the ones in the following categories:</p> +<ul> +<li> <i>undefined behavior</i> - there are no restrictions on the behavior of the program. Examples of undefined behavior are memory accesses outside of array bounds, signed integer overflow, null pointer dereference, modification of the same scalar <a href="eval_order" title="c/language/eval order">more than once</a> in an expression without sequence points, access to an object through a pointer of a different type, etc. Compilers are not required to diagnose undefined behavior (although many simple situations are diagnosed), and the compiled program is not required to do anything meaningful. </li> +<li> <i>unspecified behavior</i> - two or more behaviors are permitted and the implementation is not required to document the effects of each behavior. For example, <a href="eval_order" title="c/language/eval order">order of evaluation</a>, whether identical <a href="string_literal" title="c/language/string literal">string literals</a> are distinct, etc. Each unspecified behavior results in one of a set of valid results and may produce a different result when repeated in the same program. </li> +<li> <i>implementation-defined behavior</i> - unspecified behavior where each implementation documents how the choice is made. For example, number of bits in a byte, or whether signed integer right shift is arithmetic or logical. </li> +<li> <i>locale-specific behavior</i> - implementation-defined behavior that depends on the <a href="../locale/setlocale" title="c/locale/setlocale">currently chosen locale</a>. For example, whether <code><a href="../string/byte/islower" title="c/string/byte/islower">islower</a></code> returns true for any character other than the 26 lowercase Latin letters. </li> +</ul> <p>(Note: <a href="conformance" title="c/language/conformance">Strictly conforming</a> programs do not depend on any unspecified, undefined, or implementation-defined behavior)</p> +<p>The compilers are required to issue diagnostic messages (either errors or warnings) for any programs that violates any C syntax rule or semantic constraint, even if its behavior is specified as undefined or implementation-defined or if the compiler provides a language extension that allows it to accept such program. Diagnostics for undefined behavior are not otherwise required.</p> +<h3 id="UB_and_optimization"> UB and optimization</h3> <p>Because correct C programs are free of undefined behavior, compilers may produce unexpected results when a program that actually has UB is compiled with optimization enabled:</p> +<p>For example,</p> +<h4 id="Signed_overflow"> Signed overflow</h4> <div class="c source-c"><pre data-language="c">int foo(int x) +{ + return x + 1 > x; // either true or UB due to signed overflow +}</pre></div> <p>may be compiled as (<a rel="nofollow" class="external text" href="https://godbolt.org/z/9dh7b71TK">demo</a>)</p> +<div class="c source-c"><pre data-language="c">foo: + mov eax, 1 + ret</pre></div> <h4 id="Access_out_of_bounds"> Access out of bounds</h4> <div class="c source-c"><pre data-language="c">int table[4] = {0}; +int exists_in_table(int v) +{ + // return 1 in one of the first 4 iterations or UB due to out-of-bounds access + for (int i = 0; i <= 4; i++) + if (table[i] == v) + return 1; + return 0; +}</pre></div> <p>May be compiled as (<a rel="nofollow" class="external text" href="https://godbolt.org/z/48bn19Tsb">demo</a>)</p> +<div class="c source-c"><pre data-language="c">exists_in_table: + mov eax, 1 + ret</pre></div> <h4 id="Uninitialized_scalar"> Uninitialized scalar</h4> <div class="c source-c"><pre data-language="c">_Bool p; // uninitialized local variable +if (p) // UB access to uninitialized scalar + puts("p is true"); +if (!p) // UB access to uninitialized scalar + puts("p is false");</pre></div> <p>May produce the following output (observed with an older version of gcc):</p> +<div class="c source-c"><pre data-language="c">p is true +p is false</pre></div> <div class="c source-c"><pre data-language="c">size_t f(int x) +{ + size_t a; + if (x) // either x nonzero or UB + a = 42; + return a; +}</pre></div> <p>May be compiled as (<a rel="nofollow" class="external text" href="https://godbolt.org/z/9nz6EMPTG">demo</a>)</p> +<div class="c source-c"><pre data-language="c">f: + mov eax, 42 + ret</pre></div> <h4 id="Invalid_scalar"> Invalid scalar</h4> <div class="c source-c"><pre data-language="c">int f(void) +{ + _Bool b = 0; + unsigned char* p = (unsigned char*)&b; + *p = 10; + // reading from b is now UB + return b == 0; +}</pre></div> <p>May be compiled as (<a rel="nofollow" class="external text" href="https://godbolt.org/z/rjx77bjoh">demo</a>)</p> +<div class="c source-c"><pre data-language="c">f: + mov eax, 11 + ret</pre></div> <h4 id="Null_pointer_dereference"> Null pointer dereference</h4> <div class="c source-c"><pre data-language="c">int foo(int* p) +{ + int x = *p; + if (!p) + return x; // Either UB above or this branch is never taken + else + return 0; +} + +int bar() +{ + int* p = NULL; + return *p; // Unconditional UB +}</pre></div> <p>may be compiled as (<a rel="nofollow" class="external text" href="https://godbolt.org/z/8jnjMjcPz">demo</a>)</p> +<div class="c source-c"><pre data-language="c">foo: + xor eax, eax + ret +bar: + ret</pre></div> <h4 id="Access_to_pointer_passed_to_realloc"> Access to pointer passed to <code><a href="../memory/realloc" title="c/memory/realloc">realloc</a></code> +</h4> <div class="t-example"> +<p>Choose clang to observe the output shown</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + int *p = (int*)malloc(sizeof(int)); + int *q = (int*)realloc(p, sizeof(int)); + *p = 1; // UB access to a pointer that was passed to realloc + *q = 2; + if (p == q) // UB access to a pointer that was passed to realloc + printf("%d%d\n", *p, *q); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">12</pre></div> </div> <h4 id="Infinite_loop_without_side-effects"> Infinite loop without side-effects</h4> <div class="t-example"> +<p>Choose clang to observe the output shown</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> + +int fermat() +{ + const int MAX = 1000; + // Endless loop with no side effects is UB + for (int a = 1, b = 1, c = 1; 1;) + { + if (((a * a * a) == ((b * b * b) + (c * c * c)))) + return 1; + ++a; + if (a > MAX) + { + a = 1; + ++b; + } + if (b > MAX) + { + b = 1; + ++c; + } + if (c > MAX) + c = 1; + } + return 0; +} + +int main(void) +{ + if (fermat()) + puts("Fermat's Last Theorem has been disproved."); + else + puts("Fermat's Last Theorem has not been disproved."); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Fermat's Last Theorem has been disproved.</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 3.4 Behavior (p: TBD) </li> +<li> 4 Conformance (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 3.4 Behavior (p: 3-4) </li> +<li> 4 Conformance (p: 8) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 3.4 Behavior (p: 3-4) </li> +<li> 4/2 Undefined behavior (p: 8) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 3.4 Behavior (p: 3-4) </li> +<li> 4/2 Undefined behavior (p: 7) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 1.6 DEFINITIONS OF TERMS </li></ul> +</ul> <h3 id="External_links"> External links</h3> <table> <tr style="vertical-align:top;"> <td>1. </td> <td> +<a rel="nofollow" class="external text" href="https://blog.llvm.org/2011/05/what-every-c-programmer-should-know.html">What Every C Programmer Should Know About Undefined Behavior #1/3</a> </td> +</tr> <tr style="vertical-align:top;"> <td>2. </td> <td> +<a rel="nofollow" class="external text" href="https://blog.llvm.org/2011/05/what-every-c-programmer-should-know_14.html">What Every C Programmer Should Know About Undefined Behavior #2/3</a> </td> +</tr> <tr style="vertical-align:top;"> <td>3. </td> <td> +<a rel="nofollow" class="external text" href="https://blog.llvm.org/2011/05/what-every-c-programmer-should-know_21.html">What Every C Programmer Should Know About Undefined Behavior #3/3</a> </td> +</tr> <tr style="vertical-align:top;"> <td>4. </td> <td> +<a rel="nofollow" class="external text" href="https://blogs.msdn.com/b/oldnewthing/archive/2014/06/27/10537746.aspx">Undefined behavior can result in time travel (among other things, but time travel is the funkiest)</a> </td> +</tr> <tr style="vertical-align:top;"> <td>5. </td> <td> +<a rel="nofollow" class="external text" href="https://www.cs.utah.edu/~regehr/papers/overflow12.pdf">Understanding Integer Overflow in C/C++</a> </td> +</tr> <tr style="vertical-align:top;"> <td>6. </td> <td> +<a rel="nofollow" class="external text" href="https://web.archive.org/web/20201108094235/https://kukuruku.co/post/undefined-behavior-and-fermats-last-theorem/">Undefined Behavior and Fermat’s Last Theorem</a> </td> +</tr> <tr style="vertical-align:top;"> <td>7. </td> <td> +<a rel="nofollow" class="external text" href="https://lwn.net/Articles/342330/">Fun with NULL pointers, part 1</a> (local exploit in Linux 2.6.30 caused by UB due to null pointer dereference) </td> +</tr> +</table> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/ub" title="cpp/language/ub">C++ documentation</a></span> for <span class=""><span>Undefined behavior</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/behavior" class="_attribution-link">https://en.cppreference.com/w/c/language/behavior</a> + </p> +</div> diff --git a/devdocs/c/language%2Fbit_field.html b/devdocs/c/language%2Fbit_field.html new file mode 100644 index 00000000..016f0ca2 --- /dev/null +++ b/devdocs/c/language%2Fbit_field.html @@ -0,0 +1,102 @@ + <h1 id="firstHeading" class="firstHeading">Bit-fields</h1> <p>Declares a member with explicit width, in bits. Adjacent bit-field members may be packed to share and straddle the individual bytes.</p> +<p>A bit-field declaration is a <a href="struct" title="c/language/struct">struct</a> or <a href="union" title="c/language/union">union</a> member declaration which uses the following <a href="declarations" title="c/language/declarations">declarator</a>:</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">identifier</span> <span class="t-mark">(optional)</span> <code>:</code> <span class="t-spar">width</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">identifier</span> </td> <td> - </td> <td> a name of the bit-field that is being declared. The name is optional: nameless bit-fields introduce the specified number of bits of padding </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">width</span> </td> <td> - </td> <td> an integer <a href="constant_expression" title="c/language/constant expression">constant expression</a> with a value greater or equal to zero and less or equal the number of bits in the underlying type. When greater than zero, this is the number of bits that this bit-field will occupy. The value zero is only allowed for nameless bit-fields and has special meaning: it specifies that the next bit-field in the class definition will begin at an allocation unit's boundary. </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>Bit-fields can have only one of these <span class="t-rev-inl t-until-c99"><span>three</span><span><span class="t-mark-rev t-until-c99">(until C99)</span></span></span> – <span class="t-rev-inl t-since-c99 t-until-c23"><span>four</span><span><span class="t-mark-rev t-since-c99">(since C99)</span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span> types (possibly <a href="const" title="c/language/const">const</a> or <a href="volatile" title="c/language/volatile">volatile</a> qualified):</p> +<ul> +<li> <code>unsigned int</code>, for unsigned bit-fields (<code>unsigned int b:3;</code> has the range <code>0..7</code>) </li> +<li> <code>signed int</code>, for signed bit-fields (<code>signed int b:3;</code> has the range <code>-4..3</code>) </li> +<li> <code>int</code>, for bit-fields with implementation-defined signedness (Note that this differs from the meaning of the keyword <code>int</code> everywhere else, where it means "signed int"). For example, <code>int b:3;</code> may have the range of values <code>0..7</code> or <code>-4..3</code>. </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <ul><li> <code>_Bool</code>, for single-bit bit-fields (<code>bool x:1;</code>) has the range <code>0..1</code> and <a href="conversion" title="c/language/conversion">implicit conversions</a> to and from it follow the boolean conversion rules. </li></ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td> <ul><li> bit-precise integer types. (e.g. <code>_BitInt(5):4;</code> has the range <code>-8..7</code> and <code>unsigned _BitInt(5):4;</code> has the range <code>0..15</code>). </li></ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <p>Additional implementation-defined types may be acceptable. <span class="t-rev-inl t-since-c11"><span>It is also implementation-defined whether a bit-field may have <a href="atomic" title="c/language/atomic">atomic</a> type.</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> The number of bits in a bit-field (<span class="t-spar">width</span>) sets the limit to the range of values it can hold:</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +struct S +{ + // three-bit unsigned field, + // allowed values are 0...7 + unsigned int b : 3; +}; + +int main(void) +{ + struct S s = {7}; + ++s.b; // unsigned overflow + printf("%d\n", s.b); // output: 0 +}</pre></div> </div> <p>Multiple adjacent bit-fields are permitted to be (and usually are) packed together:</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +struct S +{ + // will usually occupy 4 bytes: + // 5 bits: value of b1 + // 11 bits: unused + // 6 bits: value of b2 + // 2 bits: value of b3 + // 8 bits: unused + unsigned b1 : 5, : 11, b2 : 6, b3 : 2; +}; + +int main(void) +{ + printf("%zu\n",sizeof(struct S)); // usually prints 4 +}</pre></div> </div> <p>The special <i>unnamed bit-field</i> of <span class="t-spar">width</span> zero breaks up padding: it specifies that the next bit-field begins at the beginning of the next allocation unit:</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +struct S +{ + // will usually occupy 8 bytes: + // 5 bits: value of b1 + // 27 bits: unused + // 6 bits: value of b2 + // 15 bits: value of b3 + // 11 bits: unused + unsigned b1 : 5; + unsigned :0; // start a new unsigned int + unsigned b2 : 6; + unsigned b3 : 15; +}; + +int main(void) +{ + printf("%zu\n", sizeof(struct S)); // usually prints 8 +}</pre></div> </div> <p>Because bit-fields do not necessarily begin at the beginning of a byte, address of a bit-field cannot be taken. Pointers to bit-fields are not possible. Bit-fields cannot be used with <a href="sizeof" title="c/language/sizeof"><code>sizeof</code></a> <span class="t-rev-inl t-since-c11"><span>and <a href="_alignas" title="c/language/ Alignas"><code>_Alignas</code></a></span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span>.</p> +<h3 id="Notes"> Notes</h3> <p>The following usages of bit-fields causes <i>undefined behavior</i>:</p> +<ul><li> Calling <code><a href="../types/offsetof" title="c/types/offsetof">offsetof</a></code> on a bit-field </li></ul> <p>The following properties of bit-fields are <i>unspecified</i>:</p> +<ul><li> Alignment of the allocation unit that holds a bit-field </li></ul> <p>The following properties of bit-fields are <i>implementation-defined</i>:</p> +<ul> +<li> Whether bit-fields of type <code>int</code> are treated as signed or unsigned </li> +<li> Whether types other than <code>int</code>, <code>signed int</code>, <code>unsigned int</code><span class="t-rev-inl t-since-c99"><span>, <code>_Bool</code></span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> <span class="t-rev-inl t-since-c23"><span>and (possibly <code>unsigned</code>) <code>_BitInt(N)</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> are permitted </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <ul><li> Whether atomic types are permitted </li></ul> </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <ul> +<li> Whether a bit-field can straddle an allocation unit boundary </li> +<li> The order of bit-fields within an allocation unit (on some platforms, bit-fields are packed left-to-right, on others right-to-left) </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>Even though the number of bits in the object representation of <code>_Bool</code> is at least <code><a href="../types/limits" title="c/types/limits">CHAR_BIT</a></code>, the <span class="t-spar">width</span> of the bit-field of type <code>_Bool</code> cannot be greater than 1.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <p>In the C++ programming language, the width of a bit-field can exceed the width of the underlying type (but the extra bits are padding bits), and bit-fields of type <code>int</code> are always signed.</p> +<h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.7.2.1 Structure and union specifiers </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.7.2.1 Structure and union specifiers </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.7.2.1 Structure and union specifiers </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.7.2.1 Structure and union specifiers </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.5.2.1 Structure and union specifiers </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/bit_field" title="cpp/language/bit field">C++ documentation</a></span> for <span class=""><span>Bit-field</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/bit_field" class="_attribution-link">https://en.cppreference.com/w/c/language/bit_field</a> + </p> +</div> diff --git a/devdocs/c/language%2Fbool_constant.html b/devdocs/c/language%2Fbool_constant.html new file mode 100644 index 00000000..f3be4efd --- /dev/null +++ b/devdocs/c/language%2Fbool_constant.html @@ -0,0 +1,21 @@ + <h1 id="firstHeading" class="firstHeading">Predefined Boolean constants <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>true</code> </td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>false</code> </td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>Keywords <code>true</code> and <code>false</code> represent predefined constants. They are <a href="value_category#Non-lvalue_object_expressions" title="c/language/value category">non-lvalues</a> of type <a href="types" title="c/language/types" class="mw-redirect"><code>bool</code></a>.</p> +<h3 id="Notes"> Notes</h3> <p>See <a href="conversion#Integer_conversions" title="c/language/conversion">integral conversions</a> for implicit conversions from <code>bool</code> to other types and <a href="conversion#Boolean_conversion" title="c/language/conversion">boolean conversions</a> for the implicit conversions from other types to <code>bool</code>.</p> +<p>Until C23, <code>true</code> and <code>false</code> were implemented as macros provided in <a href="../types" title="c/types"><code><stdbool.h></code></a>. An implementation may also define <code>bool</code>, <code>true</code>, and <code>false</code> as predefined macros in C23 for compatibility.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +int main(void) +{ + printf("%d\n%d\n", true, false); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">1 +0</pre></div> </div> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/bool_literal" title="cpp/language/bool literal">C++ documentation</a></span> for <span class=""><span>Boolean literals</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/bool_constant" class="_attribution-link">https://en.cppreference.com/w/c/language/bool_constant</a> + </p> +</div> diff --git a/devdocs/c/language%2Fbreak.html b/devdocs/c/language%2Fbreak.html new file mode 100644 index 00000000..bf2423f9 --- /dev/null +++ b/devdocs/c/language%2Fbreak.html @@ -0,0 +1,62 @@ + <h1 id="firstHeading" class="firstHeading">break statement</h1> <p>Causes the enclosing <a href="for" title="c/language/for">for</a>, <a href="while" title="c/language/while">while</a> or <a href="do" title="c/language/do">do-while</a> loop or <a href="switch" title="c/language/switch">switch statement</a> to terminate.</p> +<p>Used when it is otherwise awkward to terminate the loop using the condition expression and conditional statements.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">attr-spec-seq</span> <span class="t-mark">(optional)</span> <code>break</code> <code>;</code> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">attr-spec-seq</span> </td> <td> - </td> <td> <span class="t-mark-rev t-since-c23">(C23)</span> optional list of <a href="attributes" title="c/language/attributes">attributes</a>, applied to the <code>break</code> statement </td> +</tr> +</table> <p>Appears only within the <span class="t-spar">statement</span> of a loop body (<a href="while" title="c/language/while"><code>while</code></a>, <a href="do" title="c/language/do"><code>do-while</code></a>, <a href="for" title="c/language/for"><code>for</code></a>) or within the <span class="t-spar">statement</span> of a <a href="switch" title="c/language/switch"><code>switch</code></a>.</p> +<h3 id="Explanation"> Explanation</h3> <p>After this statement the control is transferred to the statement or declaration immediately following the enclosing loop or switch, as if by <a href="goto" title="c/language/goto"><code>goto</code></a>.</p> +<h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/break" title="c/keyword/break"><code>break</code></a></p> +<h3 id="Notes"> Notes</h3> <p>A break statement cannot be used to break out of multiple nested loops. The <a href="goto" title="c/language/goto"><code>goto</code> statement</a> may be used for this purpose.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +int main(void) +{ + int i = 2; + switch (i) + { + case 1: printf("1"); + case 2: printf("2"); // i==2, so execution starts at this case label + case 3: printf("3"); + case 4: + case 5: printf("45"); + break; // execution of subsequent cases is terminated + case 6: printf("6"); + } + printf("\n"); + + // Compare outputs from these two nested for loops. + for (int j = 0; j < 2; j++) + for (int k = 0; k < 5; k++) + printf("%d%d ", j,k); + printf("\n"); + + for (int j = 0; j < 2; j++) + { + for (int k = 0; k < 5; k++) // only this loop is exited by break + { + if (k == 2) + break; + printf("%d%d ", j,k); + } + } +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">2345 +00 01 02 03 04 10 11 12 13 14 +00 01 10 11</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.8.6.3 The break statement (p: 111) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.8.6.3 The break statement (p: 153) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.8.6.3 The break statement (p: 138) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.6.6.3 The break statement </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <code>[[<a href="attributes/fallthrough" title="c/language/attributes/fallthrough">fallthrough</a>]]</code><span class="t-mark-rev t-since-c23">(C23)</span> </td> <td> indicates that the fall through from the previous case label is intentional and should not be diagnosed by a compiler that warns on fall-through<br><span class="t-mark">(attribute specifier)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/break" title="cpp/language/break">C++ documentation</a></span> for <span class=""><span><code>break</code> statement</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/break" class="_attribution-link">https://en.cppreference.com/w/c/language/break</a> + </p> +</div> diff --git a/devdocs/c/language%2Fcast.html b/devdocs/c/language%2Fcast.html new file mode 100644 index 00000000..aae5fe1a --- /dev/null +++ b/devdocs/c/language%2Fcast.html @@ -0,0 +1,64 @@ + <h1 id="firstHeading" class="firstHeading">cast operator</h1> <p>Performs explicit type conversion</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <code>(</code> <span class="t-spar">type-name</span> <code>)</code> <span class="t-spar">expression</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">type-name</span> </td> <td> - </td> <td> either the type <code>void</code> or any <a href="type#Type_groups" title="c/language/type">scalar type</a> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">expression</span> </td> <td> - </td> <td> any <a href="expressions" title="c/language/expressions">expression</a> of <a href="type#Type_groups" title="c/language/type">scalar type</a> (unless <span class="t-spar">type-name</span> is void, in which case it can be anything) </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>If <span class="t-spar">type-name</span> is <code>void</code>, then <span class="t-spar">expression</span> is evaluated for its side-effects and its returned value is discarded, same as when <span class="t-spar">expression</span> is used on its own, as an <a href="statements#Expression_statements" title="c/language/statements">expression statement</a>.</p> +<p>Otherwise, if <span class="t-spar">type-name</span> is exactly the type of <span class="t-spar">expression</span>, nothing is done (except that if <span class="t-spar">expression</span> has floating type and is represented with greater range and precision than its type indicates -- see below)</p> +<p>Otherwise, the value of <span class="t-spar">expression</span> is converted to the type named by <span class="t-spar">type-name</span>, as follows:</p> +<p>Every <a href="conversion" title="c/language/conversion">implicit conversion as if by assignment</a> is allowed.</p> +<p>In addition to the implicit conversions, the following conversions are allowed:</p> +<ul> +<li> Any integer can be cast to any pointer type. Except for the null pointer constants such as <code><a href="../types/null" title="c/types/NULL">NULL</a></code> (which <a href="conversion" title="c/language/conversion">doesn't need a cast</a>), the result is implementation-defined, may not be correctly aligned, may not point to an object of the referenced type, and may be a <a href="object" title="c/language/object">trap representation</a>. </li> +<li> Any pointer type can be cast to any integer type. The result is implementation-defined, even for null pointer values (they do not necessarily result in the value zero). If the result cannot be represented in the target type, the behavior is undefined (unsigned integers do not implement modulo arithmetic on a cast from pointer) </li> +<li> Any pointer to object can be cast to any other pointer to object. If the value is not correctly aligned for the target type, the behavior is undefined. Otherwise, if the value is converted back to the original type, it compares equal to the original value. If a pointer to object is cast to pointer to any character type, the result points at the lowest byte of the object and may be incremented up to sizeof the target type (in other words, can be used to examine <a href="object" title="c/language/object">object representation</a> or to make a copy via <code><a href="../string/byte/memcpy" title="c/string/byte/memcpy">memcpy</a></code> or <code><a href="../string/byte/memmove" title="c/string/byte/memmove">memmove</a></code>). </li> +<li> Any pointer to function can be cast to a pointer to any other function type. If the resulting pointer is converted back to the original type, it compares equal to the original value. If the converted pointer is used to make a function call, the behavior is undefined (unless the function types are <a href="type#Compatible_types" title="c/language/type">compatible</a>) </li> +<li> When casting between pointers (either object or function), if the original value is a null pointer value of its type, the result is the correct null pointer value for the target type. </li> +</ul> <p>In any case (both when executing an implicit conversion and in the same-type cast), if <span class="t-spar">expression</span> and <span class="t-spar">type-name</span> are floating types and <span class="t-spar">expression</span> is represented with greater range and precision than its type indicates (see <code><a href="../types/limits/flt_eval_method" title="c/types/limits/FLT EVAL METHOD">FLT_EVAL_METHOD</a></code>), the range and precision are stripped off to match the target type.</p> +<p>The <a href="value_category" title="c/language/value category">value category</a> of the cast expression is always non-lvalue.</p> +<h3 id="Notes"> Notes</h3> <p>Because <a href="const" title="c/language/const"><code>const</code></a>, <a href="volatile" title="c/language/volatile"><code>volatile</code></a>, <a href="restrict" title="c/language/restrict"><code>restrict</code></a>, and <a href="atomic" title="c/language/atomic"><code>_Atomic</code></a> qualifiers have effect on <a href="value_category" title="c/language/value category">lvalues</a> only, a cast to a cvr-qualified or atomic type is exactly equivalent to the cast to the corresponding unqualified type.</p> +<p>The cast to <code>void</code> is sometimes useful to silence compiler warnings about unused results.</p> +<p>The conversions not listed here are not allowed. In particular,</p> +<ul> +<li> there are no conversions between pointers and floating types </li> +<li> there are no conversions between pointers to functions and pointers to objects (including <code>void*</code>) </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>If the implementation provides <code><a href="../types/integer" title="c/types/integer">intptr_t</a></code> and/or <code><a href="../types/integer" title="c/types/integer">uintptr_t</a></code>, then a cast from a pointer to an object type (including <i>cv</i> <code>void</code>) to these types is always well-defined. However, this is not guaranteed for a function pointer.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <p>Note that conversions between function pointers and object pointers are accepted as extensions by many compilers, and expected by some usages of <a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/dlsym.html">POSIX <code>dlsym()</code> function</a>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +int main(void) +{ + // examining object representation is a legitimate use of cast + double d = 3.14; + printf("The double %.2f (%a) is: ", d, d); + for (size_t n = 0; n < sizeof d; ++n) + printf("0x%02x ", ((unsigned char*)&d)[n]); + + // edge cases + struct S { int x; } s; +// (struct S)s; // error; not a scalar type + // even though casting to the same type does nothing + (void)s; // okay to cast any type to void +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">The double 3.14 (0x1.91eb851eb851fp+1) is: 0x1f 0x85 0xeb 0x51 0xb8 0x1e 0x09 0x40</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.5.4 Cast operators (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.5.4 Cast operators (p: 65-66) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.5.4 Cast operators (p: 91) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.5.4 Cast operators (p: 81) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.3.4 Cast operators </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/explicit_cast" title="cpp/language/explicit cast">C++ documentation</a></span> for <span class=""><span>explicit type conversion</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/cast" class="_attribution-link">https://en.cppreference.com/w/c/language/cast</a> + </p> +</div> diff --git a/devdocs/c/language%2Fcharacter_constant.html b/devdocs/c/language%2Fcharacter_constant.html new file mode 100644 index 00000000..acf4a443 --- /dev/null +++ b/devdocs/c/language%2Fcharacter_constant.html @@ -0,0 +1,106 @@ + <h1 id="firstHeading" class="firstHeading">Character constant</h1> <h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>'</code><span class="t-spar">c-char</span> <code>'</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>u8'</code><span class="t-spar">c-char</span> <code>'</code> </td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>u'</code><span class="t-spar">c-char</span> <code>'</code> </td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>U'</code><span class="t-spar">c-char</span> <code>'</code> </td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>L'</code><span class="t-spar">c-char</span> <code>'</code> </td> <td> (5) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>'</code><span class="t-spar">c-char-sequence</span> <code>'</code> </td> <td> (6) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>L'</code><span class="t-spar">c-char-sequence</span> <code>'</code> </td> <td> (7) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>u'</code><span class="t-spar">c-char-sequence</span> <code>'</code> </td> <td> (8) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span><span class="t-mark-rev t-until-c23">(removed in C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>U'</code><span class="t-spar">c-char-sequence</span> <code>'</code> </td> <td> (9) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span><span class="t-mark-rev t-until-c23">(removed in C23)</span> </td> +</tr> +</table> <p>where</p> +<ul> +<li> <span class="t-spar">c-char</span> is either </li> +<ul> +<li> a character from the basic source character set minus single-quote (<code>'</code>), backslash (<code>\</code>), or the newline character. </li> +<li> escape sequence: one of special character escapes <code>\'</code> <code>\"</code> <code>\?</code> <code>\\</code> <code>\a</code> <code>\b</code> <code>\f</code> <code>\n</code> <code>\r</code> <code>\t</code> <code>\v</code>, hex escapes <code>\x...</code> or octal escapes <code>\...</code> as defined in <a href="escape" title="c/language/escape">escape sequences</a>. </li> +</ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <ul><li>universal character name, <code>\u...</code> or <code>\U...</code> as defined in <a href="escape" title="c/language/escape">escape sequences</a>. </li></ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <ul><li> <span class="t-spar">c-char-sequence</span> is a sequence of two or more <span class="t-spar">c-char</span>s. </li></ul> <div class="t-li1"> +<span class="t-li">1)</span> single-byte integer character constant, e.g. <code>'a'</code> or <code>'\n'</code> or <code>'\13'</code>. Such constant has type <code>int</code> and a value equal to the representation of <span class="t-spar">c-char</span> in the execution character set as a value of type <code>char</code> mapped to <code>int</code>. If <span class="t-spar">c-char</span> is not representable as a single byte in the execution character set, the value is implementation-defined.</div> <div class="t-li1"> +<span class="t-li">2)</span> UTF-8 character constant, e.g. <code>u8'a'</code>. Such constant has type <code>char8_t</code> and the value equal to ISO 10646 code point value of <span class="t-spar">c-char</span>, provided that the code point value is representable with a single UTF-8 code unit (that is, <span class="t-spar">c-char</span> is in the range 0x0-0x7F, inclusive). If <span class="t-spar">c-char</span> is not representable with a single UTF-8 code unit, the program is ill-formed.</div> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <span class="t-li">3)</span> 16-bit wide character constant, e.g. <code>u'貓'</code>, but not <code>u'🍌'</code> (<code>u'\U0001f34c'</code>). Such constant has type <code>char16_t</code> and a value equal to the value of <span class="t-spar">c-char</span> in the 16-bit encoding produced by <code><a href="../string/multibyte/mbrtoc16" title="c/string/multibyte/mbrtoc16">mbrtoc16</a></code> (normally UTF-16). If <span class="t-spar">c-char</span> is not representable or maps to more than one 16-bit character, the value is implementation-defined. <span class="t-li">4)</span> 32-bit wide character constant, e.g. <code>U'貓'</code> or <code>U'🍌'</code>. Such constant has type <code>char32_t</code> and a value equal to the value of <span class="t-spar">c-char</span> in in the 32-bit encoding produced by <code><a href="../string/multibyte/mbrtoc32" title="c/string/multibyte/mbrtoc32">mbrtoc32</a></code> (normally UTF-32). If <span class="t-spar">c-char</span> is not representable or maps to more than one 32-bit character, the value is implementation-defined. </td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td> <span class="t-li">3)</span> UTF-16 character constant, e.g. <code>u'貓'</code>, but not <code>u'🍌'</code> (<code>u'\U0001f34c'</code>). Such constant has type <code>char16_t</code> and the value equal to ISO 10646 code point value of <span class="t-spar">c-char</span>, provided that the code point value is representable with a single UTF-16 code unit (that is, <span class="t-spar">c-char</span> is in the range 0x0-0xD7FF or 0xE000-0xFFFF, inclusive). If <span class="t-spar">c-char</span> is not representable with a single UTF-16 code unit, the program is ill-formed. <span class="t-li">4)</span> UTF-32 character constant, e.g. <code>U'貓'</code> or <code>U'🍌'</code>. Such constant has type <code>char32_t</code> and the value equal to ISO 10646 code point value of <span class="t-spar">c-char</span>, provided that the code point value is representable with a single UTF-32 code unit (that is, <span class="t-spar">c-char</span> is in the range 0x0-0xD7FF or 0xE000-0x10FFFF, inclusive). If <span class="t-spar">c-char</span> is not representable with a single UTF-32 code unit, the program is ill-formed. </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <div class="t-li1"> +<span class="t-li">5)</span> wide character constant, e.g. <code>L'β'</code> or <code>L'貓</code>. Such constant has type <code>wchar_t</code> and a value equal to the value of <span class="t-spar">c-char</span> in the execution wide character set (that is, the value that would be produced by <code><a href="../string/multibyte/mbtowc" title="c/string/multibyte/mbtowc">mbtowc</a></code>). If <span class="t-spar">c-char</span> is not representable or maps to more than one wide character (e.g. a non-BMP value on Windows where <code>wchar_t</code> is 16-bit), the value is implementation-defined .</div> <div class="t-li1"> +<span class="t-li">6)</span> multicharacter constant, e.g. <code>'AB'</code>, has type <code>int</code> and implementation-defined value.</div> <div class="t-li1"> +<span class="t-li">7)</span> wide multicharacter constant, e.g. <code>L'AB'</code>, has type <code>wchar_t</code> and implementation-defined value.</div> <div class="t-li1"> +<span class="t-li">8)</span> 16-bit multicharacter constant, e.g. <code>u'CD'</code>, has type <code>char16_t</code> and implementation-defined value.</div> <div class="t-li1"> +<span class="t-li">9)</span> 32-bit multicharacter constant, e.g. <code>U'XY'</code>, has type <code>char32_t</code> and implementation-defined value.</div> <h3 id="Notes"> Notes</h3> <p>Multicharacter constants were inherited by C from the B programming language. Although not specified by the C standard, most compilers (MSVC is a notable exception) implement multicharacter constants as specified in B: the values of each char in the constant initialize successive bytes of the resulting integer, in big-endian zero-padded right-adjusted order, e.g. the value of <code>'\1'</code> is <code>0x00000001</code> and the value of <code>'\1\2\3\4'</code> is <code>0x01020304</code>.</p> +<p>In C++, encodable ordinary character literals have type <code>char</code>, rather than <code>int</code>.</p> +<p>Unlike <a href="integer_constant" title="c/language/integer constant">integer constants</a>, a character constant may have a negative value if <code>char</code> is signed: on such implementations <code>'\xFF'</code> is an <code>int</code> with the value <code>-1</code>.</p> +<p>When used in a controlling expression of <a href="../preprocessor/conditional" title="c/preprocessor/conditional"><code> #if</code></a> or <a href="../preprocessor/conditional" title="c/preprocessor/conditional"><code> #elif</code></a>, character constants may be interpreted in terms of the source character set, the execution character set, or some other implementation-defined character set.</p> +<p>16/32-bit multicharacter constants are not widely supported and removed in C23. Some common implementations (e.g. clang) do not accept them at all.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stddef.h> +#include <stdio.h> +#include <uchar.h> + +int main (void) +{ + printf("constant value \n"); + printf("-------- ----------\n"); + + // integer character constants, + int c1='a'; printf("'a':\t %#010x\n", c1); + int c2='🍌'; printf("'🍌':\t %#010x\n\n", c2); // implementation-defined + + // multicharacter constant + int c3='ab'; printf("'ab':\t %#010x\n\n", c3); // implementation-defined + + // 16-bit wide character constants + char16_t uc1 = u'a'; printf("'a':\t %#010x\n", (int)uc1); + char16_t uc2 = u'¢'; printf("'¢':\t %#010x\n", (int)uc2); + char16_t uc3 = u'猫'; printf("'猫':\t %#010x\n", (int)uc3); + // implementation-defined (🍌 maps to two 16-bit characters) + char16_t uc4 = u'🍌'; printf("'🍌':\t %#010x\n\n", (int)uc4); + + // 32-bit wide character constants + char32_t Uc1 = U'a'; printf("'a':\t %#010x\n", (int)Uc1); + char32_t Uc2 = U'¢'; printf("'¢':\t %#010x\n", (int)Uc2); + char32_t Uc3 = U'猫'; printf("'猫':\t %#010x\n", (int)Uc3); + char32_t Uc4 = U'🍌'; printf("'🍌':\t %#010x\n\n", (int)Uc4); + + // wide character constants + wchar_t wc1 = L'a'; printf("'a':\t %#010x\n", (int)wc1); + wchar_t wc2 = L'¢'; printf("'¢':\t %#010x\n", (int)wc2); + wchar_t wc3 = L'猫'; printf("'猫':\t %#010x\n", (int)wc3); + wchar_t wc4 = L'🍌'; printf("'🍌':\t %#010x\n\n", (int)wc4); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">constant value +-------- ---------- +'a': 0x00000061 +'🍌': 0xf09f8d8c + +'ab': 0x00006162 + +'a': 0x00000061 +'¢': 0x000000a2 +'猫': 0x0000732b +'🍌': 0x0000df4c + +'a': 0x00000061 +'¢': 0x000000a2 +'猫': 0x0000732b +'🍌': 0x0001f34c + +'a': 0x00000061 +'¢': 0x000000a2 +'猫': 0x0000732b +'🍌': 0x0001f34c</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.4.4.4 Character constants (p: 48-50) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.4.4.4 Character constants (p: 67-70) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.4.4.4 Character constants (p: 59-61) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.1.3.4 Character constants </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/character_literal" title="cpp/language/character literal">C++ documentation</a></span> for <span class=""><span>Character literal</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/character_constant" class="_attribution-link">https://en.cppreference.com/w/c/language/character_constant</a> + </p> +</div> diff --git a/devdocs/c/language%2Fcharset.html b/devdocs/c/language%2Fcharset.html new file mode 100644 index 00000000..38cfbf0f --- /dev/null +++ b/devdocs/c/language%2Fcharset.html @@ -0,0 +1,112 @@ + <h1 id="firstHeading" class="firstHeading">Character sets and encodings</h1> <h3 id="Basic_character_set"> Basic character set</h3> <p> The <i>basic character set</i> consists of the following 95 characters:</p> +<table class="wikitable"> <tr> <th> Code unit</th> <th>Character</th> <th>Glyph </th> +</tr> <tr> <td>U+0009</td> <td>Character tabulation</td> <td> </td> +</tr> <tr> <td>U+000B</td> <td>Line tabulation</td> <td> </td> +</tr> <tr> <td>U+000C</td> <td>Form feed (FF)</td> <td> </td> +</tr> <tr> <td>U+0020</td> <td>Space</td> <td> </td> +</tr> <tr> <td>U+0021</td> <td>Exclamation mark</td> <td> +<code>!</code> </td> +</tr> <tr> <td>U+0022</td> <td>Quotation mark</td> <td> +<code>"</code> </td> +</tr> <tr> <td>U+0023</td> <td>Number sign</td> <td> +<code>#</code> </td> +</tr> <tr> <td>U+0025</td> <td>Percent sign</td> <td> +<code>%</code> </td> +</tr> <tr> <td>U+0026</td> <td>Ampersand</td> <td> +<code>&</code> </td> +</tr> <tr> <td>U+0027</td> <td>Apostrophe</td> <td> +<code>'</code> </td> +</tr> <tr> <td>U+0028</td> <td>Left parenthesis</td> <td> +<code>(</code> </td> +</tr> <tr> <td>U+0029</td> <td>Right parenthesis</td> <td> +<code>)</code> </td> +</tr> <tr> <td>U+002A</td> <td>Asterisk</td> <td> +<code>*</code> </td> +</tr> <tr> <td>U+002B</td> <td>Plus sign</td> <td> +<code>+</code> </td> +</tr> <tr> <td>U+002C</td> <td>Comma</td> <td> +<code>,</code> </td> +</tr> <tr> <td>U+002D</td> <td>Hyphen-minus</td> <td> +<code>-</code> </td> +</tr> <tr> <td>U+002E</td> <td>Full stop</td> <td> +<code>.</code> </td> +</tr> <tr> <td>U+002F</td> <td>Solidus</td> <td> +<code>/</code> </td> +</tr> <tr> <td>U+0030 .. U+0039</td> <td>Digit zero .. nine</td> <td> +<code>0 1 2 3 4 5 6 7 8 9</code> </td> +</tr> <tr> <td>U+003A</td> <td>Colon</td> <td> +<code>:</code> </td> +</tr> <tr> <td>U+003B</td> <td>Semicolon</td> <td> +<code>;</code> </td> +</tr> <tr> <td>U+003C</td> <td>Less-than sign</td> <td> +<code><</code> </td> +</tr> <tr> <td>U+003D</td> <td>Equals sign</td> <td> +<code>=</code> </td> +</tr> <tr> <td>U+003E</td> <td>Greater-than sign</td> <td> +<code>></code> </td> +</tr> <tr> <td>U+003F</td> <td>Question mark</td> <td> +<code>?</code> </td> +</tr> <tr> <td>U+0041 .. U+005A</td> <td>Latin capital letter A .. Z</td> <td> +<code>A B C D E F G H I J K L M</code> <p><code>N O P Q R S T U V W X Y Z</code></p> +</td> +</tr> <tr> <td>U+005B</td> <td>Left square bracket</td> <td> +<code>[</code> </td> +</tr> <tr> <td>U+005C</td> <td>Reverse solidus</td> <td> +<code>\</code> </td> +</tr> <tr> <td>U+005D</td> <td>Right square bracket</td> <td> +<code>]</code> </td> +</tr> <tr> <td>U+005E</td> <td>Circumflex accent</td> <td> +<code>^</code> </td> +</tr> <tr> <td>U+005F</td> <td>Low line</td> <td> +<code>_</code> </td> +</tr> <tr> <td>U+0061 .. U+007A</td> <td>Latin small letter a .. z</td> <td> +<code>a b c d e f g h i j k l m</code> <p><code>n o p q r s t u v w x y z</code></p> +</td> +</tr> <tr> <td>U+007B</td> <td>Left curly bracket</td> <td> +<code>{</code> </td> +</tr> <tr> <td>U+007C</td> <td>Vertical line</td> <td> +<code>|</code> </td> +</tr> <tr> <td>U+007D</td> <td>Right curly bracket</td> <td> +<code>}</code> </td> +</tr> <tr> <td>U+007E</td> <td>Tilde</td> <td> +<code>~</code> </td> +</tr> +</table> <p>Unlike C++, the U+000A LINE FEED (LF) character is not included in basic character set. Instead, there shall be some way of indicating the end of each line of text in the source file and the document treats such an end-of-line indicator as if it were a single new-line character.</p> +<p>Basic character set is also known as <i>basic source character set</i>.</p> +<h3 id="Basic_execution_character_set"> Basic execution character set</h3> <p>The <i>basic execution character set</i> contains all the members of the basic character set, plus the following characters:</p> +<table class="wikitable"> <tr> <th> Code unit </th> <th> Character </th> +</tr> <tr> <td>U+0000</td> <td>Null </td> +</tr> <tr> <td>U+0007</td> <td>Bell </td> +</tr> <tr> <td>U+0008</td> <td>Backspace </td> +</tr> <tr> <td>U+000A</td> <td>Line feed (LF) </td> +</tr> <tr> <td>U+000D</td> <td>Carriage return (CR) </td> +</tr> +</table> <p>For each basic execution character set, the values of the members shall be non-negative and distinct from one another. In both the source and execution basic character sets, the value of each character after 0 in the above list of decimal digits shall be one greater than the value of the previous. The U+0000 NULL character has the value 0.</p> +<p>The representation of each member of the basic execution character sets fit in a byte.</p> +<p>In C++, basic execution character set is also known as <i>basic literal character set</i> and <i>basic execution wide-character set</i>.</p> +<h3 id="Literal_encodings"> Literal encodings</h3> <p>The <i>literal encoding</i> is an implementation-defined mapping of the characters of the execution character set to the values in a <a href="character_constant" title="c/language/character constant">character constant</a> or <a href="string_literal" title="c/language/string literal">string literal</a> without encoding prefix. It supports a mapping from all the basic execution character set values into the implementation-defined encoding. It may contain multibyte character sequences.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>The following characters are not in basic execution character set, but they are required to be encoded as a single byte in an ordinary character constant or ordinary string literal.</p> +<table class="wikitable"> <tr> <th> Code unit</th> <th>Character</th> <th>Glyph </th> +</tr> <tr> <td>U+0024</td> <td>Dollar Sign</td> <td> +<code>$</code> </td> +</tr> <tr> <td>U+0040</td> <td>Commercial At</td> <td> +<code>@</code> </td> +</tr> <tr> <td>U+0060</td> <td>Grave Accent</td> <td> +<code>`</code> </td> +</tr> +</table> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <p>The <i>wide literal encoding</i> is an implementation-defined mapping of the characters of the execution character set to the values in an <code>L</code>-prefixed character constant or string literal. It supports a mapping from all the basic execution character set values into the implementation-defined encoding. If an implementation does not define <code>__STDC_MB_MIGHT_NEQ_WC__</code>, the mapping produces values identical to the literal encoding for all the basic execution character set values. One or more values may map to one or more values of the extended execution character set.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <p>The UTF-8 encoding is used for mapping characters of the execution character set to a <code>u8</code>-prefixed <span class="t-rev-inl t-since-c23"><span>character constant or</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> string literal.</p> +<p><span class="t-rev-inl t-until-c23"><span>An implementation-defined encoding</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span>The UTF-16 encoding</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> is used for mapping characters of the execution character set to a <code>u</code>-prefixed character constant or string literal.</p> +<p><span class="t-rev-inl t-until-c23"><span>An implementation-defined encoding</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span>The UTF-32 encoding</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> is used for mapping characters of the execution character set to a <code>U</code>-prefixed character constant or string literal.</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <a href="ascii" title="c/language/ascii">ASCII chart</a> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/charset" title="cpp/language/charset">C++ documentation</a></span> for <span class=""><span>Character sets and encodings</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/charset" class="_attribution-link">https://en.cppreference.com/w/c/language/charset</a> + </p> +</div> diff --git a/devdocs/c/language%2Fcompatible_type.html b/devdocs/c/language%2Fcompatible_type.html new file mode 100644 index 00000000..06a3bead --- /dev/null +++ b/devdocs/c/language%2Fcompatible_type.html @@ -0,0 +1,233 @@ + <h1 id="firstHeading" class="firstHeading">Type</h1> <p><small>(See also <a href="arithmetic_types" title="c/language/arithmetic types">arithmetic types</a> for the details on most built-in types and <a href="../types" title="c/types">the list of type-related utilities</a> that are provided by the C library.)</small></p> +<p><a href="object" title="c/language/object">Objects</a>, <a href="functions" title="c/language/functions">functions</a>, and <a href="expressions" title="c/language/expressions">expressions</a> have a property called <i>type</i>, which determines the interpretation of the binary value stored in an object or evaluated by the expression.</p> +<h3 id="Type_classification"> Type classification</h3> <p>The C type system consists of the following types:</p> +<ul> +<li>the type <code>void</code> </li> +<li>basic types </li> +<li>the type <code>char</code> </li> +<li>signed integer types </li> +<ul><li>standard: <code>signed char</code>, <code>short</code>, <code>int</code>, <code>long</code><span class="t-rev-inl t-since-c99"><span>, <code>long long</code></span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> </li></ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <ul><li>bit-precise: <code>_BitInt(N)</code> where N is an integer constant expression that specifies the number of bits that are used to represent the type, including the sign bit. Each value of N designates a distinct type. </li></ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> <tr class="t-rev t-since-c99"> +<td> <ul><li>extended: implementation defined, e.g. <code>__int128</code> </li></ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <ul> +<li>unsigned integer types </li> +<ul><li>standard: <span class="t-rev-inl t-since-c99"><span><code>_Bool</code>,</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> <code>unsigned char</code>, <code>unsigned short</code>, <code>unsigned int</code>, <code>unsigned long</code><span class="t-rev-inl t-since-c99"><span>, <code>unsigned long long</code></span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> </li></ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <ul><li>bit-precise: <code>unsigned _BitInt(N)</code> where N is an integer constant expression that specifies the number of bits that are used to represent the type. Each value of N designates a distinct type. This category includes the type <code>unsigned _BitInt(1)</code> which does not have a corresponding bit-precise signed integer type </li></ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> <tr class="t-rev t-since-c99"> +<td> <ul><li>extended: implementation-defined, e.g. <code>__uint128</code> </li></ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <ul> +<li>floating-point types </li> +<ul><li>real floating-point types: <code>float</code>, <code>double</code>, <code>long double</code> </li></ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <ul><li>decimal real floating-point types: <code>_Decimal32</code>, <code>_Decimal64</code>, <code>_Decimal128</code> </li></ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> <tr class="t-rev t-since-c99"> +<td> <ul> +<li>complex types: <code>float _Complex</code>, <code>double _Complex</code>, <code>long double _Complex</code> </li> +<li>imaginary types: <code>float _Imaginary</code>, <code>double _Imaginary</code>, <code>long double _Imaginary</code> </li> +</ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <ul> +<li> <a href="enum" title="c/language/enum">enumerated types</a> </li> +<li> derived types </li> +<ul> +<li> <a href="array" title="c/language/array">array types</a> </li> +<li> <a href="struct" title="c/language/struct">structure types</a> </li> +<li> <a href="union" title="c/language/union">union types</a> </li> +<li> <a href="functions" title="c/language/functions">function types</a> </li> +<li> <a href="pointer" title="c/language/pointer">pointer types</a> </li> +</ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <ul><li> <a href="atomic" title="c/language/atomic">atomic types</a> </li></ul> </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <p>For every type listed above several qualified versions of its type may exist, corresponding to the combinations of one, two, or all three of the <a href="const" title="c/language/const"><code>const</code></a>, <a href="volatile" title="c/language/volatile"><code>volatile</code></a>, and <a href="restrict" title="c/language/restrict"><code>restrict</code></a> qualifiers (where allowed by the qualifier's semantics).</p> +<h4 id="Type_groups"> Type groups</h4> <ul> +<li> <i>object types</i>: all types that aren't function types </li> +<li> <i>character types</i>: <code>char</code>, <code>signed char</code>, <code>unsigned char</code> </li> +<li> <i>integer types</i>: <code>char</code>, signed integer types, unsigned integer types, enumerated types </li> +<li> <i>real types</i>: integer types and real floating types </li> +<li> <a href="arithmetic_types" title="c/language/arithmetic types">arithmetic types</a>: integer types and floating types </li> +<li> <i>scalar types</i>: arithmetic types, pointer types<span class="t-rev-inl t-since-c23"><span>, and <code><a href="../types/nullptr_t" title="c/types/nullptr t">nullptr_t</a></code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> </li> +<li> <i>aggregate types</i>: array types and structure types </li> +<li> <i>derived declarator types</i>: array types, function types, and pointer types </li> +</ul> <p>Constructing a complete object type such that the number of bytes in its object representation is not representable in the type <code><a href="../types/size_t" title="c/types/size t">size_t</a></code> (i.e. the result type of <a href="sizeof" title="c/language/sizeof"><code>sizeof</code></a> operator)<span class="t-rev-inl t-since-c99"><span>, including forming such a VLA type at runtime,</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> is undefined behavior.</p> +<h3 id="Compatible_types"> Compatible types</h3> <p>In a C program, the declarations referring to the same object or function in <i>different translation units</i> do not have to use the same type. They only have to use sufficiently similar types, formally known as <i>compatible types</i>. Same applies to function calls and lvalue accesses; argument types must be <i>compatible</i> with parameter types and lvalue expression type must be <i>compatible</i> with the object type that is accessed.</p> +<p>The types <code>T</code> and <code>U</code> are compatible, if</p> +<ul> +<li> they are the same type (same name or aliases introduced by a <a href="typedef" title="c/language/typedef"><code>typedef</code></a>) </li> +<li> they are identically cvr-qualified versions of compatible unqualified types </li> +<li> they are pointer types and are pointing to compatible types </li> +<li> they are array types, and </li> +<ul> +<li> their element types are compatible, and </li> +<li> if both have constant size, that size is the same. Note: arrays of unknown bound are compatible with any array of compatible element type. <span class="t-rev-inl t-since-c99"><span>VLA is compatible with any array of compatible element type.</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> </li> +</ul> +<li> they are both structure/union/enumeration types, and </li> +<li> +<span class="t-mark-rev t-since-c99">(C99)</span>if one is declared with a tag, the other must also be declared with the same tag. </li> +<li> if both are completed types, their members must correspond exactly in number, be declared with compatible types, and have matching names. </li> +<li> additionally, if they are enumerations, corresponding members must also have the same values. </li> +<li> additionally, if they are structures or unions, </li> +<ul> +<li> Corresponding members must be declared in the same order (structures only) </li> +<li> Corresponding <a href="bit_field" title="c/language/bit field">bit-fields</a> must have the same widths. </li> +</ul> +<li> one is an enumerated type and the other is that enumeration's underlying type </li> +<li> they are function types, and </li> +<ul> +<li> their return types are compatible </li> +<li> they both use parameter lists, the number of parameters (including the use of the ellipsis) is the same, and the corresponding parameter, after applying array-to-pointer and function-to-pointer type adjustments and after stripping top-level qualifiers, have compatible types </li> +</ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <ul> +<li> one is an old-style (parameter-less) definition, the other has a parameter list, the parameter list does not use an ellipsis and each parameter is compatible (after function parameter type adjustment) with the corresponding old-style parameter after default argument promotions </li> +<li> one is an old-style (parameter-less) declaration, the other has a parameter list, the parameter list does not use an ellipsis, and all parameters (after function parameter type adjustment) are unaffected by default argument promotions </li> +</ul> </td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> </table> <p>The type <code>char</code> is not compatible with <code>signed char</code> and not compatible with <code>unsigned char</code>.</p> +<p>If two declarations refer to the same object or function and do not use compatible types, the behavior of the program is undefined.</p> +<div class="c source-c"><pre data-language="c">// Translation Unit 1 +struct S { int a; }; +extern struct S *x; // compatible with TU2's x, but not with TU3's x + +// Translation Unit 2 +struct S; +extern struct S *x; // compatible with both x's + +// Translation Unit 3 +struct S { float a; }; +extern struct S *x; // compatible with TU2's x, but not with TU1's x + +// the behavior is undefined</pre></div> <div class="c source-c"><pre data-language="c">// Translation Unit 1 +#include <stdio.h> + +struct s { int i; }; // compatible with TU3's s, but not TU2's +extern struct s x = {0}; // compatible with TU3's x +extern void f(void); // compatible with TU2's f + +int main() +{ + f(); + return x.i; +} + +// Translation Unit 2 +struct s { float f; }; // compatible with TU4's s, but not TU1's s +extern struct s y = {3.14}; // compatible with TU4's y +void f() // compatible with TU1's f +{ + return; +} + +// Translation Unit 3 +struct s { int i; }; // compatible with TU1's s, but not TU2's s +extern struct s x; // compatible with TU1's x + +// Translation Unit 4 +struct s { float f; }; // compatible with TU2's s, but not TU1's s +extern struct s y; // compatible with TU2's y + +// the behavior is well-defined: only multiple declarations +// of objects and functions must have compatible types, not the types themselves</pre></div> <p>Note: C++ has no concept of compatible types. A C program that declares two types that are compatible but not identical in different translation units is not a valid C++ program.</p> +<h3 id="Composite_types"> Composite types</h3> <p>A composite type can be constructed from two types that are compatible; it is a type that is compatible with both of the two types and satisfies the following conditions:</p> +<ul> +<li>If both types are array types, the following rules are applied: </li> +<ul><li>If one type is an array of known constant size, the composite type is an array of that size. </li></ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <ul> +<li>Otherwise, if one type is a VLA whose size is specified by an expression that is not evaluated, a program necessitating the composite type of both types has undefined behavior. </li> +<li>Otherwise, if one type is a VLA whose size is specified, the composite type is a VLA of that size. </li> +<li>Otherwise, if one type is a VLA of unspecified size, the composite type is a VLA of unspecified size. </li> +</ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <ul><li>Otherwise, both types are arrays of unknown size and the composite type is an array of unknown size. </li></ul> The element type of the composite type is the composite type of the two element types. <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <ul><li>If only one type is a function type with a parameter type list (a function prototype), the composite type is a function prototype with the parameter type list. </li></ul> </td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> </table> <ul><li>If both types are function types with parameter type lists, the type of each parameter in the composite parameter type list is the composite type of the corresponding parameters. </li></ul> <p>These rules apply recursively to the types from which the two types are derived.</p> +<div class="c source-c"><pre data-language="c">// Given the following two file scope declarations: +int f(int (*)(), double (*)[3]); +int f(int (*)(char *), double (*)[]); // C23: Error: conflicting types for 'f' +// The resulting composite type for the function is: +int f(int (*)(char *), double (*)[3]);</pre></div> <p>For an identifier with internal or external <a href="storage_duration" title="c/language/storage duration">linkage</a> declared in a scope in which a prior declaration of that identifier is visible, if the prior declaration specifies internal or external linkage, the type of the identifier at the later declaration becomes the composite type.</p> +<h3 id="Incomplete_types"> Incomplete types</h3> <p>An incomplete type is an object type that lacks sufficient information to determine the size of the objects of that type. An incomplete type may be completed at some point in the translation unit.</p> +<p>The following types are incomplete:</p> +<ul> +<li> the type <code>void</code>. This type cannot be completed. </li> +<li> array type of unknown size. It can be completed by a later declaration that specifies the size. </li> +</ul> <div class="c source-c"><pre data-language="c">extern char a[]; // the type of a is incomplete (this typically appears in a header) +char a[10]; // the type of a is now complete (this typically appears in a source file)</pre></div> <ul><li> structure or union type of unknown content. It can be completed by a declaration of the same structure or union that defines its content later in the same scope. </li></ul> <div class="c source-c"><pre data-language="c">struct node +{ + struct node *next; // struct node is incomplete at this point +}; // struct node is complete at this point</pre></div> <h3 id="Type_names"> Type names</h3> <p>A type may have to be named in context other than the <a href="declarations" title="c/language/declarations">declaration</a>. In these situations, <i>type name</i> is used, which is, grammatically, exactly the same as a list of <i>type-specifiers</i> and <i>type-qualifiers</i>, followed by the <i>declarator</i> (see <a href="declarations" title="c/language/declarations">declarations</a>) as would be used to declare a single object or function of this type, except that the identifier is omitted:</p> +<div class="c source-c"><pre data-language="c">int n; // declaration of an int +sizeof(int); // use of type name + +int *a[3]; // declaration of an array of 3 pointers to int +sizeof(int *[3]); // use of type name + +int (*p)[3]; // declaration of a pointer to array of 3 int +sizeof(int (*)[3]); // use of type name + +int (*a)[*] // declaration of pointer to VLA (in a function parameter) +sizeof(int (*)[*]) // use of type name (in a function parameter) + +int *f(void); // declaration of function +sizeof(int *(void)); // use of type name + +int (*p)(void); // declaration of pointer to function +sizeof(int (*)(void)); // use of type name + +int (*const a[])(unsigned int, ...) = {0}; // array of pointers to functions +sizeof(int (*const [])(unsigned int, ...)); // use of type name</pre></div> <p>Except the redundant parentheses around the identifier are meaningful in a type-name and represent "function with no parameter specification":</p> +<div class="c source-c"><pre data-language="c">int (n); // declares n of type int +sizeof(int ()); // uses type "function returning int"</pre></div> <p>Type names are used in the following situations:</p> +<ul> +<li> <a href="cast" title="c/language/cast">cast</a> </li> +<li> <a href="sizeof" title="c/language/sizeof">sizeof</a> </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <ul><li> <a href="compound_literal" title="c/language/compound literal">compound literal</a> </li></ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> <tr class="t-rev t-since-c11"> +<td> <ul> +<li> <a href="generic" title="c/language/generic">generic selection</a> </li> +<li> <a href="_alignof" title="c/language/ Alignof">_Alignof</a> </li> +<li> <a href="_alignas" title="c/language/ Alignas">_Alignas</a> </li> +<li> <a href="atomic" title="c/language/atomic">_Atomic</a> (when used as a type specifier) </li> +</ul> </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <p><br> A type name may introduce a new type:</p> +<div class="c source-c"><pre data-language="c">void* p = (void*)(struct X { int i; } *)0; +// type name "struct X {int i;}*" used in the cast expression +// introduces the new type "struct X" +struct X x = {1}; // struct X is now in scope</pre></div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 6.2.5 Types (p: TBD) </li> +<li> 6.2.6 Representations of types (p: TBD) </li> +<li> 6.2.7 Compatible type and composite type (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.2.5 Types (p: 31-33) </li> +<li> 6.2.6 Representations of types (p: 31-35) </li> +<li> 6.2.7 Compatible type and composite type (p: 35-36) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.2.5 Types (p: 39-43) </li> +<li> 6.2.6 Representations of types (p: 44-46) </li> +<li> 6.2.7 Compatible type and composite type (p: 47-48) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 6.2.5 Types (p: 33-37) </li> +<li> 6.2.6 Representations of types (p: 37-40) </li> +<li> 6.2.7 Compatible type and composite type (p: 40-41) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 3.1.2.5 Types </li> +<li> 3.1.2.6 Compatible type and composite type </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/type" title="cpp/language/type">C++ documentation</a></span> for <span class=""><span>Type</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/compatible_type" class="_attribution-link">https://en.cppreference.com/w/c/language/compatible_type</a> + </p> +</div> diff --git a/devdocs/c/language%2Fcompound_literal.html b/devdocs/c/language%2Fcompound_literal.html new file mode 100644 index 00000000..6b245c1a --- /dev/null +++ b/devdocs/c/language%2Fcompound_literal.html @@ -0,0 +1,89 @@ + <h1 id="firstHeading" class="firstHeading">Compound literals <span class="t-mark-rev t-since-c99">(since C99)</span> +</h1> <p>Constructs an unnamed object of specified type (which may be struct, union, or even array type) in-place.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>(</code> <span class="t-spar">storage-class-specifiers</span> <span class="t-mark">(optional)</span><span class="t-mark-rev t-since-c23">(since C23)</span> <span class="t-spar">type</span> <code>)</code> <code>{</code> <span class="t-spar">initializer-list</span> <code>}</code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>(</code> <span class="t-spar">storage-class-specifiers</span> <span class="t-mark">(optional)</span><span class="t-mark-rev t-since-c23">(since C23)</span> <span class="t-spar">type</span> <code>)</code> <code>{</code> <span class="t-spar">initializer-list</span> <code>,</code> <code>}</code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>(</code> <span class="t-spar">storage-class-specifiers</span> <span class="t-mark">(optional)</span> <span class="t-spar">type</span> <code>)</code> <code>{</code> <code>}</code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">storage-class-specifiers</span> </td> <td> - </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> A list of <a href="storage_duration" title="c/language/storage duration">storage class specifiers</a> that can contain only <code>constexpr</code>, <code>static</code>, <code>register</code>, or <code><a href="http://en.cppreference.com/w/c/thread/thread_local"><span class="kw1032">thread_local</span></a></code> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">type</span> </td> <td> - </td> <td> a <a href="type#Type_names" title="c/language/type">type name</a> specifying any complete object type or an array of unknown size, but not a VLA </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">initializer-list</span> </td> <td> - </td> <td> list of initializers suitable for <a href="initialization" title="c/language/initialization">initialization</a> of an object of <span class="t-spar">type</span> </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>The compound literal expression constructs an unnamed object of the type specified by <span class="t-spar">type</span> and initializes it as specified by <span class="t-spar">initializer-list</span>. <a href="initialization" title="c/language/initialization">Designated initializers</a> are accepted.</p> +<p>The type of the compound literal is <span class="t-spar">type</span> (except when <span class="t-spar">type</span> is an array of unknown size; its size is deduced from the <span class="t-spar">initializer-list</span> as in <a href="array_initialization" title="c/language/array initialization">array initialization</a>).</p> +<p>The value category of a compound literal is <a href="value_category" title="c/language/value category">lvalue</a> (its address can be taken).</p> +<table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td>The unnamed object to which the compound literal evaluates has static <a href="storage_duration" title="c/language/storage duration">storage duration</a> if the compound literal occurs at file scope and automatic <a href="storage_duration" title="c/language/storage duration">storage duration</a> if the compound literal occurs at block scope (in which case the object's <a href="lifetime" title="c/language/lifetime">lifetime</a> ends at the end of the enclosing block).</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td>If the compound literal is evaluated outside the body of a function and outside of any parameter list, it is associated with file scope; otherwise, it is associated with the enclosing block. Depending on this association, the storage-class specifiers (possibly empty), type name, and initializer list, if any, shall be such that they are valid specifiers for an object definition in file scope or block scope, respectively, of the following form, <pre data-language="c"> storage-class-specifiers typeof(type) ID = { initializer-list }; +</pre> where ID is an identifier that is unique for the whole program. A compound literal provides an unnamed object whose value, type, storage duration and other properties are as if given by the definition syntax above; if the storage duration is automatic, the lifetime of the instance of the unnamed object is the current execution of the enclosing block. If the storage-class specifiers contain other specifiers than <code>constexpr</code>, <code>static</code>, <code>register</code>, or <code><a href="http://en.cppreference.com/w/c/thread/thread_local"><span class="kw1032">thread_local</span></a></code> the behavior is undefined.</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>Compound literals of const-qualified character or wide character array types may share storage with <a href="string_literal" title="c/language/string literal">string literals</a>.</p> +<div class="c source-c"><pre data-language="c">(const char []){"abc"} == "abc" // might be 1 or 0, unspecified</pre></div> <p>Each compound literal creates only a single object in its scope:</p> +<div class="c source-c"><pre data-language="c">int f (void) +{ + struct s {int i;} *p = 0, *q; + int j = 0; +again: + q = p, p = &((struct s){ j++ }); + if (j < 2) goto again; // note; if a loop were used, it would end scope here, + // which would terminate the lifetime of the compound literal + // leaving p as a dangling pointer + return p == q && q->i == 1; // always returns 1 +}</pre></div> <p>Because compound literals are unnamed, a compound literal cannot reference itself (a named struct can include a pointer to itself)</p> +<p>Although the syntax of a compound literal is similar to a <a href="cast" title="c/language/cast">cast</a>, the important distinction is that a cast is a non-lvalue expression while a compound literal is an lvalue.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +int *p = (int[]){2, 4}; // creates an unnamed static array of type int[2] + // initializes the array to the values {2, 4} + // creates pointer p to point at the first element of + // the array +const float *pc = (const float []){1e0, 1e1, 1e2}; // read-only compound literal + +struct point {double x,y;}; + +int main(void) +{ + int n = 2, *p = &n; + p = (int [2]){*p}; // creates an unnamed automatic array of type int[2] + // initializes the first element to the value formerly + // held in *p + // initializes the second element to zero + // stores the address of the first element in p + + void drawline1(struct point from, struct point to); + void drawline2(struct point *from, struct point *to); + drawline1( + (struct point){.x=1, .y=1}, // creates two structs with block scope and + (struct point){.x=3, .y=4}); // calls drawline1, passing them by value + drawline2( + &(struct point){.x=1, .y=1}, // creates two structs with block scope and + &(struct point){.x=3, .y=4}); // calls drawline2, passing their addresses +} + +void drawline1(struct point from, struct point to) +{ + printf("drawline1: `from` @ %p {%.2f, %.2f}, `to` @ %p {%.2f, %.2f}\n", + (void*)&from, from.x, from.y, (void*)&to, to.x, to.y); +} + +void drawline2(struct point *from, struct point *to) +{ + printf("drawline2: `from` @ %p {%.2f, %.2f}, `to` @ %p {%.2f, %.2f}\n", + (void*)from, from->x, from->y, (void*)to, to->x, to->y); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">drawline1: `from` @ 0x7ffd24facea0 {1.00, 1.00}, `to` @ 0x7ffd24face90 {3.00, 4.00} +drawline2: `from` @ 0x7ffd24facec0 {1.00, 1.00}, `to` @ 0x7ffd24faced0 {3.00, 4.00}</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.5.2.5 Compound literals (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.5.2.5 Compound literals (p: 61-63) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.5.2.5 Compound literals (p: 85-87) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.5.2.5 Compound literals (p: 75-77) </li></ul> +</ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/compound_literal" class="_attribution-link">https://en.cppreference.com/w/c/language/compound_literal</a> + </p> +</div> diff --git a/devdocs/c/language%2Fconformance.html b/devdocs/c/language%2Fconformance.html new file mode 100644 index 00000000..63acf442 --- /dev/null +++ b/devdocs/c/language%2Fconformance.html @@ -0,0 +1,55 @@ + <h1 id="firstHeading" class="firstHeading">Conformance</h1> <p><i>Conformance</i> has a three-fold definition:</p> +<ul> +<li> <i>strictly conforming program</i> - uses only well-defined language constructs, that is constructs with a single behavior. It excludes unspecified, undefined, or implementation-defined behavior, and does not exceed any minimum implementation limit. </li> +<li> <i>conforming program</i> - acceptable to a conforming implementation. </li> +<li> <i>conforming implementation</i> - <ul> +<li> A conforming hosted implementation shall accept any strictly conforming program. </li> +<li> A conforming freestanding implementation shall accept any strictly conforming program in which the use of the features specified in the library clause (clause 7) is confined to the contents of the freestanding standard library headers (see below). </li> +<li> A conforming implementation may have extensions (including additional library functions), provided they do not alter the behavior of any strictly conforming program. </li> +</ul> </li> +</ul> <h3 id="Explanation"> Explanation</h3> <p>The standard does not define any minimum implementation limit on translation units. A hosted environment has an operating system; a freestanding environment does not. A program running in a hosted environment may use all features described in the library clause (clause 7); a program running in a freestanding environment may use a subset of library features required by clause 4.</p> +<h4 id="Freestanding_standard_library_headers"> Freestanding standard library headers</h4> <p>All standard library features in every fully freestanding header are required to be provided by a freestanding implementation.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>Some standard library headers are conditionally freestanding.</p> +<ul><li> If the implementation predefines the macro <code>__STDC_IEC_60559_BFP__</code> or <code>__STDC_IEC_60559_DFP__</code>, then <ul> +<li> <a href="../numeric/math" title="c/numeric/math"><code><math.h></code></a> and <a href="../numeric/fenv" title="c/numeric/fenv"><code><fenv.h></code></a> are fully freestanding headers, and </li> +<li> <a href="../program" title="c/program"><code><stdlib.h></code></a> is a partially freestanding header. </li> +</ul> </li></ul> <p>In a partially freestanding header, only a part of standard library features are required to be provided by a freestanding implementation.</p> +<ul> +<li> <a href="../string/byte/strdup" title="c/string/byte/strdup"><code>strdup</code></a>, <a href="../string/byte/strndup" title="c/string/byte/strndup"><code>strndup</code></a>, <code><a href="../string/byte/strcoll" title="c/string/byte/strcoll">strcoll</a></code>, <code><a href="../string/byte/strxfrm" title="c/string/byte/strxfrm">strxfrm</a></code>, and <code><a href="../string/byte/strerror" title="c/string/byte/strerror">strerror</a></code> are not required to be provided by a freestanding implementation. </li> +<li> When <code>__STDC_IEC_60559_BFP__</code> or <code>__STDC_IEC_60559_DFP__</code> are predefined, in <a href="../program" title="c/program"><code><stdlib.h></code></a>, only numeric conversion functions (<code>ato<i>X</i></code>, <code>strto<i>X</i></code>, and <code>strfrom<i>X</i></code>) are required to be provided by a freestanding implementation. </li> +</ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <table class="t-dsc-begin"> <tr> <td colspan="2"> <h5 id="Fully_freestanding_standard_library_headers"> Fully freestanding standard library headers </h5> </td> +</tr> <tr class="t-dsc"> <td> <a href="../types/limits#Limits_of_floating_point_types" title="c/types/limits"><code><float.h></code></a> </td> <td> <a href="../types/limits#Limits_of_floating_point_types" title="c/types/limits">Limits of floating-point types</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="operator_alternative" title="c/language/operator alternative"><code><iso646.h></code></a> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> <td> <a href="operator_alternative" title="c/language/operator alternative">Alternative operator spellings</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="../types/limits" title="c/types/limits"><code><limits.h></code></a> </td> <td> <a href="../types/limits" title="c/types/limits">Ranges of integer types</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="../types" title="c/types"><code><stdalign.h></code></a> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> <td> <a href="../types" title="c/types"><code>alignas</code> and <code>alignof</code></a> convenience macros </td> +</tr> <tr class="t-dsc"> <td> <a href="../variadic" title="c/variadic"><code><stdarg.h></code></a> </td> <td> <a href="../variadic" title="c/variadic">Variable arguments</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="../types" title="c/types"><code><stdbool.h></code></a> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> <td> <a href="../types" title="c/types">Macros for boolean type</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="../types" title="c/types"><code><stddef.h></code></a> </td> <td> <a href="../types" title="c/types">Common macro definitions</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="../types/integer" title="c/types/integer"><code><stdint.h></code></a> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> <td> <a href="../types/integer" title="c/types/integer">Fixed-width integer types</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="_noreturn" title="c/language/ Noreturn"><code><stdnoreturn.h></code></a> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> <td> <a href="../types" title="c/types"><code>noreturn</code></a> convenience macro </td> +</tr> <tr class="t-dsc"> <td> <code><stdbit.h></code> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> <td> Macros to work with the byte and bit representations of types </td> +</tr> <tr> <td colspan="2"> <h5 id="Partially_freestanding_standard_library_headers"> Partially freestanding standard library headers </h5> </td> +</tr> <tr class="t-dsc"> <td> <a href="../string/byte" title="c/string/byte"><code><string.h></code></a> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> <td> <a href="../string/byte" title="c/string/byte">String handling</a> </td> +</tr> <tr> <td colspan="2"> <h5 id="Conditionally_fully_freestanding_standard_library_headers"> Conditionally fully freestanding standard library headers </h5> </td> +</tr> <tr class="t-dsc"> <td> <a href="../numeric/fenv" title="c/numeric/fenv"><code><fenv.h></code></a> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> <td> <a href="../numeric/fenv" title="c/numeric/fenv">Floating-point environment</a> </td> +</tr> <tr class="t-dsc"> <td> <a href="../numeric/math" title="c/numeric/math"><code><math.h></code></a> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> <td> <a href="../numeric/math" title="c/numeric/math">Common mathematics functions</a> </td> +</tr> <tr> <td colspan="2"> <h5 id="Conditionally_partially_freestanding_standard_library_headers"> Conditionally partially freestanding standard library headers </h5> </td> +</tr> <tr class="t-dsc"> <td> <a href="../program" title="c/program"><code><stdlib.h></code></a> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> <td> General utilities: <a href="../memory" title="c/memory">memory management</a>, <a href="../program" title="c/program">program utilities</a>, <a href="../string" title="c/string">string conversions</a>, <a href="../numeric/random" title="c/numeric/random">random numbers</a>, <a href="../algorithm" title="c/algorithm">algorithms</a> </td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 4 Conformance (p: 4) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 4 Conformance (p: 8-9) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 4 Conformance (p: 7-8) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 1.7 Compliance </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/freestanding" title="cpp/freestanding">C++ documentation</a></span> for <span class=""><span>Freestanding and hosted implementation</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/conformance" class="_attribution-link">https://en.cppreference.com/w/c/language/conformance</a> + </p> +</div> diff --git a/devdocs/c/language%2Fconst.html b/devdocs/c/language%2Fconst.html new file mode 100644 index 00000000..be91d4c7 --- /dev/null +++ b/devdocs/c/language%2Fconst.html @@ -0,0 +1,65 @@ + <h1 id="firstHeading" class="firstHeading">const type qualifier</h1> <p>Each individual type in the C <a href="type" title="c/language/type">type system</a> has several <i>qualified</i> versions of that type, corresponding to one, two, or all three of the <code>const</code>, <a href="volatile" title="c/language/volatile"><code>volatile</code></a>, and, for pointers to object types, <a href="restrict" title="c/language/restrict"><code>restrict</code></a> qualifiers. This page describes the effects of the <code>const</code> qualifier.</p> +<p>Objects <a href="declarations" title="c/language/declarations">declared</a> with const-qualified types may be placed in read-only memory by the compiler, and if the address of a const object is never taken in a program, it may not be stored at all.</p> +<p>Any attempt to modify an object whose type is const-qualified results in undefined behavior.</p> +<div class="c source-c"><pre data-language="c">const int n = 1; // object of const-qualified type +int* p = (int*)&n; +*p = 2; // undefined behavior</pre></div> <p><code>const</code> semantics apply to <a href="value_category" title="c/language/value category">lvalue</a> expressions only; whenever a const lvalue expression is used in context that does not require an lvalue, its <code>const</code> qualifier is lost (note that volatile qualifier, if present, isn't lost).</p> +<p>The lvalue expressions that designate objects of const-qualified type and the lvalue expressions that designate objects of struct or union type with at least one member of const-qualified type (including members of recursively contained aggregates or unions), are not <i>modifiable lvalues</i>. In particular, they are not assignable:</p> +<div class="c source-c"><pre data-language="c">const int n = 1; // object of const type +n = 2; // error: the type of n is const-qualified + +int x = 2; // object of unqualified type +const int* p = &x; +*p = 3; // error: the type of the lvalue *p is const-qualified + +struct {int a; const int b; } s1 = {.b=1}, s2 = {.b=2}; +s1 = s2; // error: the type of s1 is unqualified, but it has a const member</pre></div> <p>A member of a const-qualified structure or union type acquires the qualification of the type it belongs to (both when accessed using the <code>.</code> operator or the <code>-></code> operator).</p> +<div class="c source-c"><pre data-language="c">struct s { int i; const int ci; } s; +// the type of s.i is int, the type of s.ci is const int +const struct s cs; +// the types of cs.i and cs.ci are both const int</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>If an array type is declared with the const type qualifier (through the use of <a href="typedef" title="c/language/typedef">typedef</a>), the array type is not const-qualified, but its element type is.</p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td> <p>An array type and its element type are always considered to be identically const-qualified.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <div class="c source-c"><pre data-language="c">typedef int A[2][3]; +const A a = {{4, 5, 6}, {7, 8, 9}}; // array of array of const int +int* pi = a[0]; // Error: a[0] has type const int* +void *unqual_ptr = a; // OK until C23; error since C23 +// Notes: clang applies the rule in C++/C23 even in C89-C17 modes</pre></div> <p>If a function type is declared with the const type qualifier (through the use of <a href="typedef" title="c/language/typedef">typedef</a>), the behavior is undefined.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>In a function declaration, the keyword <code>const</code> may appear inside the square brackets that are used to declare an array type of a function parameter. It qualifies the pointer type to which the array type is transformed.</p> +<p>The following two declarations declare the same function:</p> +<div class="c source-c"><pre data-language="c">void f(double x[const], const double y[const]); +void f(double * const x, const double * const y);</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>const-qualified compound literals do not necessarily designate distinct objects; they may share storage with other compound literals and with string literals that happen to have the same or overlapping representation.</p> +<div class="c source-c"><pre data-language="c">const int* p1 = (const int[]){1, 2, 3}; +const int* p2 = (const int[]){2, 3, 4}; // the value of p2 may equal p1+1 +_Bool b = "foobar" + 3 == (const char[]){"bar"}; // the value of b may be 1</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <p>A pointer to a non-const type can be implicitly converted to a pointer to const-qualified version of the same or <a href="compatible_type" title="c/language/compatible type" class="mw-redirect">compatible</a> type. The reverse conversion requires a cast expression.</p> +<div class="c source-c"><pre data-language="c">int* p = 0; +const int* cp = p; // OK: adds qualifiers (int to const int) +p = cp; // Error: discards qualifiers (const int to int) +p = (int*)cp; // OK: cast</pre></div> <p>Note that pointer to pointer to <code>T</code> is not convertible to pointer to pointer to <code>const T</code>; for two types to be compatible, their qualifications must be identical.</p> +<div class="c source-c"><pre data-language="c">char *p = 0; +const char **cpp = &p; // Error: char* and const char* are not compatible types +char * const *pcp = &p; // OK, adds qualifiers (char* to char*const)</pre></div> <h3 id="Keywords"> Keywords</h3> <p><a href="https://en.cppreference.com/w/cpp/keyword/const" title="cpp/keyword/const"><code>const</code></a></p> +<h3 id="Notes"> Notes</h3> <p>C adopted the <i>const</i> qualifier from C++, but unlike in C++, expressions of const-qualified type in C are not <a href="constant_expression" title="c/language/constant expression">constant expressions</a>; they may not be used as <a href="switch" title="c/language/switch">case</a> labels or to initialize <a href="static_storage_duration" title="c/language/static storage duration">static</a> and <a href="thread_storage_duration" title="c/language/thread storage duration">thread</a> storage duration objects, <a href="enum" title="c/language/enum">enumerators</a>, or <a href="bit_field" title="c/language/bit field">bit-field</a> sizes. When they are used as <a href="array" title="c/language/array">array</a> sizes, the resulting arrays are VLAs.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.7.3 Type qualifiers (p: 87-90) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.7.3 Type qualifiers (p: 121-123) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.7.3 Type qualifiers (p: 108-110) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 6.5.3 Type qualifiers </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/cv" title="cpp/language/cv">C++ documentation</a></span> for <span class=""><span>cv (<code>const</code> and <code>volatile</code>) type qualifiers</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/const" class="_attribution-link">https://en.cppreference.com/w/c/language/const</a> + </p> +</div> diff --git a/devdocs/c/language%2Fconstant_expression.html b/devdocs/c/language%2Fconstant_expression.html new file mode 100644 index 00000000..3860cf84 --- /dev/null +++ b/devdocs/c/language%2Fconstant_expression.html @@ -0,0 +1,107 @@ + <h1 id="firstHeading" class="firstHeading">Constant expressions</h1> <p>Several varieties of expressions are known as <i>constant expressions</i></p> +<h3 id="Preprocessor_constant_expression"> Preprocessor constant expression</h3> <p>The expression following <a href="../preprocessor/conditional" title="c/preprocessor/conditional"><code>#if</code> or <code>#elif</code></a> must expand to</p> +<ul> +<li> <a href="expressions#Operators" title="c/language/expressions">operators</a> other than <a href="operator_assignment" title="c/language/operator assignment">assignment</a>, <a href="operator_incdec" title="c/language/operator incdec">increment, decrement</a>, <a href="operator_other#Function_call" title="c/language/operator other">function-call</a>, or <a href="operator_other#Comma_operator" title="c/language/operator other">comma</a> whose arguments are preprocessor constant expressions </li> +<li> <a href="integer_constant" title="c/language/integer constant">integer constants</a> </li> +<li> <a href="character_constant" title="c/language/character constant">character constants</a> </li> +<li> the special preprocessor operator <code>defined</code> </li> +</ul> <p>Character constants, when evaluated in <code>#if</code>-expressions, may be interpreted in the source character set, the execution character set, or some other implementation-defined character set.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>Integer arithmetic in <code>#if</code>-expressions is performed using the semantics of <code><a href="../types/integer" title="c/types/integer">intmax_t</a></code> for signed types and <code><a href="../types/integer" title="c/types/integer">uintmax_t</a></code> for unsigned types.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Integer_constant_expression"> Integer constant expression</h3> <p>An integer constant expression is an expression that consists only of</p> +<ul> +<li> <a href="expressions#Operators" title="c/language/expressions">operators</a> other than <a href="operator_assignment" title="c/language/operator assignment">assignment</a>, <a href="operator_incdec" title="c/language/operator incdec">increment, decrement</a>, <a href="operator_other#Function_call" title="c/language/operator other">function-call</a>, or <a href="operator_other#Comma_operator" title="c/language/operator other">comma</a>, except that <a href="cast" title="c/language/cast">cast</a> operators can only cast arithmetic types to integer types unless they are part of an operand to a sizeof, <span class="t-rev-inl t-since-c11"><span>_Alignof</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> <span class="t-rev-inl t-since-c23"><span>or typeof/typeof_unqual</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> operator. </li> +<li> <a href="integer_constant" title="c/language/integer constant">integer constants</a> </li> +<li> <a href="enum" title="c/language/enum">enumeration constants</a> </li> +<li> <a href="character_constant" title="c/language/character constant">character constants</a> </li> +<li> <a href="floating_constant" title="c/language/floating constant">floating constants</a>, but only if they are immediately used as operands of casts to integer type </li> +<li> <a href="sizeof" title="c/language/sizeof"><code>sizeof</code></a> operators <span class="t-rev-inl t-since-c99"><span>whose operands are not VLA</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <ul><li> <a href="_alignof" title="c/language/ Alignof"><code>_Alignof</code></a> operators </li></ul> </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <ul><li> named and compound literal constants that are of integer type or that are of arithmetic type and are the immediate operands of casts </li></ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <p>Integer constant expressions are evaluated at compile time. The following contexts require expressions that are known as <i>integer constant expressions</i>:</p> +<ul> +<li> The size of a <a href="bit_field" title="c/language/bit field">bit-field</a>. </li> +<li> The value of an <a href="enum" title="c/language/enum">enumeration constant</a> </li> +<li> The <code>case</code> label of a <a href="switch" title="c/language/switch">switch statement</a> </li> +<li> The size of a <span class="t-rev-inl t-since-c99"><span>non-VLA</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> array </li> +<li> Integer to pointer implicit <a href="conversion" title="c/language/conversion">conversion</a>. </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <ul><li> The index in an <a href="array_initialization" title="c/language/array initialization">array designator</a> </li></ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> <tr class="t-rev t-since-c11"> +<td> <ul> +<li> The first argument of <a href="_static_assert" title="c/language/ Static assert"><code>_Static_assert</code></a> </li> +<li> The integer argument of <a href="_alignas" title="c/language/ Alignas"><code>_Alignas</code></a> </li> +</ul> </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td> <ul><li> The number of bits N of a bit-precise integer type (<code>_BitInt(N)</code>) </li></ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Static_initializer"> Static initializer</h3> <p>Expressions that are used in the <a href="initialization" title="c/language/initialization">initializers</a> of objects with static and thread_local <a href="storage_duration" title="c/language/storage duration">storage duration</a> <span class="t-rev-inl t-since-c23"><span>or declared with the <code>constexpr</code> storage-class specifier</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> must be either string literals or expressions that may be one of the following</p> +<div class="t-li1"> +<span class="t-li">1)</span> <i>arithmetic constant expression</i>, which is an expression of any arithmetic type that consists of <ul> +<li> <a href="expressions#Operators" title="c/language/expressions">operators</a> other than <a href="operator_assignment" title="c/language/operator assignment">assignment</a>, <a href="operator_incdec" title="c/language/operator incdec">increment, decrement</a>, <a href="operator_other#Function_call" title="c/language/operator other">function-call</a>, or <a href="operator_other#Comma_operator" title="c/language/operator other">comma</a>, except that <a href="cast" title="c/language/cast">cast</a> operators must be converting arithmetic types to other arithmetic types unless they are part of an operand to a sizeof, <span class="t-rev-inl t-since-c11"><span>_Alignof</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> <span class="t-rev-inl t-since-c23"><span>or typeof/typeof_unqual</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> operator </li> +<li> <a href="integer_constant" title="c/language/integer constant">integer constants</a> </li> +<li> <a href="floating_constant" title="c/language/floating constant">floating constants</a> </li> +<li> <a href="enum" title="c/language/enum">enumeration constants</a> </li> +<li> <a href="character_constant" title="c/language/character constant">character constants</a> </li> +<li> <a href="sizeof" title="c/language/sizeof"><code>sizeof</code></a> operators <span class="t-rev-inl t-since-c99"><span>whose operands are not VLA</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <ul><li> <a href="_alignof" title="c/language/ Alignof"><code>_Alignof</code></a> operators </li></ul> </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <ul><li> named or compound literal constants of arithmetic type </li></ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> +</div> <div class="t-li1"> +<span class="t-li">2)</span> a null pointer constant (e.g. <code><a href="../types/null" title="c/types/NULL">NULL</a></code>)</div> <div class="t-li1"> +<span class="t-li">3)</span> <i>address constant expression</i>, which is <ul> +<li> a null pointer </li> +<li> <a href="value_category" title="c/language/value category">lvalue</a> designating an object of static <a href="storage_duration" title="c/language/storage duration">storage duration</a> or a function designator, converted to a pointer either </li> +<ul> +<li> by using the unary address-of operator </li> +<li> by casting an integer constant to a pointer </li> +<li> by array-to-pointer or function-to-pointer implicit <a href="conversion" title="c/language/conversion">conversion</a> +</li> +</ul> +</ul> </div> <div class="t-li1"> +<span class="t-li">4)</span> <i>address constant expression</i> of some complete object type, plus or minus an <i>integer constant expression</i> +</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <span class="t-li">5)</span> a <i>named constant</i> which is, an identifier that is <ul> +<li> an enumeration constant </li> +<li> a predefined constant (one of <code>true</code>, <code>false</code> or <code>nullptr</code>) </li> +<li> declared with storage-class specifier <code>constexpr</code> and has an object type </li> +</ul> or a postfix expression that applies the <code>.</code> member access operator to a named constant of structure or union type, even recursively. <span class="t-li">6)</span> a <i>compound literal constant</i>, which is <ul> +<li>a <a href="compound_literal" title="c/language/compound literal">compound literal</a> with storage-class specifier <code>constexpr</code> </li> +<li>a postfix expression that applies the <code>.</code> member access operator to a compound literal constant of structure or union type, even recursively.</li> +</ul> <p>A <i>structure or union constant</i> is a named constant or compound literal constant with structure or union type, respectively. If the member-access operator <code>.</code> accesses a member of a union constant, the accessed member shall be the same as the member that is initialized by the union constant’s initializer.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <div class="t-li1"> +<span class="t-li">7)</span> constant expression of one of the other forms accepted by the implementation.</div> <p>Unlike with integer constant expressions, static initializer expressions are not required to be evaluated at compile time; the compiler is at liberty to turn such initializers into executable code which is invoked prior to program startup.</p> +<div class="c source-c"><pre data-language="c">static int i = 2 || 1 / 0; // initializes i to value 1</pre></div> <p>The value of a floating-point static initializer is never less accurate than the value of the same expression executed at run time, but it may be better.</p> +<h3 id="Floating-point_constant_expressions"> Floating-point constant expressions</h3> <p>Arithmetic constant expressions of floating-point types that are not used in static initializers are always evaluated as-if during run-time and are affected by the <a href="../numeric/fenv/fe_round" title="c/numeric/fenv/FE round">current rounding</a> (if <a href="../preprocessor/impl" title="c/preprocessor/impl"><code>FENV_ACCESS</code></a> is on) and report errors as specified in <a href="../numeric/math/math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<div class="c source-c"><pre data-language="c">void f(void) +{ +#pragma STDC FENV_ACCESS ON + static float x = 0.0/0.0; // static initializer: does not raise an exception + float w[] = { 0.0/0.0 }; // raises an exception + float y = 0.0/0.0; // raises an exception + double z = 0.0/0.0; // raises an exception +}</pre></div> <h3 id="Notes"> Notes</h3> <p>If an expression evaluates to a value that is not representable by its type, it cannot be used as a constant expression.</p> +<p>Implementations may accept other forms of constant expressions. However, these constant expressions are not considered as integer constant expressions, arithmetic constant expressions, or address constant expressions, and thus cannot be used in the contexts requiring these kinds of constant expressions. For example, <code>int arr[(int)+1.0];</code> declares a VLA.</p> +<h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.6 Constant expressions (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.6 Constant expressions (p: 76-77) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.6 Constant expressions (p: 106-107) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.6 Constant expressions (p: 95-96) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.4 CONSTANT EXPRESSIONS </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/constant_expression" title="cpp/language/constant expression">C++ documentation</a></span> for <span class=""><span>Constant expressions</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/constant_expression" class="_attribution-link">https://en.cppreference.com/w/c/language/constant_expression</a> + </p> +</div> diff --git a/devdocs/c/language%2Fconstexpr.html b/devdocs/c/language%2Fconstexpr.html new file mode 100644 index 00000000..5cffe330 --- /dev/null +++ b/devdocs/c/language%2Fconstexpr.html @@ -0,0 +1,33 @@ + <h1 id="firstHeading" class="firstHeading">constexpr specifier <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <p>A scalar object declared with the <code>constexpr</code> storage-class specifier is a <a href="constant_expression" title="c/language/constant expression">constant</a>. It must be fully and explicitly initialized according to the static initialization rules. It still has linkage appropriate to its declaration and it exist at runtime to have its address taken; it simply cannot be modified at runtime in any way, i.e. the compiler can use its knowledge of the object’s fixed value in any other <a href="constant_expression" title="c/language/constant expression">constant expression</a>.</p> +<p>Additionally, the constant expression that is used for the initializer of such a constant is checked at compile time.</p> +<p>An initializer of floating-point type must be evaluated with the translation-time floating-point environment.</p> +<p>There are some restrictions on the type of an object that can be declared with <code>constexpr</code>. Namely, the following constructs are not allowed to be <code>constexpr</code>:</p> +<ul> +<li> <a href="pointer" title="c/language/pointer">Pointers</a> (except that null pointers can be <code>constexpr</code>), </li> +<li> Variably modified types, </li> +<li> <a href="atomic" title="c/language/atomic">Atomic types</a>, </li> +<li> <a href="volatile" title="c/language/volatile"><code>volatile</code></a> types, </li> +<li> <a href="restrict" title="c/language/restrict"><code>restrict</code></a> pointers. </li> +</ul> <h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/constexpr" title="c/keyword/constexpr"><code>constexpr</code></a></p> +<h3 id="Notes"> Notes</h3> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <fenv.h> +#include <stdio.h> + +int main(void) +{ + constexpr float f = 23.0f; + constexpr float g = 33.0f; + fesetround(FE_TOWARDZERO); + constexpr float h = f / g; // is not affected by fesetround() above + printf("%f\n", h); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">0.696969</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> TBD TBD (p: TBD) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/constexpr" title="cpp/language/constexpr">C++ documentation</a></span> for <span class=""><span><code>constexpr</code> type specifier</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/constexpr" class="_attribution-link">https://en.cppreference.com/w/c/language/constexpr</a> + </p> +</div> diff --git a/devdocs/c/language%2Fcontinue.html b/devdocs/c/language%2Fcontinue.html new file mode 100644 index 00000000..831fd254 --- /dev/null +++ b/devdocs/c/language%2Fcontinue.html @@ -0,0 +1,61 @@ + <h1 id="firstHeading" class="firstHeading">continue statement</h1> <p>Causes the remaining portion of the enclosing <a href="for" title="c/language/for">for</a>, <a href="while" title="c/language/while">while</a> or <a href="do" title="c/language/do"> do-while</a> loop body to be skipped.</p> +<p>Used when it is otherwise awkward to ignore the remaining portion of the loop using conditional statements.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span> <code>continue</code> <code>;</code> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">attr-spec-seq</span> </td> <td> - </td> <td> <span class="t-mark-rev t-since-c23">(C23)</span>optional list of <a href="attributes" title="c/language/attributes">attributes</a>, applied to the <code>continue</code> statement </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>The <code>continue</code> statement causes a jump, as if by <a href="goto" title="c/language/goto">goto</a>, to the end of the loop body (it may only appear within the loop body of <a href="for" title="c/language/for">for</a>, <a href="while" title="c/language/while">while</a>, and <a href="do" title="c/language/do">do-while</a> loops).</p> +<p>For <a href="while" title="c/language/while">while</a> loop, it acts as</p> +<div class="c source-c"><pre data-language="c">while (/* ... */) { + // ... + continue; // acts as goto contin; + // ... + contin:; +}</pre></div> <p>For <a href="do" title="c/language/do">do-while</a> loop, it acts as:</p> +<div class="c source-c"><pre data-language="c">do { + // ... + continue; // acts as goto contin; + // ... + contin:; +} while (/* ... */);</pre></div> <p>For <a href="for" title="c/language/for">for</a> loop, it acts as:</p> +<div class="c source-c"><pre data-language="c">for (/* ... */) { + // ... + continue; // acts as goto contin; + // ... + contin:; +}</pre></div> <h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/continue" title="c/keyword/continue"><code>continue</code></a></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +int main(void) +{ + for (int i = 0; i < 10; i++) { + if (i != 5) continue; + printf("%d ", i); // this statement is skipped each time i != 5 + } + + printf("\n"); + + for (int j = 0; j < 2; j++) { + for (int k = 0; k < 5; k++) { // only this loop is affected by continue + if (k == 3) continue; + printf("%d%d ", j, k); // this statement is skipped each time k == 3 + } + } +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">5 +00 01 02 04 10 11 12 14</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.8.6.2 The continue statement (p: 111) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.8.6.2 The continue statement (p: 153) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.8.6.2 The continue statement (p: 138) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.6.6.2 The continue statement </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/continue" title="cpp/language/continue">C++ documentation</a></span> for <span class=""><span><code>continue</code> statement</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/continue" class="_attribution-link">https://en.cppreference.com/w/c/language/continue</a> + </p> +</div> diff --git a/devdocs/c/language%2Fconversion.html b/devdocs/c/language%2Fconversion.html new file mode 100644 index 00000000..f9f44d98 --- /dev/null +++ b/devdocs/c/language%2Fconversion.html @@ -0,0 +1,304 @@ + <h1 id="firstHeading" class="firstHeading">Implicit conversions</h1> <p>When an expression is used in the context where a value of a different type is expected, <i>conversion</i> may occur:</p> +<div class="c source-c"><pre data-language="c">int n = 1L; // expression 1L has type long, int is expected +n = 2.1; // expression 2.1 has type double, int is expected +char *p = malloc(10); // expression malloc(10) has type void*, char* is expected</pre></div> <p>Conversions take place in the following situations:</p> +<h3 id="Conversion_as_if_by_assignment"> Conversion as if by assignment</h3> <ul> +<li> In the <a href="operator_assignment" title="c/language/operator assignment">assignment</a> operator, the value of the right-hand operand is converted to the unqualified type of the left-hand operand. </li> +<li> In <a href="scalar_initialization" title="c/language/scalar initialization">scalar initialization</a>, the value of the initializer expression is converted to the unqualified type of the object being initialized </li> +<li> In a <a href="operator_other" title="c/language/operator other">function-call expression</a>, to a function that has a prototype, the value of each argument expression is converted to the type of the unqualified declared types of the corresponding parameter </li> +<li> In a <a href="return" title="c/language/return">return statement</a>, the value of the operand of <code>return</code> is converted to an object having the return type of the function </li> +</ul> <p>Note that actual assignment, in addition to the conversion, also removes extra range and precision from floating-point types and prohibits overlaps; those characteristics do not apply to conversion as if by assignment.</p> +<h3 id="Default_argument_promotions"> Default argument promotions</h3> <p>In a <a href="operator_other#Function_call" title="c/language/operator other">function call expression</a> when the call is made to</p> +<div class="t-li1"> +<span class="t-li">1)</span> a <a href="function_declaration" title="c/language/function declaration">function without a prototype</a> <span class="t-mark-rev t-until-c23">(until C23)</span> +</div> <div class="t-li1"> +<span class="t-li">2)</span> a <a href="variadic" title="c/language/variadic">variadic function</a>, where the argument expression is one of the trailing arguments that are matched against the ellipsis parameter</div> <p>Each argument of integer type undergoes <i>integer promotion</i> (see below), and each argument of type <code>float</code> is implicitly converted to the type <code>double</code></p> +<div class="c source-c"><pre data-language="c">int add_nums(int count, ...); +int sum = add_nums(2, 'c', true); // add_nums is called with three ints: (2, 99, 1)</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>Note that <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code> and <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code> are not promoted to <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code> and <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code> in this context.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Usual_arithmetic_conversions"> Usual arithmetic conversions</h3> <p>The arguments of the following arithmetic operators undergo implicit conversions for the purpose of obtaining the <i>common real type</i>, which is the type in which the calculation is performed:</p> +<ul> +<li> <a href="operator_arithmetic" title="c/language/operator arithmetic">binary arithmetic</a> <span class="sy2">*</span>, <span class="sy2">/</span>, <span class="sy2">%</span>, <span class="sy2">+</span>, <span class="sy2">-</span> </li> +<li> <a href="operator_comparison" title="c/language/operator comparison">relational operators</a> <span class="sy1"><</span>, <span class="sy1">></span>, <span class="sy1"><=</span>, <span class="sy1">>=</span>, <span class="sy1">==</span>, <span class="sy3">!</span><span class="sy1">=</span> </li> +<li> <a href="operator_arithmetic" title="c/language/operator arithmetic">binary bitwise arithmetic</a> <span class="sy3">&</span>, <span class="sy3">^</span>, <span class="sy3">|</span>, </li> +<li> the <a href="operator_other" title="c/language/operator other">conditional operator</a> <span class="sy4">?:</span> </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <span class="t-li">1)</span> If one operand has decimal floating type, the other operand shall not have standard floating, <p>complex, or imaginary type.</p> +<ul> +<li>First, if the type of either operand is _Decimal128, the other operand is converted to _Decimal128. </li> +<li>Otherwise, if the type of either operand is _Decimal64, the other operand is converted to _Decimal64. </li> +<li>Otherwise, if the type of either operand is _Decimal32, the other operand is converted to _Decimal32.</li> +</ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <div class="t-li1"> +<span class="t-li">2)</span> Otherwise, if one operand is <code>long double</code><span class="t-rev-inl t-since-c99"><span>, <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, or <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code> </span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>, the other operand is implicitly converted as follows: <ul><li>integer or real floating type to <code>long double</code> </li></ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <ul> +<li>complex type to <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code> </li> +<li>imaginary type to <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code> </li> +</ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> +</div> <div class="t-li1"> +<span class="t-li">3)</span> Otherwise, if one operand is <code>double</code><span class="t-rev-inl t-since-c99"><span>, <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, or <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code> </span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>, the other operand is implicitly converted as follows: <ul><li>integer or real floating type to <code>double</code> </li></ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <ul> +<li>complex type to <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code> </li> +<li>imaginary type to <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code> </li> +</ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> +</div> <div class="t-li1"> +<span class="t-li">4)</span> Otherwise, if one operand is <code>float</code><span class="t-rev-inl t-since-c99"><span>, <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, or <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code> </span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>, the other operand is implicitly converted as follows: <ul><li>integer type to <code>float</code> (the only real type possible is float, which remains as-is) </li></ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <ul> +<li>complex type remains <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code> </li> +<li>imaginary type remains <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code> </li> +</ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> +</div> <div class="t-li1"> +<span class="t-li">5)</span> Otherwise, both operands are integers. Both operands undergo <i>integer promotions</i> (see below); then, after integer promotion, one of the following cases applies: <ul> +<li> If the types are the same, that type is the common type. </li> +<li> Else, the types are different: <ul> +<li> If the types have the same signedness (both signed or both unsigned), the operand whose type has the lesser <i>conversion rank</i><sup>1</sup> is implicitly converted<sup>2</sup> to the other type. </li> +<li> Else, the operands have different signedness: <ul> +<li> If the unsigned type has <i>conversion rank</i> greater than or equal to the rank of the signed type, then the operand with the signed type is implicitly converted to the unsigned type. </li> +<li> Else, the unsigned type has <i>conversion rank</i> less than the signed type: <ul> +<li> If the signed type can represent all values of the unsigned type, then the operand with the unsigned type is implicitly converted to the signed type. </li> +<li> Else, both operands undergo implicit conversion to the unsigned type counterpart of the signed operand's type.</li> +</ul> +</li> +</ul> +</li> +</ul> +</li> +</ul> +</div> <hr> <dl> +<dd>1. Refer to "integer promotions" below for the rules on ranking. </dd> +<dd>2. Refer to "integer conversions" under "implicit conversion semantics" below. </dd> +</dl> <div class="c source-c"><pre data-language="c">1.f + 20000001; // int is converted to float, giving 20000000.00 + // addition and then rounding to float gives 20000000.00 + +(char)'a' + 1L; // first, char 'a', which is 97, is promoted to int + // different types: int and long + // same signedness: both signed + // different rank: long is of greater rank than int + // therefore, int 97 is converted to long 97 + // the result is 97 + 1 = 98 of type signed long + +2u - 10; // different types: unsigned int and signed int + // different signedness + // same rank + // therefore, signed int 10 is converted to unsigned int 10 + // since the arithmetic operation is performed for unsigned integers + // (see "Arithmetic operators" topic), the calculation performed is (2 - 10) + // modulo (2 raised to n), where n is the number of value bits of unsigned int + // if unsigned int is 32-bit long and there is no padding bits in its object + // representation, then the result is (-8) modulo (2 raised to 32) = 4294967288 + // of type unsigned int + +5UL - 2ULL; // different types: unsigned long and unsigned long long + // same signedness + // different rank: rank of unsigned long long is greater + // therefore, unsigned long 5 is converted to unsigned long long 5 + // since the arithmetic operation is performed for unsigned integers + // (see "Arithmetic operators" topic), + // if unsigned long long is 64-bit long, then + // the result is (5 - 2) modulo (2 raised to 64) = 3 of type + // unsigned long long + +0UL - 1LL; // different types: unsigned long and signed long long + // different signedness + // different rank: rank of signed long long is greater. + // if ULONG_MAX > LLONG_MAX, then signed long long cannot represent all + // unsigned long therefore, this is the last case: both operands are converted + // to unsigned long long unsigned long 0 is converted to unsigned long long 0 + // long long 1 is converted to unsigned long long 1 since the arithmetic + // operation is performed for unsigned integers + // (see "Arithmetic operators" topic), + // if unsigned long long is 64-bit long, then + // the calculation is (0 - 1) modulo (2 raised to 64) + // thus, the result is 18446744073709551615 (ULLONG_MAX) of type + // unsigned long long</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>The result type is determined as follows:</p> +<ul> +<li> if both operands are complex, the result type is complex </li> +<li> if both operands are imaginary, the result type is imaginary </li> +<li> if both operands are real, the result type is real </li> +<li> if the two floating-point operands have different type domains (complex vs. real, complex vs imaginary, or imaginary vs. real), the result type is complex </li> +</ul> <div class="c source-c"><pre data-language="c">double complex z = 1 + 2*I; +double f = 3.0; +z + f; // z remains as-is, f is converted to double, the result is double complex</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <p>As always, the result of a floating-point operator may have greater range and precision than is indicated by its type (see <code><a href="../types/limits/flt_eval_method" title="c/types/limits/FLT EVAL METHOD">FLT_EVAL_METHOD</a></code>).</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>Note: real and imaginary operands are not implicitly converted to complex because doing so would require extra computation, while producing undesirable results in certain cases involving infinities, NaNs and signed zeros. For example, if reals were converted to complex, 2.0×(3.0+i∞) would evaluate as (2.0+i0.0)×(3.0+i∞) ⇒ (2.0×3.0–0.0×∞) + i(2.0×∞+0.0×3.0) ⇒ NaN+i∞ rather than the correct 6.0+i∞. If imaginaries were converted to complex, i2.0×(∞+i3.0) would evaluate as (0.0+i2.0) × (∞+i3.0) ⇒ (0.0×∞ – 2.0×3.0) + i(0.0×3.0 + 2.0×∞) ⇒ NaN + i∞ instead of –6.0 + i∞.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <p>Note: regardless of usual arithmetic conversions, the calculation may always be performed in a narrower type than specified by these rules under the <a href="as_if" title="c/language/as if">as-if rule</a></p> +<h3 id="Value_transformations"> Value transformations</h3> <h4 id="Lvalue_conversion"> Lvalue conversion</h4> <p>Any <a href="value_category" title="c/language/value category">lvalue expression</a> of any non-array type, when used in any context other than</p> +<ul> +<li> as the operand of the <a href="operator_member_access" title="c/language/operator member access">address-of operator</a> (if allowed) </li> +<li> as the operand of the pre/post <a href="operator_incdec" title="c/language/operator incdec">increment and decrement operators</a>. </li> +<li> as the left-hand operand of the <a href="operator_member_access" title="c/language/operator member access">member access</a> (dot) operator. </li> +<li> as the left-hand operand of the <a href="operator_assignment" title="c/language/operator assignment">assignment and compound assignment</a> operators. </li> +<li> as the operand of <a href="sizeof" title="c/language/sizeof">sizeof</a> </li> +</ul> <p>undergoes <i>lvalue conversion</i>: the type remains the same, but loses <a href="const" title="c/language/const">const</a>/<a href="volatile" title="c/language/volatile">volatile</a>/<a href="restrict" title="c/language/restrict">restrict</a>-qualifiers and <a href="atomic" title="c/language/atomic">atomic</a> properties, if any. The value remains the same, but loses its lvalue properties (the address may no longer be taken).</p> +<p>If the lvalue has incomplete type, the behavior is undefined.</p> +<p>If the lvalue designates an object of automatic storage duration whose address was never taken and if that object was uninitialized (not declared with an initializer and no assignment to it has been performed prior to use), the behavior is undefined.</p> +<p>This conversion models the memory load of the value of the object from its location.</p> +<div class="c source-c"><pre data-language="c">volatile int n = 1; +int x = n; // lvalue conversion on n reads the value of n +volatile int* p = &n; // no lvalue conversion: does not read the value of n</pre></div> <h4 id="Array_to_pointer_conversion"> Array to pointer conversion</h4> <p>Any <a href="value_category" title="c/language/value category">lvalue expression</a> of <a href="array" title="c/language/array">array type</a>, when used in any context other than</p> +<ul> +<li> as the operand of the <a href="operator_member_access" title="c/language/operator member access">address-of operator</a> </li> +<li> as the operand of <a href="sizeof" title="c/language/sizeof">sizeof</a> </li> +<li> as the operand of <a href="typeof" title="c/language/typeof">typeof</a> and <a href="https://en.cppreference.com/mwiki/index.php?title=c/language/typeof_unqual&action=edit&redlink=1" class="new" title="c/language/typeof unqual (page does not exist)">typeof_unqual</a> <span class="t-mark-rev t-since-c23">(since C23)</span> </li> +<li> as the string literal used for <a href="array_initialization" title="c/language/array initialization">array initialization</a> </li> +</ul> <p>undergoes a conversion to the non-lvalue pointer to its first element.</p> +<p>If the array was declared <a href="storage_duration" title="c/language/storage duration">register</a>, the behavior is undefined.</p> +<div class="c source-c"><pre data-language="c">int a[3], b[3][4]; +int* p = a; // conversion to &a[0] +int (*q)[4] = b; // conversion to &b[0]</pre></div> <h4 id="Function_to_pointer_conversion"> Function to pointer conversion</h4> <p>Any function designator expression, when used in any context other than</p> +<ul> +<li> as the operand of the <a href="operator_member_access" title="c/language/operator member access">address-of operator</a> </li> +<li> as the operand of <a href="sizeof" title="c/language/sizeof">sizeof</a> </li> +<li> as the operand of <a href="typeof" title="c/language/typeof">typeof</a> and <a href="https://en.cppreference.com/mwiki/index.php?title=c/language/typeof_unqual&action=edit&redlink=1" class="new" title="c/language/typeof unqual (page does not exist)">typeof_unqual</a> <span class="t-mark-rev t-since-c23">(since C23)</span> </li> +</ul> <p>undergoes a conversion to the non-lvalue pointer to the function designated by the expression.</p> +<div class="c source-c"><pre data-language="c">int f(int); +int (*p)(int) = f; // conversion to &f +(***p)(1); // repeated dereference to f and conversion back to &f</pre></div> <h3 id="Implicit_conversion_semantics"> Implicit conversion semantics</h3> <p>Implicit conversion, whether <i>as if by assignment</i> or a <i>usual arithmetic conversion</i>, consists of two stages:</p> +<div class="t-li1"> +<span class="t-li">1)</span> value transformation (if applicable)</div> <div class="t-li1"> +<span class="t-li">2)</span> one of the conversions listed below (if it can produce the target type)</div> <h4 id="Compatible_types"> Compatible types</h4> <p>Conversion of a value of any type to any <a href="types#Compatible_types" title="c/language/types" class="mw-redirect">compatible type</a> is always a no-op and does not change the representation.</p> +<div class="c source-c"><pre data-language="c">uint8_t (*a)[10]; // if uint8_t is a typedef to unsigned char +unsigned char (*b)[] = a; // then these pointer types are compatible</pre></div> <h4 id="Integer_promotions"> Integer promotions</h4> <p>Integer promotion is the implicit conversion of a value of any integer type with <i>rank</i> less or equal to <i>rank</i> of int or of a <a href="bit_field" title="c/language/bit field">bit-field</a> of type <span class="t-rev-inl t-until-c23"><span><code>_Bool</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>bool</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, <code>int</code>, <code>signed int</code>, <code>unsigned int</code>, to the value of type <code>int</code> or <code>unsigned int</code>.</p> +<p>If <code>int</code> can represent the entire range of values of the original type (or the range of values of the original bit-field), the value is converted to type <code>int</code>. Otherwise the value is converted to <code>unsigned int</code>.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>The value from a bit-field of a bit-precise integer type is converted to the corresponding bit-precise integer type. Otherwise, bit-precise integer types are exempt from the integer promotion rules.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <p>Integer promotions preserve the value, including the sign:</p> +<div class="c source-c"><pre data-language="c">int main(void) +{ + void f(); // old-style function declaration + // since C23, void f(...) has the same behavior wrt promotions + char x = 'a'; // integer conversion from int to char + f(x); // integer promotion from char back to int +} + +void f(x) int x; {} // the function expects int</pre></div> <p><i>rank</i> above is a property of every <a href="type" title="c/language/type">integer type</a> and is defined as follows:</p> +<div class="t-li1"> +<span class="t-li">1)</span> the ranks of all signed integer types are different and increase with their precision: rank of <code>signed char</code> < rank of <code>short</code> < rank of <code>int</code> < rank of <code>long int</code> < rank of <code>long long int</code> +</div> <div class="t-li1"> +<span class="t-li">2)</span> the ranks of all signed integer types equal the ranks of the corresponding unsigned integer types</div> <div class="t-li1"> +<span class="t-li">3)</span> the rank of any standard integer type is greater than the rank of any extended integer type <span class="t-rev-inl t-since-c23"><span>or bit-precise integer type</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> of the same size (that is, rank of <code>__int64</code> < rank of <code>long long int</code>, but rank of <code>long long</code> < rank of <code>__int128</code> due to the rule <span class="t-v">(1)</span>)</div> <div class="t-li1"> +<span class="t-li">4)</span> rank of <code>char</code> equals rank of <code>signed char</code> and rank of <code>unsigned char</code> +</div> <div class="t-li1"> +<span class="t-li">5)</span> the rank of <span class="t-rev-inl t-until-c23"><span><code>_Bool</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>bool</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> is less than the rank of any other standard integer type</div> <div class="t-li1"> +<span class="t-li">6)</span> the rank of any enumerated type equals the rank of its compatible integer type</div> <div class="t-li1"> +<span class="t-li">7)</span> ranking is transitive: if rank of T1 < rank of T2 and rank of T2 < rank of T3 then rank of T1 < rank of T3</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <span class="t-li">8)</span> the rank of a bit-precise signed integer type shall be greater than the rank of any standard integer type with less width or any bit-precise integer type with less width. <span class="t-li">9)</span> the rank of any bit-precise integer type relative to an extended integer type of the same width is implementation-defined. </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <div class="t-li1"> +<span class="t-li">10)</span> any aspects of relative ranking of extended integer types not covered above are implementation defined.</div> <p>Note: integer promotions are applied only</p> +<ul> +<li> as part of <i>usual arithmetic conversions</i> (see above) </li> +<li> as part of <i>default argument promotions</i> (see above) </li> +<li> to the operand of the unary arithmetic operators <code>+</code> and <code>-</code> </li> +<li> to the operand of the unary bitwise operator <code>~</code> </li> +<li> to both operands of the shift operators <code><<</code> and <code>>></code> </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <h4 id="Boolean_conversion"> Boolean conversion</h4> <p>A value of any scalar type can be implicitly converted to <span class="t-rev-inl t-until-c23"><span><code>_Bool</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>bool</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>. The values that <span class="t-rev-inl t-until-c23"><span>compare equal to an integer constant expression of value zero</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span>are a zero (for arithmetic types), null (for pointer types) or have a type of <code><a href="../types/nullptr_t" title="c/types/nullptr t">nullptr_t</a></code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> are converted to <span class="t-rev-inl t-until-c23"><span><code>0</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>false</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, all other values are converted to <span class="t-rev-inl t-until-c23"><span><code>1</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>true</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>.</p> +<div class="c source-c"><pre data-language="c">bool b1 = 0.5; // b1 == 1 (0.5 converted to int would be zero) +bool b2 = 2.0*_Imaginary_I; // b2 == 1 (but converted to int would be zero) +bool b3 = 0.0 + 3.0*I; // b3 == 1 (but converted to int would be zero) +bool b4 = 0.0/0.0; // b4 == 1 (NaN does not compare equal to zero) +bool b5 = nullptr; // b5 == 0 (since C23: nullptr is converted to false)</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h4 id="Integer_conversions"> Integer conversions</h4> <p>A value of any integer type can be implicitly converted to any other integer type. Except where covered by promotions and boolean conversions above, the rules are:</p> +<ul> +<li> if the target type can represent the value, the value is unchanged </li> +<li> otherwise, if the target type is unsigned, the value 2<sup class="t-su">b</sup>, where b is the number of value bits in the target type, is repeatedly subtracted or added to the source value until the result fits in the target type. In other words, unsigned integers implement modulo arithmetic. </li> +<li> otherwise, if the target type is signed, the behavior is implementation-defined (which may include raising a signal) </li> +</ul> <div class="c source-c"><pre data-language="c">char x = 'a'; // int -> char, result unchanged +unsigned char n = -123456; // target is unsigned, result is 192 (that is, -123456+483*256) +signed char m = 123456; // target is signed, result is implementation-defined +assert(sizeof(int) > -1); // assert fails: + // operator > requests conversion of -1 to size_t, + // target is unsigned, result is SIZE_MAX</pre></div> <h4 id="Real_floating-integer_conversions"> Real floating-integer conversions</h4> <p>A finite value of any real floating type can be implicitly converted to any integer type. Except where covered by boolean conversion above, the rules are:</p> +<ul> +<li> The fractional part is discarded (truncated towards zero). </li> +<ul> +<li> If the resulting value can be represented by the target type, that value is used </li> +<li> otherwise, the behavior is undefined </li> +</ul> +</ul> <div class="c source-c"><pre data-language="c">int n = 3.14; // n == 3 +int x = 1e10; // undefined behavior for 32-bit int</pre></div> <p>A value of any integer type can be implicitly converted to any real floating type.</p> +<ul> +<li> if the value can be represented exactly by the target type, it is unchanged </li> +<li> if the value can be represented, but cannot be represented exactly, the result is an implementation-defined choice of either the nearest higher or nearest lower value, although if IEEE arithmetic is supported, rounding is to nearest. It is unspecified whether <code><a href="../numeric/fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> is raised in this case. </li> +<li> if the value cannot be represented, the behavior is undefined, although if IEEE arithmetic is supported, <code><a href="../numeric/fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised and the result value is unspecified. </li> +</ul> <p>The result of this conversion may have greater range and precision than its target type indicates (see <code><a href="../types/limits/flt_eval_method" title="c/types/limits/FLT EVAL METHOD">FLT_EVAL_METHOD</a></code>).</p> +<p>If control over <code><a href="../numeric/fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> is needed in floating-to-integer conversions, <code><a href="../numeric/math/rint" title="c/numeric/math/rint">rint</a></code> and <code><a href="../numeric/math/nearbyint" title="c/numeric/math/nearbyint">nearbyint</a></code> may be used.</p> +<div class="c source-c"><pre data-language="c">double d = 10; // d = 10.00 +float f = 20000001; // f = 20000000.00 (FE_INEXACT) +float x = 1+(long long)FLT_MAX; // undefined behavior</pre></div> <h4 id="Real_floating_point_conversions"> Real floating point conversions</h4> <p>A value of any real floating type can be implicitly converted to any other real floating type.</p> +<ul> +<li> If the value can be represented by the target type exactly, it is unchanged </li> +<li> if the value can be represented, but cannot be represented exactly, the result is the nearest higher or the nearest lower value (in other words, rounding direction is implementation-defined), although if IEEE arithmetic is supported, rounding is to nearest </li> +<li> if the value cannot be represented, the behavior is undefined </li> +</ul> <p>The result of this conversion may have greater range and precision than its target type indicates (see <code><a href="../types/limits/flt_eval_method" title="c/types/limits/FLT EVAL METHOD">FLT_EVAL_METHOD</a></code>).</p> +<div class="c source-c"><pre data-language="c">double d = 0.1; // d = 0.1000000000000000055511151231257827021181583404541015625 +float f = d; // f = 0.100000001490116119384765625 +float x = 2*(double)FLT_MAX; // undefined</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <h4 id="Complex_type_conversions"> Complex type conversions</h4> <p>A value of any complex type can be implicitly converted to any other complex type. The real part and the imaginary part individually follow the conversion rules for the real floating types.</p> +<div class="c source-c"><pre data-language="c">double complex d = 0.1 + 0.1*I; +float complex f = d; // f is (0.100000001490116119384765625, 0.100000001490116119384765625)</pre></div> <h4 id="Imaginary_type_conversions"> Imaginary type conversions</h4> <p>A value of any imaginary type can be implicitly converted to any other imaginary type. The imaginary part follows the conversion rules for the real floating types.</p> +<div class="c source-c"><pre data-language="c">double imaginary d = 0.1*_Imaginary_I; +float imaginary f = d; // f is 0.100000001490116119384765625*I</pre></div> <h4 id="Real-complex_conversions"> Real-complex conversions</h4> <p>A value of any real floating type can be implicitly converted to any complex type.</p> +<ul> +<li> The real part of the result is determined by the conversion rules for the real floating types </li> +<li> The imaginary part of the result is positive zero (or unsigned zero on non-IEEE systems) </li> +</ul> <p>A value of any complex type can be implicitly converted to any real floating type</p> +<ul> +<li> The real part is converted following the rules for the real floating types </li> +<li> The imaginary part is discarded </li> +</ul> <p>Note: in complex-to-real conversion, a NaN in the imaginary part will not propagate to the real result.</p> +<div class="c source-c"><pre data-language="c">double complex z = 0.5 + 3*I; +float f = z; // the imaginary part is discarded, f is set to 0.5 +z = f; // sets z to 0.5 + 0*I</pre></div> <h4 id="Real-imaginary_conversions"> Real-imaginary conversions</h4> <p>A value of any imaginary type can be implicitly converted to any real type (integer or floating-point). The result is always a positive (or unsigned) zero, except when the target type is <span class="t-rev-inl t-until-c23"><span><code>_Bool</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>bool</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, in which case boolean conversion rules apply.</p> +<p>A value of any real type can be implicitly converted to any imaginary type. The result is always a positive imaginary zero.</p> +<div class="c source-c"><pre data-language="c">double imaginary z = 3*I; +bool b = z; // Boolean conversion: sets b to true +float f = z; // Real-imaginary conversion: sets f to 0.0 +z = 3.14; // Imaginary-real conversion: sets z to 0*_Imaginary_I</pre></div> <h4 id="Complex-imaginary_conversions"> Complex-imaginary conversions</h4> <p>A value of any imaginary type can be implicitly converted to any complex type.</p> +<ul> +<li> The real part of the result is the positive zero </li> +<li> The imaginary part of the result follows the conversion rules for the corresponding real types </li> +</ul> <p>A value of any complex type can be implicitly converted to any imaginary type</p> +<ul> +<li> The real part is discarded </li> +<li> The imaginary part of the result follows the conversion rules for the corresponding real types </li> +</ul> <div class="c source-c"><pre data-language="c">double imaginary z = I * (3*I); // the complex result -3.0+0i loses real part + // sets z to 0*_Imaginary_I</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h4 id="Pointer_conversions"> Pointer conversions</h4> <p>A pointer to <code>void</code> can be implicitly converted to and from any pointer to object type with the following semantics:</p> +<ul> +<li> If a pointer to object is converted to a pointer to void and back, its value compares equal to the original pointer. </li> +<li> No other guarantees are offered </li> +</ul> <div class="c source-c"><pre data-language="c">int* p = malloc(10 * sizeof(int)); // malloc returns void*</pre></div> <p>A pointer to an unqualified type may be implicitly converted to the pointer to qualified version of that type (in other words, <a href="const" title="c/language/const">const</a>, <a href="volatile" title="c/language/volatile">volatile</a>, and <a href="restrict" title="c/language/restrict">restrict</a> qualifiers can be added). The original pointer and the result compare equal.</p> +<div class="c source-c"><pre data-language="c">int n; +const int* p = &n; // &n has type int*</pre></div> <p>Any integer <a href="constant_expression" title="c/language/constant expression">constant expression</a> with value <code>0</code> as well as integer pointer expression with value zero cast to the type <code>void*</code> can be implicitly converted to any pointer type (both pointer to object and pointer to function). The result is the null pointer value of its type, guaranteed to compare unequal to any non-null pointer value of that type. This integer or void* expression is known as <i>null pointer constant</i> and the standard library provides one definition of this constant as the macro <code><a href="../types/null" title="c/types/NULL">NULL</a></code>.</p> +<div class="c source-c"><pre data-language="c">int* p = 0; +double* q = NULL;</pre></div> <h3 id="Notes"> Notes</h3> <p>Although signed integer overflow in any arithmetic operator is undefined behavior, overflowing a signed integer type in an integer conversion is merely unspecified behavior.</p> +<p>On the other hand, although unsigned integer overflow in any arithmetic operator (and in integer conversion) is a well-defined operation and follows the rules of modulo arithmetic, overflowing an unsigned integer in a floating-to-integer conversion is undefined behavior: the values of real floating type that can be converted to unsigned integer are the values from the open interval (-1; Unnn_MAX+1).</p> +<div class="c source-c"><pre data-language="c">unsigned int n = -1.0; // undefined behavior</pre></div> <p>Conversions between pointers and integers (except <span class="t-rev-inl t-since-c99"><span>from pointer to <span class="t-rev-inl t-until-c23"><span><code>_Bool</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>bool</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> and </span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>from integer constant expression with the value zero to pointer), between pointers to objects (except where either to or from is a pointer to void) and conversions between pointers to functions (except when the functions have compatible types) are never implicit and require a <a href="cast" title="c/language/cast">cast operator</a>.</p> +<p>There are no conversions (implicit or explicit) between pointers to functions and pointers to objects (including void*) or integers.</p> +<h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.3 Conversions (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.3 Conversions (p: 37-41) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.3 Conversions (p: 50-56) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.3 Conversions (p: 42-48) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.2 Conversions </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/implicit_cast" title="cpp/language/implicit cast" class="mw-redirect">C++ documentation</a></span> for <span class=""><span>Implicit conversions</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/conversion" class="_attribution-link">https://en.cppreference.com/w/c/language/conversion</a> + </p> +</div> diff --git a/devdocs/c/language%2Fdeclarations.html b/devdocs/c/language%2Fdeclarations.html new file mode 100644 index 00000000..f08779ae --- /dev/null +++ b/devdocs/c/language%2Fdeclarations.html @@ -0,0 +1,142 @@ + <h1 id="firstHeading" class="firstHeading">Declarations</h1> <p>A <i>declaration</i> is a C language construct that introduces one or more <a href="identifier" title="c/language/identifier">identifiers</a> into the program and specifies their meaning and properties.</p> +<p>Declarations may appear in any scope. Each declaration ends with a semicolon (just like <a href="statements" title="c/language/statements">a statement</a>) and consists of <span class="t-rev-inl t-until-c23"><span>two</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span>three</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> distinct parts:</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="t-spar">specifiers-and-qualifiers</span> <span class="t-spar">declarators-and-initializers</span><span class="t-mark">(optional)</span> <code>;</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span> <span class="t-spar">specifiers-and-qualifiers</span> <span class="t-spar">declarators-and-initializers</span> <code>;</code> </td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span> <code>;</code> </td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">specifiers-and-qualifiers</span> </td> <td> - </td> <td> whitespace-separated list of, in any order, <ul> +<li> type specifiers: </li> +<ul> +<li> <code>void</code> </li> +<li> the name of an <a href="arithmetic_types" title="c/language/arithmetic types">arithmetic type</a> </li> +<li> the name of an <a href="atomic" title="c/language/atomic">atomic type</a> </li> +<li> a name earlier introduced by a <a href="typedef" title="c/language/typedef">typedef</a> declaration </li> +<li> <a href="struct" title="c/language/struct"><code>struct</code></a>, <a href="union" title="c/language/union"><code>union</code></a>, or <a href="enum" title="c/language/enum"><code>enum</code></a> specifier </li> +<li> a <a href="typeof" title="c/language/typeof">typeof</a> specifier <span class="t-mark-rev t-since-c23">(since C23)</span> </li> +</ul> +<li> zero or one storage-class specifiers: <a href="typedef" title="c/language/typedef"><code>typedef</code></a>, <a href="constexpr" title="c/language/constexpr"><code>constexpr</code></a>, <a href="auto" title="c/language/auto"><code>auto</code></a>, <a href="storage_duration" title="c/language/storage duration"><code>register</code>, <code>static</code>, <code>extern</code>, <code>_Thread_local</code></a> </li> +<li> zero or more type qualifiers: <a href="const" title="c/language/const"><code>const</code></a>, <a href="volatile" title="c/language/volatile"><code>volatile</code></a>, <a href="restrict" title="c/language/restrict"><code>restrict</code></a>, <a href="atomic" title="c/language/atomic"><code>_Atomic</code></a> </li> +<li> (only when declaring functions), zero or more function specifiers: <a href="inline" title="c/language/inline"><code>inline</code></a>, <a href="_noreturn" title="c/language/ Noreturn"><code>_Noreturn</code></a> </li> +<li> zero or more alignment specifiers: <a href="_alignas" title="c/language/ Alignas"><code>_Alignas</code></a> </li> +</ul> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">declarators-and-initializers</span> </td> <td> - </td> <td> comma-separated list of <span class="t-spar">declarators</span> (each declarator provides additional type information and/or the identifier to declare). Declarators may be accompanied by <a href="initialization" title="c/language/initialization">initializers</a>. The <a href="enum" title="c/language/enum">enum</a>, <a href="struct" title="c/language/struct">struct</a>, and <a href="union" title="c/language/union">union</a> declarations may omit <span class="t-spar">declarators</span>, in which case they only introduce the enumeration constants and/or tags. </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">attr-spec-seq</span> </td> <td> - </td> <td> <span class="t-mark-rev t-since-c23">(C23)</span>optional list of <a href="attributes" title="c/language/attributes">attributes</a>, applied to the declared entities, or forms an attribute declaration if appears alone. </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1-2)</span> Simple declaration. Introduces one or more identifiers which denotes objects, functions, struct/union/enum tags, typedefs, or enumeration constants.</div> <div class="t-li1"> +<span class="t-li">3)</span> Attribute declaration. Does not declares any identifier, and has implementation-defined meaning if the meaning is not specified by the standard.</div> <p>For example,</p> +<div class="c source-c"><pre data-language="c">int a, *b=NULL; // "int" is the type specifier, + // "a" is a declarator + // "*b" is a declarator and NULL is its initializer +const int *f(void); // "int" is the type specifier + // "const" is the type qualifier + // "*f(void)" is the declarator +enum COLOR {RED, GREEN, BLUE} c; // "enum COLOR {RED, GREEN, BLUE}" is the type specifier + // "c" is the declarator</pre></div> <p>The type of each identifier introduced in a declaration is determined by a combination of the type specified by the <span class="t-spar">type specifier</span> and the type modifications applied by its <span class="t-spar">declarator</span>. <span class="t-rev-inl t-since-c23"><span>The type of a variable might also be inferred if <code>auto</code> specifier is used.</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span></p> +<p><a href="attributes" title="c/language/attributes">Attributes</a><span class="t-mark-rev t-since-c23">(since C23)</span> may appear in <span class="t-spar">specifiers-and-qualifiers</span>, in which case they apply to the type determined by the preceding specifiers.</p> +<h3 id="Declarators"> Declarators</h3> <p>Each declarator is one of the following:</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="t-spar">identifier</span> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>(</code> <span class="t-spar">declarator</span> <code>)</code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>*</code> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span> <span class="t-spar">qualifiers</span><span class="t-mark">(optional)</span> <span class="t-spar">declarator</span> </td> <td> (3) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">noptr-declarator</span> <code>[</code> <code>static</code><span class="t-mark">(optional)</span> <span class="t-spar">qualifiers</span><span class="t-mark">(optional)</span> <span class="t-spar">expression</span> <code>]</code> <p><span class="t-spar">noptr-declarator</span> <code>[</code> <span class="t-spar">qualifiers</span><span class="t-mark">(optional)</span> <code>*</code> <code>]</code></p> +</td> <td> (4) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">noptr-declarator</span> <code>(</code> <span class="t-spar">parameters-or-identifiers</span> <code>)</code> </td> <td> (5) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> the identifier that this declarator introduces.</div> <div class="t-li1"> +<span class="t-li">2)</span> any declarator may be enclosed in parentheses; this is required to introduce pointers to arrays and pointers to functions.</div> <div class="t-li1"> +<span class="t-li">3)</span> <a href="pointer" title="c/language/pointer">pointer declarator</a>: the declaration <code>S * cvr D</code>; declares <code>D</code> as a <span class="t-spar">cvr</span>-qualified pointer to the type determined by <code>S</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> <a href="array" title="c/language/array">array declarator</a>: the declaration <code>S D[N]</code> declares <code>D</code> as an array of <code>N</code> objects of the type determined by <code>S</code>. <span class="t-spar">noptr-declarator</span> is any other declarator except unparenthesized pointer declarator.</div> <div class="t-li1"> +<span class="t-li">5)</span> <a href="function_declaration" title="c/language/function declaration">function declarator</a>: the declaration <code>S D(params)</code> declared <code>D</code> as a function taking the parameters <code>params</code> and returning <code>S</code>. <span class="t-spar">noptr-declarator</span> is any other declarator except unparenthesized pointer declarator.</div> <p>The reasoning behind this syntax is that when the identifier declared by the declarator appears in an expression of the same form as the declarator, it would have the type specified by the type specifier sequence.</p> +<div class="c source-c"><pre data-language="c">struct C { + int member; // "int" is the type specifier + // "member" is the declarator +} obj, *pObj = &obj; +// "struct C { int member; }" is the type specifier +// declarator "obj" defines an object of type struct C +// declarator "*pObj" declares a pointer to C, +// initializer "= &obj" provides the initial value for that pointer + +int a = 1, *p = NULL, f(void), (*pf)(double); +// the type specifier is "int" +// declarator "a" defines an object of type int +// initializer "=1" provides its initial value +// declarator "*p" defines an object of type pointer to int +// initializer "=NULL" provides its initial value +// declarator "f(void)" declares a function taking void and returning int +// declarator "(*pf)(double)" defines an object of type pointer +// to function taking double and returning int + +int (*(*foo)(double))[3] = NULL; +// the type specifier is int +// 1. declarator "(*(*foo)(double))[3]" is an array declarator: +// the type declared is "/nested declarator/ array of 3 int" +// 2. the nested declarator is "*(*foo)(double))", which is a pointer declarator +// the type declared is "/nested declarator/ pointer to array of 3 int" +// 3. the nested declarator is "(*foo)(double)", which is a function declarator +// the type declared is "/nested declarator/ function taking double and returning +// pointer to array of 3 int" +// 4. the nested declarator is "(*foo)" which is a (parenthesized, as required by +// function declarator syntax) pointer declarator. +// the type declared is "/nested declarator/ pointer to function taking double +// and returning pointer to array of 3 int" +// 5. the nested declarator is "foo", which is an identifier. +// The declaration introduces the identifier "foo" to refer to an object of type +// "pointer to function taking double and returning pointer to array of 3 int" +// The initializer "= NULL" provides the initial value of this pointer. + +// If "foo" is used in an expression of the form of the declarator, its type would be +// int. +int x = (*(*foo)(1.2))[0];</pre></div> <p>The end of every declarator that is not part of another declarator is a <a href="eval_order" title="c/language/eval order">sequence point</a>.</p> +<p>In all cases, <span class="t-spar">attr-spec-seq</span> is an optional sequence of <a href="attributes" title="c/language/attributes">attributes</a><span class="t-mark-rev t-since-c23">(since C23)</span>. When appearing immediately after the identifier, it applies to the object or function being declared.</p> +<h3 id="Definitions"> Definitions</h3> <p>A <i>definition</i> is a declaration that provides all information about the identifiers it declares.</p> +<p>Every declaration of an <a href="enum" title="c/language/enum">enum</a> or a <a href="typedef" title="c/language/typedef">typedef</a> is a definition.</p> +<p>For functions, a declaration that includes the function body is a <a href="function_definition" title="c/language/function definition">function definition</a>:</p> +<div class="c source-c"><pre data-language="c">int foo(double); // declaration +int foo(double x){ return x; } // definition</pre></div> <p>For objects, a declaration that allocates storage (<a href="storage_duration" title="c/language/storage duration">automatic or static</a>, but not extern) is a definition, while a declaration that does not allocate storage (<a href="extern" title="c/language/extern">external declaration</a>) is not.</p> +<div class="c source-c"><pre data-language="c">extern int n; // declaration +int n = 10; // definition</pre></div> <p>For <a href="struct" title="c/language/struct">structs</a> and <a href="union" title="c/language/union">unions</a>, declarations that specify the list of members are definitions:</p> +<div class="c source-c"><pre data-language="c">struct X; // declaration +struct X { int n; }; // definition</pre></div> <h3 id="Redeclaration"> Redeclaration</h3> <p>A declaration cannot introduce an identifier if another declaration for the same identifier in the same <a href="scope" title="c/language/scope">scope</a> appears earlier, except that</p> +<ul><li> Declarations of objects <a href="storage_duration" title="c/language/storage duration">with linkage</a> (external or internal) can be repeated: </li></ul> <div class="c source-c"><pre data-language="c">extern int x; +int x = 10; // OK +extern int x; // OK + +static int n; +static int n = 10; // OK +static int n; // OK</pre></div> <ul><li> Non-VLA <a href="typedef" title="c/language/typedef">typedef</a> can be repeated as long as it names the same type: </li></ul> <div class="c source-c"><pre data-language="c">typedef int int_t; +typedef int int_t; // OK</pre></div> <ul><li> <a href="struct" title="c/language/struct">struct</a> and <a href="union" title="c/language/union">union</a> declarations can be repeated: </li></ul> <div class="c source-c"><pre data-language="c">struct X; +struct X { int n; }; +struct X;</pre></div> <p>These rules simplify the use of header files.</p> +<h3 id="Notes"> Notes</h3> <table class="t-rev-begin"> <tr class="t-rev t-until-c99"> +<td> <p>In C89, declarations within any <a href="statements#Compound_statements" title="c/language/statements">compound statement</a> (block scope) must appear in the beginning of the block, before any <a href="statements" title="c/language/statements">statements</a>.</p> +<p>Also, in C89, functions returning <code>int</code> may be implicitly declared by the <a href="operator_other#Function_call" title="c/language/operator other">function call operator</a> and function parameters of type <code>int</code> do not have to be declared when using old-style <a href="function_definition" title="c/language/function definition">function definitions</a>.</p> +</td> <td><span class="t-mark-rev t-until-c99">(until C99)</span></td> +</tr> </table> <p>Empty declarators are prohibited; a simple declaration must have at least one declarator or declare at least one struct/union/enum tag, or introduce at least one enumeration constant.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>If any part of a declarator is a <a href="array" title="c/language/array">variable-length array</a> (VLA) declarator, the entire declarator's type is known as "variably-modified type". Types defined from variably-modified types are also variably modified (VM).</p> +<p>Declarations of any variably-modified types may appear only at <a href="scope" title="c/language/scope">block scope</a> or function prototype scope and cannot be members of structs or unions. Although VLA can only have automatic or allocated <a href="storage_duration" title="c/language/storage duration">storage duration</a>, a VM type such as a pointer to a VLA may be static. There are other restrictions on the use of VM types, see <a href="goto" title="c/language/goto">goto</a>, <a href="switch" title="c/language/switch">switch</a>. <code><a href="../program/longjmp" title="c/program/longjmp">longjmp</a></code></p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <p><a href="_static_assert" title="c/language/ Static assert">static_asserts</a> are considered to be declarations from the point of view of the C grammar (so that they may appear anywhere a declaration may appear), but they do not introduce any identifiers and do not follow the declaration syntax.</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p><a href="attributes" title="c/language/attributes">Attribute</a> declarations are also considered to be declarations (so that they may appear anywhere a declaration may appear), but they do not introduce any identifiers. A single <code>;</code> without <span class="t-spar">attr-spec-seq</span> is not an attribute declaration, but a statement.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.7 Declarations (p: 78-105) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.7 Declarations (p: 108-145) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.7 Declarations (p: 97-130) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.5 Declarations </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/declarations" title="cpp/language/declarations">C++ documentation</a></span> for <span class=""><span>Declarations</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/declarations" class="_attribution-link">https://en.cppreference.com/w/c/language/declarations</a> + </p> +</div> diff --git a/devdocs/c/language%2Fdo.html b/devdocs/c/language%2Fdo.html new file mode 100644 index 00000000..226bcf7c --- /dev/null +++ b/devdocs/c/language%2Fdo.html @@ -0,0 +1,61 @@ + <h1 id="firstHeading" class="firstHeading">do-while loop</h1> <p>Executes a <span class="t-spar">statement</span> repeatedly until the value of the condition <span class="t-spar">expression</span> becomes false. The test takes place after each iteration.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span> <code>do</code> <span class="t-spar">statement</span> <code>while (</code> <span class="t-spar">expression</span> <code>)</code> <code>;</code> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">expression</span> </td> <td> - </td> <td> any <a href="expressions" title="c/language/expressions">expression</a> of <a href="type#Type_groups" title="c/language/type">scalar type</a>. This expression is evaluated after each iteration, and if it compares equal to zero, the loop is exited. </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">statement</span> </td> <td> - </td> <td> any <a href="statements" title="c/language/statements">statement</a>, typically a compound statement, which is the body of the loop </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">attr-spec-seq</span> </td> <td> - </td> <td> <span class="t-mark-rev t-since-c23">(C23)</span>optional list of <a href="attributes" title="c/language/attributes">attributes</a>, applied to the loop statement </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>A <code>do-while</code> statement causes the <span class="t-spar">statement</span> (also called <i>the loop body</i>) to be executed repeatedly until the <span class="t-spar">expression</span> (also called <i>controlling expression</i>) compares equal to 0. The repetition occurs regardless of whether the loop body is entered normally or by a <a href="goto" title="c/language/goto">goto</a> into the middle of <span class="t-spar">statement</span>.</p> +<p>The evaluation of <span class="t-spar">expression</span> takes place after each execution of <span class="t-spar">statement</span> (whether entered normally or by a goto). If the controlling expression needs to be evaluated before the loop body, the <a href="while" title="c/language/while">while loop</a> or the <a href="for" title="c/language/for">for loop</a> may be used.</p> +<p>If the execution of the loop needs to be terminated at some point, <a href="break" title="c/language/break"> break statement</a> can be used as terminating statement.</p> +<p>If the execution of the loop needs to be continued at the end of the loop body, <a href="continue" title="c/language/continue"> continue statement</a> can be used as a shortcut.</p> +<p>A program with an endless loop has undefined behavior if the loop has no observable behavior (I/O, volatile accesses, atomic or synchronization operation) in any part of its <span class="t-spar">statement</span> or <span class="t-spar">expression</span>. This allows the compilers to optimize out all unobservable loops without proving that they terminate. The only exceptions are the loops where <span class="t-spar">expression</span> is a constant expression; <code>do {...} while(true);</code> is always an endless loop.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>As with all other selection and iteration statements, the do-while statement establishes <a href="scope" title="c/language/scope">block scope</a>: any identifier introduced in the <span class="t-spar">expression</span> goes out of scope after the statement.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>Boolean and pointer expressions are often used as loop controlling expressions. The boolean value <code>false</code> and the null pointer value of any pointer type compare equal to zero.</p> +<h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/do" title="c/keyword/do"><code>do</code></a>, <a href="../keyword/while" title="c/keyword/while"><code>while</code></a></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> +enum { SIZE = 8 }; +int main(void) +{ + // trivial example + int array[SIZE], n = 0; + do array[n++] = rand() % 2; // the loop body is a single expression statement + while(n < SIZE); + puts("Array filled!"); + n = 0; + do { // the loop body is a compound statement + printf("%d ", array[n]); + ++n; + } while (n < SIZE); + printf("\n"); + + // the loop from K&R itoa(). The do-while loop is used + // because there is always at least one digit to generate + int num = 1234, i=0; + char s[10]; + do s[i++] = num % 10 + '0'; // get next digit in reverse order + while ((num /= 10) > 0); + s[i] = '\0'; + puts(s); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Array filled! +1 0 1 1 1 1 0 0 +4321</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.8.5.2 The do statement (p: 109) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.8.5.2 The do statement (p: 151) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.8.5.2 The do statement (p: 136) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.6.5.2 The do statement </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/do" title="cpp/language/do">C++ documentation</a></span> for <span class=""><span><code>do</code>-<code>while</code> loop</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/do" class="_attribution-link">https://en.cppreference.com/w/c/language/do</a> + </p> +</div> diff --git a/devdocs/c/language%2Fenum.html b/devdocs/c/language%2Fenum.html new file mode 100644 index 00000000..f472e47a --- /dev/null +++ b/devdocs/c/language%2Fenum.html @@ -0,0 +1,140 @@ + <h1 id="firstHeading" class="firstHeading">Enumerations</h1> <p>An <i>enumerated type</i> is a distinct <a href="type" title="c/language/type">type</a> whose value is a value of its <i>underlying type</i> (see below), which includes the values of explicitly named constants (<i>enumeration constants</i>).</p> +<h3 id="Syntax"> Syntax</h3> <p>Enumerated type is declared using the following <i>enumeration specifier</i> as the <span class="t-spar">type-specifier</span> in the <a href="declarations" title="c/language/declarations">declaration grammar</a>:</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>enum</code> <span class="t-spar">attr-spec-seq</span> <span class="t-mark">(optional)</span> <span class="t-spar">identifier</span> <span class="t-mark">(optional)</span> <code>{</code> <span class="t-spar">enumerator-list</span> <code>}</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>enum</code> <span class="t-spar">attr-spec-seq</span> <span class="t-mark">(optional)</span> <span class="t-spar">identifier</span> <span class="t-mark">(optional)</span> <code>:</code> <span class="t-spar">type</span> <code>{</code> <span class="t-spar">enumerator-list</span> <code>}</code> </td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> Declares an enumeration without a fixed underlying type.</div> <div class="t-li1"> +<span class="t-li">2)</span> Declares an enumeration of fixed underlying type <span class="t-spar">type</span>.</div> <p>where <span class="t-spar">enumerator-list</span> is a comma-separated list<span class="t-rev-inl t-since-c99"><span>(with trailing comma permitted)</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> of <span class="t-spar">enumerator</span>, each of which has the form:</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="t-spar">enumeration-constant</span> <span class="t-spar">attr-spec-seq</span> <span class="t-mark">(optional)</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">enumeration-constant</span> <span class="t-spar">attr-spec-seq</span> <span class="t-mark">(optional)</span> <code>=</code> <span class="t-spar">constant-expression</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">identifier</span>, <span class="t-spar">enumeration-constant</span> </td> <td> - </td> <td> identifiers that are introduced by this declaration </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">constant-expression</span> </td> <td> - </td> <td> <a href="constant_expression" title="c/language/constant expression">integer constant expression</a> <span class="t-rev-inl t-until-c23"><span>whose value is representable as a value of type <span class="kw4">int</span></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span>. <span class="t-rev-inl t-since-c23"><span>If the enumeration has a fixed underlying type, representable as a value of <span class="t-spar">type</span></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">attr-spec-seq</span> </td> <td> - </td> <td> <span class="t-mark-rev t-since-c23">(C23)</span>optional list of <a href="attributes" title="c/language/attributes">attributes</a>, <ul> +<li> applied to the whole enumeration if appears after <code>enum</code>, </li> +<li> applied to the <span class="t-spar">enumerator</span> if appears after <span class="t-spar">enumeration-constant</span> </li> +</ul> </td> +</tr> +</table> <p>As with <a href="struct" title="c/language/struct">struct</a> or <a href="union" title="c/language/union">union</a>, a declaration that introduced an enumerated type and one or more enumeration constants may also declare one or more objects of that type or type derived from it.</p> +<div class="c source-c"><pre data-language="c">enum color { RED, GREEN, BLUE } c = RED, *cp = &c; +// introduces the type enum color +// the integer constants RED, GREEN, BLUE +// the object c of type enum color +// the object cp of type pointer to enum color</pre></div> <h3 id="Explanation"> Explanation</h3> <p>Each <span class="t-spar">enumeration-constant</span> that appears in the body of an enumeration specifier becomes an <a href="constant_expression" title="c/language/constant expression">integer constant</a> <span class="t-rev-inl t-until-c23"><span>with type <span class="kw4">int</span></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span> in the enclosing scope and can be used whenever integer constants are required (e.g. as a case label or as a non-VLA array size).</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>During the processing of each enumeration constant in the enumerator list, the type of the enumeration constant shall be:</p> +<ul> +<li> the previously declared type, if it is a redeclaration of the same enumeration constant; or, </li> +<li> the enumerated type, for an enumeration with fixed underlying type; or, </li> +<li> <span class="kw4">int</span>, if there are no previous enumeration constants in the enumerator list and no explicit = with a defining integer constant expression; or, </li> +<li> <span class="kw4">int</span>, if given explicitly with = and the value of the integer constant expression is representable by an int; or, </li> +<li> the type of the integer constant expression, if given explicitly with = and if the value of the integer constant expression is not representable by <span class="kw4">int</span>; or, </li> +<li> the type of the value from last enumeration constant with 1 added to it. If such an integer constant expression would overflow or wraparound the value of the previous enumeration constant from the addition of 1, the type takes on either: <ul> +<li> a suitably sized signed integer type (excluding the bit-precise signed integer types) capable of representing the value of the previous enumeration constant plus 1; or, </li> +<li> a suitably sized unsigned integer type (excluding the bit-precise unsigned integer types) capable of representing the value of the previous enumeration constant plus 1. </li> +</ul> </li> +</ul> <p>A signed integer type is chosen if the previous enumeration constant being added is of signed integer type. An unsigned integer type is chosen if the previous enumeration constant is of unsigned integer type. If there is no suitably sized integer type described previous which can represent the new value, then the enumeration has no type which is capable of representing all of its values.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <div class="c source-c"><pre data-language="c">enum color { RED, GREEN, BLUE } r = RED; +switch(r) +{ +case RED: + puts("red"); + break; +case GREEN: + puts("green"); + break; +case BLUE: + puts("blue"); + break; +}</pre></div> <p>If <span class="t-spar">enumeration-constant</span> is followed by <span class="t-spar">= constant-expression</span>, its value is the value of that constant expression. If <span class="t-spar">enumeration-constant</span> is not followed by <span class="t-spar">= constant-expression</span>, its value is the value one greater than the value of the previous enumerator in the same enumeration. The value of the first enumerator (if it does not use <span class="t-spar">= constant-expression</span>) is zero.</p> +<div class="c source-c"><pre data-language="c">enum Foo { A, B, C = 10, D, E = 1, F, G = F + C }; +// A=0, B=1, C=10, D=11, E=1, F=2, G=12</pre></div> <p>The <span class="t-spar">identifier</span> itself, if used, becomes the name of the enumerated type in the tags <a href="name_space" title="c/language/name space">name space</a> and requires the use of the keyword enum (unless typedef'd into the ordinary name space).</p> +<div class="c source-c"><pre data-language="c">enum color { RED, GREEN, BLUE }; +enum color r = RED; // OK +// color x = GREEN: // Error: color is not in ordinary name space +typedef enum color color_t; +color_t x = GREEN; // OK</pre></div> <p>Each enumerated type <span class="t-rev-inl t-since-c23"><span>without a fixed underlying type</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> is <a href="type#Compatible_types" title="c/language/type">compatible</a> with one of: <span class="kw4">char</span>, a signed integer type, or an unsigned integer type <span class="t-rev-inl t-since-c23"><span>(excluding bool and the bit-precise integer types)</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>. It is implementation-defined which type is compatible with any given enumerated type, but whatever it is, it must be capable of representing all enumerator values of that enumeration. <span class="t-rev-inl t-since-c23"><span>For all enumerations with a fixed underlying type, the enumerated type is compatible with the underlying type of the enumeration.</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span></p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>The enumeration member type for an enumerated type without fixed underlying type upon completion is:</p> +<ul> +<li> <span class="kw4">int</span> if all the values of the enumeration are representable as an <span class="kw4">int</span>; or, </li> +<li> the enumerated type. </li> +</ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td>All enumerations have an underlying type. The underlying type can be explicitly specified using an enum-type-specifier and is its fixed underlying type. If it is not explicitly specified, the underlying type is the enumeration’s compatible type, which is either a signed or unsigned integer type, or <span class="kw4">char</span>. </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <p>Enumerated types are integer types, and as such can be used anywhere other integer types can, including in <a href="conversion" title="c/language/conversion">implicit conversions</a> and <a href="operator_arithmetic" title="c/language/operator arithmetic">arithmetic operators</a>.</p> +<div class="c source-c"><pre data-language="c">enum { ONE = 1, TWO } e; +long n = ONE; // promotion +double d = ONE; // conversion +e = 1.2; // conversion, e is now ONE +e = e + 1; // e is now TWO</pre></div> <h3 id="Notes"> Notes</h3> <p>Unlike <a href="struct" title="c/language/struct">struct</a> or <a href="union" title="c/language/union">union</a>, there are no forward-declared enums in C:</p> +<div class="c source-c"><pre data-language="c">enum Color; // Error: no forward-declarations for enums in C +enum Color { RED, GREEN, BLUE };</pre></div> <p>Enumerations permit the declaration of named constants in a more convenient and structured fashion than does <code>#define</code>; they are visible in the debugger, obey scope rules, and participate in the type system.</p> +<div class="c source-c"><pre data-language="c">#define TEN 10 +struct S { int x : TEN; }; // OK</pre></div> <p>or</p> +<div class="c source-c"><pre data-language="c">enum { TEN = 10 }; +struct S { int x : TEN; }; // also OK</pre></div> <p>Since C23 <a href="constexpr" title="c/language/constexpr">constexpr</a> can be used for the same purpose:</p> +<div class="c source-c"><pre data-language="c">constexpr int TEN = 10; +struct S { int x : TEN; }; // also OK</pre></div> <p>Moreover, as a <a href="struct" title="c/language/struct">struct</a> or <a href="union" title="c/language/union">union</a> does not establish its scope in C, an enumeration type and its enumeration constants may be introduced in the member specification of the former, and their scope is the same as of the former, afterwards.</p> +<div class="c source-c"><pre data-language="c">struct Element +{ + int z; + enum State { SOLID, LIQUID, GAS, PLASMA } state; +} oxygen = { 8, GAS }; + +// type enum State and its enumeration constants stay visible here, e.g. +void foo(void) +{ + enum State e = LIQUID; // OK + printf("%d %d %d ", e, oxygen.state, PLASMA); // prints 1 2 3 +}</pre></div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +int main(void) +{ + enum TV { FOX = 11, CNN = 25, ESPN = 15, HBO = 22, MAX = 30, NBC = 32 }; + + printf("List of cable stations:\n"); + printf(" FOX: \t%2d\n", FOX); + printf(" HBO: \t%2d\n", HBO); + printf(" MAX: \t%2d\n", MAX); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">List of cable stations: + FOX: 11 + HBO: 22 + MAX: 30</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 6.2.5/21 Types (p: 39) </li> +<li> 6.7.2.2 Enumeration specifiers (p: 107-112) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.2.5/16 Types (p: 32) </li> +<li> 6.7.2.2 Enumeration specifiers (p: 84-85) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.2.5/16 Types (p: 41) </li> +<li> 6.7.2.2 Enumeration specifiers (p: 117-118) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 6.2.5/16 Types (p: 35) </li> +<li> 6.7.2.2 Enumeration specifiers (p: 105-106) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 3.1.2.5 Types </li> +<li> 3.5.2.2 Enumeration specifiers </li> +</ul> +</ul> <h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/enum" title="c/keyword/enum"><code>enum</code></a></p> +<h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/enum" title="cpp/language/enum">C++ documentation</a></span> for <span class=""><span>enumeration declaration</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/enum" class="_attribution-link">https://en.cppreference.com/w/c/language/enum</a> + </p> +</div> diff --git a/devdocs/c/language%2Fescape.html b/devdocs/c/language%2Fescape.html new file mode 100644 index 00000000..84167c53 --- /dev/null +++ b/devdocs/c/language%2Fescape.html @@ -0,0 +1,82 @@ + <h1 id="firstHeading" class="firstHeading">Escape sequences</h1> <p>Escape sequences are used to represent certain special characters within <a href="string_literal" title="c/language/string literal">string literals</a> and <a href="character_constant" title="c/language/character constant">character constants</a>.</p> +<p>The following escape sequences are available. ISO C requires a diagnostic if the backslash is followed by any character not listed here:</p> +<table class="wikitable"> <tr> <th> Escape<br> sequence </th> <th> Description </th> <th> Representation </th> +</tr> <tr> <th colspan="3"> Simple escape sequences </th> +</tr> <tr> <td> <code>\'</code> </td> <td> single quote </td> <td> byte <code>0x27</code> in ASCII encoding </td> +</tr> <tr> <td> <code>\"</code> </td> <td> double quote </td> <td> byte <code>0x22</code> in ASCII encoding </td> +</tr> <tr> <td> <code>\?</code> </td> <td> question mark </td> <td> byte <code>0x3f</code> in ASCII encoding </td> +</tr> <tr> <td> <code>\\</code> </td> <td> backslash </td> <td> byte <code>0x5c</code> in ASCII encoding </td> +</tr> <tr> <td> <code>\a</code> </td> <td> audible bell </td> <td> byte <code>0x07</code> in ASCII encoding </td> +</tr> <tr> <td> <code>\b</code> </td> <td> backspace </td> <td> byte <code>0x08</code> in ASCII encoding </td> +</tr> <tr> <td> <code>\f</code> </td> <td> form feed - new page </td> <td> byte <code>0x0c</code> in ASCII encoding </td> +</tr> <tr> <td> <code>\n</code> </td> <td> line feed - new line </td> <td> byte <code>0x0a</code> in ASCII encoding </td> +</tr> <tr> <td> <code>\r</code> </td> <td> carriage return </td> <td> byte <code>0x0d</code> in ASCII encoding </td> +</tr> <tr> <td> <code>\t</code> </td> <td> horizontal tab </td> <td> byte <code>0x09</code> in ASCII encoding </td> +</tr> <tr> <td> <code>\v</code> </td> <td> vertical tab </td> <td> byte <code>0x0b</code> in ASCII encoding </td> +</tr> <tr> <th colspan="3"> Numeric escape sequences </th> +</tr> <tr> <td> <code>\<i>nnn</i></code> </td> <td> arbitrary octal value </td> <td> code unit <code><i>nnn</i></code> </td> +</tr> <tr> <td> <code>\x<i>n...</i></code> </td> <td> arbitrary hexadecimal value </td> <td> code unit <code><i>n...</i></code> (arbitrary number of hexadecimal digits) </td> +</tr> <tr> <th colspan="3"> Universal character names </th> +</tr> <tr> <td> <code>\u<i>nnnn</i></code> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> <td> <a href="https://en.wikipedia.org/wiki/Unicode" class="extiw" title="enwiki:Unicode"> Unicode</a> value in allowed range;<br>may result in several code units </td> <td> code point <code>U+<i>nnnn</i></code> </td> +</tr> <tr> <td> <code>\U<i>nnnnnnnn</i></code> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> <td> <a href="https://en.wikipedia.org/wiki/Unicode" class="extiw" title="enwiki:Unicode"> Unicode</a> value in allowed range;<br>may result in several code units </td> <td> code point <code>U+<i>nnnnnnnn</i></code> </td> +</tr> +</table> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <h3 id="Range_of_universal_character_names"> Range of universal character names</h3> <p>If a universal character name corresponds to a code point that is not <code>0x24</code> (<span class="st0">'$'</span>), <code>0x40</code> (<span class="st0">'@'</span>), nor <code>0x60</code> (<span class="st0">'`'</span>) and less than <code>0xA0</code>, or a surrogate code point (the range <code>0xD800-0xDFFF</code>, inclusive)<span class="t-rev-inl t-since-c23"><span>, or greater than <code>0x10FFFF</code>, i.e. not a Unicode code point</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, the program is ill-formed. In other words, members of <a href="translation_phases" title="c/language/translation phases">basic source character set</a> and control characters (in ranges <code>0x0-0x1F</code> and <code>0x7F-0x9F</code>) cannot be expressed in universal character names.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p><code>\0</code> is the most commonly used octal escape sequence, because it represents the terminating null character in null-terminated strings.</p> +<p>The new-line character <code>\n</code> has special meaning when used in <a href="../io" title="c/io">text mode I/O</a>: it is converted to the OS-specific newline byte or byte sequence.</p> +<p>Octal escape sequences have a length limit of three octal digits but terminate at the first character that is not a valid octal digit if encountered sooner.</p> +<p>Hexadecimal escape sequences have no length limit and terminate at the first character that is not a valid hexadecimal digit. If the value represented by a single hexadecimal escape sequence does not fit the range of values represented by the character type used in this string literal or character constant (<span class="kw4">char</span><span class="t-rev-inl t-since-c23"><span>, char8_t</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span><span class="t-rev-inl t-since-c11"><span>, char16_t, char32_t</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span>, or <span class="kw4">wchar_t</span>), the result is unspecified.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>A universal character name in a narrow string literal <span class="t-rev-inl t-since-c11"><span>or a 16-bit string literal</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> may map to more than one code unit, e.g. <code>\U0001f34c</code> is 4 <span class="kw4">char</span> code units in UTF-8 (<code>\xF0\x9F\x8D\x8C</code>)<span class="t-rev-inl t-since-c11"><span> and 2 char16_t code units in UTF-16 (<code>\xD83C\xDF4C</code>)</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span>.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <table class="t-rev-begin"> <tr class="t-rev t-since-c99 t-until-c23"> +<td> <p>A universal character name corresponding to a code pointer greater than <code>0x10FFFF</code> (which is undefined in ISO/ISC 10646) can be used in <a href="character_constant" title="c/language/character constant">character constants</a> and <a href="string_literal" title="c/language/string literal">string literals</a>. Such usage is not allowed in C++20.</p> +</td> <td> +<span class="t-mark-rev t-since-c99">(since C99)</span><br><span class="t-mark-rev t-until-c23">(until C23)</span> +</td> +</tr> </table> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>The question mark escape sequence <code>\?</code> is used to prevent <a href="operator_alternative" title="c/language/operator alternative">trigraphs</a> from being interpreted inside string literals: a string such as <code>"??/"</code> is compiled as <code>"\"</code>, but if the second question mark is escaped, as in <code>"?\?/"</code>, it becomes <code>"??/"</code></p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> </table> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +int main(void) +{ + printf("This\nis\na\ntest\n\nShe said, \"How are you?\"\n"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">This +is +a +test + +She said, "How are you?"</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 5.2.2 Character display semantics (p: 18-19) </li> +<li> 6.4.3 Universal Character names (p: 44) </li> +<li> 6.4.4.4 Character constants (p: 48-50) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 5.2.2 Character display semantics (p: 24-25) </li> +<li> 6.4.3 Universal Character names (p: 61) </li> +<li> 6.4.4.4 Character constants (p: 67-70) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 5.2.2 Character display semantics (p: 19-20) </li> +<li> 6.4.3 Universal Character names (p: 53) </li> +<li> 6.4.4.4 Character constants (p: 59-61) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 2.2.2 Character display semantics </li> +<li> 3.1.3.4 Character constants </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <ul><li> <a href="ascii" title="c/language/ascii">ASCII chart</a> </li></ul> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/escape" title="cpp/language/escape">C++ documentation</a></span> for <span class=""><span>Escape sequences</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/escape" class="_attribution-link">https://en.cppreference.com/w/c/language/escape</a> + </p> +</div> diff --git a/devdocs/c/language%2Feval_order.html b/devdocs/c/language%2Feval_order.html new file mode 100644 index 00000000..8b1ef82e --- /dev/null +++ b/devdocs/c/language%2Feval_order.html @@ -0,0 +1,43 @@ + <h1 id="firstHeading" class="firstHeading">Order of evaluation</h1> <p>Order of evaluation of the operands of any C operator, including the order of evaluation of function arguments in a function-call expression, and the order of evaluation of the subexpressions within any expression is unspecified (except where noted below). The compiler will evaluate them in any order, and may choose another order when the same expression is evaluated again.</p> +<p>There is no concept of left-to-right or right-to-left evaluation in C, which is not to be confused with left-to-right and right-to-left associativity of operators: the expression <code>f1() + f2() + f3()</code> is parsed as <code>(f1() + f2()) + f3()</code> due to left-to-right associativity of operator+, but the function call to <code>f3</code> may be evaluated first, last, or between <code>f1()</code> or <code>f2()</code> at run time.</p> +<h3 id="Definitions"> Definitions</h3> <h4 id="Evaluations"> Evaluations</h4> <p>There are two kinds of evaluations performed by the compiler for each expression or subexpression (both of which are optional):</p> +<ul> +<li> <i>value computation</i>: calculation of the value that is returned by the expression. This may involve determination of the identity of the object (<a href="value_category" title="c/language/value category">lvalue evaluation</a>) or reading the value previously assigned to an object (rvalue evaluation) </li> +<li> <i>side effect</i>: access (read or write) to an object designated by a <a href="volatile" title="c/language/volatile">volatile</a> lvalue, modification (writing) to an object<span class="t-rev-inl t-since-c11"><span>, atomic synchronization</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span>, modifying a file, modifying the floating-point environment (if supported), or calling a function that does any of those operations. </li> +</ul> <p>If no side effects are produced by an expression and the compiler can determine that the value is not used, the expression <a href="as_if" title="c/language/as if">may not be evaluated</a>.</p> +<h4 id="Ordering"> Ordering</h4> <p>"sequenced-before" is an asymmetric, transitive, pair-wise relationship between evaluations within the same thread (it may extend across threads if atomic types and memory barriers are involved).</p> +<ul><li> If a <a href="https://en.wikipedia.org/wiki/Sequence_point" class="extiw" title="enwiki:Sequence point"><i>sequence point</i></a> is present between the subexpressions E1 and E2, then both value computation and side effects of E1 are <i>sequenced-before</i> every value computation and side effect of E2 </li></ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <ul> +<li> If evaluation A is sequenced before evaluation B, then evaluation of A will be complete before evaluation of B begins. </li> +<li> If A is not sequenced before B and B is sequenced before A, then evaluation of B will be complete before evaluation of A begins. </li> +<li> If A is not sequenced before B and B is not sequenced before A, then two possibilities exist: <ul> +<li> evaluations of A and B are unsequenced: they may be performed in any order and may overlap (within a single thread of execution, the compiler may interleave the CPU instructions that comprise A and B) </li> +<li> evaluations of A and B are indeterminably-sequenced: they may be performed in any order but may not overlap: either A will be complete before B, or B will be complete before A. The order may be the opposite the next time the same expression is evaluated. </li> +</ul> </li> +</ul> </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <h3 id="Rules"> Rules</h3> <div class="t-li1"> +<span class="t-li">1)</span> There is a sequence point after the evaluation of all function arguments and of the function designator, and before the actual function call.</div> <div class="t-li1"> +<span class="t-li">2)</span> There is a sequence point after evaluation of the first (left) operand and before evaluation of the second (right) operand of the following binary operators: <code>&&</code> (logical AND), <code>||</code> (logical OR), and <code>,</code> (comma).</div> <div class="t-li1"> +<span class="t-li">3)</span> There is a sequence point after evaluation of the first (left) operand and before evaluation of the second or third operand (whichever is evaluated) of the conditional operator <code>?:</code> +</div> <div class="t-li1"> +<span class="t-li">4)</span> There is a sequence point after the evaluation of a full expression (an expression that is not a subexpression: typically something that ends with a semicolon or a <a href="statements" title="c/language/statements">controlling statement</a> of <code>if</code>/<code>switch</code>/<code>while</code>/<code>do</code>) and before the next full expression.</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <span class="t-li">5)</span> There is a sequence point at the end of a full declarator. <span class="t-li">6)</span> There is a sequence point immediately before the return of a library function. <span class="t-li">7)</span> There is a sequence point after the action associated with each conversion specifier in formatted I/O (in particular, it is well-formed for <code><a href="../io/fscanf" title="c/io/fscanf">scanf</a></code> to write different fields into the same variable and for <code><a href="../io/fprintf" title="c/io/fprintf">printf</a></code> to read and modify or modify the same variable more than once using <code>%n</code>) <span class="t-li">8)</span> There are sequence points before and immediately after each call to a comparison function made by the library functions <code><a href="../algorithm/qsort" title="c/algorithm/qsort">qsort</a></code> and <code><a href="../algorithm/bsearch" title="c/algorithm/bsearch">bsearch</a></code>, as well as between any call to the comparison function and the movement of the associated objects made by <code><a href="../algorithm/qsort" title="c/algorithm/qsort">qsort</a></code> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> <tr class="t-rev t-since-c11"> +<td> <span class="t-li">9)</span> The value computations (but not the side-effects) of the operands to any operator are sequenced before the value computation of the result of the operator (but not its side-effects). <span class="t-li">10)</span> The side effect (modification of the left argument) of the direct assignment operator and of all compound assignment operators is sequenced after the value computation (but not the side effects) of both left and right arguments. <span class="t-li">11)</span> The value computation of the postincrement and postdecrement operators is sequenced before its side-effect. <span class="t-li">12)</span> A function call that is not sequenced before or sequenced after another function call is indeterminately sequenced (CPU instructions that constitute different function calls cannot be interleaved, even if the functions are inlined) <span class="t-li">13)</span> In <a href="initialization" title="c/language/initialization">initialization</a> list expressions, all evaluations are indeterminately sequenced <span class="t-li">14)</span> With respect to an indeterminately-sequenced function call, the operation of compound assignment operators, and both prefix and postfix forms of increment and decrement operators are single evaluations. </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <h3 id="Undefined_behavior"> Undefined behavior</h3> <div class="t-li1"> +<span class="t-li">1)</span> If a side effect on a scalar object is unsequenced relative to another side effect on the same scalar object, the <a href="behavior#UB_and_optimization" title="c/language/behavior">behavior is undefined</a>. <div class="c source-c"><pre data-language="c">i = ++i + i++; // undefined behavior +i = i++ + 1; // undefined behavior +f(++i, ++i); // undefined behavior +f(i = -1, i = -1); // undefined behavior</pre></div> +</div> <div class="t-li1"> +<span class="t-li">2)</span> If a side effect on a scalar object is unsequenced relative to a value computation using the value of the same scalar object, the behavior is undefined. <div class="c source-c"><pre data-language="c">f(i, i++); // undefined behavior +a[i] = i++; // undefined bevahior</pre></div> +</div> <div class="t-li1"> +<span class="t-li">3)</span> The above rules apply as long as at least one allowable ordering of subexpressions permits such an unsequenced side-effect.</div> <h3 id="See_also"> See also</h3> <p><a href="operator_precedence" title="c/language/operator precedence">Operator precedence</a> which defines how expressions are built from their source code representation.</p> +<table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/eval_order" title="cpp/language/eval order">C++ documentation</a></span> for <span class=""><span>Order of evaluation</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/eval_order" class="_attribution-link">https://en.cppreference.com/w/c/language/eval_order</a> + </p> +</div> diff --git a/devdocs/c/language%2Fexpressions.html b/devdocs/c/language%2Fexpressions.html new file mode 100644 index 00000000..77504701 --- /dev/null +++ b/devdocs/c/language%2Fexpressions.html @@ -0,0 +1,79 @@ + <h1 id="firstHeading" class="firstHeading">Expressions</h1> <p>An expression is a sequence of <i>operators</i> and their <i>operands</i>, that specifies a computation.</p> +<p>Expression evaluation may produce a result (e.g., evaluation of <code>2+2</code> produces the result <code>4</code>), may generate side-effects (e.g. evaluation of <code><a href="http://en.cppreference.com/w/c/io/fprintf"><span class="kw851">printf</span></a><span class="br0">(</span><span class="st0">"%d"</span>,<span class="nu0">4</span><span class="br0">)</span></code> sends the character <code>'4'</code> to the standard output stream), and may designate objects or functions.</p> +<h4 id="General"> General</h4> <ul> +<li> <a href="value_category" title="c/language/value category">value categories</a> (lvalue, non-lvalue object, function designator) classify expressions by their values </li> +<li> <a href="eval_order" title="c/language/eval order">order of evaluation</a> of arguments and subexpressions specifies the order in which intermediate results are obtained </li> +</ul> <h3 id="Operators"> Operators</h3> <table class="wikitable"> <tr style="text-align:center"> <th colspan="7"> Common operators </th> +</tr> <tr style="text-align:center"> <td> <a href="operator_assignment" title="c/language/operator assignment"> assignment</a> </td> <td> <a href="operator_incdec" title="c/language/operator incdec"> increment<br>decrement</a> </td> <td> <a href="operator_arithmetic" title="c/language/operator arithmetic"> arithmetic</a> </td> <td> <a href="operator_logical" title="c/language/operator logical"> logical</a> </td> <td> <a href="operator_comparison" title="c/language/operator comparison"> comparison</a> </td> <td> <a href="operator_member_access" title="c/language/operator member access"> member<br>access</a> </td> <td> <a href="operator_other" title="c/language/operator other"> other</a> </td> +</tr> <tr style="text-align:center"> <td> <p><code>a = b a += b a -= b a *= b a /= b a %= b a &= b a |= b a ^= b a <<= b a >>= b</code></p> +</td> <td> <p><code>++a --a a++ a--</code></p> +</td> <td> <p><code>+a -a a + b a - b a * b a / b a % b ~a a & b a | b a ^ b a << b a >> b</code></p> +</td> <td> <p><code>!a a && b a || b</code></p> +</td> <td> <p><code>a == b a != b a < b a > b a <= b a >= b</code></p> +</td> <td> <p><code>a[b] *a &a a->b a.b</code></p> +</td> <td> <p><code>a(...) a, b (type) a a ? b : c sizeof</code><br><br> <code>_Alignof</code><br><span class="t-mark-rev t-since-c11">(since C11)</span></p> +</td> +</tr> </table> <ul> +<li> <a href="operator_precedence" title="c/language/operator precedence"> operator precedence</a> defines the order in which operators are bound to their arguments </li> +<li> <a href="operator_alternative" title="c/language/operator alternative"> alternative representations</a> are alternative spellings for some operators </li> +</ul> <h4 id="Conversions"> Conversions</h4> <ul> +<li> <a href="conversion" title="c/language/conversion">Implicit conversions</a> take place when types of operands do not match the expectations of operators </li> +<li> <a href="cast" title="c/language/cast">Casts</a> may be used to explicitly convert values from one type to another. </li> +</ul> <h4 id="Other"> Other</h4> <ul><li> <a href="constant_expression" title="c/language/constant expression">constant expressions</a> can be evaluated at compile time and used in compile-time context (<span class="t-rev-inl t-since-c99"><span>non-VLA </span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>array sizes, static initializers, etc) </li></ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <ul><li> <a href="generic" title="c/language/generic">generic selections</a> can execute different expressions depending on the types of the arguments </li></ul> </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <ul> +<li> Floating-point expressions may raise exceptions and report errors as specified in <a href="../numeric/math/math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a> </li> +<li> The standard <a href="../preprocessor/impl" title="c/preprocessor/impl">#pragmas</a> <code>FENV_ACCESS</code>, <code>FP_CONTRACT</code>, and <code>CX_LIMITED_RANGE</code> as well as the <a href="../types/limits/flt_eval_method" title="c/types/limits/FLT EVAL METHOD">floating-point evaluation precision</a> and <a href="../numeric/fenv/fe_round" title="c/numeric/fenv/FE round">rounding direction</a> control the way floating-point expressions are executed. </li> +</ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Primary_expressions"> Primary expressions</h3> <p>The operands of any operator may be other expressions or they may be <i>primary expressions</i> (e.g. in <code>1+2*3</code>, the operands of operator+ are the subexpression <code>2*3</code> and the primary expression <code>1</code>).</p> +<p>Primary expressions are any of the following:</p> +<div class="t-li1"> +<span class="t-li">1)</span> Constants and literals (e.g. <code>2</code> or <code>"Hello, world"</code>)</div> <div class="t-li1"> +<span class="t-li">2)</span> Suitably declared <a href="identifier" title="c/language/identifier">identifiers</a> (e.g. <code>n</code> or <code><a href="http://en.cppreference.com/w/c/io/fprintf"><span class="kw851">printf</span></a></code>)</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <span class="t-li">3)</span> <a href="generic" title="c/language/generic">Generic selections</a> </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <p>Any expression in parentheses is also classified as a primary expression: this guarantees that the parentheses have higher precedence than any operator.</p> +<h4 id="Constants_and_literals"> Constants and literals</h4> <p>Constant values of certain types may be embedded in the source code of a C program using specialized expressions known as literals (for lvalue expressions) and constants (for non-lvalue expressions)</p> +<ul> +<li> <a href="integer_constant" title="c/language/integer constant">integer constants</a> are decimal, octal, or hexadecimal numbers of integer type. </li> +<li> <a href="character_constant" title="c/language/character constant">character constants</a> are individual characters of type <code>int</code> suitable for conversion to a character type or of type <span class="t-rev-inl t-since-c23"><span><code>char8_t</code>,</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> <span class="t-rev-inl t-since-c11"><span><code>char16_t</code>, <code>char32_t</code>, or </span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span><code>wchar_t</code> </li> +<li> <a href="floating_constant" title="c/language/floating constant">floating constants</a> are values of type <code>float</code>, <code>double</code>, or <code>long double</code> </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <ul> +<li> predefined constants <a href="bool_constant" title="c/language/bool constant"><code>true</code>/<code>false</code></a> are values of type <code>bool</code> </li> +<li> predefined constant <a href="nullptr" title="c/language/nullptr"><code>nullptr</code></a> is a value of type <code><a href="../types/nullptr_t" title="c/types/nullptr t">nullptr_t</a></code> </li> +</ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <ul><li> <a href="string_literal" title="c/language/string literal">string literals</a> are sequences of characters of type <code>char[]</code><span class="t-rev-inl t-since-c23"><span>, <code>char8_t[]</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span><span class="t-rev-inl t-since-c11"><span>, <code>char16_t[]</code>, <code>char32_t[]</code>,</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> or <code>wchar_t[]</code> that represent null-terminated strings </li></ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <ul><li> <a href="compound_literal" title="c/language/compound literal">compound literals</a> are values of struct, union, or array type directly embedded in program code </li></ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Unevaluated_expressions"> Unevaluated expressions</h3> <p>The operands of the <a href="sizeof" title="c/language/sizeof"><code>sizeof</code> operator</a> are expressions that are not evaluated<span class="t-rev-inl t-since-c99"><span> (unless they are VLAs)</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>. Thus, <code><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a> n <span class="sy1">=</span> <span class="kw4">sizeof</span><span class="br0">(</span><a href="http://en.cppreference.com/w/c/io/fprintf"><span class="kw851">printf</span></a><span class="br0">(</span><span class="st0">"%d"</span>, <span class="nu0">4</span><span class="br0">)</span><span class="br0">)</span><span class="sy4">;</span></code> does not perform console output.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <p>The operands of the <a href="_alignof" title="c/language/ Alignof"><code>_Alignof</code> operator</a>, the controlling expression of a <a href="generic" title="c/language/generic">generic selection</a>, and size expressions of VLAs that are operands of <code>_Alignof</code> are also expressions that are not evaluated.</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.5 Expressions (p: 55-75) </li> +<li> 6.6 Constant expressions (p: 76-77) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.5 Expressions (p: 76-105) </li> +<li> 6.6 Constant expressions (p: 106-107) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 6.5 Expressions (p: 67-94) </li> +<li> 6.6 Constant expressions (p: 95-96) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 3.3 EXPRESSIONS </li> +<li> 3.4 CONSTANT EXPRESSIONS </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/expressions" title="cpp/language/expressions">C++ documentation</a></span> for <span class=""><span>Expressions</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/expressions" class="_attribution-link">https://en.cppreference.com/w/c/language/expressions</a> + </p> +</div> diff --git a/devdocs/c/language%2Fextern.html b/devdocs/c/language%2Fextern.html new file mode 100644 index 00000000..f2fd53ea --- /dev/null +++ b/devdocs/c/language%2Fextern.html @@ -0,0 +1,56 @@ + <h1 id="firstHeading" class="firstHeading">External and tentative definitions</h1> <p>At the top level of a <a href="translation_phases" title="c/language/translation phases">translation unit</a> (that is, a source file with all the #includes after the preprocessor), every C program is a sequence of <a href="declarations" title="c/language/declarations">declarations</a>, which declare functions and objects with <a href="storage_duration" title="c/language/storage duration">external or internal linkage</a>. These declarations are known as <i>external declarations</i> because they appear outside of any function.</p> +<div class="c source-c"><pre data-language="c">extern int n; // external declaration with external linkage +int b = 1; // external definition with external linkage +static const char *c = "abc"; // external definition with internal linkage +int f(void) { // external definition with external linkage + int a = 1; // non-external + return b; +} +static void x(void) { // external definition with internal linkage +}</pre></div> <p>Objects declared with an external declaration have static <a href="storage_duration" title="c/language/storage duration">storage duration</a>, and as such cannot use <code>auto</code> or <code>register</code> specifiers <span class="t-rev-inl t-since-c23"><span>except that <code>auto</code> can be used for type inference</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>. The identifiers introduced by external declarations have <a href="scope" title="c/language/scope">file scope</a>.</p> +<h3 id="Tentative_definitions"> Tentative definitions</h3> <p>A <i>tentative definition</i> is an external declaration without an initializer, and either without a <a href="storage_duration" title="c/language/storage duration">storage-class specifier</a> or with the specifier <code>static</code>.</p> +<p>A <i>tentative definition</i> is a declaration that may or may not act as a definition. If an actual external definition is found earlier or later in the same translation unit, then the tentative definition just acts as a declaration.</p> +<div class="c source-c"><pre data-language="c">int i1 = 1; // definition, external linkage +int i1; // tentative definition, acts as declaration because i1 is defined +extern int i1; // declaration, refers to the earlier definition + +extern int i2 = 3; // definition, external linkage +int i2; // tentative definition, acts as declaration because i2 is defined +extern int i2; // declaration, refers to the external linkage definition</pre></div> <p>If there are no definitions in the same translation unit, then the tentative definition acts as an actual definition that <a href="initialization#Empty_initialization" title="c/language/initialization">empty-initializes</a> the object.</p> +<div class="c source-c"><pre data-language="c">int i3; // tentative definition, external linkage +int i3; // tentative definition, external linkage +extern int i3; // declaration, external linkage +// in this translation unit, i3 is defined as if by "int i3 = 0;"</pre></div> <p>Unlike the <a href="storage_duration" title="c/language/storage duration">extern</a> declarations, which don't change the linkage of an identifier if a previous declaration established it, tentative definitions may disagree in linkage with another declaration of the same identifier. If two declarations for the same identifier are in scope and have different linkage, the behavior is undefined:</p> +<div class="c source-c"><pre data-language="c">static int i4 = 2; // definition, internal linkage +int i4; // Undefined behavior: linkage disagreement with previous line +extern int i4; // declaration, refers to the internal linkage definition + +static int i5; // tentative definition, internal linkage +int i5; // Undefined behavior: linkage disagreement with previous line +extern int i5; // refers to previous, whose linkage is internal</pre></div> <p>A tentative definition with internal linkage must have complete type.</p> +<div class="c source-c"><pre data-language="c">static int i[]; // Error, incomplete type in a static tentative definition +int i[]; // OK, equivalent to int i[1] = {0}; unless redeclared later in this file</pre></div> <h3 id="One_definition_rule"> One definition rule</h3> <p>Each translation unit may have zero or one external definition of every identifier with <a href="storage_duration" title="c/language/storage duration">internal linkage</a> (a <code>static</code> global).</p> +<p>If an identifier with internal linkage is used in any expression other than a <span class="t-rev-inl t-since-c99"><span>non-VLA,</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> <a href="sizeof" title="c/language/sizeof"><code>sizeof</code></a><span class="t-rev-inl t-since-c11"><span>, <a href="_alignof" title="c/language/ Alignof"><code>_Alignof</code></a></span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span><span class="t-rev-inl t-since-c23"><span>, or <a href="typeof" title="c/language/typeof"><code>typeof</code></a></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, there must be one and only one external definition for that identifier in the translation unit.</p> +<p>The entire program may have zero or one external definition of every identifier with <a href="storage_duration" title="c/language/storage duration">external linkage</a>.</p> +<p>If an identifier with external linkage is used in any expression other than a <span class="t-rev-inl t-since-c99"><span>non-VLA,</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> <a href="sizeof" title="c/language/sizeof"><code>sizeof</code></a><span class="t-rev-inl t-since-c11"><span>, <a href="_alignof" title="c/language/ Alignof"><code>_Alignof</code></a></span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span><span class="t-rev-inl t-since-c23"><span>, or <a href="typeof" title="c/language/typeof"><code>typeof</code></a></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, there must be one and only one external definition for that identifier somewhere in the entire program.</p> +<h3 id="Notes"> Notes</h3> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>Inline definitions in different translation units are not constrained by one definition rule. See <a href="inline" title="c/language/inline"><code>inline</code></a> for the details on the inline function definitions.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <p>See <a href="storage_duration" title="c/language/storage duration">storage duration and linkage</a> for the meaning of the keyword <code>extern</code> with declarations at file scope</p> +<p>See <a href="declarations#Definitions" title="c/language/declarations">definitions</a> for the distinction between declarations and definitions.</p> +<p>Tentative definitions were invented to standardize various pre-C89 approaches to forward declaring identifiers with internal linkage.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.9 External definitions (p: 113-116) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.9 External definitions (p: 155-159) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.9 External definitions (p: 140-144) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.7 EXTERNAL DEFINITIONS </li></ul> +</ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/extern" class="_attribution-link">https://en.cppreference.com/w/c/language/extern</a> + </p> +</div> diff --git a/devdocs/c/language%2Ffile_scope.html b/devdocs/c/language%2Ffile_scope.html new file mode 100644 index 00000000..1e49b1cf --- /dev/null +++ b/devdocs/c/language%2Ffile_scope.html @@ -0,0 +1,27 @@ + <h1 id="firstHeading" class="firstHeading">File scope</h1> <p>If the declarator or type specifier that declares the identifier appears outside of any block or list of parameters, the identifier has file scope, which terminates at the end of the translation unit.</p> +<p>So, placement of an identifier's declaration (in a declarator or type specifier) outside any block or list of parameters means that the identifier has file scope. File scope of an identifier extends from the declaration to the end of the translation unit in which the declaration appears.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>Identifiers a, b, f, and g have file scope.</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> + +int a = 1; +static int b = 2; + +void f (void) {printf("from function f()\n");} +static void g (void) {printf("from function g()\n");} + +int main(void) +{ + f(); + g(); + + return 0; +} +/* end of this translation unit, end of file scope */</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">from function f() +from function g()</pre></div> </div> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/file_scope" class="_attribution-link">https://en.cppreference.com/w/c/language/file_scope</a> + </p> +</div> diff --git a/devdocs/c/language%2Ffloating_constant.html b/devdocs/c/language%2Ffloating_constant.html new file mode 100644 index 00000000..112ca10b --- /dev/null +++ b/devdocs/c/language%2Ffloating_constant.html @@ -0,0 +1,87 @@ + <h1 id="firstHeading" class="firstHeading">Floating constant</h1> <p>Allows values of floating type to be used directly in expressions.</p> +<h3 id="Syntax"> Syntax</h3> <p>A floating constant is a <a href="value_category" title="c/language/value category">non-lvalue</a> expression having the form:</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">significand</span> <span class="t-spar">exponent</span> <span class="t-mark">(optional)</span> <span class="t-spar">suffix</span> <span class="t-mark">(optional)</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>Where the <span class="t-spar">significand</span> has the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">whole-number</span> <span class="t-mark">(optional)</span> <code>.</code><span class="t-mark">(optional)</span> <span class="t-spar">fraction</span> <span class="t-mark">(optional)</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>The <span class="t-spar">exponent</span> has the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>e</code> | <code>E</code> <span class="t-spar">exponent-sign</span> <span class="t-mark">(optional)</span> <span class="t-spar">digit-sequence</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>p</code> | <code>P</code> <span class="t-spar">exponent-sign</span> <span class="t-mark">(optional)</span> <span class="t-spar">digit-sequence</span> </td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> The exponent syntax for a decimal floating-point constant</div> <div class="t-li1"> +<span class="t-li">2)</span> The exponent syntax for hexadecimal floating-point constant</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>Optional single quotes (<code>'</code>) can be inserted between the digits as a separator, they are ignored when compiling.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Explanation"> Explanation</h3> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>If the <span class="t-spar">significand</span> begins with the character sequence <code>0x</code> or <code>0X</code>, the floating constant is a <i>hexadecimal floating constant</i>. Otherwise, it is a <i>decimal floating constant</i>.</p> +<p>For a <i>hexadecimal floating constant</i>, the <span class="t-spar">significand</span> is interpreted as a hexadecimal rational number, and the <span class="t-spar">digit-sequence</span> of the exponent is interpreted as the integer power of 2 to which the significand has to be scaled.</p> +<div class="c source-c"><pre data-language="c">double d = 0x1.2p3; // hex fraction 1.2 (decimal 1.125) scaled by 2^3, that is 9.0</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <p>For a <i>decimal floating constant</i>, the <span class="t-spar">significand</span> is interpreted as a decimal rational number, and the <span class="t-spar">digit-sequence</span> of the exponent is interpreted as the integer power of 10 to which the significand has to be scaled.</p> +<div class="c source-c"><pre data-language="c">double d = 1.2e3; // decimal fraction 1.2 scaled by 10^3, that is 1200.0</pre></div> <h4 id="Suffixes"> Suffixes</h4> <p>An unsuffixed floating constant has type <code>double</code>. If <span class="t-spar">suffix</span> is the letter <code>f</code> or <code>F</code>, the floating constant has type <code>float</code>. If <span class="t-spar">suffix</span> is the letter <code>l</code> or <code>L</code>, the floating constant has type <code>long double</code>.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>If the implementation predefines macro <code>__STDC_IEC_60559_BFP__</code>, the following suffixes and corresponding floating constants are additionally supported:</p> +<ul> +<li> if <span class="t-spar">suffix</span> is <code>df</code> or <code>DF</code>, the floating constant has type <code>_Decimal32</code>; </li> +<li> if <span class="t-spar">suffix</span> is <code>dd</code> or <code>DD</code>, the floating constant has type <code>_Decimal64</code>; </li> +<li> if <span class="t-spar">suffix</span> is <code>dl</code> or <code>DL</code>, the floating constant has type <code>_Decimal128</code>. </li> +</ul> <p>Suffixes for decimal floating-point types are not allowed in hexadecimal floating constants.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h4 id="Optional_parts"> Optional parts</h4> <p>If the exponent is present and fractional part is not used, the decimal separator may be omitted:</p> +<div class="c source-c"><pre data-language="c">double x = 1e0; // floating-point 1.0 (period not used)</pre></div> <p>For decimal floating constants, the <span class="t-spar">exponent</span> part is optional. If it is omitted, the period is not optional, and either the <span class="t-spar">whole-number</span> or the <span class="t-spar">fraction</span> must be present.</p> +<div class="c source-c"><pre data-language="c">double x = 1.; // floating-point 1.0 (fractional part optional) +double y = .1; // floating-point 0.1 (whole-number part optional)</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>For hexadecimal floating constants, the exponent is not optional to avoid ambiguity resulting from an <code>f</code> suffix being mistaken as a hexadecimal digit.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h4 id="Representable_values"> Representable values</h4> <p>The result of evaluating a floating constant is either the nearest representable value or the larger or smaller representable value immediately adjacent to the nearest representable value, chosen in an implementation-defined manner (in other words, <a href="../numeric/fenv/fe_round" title="c/numeric/fenv/FE round">default rounding direction</a> during translation is implementation-defined).</p> +<p>All floating constants of the same source form convert to the same internal format with the same value. Floating constants of different source forms, e.g. <code>1.23</code> and <code>1.230</code>, need not to convert to the same internal format and value.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>Floating-point constants may convert to more range and precision than is indicated by their type, if indicated by <code><a href="../types/limits/flt_eval_method" title="c/types/limits/FLT EVAL METHOD">FLT_EVAL_METHOD</a></code>. For example, the constant <code>0.1f</code> may act as if it were <code>0.1L</code> in an expression.</p> +<p>The result of evaluating a hexadecimal floating constant, if <code><a href="../types/limits" title="c/types/limits">FLT_RADIX</a></code> is 2, is the exact value represented by the floating constant, correctly rounded to the target type.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>Floating constants of decimal floating-point type that have the same numerical value \(\small x\)x but different quantum exponents, e.g. <code>1230.dd</code>, <code>1230.0dd</code>, and <code>1.23e3dd</code>, have distinguishable internal representations.</p> +<p>The quantum exponent \(\small q\)q of a floating constant of a decimal floating-point type is determined in the manner that \(\small 10^q\)10<sup class="t-su">q</sup> represents 1 at the place of last digit of the <span class="t-spar">significand</span> when possible. If the quantum exponent \(\small q\)q and the coefficient \(\small c = x\cdot 10^{-q}\)c=x·10<sup class="t-su">-q</sup> determined above cannot represented exactly in the type of the floating constant, \(\small q\)q is increased as needed within the limit of the type, and \(\small c\)c is reduced correspondingly, with needed rounding. The rounding may result in zero or infinity. If (the possibly rounded) \(\small c\)c is still out of the permitted range after \(\small q\)q reaches the maximum value, the resulted floating constant has value positive infinity.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>Default <a href="../numeric/fenv/fe_round" title="c/numeric/fenv/FE round">rounding direction</a> and <a href="../types/limits/flt_eval_method" title="c/types/limits/FLT EVAL METHOD">precision</a> are in effect when the floating constants are converted into internal representations, and <a href="../numeric/fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">floating-point exceptions</a> are not raised even if <a href="../preprocessor/impl" title="c/preprocessor/impl"><code> #pragma STDC FENV_ACCESS</code></a> is in effect (for execution-time conversion of character strings, <code><a href="../string/byte/strtof" title="c/string/byte/strtof">strtod</a></code> can be used). Note that this differs from <a href="constant_expression" title="c/language/constant expression">arithmetic constant expressions</a> of floating type.</p> +<p>Letters in the floating constants are case-insensitive<span class="t-rev-inl t-since-c23"><span>, except that uppercase and lowercase cannot be both used in suffixes for decimal floating-point types</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>: <code>0x1.ep+3</code> and <code>0X1.EP+3</code> represent the same floating-point value <code>15.0</code>.</p> +<p>The decimal point specified by <code><a href="../locale/setlocale" title="c/locale/setlocale">setlocale</a></code> has no effect on the syntax of floating constants: the decimal point character is always the period.</p> +<p>Unlike integers, not every floating value can be represented directly by decimal <span class="t-rev-inl t-since-c99"><span>or even hexadecimal</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> constant syntax<span class="t-rev-inl t-since-c99"><span>: macros <a href="../numeric/math/nan" title="c/numeric/math/NAN"><code>NAN</code></a> and <a href="../numeric/math/infinity" title="c/numeric/math/INFINITY"><code>INFINITY</code></a> as well as functions such as <code><a href="../numeric/math/nan" title="c/numeric/math/nan">nan</a></code> offer ways to generate those special values</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>. Note that <code>0x1.FFFFFEp128f</code>, which might appear to be an IEEE float NaN, in fact overflows to an infinity in that format.</p> +<p>There are no negative floating constants; an expression such as <code>-1.2</code> is the <a href="operator_arithmetic" title="c/language/operator arithmetic">arithmetic operator</a> unary minus applied to the floating constant <code>1.2</code>. Note that the special value negative zero may be constructed with <code>-0.0</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +int main(void) +{ + printf("15.0 = %a\n", 15.0); + printf("0x1.ep+3 = %f\n", 0x1.ep+3); + + // Constants outside the range of type double. + printf("+2.0e+308 --> %g\n", 2.0e+308); + printf("+1.0e-324 --> %g\n", 1.0e-324); + printf("-1.0e-324 --> %g\n", -1.0e-324); + printf("-2.0e+308 --> %g\n", -2.0e+308); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">15.0 = 0x1.ep+3 +0x1.ep+3 = 15.000000 ++2.0e+308 --> inf ++1.0e-324 --> 0 +-1.0e-324 --> -0 +-2.0e+308 --> -inf</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.4.4.2 Floating constants (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.4.4.2 Floating constants (p: 47-48) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.4.4.2 Floating constants (p: 65-66) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.4.4.2 Floating constants (p: 57-58) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.1.3.1 Floating constants </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/floating_literal" title="cpp/language/floating literal">C++ documentation</a></span> for <span class=""><span>Floating-point literal</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/floating_constant" class="_attribution-link">https://en.cppreference.com/w/c/language/floating_constant</a> + </p> +</div> diff --git a/devdocs/c/language%2Ffor.html b/devdocs/c/language%2Ffor.html new file mode 100644 index 00000000..010d826f --- /dev/null +++ b/devdocs/c/language%2Ffor.html @@ -0,0 +1,63 @@ + <h1 id="firstHeading" class="firstHeading">for loop</h1> <p>Executes a loop.</p> +<p>Used as a shorter equivalent of <a href="while" title="c/language/while">while loop</a>.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">attr-spec-seq</span><span class="t-mark-rev t-since-c23">(since C23)</span><span class="t-mark">(optional)</span> <code>for</code> <code>(</code> <span class="t-spar">init-clause</span> <code>;</code> <span class="t-spar">cond-expression</span> <code>;</code> <span class="t-spar">iteration-expression</span> <code>)</code> <span class="t-spar">loop-statement</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>Behaves as follows:</p> +<ul> +<li> <span class="t-spar">init-clause</span> may be an expression <span class="t-rev-inl t-since-c99"><span>or a declaration</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>. </li> +<ul><li> An <span class="t-spar">init-clause</span>, which is an expression, is evaluated once, before the first evaluation of <span class="t-spar">cond-expression</span> and its result is discarded. </li></ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <ul><li> An <span class="t-spar">init-clause</span>, which is a declaration, is in scope in the entire loop body, including the remainder of <span class="t-spar">init-clause</span>, the entire <span class="t-spar">cond-expression</span>, the entire <span class="t-spar">iteration-expression</span> and the entire <span class="t-spar">loop-statement</span>. Only <code>auto</code> and <code>register</code> <a href="storage_duration" title="c/language/storage duration">storage class specifiers</a> are allowed for the variables declared in this declaration. </li></ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <ul> +<li> <span class="t-spar">cond-expression</span> is evaluated before the loop body. If the result of the expression is zero, the loop statement is exited immediately. </li> +<li> <span class="t-spar">iteration-expression</span> is evaluated after the loop body and its result is discarded. After evaluating <span class="t-spar">iteration-expression</span>, control is transferred to <span class="t-spar">cond-expression</span>. </li> +</ul> <p><span class="t-spar">init-clause</span>, <span class="t-spar">cond-expression</span>, and <span class="t-spar">iteration-expression</span> are all optional. If <span class="t-spar">cond-expression</span> is omitted, it is replaced with a non-zero integer constant, which makes the loop endless:</p> +<div class="c source-c"><pre data-language="c">for(;;) { + printf("endless loop!"); +}</pre></div> <p><span class="t-spar">loop-statement</span> is not optional, but it may be a null statement:</p> +<div class="c source-c"><pre data-language="c">for(int n = 0; n < 10; ++n, printf("%d\n", n)) + ; // null statement</pre></div> <p>If the execution of the loop needs to be terminated at some point, a <a href="break" title="c/language/break"> break statement</a> can be used anywhere within the <span class="t-spar">loop-statement</span>.</p> +<p>The <a href="continue" title="c/language/continue"> continue statement</a> used anywhere within the <span class="t-spar">loop-statement</span> transfers control to <span class="t-spar">iteration-expression</span>.</p> +<p>A program with an endless loop has undefined behavior if the loop has no observable behavior (I/O, volatile accesses, atomic or synchronization operation) in any part of its <span class="t-spar">cond-expression</span>, <span class="t-spar">iteration-expression</span> or <span class="t-spar">loop-statement</span>. This allows the compilers to optimize out all unobservable loops without proving that they terminate. The only exceptions are the loops where <span class="t-spar">cond-expression</span> is omitted or is a constant expression; <code>for(;;)</code> is always an endless loop.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>As with all other selection and iteration statements, the for statement establishes <a href="scope" title="c/language/scope">block scope</a>: any identifier introduced in the <span class="t-spar">init-clause</span>, <span class="t-spar">cond-expression</span>, or <span class="t-spar">iteration-expression</span> goes out of scope after the <span class="t-spar">loop-statement</span>.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p><span class="t-spar">attr-spec-seq</span> is an optional list of <a href="attributes" title="c/language/attributes">attributes</a>, applied to the <code>for</code> statement.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/for" title="c/keyword/for"><code>for</code></a></p> +<h3 id="Notes"> Notes</h3> <p>The expression statement used as <span class="t-spar">loop-statement</span> establishes its own block scope, distinct from the scope of <span class="t-spar">init-clause</span>, unlike in C++:</p> +<div class="c source-c"><pre data-language="c">for (int i = 0; ; ) { + long i = 1; // valid C, invalid C++ + // ... +}</pre></div> <p>It is possible to enter the body of a loop using <a href="goto" title="c/language/goto">goto</a>. When entering a loop in this manner, <span class="t-spar">init-clause</span> and <span class="t-spar">cond-expression</span> are not executed. (If control then reaches the end of the loop body, repetition may occur including execution of <span class="t-spar">cond-expression</span>.)</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> +enum { SIZE = 8 }; +int main(void) +{ + int array[SIZE]; + for(size_t i = 0 ; i < SIZE; ++i) + array [i] = rand() % 2; + printf("Array filled!\n"); + for (size_t i = 0; i < SIZE; ++i) + printf("%d ", array[i]); + putchar('\n'); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Array filled! +1 0 1 1 1 1 0 0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.8.5.3 The for statement (p: 110) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.8.5.3 The for statement (p: 151) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.8.5.3 The for statement (p: 136) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.6.5.3 The for statement </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/for" title="cpp/language/for">C++ documentation</a></span> for <span class=""><span><code>for</code> loop</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/for" class="_attribution-link">https://en.cppreference.com/w/c/language/for</a> + </p> +</div> diff --git a/devdocs/c/language%2Ffunction_declaration.html b/devdocs/c/language%2Ffunction_declaration.html new file mode 100644 index 00000000..af2619d7 --- /dev/null +++ b/devdocs/c/language%2Ffunction_declaration.html @@ -0,0 +1,102 @@ + <h1 id="firstHeading" class="firstHeading">Function declarations</h1> <p>A function declaration introduces an <a href="identifier" title="c/language/identifier">identifier</a> that designates a function and, optionally, specifies the types of the function parameters (the <i>prototype</i>). Function declarations (unlike <a href="function_definition" title="c/language/function definition">definitions</a>) may appear at block scope as well as file scope.</p> +<h3 id="Syntax"> Syntax</h3> <p>In the <a href="declarations" title="c/language/declarations">declaration grammar</a> of a function declaration, the <span class="t-spar">type-specifier</span> sequence, possibly modified by the declarator, designates the <i>return type</i> (which may be any type other than array or function type), and the <span class="t-spar">declarator</span> has one of three forms:</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="t-spar">noptr-declarator</span> <code>(</code> <span class="t-spar">parameter-list</span> <code>)</code> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">noptr-declarator</span> <code>(</code> <span class="t-spar">identifier-list</span> <code>)</code> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span> </td> <td> (2) </td> <td> <span class="t-mark-rev t-until-c23">(until C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">noptr-declarator</span> <code>(</code> <code>)</code> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span> </td> <td> (3) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">noptr-declarator</span> </td> <td> - </td> <td> any <a href="declarations#Declarators" title="c/language/declarations">declarator</a> except unparenthesized pointer declarator. The identifier that is contained in this declarator is the identifier that becomes the function designator. </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">parameter-list</span> </td> <td> - </td> <td> either the single keyword <code>void</code> or a comma-separated list of <i>parameters</i>, which may end with an <a href="variadic" title="c/language/variadic">ellipsis parameter</a> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">identifier-list</span> </td> <td> - </td> <td> comma-separated list of identifiers, only possible if this declarator is used as part of old-style <a href="function_definition" title="c/language/function definition">function definition</a> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">attr-spec-seq</span> </td> <td> - </td> <td> <span class="t-mark-rev t-since-c23">(C23)</span>an optional list of <a href="attributes" title="c/language/attributes">attributes</a>, applied to the function type </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> New-style (C89) function declaration. This declaration both introduces the function designator itself and also serves as a function prototype for any future <a href="operator_other#Function_call" title="c/language/operator other">function call expressions</a>, forcing conversions from argument expressions to the declared parameter types and compile-time checks for the number of arguments. <div class="c source-c"><pre data-language="c">int max(int a, int b); // declaration +int n = max(12.01, 3.14); // OK, conversion from double to int</pre></div> +</div> <div class="t-li1"> +<span class="t-li">2)</span> <span class="t-mark-rev t-until-c23">(until C23)</span> Old-style (K&R) function definition. This declaration does not introduce a prototype and any future <a href="operator_other#Function_call" title="c/language/operator other">function call expressions</a> will perform default argument promotions and will invoke undefined behavior if the number of arguments doesn't match the number of parameters. <div class="c source-c"><pre data-language="c">int max(a, b) + int a, b; // definition expects ints; the second call is undefined +{ + return a > b ? a : b; +} + +int n = max(true, (char)'a'); // calls max with two int args (after promotions) + +int n = max(12.01f, 3.14); // calls max with two double args (after promotions)</pre></div> +</div> <div class="t-li1"> +<span class="t-li">3)</span> <span class="t-rev-inl t-until-c23"><span>Non-prototype function declaration. This declaration does not introduce a prototype</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span>. <span class="t-rev-inl t-since-c23"><span>A new style function declaration equivalent to the <span class="t-spar">parameter-list</span> <code>void</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>.</div> <h3 id="Explanation"> Explanation</h3> <p>The return type of the function, determined by the type specifier in <span class="t-spar">specifiers-and-qualifiers</span> and possibly modified by the <span class="t-spar">declarator</span> as usual in <a href="declarations" title="c/language/declarations">declarations</a>, must be a non-array object type or the type <code>void</code>. If the function declaration is not a definition, the return type can be <a href="type#Incomplete_types" title="c/language/type">incomplete</a>. The return type cannot be cvr-qualified: any qualified return type is adjusted to its unqualified version for the purpose of constructing the function type.</p> +<div class="c source-c"><pre data-language="c">void f(char *s); // return type is void +int sum(int a, int b); // return type of sum is int. +int (*foo(const void *p))[3]; // return type is pointer to array of 3 int + +double const bar(void); // declares function of type double(void) +double (*barp)(void) = bar; // OK: barp is a pointer to double(void) +double const (*barpc)(void) = barp; // OK: barpc is also a pointer to double(void)</pre></div> <p>Function declarators can be combined with other declarators as long as they can share their type specifiers and qualifiers</p> +<div class="c source-c"><pre data-language="c">int f(void), *fip(), (*pfi)(), *ap[3]; // declares two functions and two objects +inline int g(int), n; // Error: inline qualifier is for functions only +typedef int array_t[3]; +array_t a, h(); // Error: array type cannot be a return type for a function</pre></div> <p>If a function declaration appears outside of any function, the identifier it introduces has <a href="scope" title="c/language/scope">file scope</a> and <a href="storage_duration" title="c/language/storage duration">external linkage</a>, unless <code>static</code> is used or an earlier static declaration is visible. If the declaration occurs inside another function, the identifier has block scope (and also either internal or external linkage).</p> +<div class="c source-c"><pre data-language="c">int main(void) +{ + int f(int); // external linkage, block scope + f(1); // definition needs to be available somewhere in the program +}</pre></div> <p>The parameters in a declaration<span class="t-rev-inl t-until-c23"><span> that is not part of a <a href="function_definition" title="c/language/function definition">function definition</a></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span> do not need to be named:</p> +<div class="c source-c"><pre data-language="c">int f(int, int); // declaration +// int f(int, int) { return 7; } // Error: parameters must be named in definitions +// This definition is allowed since C23</pre></div> <p>Each parameter in a <span class="t-spar">parameter-list</span> is a <a href="declarations" title="c/language/declarations">declaration</a> that introduced a single variable, with the following additional properties:</p> +<ul><li> the identifier in the declarator is optional <span class="t-rev-inl t-until-c23"><span>(except if this function declaration is part of a function definition)</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span> </li></ul> <div class="c source-c"><pre data-language="c">int f(int, double); // OK +int g(int a, double b); // also OK +// int f(int, double) { return 1; } // Error: definition must name parameters +// This definition is allowed since C23</pre></div> <ul><li> the only <a href="storage_duration" title="c/language/storage duration">storage class specifier</a> allowed for parameters is <code>register</code>, and it is ignored in function declarations that are not definitions </li></ul> <div class="c source-c"><pre data-language="c">int f(static int x); // Error +int f(int [static 10]); // OK (array index static is not a storage class specifier)</pre></div> <ul><li> any parameter of array type is adjusted to the corresponding pointer type<span class="t-rev-inl t-since-c99"><span>, which may be qualified if there are qualifiers between the square brackets of the array declarator</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> </li></ul> <div class="c source-c"><pre data-language="c">int f(int[]); // declares int f(int*) +int g(const int[10]); // declares int g(const int*) +int h(int[const volatile]); // declares int h(int * const volatile) +int x(int[*]); // declares int x(int*)</pre></div> <ul><li> any parameter of function type is adjusted to the corresponding pointer type </li></ul> <div class="c source-c"><pre data-language="c">int f(char g(double)); // declares int f(char (*g)(double)) +int h(int(void)); // declares int h(int (*)(void))</pre></div> <ul><li> the parameter list may terminate with <code>, ...</code> <span class="t-rev-inl t-since-c23"><span>or be <code>...</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, see <a href="variadic" title="c/language/variadic">variadic functions</a> for details. </li></ul> <div class="c source-c"><pre data-language="c">int f(int, ...);</pre></div> <ul><li> parameters cannot have type <code>void</code> (but can have type pointer to void). The special parameter list that consists entirely of the keyword <code>void</code> is used to declare functions that take no parameters. </li></ul> <div class="c source-c"><pre data-language="c">int f(void); // OK +int g(void x); // Error</pre></div> <ul> +<li> any identifier that appears in a parameter list that could be treated as a typedef name or as a parameter name is treated as a typedef name: <code><span class="kw4">int</span> f<span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a>, <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw133">uintptr_t</span></a><span class="br0">)</span></code> is parsed as a new-style declarator for a function taking two unnamed parameters of type size_t and uintptr_t, not an old-style declarator that begins the definition of a function taking two parameters named "size_t" and "uintptr_t" </li> +<li> parameters may have incomplete type<span class="t-rev-inl t-since-c99"><span> and may use the VLA notation [*]</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> (except that in a <a href="function_definition" title="c/language/function definition">function definition</a>, the parameter types after array-to-pointer and function-to-pointer adjustment must be complete) </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p><a href="attributes" title="c/language/attributes">Attribute specifier sequences</a> can also applied to function parameters.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <p>See <a href="operator_other#Function_call" title="c/language/operator other">function call operator</a> for other details on the mechanics of a function call and <a href="return" title="c/language/return">return</a> for returning from functions.</p> +<h3 id="Notes"> Notes</h3> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>Unlike in C++, the declarators <code>f()</code> and <code>f(void)</code> have different meaning: the declarator <code>f(void)</code> is a new-style (prototype) declarator that declares a function that takes no parameters. The declarator <code>f()</code> is a declarator that declares a function that takes <i>unspecified</i> number of parameters (unless used in a function definition)</p> +<div class="c source-c"><pre data-language="c">int f(void); // declaration: takes no parameters +int g(); // declaration: takes unknown parameters + +int main(void) { + f(1); // compile-time error + g(2); // undefined behavior +} + +int f(void) { return 1; } // actual definition +int g(a,b,c,d) int a,b,c,d; { return 2; } // actual definition</pre></div> </td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> </table> <p>Unlike in a <a href="function_definition" title="c/language/function definition">function definition</a>, the parameter list may be inherited from a typedef</p> +<div class="c source-c"><pre data-language="c">typedef int p(int q, int r); // p is a function type int(int, int) +p f; // declares int f(int, int)</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-until-c99"> +<td> <p>In C89, <span class="t-spar">specifiers-and-qualifiers</span> was optional, and if omitted, the return type of the function defaulted to <code>int</code> (possibly amended by the <span class="t-spar">declarator</span>).</p> +<div class="c source-c"><pre data-language="c">*f() { // function returning int* + return NULL; +}</pre></div> </td> <td><span class="t-mark-rev t-until-c99">(until C99)</span></td> +</tr> </table> <h3 id="Defect_reports"> Defect reports</h3> <p>The following behavior-changing defect reports were applied retroactively to previously published C standards.</p> +<table class="dsctable"> <tr> <th>DR </th> <th>Applied to </th> <th>Behavior as published </th> <th>Correct behavior </th> +</tr> <tr> <td> +<a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_423">DR 423</a> </td> <td>C89 </td> <td>the return type might be qualified </td> <td>the return type is implicitly disqualified </td> +</tr> +</table> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.7.6.3 Function declarators (including prototypes) (p: 96-98) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.7.6.3 Function declarators (including prototypes) (p: 133-136) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.7.5.3 Function declarators (including prototypes) (p: 118-121) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.5.4.3 Function declarators (including prototypes) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/function" title="cpp/language/function">C++ documentation</a></span> for <span class=""><span>Function declaration</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/function_declaration" class="_attribution-link">https://en.cppreference.com/w/c/language/function_declaration</a> + </p> +</div> diff --git a/devdocs/c/language%2Ffunction_definition.html b/devdocs/c/language%2Ffunction_definition.html new file mode 100644 index 00000000..8efefcc2 --- /dev/null +++ b/devdocs/c/language%2Ffunction_definition.html @@ -0,0 +1,93 @@ + <h1 id="firstHeading" class="firstHeading">Function definitions</h1> <p>A function definition associates the function body (a sequence of declarations and statements) with the function name and parameter list. Unlike <a href="function_declaration" title="c/language/function declaration">function declaration</a>, function definitions are allowed at file scope only (there are no nested functions).</p> +<p>C supports two different forms of function definitions:</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span> <span class="t-spar">specifiers-and-qualifiers</span> <span class="t-spar">parameter-list-declarator</span> <span class="t-spar">function-body</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">specifiers-and-qualifiers</span> <span class="t-spar">identifier-list-declarator</span> <span class="t-spar">declaration-list</span> <span class="t-spar">function-body</span> </td> <td> (2) </td> <td> <span class="t-mark-rev t-until-c23">(until C23)</span> </td> +</tr> +</table> <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">attr-spec-seq</span> </td> <td> - </td> <td> <span class="t-mark-rev t-since-c23">(C23)</span>an optional list of <a href="attributes" title="c/language/attributes">attributes</a>, applied to the function </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">specifiers-and-qualifiers</span> </td> <td> - </td> <td> a combination of <ul> +<li> <a href="declarations" title="c/language/declarations">type specifiers</a> that, possibly modified by the declarator, form the <i>return type</i> </li> +<li> <a href="storage_duration" title="c/language/storage duration">storage class specifiers</a>, which determine the linkage of the identifier (<code>static</code>, <code>extern</code>, or none) </li> +<li> function specifiers <a href="inline" title="c/language/inline"><code>inline</code></a>, <a href="_noreturn" title="c/language/ Noreturn"><code>_Noreturn</code></a>, or none </li> +</ul> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">parameter-list-declarator</span> </td> <td> - </td> <td> a declarator for a function type which uses a <a href="function_declaration" title="c/language/function declaration">parameter list</a> to designate function parameters </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">identifier-list-declarator</span> </td> <td> - </td> <td> a declarator for a function type which uses a <a href="function_declaration" title="c/language/function declaration">identifier list</a> to designate function parameters </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">declaration-list</span> </td> <td> - </td> <td> sequence of declarations that declare every identifier in <span class="t-spar">identifier-list-declarator</span>. These declarations cannot use initializers and the only <a href="storage_duration" title="c/language/storage duration">storage-class specifier</a> allowed is <code>register</code>. </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">function-body</span> </td> <td> - </td> <td> a <a href="statements#Compound_statements" title="c/language/statements">compound statement</a>, that is a brace-enclosed sequence of declarations and statements, that is executed whenever this function is called </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> New-style (C89) function definition. This definition both introduces the function itself and serves as a function prototype for any future <a href="operator_other#Function_call" title="c/language/operator other">function call expressions</a>, forcing conversions from argument expressions to the declared parameter types. <div class="c source-c"><pre data-language="c">int max(int a, int b) +{ + return a>b?a:b; +} + +double g(void) +{ + return 0.1; +}</pre></div> +</div> <div class="t-li1"> +<span class="t-li">2)</span> <span class="t-mark-rev t-until-c23">(until C23)</span> Old-style (K&R) function definition. This definition does not behave as a prototype and any future <a href="operator_other#Function_call" title="c/language/operator other">function call expressions</a> will perform default argument promotions. <div class="c source-c"><pre data-language="c">int max(a, b) +int a, b; +{ + return a>b?a:b; +} +double g() +{ + return 0.1; +}</pre></div> +</div> <h3 id="Explanation"> Explanation</h3> <p>As with <a href="function_declaration" title="c/language/function declaration">function declarations</a>, the return type of the function, determined by the type specifier in <span class="t-spar">specifiers-and-qualifiers</span> and possibly modified by the <span class="t-spar">declarator</span> as usual in <a href="declarations" title="c/language/declarations">declarations</a>, must be a complete non-array object type or the type <code>void</code>. If the return type would be cvr-qualified, it is adjusted to its unqualified version for the purpose of constructing the function type.</p> +<div class="c source-c"><pre data-language="c">void f(char *s) { puts(s); } // return type is void +int sum(int a, int b) { return a+b: } // return type is int +int (*foo(const void *p))[3] { // return type is pointer to array of 3 int + return malloc(sizeof(int[3])); +}</pre></div> <p>As with <a href="function_declaration" title="c/language/function declaration">function declarations</a>, the types of the parameters are adjusted from functions to pointers and from arrays to pointers for the purpose of constructing the function type and the top-level cvr-qualifiers of all parameter types are ignored for the purpose of determining <a href="type#Compatible_types" title="c/language/type">compatible function type</a>.</p> +<table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>Unlike <a href="function_declaration" title="c/language/function declaration">function declarations</a>, unnamed formal parameters are not allowed (otherwise, there would be conflicts in old-style (K&R) function definitions), they must be named even if they are not used within the function. The only exception is the special parameter list <code>(void)</code>.</p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td> <p>Formal parameters may be unnamed in function definitions, because old-style (K&R) function definitions has been removed. Unnamed parameters are inaccessible by name within the function body.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <div class="c source-c"><pre data-language="c">int f(int, int); // declaration +// int f(int, int) { return 7; } // Error until C23, OK since C23 +int f(int a, int b) { return 7; } // definition +int g(void) { return 8; } // OK: void doesn't declare a parameter</pre></div> <p>Within the function body, every named parameter is an <a href="value_category" title="c/language/value category">lvalue</a> expression, they have automatic <a href="storage_duration" title="c/language/storage duration">storage duration</a> and <a href="scope" title="c/language/scope">block scope</a>. The layout of the parameters in memory (or if they are stored in memory at all) is unspecified: it is a part of the <a href="https://en.wikipedia.org/wiki/Calling_convention" class="extiw" title="enwiki:Calling convention">calling convention</a>.</p> +<div class="c source-c"><pre data-language="c">int main(int ac, char **av) +{ + ac = 2; // parameters are lvalues + av = (char *[]){"abc", "def", NULL}; + f(ac, av); +}</pre></div> <p>See <a href="operator_other#Function_call" title="c/language/operator other">function call operator</a> for other details on the mechanics of a function call and <a href="return" title="c/language/return">return</a> for returning from functions.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <h3 id="func"> __func__</h3> <p>Within every <span class="t-spar">function-body</span>, the special predefined variable <code>__func__</code> with block scope and static storage duration is available, as if defined immediately after the opening brace by</p> +<div class="c source-c"><pre data-language="c">static const char __func__[] = "function name";</pre></div> <p>This special identifier is sometimes used in combination with the <a href="../preprocessor/replace" title="c/preprocessor/replace">predefined macro constants</a> <code>__FILE__</code> and <code>__LINE__</code>, for example, by <code><a href="../error/assert" title="c/error/assert">assert</a></code>.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>The argument list must be explicitly present in the declarator, it cannot be inherited from a typedef</p> +<div class="c source-c"><pre data-language="c">typedef int p(int q, int r); // p is a function type int(int, int) +p f { return q + r; } // Error</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-until-c99"> +<td> <p>In C89, <span class="t-spar">specifiers-and-qualifiers</span> was optional, and if omitted, the return type of the function defaulted to <code>int</code> (possibly amended by the <span class="t-spar">declarator</span>).</p> +<p>In addition, old-style definition didn't require a declaration for every parameter in <span class="t-spar">declaration-list</span>. Any parameter whose declaration was missing had type <code>int</code></p> +<div class="c source-c"><pre data-language="c">max(a, b) // a and b have type int, return type is int +{ + return a>b?a:b; +}</pre></div> </td> <td><span class="t-mark-rev t-until-c99">(until C99)</span></td> +</tr> </table> <h3 id="Defect_reports"> Defect reports</h3> <p>The following behavior-changing defect reports were applied retroactively to previously published C standards.</p> +<table class="dsctable"> <tr> <th>DR </th> <th>Applied to </th> <th>Behavior as published </th> <th>Correct behavior </th> +</tr> <tr> <td> +<a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_423">DR 423</a> </td> <td>C89 </td> <td>the return type might be qualified </td> <td>the return type is implicitly disqualified </td> +</tr> +</table> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.9.1 Function definitions (p: 113-115) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.9.1 Function definitions (p: 156-158) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.9.1 Function definitions (p: 141-143) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.7.1 Function definitions </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/function#Function_definition" title="cpp/language/function">C++ documentation</a></span> for <span class=""><span>Function definition</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/function_definition" class="_attribution-link">https://en.cppreference.com/w/c/language/function_definition</a> + </p> +</div> diff --git a/devdocs/c/language%2Ffunctions.html b/devdocs/c/language%2Ffunctions.html new file mode 100644 index 00000000..23bdd021 --- /dev/null +++ b/devdocs/c/language%2Ffunctions.html @@ -0,0 +1,53 @@ + <h1 id="firstHeading" class="firstHeading">Functions</h1> <p>A function is a C language construct that associates a <a href="statements#Compound_statements" title="c/language/statements">compound statement</a> (the function body) with an <a href="identifier" title="c/language/identifier">identifier</a> (the function name). Every C program begins execution from the <a href="main_function" title="c/language/main function">main function</a>, which either terminates, or invokes other, user-defined or library functions.</p> +<div class="c source-c"><pre data-language="c">// function definition. +// defines a function with the name "sum" and with the body "{ return x+y; }" +int sum(int x, int y) +{ + return x + y; +}</pre></div> <p>A function is introduced by a <a href="function_declaration" title="c/language/function declaration">function declaration</a> or a <a href="function_definition" title="c/language/function definition">function definition</a>.</p> +<p>Functions may accept zero or more <i>parameters</i>, which are initialized from the <i>arguments</i> of a <a href="operator_other#Function_call" title="c/language/operator other">function call operator</a>, and may return a value to its caller by means of the <a href="return" title="c/language/return">return statement</a>.</p> +<div class="c source-c"><pre data-language="c">int n = sum(1, 2); // parameters x and y are initialized with the arguments 1 and 2</pre></div> <p>The body of a function is provided in a <a href="function_definition" title="c/language/function definition">function definition</a>. Each <span class="t-rev-inl t-since-c99"><span>non-<a href="inline" title="c/language/inline">inline</a></span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> function that is used in an expression (unless <a href="expressions#Unevaluated_expressions" title="c/language/expressions">unevaluated</a>) must be <a href="extern#One_definition_rule" title="c/language/extern">defined only once</a> in a program.</p> +<p>There are no nested functions (except where allowed through non-standard compiler extensions): each function definition must appear at file scope, and functions have no access to the local variables from the caller:</p> +<div class="c source-c"><pre data-language="c">int main(void) // the main function definition +{ + int sum(int, int); // function declaration (may appear at any scope) + int x = 1; // local variable in main + sum(1, 2); // function call + +// int sum(int a, int b) // error: no nested functions +// { +// return a + b; +// } +} +int sum(int a, int b) // function definition +{ +// return x + a + b; // error: main's x is not accessible within sum + return a + b; +}</pre></div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.7.6.3 Function declarators (including prototypes) (p: 96-98) </li> +<li> 6.9.1 Function definitions (p: 113-115) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.7.6.3 Function declarators (including prototypes) (p: 133-136) </li> +<li> 6.9.1 Function definitions (p: 156-158) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 6.7.5.3 Function declarators (including prototypes) (p: 118-121) </li> +<li> 6.9.1 Function definitions (p: 141-143) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 3.5.4.3 Function declarators (including prototypes) </li> +<li> 3.7.1 Function definitions </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/function" title="cpp/language/function">C++ documentation</a></span> for <span class=""><span>Declaring functions</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/functions" class="_attribution-link">https://en.cppreference.com/w/c/language/functions</a> + </p> +</div> diff --git a/devdocs/c/language%2Fgeneric.html b/devdocs/c/language%2Fgeneric.html new file mode 100644 index 00000000..670853f3 --- /dev/null +++ b/devdocs/c/language%2Fgeneric.html @@ -0,0 +1,62 @@ + <h1 id="firstHeading" class="firstHeading">Generic selection <span class="t-mark-rev t-since-c11">(since C11)</span> +</h1> <p>Provides a way to choose one of several expressions at compile time, based on a type of a controlling expression</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>_Generic</code> <code>(</code> <span class="t-spar">controlling-expression</span> <code>,</code> <span class="t-spar">association-list</span> <code>)</code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> +</tr> +</table> <p>where <span class="t-spar">association-list</span> is a comma-separated list of associations, each of which has the syntax</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">type-name</span> <code>:</code> <span class="t-spar">expression</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <code>default</code> <code>:</code> <span class="t-spar">expression</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">type-name</span> </td> <td> - </td> <td> any complete <a href="type" title="c/language/type">object type</a> that isn't variably-modified (that is, not VLA or pointer to VLA). </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">controlling-expression</span> </td> <td> - </td> <td> any expression (except for the <a href="operator_other#Comma_operator" title="c/language/operator other">comma operator</a>) whose type must be compatible with one of the <span class="t-spar">type-name</span>s if the <code>default</code> association is not used </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">expression</span> </td> <td> - </td> <td> any expression (except for the <a href="operator_other#Comma_operator" title="c/language/operator other">comma operator</a>) of any type and value category </td> +</tr> +</table> <p>No two <span class="t-spar">type-name</span>s in the <span class="t-spar">association-list</span> may specify <a href="type#Compatible_types" title="c/language/type">compatible types</a>. There may be only one association that uses the keyword <code>default</code>. If <code>default</code> is not used and none of the <span class="t-spar">type-name</span>s are compatible with the type of the controlling expression, the program will not compile.</p> +<h3 id="Explanation"> Explanation</h3> <p>First, the type of <span class="t-spar">controlling-expression</span> undergoes <a href="conversion#Lvalue_conversions" title="c/language/conversion">lvalue conversions</a>. The conversion is performed in type domain only: it discards the top-level cvr-qualifiers and atomicity and applies array-to-pointer/function-to-pointer transformations to the type of the controlling expression, without initiating any side-effects or calculating any values.</p> +<p>The type after conversion is compared with <span class="t-spar">type-name</span>s from the list of associations.</p> +<p>If the type is <a href="type#Compatible_types" title="c/language/type">compatible</a> with the <span class="t-spar">type-name</span> of one of the associations, then the type, value, and <a href="value_category" title="c/language/value category">value category</a> of the generic selection are the type, value, and value category of the <span class="t-spar">expression</span> that appears after the colon for that <span class="t-spar">type-name</span>.</p> +<p>If none of the <span class="t-spar">type-name</span>s are compatible with the type of the <span class="t-spar">controlling-expression</span>, and the <code>default</code> association is provided, then the type, value, and value category of the generic selection are the type, value, and value category of the expression after the <code>default :</code> label.</p> +<h3 id="Notes"> Notes</h3> <p>The <span class="t-spar">controlling-expression</span> and the <span class="t-spar">expression</span>s of the selections that are not chosen are never evaluated.</p> +<p>Because of the lvalue conversions, <code>"abc"</code> matches <code>char*</code> and not <code>char[4]</code> and <code>(int const){0}</code> matches <code>int</code>, and not <code>const int</code>.</p> +<p>All <a href="value_category" title="c/language/value category">value categories</a>, including function designators and void expressions, are allowed as <span class="t-spar">expression</span>s in a generic selection, and if selected, the generic selection itself has the same value category.</p> +<p>The <a href="../numeric/tgmath" title="c/numeric/tgmath">type-generic math macros</a> from <a href="../numeric/tgmath" title="c/numeric/tgmath"><code><tgmath.h></code></a>, introduced in C99, were implemented in compiler-specific manner. Generic selections, introduced in C11, gave the programmers the ability to write similar type-dependent code.</p> +<p>Generic selection is similar to overloading in C++ (where one of several functions is chosen at compile time based on the types of the arguments), except that it makes the selection between arbitrary expressions.</p> +<h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/_generic" title="c/keyword/ Generic"><code>_Generic</code></a>, <a href="../keyword/default" title="c/keyword/default"><code>default</code></a></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <math.h> +#include <stdio.h> + +// Possible implementation of the tgmath.h macro cbrt +#define cbrt(X) _Generic((X), \ + long double: cbrtl, \ + default: cbrt, \ + float: cbrtf \ + )(X) + +int main(void) +{ + double x = 8.0; + const float y = 3.375; + printf("cbrt(8.0) = %f\n", cbrt(x)); // selects the default cbrt + printf("cbrtf(3.375) = %f\n", cbrt(y)); // converts const float to float, + // then selects cbrtf +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">cbrt(8.0) = 2.000000 +cbrtf(3.375) = 1.500000</pre></div> </div> <h3 id="Defect_reports"> Defect reports</h3> <p>The following behavior-changing defect reports were applied retroactively to previously published C standards.</p> +<table class="dsctable"> <tr> <th>DR </th> <th>Applied to </th> <th>Behavior as published </th> <th>Correct behavior </th> +</tr> <tr> <td> +<a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_481">DR 481</a> </td> <td>C11 </td> <td>it was underspecified if the controlling expression undergoes lvalue conversions </td> <td>it undergoes </td> +</tr> +</table> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.5.1.1 Generic selection (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.5.1.1 Generic selection (p: 56-57) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.5.1.1 Generic selection (p: 78-79) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/templates" title="cpp/language/templates">C++ documentation</a></span> for <span class=""><span>Templates</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/generic" class="_attribution-link">https://en.cppreference.com/w/c/language/generic</a> + </p> +</div> diff --git a/devdocs/c/language%2Fgoto.html b/devdocs/c/language%2Fgoto.html new file mode 100644 index 00000000..ab3db583 --- /dev/null +++ b/devdocs/c/language%2Fgoto.html @@ -0,0 +1,64 @@ + <h1 id="firstHeading" class="firstHeading">goto statement</h1> <p>Transfers control unconditionally to the desired location.</p> +<p>Used when it is otherwise impossible to transfer control to the desired location using conventional constructs.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span> <code>goto</code> <span class="t-spar">label</span> <code>;</code> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">label</span> </td> <td> - </td> <td> target <a href="statements#Labels" title="c/language/statements">label</a> for the <code>goto</code> statement </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">attr-spec-seq</span> </td> <td> - </td> <td> <span class="t-mark-rev t-since-c23">(C23)</span>optional list of <a href="attributes" title="c/language/attributes">attributes</a>, applied to the <code>goto</code> statement </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>The <code>goto</code> statement causes an unconditional jump (transfer of control) to the statement prefixed by the named <span class="t-spar">label</span> (which must appear in the same function as the goto statement)<span class="t-rev-inl t-since-c99"><span>, except when this jump would enter the scope of a <a href="array" title="c/language/array">variable-length array</a> or another <a href="declarations" title="c/language/declarations">variably-modified type</a>.</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span></p> +<p>A <span class="t-spar">label</span> is an identifier followed by a colon (<code>:</code>)<span class="t-rev-inl t-until-c23"><span> and a statement</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span>. Labels are the only identifiers that have <i>function scope</i>: they can be used (in a goto statement) anywhere in the same function in which they appear. There may be multiple labels before any statement.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>Entering the scope of a non-variably modified variable is permitted:</p> +<div class="c source-c"><pre data-language="c">goto lab1; // OK: going into the scope of a regular variable + int n = 5; +lab1:; // Note, n is uninitialized, as if declared by int n; + +// goto lab2; // Error: going into the scope of two VM types + double a[n]; // a VLA + int (*p)[n]; // a VM pointer +lab2:</pre></div> <p>If <code>goto</code> leaves the scope of a VLA, it is deallocated (and may be reallocated if its initialization is executed again):</p> +<div class="c source-c"><pre data-language="c">{ + int n = 1; +label:; + int a[n]; // re-allocated 10 times, each with a different size + if (n++ < 10) goto label; // leaving the scope of a VM +}</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/goto" title="c/keyword/goto"><code>goto</code></a></p> +<h3 id="Notes"> Notes</h3> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>Because declarations are not statements, a label before a declaration must use a null statement (a semicolon immediately after the colon). Same applies to a label before the end of a block.</p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> </table> <p>C++ imposes additional limitations on the <code>goto</code> statement, but allows labels before declarations (which are statements in C++).</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +int main(void) +{ + // goto can be used to leave a multi-level loop easily + for (int x = 0; x < 3; x++) { + for (int y = 0; y < 3; y++) { + printf("(%d;%d)\n",x,y); + if (x + y >= 3) goto endloop; + } + } +endloop:; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">(0;0) +(0;1) +(0;2) +(1;0) +(1;1) +(1;2)</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.8.6.1 The goto statement (p: 110-111) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.8.6.1 The goto statement (p: 152-153) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.8.6.1 The goto statement (p: 137-138) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.6.6.1 The goto statement </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/goto" title="cpp/language/goto">C++ documentation</a></span> for <span class=""><span><code>goto</code> statement</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/goto" class="_attribution-link">https://en.cppreference.com/w/c/language/goto</a> + </p> +</div> diff --git a/devdocs/c/language%2Fhistory.html b/devdocs/c/language%2Fhistory.html new file mode 100644 index 00000000..62ab470b --- /dev/null +++ b/devdocs/c/language%2Fhistory.html @@ -0,0 +1,154 @@ + <h1 id="firstHeading" class="firstHeading">History of C</h1> <h2 id="Early_C"> Early C</h2> <ul> +<li> 1969: B created, based on BCPL, to replace PDP-7 assembler as the system programming language for Unix </li> +<ul><li> added operators <code>++</code>, <code>--</code>, compound assignment, remained a typeless language like BCPL </li></ul> +<li> 1971: NB ("new B") created when porting B to PDP-11 </li> +<ul><li> types (<code>int</code>, <code>char</code>, arrays and pointers), array-to-pointer conversion, compilation to machine code </li></ul> +<li> 1972: Language renamed to C </li> +<ul><li> <code>struct</code>, operators <code>&&</code> and <code>||</code>, preprocessor, portable I/O </li></ul> +<li> 1973: Unix re-written in C </li> +<ul><li> <code>unsigned</code>, <code>long</code>, <code>union</code>, enumerations, increased type safety </li></ul> +<li> 1978: The C Programming Language, 1st edition </li> +</ul> <h2 id="Standard_C"> Standard C</h2> <ul> +<li> 1983: ANSI established X3J11 committee </li> +<li> 1988: The C Programming Language, 2nd edition </li> +<li> 1989: <b>C89</b>, the ANSI C standard published </li> +</ul> <ol> +<li> codified existing practices </li> +<li> new features: <code>volatile</code>, <code>enum</code>, <code>signed</code>, <code>void</code>, locales </li> +<li> From C++: <code>const</code>, function prototypes </li> +</ol> <ul> +<li> 1990: <b>C90</b>, the ANSI C standard accepted as ISO/IEC 9899:1990 </li> +<li> 1994: Technical corrigendum 1 (ISO/IEC 9899:1990/Cor.1:1994) </li> +<ul><li> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/tc1.htm">44 small changes</a> </li></ul> +<li> 1995: <b>C95</b> (ISO/IEC 9899:1990/Amd.1:1995) (<a rel="nofollow" class="external text" href="https://infostore.saiglobal.com/store/Details.aspx?DocN=isoc000767513">online store</a>) </li> +</ul> <ol> +<li> greatly expanded wide and multibyte character support (<code><wctype.h></code>, <code><wchar.h></code>, additions and changes to stream I/O, etc) </li> +<li> digraphs, <code><iso646.h></code>, </li> +</ol> <ul> +<li> 1996: Technical corrigendum 2 (ISO/IEC 9899:1990/Cor.2:1996) </li> +<ul><li> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/tc2.htm">24 small changes</a> </li></ul> +<li> 1999: <b>C99</b> (ISO/IEC 9899:1999) </li> +</ul> <ol> +<li> new features: <code>bool</code>, <code>long long</code>, <code><stdint.h></code>, <code><inttypes.h></code>, <code>restrict</code>, compound literals, variable length arrays, flexible array members, designated initializers, <code><fenv.h></code>, variadic macros, complex numbers, <code>__func__</code>, hexadecimal floating point format (<code>%a</code>), monetary formatting in <code><a href="../locale/lconv" title="c/locale/lconv">lconv</a></code>, <code><a href="../string/byte/isblank" title="c/string/byte/isblank">isblank</a></code>, concatenation of narrow and wide string literals, trailing comma in enumerations, empty arguments in function-like macros, <code>STDC_*</code> pragmas, <code>va_copy</code>, null return of <code><a href="../io/tmpnam" title="c/io/tmpnam">tmpnam</a></code>, null pointer in <code><a href="../io/setvbuf" title="c/io/setvbuf">setvbuf</a></code>, <code>hh</code> and <code>ll</code> length-specifiers in <code><a href="../io/fprintf" title="c/io/fprintf">printf</a></code>, <code><a href="../io/fprintf" title="c/io/fprintf">snprintf</a></code>, <code><a href="../program/_exit" title="c/program/ Exit">_Exit</a></code>, <code><tgmath.h></code>, POSIX-like <code><a href="../chrono/strftime" title="c/chrono/strftime">strftime</a></code> specifiers </li> +<li> from C++: <code>inline</code>, mix declarations and code, declarations in the init-clause of the for loop, <code>//</code> comments, universal character names in source code </li> +<li> removed implicit functions and implicit <code>int</code> </li> +</ol> <ul> +<li> 2001: Technical corrigendum 1 (ISO/IEC 9899:1999/Cor.1:2001) </li> +<ul><li> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/9899tc1/.">11 defects fixed</a> </li></ul> +<li> 2004: Technical corrigendum 2 (ISO/IEC 9899:1999/Cor.2:2004) </li> +<li> 2004: Unicode TR (ISO/IEC TR 19769:2004) (<a rel="nofollow" class="external text" href="https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=33907">ISO store</a>) (<a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n1040.pdf">N1040</a> November 7, 2003 draft) </li> +<li> 2007: Technical corrigendum 3 (ISO/IEC 9899:1999/Cor.3:2007) (<a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n1256.pdf">N1256</a> September 7, 2007 draft) </li> +<ul><li> deprecated <code><a href="../io/gets" title="c/io/gets">gets</a></code> </li></ul> +<li> 2007: Bounds-checking interfaces TR (ISO/IEC TR 24731-1:2007) (<a rel="nofollow" class="external text" href="https://www.iso.org/iso/catalogue_detail.htm?csnumber=38841">ISO store</a>) (<a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n1225.pdf">N1225</a> March 28, 2007 draft) </li> +<li> 2008: Embedded TR (ISO/IEC TR 18037:2008) (<a rel="nofollow" class="external text" href="https://www.iso.org/iso/catalogue_detail.htm?csnumber=51126">ISO store</a>) (<a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n1021.pdf">N1021</a> September 24, 2003 draft) </li> +<li> 2009: Decimal floating-point TR (ISO/IEC TR 24732:2009) (<a rel="nofollow" class="external text" href="https://www.iso.org/iso/catalogue_detail.htm?csnumber=38842">ISO store</a>) (<a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n1241.pdf">N1241</a> July 5, 2007 draft) </li> +<li> 2009: Mathematical special functions TR (ISO/IEC TR 24747:2009) (<a rel="nofollow" class="external text" href="https://www.iso.org/iso/catalogue_detail.htm?csnumber=38857">ISO store</a>) (<a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n1182.pdf">N1182</a> August 2, 2006 draft) </li> +<li> 2010: Dynamic allocations functions TR (ISO/IEC TR 24731-2:2010) (<a rel="nofollow" class="external text" href="https://www.iso.org/iso/catalogue_detail.htm?csnumber=51678">ISO store</a>) (<a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n1388.pdf">N1388</a> June 1, 2009 draft) </li> +<li> 2011: <b>C11</b> (ISO/IEC 9899:2011) (<a rel="nofollow" class="external text" href="https://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=57853">ISO store</a>) (<a rel="nofollow" class="external text" href="https://webstore.ansi.org/RecordDetail.aspx?sku=INCITS%2fISO%2fIEC+9899-2012#.UGCvLIHyaHM">ANSI store</a>) (<a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n1570.pdf">N1570</a> April 12, 2011 draft) </li> +</ul> <ol> +<li> thread-aware memory model, <code><stdatomic.h></code>, <code><threads.h></code>, type-generic functions, <code>alignas</code>/<code>alignof</code>, <code>noreturn</code>, <code>static_assert</code>, analyzability extensions, extensions to complex and imaginary types, anonymous structures and unions, exclusive file open mode, <code><a href="../program/quick_exit" title="c/program/quick exit">quick_exit</a></code> </li> +<li> removed <code><a href="../io/gets" title="c/io/gets">gets</a></code> </li> +<li> from Bounds-checking interfaces TR: bounds-checking interfaces, </li> +<li> from Unicode TR: <code>char16_t</code>, <code>char32_t</code>, and <code><uchar.h></code> </li> +</ol> <ul> +<li> 2012: Technical corrigendum 1 (ISO/IEC 9899:2011/Cor 1:2012) (<a rel="nofollow" class="external text" href="https://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=61717">ISO store</a>) </li> +<ul><li> Fixes <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2244.htm#dr_411">DR 411</a> </li></ul> +<li> 2013: Secure Coding Rules TS (ISO/IEC TS 17961:2013) (<a rel="nofollow" class="external text" href="https://www.iso.org/iso/catalogue_detail.htm?csnumber=61134">ISO store</a>) (<a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n1718.pdf">N1718</a> May 30, 2013) </li> +<li> 2014: FP TS part 1: Binary floating-point arithmetic (ISO/IEC TS 18661-1:2014) (<a rel="nofollow" class="external text" href="https://www.iso.org/iso/catalogue_detail.htm?csnumber=63146">ISO store</a>) (<a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n1778.pdf">N1778</a> 2013 draft) </li> +</ul> <ol><li> provides changes to C11 (mostly to Annex F) that cover all basic requirements and some recommendations of IEC 60559:2011 (C11 was built on IEC 60559:1989) </li></ol> <ul><li> 2015: FP TS part 2: Decimal floating-point arithmetic (ISO/IEC TS 18661-2:2015) (<a rel="nofollow" class="external text" href="https://www.iso.org/iso/home/store/catalogue_ics/catalogue_detail_ics.htm?csnumber=68882">ISO store</a>) (<a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n1912.pdf">N1912</a> 2015 draft) </li></ul> <ol><li> provides changes to C11 to support all the requirements, plus some basic recommendations, of IEC 60559:2011 for decimal floating-point arithmetic. This supersedes ISO/IEC TR 24732:2009. </li></ol> <ul><li> 2015: FP TS part 3: Interchange and extended types (ISO/IEC TS 18661-3:2015) (<a rel="nofollow" class="external text" href="https://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=65615">ISO store</a>) (<a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n1945.pdf">N1945</a> 2015 draft) </li></ul> <ol><li> provides changes to C11 to support the recommendations of IEC 60559:2011 for extended floating‐point formats and the interchange formats, both arithmetic and non-arithmetic. </li></ol> <ul><li> 2015: FP TS part 4: Supplementary functions (ISO/IEC TS 18661-4:2015) (<a rel="nofollow" class="external text" href="https://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=65616">ISO store</a>) (<a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n1950.pdf">N1950</a> 2015 draft) </li></ul> <ol><li> provides changes to C11 to support all mathematical operations recommended by IEC 60559:2011, including trigonometry in π units, inverse square root, compounded interest, etc. </li></ol> <ul><li> 2016: FP TS part 5: Supplementary attributes (ISO/IEC TS 18661-5:2016) (<a rel="nofollow" class="external text" href="https://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=65617">ISO store</a>) (<a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2004.pdf">N2004</a> 2016 draft) </li></ul> <ol><li> provides changes to C11 to support all supplementary attributes (evaluation model, exception handling, reproducibility, etc) recommended by IEC 60559:2011 </li></ol> <ul><li> 2018: <b>C17</b> (ISO/IEC 9899:2018) (<a rel="nofollow" class="external text" href="https://www.iso.org/standard/74528.html">ISO Store</a>) (<a rel="nofollow" class="external text" href="https://files.lhmouse.com/standards/ISO%20C%20N2176.pdf">Final draft</a>) </li></ul> <a href="../17" title="c/17">Main Article: C17</a> <div style="margin-left:0px"> <table class="mw-collapsible mw-collapsed"> <tr> <th>Defect Reports fixed in C17 (54 defects) </th> +</tr> <tr> <td> <ul> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_400">DR 400</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_401">DR 401</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_402">DR 402</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_403">DR 403</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_404">DR 404</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_405">DR 405</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_406">DR 406</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_407">DR 407</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_410">DR 410</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_412">DR 412</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_414">DR 414</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_415">DR 415</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_416">DR 416</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_417">DR 417</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_419">DR 419</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_423">DR 423</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_426">DR 426</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_428">DR 428</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_429">DR 429</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_430">DR 430</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_431">DR 431</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_433">DR 433</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_434">DR 434</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_436">DR 436</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_437">DR 437</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_438">DR 438</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_439">DR 439</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_441">DR 441</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_444">DR 444</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_445">DR 445</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_447">DR 447</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_448">DR 448</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_450">DR 450</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_452">DR 452</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_453">DR 453</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_457">DR 457</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_458">DR 458</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_459">DR 459</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_460">DR 460</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_462">DR 462</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_464">DR 464</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_465">DR 465</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_468">DR 468</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_470">DR 470</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_471">DR 471</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_472">DR 472</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_473">DR 473</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_475">DR 475</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_477">DR 477</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_480">DR 480</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_481">DR 481</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_485">DR 485</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_487">DR 487</a> </li> +<li> <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2244.htm#dr_491">DR 491</a> </li> +</ul> </td> +</tr> +</table> +</div> <h3 id="Future_development"> Future development</h3> <ul> +<li> Parallelism TS (Draft <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2017.pdf">N2017</a> 2016-03-10) </li> +<li> Transactional Memory TS (Draft <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n1961.pdf">N1961</a> 2015-09-23) </li> +<li> <b>C23</b> (Latest draft <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n3096.pdf">n3096</a> 2023-04-01) </li> +</ul> <ol><li> List of issues that were not granted DR status: (<a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2556.pdf">N2556</a> 2020-08-02) </li></ol> <dl> +<dd> +<a href="../23" title="c/23">Main Article: C23</a> </dd> +<dd>Next major C language standard revision </dd> +</dl> <div style="margin-left:0px"> <table class="mw-collapsible mw-collapsed"> <tr> <th>Defect Reports fixed in C23 (? defects) </th> +</tr> <tr> <td> <ul> +<li> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2379.htm">DR 440</a> </li> +<li> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2326.htm">DR 432</a> </li> +<li> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2326.htm">DR 467</a> </li> +<li> <a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_476">DR 476</a> </li> +<li> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2324.htm">DR 482</a> </li> +<li> <a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_488">DR 488</a> </li> +<li> <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2713.htm">DR 489</a> </li> +<li> <a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_494">DR 494</a> </li> +<li> <a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_496">DR 496</a> </li> +<li> <a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_497">DR 497</a> </li> +<li> <a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_499">DR 499</a> </li> +<li> <a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_500">DR 500</a> </li> +<li> <a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_501">DR 501</a> </li> +</ul> </td> +</tr> +</table> +</div> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/history" title="cpp/language/history">C++ documentation</a></span> for <span class=""><span>History of C++</span></span> </td> +</tr> </table> <h3 id="External_links"> External links</h3> <table> <tr style="vertical-align:top;"> <td>1. </td> <td> +<a rel="nofollow" class="external text" href="https://www.bell-labs.com/usr/dmr/www/chist.html">The Development of the C Language</a> by Dennis M. Ritchie </td> +</tr> <tr style="vertical-align:top;"> <td>2. </td> <td> +<a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/C99RationaleV5.10.pdf">Rationale for the C99 standard</a> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/history" class="_attribution-link">https://en.cppreference.com/w/c/language/history</a> + </p> +</div> diff --git a/devdocs/c/language%2Fidentifier.html b/devdocs/c/language%2Fidentifier.html new file mode 100644 index 00000000..16963e77 --- /dev/null +++ b/devdocs/c/language%2Fidentifier.html @@ -0,0 +1,142 @@ + <h1 id="firstHeading" class="firstHeading">Identifier</h1> <p>An <i>identifier</i> is an arbitrarily long sequence of digits, underscores, lowercase and uppercase Latin letters<span class="t-rev-inl t-since-c99"><span>, and Unicode characters specified using <code>\u</code> and <code>\U</code> <a href="escape" title="c/language/escape">escape</a> notation</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span><span class="t-rev-inl t-since-c23"><span>, of class <a rel="nofollow" class="external text" href="https://www.unicode.org/reports/tr31/#Table_Lexical_Classes_for_Identifiers">XID_Continue</a></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>. A valid identifier must begin with a non-digit character (Latin letter, underscore<span class="t-rev-inl t-since-c99 t-until-c23"><span>, or Unicode non-digit character</span><span><span class="t-mark-rev t-since-c99">(since C99)</span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span>, or Unicode character of class <a rel="nofollow" class="external text" href="https://www.unicode.org/reports/tr31/#Table_Lexical_Classes_for_Identifiers">XID_Start</a>)</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>). Identifiers are case-sensitive (lowercase and uppercase letters are distinct). <span class="t-rev-inl t-since-c23"><span>Every identifier must conform to <a rel="nofollow" class="external text" href="https://www.unicode.org/charts/normalization/">Normalization Form C</a>.</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span></p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99 t-until-c23"> +<td>It is implementation-defined if raw (not escaped) Unicode characters are allowed in identifiers: <div class="c source-c"><pre data-language="c">char *\U0001f431 = "cat"; // supported +char *🐱 = "cat"; // implementation-defined + // (e.g. works with Clang, but not GCC prior to version 10) + // both are ill formed in C23. Emoji are not XID_Start characters</pre></div> </td> <td> +<span class="t-mark-rev t-since-c99">(since C99)</span><br><span class="t-mark-rev t-until-c23">(until C23)</span> +</td> +</tr> <tr class="t-rev t-since-c23"> +<td>Implementation-defined characters whose corresponding code points in <a rel="nofollow" class="external text" href="https://unicode.org/L2/L2010/10038-fcd10646-main.pdf">ISO/IEC 10646</a> (Unicode) have the XID_Start or XID_Continue property can appear in the beginning or after the first character of an identifier respectively.</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <p>Identifiers can denote the following types of entities:</p> +<ul> +<li> <a href="object" title="c/language/object">objects</a> </li> +<li> <a href="functions" title="c/language/functions">functions</a> </li> +<li> tags (<a href="struct" title="c/language/struct">struct</a>, <a href="union" title="c/language/union">union</a>, or <a href="enum" title="c/language/enum">enumerations</a>) </li> +<li> structure or union members </li> +<li> enumeration constants </li> +<li> <a href="typedef" title="c/language/typedef">typedef</a> names </li> +<li> <a href="statements#Labels" title="c/language/statements">label</a> names </li> +<li> <a href="../preprocessor/replace" title="c/preprocessor/replace">macro</a> names </li> +<li> <a href="../preprocessor/replace" title="c/preprocessor/replace">macro parameter</a> names </li> +</ul> <p>Every identifier other than macro names or macro parameter names has <a href="scope" title="c/language/scope">scope</a>, belongs to a <a href="name_space" title="c/language/name space">name space</a>, and may have <a href="storage_duration" title="c/language/storage duration">linkage</a>. The same identifier can denote different entities at different points in the program, or may denote different entities at the same point if the entities are in different name spaces.</p> +<h3 id="Reserved_identifiers"> Reserved identifiers</h3> <p>The following identifiers are <i>reserved</i> and may not be declared in a program (doing so invokes undefined behavior):</p> +<ol> <li>The identifiers that are <a href="../keyword" title="c/keyword">keywords</a> cannot be used for other purposes. In particular #define or #undef of an identifier that is identical to a keyword is not allowed.</li> <li>All external identifiers that begin with an underscore.</li> <li>All identifiers that begin with an underscore followed by a capital letter or by another underscore (these reserved identifiers allow the library to use numerous behind-the-scenes non-external macros and functions).</li> <li>All external identifiers defined by the standard library (in hosted environment). This means that no user-supplied external names are allowed to match any library names, not even if declaring a function that is identical to a library function.</li> <li>Identifiers declared as reserved for the implementation or future use by the standard library (see below).</li> <li class="t-rev-inl t-rev-inl-noborder t-since-c23"> +<span>Identifiers declared as potentially reserved and provided by the implementation (see below).</span> <span class="t-mark-rev t-since-c23">(since C23)</span> +</li> </ol> <p>All other identifiers are available. Identifiers that are not reserved <span class="t-rev-inl t-since-c23"><span>or potentially reserved</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> can be used with no fear of unexpected collisions when moving programs from one compiler and library to another.</p> +<p>Note: in C++, identifiers with a double underscore anywhere are reserved everywhere; in C, only the ones that begin with a double underscore are reserved.</p> +<h4 id="Reserved_and_potentially_reserved_identifiers_in_the_library"> Reserved and potentially reserved identifiers in the library</h4> <p>The standard library reserves every identifier it provides. Reserved identifiers that have <a href="storage_duration" title="c/language/storage duration">external linkage</a> (e.g. name of every standard function) are reserved regardless which header is included. Other reserved identifiers are reserved when any of its associated headers is included.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>Potentially reserved identifiers are intended to be used by the implementation and future revision of standard. If a potentially reserved identifier is provided by the implementation, it becomes reserved.</p> +<p>Implementations are only allowed to provide <a href="extern" title="c/language/extern">external definitions</a> of potentially reserved identifiers that are reserved as function names.</p> +<p>Potentially reserved identifiers that are not provided by the implementation are not reserved. They can be declared or defined by the user without undefined behavior. However, such usage is not portable.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <p>Following identifiers are reserved <span class="t-rev-inl t-since-c23"><span>or potentially reserved</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> for the implementation or future use by the standard library.</p> +<ul> <li> +<i>function names</i><span class="t-rev-inl t-since-c23"><span>, all of which are potentially reserved</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> <ul> <li class="t-rev-inl t-rev-inl-noborder t-since-c99"> +<span><code>cerf</code>, <code>cerfc</code>, <code>cexp2</code>, <code>cexpm1</code>, <code>clog10</code>, <code>clog1p</code>, <code>clog2</code>, <code>clgamma</code>, <code>ctgamma</code><span class="t-rev-inl t-since-c23"><span>, <code>csinpi</code>, <code>ccospi</code>, <code>ctanpi</code>, <code>casinpi</code>, <code>cacospi</code>, <code>catanpi</code>, <code>ccompoundn</code>, <code>cpown</code>, <code>cpowr</code>, <code>crootn</code>, <code>crsqrt</code>, <code>cexp10m1</code>, <code>cexp10</code>, <code>cexp2m1</code>, <code>clog10p1</code>, <code>clog2p1</code>, <code>clogp1</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> and their -f and -l suffixed variants, in <a href="../numeric/complex" title="c/numeric/complex"><code><complex.h></code></a></span> <span class="t-mark-rev t-since-c99">(since C99)</span> +</li> <li>beginning with <code>is</code> or <code>to</code> followed by a lowercase letter, in <a href="../string/byte" title="c/string/byte"><code><ctype.h></code></a><span class="t-rev-inl t-since-c95"><span> and <a href="../string/wide" title="c/string/wide"><code><wctype.h></code></a></span><span><span class="t-mark-rev t-since-c95">(since C95)</span></span></span> +</li> <li>beginning with <code>str</code> <span class="t-rev-inl t-since-c23"><span>or <code>wcs</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> followed by a lowercase letter, in <a href="../string/byte" title="c/string/byte"><code><stdlib.h></code></a> <span class="t-rev-inl t-since-c23"><span>and <a href="../types/integer" title="c/types/integer"><code><inttypes.h></code></a></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> +</li> <li class="t-rev-inl t-rev-inl-noborder t-since-c23"> +<span>beginning with <code>cr_</code>, in <a href="../numeric/math" title="c/numeric/math"><code><math.h></code></a></span> <span class="t-mark-rev t-since-c23">(since C23)</span> +</li> <li class="t-rev-inl t-rev-inl-noborder t-since-c95"> +<span>beginning with <code>wcs</code> followed by a lowercase letter, in <a href="../string/wide" title="c/string/wide"><code><wchar.h></code></a></span> <span class="t-mark-rev t-since-c95">(since C95)</span> +</li> <li class="t-rev-inl t-rev-inl-noborder t-since-c11"> +<span>beginning with <code>atomic_</code> followed by a lowercase letter, in <a href="../thread" title="c/thread"><code><stdatomic.h></code></a></span> <span class="t-mark-rev t-since-c11">(since C11)</span> +</li> <li class="t-rev-inl t-rev-inl-noborder t-since-c11"> +<span>beginning with <code>cnd_</code>, <code>mtx_</code>, <code>thrd_</code> or <code>tss_</code> followed by a lowercase letter, in <a href="../thread" title="c/thread"><code><threads.h></code></a></span> <span class="t-mark-rev t-since-c11">(since C11)</span> +</li> </ul> </li> <li> +<i>typedef names</i><span class="t-rev-inl t-since-c23"><span>, all of which are potentially reserved</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> <ul> <li class="t-rev-inl t-rev-inl-noborder t-since-c99"> +<span>beginning with <code>int</code> or <code>uint</code> and ending with <code>_t</code>, in <a href="../types/integer" title="c/types/integer"><code><stdint.h></code></a></span> <span class="t-mark-rev t-since-c99">(since C99)</span> +</li> <li class="t-rev-inl t-rev-inl-noborder t-since-c11"> +<span>beginning with <code>atomic_</code> or <code>memory_</code> followed by a lowercase letter, in <a href="../thread" title="c/thread"><code><stdatomic.h></code></a></span> <span class="t-mark-rev t-since-c11">(since C11)</span> +</li> <li class="t-rev-inl t-rev-inl-noborder t-since-c11"> +<span>beginning with <code>cnd_</code>, <code>mtx_</code>, <code>thrd_</code> or <code>tss_</code> followed by a lowercase letter, in <a href="../thread" title="c/thread"><code><threads.h></code></a></span> <span class="t-mark-rev t-since-c11">(since C11)</span> +</li> </ul> </li> <li> +<i>macro names</i> <ul> <li>beginning with <code>E</code> followed by a digit or an uppercase letter, in <a href="../error/errno_macros" title="c/error/errno macros"><code><errno.h></code></a> +</li> <li class="t-rev-inl t-rev-inl-noborder t-since-c99"> +<span>beginning with <code>FE_</code> followed by an uppercase letter, in <a href="../numeric/fenv" title="c/numeric/fenv"><code><fenv.h></code></a></span> <span class="t-mark-rev t-since-c99">(since C99)</span> +</li> <li class="t-rev-inl t-rev-inl-noborder t-since-c23"> +<span>beginning with <code>DBL_</code>, <code>DEC32_</code>, <code>DEC64_</code>, <code>DEC128_</code>, <code>DEC_</code>, <code>FLT_</code>, or <code>LDBL_</code> followed by an uppercase letter, in <a href="../types/limits" title="c/types/limits"><code><float.h></code></a>; these identifiers are potentially reserved</span> <span class="t-mark-rev t-since-c23">(since C23)</span> +</li> <li class="t-rev-inl t-rev-inl-noborder t-since-c99"> +<span>beginning with <code>INT</code> or <code>UINT</code> and ending with <code>_MAX</code>, <code>_MIN</code><span class="t-rev-inl t-since-c23"><span>, <code>_WIDTH</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, or <code>_C</code>, in <a href="../types/integer" title="c/types/integer"><code><stdint.h></code></a><span class="t-rev-inl t-since-c23"><span>; these identifiers are potentially reserved</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span></span> <span class="t-mark-rev t-since-c99">(since C99)</span> +</li> <li class="t-rev-inl t-rev-inl-noborder t-since-c99"> +<span>beginning with <code>PRI</code> or <code>SCN</code> followed by lowercase letter or the letter <code>X</code>, in <a href="../types/integer" title="c/types/integer"><code><inttypes.h></code></a><span class="t-rev-inl t-since-c23"><span>; these identifiers are potentially reserved</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span></span> <span class="t-mark-rev t-since-c99">(since C99)</span> +</li> <li>beginning with <code>LC_</code> followed by an uppercase letter, in <a href="../locale/lc_categories" title="c/locale/LC categories"><code><locale.h></code></a> +</li> <li class="t-rev-inl t-rev-inl-noborder t-since-c23"> +<span>beginning with <code>FP_</code> followed by an uppercase letter, in <a href="../numeric/math" title="c/numeric/math"><code><math.h></code></a></span> <span class="t-mark-rev t-since-c23">(since C23)</span> +</li> <li class="t-rev-inl t-rev-inl-noborder t-since-c23"> +<span>beginning with <code>MATH_</code> followed by an uppercase letter, in <a href="../numeric/math" title="c/numeric/math"><code><math.h></code></a>; these identifiers are potentially reserved</span> <span class="t-mark-rev t-since-c23">(since C23)</span> +</li> <li>beginning with <code>SIG</code> or <code>SIG_</code> followed by an uppercase letter, in <a href="../program" title="c/program"><code><signal.h></code></a> +</li> <li class="t-rev-inl t-rev-inl-noborder t-since-c11"> +<span>beginning with <code>TIME_</code> followed by an uppercase letter, in <a href="../chrono/timespec_get" title="c/chrono/timespec get"><code><time.h></code></a></span> <span class="t-mark-rev t-since-c11">(since C11)</span> +</li> <li class="t-rev-inl t-rev-inl-noborder t-since-c11"> +<span>beginning with <code>ATOMIC_</code> followed by an uppercase letter, in <a href="../thread" title="c/thread"><code><stdatomic.h></code></a><span class="t-rev-inl t-since-c23"><span>; these identifiers are potentially reserved</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span></span> <span class="t-mark-rev t-since-c11">(since C11)</span> +</li> </ul> </li> <li> +<i>enumeration constants</i><span class="t-rev-inl t-since-c23"><span>, all of which are potentially reserved</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> <ul> <li class="t-rev-inl t-rev-inl-noborder t-since-c11"> +<span>beginning with <code>memory_order_</code> followed by a lowercase letter, in <a href="../thread" title="c/thread"><code><stdatomic.h></code></a></span> <span class="t-mark-rev t-since-c11">(since C11)</span> +</li> <li class="t-rev-inl t-rev-inl-noborder t-since-c11"> +<span>beginning with <code>cnd_</code>, <code>mtx_</code>, <code>thrd_</code> or <code>tss_</code> followed by a lowercase letter, in <a href="../thread" title="c/thread"><code><threads.h></code></a></span> <span class="t-mark-rev t-since-c11">(since C11)</span> +</li> </ul> </li> </ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>Implementations are recommended to warn when on declaration or definition of potentially reserved identifiers, except when</p> +<ul> +<li> the declaration is a non-definition declaration of an identifier with external linkage provided by the implementation, and </li> +<li> the type used in the declaration is <a href="types#Compatible_types" title="c/language/types" class="mw-redirect">compatible</a> with that used in the definition. </li> +</ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Translation_limits"> Translation limits</h3> <p>Even though there is no specific limit on the length of identifiers, early compilers had limits on the number of significant initial characters in identifiers and the linkers imposed stricter limits on the names with <a href="storage_duration" title="c/language/storage duration">external linkage</a>. C requires that at least the following limits are supported by any standard-compliant implementation:</p> +<table class="t-rev-begin"> <tr class="t-rev t-until-c99"> +<td> <ul> +<li>31 significant initial characters in an internal identifier or a macro name </li> +<li>6 significant initial characters in an external identifier </li> +<li>511 external identifiers in one translation unit </li> +<li>127 identifiers with block scope declared in one block </li> +<li>1024 macro identifiers simultaneously defined in one preprocessing translation unit </li> +</ul> </td> <td><span class="t-mark-rev t-until-c99">(until C99)</span></td> +</tr> <tr class="t-rev t-since-c99"> +<td> <ul> +<li>63 significant initial characters in an internal identifier or a macro name </li> +<li>31 significant initial characters in an external identifier </li> +<li>4095 external identifiers in one translation unit </li> +<li>511 identifiers with block scope declared in one block </li> +<li>4095 macro identifiers simultaneously defined in one preprocessing translation unit </li> +</ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 5.2.4.1 Translation limits (p: 19-20) </li> +<li> 6.4.2 Identifiers (p: 43) </li> +<li> 6.10.8 Predefined macro names (p: 127-129) </li> +<li> 6.11.9 Predefined macro names (p: 130) </li> +<li> 7.31 Future library directions (p: 332-333) </li> +<li> K.3.1.2 Reserved identifiers (p: 425) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 5.2.4.1 Translation limits (p: 25-26) </li> +<li> 6.4.2 Identifiers (p: 59-60) </li> +<li> 6.10.8 Predefined macro names (p: 175-176) </li> +<li> 6.11.9 Predefined macro names (p: 179) </li> +<li> 7.31 Future library directions (p: 455-457) </li> +<li> K.3.1.2 Reserved identifiers (p: 584) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 5.2.4.1 Translation limits (p: 20-21) </li> +<li> 6.4.2 Identifiers (p: 51-52) </li> +<li> 6.10.8 Predefined macro names (p: 160-161) </li> +<li> 6.11.9 Predefined macro names (p: 163) </li> +<li> 7.26 Future library directions (p: 401-402) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 2.2.4.1 Translation limits </li> +<li> 3.1.2 Identifiers </li> +<li> 3.8.8 Predefined macro names </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/identifiers" title="cpp/language/identifiers">C++ documentation</a></span> for <span class=""><span>Identifiers</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/identifier" class="_attribution-link">https://en.cppreference.com/w/c/language/identifier</a> + </p> +</div> diff --git a/devdocs/c/language%2Fif.html b/devdocs/c/language%2Fif.html new file mode 100644 index 00000000..b273c4e8 --- /dev/null +++ b/devdocs/c/language%2Fif.html @@ -0,0 +1,65 @@ + <h1 id="firstHeading" class="firstHeading">if statement</h1> <p>Conditionally executes code.</p> +<p>Used where code needs to be executed only if some condition is true.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span> <code>if (</code> <span class="t-spar">expression</span> <code>)</code> <span class="t-spar">statement-true</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span> <code>if (</code> <span class="t-spar">expression</span> <code>)</code> <span class="t-spar">statement-true</span> <code>else</code> <span class="t-spar">statement-false</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">attr-spec-seq</span> </td> <td> - </td> <td> <span class="t-mark-rev t-since-c23">(C23)</span>optional list of <a href="attributes" title="c/language/attributes">attributes</a>, applied to the <code>if</code> statement </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">expression</span> </td> <td> - </td> <td> an <a href="expressions" title="c/language/expressions">expression</a> of any scalar type </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">statement-true</span> </td> <td> - </td> <td> any <a href="statements" title="c/language/statements">statement</a> (often a compound statement), which is executed if <span class="t-spar">expression</span> compares not equal to <code>0</code> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">statement-false</span> </td> <td> - </td> <td> any <a href="statements" title="c/language/statements">statement</a> (often a compound statement), which is executed if <span class="t-spar">expression</span> compares equal to <code>0</code> </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p><span class="t-spar">expression</span> must be an expression of any <a href="type#Type_groups" title="c/language/type">scalar type</a>.</p> +<p>If <span class="t-spar">expression</span> compares not equal to the integer zero, <span class="t-spar">statement-true</span> is executed.</p> +<p>In the form <span class="t-v">(2)</span>, if <span class="t-spar">expression</span> compares equal to the integer zero, <span class="t-spar">statement_false</span> is executed.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>As with all other selection and iteration statements, the entire if-statement has its own block scope:</p> +<div class="c source-c"><pre data-language="c">enum {a, b}; +int different(void) +{ + if (sizeof(enum {b, a}) != sizeof(int)) + return a; // a == 1 + return b; // b == 0 in C89, b == 1 in C99 +}</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>The <code>else</code> is always associated with the closest preceding <code>if</code> (in other words, if <span class="t-spar">statement-true</span> is also an if statement, then that inner if statement must contain an <code>else</code> part as well):</p> +<div class="c source-c"><pre data-language="c">int j = 1; +if (i > 1) + if(j > 2) + printf("%d > 1 and %d > 2\n", i, j); + else // this else is part of if(j>2), not part of if(i>1) + printf("%d > 1 and %d <= 2\n", i, j);</pre></div> <p>If <span class="t-spar">statement-true</span> is entered through a <a href="goto" title="c/language/goto">goto</a>, <span class="t-spar">statement-false</span> is not executed.</p> +<h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/if" title="c/keyword/if"><code>if</code></a>, <a href="../keyword/else" title="c/keyword/else"><code>else</code></a></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +int main(void) +{ + int i = 2; + if (i > 2) { + printf("first is true\n"); + } else { + printf("first is false\n"); + } + + i = 3; + if (i == 3) printf("i == 3\n"); + + if (i != 3) printf("i != 3 is true\n"); + else printf("i != 3 is false\n"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">first is false +i == 3 +i != 3 is false</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.8.4.1 The if statement (p: 108-109) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.8.4.1 The if statement (p: 148-149) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.8.4.1 The if statement (p: 133-134) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.6.4.1 The if statement </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/if" title="cpp/language/if">C++ documentation</a></span> for <span class=""><span><code>if</code> statement</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/if" class="_attribution-link">https://en.cppreference.com/w/c/language/if</a> + </p> +</div> diff --git a/devdocs/c/language%2Finitialization.html b/devdocs/c/language%2Finitialization.html new file mode 100644 index 00000000..7cacdb5b --- /dev/null +++ b/devdocs/c/language%2Finitialization.html @@ -0,0 +1,89 @@ + <h1 id="firstHeading" class="firstHeading">Initialization</h1> <p>A <a href="declarations" title="c/language/declarations">declaration</a> of an object may provide its initial value through the process known as <i>initialization</i>.</p> +<p>For each <a href="declarations" title="c/language/declarations">declarator</a>, the initializer, if not omitted, may be one of the following:</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>=</code> <span class="t-spar">expression</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>=</code> <code>{</code> <span class="t-spar">initializer-list</span> <code>}</code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>=</code> <code>{</code> <code>}</code> </td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <p>where <span class="t-spar">initializer-list</span> is a non-empty comma-separated list of <span class="t-spar">initializer</span> s (with an optional trailing comma), where each initializer has one of three possible forms:</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="t-spar">expression</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>{</code> <span class="t-spar">initializer-list</span> <code>}</code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>{</code> <code>}</code> </td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">designator-list</span> <code>=</code> <span class="t-spar">initializer</span> </td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> +</tr> +</table> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>where <span class="t-spar">designator-list</span> is a list of either array designators of the form <code>[</code> <span class="t-spar">constant-expression</span> <code>]</code> or struct/union member designators of the form <code>.</code> <span class="t-spar">identifier</span> ; see <a href="array_initialization" title="c/language/array initialization">array initialization</a> and <a href="struct_initialization" title="c/language/struct initialization">struct initialization</a>.</p> +<p>Note: besides initializers, brace-enclosed <span class="t-spar">initializer-list</span> may appear in <a href="compound_literal" title="c/language/compound literal">compound literals</a>, which are expressions of the form:</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>(</code> <span class="t-spar">type</span> <code>)</code> <code>{</code> <span class="t-spar">initializer-list</span> <code>}</code> </td> <td class="t-sdsc-nopad"> </td> <td> </td> +</tr> <tr class="t-sdsc"> <td> <code>(</code> <span class="t-spar">type</span> <code>)</code> <code>{</code> <code>}</code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Explanation"> Explanation</h3> <p>The initializer specifies the initial value stored in an object.</p> +<h4 id="Explicit_initialization"> Explicit initialization</h4> <p>If an initializer is provided, see</p> +<ul> +<li> <a href="scalar_initialization" title="c/language/scalar initialization">scalar initialization</a> for the initialization of scalar types </li> +<li> <a href="array_initialization" title="c/language/array initialization">array initialization</a> for the initialization of array types </li> +<li> <a href="struct_initialization" title="c/language/struct initialization">struct initialization</a> for the initialization of struct and union types. </li> +</ul> <h4 id="Implicit_initialization"> Implicit initialization</h4> <p>If an initializer is not provided:</p> +<ul> +<li> objects with automatic <a href="storage_duration" title="c/language/storage duration">storage duration</a> are initialized to indeterminate values (which may be <a href="object" title="c/language/object">trap representations</a>) </li> +<li> objects with static and thread-local <a href="storage_duration" title="c/language/storage duration">storage duration</a> are empty-initialized </li> +</ul> <h4 id="Empty_initialization"> Empty initialization</h4> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>An object is empty-initialized if it is explicitly initialized from initializer <code>= {}</code>.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <p>In some cases, an object is empty-initialized if it is not initialized explicitly, that is:</p> +<ul> +<li> pointers are initialized to null pointer values of their types </li> +<li> objects of integral types are initialized to unsigned zero </li> +<li> objects of floating types are initialized to positive zero </li> +<li> all elements of arrays, all members of structs, and the first members of unions are empty-initialized, recursively, plus all padding bits are initialized to zero </li> +</ul> (on platforms where null pointer values and floating zeroes have all-bit-zero representations, this form of initialization for statics is normally implemented by allocating them in the .bss section of the program image) <h3 id="Notes"> Notes</h3> <p>When initializing an object of static or thread-local <a href="storage_duration" title="c/language/storage duration">storage duration</a>, every <span class="t-spar">expression</span> in the initializer must be a <a href="constant_expression" title="c/language/constant expression">constant expression</a> or <a href="string_literal" title="c/language/string literal">string literal</a>.</p> +<p>Initializers cannot be used in declarations of objects of incomplete type, VLAs, and block-scope objects with linkage.</p> +<p>The initial values of function parameters are established as if by assignment from the arguments of a <a href="operator_other#Function_call" title="c/language/operator other">function call</a>, rather than by initialization.</p> +<p>If an indeterminate value is used as an argument to any standard library call, the behavior is undefined. Otherwise, the result of any expression involving indeterminate values is an indeterminate value (e.g. <code>int n;</code>, <code>n</code> may not compare equal to itself and it may appear to change its value on subsequent reads)</p> +<table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>There is no special construct in C corresponding to <a href="https://en.cppreference.com/w/cpp/language/value_initialization" title="cpp/language/value initialization">value initialization</a> in C++; however, <code>= {0}</code><span class="t-rev-inl t-since-c99"><span> (or <code>(T){0}</code> in compound literals)</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> can be used instead, as the C standard does not allow empty structs, empty unions, or arrays of zero length.</p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td> <p>The empty initializer <code>= {}</code> (or <code>(T){}</code> in compound literals) can be used to achieve the same semantics as <a href="https://en.cppreference.com/w/cpp/language/value_initialization" title="cpp/language/value initialization">value initialization</a> in C++.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdlib.h> +int a[2]; // initializes a to {0, 0} +int main(void) +{ + int i; // initializes i to an indeterminate value + static int j; // initializes j to 0 + int k = 1; // initializes k to 1 + + // initializes int x[3] to 1,3,5 + // initializes int* p to &x[0] + int x[] = { 1, 3, 5 }, *p = x; + + // initializes w (an array of two structs) to + // { { {1,0,0}, 0}, { {2,0,0}, 0} } + struct {int a[3], b;} w[] = {[0].a = {1}, [1].a[0] = 2}; + + // function call expression can be used for a local variable + char* ptr = malloc(10); + free(ptr); + +// Error: objects with static storage duration require constant initializers +// static char* ptr = malloc(10); + +// Error: VLA cannot be initialized +// int vla[n] = {0}; +}</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.7.9 Initialization (p: 100-105) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.7.9 Initialization (p: 139-144) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.7.8 Initialization (p: 125-130) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 6.5.7 Initialization </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/initialization" title="cpp/language/initialization">C++ documentation</a></span> for <span class=""><span>Initialization</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/initialization" class="_attribution-link">https://en.cppreference.com/w/c/language/initialization</a> + </p> +</div> diff --git a/devdocs/c/language%2Finline.html b/devdocs/c/language%2Finline.html new file mode 100644 index 00000000..b5413a96 --- /dev/null +++ b/devdocs/c/language%2Finline.html @@ -0,0 +1,77 @@ + <h1 id="firstHeading" class="firstHeading">inline function specifier</h1> <p>Declares an <a href="https://en.wikipedia.org/wiki/inline_function" class="extiw" title="enwiki:inline function">inline function</a>.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>inline</code> <span class="t-spar">function_declaration</span> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>The intent of the <code>inline</code> specifier is to serve as a hint for the compiler to perform optimizations, such as <a href="https://en.wikipedia.org/wiki/inline_expansion" class="extiw" title="enwiki:inline expansion">function inlining</a>, which usually require the definition of a function to be visible at the call site. The compilers can (and usually do) ignore presence or absence of the <code>inline</code> specifier for the purpose of optimization.</p> +<p>If the compiler performs function inlining, it replaces a call of that function with its body, avoiding the overhead of a function call (placing data on stack and retrieving the result), which may result in a larger executable as the code for the function has to be repeated multiple times. The result is similar to <a href="../preprocessor/replace" title="c/preprocessor/replace">function-like macros</a>, except that identifiers and macros used in the function refer to the definitions visible at the point of definition, not at the point of call.</p> +<p>Regardless of whether inlining takes place, the following semantics of inline functions are guaranteed:</p> +<p>Any function with internal linkage may be declared <code>static inline</code> with no other restrictions.</p> +<p>A non-static inline function cannot define a non-const function-local static and cannot refer to a file-scope static.</p> +<div class="c source-c"><pre data-language="c">static int x; + +inline void f(void) +{ + static int n = 1; // error: non-const static in a non-static inline function + int k = x; // error: non-static inline function accesses a static variable +}</pre></div> <p>If a non-static function is declared <code>inline</code>, then it must be defined in the same translation unit. The inline definition that does not use <code>extern</code> is not externally visible and does not prevent other translation units from defining the same function. This makes the <code>inline</code> keyword an alternative to <code>static</code> for defining functions inside header files, which may be included in multiple translation units of the same program.</p> +<p>If a function is declared <code>inline</code> in some translation units, it does not need to be declared <code>inline</code> everywhere: at most one translation unit may also provide a regular, non-inline non-static function, or a function declared <code>extern inline</code>. This one translation unit is said to provide the <i>external definition</i>. In order to avoid undefined behavior, one external definition must exist in the program if the name of the function with external linkage is used in an expression, see <a href="extern#One_definition_rule" title="c/language/extern">one definition rule</a>.</p> +<p>The address of an inline function with external linkage is always the address of the external definition, but when this address is used to make a function call, it's unspecified whether the <i>inline definition</i> (if present in the translation unit) or the <i>external definition</i> is called. The static objects defined within an inline definition are distinct from the static objects defined within the external definition:</p> +<div class="c source-c"><pre data-language="c">inline const char *saddr(void) // the inline definition for use in this file +{ + static const char name[] = "saddr"; + return name; +} + +int compare_name(void) +{ + return saddr() == saddr(); // unspecified behavior, one call could be external +} + +extern const char *saddr(void); // an external definition is generated, too</pre></div> <p>A C program should not depend on whether the inline version or the external version of a function is called, otherwise the behavior is unspecified.</p> +<h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/inline" title="c/keyword/inline"><code>inline</code></a></p> +<h3 id="Notes"> Notes</h3> <p>The <code>inline</code> keyword was adopted from C++, but in C++, if a function is declared <code>inline</code>, it must be declared <code>inline</code> in every translation unit, and also every definition of an inline function must be exactly the same (in C, the definitions may be different, and depending on the differences only results in unspecified behavior). On the other hand, C++ allows non-const function-local statics and all function-local statics from different definitions of an inline function are the same in C++ but distinct in C.</p> +<h3 id="Example"> Example</h3> <table class="t-rev-begin"> <tr class="t-rev"> +<td> <p>Header file "test.h"</p> +<div class="c source-c"><pre data-language="c">#ifndef TEST_H_INCLUDED +#define TEST_H_INCLUDED + +inline int sum(int a, int b) +{ + return a + b; +} + +#endif</pre></div> <p>Source file "sum.c"</p> +<div class="c source-c"><pre data-language="c">#include "test.h" + +extern inline int sum(int a, int b); // provides external definition</pre></div> <p>Source file "test1.c"</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> +#include "test.h" + +extern int f(void); + +int main(void) +{ + printf("%d\n", sum(1, 2) + f()); +}</pre></div> <p>Source file "test2.c"</p> +<div class="c source-c"><pre data-language="c">#include "test.h" + +int f(void) +{ + return sum(3, 4); +}</pre></div> <p>Output</p> +<div class="c source-c"><pre data-language="c">10</pre></div> </td> <td></td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.7.4 Function specifiers (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.7.4 Function specifiers (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.7.4 Function specifiers (p: 125-127) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.7.4 Function specifiers (p: 112-113) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/inline" title="cpp/language/inline">C++ documentation</a></span> for <span class=""><span><code>inline</code> specifier</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/inline" class="_attribution-link">https://en.cppreference.com/w/c/language/inline</a> + </p> +</div> diff --git a/devdocs/c/language%2Finteger_constant.html b/devdocs/c/language%2Finteger_constant.html new file mode 100644 index 00000000..999d4816 --- /dev/null +++ b/devdocs/c/language%2Finteger_constant.html @@ -0,0 +1,135 @@ + <h1 id="firstHeading" class="firstHeading">Integer constant</h1> <p>Allows values of integer type to be used in expressions directly.</p> +<h3 id="Syntax"> Syntax</h3> <p>An integer constant is a <a href="value_category" title="c/language/value category">non-lvalue</a> expression of the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="t-spar">decimal-constant</span> <span class="t-spar">integer-suffix</span> <span class="t-mark">(optional)</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">octal-constant</span> <span class="t-spar">integer-suffix</span> <span class="t-mark">(optional)</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">hex-constant</span> <span class="t-spar">integer-suffix</span> <span class="t-mark">(optional)</span> </td> <td> (3) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">binary-constant</span> <span class="t-spar">integer-suffix</span> <span class="t-mark">(optional)</span> </td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <p>where</p> +<ul> +<li> <span class="t-spar">decimal-constant</span> is a non-zero decimal digit (<code>1</code>, <code>2</code>, <code>3</code>, <code>4</code>, <code>5</code>, <code>6</code>, <code>7</code>, <code>8</code>, <code>9</code>), followed by zero or more decimal digits (<code>0</code>, <code>1</code>, <code>2</code>, <code>3</code>, <code>4</code>, <code>5</code>, <code>6</code>, <code>7</code>, <code>8</code>, <code>9</code>) </li> +<li> <span class="t-spar">octal-constant</span> is the digit zero (<code>0</code>) followed by zero or more octal digits (<code>0</code>, <code>1</code>, <code>2</code>, <code>3</code>, <code>4</code>, <code>5</code>, <code>6</code>, <code>7</code>) </li> +<li> <span class="t-spar">hex-constant</span> is the character sequence <code>0x</code> or the character sequence <code>0X</code> followed by one or more hexadecimal digits (<code>0</code>, <code>1</code>, <code>2</code>, <code>3</code>, <code>4</code>, <code>5</code>, <code>6</code>, <code>7</code>, <code>8</code>, <code>9</code>, <code>a</code>, <code>A</code>, <code>b</code>, <code>B</code>, <code>c</code>, <code>C</code>, <code>d</code>, <code>D</code>, <code>e</code>, <code>E</code>, <code>f</code>, <code>F</code>) </li> +<li> <span class="t-spar">binary-constant</span> is the character sequence <code>0b</code> or the character sequence <code>0B</code> followed by one or more binary digits (<code>0</code>, <code>1</code>) </li> +<li> <span class="t-spar">integer-suffix</span>, if provided, may contain one of the following (except the unsigned prefix can be combined with one of the others; if two suffixes are used they can appear in any order): </li> +<ul> +<li> <span class="t-spar">unsigned-suffix</span> (the character <code>u</code> or the character <code>U</code>) </li> +<li> <span class="t-spar">long-suffix</span> (the character <code>l</code> or the character <code>L</code>) <span class="t-rev-inl t-since-c99"><span>or the <span class="t-spar">long-long-suffix</span> (the character sequence <code>ll</code> or the character sequence <code>LL</code>)</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> </li> +<li> <span class="t-spar">bit-precise-int-suffix</span> (the character sequence <code>wb</code> or the character sequence <code>WB</code>) <span class="t-mark-rev t-since-c23">(since C23)</span> </li> +</ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>Optional single quotes (<code>'</code>) may be inserted between the digits as a separator. They are ignored by the compiler.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Explanation"> Explanation</h3> <div class="t-li1"> +<span class="t-li">1)</span> Decimal integer constant (base 10, the first digit is the most significant).</div> <div class="t-li1"> +<span class="t-li">2)</span> Octal integer constant (base 8, the first digit is the most significant).</div> <div class="t-li1"> +<span class="t-li">3)</span> Hexadecimal integer constant (base 16, the first digit is the most significant, the letters <code>a</code> through <code>f</code> represent the decimal values 10 through 15).</div> <div class="t-li1"> +<span class="t-li">4)</span> Binary integer constant (base 2, the first digit is the most significant).</div> <p>The following variables are initialized to the same value:</p> +<div class="c source-c"><pre data-language="c">int d = 42; +int o = 052; +int x = 0x2a; +int X = 0X2A; +int b = 0b101010; // C23</pre></div> <p>The following variables are also initialized to the same value:</p> +<div class="c source-c"><pre data-language="c">unsigned long long l1 = 18446744073709550592ull; // C99 +unsigned long long l2 = 18'446'744'073'709'550'592llu; // C23 +unsigned long long l3 = 1844'6744'0737'0955'0592uLL; // C23 +unsigned long long l4 = 184467'440737'0'95505'92LLU; // C23</pre></div> <h3 id="The_type_of_the_integer_constant"> The type of the integer constant</h3> <p>The type of the integer constant is the first type in which the value can fit, from the list of types which depends on which numeric base and which <span class="t-spar">integer-suffix</span> was used.</p> +<table class="wikitable"> <caption> Types allowed for integer constants </caption> <tr> <th> suffix </th> <th> decimal bases </th> <th> other bases </th> +</tr> <tr> <td>no suffix </td> <td> +<code>int</code> <p><code>long int</code><br> <code>unsigned long int</code> <span class="t-mark-rev t-until-c99">(until C99)</span><br> <code>long long int</code> <span class="t-mark-rev t-since-c99">(since C99)</span></p> +</td> <td> +<code>int</code> <p><code>unsigned int</code><br> <code>long int</code><br> <code>unsigned long int</code><br> <code>long long int</code><span class="t-mark-rev t-since-c99">(since C99)</span><br> <code>unsigned long long int</code><span class="t-mark-rev t-since-c99">(since C99)</span></p> +</td> +</tr> <tr> <td> +<code>u</code> or <code>U</code> </td> <td> +<code>unsigned int</code> <p><code>unsigned long int</code><br> <code>unsigned long long int</code><span class="t-mark-rev t-since-c99">(since C99)</span></p> +</td> <td> +<code>unsigned int</code> <p><code>unsigned long int</code><br> <code>unsigned long long int</code><span class="t-mark-rev t-since-c99">(since C99)</span></p> +</td> +</tr> <tr> <td> +<code>l</code> or <code>L</code> </td> <td> +<code>long int</code> <p><code>unsigned long int</code><span class="t-mark-rev t-until-c99">(until C99)</span><br> <code>long long int</code><span class="t-mark-rev t-since-c99">(since C99)</span></p> +</td> <td> +<code>long int</code> <p><code>unsigned long int</code><br> <code>long long int</code><span class="t-mark-rev t-since-c99">(since C99)</span><br> <code>unsigned long long int</code><span class="t-mark-rev t-since-c99">(since C99)</span></p> +</td> +</tr> <tr> <td>both <code>l</code>/<code>L</code> and <code>u</code>/<code>U</code> </td> <td> +<code>unsigned long int</code> <p><code>unsigned long long int</code><span class="t-mark-rev t-since-c99">(since C99)</span></p> +</td> <td> +<code>unsigned long int</code> <p><code>unsigned long long int</code><span class="t-mark-rev t-since-c99">(since C99)</span></p> +</td> +</tr> <tr> <td> +<code>ll</code> or <code>LL</code> </td> <td> +<code>long long int</code><span class="t-mark-rev t-since-c99">(since C99)</span> </td> <td> +<code>long long int</code><span class="t-mark-rev t-since-c99">(since C99)</span> <p><code>unsigned long long int</code><span class="t-mark-rev t-since-c99">(since C99)</span></p> +</td> +</tr> <tr> <td>both <code>ll</code>/<code>LL</code> and <code>u</code>/<code>U</code> </td> <td> +<code>unsigned long long int</code><span class="t-mark-rev t-since-c99">(since C99)</span> </td> <td> +<code>unsigned long long int</code><span class="t-mark-rev t-since-c99">(since C99)</span> </td> +</tr> <tr> <td> +<code>wb</code> or <code>WB</code> </td> <td> +<code>_BitInt(N)</code> where the width N is the smallest N greater than 1 which can accommodate the value and the sign bit<span class="t-mark-rev t-since-c23">(since C23)</span> </td> <td> +<code>_BitInt(N)</code> where the width N is the smallest N greater than 1 which can accommodate the value and the sign bit<span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> <tr> <td>both <code>wb</code>/<code>WB</code> and <code>u</code>/<code>U</code> </td> <td> +<code>unsigned _BitInt(N)</code> where the width N is the smallest N greater than 0 which can accommodate the value<span class="t-mark-rev t-since-c23">(since C23)</span> </td> <td> +<code>unsigned _BitInt(N)</code> where the width N is the smallest N greater than 0 which can accommodate the value<span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <p>If the value of the integer constant is too big to fit in any of the types allowed by suffix/base combination, <span class="t-rev-inl t-since-c23"><span>it does not have suffixes <code>wb</code>, <code>WB</code>, <code>uwb</code>, or <code>UWB</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> and the compiler supports extended integer types (such as <code>__int128</code>), the constant may be given the extended integer type; otherwise, the program is ill-formed.</p> +<h3 id="Notes"> Notes</h3> <p>Letters in the integer constants are case-insensitive: <code>0xDeAdBaBeU</code> and <code>0XdeadBABEu</code> represent the same number<span class="t-rev-inl t-since-c99"><span> (one exception is the <span class="t-spar">long-long-suffix</span>, which is either <code>ll</code> or <code>LL</code>, never <code>lL</code> or <code>Ll</code>)</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>.</p> +<p>There are no negative integer constants. Expressions such as <code>-1</code> apply the <a href="operator_arithmetic" title="c/language/operator arithmetic">unary minus operator</a> to the value represented by the constant.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>When used in a controlling expression of <a href="../preprocessor/conditional" title="c/preprocessor/conditional"><code> #if</code></a> or <a href="../preprocessor/conditional" title="c/preprocessor/conditional"><code> #elif</code></a>, all signed integer constants act as if they have type <code><a href="../types/integer" title="c/types/integer">intmax_t</a></code> and all unsigned integer constants act as if they have type <code><a href="../types/integer" title="c/types/integer">uintmax_t</a></code>.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <p>Integer constants may be used in <a href="constant_expression" title="c/language/constant expression">integer constant expressions</a>.</p> +<p>Due to <a href="translation_phases#maximal_munch" title="c/language/translation phases">maximal munch</a>, hexadecimal integer constants ending in <code>e</code> and <code>E</code>, when followed by the operators <code>+</code> or <code>-</code>, must be separated from the operator with whitespace or parentheses in the source:</p> +<div class="c source-c"><pre data-language="c">int x = 0xE+2; // error +int y = 0xa+2; // OK +int z = 0xE +2; // OK +int q = (0xE)+2; // OK</pre></div> <p>Otherwise, a single invalid preprocessing number token is formed, which causes further analysis to fail.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <inttypes.h> +#include <stdio.h> + +int main(void) +{ + printf("123 = %d\n", 123); + printf("0123 = %d\n", 0123); + printf("0x123 = %d\n", 0x123); + printf("12345678901234567890ull = %llu\n", 12345678901234567890ull); + // the type is a 64-bit type (unsigned long long or possibly unsigned long) + // even without a long suffix + printf("12345678901234567890u = %"PRIu64"\n", 12345678901234567890u ); + + // printf("%lld\n", -9223372036854775808); // Error: + // the value 9223372036854775808 cannot fit in signed long long, which + // is the biggest type allowed for unsuffixed decimal integer constant + + printf("%llu\n", -9223372036854775808ull ); + // unary minus applied to unsigned value subtracts it from 2^64, + // this gives unsigned 9223372036854775808 + + printf("%lld\n", -9223372036854775807ll - 1); + // correct way to form signed value -9223372036854775808 +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">123 = 123 +0123 = 83 +0x123 = 291 +12345678901234567890ull = 12345678901234567890 +12345678901234567890u = 12345678901234567890 +9223372036854775808 +-9223372036854775808</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.4.4.1 Integer constants (p: 57-60) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.4.4.1 Integer constants (p: 45-46) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.4.4.1 Integer constants (p: 62-64) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.4.4.1 Integer constants (p: 54-56) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.1.3.2 Integer constants </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/integer_literal" title="cpp/language/integer literal">C++ documentation</a></span> for <span class=""><span>Integer literal</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/integer_constant" class="_attribution-link">https://en.cppreference.com/w/c/language/integer_constant</a> + </p> +</div> diff --git a/devdocs/c/language%2Flifetime.html b/devdocs/c/language%2Flifetime.html new file mode 100644 index 00000000..b250592e --- /dev/null +++ b/devdocs/c/language%2Flifetime.html @@ -0,0 +1,41 @@ + <h1 id="firstHeading" class="firstHeading">Lifetime</h1> <p>Every <a href="object" title="c/language/object">object</a> in C exists, has a constant address, retains its last-stored value (except when the value is indeterminate)<span class="t-rev-inl t-since-c99"><span>, and, for VLA, retains its size</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> over a portion of program execution known as this object's <i>lifetime</i>.</p> +<p>For the objects that are declared with automatic, static, and thread storage duration, lifetime equals their <a href="storage_duration" title="c/language/storage duration">storage duration</a> (note the difference between non-VLA and VLA automatic storage duration).</p> +<p>For the objects with allocated storage duration, the lifetime begins when the allocation function returns (including the return from <code><a href="../memory/realloc" title="c/memory/realloc">realloc</a></code>) and ends when the <code><a href="../memory/realloc" title="c/memory/realloc">realloc</a></code> or deallocation function is called. Note that since allocated objects have no <a href="object" title="c/language/object">declared type</a>, the type of the lvalue expression first used to access this object becomes its <a href="object" title="c/language/object">effective type</a>.</p> +<p>Accessing an object outside of its lifetime is undefined behavior.</p> +<div class="c source-c"><pre data-language="c">int* foo(void) { + int a = 17; // a has automatic storage duration + return &a; +} // lifetime of a ends +int main(void) { + int* p = foo(); // p points to an object past lifetime ("dangling pointer") + int n = *p; // undefined behavior +}</pre></div> <p>A pointer to an object (or one past the object) whose lifetime ended has indeterminate value.</p> +<h3 id="Temporary_lifetime"> Temporary lifetime</h3> <p>Struct and union objects with array members (either direct or members of nested struct/union members) that are designated by <a href="value_category" title="c/language/value category">non-lvalue expressions</a>, have <i>temporary lifetime</i>. Temporary lifetime begins when the expression that refers to such object is evaluated and ends <span class="t-rev-inl t-until-c11"><span>at the next <a href="eval_order" title="c/language/eval order">sequence point</a></span><span><span class="t-mark-rev t-until-c11">(until C11)</span></span></span><span class="t-rev-inl t-since-c11"><span>when the containing full expression or full declarator ends</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span>.</p> +<p>Any attempt to modify an object with temporary lifetime results in undefined behavior.</p> +<div class="c source-c"><pre data-language="c">struct T { double a[4]; }; +struct T f(void) { return (struct T){3.15}; } +double g1(double* x) { return *x; } +void g2(double* x) { *x = 1.0; } +int main(void) +{ + double d = g1(f().a); // C99: UB access to a[0] in g1 whose lifetime ended + // at the sequence point at the start of g1 + // C11: OK, d is 3.15 + g2(f().a); // C99: UB modification of a[0] whose lifetime ended at the sequence point + // C11: UB attempt to modify a temporary object +}</pre></div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.2.4 Storage durations of objects (p: 30) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.2.4 Storage durations of objects (p: 38-39) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.2.4 Storage durations of objects (p: 32) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.1.2.4 Storage durations of objects </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/lifetime" title="cpp/language/lifetime">C++ documentation</a></span> for <span class=""><span>Object lifetime</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/lifetime" class="_attribution-link">https://en.cppreference.com/w/c/language/lifetime</a> + </p> +</div> diff --git a/devdocs/c/language%2Fmain_function.html b/devdocs/c/language%2Fmain_function.html new file mode 100644 index 00000000..a0cfbc3e --- /dev/null +++ b/devdocs/c/language%2Fmain_function.html @@ -0,0 +1,60 @@ + <h1 id="firstHeading" class="firstHeading">Main function</h1> <p>Every C program coded to run in a hosted execution environment contains the definition (not the prototype) of a function named <code>main</code>, which is the designated start of the program.</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="kw4">int</span> <code>main</code> <code>(void)</code> <code>{</code> <span class="t-spar">body</span> <code>}</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="kw4">int</span> <code>main</code> <code>(</code><span class="kw4">int</span> <span class="t-spar">argc</span><code>,</code> <span class="kw4">char</span> <span class="sy2">*</span><span class="t-spar">argv</span><span class="br0">[</span><span class="br0">]</span><code>)</code> <code>{</code> <span class="t-spar">body</span> <code>}</code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="coMULTI">/* another implementation-defined signature */</span> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> <td> (3) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> argc </td> <td> - </td> <td> Non-negative value representing the number of arguments passed to the program from the environment in which the program is run. </td> +</tr> <tr class="t-par"> <td> argv </td> <td> - </td> <td> Pointer to the first element of an array of <code>argc + 1</code> pointers, of which the last one is null and the previous ones, if any, point to strings that represent the arguments passed to the program from the host environment. If <code>argv[0]</code> is not a null pointer (or, equivalently, if <code>argc</code> > 0), it points to a string that represents the program name, which is empty if the program name is not available from the host environment. </td> +</tr> +</table> <p>The names <code>argc</code> and <code>argv</code> stand for "argument count" and "argument vector", and are traditionally used, but other names may be chosen for the parameters, as well as different but equivalent declarations of their type: <span class="kw4">int</span> main<span class="br0">(</span><span class="kw4">int</span> ac, <span class="kw4">char</span><span class="sy2">**</span> av<span class="br0">)</span> is equally valid.</p> +<p>A common implementation-defined form of main is <span class="kw4">int</span> main<span class="br0">(</span><span class="kw4">int</span> argc, <span class="kw4">char</span> <span class="sy2">*</span>argv<span class="br0">[</span><span class="br0">]</span>, <span class="kw4">char</span> <span class="sy2">*</span>envp<span class="br0">[</span><span class="br0">]</span><span class="br0">)</span>, where a third argument, of type <code>char**</code>, pointing at <a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/exec.html">an array of pointers to the <i>execution environment variables</i></a>, is added.</p> +<h3 id="Return_value"> Return value</h3> <p>If the return statement is used, the return value is used as the argument to the implicit call to <code><a href="../program/exit" title="c/program/exit">exit()</a></code> (see below for details). The values zero and <code><a href="../program/exit_status" title="c/program/EXIT status">EXIT_SUCCESS</a></code> indicate successful termination, the value <code><a href="../program/exit_status" title="c/program/EXIT status">EXIT_FAILURE</a></code> indicates unsuccessful termination.</p> +<h3 id="Explanation"> Explanation</h3> <p>The <code>main</code> function is called at program startup, after all objects with static storage duration are initialized. It is the designated entry point to a program that is executed in a <i>hosted</i> environment (that is, with an operating system). The name and type of the entry point to any <i>freestanding</i> program (boot loaders, OS kernels, etc) are implementation-defined.</p> +<p>The parameters of the two-parameter form of the main function allow arbitrary multibyte character strings to be passed from the execution environment (these are typically known as <i>command line arguments</i>). The pointers argv<span class="br0">[</span><span class="nu0">1</span><span class="br0">]</span> .. <span class="me1">argv</span><span class="br0">[</span>argc<span class="sy2">-</span><span class="nu0">1</span><span class="br0">]</span> point at the first characters in each of these strings. argv<span class="br0">[</span><span class="nu0">0</span><span class="br0">]</span> (if non-null) is the pointer to the initial character of a null-terminated multibyte string that represents the name used to invoke the program itself (or, if this is not supported by the host environment, argv<span class="br0">[</span><span class="nu0">0</span><span class="br0">]</span><span class="br0">[</span><span class="nu0">0</span><span class="br0">]</span> is guaranteed to be zero).</p> +<p>If the host environment cannot supply both lowercase and uppercase letters, the command line arguments are converted to lowercase.</p> +<p>The strings are modifiable, and any modifications made persist until program termination, although these modifications do not propagate back to the host environment: they can be used, for example, with <code><a href="../string/byte/strtok" title="c/string/byte/strtok">strtok</a></code>.</p> +<p>The size of the array pointed to by <code>argv</code> is at least <code>argc+1</code>, and the last element, <code>argv[argc]</code>, is guaranteed to be a null pointer.</p> +<p>The <code>main</code> function has several special properties:</p> +<div class="t-li1"> +<span class="t-li">1)</span> A prototype for this function cannot be supplied by the program.</div> <div class="t-li1"> +<span class="t-li">2)</span> If the return type of the main function is <a href="type#Compatible_types" title="c/language/type">compatible</a> with <code>int</code>, then the return from the initial call to main (but not the return from any subsequent, recursive, call) is equivalent to executing the <code><a href="../program/exit" title="c/program/exit">exit</a></code> function, with the value that the main function is returning passed as the argument (which then calls the functions registered with <code><a href="../program/atexit" title="c/program/atexit">atexit</a></code>, flushes and closes all streams, and deletes the files created with <code><a href="../io/tmpfile" title="c/io/tmpfile">tmpfile</a></code>, and returns control to the execution environment).</div> <div class="t-li1"> +<span class="t-li">3)</span> <table class="t-rev-begin"> <tr class="t-rev t-until-c99"> +<td> <p>If the main function executes a <code>return</code> that specifies no value or, which is the same, reaches the terminating <code>}</code> without executing a <code>return</code>, the termination status returned to the host environment is undefined.</p> +</td> <td><span class="t-mark-rev t-until-c99">(until C99)</span></td> +</tr> <tr class="t-rev t-since-c99"> +<td> <p>If the return type of the main function is not <a href="type#Compatible_types" title="c/language/type">compatible</a> with <code>int</code> (e.g. <code>void main(void)</code>), the value returned to the host environment is unspecified. If the return type is compatible with <code>int</code> and control reaches the terminating <code>}</code>, the value returned to the environment is the same as if executing <code>return 0;</code>.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> +</div> <h3 id="Example"> Example</h3> <div class="t-example"> +<p>Demonstrates how to inform a program about where to find its input and where to write its results. Invocation: ./a.out indatafile outdatafile</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> + +int main(int argc, char *argv[]) +{ + printf("argc = %d\n", argc); + for (int ndx = 0; ndx != argc; ++ndx) + printf("argv[%d] --> %s\n", ndx, argv[ndx]); + printf("argv[argc] = %p\n", (void*)argv[argc]); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">argc = 3 +argv[0] --> ./a.out +argv[1] --> indatafile +argv[2] --> outdatafile +argv[argc] = (nil)</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 5.1.2.2.1 Program startup (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 5.1.2.2.1 Program startup (p: 10-11) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 5.1.2.2.1 Program startup (p: 13) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 5.1.2.2.1 Program startup (p: 12) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 5.1.2.2 Hosted environment </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/main_function" title="cpp/language/main function">C++ documentation</a></span> for <span class=""><span><code>main</code> function</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/main_function" class="_attribution-link">https://en.cppreference.com/w/c/language/main_function</a> + </p> +</div> diff --git a/devdocs/c/language%2Fmemory_model.html b/devdocs/c/language%2Fmemory_model.html new file mode 100644 index 00000000..b0e6cfb5 --- /dev/null +++ b/devdocs/c/language%2Fmemory_model.html @@ -0,0 +1,49 @@ + <h1 id="firstHeading" class="firstHeading">Memory model</h1> <p>Defines the semantics of computer memory storage for the purpose of the C abstract machine.</p> +<p>The data storage (memory) available to a C program is one or more contiguous sequences of <i>bytes</i>. Each byte in memory has a unique <i>address</i>.</p> +<h3 id="Byte"> Byte</h3> <p>A <i>byte</i> is the smallest addressable unit of memory. It is defined as a contiguous sequence of bits, large enough to hold any member of the <i>basic execution character set</i> (<a href="translation_phases" title="c/language/translation phases">the 96 characters</a> that are required to be single-byte). C supports bytes of sizes 8 bits and greater.</p> +<p>The <a href="types" title="c/language/types" class="mw-redirect">types</a> <code>char</code>, <code>unsigned char</code>, and <code>signed char</code> use one byte for both storage and <a href="object" title="c/language/object">value representation</a>. The number of bits in a byte is accessible as <code><a href="../types/limits" title="c/types/limits">CHAR_BIT</a></code>.</p> +<p>For use of bytes to representation values of other fundamental types (including big-endian and little-endian memory layouts), see <a href="object#Object_representation" title="c/language/object">object representation</a></p> +<h3 id="Memory_location"> Memory location</h3> <p>A <i>memory location</i> is</p> +<ul> +<li> an object of <a href="type#Type_groups" title="c/language/type">scalar type</a> (arithmetic type, pointer type, enumeration type) </li> +<li> or the largest contiguous sequence of <a href="bit_field" title="c/language/bit field">bit-fields</a> of non-zero length </li> +</ul> <div class="c source-c"><pre data-language="c">struct S +{ + char a; // memory location #1 + int b : 5; // memory location #2 + int c : 11, // memory location #2 (continued) + : 0, + d : 8; // memory location #3 + struct + { + int ee : 8; // memory location #4 + } e; +} obj; // The object 'obj' consists of 4 separate memory locations</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <h3 id="Threads_and_data_races"> Threads and data races</h3> <p>A thread of execution is a flow of control within a program that begins with the invocation of a top-level function by <code><a href="../thread/thrd_create" title="c/thread/thrd create">thrd_create</a></code> or other means.</p> +<p>Any thread can potentially access any object in the program (objects with automatic and thread-local <a href="storage_duration" title="c/language/storage duration">storage duration</a> may still be accessed by another thread through a pointer).</p> +<p>Different threads of execution are always allowed to access (read and modify) different <i>memory locations</i> concurrently, with no interference and no synchronization requirements. (note that it is not safe to concurrently update two non-atomic bit-fields in the same structure if all members declared between them are also (non-zero-length) bit-fields, no matter what the sizes of those intervening bit-fields happen to be)</p> +<p>When an <a href="eval_order" title="c/language/eval order">evaluation</a> of an expression writes to a memory location and another evaluation reads or modifies the same memory location, the expressions are said to <i>conflict</i>. A program that has two conflicting evaluations has a <i>data race</i> unless either</p> +<ul> +<li> both conflicting evaluations are <a href="atomic" title="c/language/atomic">atomic operations</a> </li> +<li> one of the conflicting evaluations <i>happens-before</i> another (see <code><a href="../atomic/memory_order" title="c/atomic/memory order">memory_order</a></code>) </li> +</ul> <p>If a data race occurs, the behavior of the program is undefined. (in particular, <code><a href="../thread/mtx_unlock" title="c/thread/mtx unlock">mtx_unlock</a></code> is</p> +<i>synchronized-with</i>, and therefore, <i>happens-before</i> <code><a href="../thread/mtx_lock" title="c/thread/mtx lock">mtx_lock</a></code> of the same mutex by another thread, which makes it possible to use mutex locks to guard against data races) <h3 id="Memory_order"> Memory order</h3> <p>When a thread reads a value from a memory location, it may see the initial value, the value written in the same thread, or the value written in another thread. See <code><a href="../atomic/memory_order" title="c/atomic/memory order">memory_order</a></code> for details on the order in which writes made from threads become visible to other threads.</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 3.6 byte (p: 4) </li> +<li> 3.14 memory location (p: 5) </li> +<li> 5.1.2.4 Multi-threaded executions and data races (p: 17-21) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 3.6 byte (p: 4) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 1.6 DEFINITIONS OF TERMS </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/memory_model" title="cpp/language/memory model">C++ documentation</a></span> for <span class=""><span>Memory model</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/memory_model" class="_attribution-link">https://en.cppreference.com/w/c/language/memory_model</a> + </p> +</div> diff --git a/devdocs/c/language%2Fname_space.html b/devdocs/c/language%2Fname_space.html new file mode 100644 index 00000000..46652601 --- /dev/null +++ b/devdocs/c/language%2Fname_space.html @@ -0,0 +1,74 @@ + <h1 id="firstHeading" class="firstHeading">Lookup and name spaces</h1> <p>When an <a href="identifier" title="c/language/identifier">identifier</a> is encountered in a C program, a lookup is performed to locate the <a href="declarations" title="c/language/declarations">declaration</a> that introduced that identifier and that is currently <a href="scope" title="c/language/scope">in scope</a>. C allows more than one declaration for the same identifier to be in scope simultaneously if these identifiers belong to different categories, called <i>name spaces</i>:</p> +<div class="t-li1"> +<span class="t-li">1)</span> Label name space: all identifiers declared as <a href="statements#Labels" title="c/language/statements">labels</a>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Tag names: all identifiers declared as names of <a href="struct" title="c/language/struct">structs</a>, <a href="union" title="c/language/union">unions</a> and <a href="enum" title="c/language/enum">enumerated types</a>. Note that all three kinds of tags share one name space.</div> <div class="t-li1"> +<span class="t-li">3)</span> Member names: all identifiers declared as members of any one <a href="struct" title="c/language/struct">struct</a> or <a href="union" title="c/language/union">union</a>. Every struct and union introduces its own name space of this kind.</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <span class="t-li">4)</span> Global attribute name space: <a href="attributes" title="c/language/attributes">attribute tokens</a> defined by the standard or implementation-defined attribute prefixes. <span class="t-li">5)</span> Non-standard attribute names: attribute names following attribute prefixes. Each attribute prefix has a separate name space for the implementation-defined attributes it introduces. </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <div class="t-li1"> +<span class="t-li">6)</span> All other identifiers, called <i>ordinary identifiers</i> to distinguish from <span class="t-v">(1-5)</span> (function names, object names, typedef names, enumeration constants).</div> <p>At the point of lookup, the name space of an identifier is determined by the manner in which it is used:</p> +<div class="t-li1"> +<span class="t-li">1)</span> identifier appearing as the operand of a <a href="goto" title="c/language/goto">goto statement</a> is looked up in the label name space.</div> <div class="t-li1"> +<span class="t-li">2)</span> identifier that follows the keyword <code>struct</code>, <code>union</code>, or <code>enum</code> is looked up in the tag name space.</div> <div class="t-li1"> +<span class="t-li">3)</span> identifier that follows the <a href="operator_member_access" title="c/language/operator member access">member access</a> or member access through pointer operator is looked up in the name space of members of the type determined by the left-hand operand of the member access operator.</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <span class="t-li">4)</span> identifier that directly appears in an attribute specifier (<code>[[...]]</code>) is looked up in the global attribute name space. <span class="t-li">5)</span> identifier that follows the <code>::</code> token following an attribute prefix is looked in the name space introduced by the attribute prefix. </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <div class="t-li1"> +<span class="t-li">6)</span> all other identifiers are looked up in the name space of ordinary identifiers.</div> <h3 id="Notes"> Notes</h3> <p>The names of <a href="../preprocessor/replace" title="c/preprocessor/replace">macros</a> are not part of any name space because they are replaced by the preprocessor prior to semantic analysis.</p> +<p>It is common practice to inject struct/union/enum names into the name space of the ordinary identifiers using a <a href="typedef" title="c/language/typedef">typedef</a> declaration:</p> +<div class="c source-c"><pre data-language="c">struct A { }; // introduces the name A in tag name space +typedef struct A A; // first, lookup for A after "struct" finds one in tag name space + // then introduces the name A in the ordinary name space +struct A* p; // OK, this A is looked up in the tag name space +A* q; // OK, this A is looked up in the ordinary name space</pre></div> <p>A well-known example of the same identifier being used across two name spaces is the identifier <code>stat</code> from the POSIX header <code>sys/stat.h</code>. It <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/">names a function</a> when used as an ordinary identifier and <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_stat.h.html">indicates a struct</a> when used as a tag.</p> +<p>Unlike in C++, enumeration constants are not struct members, and their name space is the name space of ordinary identifiers, and since there is no struct scope in C, their scope is the scope in which the struct declaration appears:</p> +<div class="c source-c"><pre data-language="c">struct tagged_union { + enum {INT, FLOAT, STRING} type; + union { + int integer; + float floating_point; + char *string; + }; +} tu; + +tu.type = INT; // OK in C, error in C++</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>If a standard attribute, an attribute prefix, or a non-standard attribute name is not supported, the invalid attribute itself is ignored without causing an error.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">void foo (void) { return; } // ordinary name space, file scope +struct foo { // tag name space, file scope + int foo; // member name space for this struct foo, file scope + enum bar { // tag name space, file scope + RED // ordinary name space, file scope + } bar; // member name space for this struct foo, file scope + struct foo* p; // OK: uses tag/file scope name "foo" +}; +enum bar x; // OK: uses tag/file-scope bar +// int foo; // Error: ordinary name space foo already in scope +//union foo { int a, b; }; // Error: tag name space foo in scope + +int main(void) +{ + goto foo; // OK uses "foo" from label name space/function scope + + struct foo { // tag name space, block scope (hides file scope) + enum bar x; // OK, uses "bar" from tag name space/file scope + }; + typedef struct foo foo; // OK: uses foo from tag name space/block scope + // defines block-scope ordinary foo (hides file scope) + (foo){.x=RED}; // uses ordinary/block-scope foo and ordinary/file-scope RED + +foo:; // label name space, function scope +}</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.2.3 Name spaces of identifiers (p: 29-30) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.2.3 Name spaces of identifiers (p: 37) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.2.3 Name spaces of identifiers (p: 31) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.1.2.3 Name spaces of identifiers </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/lookup" title="cpp/language/lookup">C++ documentation</a></span> for <span class=""><span>Name lookup</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/name_space" class="_attribution-link">https://en.cppreference.com/w/c/language/name_space</a> + </p> +</div> diff --git a/devdocs/c/language%2Fnullptr.html b/devdocs/c/language%2Fnullptr.html new file mode 100644 index 00000000..9c5d8a87 --- /dev/null +++ b/devdocs/c/language%2Fnullptr.html @@ -0,0 +1,59 @@ + <h1 id="firstHeading" class="firstHeading">Predefined null pointer constant <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>nullptr</code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>The keyword <code>nullptr</code> denotes a predefined null pointer constant. It is a <a href="value_category#Non-lvalue_object_expressions" title="c/language/value category">non-lvalue</a> of type <code><a href="../types/nullptr_t" title="c/types/nullptr t">nullptr_t</a></code>. <code>nullptr</code> can be <a href="conversion" title="c/language/conversion">converted</a> to a pointer types or <code>bool</code>, where the result is the null pointer value of that type or <code>false</code> respectively.</p> +<h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/nullptr" title="c/keyword/nullptr"><code>nullptr</code></a></p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>Demonstrates that a copy of <code>nullptr</code> can also be used as a null pointer constant.</p> +<div class="c source-c"><pre data-language="c">#include <stddef.h> +#include <stdio.h> + +void g(int*) +{ + puts("Function g called"); +} + +#define DETECT_NULL_POINTER_CONSTANT(e) \ + _Generic(e, \ + void* : puts("void*"), \ + nullptr_t : puts("nullptr_t"), \ + default : puts("integer") \ + ) + +int main() +{ + g(nullptr); // OK + g(NULL); // OK + g(0); // OK + + auto cloned_nullptr = nullptr; + g(cloned_nullptr); // OK + + [[maybe_unused]] auto cloned_NULL = NULL; +// g(cloned_NULL); // implementation-defined: maybe OK + + [[maybe_unused]] auto cloned_zero = 0; +// g(cloned_zero); // Error + + DETECT_NULL_POINTER_CONSTANT(((void*)0)); + DETECT_NULL_POINTER_CONSTANT(0); + DETECT_NULL_POINTER_CONSTANT(nullptr); + DETECT_NULL_POINTER_CONSTANT(NULL); // implementation-defined +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Function g called +Function g called +Function g called +Function g called +void* +integer +nullptr_t +void*</pre></div> </div> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../types/null" title="c/types/NULL"> <span class="t-lines"><span>NULL</span></span></a></div> </td> <td> implementation-defined null pointer constant <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../types/nullptr_t" title="c/types/nullptr t"> <span class="t-lines"><span>nullptr_t</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> the type of the predefined null pointer constant <strong class="selflink"><code>nullptr</code></strong> <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/nullptr" title="cpp/language/nullptr">C++ documentation</a></span> for <code>nullptr</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/nullptr" class="_attribution-link">https://en.cppreference.com/w/c/language/nullptr</a> + </p> +</div> diff --git a/devdocs/c/language%2Fobject.html b/devdocs/c/language%2Fobject.html new file mode 100644 index 00000000..18e7ee2a --- /dev/null +++ b/devdocs/c/language%2Fobject.html @@ -0,0 +1,137 @@ + <h1 id="firstHeading" class="firstHeading">Objects and alignment</h1> <p>C programs create, destroy, access, and manipulate objects.</p> +<p>An object in C is a region of <a href="memory_model" title="c/language/memory model">data storage</a> in the execution environment, the contents of which can represent <i>values</i> (a value is the meaning of the contents of an object, when interpreted as having a specific <a href="type" title="c/language/type">type</a>).</p> +<p>Every object has</p> +<ul> +<li> size (can be determined with <a href="sizeof" title="c/language/sizeof"><code>sizeof</code></a>) </li> +<li> alignment requirement<span class="t-rev-inl t-since-c11"><span>(can be determined by <a href="_alignof" title="c/language/ Alignof"><code>_Alignof</code></a>)</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> </li> +<li> <a href="storage_duration" title="c/language/storage duration">storage duration</a> (automatic, static, allocated, thread-local) </li> +<li> <a href="lifetime" title="c/language/lifetime">lifetime</a> (equal to storage duration or temporary) </li> +<li> effective type (see below) </li> +<li> value (which may be indeterminate) </li> +<li> optionally, an <a href="identifier" title="c/language/identifier">identifier</a> that denotes this object. </li> +</ul> <p>Objects are created by <a href="declarations" title="c/language/declarations">declarations</a>, <a href="../memory" title="c/memory">allocation functions</a>, <a href="string_literal" title="c/language/string literal">string literals</a>, <a href="compound_literal" title="c/language/compound literal">compound literals</a>, and by non-lvalue expressions that return <a href="lifetime" title="c/language/lifetime">structures or unions with array members</a>.</p> +<h3 id="Object_representation"> Object representation</h3> <p>Except for <a href="bit_field" title="c/language/bit field">bit-fields</a>, objects are composed of contiguous sequences of one or more bytes, each consisting of <code><a href="../types/limits" title="c/types/limits">CHAR_BIT</a></code> bits, and can be copied with <code><a href="../string/byte/memcpy" title="c/string/byte/memcpy">memcpy</a></code> into an object of type <code>unsigned char[n]</code>, where <code>n</code> is the size of the object. The contents of the resulting array are known as <i>object representation</i>.</p> +<p>If two objects have the same object representation, they compare equal (except if they are floating-point NaNs). The reverse is not true: two objects that compare equal may have different object representations because not every bit of the object representation needs to participate in the value. Such bits may be used for padding to satisfy alignment requirement, for parity checks, to indicate trap representations, etc.</p> +<p>If an object representation does not represent any value of the object type, it is known as <i>trap representation</i>. Accessing a trap representation in any way other than reading it through an lvalue expression of character type is undefined behavior. The value of a structure or union is never a trap representation even if any particular member is one.</p> +<p>For the objects of type <span class="kw4">char</span>, <span class="kw4">signed</span> <span class="kw4">char</span>, and <span class="kw4">unsigned</span> <span class="kw4">char</span>, every bit of the object representation is required to participate in the value representation and each possible bit pattern represents a distinct value (no padding, trap bits, or multiple representations allowed).</p> +<p>When objects of <a href="arithmetic_types#Integer_types" title="c/language/arithmetic types">integer types</a> (<span class="kw4">short</span>, <span class="kw4">int</span>, <span class="kw4">long</span>, <span class="kw4">long</span> <span class="kw4">long</span>) occupy multiple bytes, the use of those bytes is implementation-defined, but the two dominant implementations are <i>big-endian</i> (POWER, Sparc, Itanium) and <i>little-endian</i> (x86, x86_64): a big-endian platform stores the most significant byte at the lowest address of the region of storage occupied by the integer, a little-endian platform stores the least significant byte at the lowest address. See <a href="https://en.wikipedia.org/wiki/Endianness" class="extiw" title="enwiki:Endianness">Endianness</a> for detail. See also example below.</p> +<p>Although most implementations do not allow trap representations, padding bits, or multiple representations for integer types, there are exceptions; for example a value of an integer type on Itanium <a rel="nofollow" class="external text" href="https://web.archive.org/web/20170830125905/https://blogs.msdn.microsoft.com/oldnewthing/20040119-00/?p=41003">may be a trap representation</a>.</p> +<h3 id="Effective_type"> Effective type</h3> <p>Every object has an <i>effective type</i>, which determines which <a href="value_category" title="c/language/value category">lvalue</a> accesses are valid and which violate the strict aliasing rules.</p> +<p>If the object was created by a <a href="declarations" title="c/language/declarations">declaration</a>, the declared type of that object is the object's <i>effective type</i>.</p> +<p>If the object was created by an <a href="../memory" title="c/memory">allocation function</a> (including <code><a href="../memory/realloc" title="c/memory/realloc">realloc</a></code>), it has no declared type. Such object acquires an effective type as follows:</p> +<ul> +<li> The first write to that object through an lvalue that has a type other than character type, at which time the type of that lvalue becomes this object's <i>effective type</i> for that write and all subsequent reads. </li> +<li> <code><a href="../string/byte/memcpy" title="c/string/byte/memcpy">memcpy</a></code> or <code><a href="../string/byte/memmove" title="c/string/byte/memmove">memmove</a></code> copy another object into that object, or copy another object into that object as an array of character type, at which time the effective type of the source object (if it had one) becomes the effective type of this object for that write and all subsequent reads. </li> +<li> Any other access to the object with no declared type, the effective type is the type of the lvalue used for the access. </li> +</ul> <h3 id="Strict_aliasing"> Strict aliasing</h3> <p>Given an object with <i>effective type</i> T1, using an lvalue expression (typically, dereferencing a pointer) of a different type T2 is undefined behavior, unless:</p> +<ul> +<li> T2 and T1 are <a href="type#Compatible_types" title="c/language/type">compatible types</a>. </li> +<li> T2 is cvr-qualified version of a type that is <a href="type#Compatible_types" title="c/language/type">compatible</a> with T1. </li> +<li> T2 is a signed or unsigned version of a type that is <a href="type#Compatible_types" title="c/language/type">compatible</a> with T1. </li> +<li> T2 is an aggregate type or union type type that includes one of the aforementioned types among its members (including, recursively, a member of a subaggregate or contained union). </li> +<li> T2 is a character type (<span class="kw4">char</span>, <span class="kw4">signed</span> <span class="kw4">char</span>, or <span class="kw4">unsigned</span> <span class="kw4">char</span>). </li> +</ul> <div class="c source-c"><pre data-language="c">int i = 7; +char* pc = (char*)(&i); + +if (pc[0] == '\x7') // aliasing through char is OK + puts("This system is little-endian"); +else + puts("This system is big-endian"); + +float* pf = (float*)(&i); +float d = *pf; // UB: float lvalue *p cannot be used to access int</pre></div> <p>These rules control whether a function that receives two pointers must re-read one after writing through another:</p> +<div class="c source-c"><pre data-language="c">// int* and double* cannot alias +void f1(int* pi, double* pd, double d) +{ + // the read from *pi can be done only once, before the loop + for (int i = 0; i < *pi; i++) + *pd++ = d; +}</pre></div> <div class="c source-c"><pre data-language="c">struct S { int a, b; }; + +// int* and struct S* may alias because S is an aggregate type with a member of type int +void f2(int* pi, struct S* ps, struct S s) +{ + // read from *pi must take place after every write through *ps + for (int i = 0; i < *pi; i++) + *ps++ = s; +}</pre></div> <p>Note that <a href="restrict" title="c/language/restrict">restrict qualifier</a> can be used to indicate that two pointers do not alias even if the rules above permit them to be.</p> +<p>Note that type-punning may also be performed through the inactive member of a <a href="union" title="c/language/union">union</a>.</p> +<h3 id="Alignment"> Alignment</h3> <p>Every complete <a href="types#Type_groups" title="c/language/types" class="mw-redirect">object type</a> has a property called <i>alignment requirement</i>, which is an integer value of type <code><a href="../types/size_t" title="c/types/size t">size_t</a></code> representing the number of bytes between successive addresses at which objects of this type can be allocated. The valid alignment values are non-negative integral powers of two.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <p>The alignment requirement of a type can be queried with <a href="_alignof" title="c/language/ Alignof"><code>_Alignof</code></a>.</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <p>In order to satisfy alignment requirements of all members of a struct, padding may be inserted after some of its members.</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdalign.h> +#include <stdio.h> + +// objects of struct S can be allocated at any address +// because both S.a and S.b can be allocated at any address +struct S +{ + char a; // size: 1, alignment: 1 + char b; // size: 1, alignment: 1 +}; // size: 2, alignment: 1 + +// objects of struct X must be allocated at 4-byte boundaries +// because X.n must be allocated at 4-byte boundaries +// because int's alignment requirement is (usually) 4 +struct X +{ + int n; // size: 4, alignment: 4 + char c; // size: 1, alignment: 1 + // three bytes padding +}; // size: 8, alignment: 4 + +int main(void) +{ + printf("sizeof(struct S) = %zu\n", sizeof(struct S)); + printf("alignof(struct S) = %zu\n", alignof(struct S)); + printf("sizeof(struct X) = %zu\n", sizeof(struct X)); + printf("alignof(struct X) = %zu\n", alignof(struct X)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">sizeof(struct S) = 2 +alignof(struct S) = 1 +sizeof(struct X) = 8 +alignof(struct X) = 4</pre></div> </div> <p>Each object type imposes its alignment requirement on every object of that type. The weakest (smallest) alignment is the alignment of the types <span class="kw4">char</span>, <span class="kw4">signed</span> <span class="kw4">char</span>, and <span class="kw4">unsigned</span> <span class="kw4">char</span>, and equals <span class="nu0">1</span>. The strictest (largest) <i>fundamental alignment</i> of any type is implementation-defined<span class="t-rev-inl t-since-c11"><span>and equal to the alignment of <code><a href="../types/max_align_t" title="c/types/max align t">max_align_t</a></code></span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span>.</p> +<p>Fundamental alignments are supported for objects of all kinds of storage durations.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <p>If an object's alignment is made stricter (larger) than <code><a href="../types/max_align_t" title="c/types/max align t">max_align_t</a></code> using <a href="_alignas" title="c/language/ Alignas"><code>_Alignas</code></a>, it has <i>extended alignment requirement</i>. A struct or union type whose member has extended alignment is an <i>over-aligned type</i>. It is implementation-defined if over-aligned types are supported, and their support may be different in each kind of <a href="storage_duration" title="c/language/storage duration">storage duration</a>.</p> +<p>If a struct or union type <code>S</code> does not have any member of an over-aligned type or declared with an alignment specifier that specifies an extended alignment, <code>S</code> has a fundamental alignment.</p> +<p>The <a href="atomic" title="c/language/atomic">atomic</a> version of every <a href="arithmetic_types" title="c/language/arithmetic types">arithmetic</a> or <a href="pointer" title="c/language/pointer">pointer</a> type has a fundamental alignment.</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <h3 id="Defect_reports"> Defect reports</h3> <p>The following behavior-changing defect reports were applied retroactively to previously published C standards.</p> +<table class="dsctable"> <tr> <th>DR </th> <th>Applied to </th> <th>Behavior as published </th> <th>Correct behavior </th> +</tr> <tr> <td> +<a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_445">DR 445</a> </td> <td>C11 </td> <td>a type might have extended alignment without _Alignas involved </td> <td>it must have fundamental alignment </td> +</tr> +</table> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 3.15 object (p: 5) </li> +<li> 6.2.6 Representations of types (p: 33-35) </li> +<li> 6.2.8 Alignment of objects (p: 36-37) </li> +<li> 6.5/6-7 Expressions (p: 55-56) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 3.15 object (p: 6) </li> +<li> 6.2.6 Representations of types (p: 44-46) </li> +<li> 6.2.8 Alignment of objects (p: 48-49) </li> +<li> 6.5/6-7 Expressions (p: 77) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 3.2 alignment (p: 3) </li> +<li> 3.14 object (p: 5) </li> +<li> 6.2.6 Representations of types (p: 37-39) </li> +<li> 6.5/6-7 Expressions (p: 67-68) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 1.6 Definitions of terms </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/object" title="cpp/language/object">C++ documentation</a></span> for <span class=""><span>Object</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/object" class="_attribution-link">https://en.cppreference.com/w/c/language/object</a> + </p> +</div> diff --git a/devdocs/c/language%2Foperator_alternative.html b/devdocs/c/language%2Foperator_alternative.html new file mode 100644 index 00000000..6d6bac63 --- /dev/null +++ b/devdocs/c/language%2Foperator_alternative.html @@ -0,0 +1,85 @@ + <h1 id="firstHeading" class="firstHeading">Alternative operators and tokens</h1> <p>C source code may be written in any 8-bit character set that includes the <a href="https://en.wikipedia.org/wiki/ISO_646" class="extiw" title="enwiki:ISO 646">ISO 646:1983</a> invariant character set, even non-ASCII ones. However, several C operators and punctuators require characters that are outside of the ISO 646 codeset: <code>{, }, [, ], #, \, ^, |, ~</code>. To be able to use character encodings where some or all of these symbols do not exist (such as the German <a href="https://en.wikipedia.org/wiki/DIN_66003" class="extiw" title="enwiki:DIN 66003">DIN 66003</a>), there are two possibilities: alternative spellings of operators that use these characters or special combinations of two or three ISO 646 compatible characters that are interpreted as if they were a single non-ISO 646 character.</p> +<h2 id="Operator_macros.28C95.29"> Operator macros<span class="t-mark-rev t-since-c95">(C95)</span> +</h2> <p>There are alternative spellings for the operators that use non-ISO646 characters, defined in <strong class="selflink"><code><iso646.h></code></strong> as macros:</p> +<table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><iso646.h></code> </th> +</tr> <tr class="t-dsc-hitem"> <th> Primary </th> <th> Alternative </th> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><code>&&</code></span></span></div> </td> <td> <code>and</code> <br> <span class="t-mark">(operator macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><code>&=</code></span></span></div> </td> <td> <code>and_eq</code> <br> <span class="t-mark">(operator macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><code>&</code></span></span></div> </td> <td> <code>bitand</code> <br> <span class="t-mark">(operator macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><code>|</code></span></span></div> </td> <td> <code>bitor</code> <br> <span class="t-mark">(operator macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><code>~</code></span></span></div> </td> <td> <code>compl</code> <br> <span class="t-mark">(operator macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><code>!</code></span></span></div> </td> <td> <code>not</code> <br> <span class="t-mark">(operator macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><code>!=</code></span></span></div> </td> <td> <code>not_eq</code> <br> <span class="t-mark">(operator macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><code>||</code></span></span></div> </td> <td> <code>or</code> <br> <span class="t-mark">(operator macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><code>|=</code></span></span></div> </td> <td> <code>or_eq</code> <br> <span class="t-mark">(operator macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><code>^</code></span></span></div> </td> <td> <code>xor</code> <br> <span class="t-mark">(operator macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><code>^=</code></span></span></div> </td> <td> <code>xor_eq</code> <br> <span class="t-mark">(operator macro)</span> </td> +</tr> </table> <p>The characters <code>&</code> and <code>!</code> are invariant under ISO-646, but alternatives are provided for the operators that use these characters anyway to accommodate even more restrictive historical charsets.</p> +<p>There is no alternative spelling (such as <code>eq</code>) for the equality operator <code>==</code> because the character <code>=</code> was present in all supported charsets.</p> +<h2 id="Alternative_tokens.28C95.29"> Alternative tokens<span class="t-mark-rev t-since-c95">(C95)</span> +</h2> <p>The following alternative tokens are part of the core language, and, in all respects of the language, each alternative token behaves exactly the same as its primary token, except for its spelling (the <a href="../preprocessor/replace" title="c/preprocessor/replace">stringification operator</a> can make the spelling visible). The two-letter alternative tokens are sometimes called "digraphs" (even though it is four letters long <code>%:%:</code> is also considered a digraph).</p> +<table class="wikitable"> <tr style="text-align: left;"> <th> Primary </th> <th> Alternative </th> +</tr> <tr> <td><code>{</code></td> <td> +<code><%</code> </td> +</tr> <tr> <td> +}</td> <td> +<code>%></code> </td> +</tr> <tr> <td><code>[</code></td> <td> +<code><:</code> </td> +</tr> <tr> <td><code>]</code></td> <td> +<code>:></code> </td> +</tr> <tr> <td><code>#</code></td> <td> +<code>%:</code> </td> +</tr> <tr> <td><code>##</code></td> <td> +<code>%:%:</code> </td> +</tr> +</table> <h2 id="Trigraphs_.28removed_in_C23.29"> Trigraphs <span class="t-mark-rev t-until-c23">(removed in C23)</span> +</h2> <p>The following three-character groups (trigraphs) are <a href="translation_phases" title="c/language/translation phases">parsed before comments and string literals are recognized</a>, and each appearance of a trigraph is replaced by the corresponding primary character:</p> +<table class="wikitable"> <tr style="text-align: left;"> <th> Primary </th> <th> Trigraph </th> +</tr> <tr> <td><code>{</code></td> <td> +<code>??<</code> </td> +</tr> <tr> <td> +}</td> <td> +<code>??></code> </td> +</tr> <tr> <td><code>[</code></td> <td> +<code>??(</code> </td> +</tr> <tr> <td><code>]</code></td> <td> +<code>??)</code> </td> +</tr> <tr> <td><code>#</code></td> <td> +<code>??=</code> </td> +</tr> <tr> <td><code>\</code></td> <td> +<code>??/</code> </td> +</tr> <tr> <td><code>^</code></td> <td> +<code>??'</code> </td> +</tr> <tr> <td><code>|</code></td> <td> +<code>??!</code> </td> +</tr> <tr> <td><code>~</code></td> <td> +<code>??-</code> </td> +</tr> +</table> <p>Because trigraphs are processed early, a comment such as <code>// Will the next line be executed?????/</code> will effectively comment out the following line, and the string literal such as <code>"What's going on??!"</code> is parsed as <code>"What's going on|"</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>Demonstrates alternative operator spellings from the <strong class="selflink"><code><iso646.h></code></strong> as well as use of digraphs and trigraphs. If command line arguments contain spaces they should be wrapped in the quotation marks, e.g., <code>"Third World!"</code>.</p> +<div class="c source-c"><pre data-language="c">%:include <stdio.h> +%:include <stdlib.h> +??=include <iso646.h> + +int main(int argc, char** argv) +??< + if (argc > 1 and argv<:1:> not_eq NULL) + <% + printf("Hello %s??/n", argv<:1:>); + %> + else + <% + printf("Hello %s??/n", argc? argv??(42??'42??) : __FILE__); + %> + + return EXIT_SUCCESS; +??></pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Hello ./a.out</pre></div> </div> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/operator_alternative" title="cpp/language/operator alternative">C++ documentation</a></span> for <span class=""><span>Alternative operator representations</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/operator_alternative" class="_attribution-link">https://en.cppreference.com/w/c/language/operator_alternative</a> + </p> +</div> diff --git a/devdocs/c/language%2Foperator_arithmetic.html b/devdocs/c/language%2Foperator_arithmetic.html new file mode 100644 index 00000000..142a5f31 --- /dev/null +++ b/devdocs/c/language%2Foperator_arithmetic.html @@ -0,0 +1,327 @@ + <h1 id="firstHeading" class="firstHeading">Arithmetic operators</h1> <p>Arithmetic operators apply standard mathematical operations to their operands.</p> +<table class="wikitable"> <tr style="text-align:center"> <th> Operator </th> <th> Operator name </th> <th> Example </th> <th> Result </th> +</tr> <tr style="text-align:center"> <td> <code>+</code> </td> <td> unary plus </td> <td> <code>+a</code> </td> <td> the value of <b>a</b> after promotions </td> +</tr> <tr style="text-align:center"> <td> <code>-</code> </td> <td> unary minus </td> <td> <code>-a</code> </td> <td> the negative of <b>a</b> </td> +</tr> <tr style="text-align:center"> <td> <code>+</code> </td> <td> addition </td> <td> <code>a + b</code> </td> <td> the addition of <b>a</b> and <b>b</b> </td> +</tr> <tr style="text-align:center"> <td> <code>-</code> </td> <td> subtraction </td> <td> <code>a - b</code> </td> <td> the subtraction of <b>b</b> from <b>a</b> </td> +</tr> <tr style="text-align:center"> <td> <code>*</code> </td> <td> product </td> <td> <code>a * b</code> </td> <td> the product of <b>a</b> and <b>b</b> </td> +</tr> <tr style="text-align:center"> <td> <code>/</code> </td> <td> division </td> <td> <code>a / b</code> </td> <td> the division of <b>a</b> by <b>b</b> </td> +</tr> <tr style="text-align:center"> <td> <code>%</code> </td> <td> remainder </td> <td> <code>a % b</code> </td> <td> the remainder of <b>a</b> divided by <b>b</b> </td> +</tr> <tr style="text-align:center"> <td> <code>~</code> </td> <td> bitwise NOT </td> <td> <code>~a</code> </td> <td> the bitwise NOT of <b>a</b> </td> +</tr> <tr style="text-align:center"> <td> <code>&</code> </td> <td> bitwise AND </td> <td> <code>a & b</code> </td> <td> the bitwise AND of <b>a</b> and <b>b</b> </td> +</tr> <tr style="text-align:center"> <td> <code>|</code> </td> <td> bitwise OR </td> <td> <code>a | b</code> </td> <td> the bitwise OR of <b>a</b> and <b>b</b> </td> +</tr> <tr style="text-align:center"> <td> <code>^</code> </td> <td> bitwise XOR </td> <td> <code>a ^ b</code> </td> <td> the bitwise XOR of <b>a</b> and <b>b</b> </td> +</tr> <tr style="text-align:center"> <td> <code><<</code> </td> <td> bitwise left shift </td> <td> <code>a << b</code> </td> <td> <b>a</b> left shifted by <b>b</b> </td> +</tr> <tr style="text-align:center"> <td> <code>>></code> </td> <td> bitwise right shift </td> <td> <code>a >> b</code> </td> <td> <b>a</b> right shifted by <b>b</b> </td> +</tr> +</table> <h3 id="Overflows"> Overflows</h3> <p>Unsigned integer arithmetic is always performed modulo 2<sup class="t-su">n</sup> where n is the number of bits in that particular integer. E.g. for <code>unsigned int</code>, adding one to <code><a href="../types/limits" title="c/types/limits">UINT_MAX</a></code> gives <code>0</code>, and subtracting one from <code>0</code> gives <code><a href="../types/limits" title="c/types/limits">UINT_MAX</a></code>.</p> +<p>When signed integer arithmetic operation overflows (the result does not fit in the result type), the behavior is undefined: it may wrap around according to the rules of the representation (typically 2's complement), it may trap on some platforms or due to compiler options (e.g. <code>-ftrapv</code> in GCC and Clang), or may be completely <a rel="nofollow" class="external text" href="http://blog.llvm.org/2011/05/what-every-c-programmer-should-know_14.html">optimized out by the compiler</a>.</p> +<h4 id="Floating-point_environment"> Floating-point environment</h4> <p>If <a href="../preprocessor/impl" title="c/preprocessor/impl"><code> #pragma STDC FENV_ACCESS</code></a> is set to <code>ON</code>, all floating-point arithmetic operators obey the current floating-point <a href="../numeric/fenv/fe_round" title="c/numeric/fenv/FE round">rounding direction</a> and report floating-point arithmetic errors as specified in <a href="../numeric/math/math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a> unless part of a <a href="initialization" title="c/language/initialization">static initializer</a> (in which case floating-point exceptions are not raised and the rounding mode is to nearest)</p> +<h4 id="Floating-point_contraction"> Floating-point contraction</h4> <p>Unless <a href="../preprocessor/impl" title="c/preprocessor/impl"><code> #pragma STDC FP_CONTRACT</code></a> is set to <code>OFF</code>, all floating-point arithmetic may be performed as if the intermediate results have infinite range and precision, that is optimizations that omit rounding errors and floating-point exceptions that would be observed if the expression was evaluated exactly as written. For example, allows the implementation of <code>(x*y) + z</code> with a single fused multiply-add CPU instruction or optimization of <code>a = x*x*x*x;</code> as <code>tmp = x*x; a = tmp*tmp</code>.</p> +<p>Unrelated to contracting, intermediate results of floating-point arithmetic may have range and precision that is different from the one indicated by its type, see <code><a href="../types/limits/flt_eval_method" title="c/types/limits/FLT EVAL METHOD">FLT_EVAL_METHOD</a></code></p> +<h3 id="Unary_arithmetic"> Unary arithmetic</h3> <p>The unary arithmetic operator expressions have the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>+</code> <span class="t-spar">expression</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>-</code> <span class="t-spar">expression</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> unary plus (promotion)</div> <div class="t-li1"> +<span class="t-li">2)</span> unary minus (negation) <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">expression</span> </td> <td> - </td> <td> expression of any <a href="arithmetic_types" title="c/language/arithmetic types">arithmetic type</a> </td> +</tr> +</table> +</div> <p>Both unary plus and unary minus first apply <a href="conversion" title="c/language/conversion">integral promotions</a> to their operand, and then</p> +<ul> +<li> unary plus returns the value after promotion </li> +<li> unary minus returns the negative of the value after promotion (except that the negative of a NaN is another NaN) </li> +</ul> <p>The type of the expression is the type after promotion, and the <a href="value_category" title="c/language/value category">value category</a> is non-lvalue.</p> +<h4 id="Notes"> Notes</h4> <p>The unary minus invokes undefined behavior due to signed integer overflow when applied to <code><a href="../types/limits" title="c/types/limits">INT_MIN</a></code>, <code><a href="../types/limits" title="c/types/limits">LONG_MIN</a></code>, or <code><a href="../types/limits" title="c/types/limits">LLONG_MIN</a></code>, on typical (2's complement) platforms.</p> +<p>In C++, unary operator <code>+</code> can also be used with other built-in types such as arrays and functions, not so in C.</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <complex.h> +#include <limits.h> + +int main(void) +{ + char c = 'a'; + printf("sizeof char: %zu sizeof int: %zu\n", sizeof c, sizeof +c); + + printf("-1, where 1 is signed: %d\n", -1); + + // Defined behavior since arithmetic is performed for unsigned integer. + // Hence, the calculation is (-1) modulo (2 raised to n) = UINT_MAX, where n is + // the number of bits of unsigned int. If unsigned int is 32-bit long, then this + // gives (-1) modulo (2 raised to 32) = 4294967295 + printf("-1, where 1 is unsigned: %u\n", -1u); + + // Undefined behavior because the mathematical value of -INT_MIN = INT_MAX + 1 + // (i.e. 1 more than the maximum possible value for signed int) + // + // printf("%d\n", -INT_MIN); + + // Undefined behavior because the mathematical value of -LONG_MIN = LONG_MAX + 1 + // (i.e. 1 more than the maximum possible value for signed long) + // + // printf("%ld\n", -LONG_MIN); + + // Undefined behavior because the mathematical value of -LLONG_MIN = LLONG_MAX + 1 + // (i.e. 1 more than the maximum possible value for signed long long) + // + // printf("%lld\n", -LLONG_MIN); + + double complex z = 1 + 2*I; + printf("-(1+2i) = %.1f%+.1f\n", creal(-z), cimag(-z)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">sizeof char: 1 sizeof int: 4 +-1, where 1 is signed: -1 +-1, where 1 is unsigned: 4294967295 +-(1+2i) = -1.0-2.0</pre></div> </div> <h3 id="Additive_operators"> Additive operators</h3> <p>The binary additive arithmetic operator expressions have the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="t-spar">lhs</span> <code>+</code> <span class="t-spar">rhs</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">lhs</span> <code>-</code> <span class="t-spar">rhs</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> addition: <span class="t-spar">lhs</span> and <span class="t-spar">rhs</span> must be one of the following <ul> +<li> both have <a href="arithmetic_types" title="c/language/arithmetic types">arithmetic types</a>, including complex and imaginary </li> +<li> one is a pointer to complete object type, the other has integer type</li> +</ul> +</div> <div class="t-li1"> +<span class="t-li">2)</span> subtraction: <span class="t-spar">lhs</span> and <span class="t-spar">rhs</span> must be one of the following <ul> +<li> both have <a href="arithmetic_types" title="c/language/arithmetic types">arithmetic types</a>, including complex and imaginary </li> +<li> <span class="t-spar">lhs</span> has pointer to complete object type, <span class="t-spar">rhs</span> has integer type </li> +<li> both are pointers to complete objects of <a href="type#Comparible_types" title="c/language/type">compatible</a> types, ignoring qualifiers</li> +</ul> +</div> <h4 id="Arithmetic_addition_and_subtraction"> Arithmetic addition and subtraction</h4> <p>If both operands have <a href="arithmetic_types" title="c/language/arithmetic types">arithmetic types</a>, then</p> +<ul> +<li> first, <a href="conversion#Usual_arithmetic_conversions" title="c/language/conversion">usual arithmetic conversions</a> are performed </li> +<li> then, the values of the operands after conversions are added or subtracted following the usual rules of mathematics (for subtraction, <span class="t-spar">rhs</span> is subtracted from <span class="t-spar">lhs</span>), except that </li> +<ul> +<li> if one operand is NaN, the result is NaN </li> +<li> infinity minus infinity is NaN and <code><a href="../numeric/fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised </li> +<li> infinity plus the negative infinity is NaN and <code><a href="../numeric/fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised </li> +</ul> +</ul> <p>Complex and imaginary addition and subtraction are defined as follows (note the result type is imaginary if both operands are imaginary and complex if one operand is real and the other imaginary, as specified by the usual arithmetic conversions):</p> +<table class="wikitable"> <tr> <th> + or - </th> <th> u </th> <th> iv </th> <th> u + iv </th> +</tr> <tr> <th> x </th> <td> x ± u </td> <td> x ± iv </td> <td> (x ± u) ± iv </td> +</tr> <tr> <th> iy </th> <td> ±u + iy </td> <td> i(y ± v) </td> <td> ±u + i(y ± v) </td> +</tr> <tr> <th> x + iy </th> <td> (x ± u) + iy </td> <td> x + i(y ± v) </td> <td> (x ± u) + i(y ± v) </td> +</tr> +</table> <div class="t-example"> <div class="c source-c"><pre data-language="c">// work in progress +// note: take part of the c/language/conversion example</pre></div> </div> <h4 id="Pointer_arithmetic"> Pointer arithmetic</h4> <ul> +<li> If the pointer <code>P</code> points at an element of an array with index <code>I</code>, then </li> +<ul> +<li> <code>P+N</code> and <code>N+P</code> are pointers that point at an element of the same array with index <code>I+N</code> </li> +<li> <code>P-N</code> is a pointer that points at an element of the same array with index <code>I-N</code> </li> +</ul> +</ul> <p>The behavior is defined only if both the original pointer and the result pointer are pointing at elements of the same array or one past the end of that array. Note that executing p-1 when p points at the first element of an array is undefined behavior and may fail on some platforms.</p> +<ul> +<li> If the pointer <code>P1</code> points at an element of an array with index <code>I</code> (or one past the end) and <code>P2</code> points at an element of the same array with index <code>J</code> (or one past the end), then </li> +<ul><li> <code>P1-P2</code> has the value equal to <code>I-J</code> and the type <code><a href="../types/ptrdiff_t" title="c/types/ptrdiff t">ptrdiff_t</a></code> (which is a signed integer type, typically half as large as the size of the largest object that can be declared) </li></ul> +</ul> <p>The behavior is defined only if the result fits in <code><a href="../types/ptrdiff_t" title="c/types/ptrdiff t">ptrdiff_t</a></code>.</p> +<p>For the purpose of pointer arithmetic, a pointer to an object that is not an element of any array is treated as a pointer to the first element of an array of size 1.</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">// work in progress +int n = 4, m = 3; +int a[n][m]; // VLA of 4 VLAs of 3 ints each +int (*p)[m] = a; // p == &a[0] +p = p + 1; // p == &a[1] (pointer arithmetic works with VLAs just the same) +(*p)[2] = 99; // changes a[1][2]</pre></div> </div> <h3 id="Multiplicative_operators"> Multiplicative operators</h3> <p>The binary multiplicative arithmetic operator expressions have the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="t-spar">lhs</span> <code>*</code> <span class="t-spar">rhs</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">lhs</span> <code>/</code> <span class="t-spar">rhs</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">lhs</span> <code>%</code> <span class="t-spar">rhs</span> </td> <td> (3) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> multiplication. <span class="t-spar">lhs</span> and <span class="t-spar">rhs</span> must have <a href="arithmetic_types" title="c/language/arithmetic types">arithmetic types</a> +</div> <div class="t-li1"> +<span class="t-li">2)</span> division. <span class="t-spar">lhs</span> and <span class="t-spar">rhs</span> must have <a href="arithmetic_types" title="c/language/arithmetic types">arithmetic types</a> +</div> <div class="t-li1"> +<span class="t-li">3)</span> remainder. <span class="t-spar">lhs</span> and <span class="t-spar">rhs</span> must have <a href="arithmetic_types" title="c/language/arithmetic types">integer types</a> +</div> <ul><li> first, <a href="conversion#Usual_arithmetic_conversions" title="c/language/conversion">usual arithmetic conversions</a> are performed. Then... </li></ul> <h4 id="Multiplication"> Multiplication</h4> <p>The binary operator * performs multiplication of its operands (after usual arithmetic conversions) following the usual arithmetic definitions, except that</p> +<ul> +<li> if one operand is a NaN, the result is a NaN </li> +<li> multiplication of infinity by zero gives NaN and <code><a href="../numeric/fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised </li> +<li> multiplication of infinity by a nonzero gives infinity (even for complex arguments) </li> +</ul> <p>Because in C, any <a href="arithmetic_types" title="c/language/arithmetic types">complex value</a> with at least one infinite part is an infinity even if its other part is a NaN, the usual arithmetic rules do not apply to complex-complex multiplication. Other combinations of floating operands follow the following table:</p> +<table class="wikitable"> <tr> <th> * </th> <th> u </th> <th> iv </th> <th> u + iv </th> +</tr> <tr> <th> x </th> <td> xu </td> <td> i(xv) </td> <td> (xu) + i(xv) </td> +</tr> <tr> <th> iy </th> <td> i(yu) </td> <td> −yv </td> <td> (−yv) + i(yu) </td> +</tr> <tr> <th> x + iy </th> <td> (xu) + i(yu) </td> <td> (−yv) + i(xv) </td> <td> <i>special rules</i> </td> +</tr> +</table> <p>Besides infinity handling, complex multiplication is not allowed to overflow intermediate results, except when <a href="../preprocessor/impl" title="c/preprocessor/impl"><code> #pragma STDC CX_LIMITED_RANGE</code></a> is set to <code>ON</code>, in which case the value may be calculated as if by (x+iy)×(u+iv) = (xu-yv)+i(yu+xv), as the programmer assumes the responsibility of limiting the range of the operands and dealing with the infinities.</p> +<p>Despite disallowing undue overflow, complex multiplication may raise spurious floating-point exceptions (otherwise it is prohibitively difficult to implement non-overflowing versions)</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdio.h> +#include <complex.h> +#include <math.h> +int main(void) +{ + + +// TODO simpler cases, take some from C++ + + + double complex z = (1 + 0*I) * (INFINITY + I*INFINITY); +// textbook formula would give +// (1+i0)(∞+i∞) ⇒ (1×∞ – 0×∞) + i(0×∞+1×∞) ⇒ NaN + I*NaN +// but C gives a complex infinity + printf("%f + i*%f\n", creal(z), cimag(z)); + +// textbook formula would give +// cexp(∞+iNaN) ⇒ exp(∞)×(cis(NaN)) ⇒ NaN + I*NaN +// but C gives ±∞+i*nan + double complex y = cexp(INFINITY + I*NAN); + printf("%f + i*%f\n", creal(y), cimag(y)); + +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">inf + i*inf +inf + i*nan</pre></div> </div> <h4 id="Division"> Division</h4> <p>The binary operator <code>/</code> divides the first operand by the second (after usual arithmetic conversions) following the usual arithmetic definitions, except that</p> +<ul> +<li> when the type after usual arithmetic conversions is an integer type, the result is the algebraic quotient (not a fraction), <span class="t-rev-inl t-until-c99"><span>rounded in implementation-defined direction</span><span><span class="t-mark-rev t-until-c99">(until C99)</span></span></span><span class="t-rev-inl t-since-c99"><span>truncated towards zero</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> </li> +<li> if one operand is a NaN, the result is a NaN </li> +<li> if the first operand is a complex infinity and the second operand is finite, then the result of the <code>/</code> operator is a complex infinity </li> +<li> if the first operand is finite and the second operand is a complex infinity, then the result of the <code>/</code> operator is a zero. </li> +</ul> <p>Because in C, any <a href="arithmetic_types" title="c/language/arithmetic types">complex value</a> with at least one infinite part as an infinity even if its other part is a NaN, the usual arithmetic rules do not apply to complex-complex division. Other combinations of floating operands follow the following table:</p> +<table class="wikitable"> <tr> <th> / </th> <th> u </th> <th> iv </th> +</tr> <tr> <th> x </th> <td> x/u </td> <td> i(−x/v) </td> +</tr> <tr> <th> iy </th> <td> i(y/u) </td> <td> y/v </td> +</tr> <tr> <th> x + iy </th> <td> (x/u) + i(y/u) </td> <td> (y/v) + i(−x/v) </td> +</tr> +</table> <p>Besides infinity handling, complex division is not allowed to overflow intermediate results, except when <a href="../preprocessor/impl" title="c/preprocessor/impl"><code> #pragma STDC CX_LIMITED_RANGE</code></a> is set to <code>ON</code>, in which case the value may be calculated as if by (x+iy)/(u+iv) = [(xu+yv)+i(yu-xv)]/(u<sup class="t-su">2</sup>+v<sup class="t-su">2</sup>), as the programmer assumes the responsibility of limiting the range of the operands and dealing with the infinities.</p> +<p>Despite disallowing undue overflow, complex division may raise spurious floating-point exceptions (otherwise it is prohibitively difficult to implement non-overflowing versions)</p> +<p>If the second operand is zero, the behavior is undefined, except that if the IEEE floating-point arithmetic is supported, and the floating-point division is taking place, then</p> +<ul> +<li> Dividing a non-zero number by ±0.0 gives the correctly-signed infinity and <code><a href="../numeric/fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_DIVBYZERO</a></code> is raised </li> +<li> Dividing 0.0 by 0.0 gives NaN and <code><a href="../numeric/fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised </li> +</ul> <h4 id="Remainder"> Remainder</h4> <p>The binary operator % yields the remainder of the division of the first operand by the second (after usual arithmetic conversions).</p> +<p>The sign of the remainder is defined in such a way that if the quotient <code>a/b</code> is representable in the result type, then <code>(a/b)*b + a%b == a</code>.</p> +<p>If the second operand is zero, the behavior is undefined.</p> +<p>If the quotient <code>a/b</code> is not representable in the result type, the behavior of both <code>a/b</code> and <code>a%b</code> is undefined (that means <code>INT_MIN%-1</code> is undefined on 2's complement systems)</p> +<p>Note: the remainder operator does not work on floating-point types, the library function <code><a href="../numeric/math/fmod" title="c/numeric/math/fmod">fmod</a></code> provides that functionality.</p> +<h3 id="Bitwise_logic"> Bitwise logic</h3> <p>The bitwise arithmetic operator expressions have the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>~</code> <span class="t-spar">rhs</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">lhs</span> <code>&</code> <span class="t-spar">rhs</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">lhs</span> <code>|</code> <span class="t-spar">rhs</span> </td> <td> (3) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">lhs</span> <code>^</code> <span class="t-spar">rhs</span> </td> <td> (4) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> bitwise NOT</div> <div class="t-li1"> +<span class="t-li">2)</span> bitwise AND</div> <div class="t-li1"> +<span class="t-li">3)</span> bitwise OR</div> <div class="t-li1"> +<span class="t-li">4)</span> bitwise XOR <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">lhs</span>, <span class="t-spar">rhs</span> </td> <td> - </td> <td> expressions of integer type </td> +</tr> +</table> +</div> <p>First, operators <code>&</code>, <code>^</code>, and <code>|</code> perform <a href="conversion#Usual_arithmetic_conversions" title="c/language/conversion">usual arithmetic conversions</a> on both operands and the operator <code>~</code> performs <a href="conversion#Integer_promotions" title="c/language/conversion">integer promotions</a> on its only operand.</p> +<p>Then, the corresponding binary logic operators are applied bitwise; that is, each bit of the result is set or cleared according to the logic operation (NOT, AND, OR, or XOR), applied to the corresponding bits of the operands.</p> +<p>Note: bitwise operators are commonly used to manipulate bit sets and bit masks.</p> +<p>Note: for unsigned types (after promotion), the expression <code>~E</code> is equivalent to the maximum value representable by the result type minus the original value of <code>E</code>.</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdint.h> + +int main(void) +{ + uint32_t a = 0x12345678; + uint16_t mask = 0x00f0; + + printf("Promoted mask:\t%#010x\n" + "Value:\t\t%#x\n" + "Setting bits:\t%#x\n" + "Clearing bits:\t%#x\n" + "Selecting bits:\t%#010x\n" + , mask + , a + , a | mask + , a & ~mask + , a & mask + ); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Promoted mask: 0x000000f0 +Value: 0x12345678 +Setting bits: 0x123456f8 +Clearing bits: 0x12345608 +Selecting bits: 0x00000070</pre></div> </div> <h3 id="Shift_operators"> Shift operators</h3> <p>The bitwise shift operator expressions have the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="t-spar">lhs</span> <code><<</code> <span class="t-spar">rhs</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">lhs</span> <code>>></code> <span class="t-spar">rhs</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> left shift of <span class="t-spar">lhs</span> by <span class="t-spar">rhs</span> bits</div> <div class="t-li1"> +<span class="t-li">2)</span> right shift of <span class="t-spar">lhs</span> by <span class="t-spar">rhs</span> bits <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">lhs</span>, <span class="t-spar">rhs</span> </td> <td> - </td> <td> expressions of integer type </td> +</tr> +</table> +</div> <p>First, <a href="conversion" title="c/language/conversion">integer promotions</a> are performed, individually, on each operand (Note: this is unlike other binary arithmetic operators, which all perform usual arithmetic conversions). The type of the result is the type of <span class="t-spar">lhs</span> after promotion.</p> +<p>The behavior is undefined if <span class="t-spar">rhs</span> is negative or is greater or equal the number of bits in the promoted <span class="t-spar">lhs</span>.</p> +<p>For unsigned <span class="t-spar">lhs</span>, the value of <code>LHS << RHS</code> is the value of LHS * 2<sup class="t-su">RHS</sup>, reduced modulo maximum value of the return type plus 1 (that is, bitwise left shift is performed and the bits that get shifted out of the destination type are discarded). For signed <span class="t-spar">lhs</span> with nonnegative values, the value of <code>LHS << RHS</code> is LHS * 2<sup class="t-su">RHS</sup> if it is representable in the promoted type of <span class="t-spar">lhs</span>, otherwise the behavior is undefined.</p> +<p>For unsigned <span class="t-spar">lhs</span> and for signed <span class="t-spar">lhs</span> with nonnegative values, the value of <code>LHS >> RHS</code> is the integer part of LHS / 2<sup class="t-su">RHS</sup>. For negative <code>LHS</code>, the value of <code>LHS >> RHS</code> is implementation-defined where in most implementations, this performs arithmetic right shift (so that the result remains negative). Thus in most implementations, right shifting a signed <code>LHS</code> fills the new higher-order bits with the original sign bit (i.e. with 0 if it was non-negative and 1 if it was negative).</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +enum {ONE=1, TWO=2}; +int main(void) +{ + char c = 0x10; + unsigned long long ulong_num = 0x123; + printf("0x123 << 1 = %#llx\n" + "0x123 << 63 = %#llx\n" // overflow truncates high bits for unsigned numbers + "0x10 << 10 = %#x\n", // char is promoted to int + ulong_num << 1, ulong_num << 63, c << 10); + long long long_num = -1000; + printf("-1000 >> 1 = %lld\n", long_num >> ONE); // implementation defined +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">0x123 << 1 = 0x246 +0x123 << 63 = 0x8000000000000000 +0x10 << 10 = 0x4000 +-1000 >> 1 = -500</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.5.3.3 Unary arithmetic operators (p: 64) </li> +<li> 6.5.5 Multiplicative operators (p: 66) </li> +<li> 6.5.6 Additive operators (p: 66-68) </li> +<li> 6.5.7 Bitwise shift operators (p: 68) </li> +<li> 6.5.10 Bitwise AND operator (p: 70) </li> +<li> 6.5.11 Bitwise exclusive OR operator (p: 70) </li> +<li> 6.5.12 Bitwise inclusive OR operator (p: 70-71) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.5.3.3 Unary arithmetic operators (p: 89) </li> +<li> 6.5.5 Multiplicative operators (p: 92) </li> +<li> 6.5.6 Additive operators (p: 92-94) </li> +<li> 6.5.7 Bitwise shift operators (p: 94-95) </li> +<li> 6.5.10 Bitwise AND operator (p: 97) </li> +<li> 6.5.11 Bitwise exclusive OR operator (p: 98) </li> +<li> 6.5.12 Bitwise inclusive OR operator (p: 98) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 6.5.3.3 Unary arithmetic operators (p: 79) </li> +<li> 6.5.5 Multiplicative operators (p: 82) </li> +<li> 6.5.6 Additive operators (p: 82-84) </li> +<li> 6.5.7 Bitwise shift operators (p: 84-85) </li> +<li> 6.5.10 Bitwise AND operator (p: 87) </li> +<li> 6.5.11 Bitwise exclusive OR operator (p: 88) </li> +<li> 6.5.12 Bitwise inclusive OR operator (p: 88) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 3.3.3.3 Unary arithmetic operators </li> +<li> 3.3.5 Multiplicative operators </li> +<li> 3.3.6 Additive operators </li> +<li> 3.3.7 Bitwise shift operators </li> +<li> 3.3.10 Bitwise AND operator </li> +<li> 3.3.11 Bitwise exclusive OR operator </li> +<li> 3.3.12 Bitwise inclusive OR operator </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <p><a href="operator_precedence" title="c/language/operator precedence">Operator precedence</a></p> +<table class="wikitable"> <tr style="text-align:center"> <th colspan="7"> Common operators </th> +</tr> <tr style="text-align:center"> <td> <a href="operator_assignment" title="c/language/operator assignment"> assignment</a> </td> <td> <a href="operator_incdec" title="c/language/operator incdec"> increment<br>decrement</a> </td> <td> <strong class="selflink"> arithmetic</strong> </td> <td> <a href="operator_logical" title="c/language/operator logical"> logical</a> </td> <td> <a href="operator_comparison" title="c/language/operator comparison"> comparison</a> </td> <td> <a href="operator_member_access" title="c/language/operator member access"> member<br>access</a> </td> <td> <a href="operator_other" title="c/language/operator other"> other</a> </td> +</tr> <tr style="text-align:center"> <td> <p><code>a = b a += b a -= b a *= b a /= b a %= b a &= b a |= b a ^= b a <<= b a >>= b</code></p> +</td> <td> <p><code>++a --a a++ a--</code></p> +</td> <td> <p><code>+a -a a + b a - b a * b a / b a % b ~a a & b a | b a ^ b a << b a >> b</code></p> +</td> <td> <p><code>!a a && b a || b</code></p> +</td> <td> <p><code>a == b a != b a < b a > b a <= b a >= b</code></p> +</td> <td> <p><code>a[b] *a &a a->b a.b</code></p> +</td> <td> <p><code>a(...) a, b (type) a a ? b : c sizeof</code><br><br> <code>_Alignof</code><br><span class="t-mark-rev t-since-c11">(since C11)</span></p> +</td> +</tr> </table> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/operator_arithmetic" title="cpp/language/operator arithmetic">C++ documentation</a></span> for <span class=""><span>Arithmetic operators</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/operator_arithmetic" class="_attribution-link">https://en.cppreference.com/w/c/language/operator_arithmetic</a> + </p> +</div> diff --git a/devdocs/c/language%2Foperator_assignment.html b/devdocs/c/language%2Foperator_assignment.html new file mode 100644 index 00000000..3d44f9ef --- /dev/null +++ b/devdocs/c/language%2Foperator_assignment.html @@ -0,0 +1,139 @@ + <h1 id="firstHeading" class="firstHeading">Assignment operators</h1> <p>Assignment and compound assignment operators are binary operators that modify the variable to their left using the value to their right.</p> +<table class="wikitable"> <tr style="text-align:center"> <th> Operator </th> <th> Operator name </th> <th> Example </th> <th> Description </th> <th> Equivalent of </th> +</tr> <tr style="text-align:center"> <td> <code>=</code> </td> <td> basic assignment </td> <td> <code>a = b</code> </td> <td> <b>a</b> becomes equal to <b>b</b> </td> <td class="table-na"> <small>N/A</small> </td> +</tr> <tr style="text-align:center"> <td> <code>+=</code> </td> <td> addition assignment </td> <td> <code>a += b</code> </td> <td> <b>a</b> becomes equal to the addition of <b>a</b> and <b>b</b> </td> <td> <code>a = a + b</code> </td> +</tr> <tr style="text-align:center"> <td> <code>-=</code> </td> <td> subtraction assignment </td> <td> <code>a -= b</code> </td> <td> <b>a</b> becomes equal to the subtraction of <b>b</b> from <b>a</b> </td> <td> <code>a = a - b</code> </td> +</tr> <tr style="text-align:center"> <td> <code>*=</code> </td> <td> multiplication assignment </td> <td> <code>a *= b</code> </td> <td> <b>a</b> becomes equal to the product of <b>a</b> and <b>b</b> </td> <td> <code>a = a * b</code> </td> +</tr> <tr style="text-align:center"> <td> <code>/=</code> </td> <td> division assignment </td> <td> <code>a /= b</code> </td> <td> <b>a</b> becomes equal to the division of <b>a</b> by <b>b</b> </td> <td> <code>a = a / b</code> </td> +</tr> <tr style="text-align:center"> <td> <code>%=</code> </td> <td> modulo assignment </td> <td> <code>a %= b</code> </td> <td> <b>a</b> becomes equal to the remainder of <b>a</b> divided by <b>b</b> </td> <td> <code>a = a % b</code> </td> +</tr> <tr style="text-align:center"> <td> <code>&=</code> </td> <td> bitwise AND assignment </td> <td> <code>a &= b</code> </td> <td> <b>a</b> becomes equal to the bitwise AND of <b>a</b> and <b>b</b> </td> <td> <code>a = a & b</code> </td> +</tr> <tr style="text-align:center"> <td> <code>|=</code> </td> <td> bitwise OR assignment </td> <td> <code>a |= b</code> </td> <td> <b>a</b> becomes equal to the bitwise OR of <b>a</b> and <b>b</b> </td> <td> <code>a = a | b</code> </td> +</tr> <tr style="text-align:center"> <td> <code>^=</code> </td> <td> bitwise XOR assignment </td> <td> <code>a ^= b</code> </td> <td> <b>a</b> becomes equal to the bitwise XOR of <b>a</b> and <b>b</b> </td> <td> <code>a = a ^ b</code> </td> +</tr> <tr style="text-align:center"> <td> <code><<=</code> </td> <td> bitwise left shift assignment </td> <td> <code>a <<= b</code> </td> <td> <b>a</b> becomes equal to <b>a</b> left shifted by <b>b</b> </td> <td> <code>a = a << b</code> </td> +</tr> <tr style="text-align:center"> <td> <code>>>=</code> </td> <td> bitwise right shift assignment </td> <td> <code>a >>= b</code> </td> <td> <b>a</b> becomes equal to <b>a</b> right shifted by <b>b</b> </td> <td> <code>a = a >> b</code> </td> +</tr> +</table> <h3 id="Simple_assignment"> Simple assignment</h3> <p>The simple assignment operator expressions have the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">lhs</span> <code>=</code> <span class="t-spar">rhs</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">lhs</span> </td> <td> - </td> <td> <a href="value_category" title="c/language/value category">modifiable lvalue</a> expression of any complete object type </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">rhs</span> </td> <td> - </td> <td> expression of any type <a href="conversion" title="c/language/conversion">implicitly convertible</a> to <span class="t-spar">lhs</span> or <a href="type#Compatible_types" title="c/language/type">compatible</a> with <span class="t-spar">lhs</span> </td> +</tr> +</table> <p>Assignment performs <a href="conversion" title="c/language/conversion">implicit conversion</a> from the value of <span class="t-spar">rhs</span> to the type of <span class="t-spar">lhs</span> and then replaces the value in the object designated by <span class="t-spar">lhs</span> with the converted value of <span class="t-spar">rhs</span>.</p> +<p>Assignment also returns the same value as what was stored in <code>lhs</code> (so that expressions such as <code>a = b = c</code> are possible). The <a href="value_category" title="c/language/value category">value category</a> of the assignment operator is non-lvalue (so that expressions such as <code>(a=b)=c</code> are invalid).</p> +<p><span class="t-spar">rhs</span> and <span class="t-spar">lhs</span> must satisfy one of the following:</p> +<ul> +<li> both <span class="t-spar">lhs</span> and <span class="t-spar">rhs</span> have <a href="type#Compatible_types" title="c/language/type">compatible</a> <a href="struct" title="c/language/struct">struct</a> or <a href="union" title="c/language/union">union</a> type, or.. </li> +<li> <span class="t-spar">rhs</span> must be <a href="conversion" title="c/language/conversion">implicitly convertible</a> to <span class="t-spar">lhs</span>, which implies </li> +<ul> +<li> both <span class="t-spar">lhs</span> and <span class="t-spar">rhs</span> have <a href="arithmetic_types" title="c/language/arithmetic types">arithmetic types</a>, in which case <span class="t-spar">lhs</span> may be <a href="volatile" title="c/language/volatile">volatile</a>-qualified<span class="t-rev-inl t-since-c11"><span> or <a href="atomic" title="c/language/atomic">atomic</a></span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> </li> +<li> both <span class="t-spar">lhs</span> and <span class="t-spar">rhs</span> have <a href="pointer" title="c/language/pointer">pointer</a> to <a href="type#Compatible_types" title="c/language/type">compatible</a> (ignoring qualifiers) types, or one of the pointers is a pointer to void, and the <a href="conversion" title="c/language/conversion">conversion</a> would not add qualifiers to the pointed-to type. <span class="t-spar">lhs</span> may be <a href="volatile" title="c/language/volatile">volatile</a><span class="t-rev-inl t-since-c99"><span> or <a href="restrict" title="c/language/restrict">restrict</a></span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>-qualified<span class="t-rev-inl t-since-c11"><span> or <a href="atomic" title="c/language/atomic">atomic</a></span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span>. </li> +<li> <span class="t-spar">lhs</span> is a (possibly qualified<span class="t-rev-inl t-since-c11"><span> or atomic</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span>) pointer and <span class="t-spar">rhs</span> is a null pointer constant such as <code><a href="../types/null" title="c/types/NULL">NULL</a></code> <span class="t-rev-inl t-since-c23"><span>or a <code><a href="../types/nullptr_t" title="c/types/nullptr t">nullptr_t</a></code> value</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> </li> +</ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <ul><li> <span class="t-spar">lhs</span> has type (possibly qualified<span class="t-rev-inl t-since-c11"><span> or atomic</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span>) <code>_Bool</code> and <span class="t-spar">rhs</span> is a pointer <span class="t-rev-inl t-since-c23"><span>or a <code><a href="../types/nullptr_t" title="c/types/nullptr t">nullptr_t</a></code> value</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> </li></ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <ul><li> <span class="t-spar">lhs</span> has type (possibly qualified or atomic) <code><a href="../types/nullptr_t" title="c/types/nullptr t">nullptr_t</a></code> and <span class="t-spar">rhs</span> has type <code><a href="../types/nullptr_t" title="c/types/nullptr t">nullptr_t</a></code> </li></ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h4 id="Notes"> Notes</h4> <p>If <span class="t-spar">rhs</span> and <span class="t-spar">lhs</span> overlap in memory (e.g. they are members of the same union), the behavior is undefined unless the overlap is exact and the types are <a href="type#Compatible_types" title="c/language/type">compatible</a>.</p> +<p>Although arrays are not assignable, an array wrapped in a struct is assignable to another object of the same (or compatible) struct type.</p> +<p>The side effect of updating <span class="t-spar">lhs</span> is <a href="eval_order" title="c/language/eval order">sequenced after</a> the value computations, but not the side effects of <span class="t-spar">lhs</span> and <span class="t-spar">rhs</span> themselves and the evaluations of the operands are, as usual, unsequenced relative to each other (so the expressions such as <code>i=++i</code>; are undefined)</p> +<p>Assignment strips extra range and precision from floating-point expressions (see <code><a href="../types/limits/flt_eval_method" title="c/types/limits/FLT EVAL METHOD">FLT_EVAL_METHOD</a></code>).</p> +<p>In C++, assignment operators are lvalue expressions, not so in C.</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +int main(void) +{ + // integers + int i = 1, j = 2, k = 3; // initialization, not assignment + + i = j = k; // values of i and j are now 3 +// (i = j) = k; // Error: lvalue required + printf("%d %d %d\n", i, j, k); + + // pointers + const char c = 'A'; // initialization; not assignment + const char *p = &c; // initialization; not assignment + const char **cpp = &p; // initialization; not assignment + +// cpp = &p; // Error: char** is not convertible to const char** + *cpp = &c; // OK, char* is convertible to const char* + printf("%c \n", **cpp); + cpp = 0; // OK, null pointer constant is convertible to any pointer + + // arrays + int arr1[2] = {1,2}, arr2[2] = {3, 4}; +// arr1 = arr2; // Error: cannot assign to an array + printf("arr1[0]=%d arr1[1]=%d arr2[0]=%d arr2[1]=%d\n", + arr1[0], arr1[1], arr2[0], arr2[1]); + + struct { int arr[2]; } sam1 = { {5, 6} }, sam2 = { {7, 8} }; + sam1 = sam2; // OK: can assign arrays wrapped in structs + + printf("%d %d \n", sam1.arr[0], sam1.arr[1]); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">3 3 3 +A +arr1[0]=1 arr1[1]=2 arr2[0]=3 arr2[1]=4 +7 8</pre></div> </div> <h3 id="Compound_assignment"> Compound assignment</h3> <p>The compound assignment operator expressions have the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">lhs</span> <span class="t-spar">op</span> <span class="t-spar">rhs</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">op</span> </td> <td> - </td> <td> one of <code>*=</code>, <code>/=</code> <code>%=</code>, <code>+=</code> <code>-=</code>, <code><<=</code>, <code>>>=</code>, <code>&=</code>, <code>^=</code>, <code>|=</code> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">lhs</span>, <span class="t-spar">rhs</span> </td> <td> - </td> <td> expressions with <a href="arithmetic_types" title="c/language/arithmetic types">arithmetic types</a> (where <span class="t-spar">lhs</span> may be qualified or atomic), except when <span class="t-spar">op</span> is <code>+=</code> or <code>-=</code>, which also accept pointer types with the same restrictions as + and - </td> +</tr> +</table> <p>The expression <span class="t-spar">lhs</span> <span class="t-spar">@=</span> <span class="t-spar">rhs</span> is exactly the same as <span class="t-spar">lhs</span> <code>=</code> <span class="t-spar">lhs</span> <span class="t-spar">@</span> <code>(</code> <span class="t-spar">rhs</span> <code>)</code>, except that <span class="t-spar">lhs</span> is evaluated only once.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <p>If <span class="t-spar">lhs</span> has <a href="atomic" title="c/language/atomic">atomic</a> type, the operation behaves as a single atomic read-modify-write operation with memory order <code><a href="../atomic/memory_order" title="c/atomic/memory order">memory_order_seq_cst</a></code>.</p> +<p>For integer atomic types, the compound assignment <code>@=</code> is equivalent to:</p> +<div class="c source-c"><pre data-language="c">T1* addr = &lhs; +T2 val = rhs; +T1 old = *addr; +T1 new; +do { new = old @ val } while (!atomic_compare_exchange_strong(addr, &old, new);</pre></div> </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +int main(void) +{ + int x = 10; + int hundred = 100; + int ten = 10; + int fifty = 50; + + printf("%d %d %d %d\n", x, hundred, ten, fifty); + + hundred *= x; + ten /= x; + fifty %= x; + + printf("%d %d %d %d\n", x, hundred, ten, fifty); + + return 0; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">10 100 10 50 +10 1000 1 0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.5.16 Assignment operators (p: 72-73) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.5.16 Assignment operators (p: 101-104) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.5.16 Assignment operators (p: 91-93) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.3.16 Assignment operators </li></ul> +</ul> <h3 id="See_Also"> See Also</h3> <p><a href="operator_precedence" title="c/language/operator precedence"> Operator precedence</a></p> +<table class="wikitable"> <tr style="text-align:center"> <th colspan="7"> Common operators </th> +</tr> <tr style="text-align:center"> <td> <strong class="selflink"> assignment</strong> </td> <td> <a href="operator_incdec" title="c/language/operator incdec"> increment<br>decrement</a> </td> <td> <a href="operator_arithmetic" title="c/language/operator arithmetic"> arithmetic</a> </td> <td> <a href="operator_logical" title="c/language/operator logical"> logical</a> </td> <td> <a href="operator_comparison" title="c/language/operator comparison"> comparison</a> </td> <td> <a href="operator_member_access" title="c/language/operator member access"> member<br>access</a> </td> <td> <a href="operator_other" title="c/language/operator other"> other</a> </td> +</tr> <tr style="text-align:center"> <td> <p><code>a = b a += b a -= b a *= b a /= b a %= b a &= b a |= b a ^= b a <<= b a >>= b</code></p> +</td> <td> <p><code>++a --a a++ a--</code></p> +</td> <td> <p><code>+a -a a + b a - b a * b a / b a % b ~a a & b a | b a ^ b a << b a >> b</code></p> +</td> <td> <p><code>!a a && b a || b</code></p> +</td> <td> <p><code>a == b a != b a < b a > b a <= b a >= b</code></p> +</td> <td> <p><code>a[b] *a &a a->b a.b</code></p> +</td> <td> <p><code>a(...) a, b (type) a a ? b : c sizeof</code><br><br> <code>_Alignof</code><br><span class="t-mark-rev t-since-c11">(since C11)</span></p> +</td> +</tr> </table> <h3 id="See_also_2"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/operator_assignment" title="cpp/language/operator assignment">C++ documentation</a></span> for <span class=""><span>Assignment operators</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/operator_assignment" class="_attribution-link">https://en.cppreference.com/w/c/language/operator_assignment</a> + </p> +</div> diff --git a/devdocs/c/language%2Foperator_comparison.html b/devdocs/c/language%2Foperator_comparison.html new file mode 100644 index 00000000..cd1e66ad --- /dev/null +++ b/devdocs/c/language%2Foperator_comparison.html @@ -0,0 +1,149 @@ + <h1 id="firstHeading" class="firstHeading">Comparison operators</h1> <p>Comparison operators are binary operators that test a condition and return <b>1</b> if that condition is logically <b>true</b> and <b>0</b> if that condition is <b>false</b>.</p> +<table class="wikitable"> <tr style="text-align:center"> <th> Operator </th> <th> Operator name </th> <th> Example </th> <th> Description </th> +</tr> <tr style="text-align:center"> <td> <code>==</code> </td> <td> equal to </td> <td> <code>a == b</code> </td> <td> <b>a</b> is equal to <b>b</b> </td> +</tr> <tr style="text-align:center"> <td> <code>!=</code> </td> <td> not equal to </td> <td> <code>a != b</code> </td> <td> <b>a</b> is not equal to <b>b</b> </td> +</tr> <tr style="text-align:center"> <td> <code><</code> </td> <td> less than </td> <td> <code>a < b</code> </td> <td> <b>a</b> is less than <b>b</b> </td> +</tr> <tr style="text-align:center"> <td> <code>></code> </td> <td> greater than </td> <td> <code>a > b</code> </td> <td> <b>a</b> is greater than <b>b</b> </td> +</tr> <tr style="text-align:center"> <td> <code><=</code> </td> <td> less than or equal to </td> <td> <code>a <= b</code> </td> <td> <b>a</b> is less than or equal to <b>b</b> </td> +</tr> <tr style="text-align:center"> <td> <code>>=</code> </td> <td> greater than or equal to </td> <td> <code>a >= b</code> </td> <td> <b>a</b> is greater than or equal to <b>b</b> </td> +</tr> +</table> <h3 id="Relational_operators"> Relational operators</h3> <p>The relational operator expressions have the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="t-spar">lhs</span> <code><</code> <span class="t-spar">rhs</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">lhs</span> <code>></code> <span class="t-spar">rhs</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">lhs</span> <code><=</code> <span class="t-spar">rhs</span> </td> <td> (3) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">lhs</span> <code>>=</code> <span class="t-spar">rhs</span> </td> <td> (4) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> less-than expression</div> <div class="t-li1"> +<span class="t-li">2)</span> greater-than expression</div> <div class="t-li1"> +<span class="t-li">3)</span> less or equal expression</div> <div class="t-li1"> +<span class="t-li">4)</span> greater or equal expression <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">lhs</span>, <span class="t-spar">rhs</span> </td> <td> - </td> <td> expressions that both have real type or both have pointer to object type </td> +</tr> +</table> +</div> <p>The type of any relational operator expression is <code>int</code>, and its value (which is not an lvalue) is <code>1</code> when the specified relationship holds true and <code>0</code> when the specified relationship does not hold.</p> +<p>If <span class="t-spar">lhs</span> and <span class="t-spar">rhs</span> are expressions of any <a href="types" title="c/language/types" class="mw-redirect">real type</a>, then</p> +<ul> +<li> <a href="conversion#Usual_arithmetic_conversions" title="c/language/conversion">usual arithmetic conversions</a> are performed </li> +<li> the values of the operands after conversion are compared in the usual mathematical sense (except that positive and negative zeroes compare equal and any comparison involving a NaN value returns zero) </li> +</ul> <p>Note that complex and imaginary numbers cannot be compared with these operators.</p> +<p>If <span class="t-spar">lhs</span> and <span class="t-spar">rhs</span> are expressions of pointer type, they must be both pointers to objects of <a href="types#Compatible_types" title="c/language/types" class="mw-redirect">compatible types</a>, except that qualifications of the pointed-to objects are ignored.</p> +<ul> +<li> a pointer to an object that is not an element of an array is treated as if it were pointing to an element of an array with one element </li> +<li> if two pointers point to the same object, or both point one past the end of the same array, they compare equal </li> +<li> if two pointers point to different elements of the same array, the one pointing at the element with the larger index compares greater. </li> +<li> if one pointer points to the element of an array and the other pointer points one past the end of the same array, the one-past-the-end pointer compares greater </li> +<li> if the two pointers point to members of the same <a href="struct" title="c/language/struct">struct</a>, the pointer to the member declared later in the struct definition compares greater than then pointer to the member declared earlier. </li> +<li> pointers to members of the same union compare equal </li> +<li> all other pointer comparisons invoke undefined behavior </li> +</ul> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <assert.h> +int main(void) +{ + assert(1 < 2); + assert(2+2 <= 4.0); // int converts to double, two 4.0's compare equal + + struct { int x,y; } s; + assert(&s.x < &s.y); // struct members compare in order of declaration + + double d = 0.0/0.0; // NaN + assert( !(d < d) ); + assert( !(d > d) ); + assert( !(d <= d) ); + assert( !(d >= d) ); + assert( !(d == d) ); + + float f = 0.1; // f = 0.100000001490116119384765625 + double g = 0.1; // g = 0.1000000000000000055511151231257827021181583404541015625 + assert(f > g); // different values +}</pre></div> </div> <h3 id="Equality_operators"> Equality operators</h3> <p>The equality operator expressions have the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="t-spar">lhs</span> <code>==</code> <span class="t-spar">rhs</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">lhs</span> <code>!=</code> <span class="t-spar">rhs</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> equal-to expression</div> <div class="t-li1"> +<span class="t-li">2)</span> not equal to expression <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">lhs</span>, <span class="t-spar">rhs</span> </td> <td> - </td> <td> expressions that <ul><li> both have any <a href="arithmetic_types" title="c/language/arithmetic types">arithmetic types</a> (including complex and imaginary) </li></ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <ul> +<li> both have type <code><a href="../types/nullptr_t" title="c/types/nullptr t">nullptr_t</a></code> </li> +<li> one has type <code><a href="../types/nullptr_t" title="c/types/nullptr t">nullptr_t</a></code> and the other is a null pointer constant </li> +</ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <ul> +<li> both are pointers to objects or functions of <a href="types#Compatible_types" title="c/language/types" class="mw-redirect">compatible</a> types, ignoring qualifiers of the pointed-to types </li> +<li> one is a pointer to object and the other is a pointer to (possibly qualified) <code>void</code> </li> +<li> one is a pointer to object or function and the other is a null pointer constant such as <code><a href="../types/null" title="c/types/NULL">NULL</a></code> <span class="t-rev-inl t-since-c23"><span>or <code>nullptr</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> </li> +</ul> </td> +</tr> +</table> +</div> <p>The type of any equality operator expression is <code>int</code>, and its value (which is not an lvalue) is <code>1</code> when the specified relationship holds true and <code>0</code> when the specified relationship does not hold.</p> +<ul><li> if both operands have arithmetic types, <a href="conversion#Usual_arithmetic_conversions" title="c/language/conversion">usual arithmetic conversions</a> are performed and the resulting values are compared in the usual mathematical sense (except that positive and negative zeroes compare equal and any comparison involving a NaN value, including equality with itself, returns zero). In particular, values of complex type are equal if their real parts compare equal and their imaginary parts compare equal. </li></ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <ul><li> two <code><a href="../types/nullptr_t" title="c/types/nullptr t">nullptr_t</a></code> value or one <code><a href="../types/nullptr_t" title="c/types/nullptr t">nullptr_t</a></code> value and a null pointer constant compare equal </li></ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <ul> +<li> if one operand is a pointer and the other is a null pointer constant, the null pointer constant is first <a href="conversion" title="c/language/conversion">converted</a> to the type of the pointer (which gives a null pointer value), and the two pointers are compared as described below </li> +<li> if one operand is a pointer and the other is a pointer to void, the non-void pointer is <a href="conversion" title="c/language/conversion">converted</a> to the pointer to void and the two pointers are compared as described below </li> +<li> two pointers compare equal if any of the following is true: </li> +<ul> +<li> they are both null pointer values of their type </li> +<li> they are both pointers to the same object or function </li> +<li> one pointer is to a struct/union/array object and the other is to its first member/any member/first element </li> +<li> they are both pointing one past the last element of the same array </li> +<li> one is one past the end of an array, and the other is at the start of a different array (of the same type) that follows the first in a larger array or in a struct with no padding </li> +</ul> +</ul> <p>(as with relational operators, pointers to objects that aren't elements of any array behave as pointers to elements of arrays of size 1)</p> +<h4 id="Notes"> Notes</h4> <p>Objects of struct type do not compare equal automatically, and comparing them with <code><a href="../string/byte/memcmp" title="c/string/byte/memcmp">memcmp</a></code> is not reliable because the padding bytes may have any values.</p> +<p>Because pointer comparison works with pointers to void, the macro <code><a href="../types/null" title="c/types/NULL">NULL</a></code> may be defined as <code>(void*)0</code> in C, although that would be invalid in C++ where void pointers do not implicitly convert to typed pointers</p> +<p>Care must be taken when comparing floating-point values for equality, because the results of many operations cannot be represented exactly and must be rounded. In practice, floating-point numbers are usually compared allowing for the difference of one or more units of the last place.</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">#include <assert.h> +int main(void) +{ + assert(2+2 == 4.0); // int converts to double, two 4.0's compare equal + + int n[2][3] = {1,2,3,4,5,6}; + int* p1 = &n[0][2]; // last element in the first row + int* p2 = &n[1][0]; // start of second row + assert(p1+1 == p2); // compare equal + + double d = 0.0/0.0; // NaN + assert( d != d ); // NaN does not equal itself + + float f = 0.1; // f = 0.100000001490116119384765625 + double g = 0.1; // g = 0.1000000000000000055511151231257827021181583404541015625 + assert(f != g); // different values +}</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.5.8 Relational operators (p: 68-69) </li> +<li> 6.5.9 Equality operators (p: 69-70) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.5.8 Relational operators (p: 95-96) </li> +<li> 6.5.9 Equality operators (p: 96-97) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 6.5.8 Relational operators (p: 85-86) </li> +<li> 6.5.9 Equality operators (p: 86-87) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 3.3.8 Relational operators </li> +<li> 3.3.9 Equality operators </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <p><a href="operator_precedence" title="c/language/operator precedence"> Operator precedence</a></p> +<table class="wikitable"> <tr style="text-align:center"> <th colspan="7"> Common operators </th> +</tr> <tr style="text-align:center"> <td> <a href="operator_assignment" title="c/language/operator assignment"> assignment</a> </td> <td> <a href="operator_incdec" title="c/language/operator incdec"> increment<br>decrement</a> </td> <td> <a href="operator_arithmetic" title="c/language/operator arithmetic"> arithmetic</a> </td> <td> <a href="operator_logical" title="c/language/operator logical"> logical</a> </td> <td> <strong class="selflink"> comparison</strong> </td> <td> <a href="operator_member_access" title="c/language/operator member access"> member<br>access</a> </td> <td> <a href="operator_other" title="c/language/operator other"> other</a> </td> +</tr> <tr style="text-align:center"> <td> <p><code>a = b a += b a -= b a *= b a /= b a %= b a &= b a |= b a ^= b a <<= b a >>= b</code></p> +</td> <td> <p><code>++a --a a++ a--</code></p> +</td> <td> <p><code>+a -a a + b a - b a * b a / b a % b ~a a & b a | b a ^ b a << b a >> b</code></p> +</td> <td> <p><code>!a a && b a || b</code></p> +</td> <td> <p><code>a == b a != b a < b a > b a <= b a >= b</code></p> +</td> <td> <p><code>a[b] *a &a a->b a.b</code></p> +</td> <td> <p><code>a(...) a, b (type) a a ? b : c sizeof</code><br><br> <code>_Alignof</code><br><span class="t-mark-rev t-since-c11">(since C11)</span></p> +</td> +</tr> </table> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/operator_comparison" title="cpp/language/operator comparison">C++ documentation</a></span> for <span class=""><span>Comparison operators</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/operator_comparison" class="_attribution-link">https://en.cppreference.com/w/c/language/operator_comparison</a> + </p> +</div> diff --git a/devdocs/c/language%2Foperator_incdec.html b/devdocs/c/language%2Foperator_incdec.html new file mode 100644 index 00000000..37060cb3 --- /dev/null +++ b/devdocs/c/language%2Foperator_incdec.html @@ -0,0 +1,98 @@ + <h1 id="firstHeading" class="firstHeading">Increment/decrement operators</h1> <p>Increment/decrement operators are unary operators that increment/decrement the value of a variable by 1.</p> +<p>They can have postfix form:</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">expr</span> <code>++</code> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">expr</span> <code>--</code> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>As well as the prefix form:</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <code>++</code> <span class="t-spar">expr</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <code>--</code> <span class="t-spar">expr</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>The operand <span class="t-spar">expr</span> of both prefix and postfix increment or decrement must be a <a href="value_category" title="c/language/value category">modifiable lvalue</a> of <a href="type" title="c/language/type">integer type</a> (including <code>_Bool</code> and enums), real floating type, or a pointer type. It may be cvr-qualified, unqualified, or <a href="atomic" title="c/language/atomic">atomic</a>.</p> +<p>The result of the postfix increment and decrement operators is the value of <span class="t-spar">expr</span>.</p> +<p>The result of the prefix increment operator is the result of adding the value <code>1</code> to the value of <span class="t-spar">expr</span>: the expression <code>++e</code> is equivalent to <code>e += 1</code>. The result of the prefix decrement operator is the result of subtracting the value <code>1</code> from the value of <span class="t-spar">expr</span>: the expression <code>--e</code> is equivalent to <code>e -= 1</code>.</p> +<p>Increment operators initiate the side-effect of adding the value <code>1</code> of appropriate type to the operand. Decrement operators initiate the side-effect of subtracting the value <code>1</code> of appropriate type from the operand. As with any other side-effects, these operations complete at or before the next <a href="eval_order" title="c/language/eval order">sequence point</a>.</p> +<div class="c source-c"><pre data-language="c">int a = 1; +int b = a++; // stores 1+a (which is 2) to a + // returns the old value of a (which is 1) + // After this line, b == 1 and a == 2 +a = 1; +int c = ++a; // stores 1+a (which is 2) to a + // returns 1+a (which is 2) + // after this line, c == 2 and a == 2</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <p>Post-increment or post-decrement on any <a href="atomic" title="c/language/atomic">atomic variable</a> is an atomic read-modify-write operation with memory order <code><a href="../atomic/memory_order" title="c/atomic/memory order">memory_order_seq_cst</a></code>.</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <p>See <a href="operator_arithmetic" title="c/language/operator arithmetic">arithmetic operators</a> for limitations on pointer arithmetic, as well as for implicit conversions applied to the operands.</p> +<h3 id="Notes"> Notes</h3> <p>Because of the side-effects involved, increment and decrement operators must be used with care to avoid undefined behavior due to violations of <a href="eval_order" title="c/language/eval order">sequencing rules</a>.</p> +<p>Increment/decrement operators are not defined for complex or imaginary types: the usual definition of adding/subtracting the real number 1 would have no effect on imaginary types, and making it add/subtract <code>i</code> for imaginaries but <code>1</code> for complex numbers would have made it handle <code>0+yi</code> different from <code>yi</code>.</p> +<p>Unlike C++ (and some implementations of C), the increment/decrement expressions are never themselves lvalues: <code>&++a</code> is invalid.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + int a = 1; + int b = 1; + + printf("original values: a == %d, b == %d\n", a, b); + printf("result of postfix operators: a++ == %d, b-- == %d\n", a++, b--); + printf("after postfix operators applied: a == %d, b == %d\n", a, b); + printf("\n"); + + // Reset a and b. + a = 1; + b = 1; + + printf("original values: a == %d, b == %d\n", a, b); + printf("result of prefix operators: ++a == %d, --b == %d\n", ++a, --b); + printf("after prefix operators applied: a == %d, b == %d\n", a, b); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">original values: a == 1, b == 1 +result of postfix operators: a++ == 1, b-- == 1 +after postfix operators applied: a == 2, b == 0 + +original values: a == 1, b == 1 +result of prefix operators: ++a == 2, --b == 0 +after prefix operators applied: a == 2, b == 0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 6.5.2.4 Postfix increment and decrement operators (p: TBD) </li> +<li> 6.5.3.1 Prefix increment and decrement operators (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.5.2.4 Postfix increment and decrement operators (p: TBD) </li> +<li> 6.5.3.1 Prefix increment and decrement operators (p: TBD) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.5.2.4 Postfix increment and decrement operators (p: 85) </li> +<li> 6.5.3.1 Prefix increment and decrement operators (p: 88) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 6.5.2.4 Postfix increment and decrement operators (p: 75) </li> +<li> 6.5.3.1 Prefix increment and decrement operators (p: 78) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 3.3.2.4 Postfix increment and decrement operators </li> +<li> 3.3.3.1 Prefix increment and decrement operators </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <p><a href="operator_precedence" title="c/language/operator precedence">Operator precedence</a></p> +<table class="wikitable"> <tr style="text-align:center"> <th colspan="7"> Common operators </th> +</tr> <tr style="text-align:center"> <td> <a href="operator_assignment" title="c/language/operator assignment"> assignment</a> </td> <td> <strong class="selflink"> increment<br>decrement</strong> </td> <td> <a href="operator_arithmetic" title="c/language/operator arithmetic"> arithmetic</a> </td> <td> <a href="operator_logical" title="c/language/operator logical"> logical</a> </td> <td> <a href="operator_comparison" title="c/language/operator comparison"> comparison</a> </td> <td> <a href="operator_member_access" title="c/language/operator member access"> member<br>access</a> </td> <td> <a href="operator_other" title="c/language/operator other"> other</a> </td> +</tr> <tr style="text-align:center"> <td> <p><code>a = b a += b a -= b a *= b a /= b a %= b a &= b a |= b a ^= b a <<= b a >>= b</code></p> +</td> <td> <p><code>++a --a a++ a--</code></p> +</td> <td> <p><code>+a -a a + b a - b a * b a / b a % b ~a a & b a | b a ^ b a << b a >> b</code></p> +</td> <td> <p><code>!a a && b a || b</code></p> +</td> <td> <p><code>a == b a != b a < b a > b a <= b a >= b</code></p> +</td> <td> <p><code>a[b] *a &a a->b a.b</code></p> +</td> <td> <p><code>a(...) a, b (type) a a ? b : c sizeof</code><br><br> <code>_Alignof</code><br><span class="t-mark-rev t-since-c11">(since C11)</span></p> +</td> +</tr> </table> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/operator_incdec" title="cpp/language/operator incdec">C++ documentation</a></span> for <span class=""><span>Increment/decrement operators</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/operator_incdec" class="_attribution-link">https://en.cppreference.com/w/c/language/operator_incdec</a> + </p> +</div> diff --git a/devdocs/c/language%2Foperator_logical.html b/devdocs/c/language%2Foperator_logical.html new file mode 100644 index 00000000..bdc70465 --- /dev/null +++ b/devdocs/c/language%2Foperator_logical.html @@ -0,0 +1,111 @@ + <h1 id="firstHeading" class="firstHeading">Logical operators</h1> <p>Logical operators apply standard boolean algebra operations to their operands.</p> +<table class="wikitable"> <tr style="text-align:center"> <th> Operator </th> <th> Operator name </th> <th> Example </th> <th> Result </th> +</tr> <tr style="text-align:center"> <td> <code>!</code> </td> <td> logical NOT </td> <td> <code>!a</code> </td> <td> the logical negation of <b>a</b> </td> +</tr> <tr style="text-align:center"> <td> <code>&&</code> </td> <td> logical AND </td> <td> <code>a && b</code> </td> <td> the logical AND of <b>a</b> and <b>b</b> </td> +</tr> <tr style="text-align:center"> <td> <code>||</code> </td> <td> logical OR </td> <td> <code>a || b</code> </td> <td> the logical OR of <b>a</b> and <b>b</b> </td> +</tr> +</table> <h3 id="Logical_NOT"> Logical NOT</h3> <p>The logical NOT expression has the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <code>!</code> <span class="t-spar">expression</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">expression</span> </td> <td> - </td> <td> an expression of any <a href="type#Type_groups" title="c/language/type">scalar type</a> </td> +</tr> +</table> <p>The logical NOT operator has type <code>int</code>. Its value is <code>0</code> if <span class="t-spar">expression</span> evaluates to a value that compares unequal to zero. Its value is <code>1</code> if <span class="t-spar">expression</span> evaluates to a value that compares equal to zero. (so <code>!E</code> is the same as <code>(0==E)</code>)</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdbool.h> +#include <stdio.h> +#include <ctype.h> +int main(void) +{ + bool b = !(2+2 == 4); // not true + printf("!(2+2==4) = %s\n", b ? "true" : "false"); + + int n = isspace('a'); // zero if 'a' is a space, nonzero otherwise + int x = !!n; // "bang-bang", common C idiom for mapping integers to [0,1] + // (all non-zero values become 1) + char *a[2] = {"nonspace", "space"}; + printf("%s\n", a[x]); // now x can be safely used as an index to array of 2 ints +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">!(2+2==4) = false +nonspace</pre></div> </div> <h3 id="Logical_AND"> Logical AND</h3> <p>The logical AND expression has the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">lhs</span> <code>&&</code> <span class="t-spar">rhs</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">lhs</span> </td> <td> - </td> <td> an expression of any scalar type </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">rhs</span> </td> <td> - </td> <td> an expression of any scalar type, which is only evaluated if <span class="t-spar">lhs</span> does not compare equal to <code>0</code> </td> +</tr> +</table> <p>The logical-AND operator has type <code>int</code> and the value <code>1</code> if both <span class="t-spar">lhs</span> and <span class="t-spar">rhs</span> compare unequal to zero. It has the value <code>0</code> otherwise (if either <span class="t-spar">lhs</span> or <span class="t-spar">rhs</span> or both compare equal to zero).</p> +<p>There is a <a href="eval_order" title="c/language/eval order">sequence point</a> after the evaluation of <span class="t-spar">lhs</span>. If the result of <span class="t-spar">lhs</span> compares equal to zero, then <span class="t-spar">rhs</span> is not evaluated at all (so-called <i>short-circuit evaluation</i>)</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdbool.h> +#include <stdio.h> +int main(void) +{ + bool b = 2+2==4 && 2*2==4; // b == true + + 1 > 2 && puts("this won't print"); + + char *p = "abc"; + if(p && *p) // common C idiom: if p is not null + // AND if p does not point at the end of the string + { // (note that thanks to short-circuit evaluation, this + // will not attempt to dereference a null pointer) + // ... // ... then do some string processing + } +}</pre></div> </div> <h3 id="Logical_OR"> Logical OR</h3> <p>The logical OR expression has the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">lhs</span> <code>||</code> <span class="t-spar">rhs</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">lhs</span> </td> <td> - </td> <td> an expression of any scalar type </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">rhs</span> </td> <td> - </td> <td> an expression of any scalar type, which is only evaluated if <span class="t-spar">lhs</span> compares equal to <code>0</code> </td> +</tr> +</table> <p>The logical-OR operator has type <code>int</code> and the value <code>1</code> if either <span class="t-spar">lhs</span> or <span class="t-spar">rhs</span> compare unequal to zero. It has value <code>0</code> otherwise (if both <span class="t-spar">lhs</span> and <span class="t-spar">rhs</span> compare equal to zero).</p> +<p>There is a <a href="eval_order" title="c/language/eval order">sequence point</a> after the evaluation of <span class="t-spar">lhs</span>. If the result of <span class="t-spar">lhs</span> compares unequal to zero, then <span class="t-spar">rhs</span> is not evaluated at all (so-called <i>short-circuit evaluation</i>)</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdbool.h> +#include <stdio.h> +#include <string.h> +#include <errno.h> +int main(void) +{ + bool b = 2+2 == 4 || 2+2 == 5; // true + printf("true or false = %s\n", b ? "true" : "false"); + + // logical OR can be used simialar to perl's "or die", as long as rhs has scalar type + fopen("test.txt", "r") || printf("could not open test.txt: %s\n", strerror(errno)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">true or false = true +could not open test.txt: No such file or directory</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.5.3.3 Unary arithmetic operators (p: 89) </li> +<li> 6.5.13 Logical AND operator (p: 99) </li> +<li> 6.5.14 Logical OR operator (p: 99) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 6.5.3.3 Unary arithmetic operators (p: 79) </li> +<li> 6.5.13 Logical AND operator (p: 89) </li> +<li> 6.5.14 Logical OR operator (p: 89) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 3.3.3.3 Unary arithmetic operators </li> +<li> 3.3.13 Logical AND operator </li> +<li> 3.3.14 Logical OR operator </li> +</ul> +</ul> <h3 id="See_Also"> See Also</h3> <p><a href="operator_precedence" title="c/language/operator precedence"> Operator precedence</a></p> +<table class="wikitable"> <tr style="text-align:center"> <th colspan="7"> Common operators </th> +</tr> <tr style="text-align:center"> <td> <a href="operator_assignment" title="c/language/operator assignment"> assignment</a> </td> <td> <a href="operator_incdec" title="c/language/operator incdec"> increment<br>decrement</a> </td> <td> <a href="operator_arithmetic" title="c/language/operator arithmetic"> arithmetic</a> </td> <td> <strong class="selflink"> logical</strong> </td> <td> <a href="operator_comparison" title="c/language/operator comparison"> comparison</a> </td> <td> <a href="operator_member_access" title="c/language/operator member access"> member<br>access</a> </td> <td> <a href="operator_other" title="c/language/operator other"> other</a> </td> +</tr> <tr style="text-align:center"> <td> <p><code>a = b a += b a -= b a *= b a /= b a %= b a &= b a |= b a ^= b a <<= b a >>= b</code></p> +</td> <td> <p><code>++a --a a++ a--</code></p> +</td> <td> <p><code>+a -a a + b a - b a * b a / b a % b ~a a & b a | b a ^ b a << b a >> b</code></p> +</td> <td> <p><code>!a a && b a || b</code></p> +</td> <td> <p><code>a == b a != b a < b a > b a <= b a >= b</code></p> +</td> <td> <p><code>a[b] *a &a a->b a.b</code></p> +</td> <td> <p><code>a(...) a, b (type) a a ? b : c sizeof</code><br><br> <code>_Alignof</code><br><span class="t-mark-rev t-since-c11">(since C11)</span></p> +</td> +</tr> </table> <h3 id="See_also_2"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/operator_logical" title="cpp/language/operator logical">C++ documentation</a></span> for <span class=""><span>Logical operators</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/operator_logical" class="_attribution-link">https://en.cppreference.com/w/c/language/operator_logical</a> + </p> +</div> diff --git a/devdocs/c/language%2Foperator_member_access.html b/devdocs/c/language%2Foperator_member_access.html new file mode 100644 index 00000000..f455d3f8 --- /dev/null +++ b/devdocs/c/language%2Foperator_member_access.html @@ -0,0 +1,170 @@ + <h1 id="firstHeading" class="firstHeading">Member access operators</h1> <p>Member access operators allow access to the members of their operands.</p> +<table class="wikitable"> <tr style="text-align:center"> <th> Operator </th> <th> Operator name </th> <th> Example </th> <th> Description </th> +</tr> <tr style="text-align:center"> <td> <code>[]</code> </td> <td> array subscript </td> <td> <code>a[b]</code> </td> <td> access the <b>b</b>th element of array <b>a</b> </td> +</tr> <tr style="text-align:center"> <td> <code>*</code> </td> <td> pointer dereference </td> <td> <code>*a</code> </td> <td> dereference the pointer <b>a</b> to access the object or function it refers to </td> +</tr> <tr style="text-align:center"> <td> <code>&</code> </td> <td> address of </td> <td> <code>&a</code> </td> <td> create a pointer that refers to the object or function <b>a</b> </td> +</tr> <tr style="text-align:center"> <td> <code>.</code> </td> <td> member access </td> <td> <code>a.b</code> </td> <td> access member <b>b</b> of <a href="struct" title="c/language/struct">struct</a> or <a href="union" title="c/language/union">union</a> <b>a</b> </td> +</tr> <tr style="text-align:center"> <td> <code>-></code> </td> <td> member access through pointer </td> <td> <code>a->b</code> </td> <td> access member <b>b</b> of <a href="struct" title="c/language/struct">struct</a> or <a href="union" title="c/language/union">union</a> pointed to by <b>a</b> </td> +</tr> +</table> <h3 id="Subscript"> Subscript</h3> <p>The array subscript expression has the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="t-spar">pointer-expression</span> <code>[</code> <span class="t-spar">integer-expression</span> <code>]</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">integer-expression</span> <code>[</code> <span class="t-spar">pointer-expression</span> <code>]</code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">pointer-expression</span> </td> <td> - </td> <td> an <a href="expressions" title="c/language/expressions">expression</a> of type pointer to complete object </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">integer-expression</span> </td> <td> - </td> <td> an <a href="expressions" title="c/language/expressions">expression</a> of integer type </td> +</tr> +</table> <p>The subscript operator expression is an <a href="value_category" title="c/language/value category">lvalue expression</a> whose type is the type of the object pointed to by <span class="t-spar">pointer-expression</span>.</p> +<p>By definition, the subscript operator <code>E1[E2]</code> is exactly identical to <code>*((E1)+(E2))</code>. If <span class="t-spar">pointer-expression</span> is an array expression, it undergoes <a href="conversion" title="c/language/conversion">lvalue-to-rvalue conversion</a> and becomes a pointer to the first element of the array.</p> +<p>Due to the definition of the <a href="operator_arithmetic" title="c/language/operator arithmetic">addition between a pointer and an integer</a>, the result is the element of the array with the index equal to the result of <span class="t-spar">integer-expression</span> (or, if <span class="t-spar">pointer-expression</span> was pointing at ith element of some array, the index of the result is i plus the result of <span class="t-spar">integer-expression</span>)</p> +<p>Note: see <a href="array" title="c/language/array">array</a> for the details on multidimensional arrays.</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +int main(void) +{ + int a[3] = {1,2,3}; + printf("%d %d\n", a[2], // n == 3 + 2[a]); // same, n == 3 + a[2] = 7; // subscripts are lvalues + + int n[2][3] = {{1,2,3},{4,5,6}}; + int (*p)[3] = &n[1]; // elements of n are arrays + printf("%d %d %d\n", (*p)[0], p[0][1], p[0][2]); // access n[1][] via p + int x = n[1][2]; // applying [] again to the array n[1] + printf("%d\n", x); + + printf("%c %c\n", "abc"[2], 2["abc"]); // string literals are arrays too +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">3 3 +4 5 6 +6 +c c</pre></div> </div> <h3 id="Dereference"> Dereference</h3> <p>The <i>dereference</i> or <i>indirection</i> expression has the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <code>*</code> <span class="t-spar">pointer-expression</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">pointer-expression</span> </td> <td> - </td> <td> an <a href="expressions" title="c/language/expressions">expression</a> of any pointer type </td> +</tr> +</table> <p>If <span class="t-spar">pointer-expression</span> is a pointer to function, the result of the dereference operator is a function designator for that function.</p> +<p>If <span class="t-spar">pointer-expression</span> is a pointer to object, the result is an <a href="value_category" title="c/language/value category">lvalue expression</a> that designates the pointed-to object.</p> +<p>Dereferencing a null pointer, a pointer to an object outside of its lifetime (a dangling pointer), a misaligned pointer, or a pointer with indeterminate value is undefined behavior, except when the dereference operator is nullified by applying the address-of operator to its result, as in <code>&*E</code>.</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +int main(void) +{ + int n = 1; + int* p = &n; + printf("*p = %d\n", *p); // the value of *p is what's stored in n + *p = 7; // *p is lvalue + printf("*p = %d\n", *p); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">*p = 1 +*p = 7</pre></div> </div> <h3 id="Address_of"> Address of</h3> <p>The address-of expression has the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>&</code> <span class="t-spar">function</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>&</code> <span class="t-spar">lvalue-expression</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>&</code> <code>*</code> <span class="t-spar">expression</span> </td> <td> (3) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>&</code> <span class="t-spar">expression</span> <code>[</code> <span class="t-spar">expression</span> <code>]</code> </td> <td> (4) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> address of a function</div> <div class="t-li1"> +<span class="t-li">2)</span> address of an object</div> <div class="t-li1"> +<span class="t-li">3)</span> special case: <code>&</code> and <code>*</code> cancel each other, neither one is evaluated</div> <div class="t-li1"> +<span class="t-li">4)</span> special case: <code>&</code> and the <code>*</code> that is implied in <code>[]</code> cancel each other, only the addition implied in <code>[]</code> is evaluated.</div> <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">lvalue-expression</span> </td> <td> - </td> <td> an <a href="value_category" title="c/language/value category">lvalue</a> expression of any type that is not a <a href="bit_field" title="c/language/bit field">bit-field</a> and does not have <a href="storage_duration" title="c/language/storage duration">register</a> storage class </td> +</tr> +</table> <p>The address-of operator produces the <a href="value_category" title="c/language/value category">non-lvalue</a> address of its operand, suitable for initializing a pointer to the type of the operand. If the operand is a function designator <span class="t-v">(1)</span>, the result is a pointer to function. If the operand is an object <span class="t-v">(2)</span>, the result is a pointer to object.</p> +<p>If the operand is the dereference operator, no action is taken (so it's okay to apply &* to a null pointer), except that the result is not an lvalue.</p> +<p>If the operand is an array index expression, no action is taken other than the array-to-pointer conversion and the addition, so &a[N] is valid for an array of size N (obtaining a pointer one past the end is okay, dereferencing it is not, but dereference cancels out in this expression).</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">int f(char c) { return c;} +int main(void) +{ + int n = 1; + int *p = &n; // address of object n + int (*fp)(char) = &f; // address of function f + int a[3] = {1,2,3}; + int *beg=a, *end=&a[3]; // same as end = a+3 +}</pre></div> </div> <h3 id="Member_access"> Member access</h3> <p>The member access expression has the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">expression</span> <code>.</code> <span class="t-spar">member-name</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">expression</span> </td> <td> - </td> <td> an expression of <a href="struct" title="c/language/struct">struct</a> or <a href="union" title="c/language/union">union</a> type </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">member-name</span> </td> <td> - </td> <td> an <a href="identifier" title="c/language/identifier">identifier</a> that names a member of the struct or union designated by <span class="t-spar">expression</span> </td> +</tr> +</table> <p>The member access expression designates the named member of the <a href="struct" title="c/language/struct">struct</a> or <a href="union" title="c/language/union">union</a> designated by its left operand. It has the same <a href="value_category" title="c/language/value category">value category</a> as its left operand.</p> +<p>If the left operand is <a href="const" title="c/language/const">const</a> or <a href="volatile" title="c/language/volatile">volatile</a> qualified, the result is also qualified. If the left operand is <a href="atomic" title="c/language/atomic">atomic</a>, the behavior is undefined.</p> +<p>Note: besides identifiers that name objects of struct or union type, the following expressions may have struct or union types: <a href="operator_assignment" title="c/language/operator assignment">assignment</a>, <a href="operator_other#Function_call" title="c/language/operator other">function call</a>, <a href="operator_other#Comma_operator" title="c/language/operator other">comma operator</a>, <a href="operator_other#Conditional_operator" title="c/language/operator other">conditional operator</a>, and <a href="compound_literal" title="c/language/compound literal">compound literal</a>.</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +struct s {int x;}; +struct s f(void) { return (struct s){1}; } +int main(void) +{ + struct s s; + s.x = 1; // ok, changes the member of s + int n = f().x; // f() is an expression of type struct s +// f().x = 1; // Error: this member access expression is not an lvalue + + const struct s sc; +// sc.x = 3; // Error: sc.x is const, can't be assigned + + union { int x; double d; } u = {1}; + u.d = 0.1; // changes the active member of the union +}</pre></div> </div> <h3 id="Member_access_through_pointer"> Member access through pointer</h3> <p>The member access expression has the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">expression</span> <code>-></code> <span class="t-spar">member-name</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">expression</span> </td> <td> - </td> <td> an expression of type <a href="pointer" title="c/language/pointer">pointer</a> to <a href="struct" title="c/language/struct">struct</a> or <a href="union" title="c/language/union">union</a> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">member-name</span> </td> <td> - </td> <td> an <a href="identifier" title="c/language/identifier">identifier</a> that names a member of the struct or union pointed by <span class="t-spar">expression</span> </td> +</tr> +</table> <p>The member access through pointer expression designates the named member of the <a href="struct" title="c/language/struct">struct</a> or <a href="union" title="c/language/union">union</a> type pointed to by its left operand. Its value category is always <a href="value_category" title="c/language/value category">lvalue</a></p> +<p>If the type pointed to by the left operand is <a href="const" title="c/language/const">const</a> or <a href="volatile" title="c/language/volatile">volatile</a> qualified, the result is also qualified. If the type pointed to by the left operand is <a href="atomic" title="c/language/atomic">atomic</a>, the behavior is undefined.</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +struct s {int x;}; +int main(void) +{ + struct s s={1}, *p = &s; + p->x = 7; // changes the value of s.x through the pointer + printf("%d\n", p->x); // prints 7 +}</pre></div> </div> <h3 id="Defect_reports"> Defect reports</h3> <p>The following behavior-changing defect reports were applied retroactively to previously published C standards.</p> +<table class="dsctable"> <tr> <th>DR </th> <th>Applied to </th> <th>Behavior as published </th> <th>Correct behavior </th> +</tr> <tr> <td> +<a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/dr_076.html">DR 076</a> </td> <td>C89 </td> <td>unnessary indirection could not be cancelled by <code>&</code> </td> <td>made cancellable </td> +</tr> +</table> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.5.2.1 Array subscripting (p: 57-58) </li> +<li> 6.5.2.3 Structure and union members (p: 58-59) </li> +<li> 6.5.3.2 Address and indirection operators (p: 59-61) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.5.2.1 Array subscripting (p: 80) </li> +<li> 6.5.2.3 Structure and union members (p: 82-84) </li> +<li> 6.5.3.2 Address and indirection operators (p: 88-89) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 6.5.2.1 Array subscripting (p: 70) </li> +<li> 6.5.2.3 Structure and union members (p: 72-74) </li> +<li> 6.5.3.2 Address and indirection operators (p: 78-79) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 3.3.2.1 Array subscripting </li> +<li> 3.3.2.3 Structure and union members </li> +<li> 3.3.3.2 Address and indirection operators </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <ul><li> <a href="operator_precedence" title="c/language/operator precedence">Operator precedence</a> </li></ul> <table class="wikitable"> <tr style="text-align:center"> <th colspan="7"> Common operators </th> +</tr> <tr style="text-align:center"> <td> <a href="operator_assignment" title="c/language/operator assignment"> assignment</a> </td> <td> <a href="operator_incdec" title="c/language/operator incdec"> increment<br>decrement</a> </td> <td> <a href="operator_arithmetic" title="c/language/operator arithmetic"> arithmetic</a> </td> <td> <a href="operator_logical" title="c/language/operator logical"> logical</a> </td> <td> <a href="operator_comparison" title="c/language/operator comparison"> comparison</a> </td> <td> <strong class="selflink"> member<br>access</strong> </td> <td> <a href="operator_other" title="c/language/operator other"> other</a> </td> +</tr> <tr style="text-align:center"> <td> <p><code>a = b a += b a -= b a *= b a /= b a %= b a &= b a |= b a ^= b a <<= b a >>= b</code></p> +</td> <td> <p><code>++a --a a++ a--</code></p> +</td> <td> <p><code>+a -a a + b a - b a * b a / b a % b ~a a & b a | b a ^ b a << b a >> b</code></p> +</td> <td> <p><code>!a a && b a || b</code></p> +</td> <td> <p><code>a == b a != b a < b a > b a <= b a >= b</code></p> +</td> <td> <p><code>a[b] *a &a a->b a.b</code></p> +</td> <td> <p><code>a(...) a, b (type) a a ? b : c sizeof</code><br><br> <code>_Alignof</code><br><span class="t-mark-rev t-since-c11">(since C11)</span></p> +</td> +</tr> </table> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/operator_member_access" title="cpp/language/operator member access">C++ documentation</a></span> for <span class=""><span>Member access operators</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/operator_member_access" class="_attribution-link">https://en.cppreference.com/w/c/language/operator_member_access</a> + </p> +</div> diff --git a/devdocs/c/language%2Foperator_other.html b/devdocs/c/language%2Foperator_other.html new file mode 100644 index 00000000..195b38dd --- /dev/null +++ b/devdocs/c/language%2Foperator_other.html @@ -0,0 +1,225 @@ + <h1 id="firstHeading" class="firstHeading">Other operators</h1> <p>A collection of operators that do not fit into any of the other major categories.</p> +<table class="wikitable"> <tr style="text-align:center"> <th> Operator </th> <th> Operator name </th> <th> Example </th> <th> Description </th> +</tr> <tr style="text-align:center"> <td> <code>(...)</code> </td> <td> <a href="#Function_call">function call</a> </td> <td> <code>f(...)</code> </td> <td> call the function <b>f</b>(), with zero or more arguments </td> +</tr> <tr style="text-align:center"> <td> <code>,</code> </td> <td> <a href="#Comma_operator">comma operator</a> </td> <td> <code>a, b</code> </td> <td> evaluate expression <b>a</b>, disregard its return value and complete any side-effects, then evaluate expression <b>b</b>, returning the type and the result of this evaluation </td> +</tr> <tr style="text-align:center"> <td> <code>(type)</code> </td> <td> <a href="cast" title="c/language/cast">type cast</a> </td> <td> <code>(type)a</code> </td> <td> cast the type of <b>a</b> to <b>type</b> </td> +</tr> <tr style="text-align:center"> <td> <code>? :</code> </td> <td> <a href="#Conditional_operator">conditional operator</a> </td> <td> <code>a ? b : c</code> </td> <td> if <b>a</b> is logically true (does not evaluate to zero) then evaluate expression <b>b</b>, otherwise evaluate expression <b>c</b> </td> +</tr> <tr style="text-align:center"> <td> <code>sizeof</code> </td> <td> <a href="sizeof" title="c/language/sizeof">sizeof operator</a> </td> <td> <code>sizeof a</code> </td> <td> the size in bytes of <b>a</b> </td> +</tr> <tr style="text-align:center"> <td> <code>_Alignof</code><br><span class="t-mark-rev t-since-c11">(since C11)</span> </td> <td> <a href="_alignof" title="c/language/ Alignof">_Alignof operator</a> </td> <td> <code>_Alignof(type)</code> </td> <td> the alignment required of <b>type</b> </td> +</tr> <tr style="text-align:center"> <td> <code>typeof</code> </td> <td> <a href="typeof" title="c/language/typeof">typeof operators</a> </td> <td> <code>typeof(a)</code> </td> <td> the type of <b>a</b> </td> +</tr> +</table> <h3 id="Function_call"> Function call</h3> <p>The function call expression has the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">expression</span> <code>(</code> <span class="t-spar">argument-list</span> <span class="t-mark">(optional)</span> <code>)</code> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">expression</span> </td> <td> - </td> <td> any expression of pointer-to-function type (after <a href="conversion#Lvalue_conversions" title="c/language/conversion">lvalue conversions</a>) </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">argument-list</span> </td> <td> - </td> <td> comma-separated list of expressions (which cannot be comma operators) of any complete object type. May be omitted when calling functions that take no arguments. </td> +</tr> +</table> <p>The behavior of the function call expression depends on whether the prototype of the function being called is <a href="scope" title="c/language/scope">in scope</a> at the point of call.</p> +<h4 id="Call_to_a_function_with_a_prototype"> Call to a function with a prototype</h4> <div class="t-li1"> +<span class="t-li">1)</span> The number of parameters must equal the number of arguments (unless the ellipsis parameter is used).</div> <div class="t-li1"> +<span class="t-li">2)</span> The type of each parameter must be a type such that <a href="conversion" title="c/language/conversion">implicit conversion as if by assignment</a> exists that converts the unqualified type of the corresponding argument to the type of the parameter.</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> Additionally, for every parameter of <a href="array" title="c/language/array">array type</a> that uses the keyword <code>static</code> between <code>[</code> and <code>]</code>, the argument expression must designate a pointer to the element of an array with at least that many elements as specified in the size expression of the parameter. </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <div class="t-li1"> +<span class="t-li">3)</span> The arguments are evaluated <a href="eval_order" title="c/language/eval order">in unspecified order and without sequencing</a>.</div> <div class="t-li1"> +<span class="t-li">4)</span> <a href="operator_assignment" title="c/language/operator assignment">Assignment</a> is performed to copy the value of each argument to the corresponding function parameter, ignoring any type qualifiers on the parameter type and its possibly recursive elements or members, if any (note: the function can modify its parameters, and those changes do not affect the arguments; C function calls are only call-by-value). <ul><li> if there is a <a href="variadic" title="c/language/variadic">trailing ellipsis</a> parameter, <a href="https://en.cppreference.com/mwiki/index.php?title=conversion&action=edit&redlink=1" class="new" title="conversion (page does not exist)">Default argument promotions</a> are performed on the remaining arguments, which are made available to <code>va_list</code>.</li></ul> +</div> <div class="t-li1"> +<span class="t-li">5)</span> Function is executed, and the value it returns becomes the value of the function call expression (if the function returns void, the function call expression is a void expression) <div class="c source-c"><pre data-language="c">void f(char* p, int x) {} +int main(void) +{ + f("abc", 3.14); // array to pointer and float to int conversions +}</pre></div> +</div> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <h4 id="Call_to_a_function_without_a_prototype"> Call to a function without a prototype</h4> <span class="t-li">1)</span> The arguments are evaluated <a href="eval_order" title="c/language/eval order">in unspecified order and without sequencing</a>. <span class="t-li">2)</span> <a href="conversion#Default_argument_promotions" title="c/language/conversion">Default argument promotions</a> are performed on every argument expression. <span class="t-li">3)</span> <a href="operator_assignment" title="c/language/operator assignment">Assignment</a> is performed to copy the value of each argument to the corresponding function parameter, ignoring any type qualifiers on the parameter type and its possibly recursive elements or members, if any. <span class="t-li">4)</span> Function is executed, and the value it returns becomes the value of the function call expression (if the function returns void, the function call expression is a void expression) <div class="c source-c"><pre data-language="c">void f(); // no prototype +int main(void) +{ + f(1, 1.0f); // UB unless f is defined to take an int and a double +} +void f(int a, double c) {}</pre></div> <p>The behavior of a function call to a function without a prototype is undefined if</p> +<ul> +<li> the number of arguments does not match the number of parameters. </li> +<li> the promoted types of the arguments are not <a href="type#Compatible_types" title="c/language/type">compatible</a> with the promoted types of the parameters except that </li> +<ul> +<li> signed and unsigned versions of the same integer type are considered compatible if the value of the argument is representable by both types. </li> +<li> pointers to void and pointers to (possibly cvr-qualified) character types are considered compatible </li> +</ul> +</ul> </td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> </table> <h4 id="Notes"> Notes</h4> <p>The evaluations of <span class="t-spar">expression</span> that designates the function to be called and all arguments are <a href="eval_order" title="c/language/eval order">unsequenced</a> with respect to each other (but there is a sequence point before the body of the function begins executing)</p> +<div class="c source-c"><pre data-language="c">(*pf[f1()]) (f2(), f3() + f4()); // f1, f2, f3, f4 may be called in any order</pre></div> <p>Although function call is only defined for pointers to functions, it works with function designators due to the <a href="conversion#Function_to_pointer_conversion" title="c/language/conversion">function-to-pointer implicit conversion</a>.</p> +<div class="c source-c"><pre data-language="c">int f(void) { return 1; } +int (*pf)(void) = f; + +int main(void) +{ + f(); // convert f to pointer, then call + (&f)(); // create a pointer to function, then call + + pf(); // call the function + (*pf)(); // obtain the function designator, convert to pointer, then calls + + (****f)(); // convert to pointer, obtain the function, repeat 4x, then call + (****pf)(); // also OK +}</pre></div> <p>Functions that ignore unused arguments, such as <code><a href="../io/fprintf" title="c/io/fprintf">printf</a></code>, must be called with a prototype in scope (the prototype of such functions necessarily uses the <a href="variadic" title="c/language/variadic">trailing ellipsis</a> parameter) to avoid invoking undefined behavior.</p> +<p>The current standard wording of the semantics of preparing function parameters is defective, because it specifies that parameters are assigned from arguments while calling, which incorrectly rejects const-qualified parameter or member types, and inappropriately applies the semantics of volatile which is unimplementable for function parameters on many platforms. A post-C11 defect report <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2396.htm#dr_427">DR427</a> proposed change of such semantics from assignment to initialization, but was closed as not-a-defect.</p> +<table class="t-rev-begin"> <tr class="t-rev t-until-c99"> +<td> <p>A function call expression where <span class="t-spar">expression</span> consists entirely of an identifier and that identifier is undeclared acts as though the identifier is declared as</p> +<div class="c source-c"><pre data-language="c">extern int identifier(); // returns int and has no prototype</pre></div> <p>So the following complete program is valid C89:</p> +<div class="c source-c"><pre data-language="c">main() +{ + int n = atoi("123"); // implicitly declares atoi as int atoi() +}</pre></div> </td> <td><span class="t-mark-rev t-until-c99">(until C99)</span></td> +</tr> </table> <h3 id="Comma_operator"> Comma operator</h3> <p>The comma operator expression has the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">lhs</span> <code>,</code> <span class="t-spar">rhs</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">lhs</span> </td> <td> - </td> <td> any expression </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">rhs</span> </td> <td> - </td> <td> any expression other than another comma operator (in other words, comma operator's <a href="operator_precedence" title="c/language/operator precedence">associativity</a> is left-to-right) </td> +</tr> +</table> <p>First, the left operand, <span class="t-spar">lhs</span>, is evaluated and its result value is discarded.</p> +<p>Then, a <a href="eval_order" title="c/language/eval order">sequence point</a> takes place, so that all side effects of <span class="t-spar">lhs</span> are complete.</p> +<p>Then, the right operand, <span class="t-spar">rhs</span>, is evaluated and its result is returned by the comma operator as a <a href="value_category" title="c/language/value category">non-lvalue</a>.</p> +<h3 id="Notes_2"> Notes</h3> <p>The type of the <span class="t-spar">lhs</span> may be <code>void</code> (that is, it may be a call to a function that returns <code>void</code>, or it can be an expression <a href="cast" title="c/language/cast">cast</a> to <code>void</code>)</p> +<p>The comma operator may be lvalue in C++, but never in C</p> +<p>The comma operator may return a struct (the only other expressions that return structs are compound literals, function calls, assignments, and the conditional operator)</p> +<p>In the following contexts, the comma operator cannot appear at the top level of an expression because the comma has a different meaning:</p> +<ul> +<li> argument list in a function call </li> +<li> initializer expression or <a href="initialization" title="c/language/initialization">initializer list</a> </li> +<li> <a href="generic" title="c/language/generic">generic selection</a> </li> +</ul> <p>If the comma operator has to be used in such context, it must be parenthesized:</p> +<div class="c source-c"><pre data-language="c">// int n = 2,3; // error, comma assumed to begin the next declarator +// int a[2] = {1,2,3}; // error: more initializers than elements +int n = (2,3), a[2] = {(1,2),3}; // OK + +f(a, (t=3, t+2), c); // OK, first, stores 3 in t, then calls f with three arguments</pre></div> <p>Top-level comma operator is also disallowed in array bounds</p> +<div class="c source-c"><pre data-language="c">// int a[2,3]; // error +int a[(2,3)]; // OK, VLA array of size 3 (VLA because (2,3) is not a constant expression)</pre></div> <p>Comma operator is not allowed in <a href="constant_expression" title="c/language/constant expression">constant expressions</a>, regardless of whether it's on the top level or not</p> +<div class="c source-c"><pre data-language="c">// static int n = (1,2); // Error: constant expression cannot call the comma operator</pre></div> <h3 id="Cast_operator"> Cast operator</h3> <p>See <a href="cast" title="c/language/cast">cast operator</a></p> +<h3 id="Conditional_operator"> Conditional operator</h3> <p>The conditional operator expression has the form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">condition</span> <code>?</code> <span class="t-spar">expression-true</span> <code>:</code> <span class="t-spar">expression-false</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">condition</span> </td> <td> - </td> <td> an expression of scalar type </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">expression-true</span> </td> <td> - </td> <td> the expression that will be evaluated if condition compares unequal to zero </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">expression-false</span> </td> <td> - </td> <td> the expression that will be evaluated if condition compares equal to zero </td> +</tr> +</table> <p>Only the following expressions are allowed as <span class="t-spar">expression-true</span> and <span class="t-spar">expression-false</span></p> +<ul> +<li> two expressions of any <a href="arithmetic_types" title="c/language/arithmetic types">arithmetic type</a> </li> +<li> two expressions of the same <a href="struct" title="c/language/struct">struct</a> or <a href="union" title="c/language/union">union</a> type </li> +<li> two expressions of void type </li> +<li> two expressions of pointer type, pointing to types that are <a href="type#Compatible_types" title="c/language/type">compatible</a>, ignoring cvr-qualifiers </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <ul><li> two expressions of <code><a href="../types/nullptr_t" title="c/types/nullptr t">nullptr_t</a></code> type </li></ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <ul> +<li> one expression is a pointer and the other is the null pointer constant (such as <code><a href="../types/null" title="c/types/NULL">NULL</a></code>)<span class="t-rev-inl t-since-c23"><span>or a <code><a href="../types/nullptr_t" title="c/types/nullptr t">nullptr_t</a></code> value</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> </li> +<li> one expression is a pointer to object and the other is a pointer to void (possibly qualified) </li> +</ul> <div class="t-li1"> +<span class="t-li">1)</span> First, evaluates <span class="t-spar">condition</span>. There is a <a href="eval_order" title="c/language/eval order">sequence point</a> after this evaluation.</div> <div class="t-li1"> +<span class="t-li">2)</span> If the result of <span class="t-spar">condition</span> compares unequal to zero, executes <span class="t-spar">expression-true</span>, otherwise executes <span class="t-spar">expression-false</span> +</div> <div class="t-li1"> +<span class="t-li">3)</span> Performs a <a href="conversion" title="c/language/conversion">conversion</a> from the result of the evaluation to the <i>common type</i>, defined as follows:</div> <div class="t-li2"> +<span class="t-li">1)</span> if the expressions have arithmetic type, the common type is the type after <a href="conversion#Usual_arithmetic_conversions" title="c/language/conversion">usual arithmetic conversions</a> +</div> <div class="t-li2"> +<span class="t-li">2)</span> if the expressions have struct/union type, the common type is that struct/union type</div> <div class="t-li2"> +<span class="t-li">3)</span> if the expressions are both void, the entire conditional operator expression is a void expression</div> <div class="t-li2"> +<span class="t-li">4)</span> if one is a pointer and the other is a null pointer constant<span class="t-rev-inl t-since-c23"><span>or a <code><a href="../types/nullptr_t" title="c/types/nullptr t">nullptr_t</a></code> value</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, the type is the type of that pointer</div> <div class="t-li2"> +<span class="t-li">5)</span> if both are pointers, the result is the pointer to the type that combines cvr-qualifiers of both pointed-to types (that is, if one is <code>const int*</code> and the other is <code>volatile int*</code>, the result is <code>const volatile int*</code>), and if the types were different, the pointed-to type is the <a href="types#Composite_type" title="c/language/types" class="mw-redirect">composite type</a>.</div> <div class="t-li2"> +<span class="t-li">6)</span> if one is a pointer to void, the result is a pointer to void with combined cvr-qualifiers</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <span class="t-li">7)</span> if both have <code><a href="../types/nullptr_t" title="c/types/nullptr t">nullptr_t</a></code> type, the common type is also <code><a href="../types/nullptr_t" title="c/types/nullptr t">nullptr_t</a></code> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <div class="c source-c"><pre data-language="c">#define ICE(x) (sizeof(*(1 ? ((void*)((x) * 0l)) : (int*)1))) + +// if x is an Integer Constant Expression then macro expands to + +sizeof(*(1 ? NULL : (int *) 1)) // (void *)((x)*0l)) -> NULL + +// according to point (4) this further converts into + +sizeof(int) + +// if x is not an Integer Constant Expression then macro expands to +// according to point (6) + +(sizeof(*(void *)(x)) // Error due incomplete type</pre></div> <h4 id="Notes_3"> Notes</h4> <p>The conditional operator is never an <a href="value_category" title="c/language/value category">lvalue expression</a>, although it may return objects of struct/union type. The only other expressions that may return structs are <a href="operator_assignment" title="c/language/operator assignment">assignment</a>, <a href="#Comma_operator">comma</a>, <a href="#Function_call">function call</a>, and <a href="compound_literal" title="c/language/compound literal">compound literal</a>.</p> +<p>Note that in C++, it may be an lvalue expression.</p> +<p>See <a href="operator_precedence" title="c/language/operator precedence">operator precedence</a> for the details on the relative precedence of this operator and assignment.</p> +<p>Conditional operator has right-to-left associativity, which allows chaining</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">#include <assert.h> + +enum vehicle { bus, airplane, train, car, horse, feet }; + +enum vehicle choose(char arg) +{ + return arg == 'B' ? bus : + arg == 'A' ? airplane : + arg == 'T' ? train : + arg == 'C' ? car : + arg == 'H' ? horse : + feet ; +} + +int main(void) +{ + assert(choose('H') == horse && choose('F') == feet); +}</pre></div> </div> <h3 id="sizeof_operator"> <code>sizeof</code> operator</h3> <p>See <a href="sizeof" title="c/language/sizeof">sizeof operator</a></p> +<h3 id="Alignof_operator"> <code>_Alignof</code> operator</h3> <p>See <a href="_alignof" title="c/language/ Alignof">_Alignof operator</a></p> +<h3 id="typeof_operators"> <code>typeof</code> operators</h3> <p>See <a href="typeof" title="c/language/typeof">typeof operators</a></p> +<h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 6.5.2.2 Function calls (p: TBD) </li> +<li> 6.5.3.4 The sizeof and _Alignof operators (p: TBD) </li> +<li> 6.5.4 Cast operators (p: TBD) </li> +<li> 6.5.15 Conditional operator (p: TBD) </li> +<li> 6.5.17 Comma operator (p: TBD) </li> +<li> 6.7.3.5 Typeof specifiers (p: 115-118) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.5.2.2 Function calls (p: 58-59) </li> +<li> 6.5.3.4 The sizeof and _Alignof operators (p: 64-65) </li> +<li> 6.5.4 Cast operators (p: 65-66) </li> +<li> 6.5.15 Conditional operator (p: 71-72) </li> +<li> 6.5.17 Comma operator (p: 75) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.5.2.2 Function calls (p: 81-82) </li> +<li> 6.5.3.4 The sizeof and _Alignof operators (p: 90-91) </li> +<li> 6.5.4 Cast operators (p: 91) </li> +<li> 6.5.15 Conditional operator (p: 100) </li> +<li> 6.5.17 Comma operator (p: 105) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 6.5.2.2 Function calls (p: 71-72) </li> +<li> 6.5.3.4 The sizeof operator (p: 80-81) </li> +<li> 6.5.4 Cast operators (p: 81) </li> +<li> 6.5.15 Conditional operator (p: 90-91) </li> +<li> 6.5.17 Comma operator (p: 94) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 3.3.2.2 Function calls </li> +<li> 3.3.3.4 The sizeof operator </li> +<li> 3.3.4 Cast operators </li> +<li> 3.3.15 Conditional operator </li> +<li> 3.3.17 Comma operator </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <ul><li> <a href="operator_precedence" title="c/language/operator precedence">Operator precedence</a> </li></ul> <table class="wikitable"> <tr style="text-align:center"> <th colspan="7"> Common operators </th> +</tr> <tr style="text-align:center"> <td> <a href="operator_assignment" title="c/language/operator assignment"> assignment</a> </td> <td> <a href="operator_incdec" title="c/language/operator incdec"> increment<br>decrement</a> </td> <td> <a href="operator_arithmetic" title="c/language/operator arithmetic"> arithmetic</a> </td> <td> <a href="operator_logical" title="c/language/operator logical"> logical</a> </td> <td> <a href="operator_comparison" title="c/language/operator comparison"> comparison</a> </td> <td> <a href="operator_member_access" title="c/language/operator member access"> member<br>access</a> </td> <td> <strong class="selflink"> other</strong> </td> +</tr> <tr style="text-align:center"> <td> <p><code>a = b a += b a -= b a *= b a /= b a %= b a &= b a |= b a ^= b a <<= b a >>= b</code></p> +</td> <td> <p><code>++a --a a++ a--</code></p> +</td> <td> <p><code>+a -a a + b a - b a * b a / b a % b ~a a & b a | b a ^ b a << b a >> b</code></p> +</td> <td> <p><code>!a a && b a || b</code></p> +</td> <td> <p><code>a == b a != b a < b a > b a <= b a >= b</code></p> +</td> <td> <p><code>a[b] *a &a a->b a.b</code></p> +</td> <td> <p><code>a(...) a, b (type) a a ? b : c sizeof</code><br><br> <code>_Alignof</code><br><span class="t-mark-rev t-since-c11">(since C11)</span></p> +</td> +</tr> </table> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/operator_other" title="cpp/language/operator other">C++ documentation</a></span> for <span class=""><span>Other operators</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/operator_other" class="_attribution-link">https://en.cppreference.com/w/c/language/operator_other</a> + </p> +</div> diff --git a/devdocs/c/language%2Foperator_precedence.html b/devdocs/c/language%2Foperator_precedence.html new file mode 100644 index 00000000..38517274 --- /dev/null +++ b/devdocs/c/language%2Foperator_precedence.html @@ -0,0 +1,68 @@ + <h1 id="firstHeading" class="firstHeading">C Operator Precedence</h1> <p>The following table lists the precedence and associativity of C operators. Operators are listed top to bottom, in descending precedence.</p> +<table class="wikitable"> <tr> <th> Precedence </th> <th> Operator </th> <th> Description </th> <th> Associativity </th> +</tr> <tr> <th rowspan="6"> 1 </th> <td> <code>++</code> <code>--</code> </td> <td> Suffix/postfix increment and decrement </td> <td rowspan="6"> Left-to-right </td> +</tr> <tr> <td> <code>()</code> </td> <td> Function call </td> +</tr> <tr> <td> <code>[]</code> </td> <td> Array subscripting </td> +</tr> <tr> <td> <code>.</code> </td> <td> Structure and union member access </td> +</tr> <tr> <td> <code>-></code> </td> <td> Structure and union member access through pointer </td> +</tr> <tr> <td> <code>(<i>type</i>){<i>list</i>}</code> </td> <td> Compound literal<span class="t-mark-rev t-since-c99">(C99)</span> </td> +</tr> <tr> <th rowspan="8"> 2 </th> <td> <code>++</code> <code>--</code> </td> <td> Prefix increment and decrement<sup id="cite_ref-1" class="reference"><a href="#cite_note-1">[note 1]</a></sup> </td> <td rowspan="8"> Right-to-left </td> +</tr> <tr> <td> <code>+</code> <code>-</code> </td> <td> Unary plus and minus </td> +</tr> <tr> <td> <code>!</code> <code>~</code> </td> <td> Logical NOT and bitwise NOT </td> +</tr> <tr> <td> <code>(<i>type</i>)</code> </td> <td> Cast </td> +</tr> <tr> <td> <code>*</code> </td> <td> Indirection (dereference) </td> +</tr> <tr> <td> <code>&</code> </td> <td> Address-of </td> +</tr> <tr> <td> <code>sizeof</code> </td> <td> Size-of<sup id="cite_ref-2" class="reference"><a href="#cite_note-2">[note 2]</a></sup> </td> +</tr> <tr> <td> <code>_Alignof</code> </td> <td> Alignment requirement<span class="t-mark-rev t-since-c11">(C11)</span> </td> +</tr> <tr> <th> 3 </th> <td> <code>*</code> <code>/</code> <code>%</code> </td> <td> Multiplication, division, and remainder </td> <td rowspan="11"> Left-to-right </td> +</tr> <tr> <th> 4 </th> <td> <code>+</code> <code>-</code> </td> <td> Addition and subtraction </td> +</tr> <tr> <th> 5 </th> <td> <code><<</code> <code>>></code> </td> <td> Bitwise left shift and right shift </td> +</tr> <tr> <th rowspan="2"> 6 </th> <td> <code><</code> <code><=</code> </td> <td> For relational operators < and ≤ respectively </td> +</tr> <tr> <td> <code>></code> <code>>=</code> </td> <td> For relational operators > and ≥ respectively </td> +</tr> <tr> <th> 7 </th> <td> <code>==</code> <code>!=</code> </td> <td> For relational = and ≠ respectively </td> +</tr> <tr> <th> 8 </th> <td> <code>&</code> </td> <td> Bitwise AND </td> +</tr> <tr> <th> 9 </th> <td> <code>^</code> </td> <td> Bitwise XOR (exclusive or) </td> +</tr> <tr> <th> 10 </th> <td> <code>|</code> </td> <td> Bitwise OR (inclusive or) </td> +</tr> <tr> <th> 11 </th> <td> <code>&&</code> </td> <td> Logical AND </td> +</tr> <tr> <th> 12 </th> <td> <code>||</code> </td> <td> Logical OR </td> +</tr> <tr> <th> 13 </th> <td> <code>?:</code> </td> <td> Ternary conditional<sup id="cite_ref-3" class="reference"><a href="#cite_note-3">[note 3]</a></sup> </td> <td rowspan="6"> Right-to-left </td> +</tr> <tr> <th rowspan="5"> 14<sup id="cite_ref-4" class="reference"><a href="#cite_note-4">[note 4]</a></sup> </th> <td> <code>=</code> </td> <td> Simple assignment </td> +</tr> <tr> <td> <code>+=</code> <code>-=</code> </td> <td> Assignment by sum and difference </td> +</tr> <tr> <td> <code>*=</code> <code>/=</code> <code>%=</code> </td> <td> Assignment by product, quotient, and remainder </td> +</tr> <tr> <td> <code><<=</code> <code>>>=</code> </td> <td> Assignment by bitwise left shift and right shift </td> +</tr> <tr> <td> <code>&=</code> <code>^=</code> <code>|=</code> </td> <td> Assignment by bitwise AND, XOR, and OR </td> +</tr> <tr> <th> 15 </th> <td> <code>,</code> </td> <td> Comma </td> <td> Left-to-right </td> +</tr> +</table> <ol class="references"> <li id="cite_note-1"> <span class="reference-text">The operand of prefix <code>++</code> and <code>--</code> can't be a type cast. This rule grammatically forbids some expressions that would be semantically invalid anyway. Some compilers ignore this rule and detect the invalidity semantically.</span> </li> <li id="cite_note-2"> <span class="reference-text">The operand of <code>sizeof</code> can't be a type cast: the expression <code>sizeof (int) * p</code> is unambiguously interpreted as <code>(sizeof(int)) * p</code>, but not <code>sizeof((int)*p)</code>.</span> </li> <li id="cite_note-3"> <span class="reference-text">The expression in the middle of the conditional operator (between <code>?</code> and <code>:</code>) is parsed as if parenthesized: its precedence relative to <code>?:</code> is ignored.</span> </li> <li id="cite_note-4"> <span class="reference-text">Assignment operators' left operands must be unary (level-2 non-cast) expressions. This rule grammatically forbids some expressions that would be semantically invalid anyway. Many compilers ignore this rule and detect the invalidity semantically. For example, <code>e = a < d ? a++ : a = d</code> is an expression that cannot be parsed because of this rule. However, many compilers ignore this rule and parse it as <code>e = ( ((a < d) ? (a++) : a) = d )</code>, and then give an error because it is semantically invalid.</span> </li> </ol> <p>When parsing an expression, an operator which is listed on some row will be bound tighter (as if by parentheses) to its arguments than any operator that is listed on a row further below it. For example, the expression <code>*p++</code> is parsed as <code>*(p++)</code>, and not as <code>(*p)++</code>.</p> +<p>Operators that are in the same cell (there may be several rows of operators listed in a cell) are evaluated with the same precedence, in the given direction. For example, the expression <code>a=b=c</code> is parsed as <code>a=(b=c)</code>, and not as <code>(a=b)=c</code> because of right-to-left associativity.</p> +<h3 id="Notes"> Notes</h3> <p>Precedence and associativity are independent from <a href="eval_order" title="c/language/eval order">order of evaluation</a>.</p> +<p>The standard itself doesn't specify precedence levels. They are derived from the grammar.</p> +<p>In C++, the conditional operator has the same precedence as assignment operators, and prefix <code>++</code> and <code>--</code> and assignment operators don't have the restrictions about their operands.</p> +<p>Associativity specification is redundant for unary operators and is only shown for completeness: unary prefix operators always associate right-to-left (<code>sizeof ++*p</code> is <code>sizeof(++(*p))</code>) and unary postfix operators always associate left-to-right (<code>a[1][2]++</code> is <code>((a[1])[2])++</code>). Note that the associativity is meaningful for member access operators, even though they are grouped with unary postfix operators: <code>a.b++</code> is parsed <code>(a.b)++</code> and not <code>a.(b++)</code>.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> A.2.1 Expressions </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> A.2.1 Expressions </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> A.2.1 Expressions </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> A.1.2.1 Expressions </li></ul> +</ul> <h3 id="See_also"> See also</h3> <p><a href="eval_order" title="c/language/eval order">Order of evaluation</a> of operator arguments at run time.</p> +<table class="wikitable"> <tr style="text-align:center"> <th colspan="7"> Common operators </th> +</tr> <tr style="text-align:center"> <td> <a href="operator_assignment" title="c/language/operator assignment"> assignment</a> </td> <td> <a href="operator_incdec" title="c/language/operator incdec"> increment<br>decrement</a> </td> <td> <a href="operator_arithmetic" title="c/language/operator arithmetic"> arithmetic</a> </td> <td> <a href="operator_logical" title="c/language/operator logical"> logical</a> </td> <td> <a href="operator_comparison" title="c/language/operator comparison"> comparison</a> </td> <td> <a href="operator_member_access" title="c/language/operator member access"> member<br>access</a> </td> <td> <a href="operator_other" title="c/language/operator other"> other</a> </td> +</tr> <tr style="text-align:center"> <td> <p><code>a = b a += b a -= b a *= b a /= b a %= b a &= b a |= b a ^= b a <<= b a >>= b</code></p> +</td> <td> <p><code>++a --a a++ a--</code></p> +</td> <td> <p><code>+a -a a + b a - b a * b a / b a % b ~a a & b a | b a ^ b a << b a >> b</code></p> +</td> <td> <p><code>!a a && b a || b</code></p> +</td> <td> <p><code>a == b a != b a < b a > b a <= b a >= b</code></p> +</td> <td> <p><code>a[b] *a &a a->b a.b</code></p> +</td> <td> <p><code>a(...) a, b (type) a a ? b : c sizeof</code><br><br> <code>_Alignof</code><br><span class="t-mark-rev t-since-c11">(since C11)</span></p> +</td> +</tr> </table> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/operator_precedence" title="cpp/language/operator precedence">C++ documentation</a></span> for <span class=""><span>C++ operator precedence</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/operator_precedence" class="_attribution-link">https://en.cppreference.com/w/c/language/operator_precedence</a> + </p> +</div> diff --git a/devdocs/c/language%2Fpointer.html b/devdocs/c/language%2Fpointer.html new file mode 100644 index 00000000..5c39408c --- /dev/null +++ b/devdocs/c/language%2Fpointer.html @@ -0,0 +1,95 @@ + <h1 id="firstHeading" class="firstHeading">Pointer declaration</h1> <p>Pointer is a type of an object that refers to a function or an object of another type, possibly adding qualifiers. Pointer may also refer to nothing, which is indicated by the special null pointer value.</p> +<h3 id="Syntax"> Syntax</h3> <p>In the <a href="declarations" title="c/language/declarations">declaration grammar</a> of a pointer declaration, the <span class="t-spar">type-specifier</span> sequence designates the pointed-to type (which may be function or object type and may be incomplete), and the <span class="t-spar">declarator</span> has the form:</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <code>*</code> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span> <span class="t-spar">qualifiers</span><span class="t-mark">(optional)</span> <span class="t-spar">declarator</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>where <span class="t-spar">declarator</span> may be the identifier that names the pointer being declared, including another pointer declarator (which would indicate a pointer to a pointer):</p> +<div class="c source-c"><pre data-language="c">float *p, **pp; // p is a pointer to float + // pp is a pointer to a pointer to float +int (*fp)(int); // fp is a pointer to function with type int(int)</pre></div> <p>The <span class="t-spar">qualifiers</span> that appear between <code>*</code> and the identifier (or other nested declarator) qualify the type of the pointer that is being declared:</p> +<div class="c source-c"><pre data-language="c">int n; +const int * pc = &n; // pc is a non-const pointer to a const int +// *pc = 2; // Error: n cannot be changed through pc without a cast +pc = NULL; // OK: pc itself can be changed + +int * const cp = &n; // cp is a const pointer to a non-const int +*cp = 2; // OK to change n through cp +// cp = NULL; // Error: cp itself cannot be changed + +int * const * pcp = &cp; // non-const pointer to const pointer to non-const int</pre></div> <p>The <span class="t-spar">attr-spec-seq</span><span class="t-mark-rev t-since-c23">(C23)</span> is an optional list of <a href="attributes" title="c/language/attributes">attributes</a>, applied to the declared pointer.</p> +<h3 id="Explanation"> Explanation</h3> <p>Pointers are used for indirection, which is a ubiquitous programming technique; they can be used to implement pass-by-reference semantics, to access objects with dynamic <a href="storage_duration" title="c/language/storage duration">storage duration</a>, to implement "optional" types (using the null pointer value), aggregation relationship between structs, callbacks (using pointers to functions), generic interfaces (using pointers to void), and much more.</p> +<h4 id="Pointers_to_objects"> Pointers to objects</h4> <p>A pointer to object can be initialized with the result of the <a href="operator_member_access" title="c/language/operator member access">address-of operator</a> applied to an expression of object type (which may be incomplete):</p> +<div class="c source-c"><pre data-language="c">int n; +int *np = &n; // pointer to int +int *const *npp = &np; // non-const pointer to const pointer to non-const int + +int a[2]; +int (*ap)[2] = &a; // pointer to array of int + +struct S { int n; } s = {1} +int* sp = &s.n; // pointer to the int that is a member of s</pre></div> <p>Pointers may appear as operands to the <a href="operator_member_access#Dereference" title="c/language/operator member access">indirection operator</a> (unary <code>*</code>), which returns <a href="value_category" title="c/language/value category">the lvalue</a> identifying the pointed-to object:</p> +<div class="c source-c"><pre data-language="c">int n; +int* p = &n; // pointer p is pointing to n +*p = 7; // stores 7 in n +printf("%d\n", *p); // lvalue-to-rvalue conversion reads the value from n</pre></div> <p>Pointers to objects of <a href="struct" title="c/language/struct">struct</a> and <a href="union" title="c/language/union">union</a> type may also appear as the left-hand operands of the <a href="operator_member_access" title="c/language/operator member access">member access through pointer</a> operator <code>-></code>.</p> +<p>Because of the <a href="array" title="c/language/array">array-to-pointer</a> implicit conversion, pointer to the first element of an array can be initialized with an expression of array type:</p> +<div class="c source-c"><pre data-language="c">int a[2]; +int *p = a; // pointer to a[0] + +int b[3][3]; +int (*row)[3] = b; // pointer to b[0]</pre></div> <p>Certain <a href="operator_arithmetic" title="c/language/operator arithmetic">addition, subtraction</a>, <a href="operator_assignment" title="c/language/operator assignment">compound assignment</a>, <a href="operator_incdec" title="c/language/operator incdec">increment, and decrement</a> operators are defined for pointers to elements of arrays.</p> +<p><a href="operator_comparison" title="c/language/operator comparison">Comparison operators</a> are defined for pointers to objects in some situations: two pointers that represent the same address compare equal, two null pointer values compare equal, pointers to elements of the same array compare the same as the array indexes of those elements, and pointers to struct members compare in order of declaration of those members.</p> +<p>Many implementations also provide <a href="https://en.wikipedia.org/wiki/Total_order#Strict_total_order" class="extiw" title="enwiki:Total order">strict total ordering</a> of pointers of random origin, e.g. if they are implemented as addresses within continuous ("flat") virtual address space.</p> +<h4 id="Pointers_to_functions"> Pointers to functions</h4> <p>A pointer to function can be initialized with an address of a function. Because of the <a href="conversion" title="c/language/conversion">function-to-pointer</a> conversion, the address-of operator is optional:</p> +<div class="c source-c"><pre data-language="c">void f(int); +void (*pf1)(int) = &f; +void (*pf2)(int) = f; // same as &f</pre></div> <p>Unlike functions, pointers to functions are objects and thus can be stored in arrays, copied, assigned, passed to other functions as arguments, etc.</p> +<p>A pointer to function can be used on the left-hand side of the <a href="operator_other#Function_call" title="c/language/operator other">function call operator</a>; this invokes the pointed-to function:</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> +int f(int n) +{ + printf("%d\n", n); + return n*n; +} +int main(void) +{ + int (*p)(int) = f; + int x = p(7); +}</pre></div> <p>Dereferencing a function pointer yields the function designator for the pointed-to function:</p> +<div class="c source-c"><pre data-language="c">int f(); +int (*p)() = f; // pointer p is pointing to f +(*p)(); // function f invoked through the function designator +p(); // function f invoked directly through the pointer</pre></div> <p><a href="operator_comparison" title="c/language/operator comparison">Equality comparison operators</a> are defined for pointers to functions (they compare equal if pointing to the same function).</p> +<p>Because <a href="type#Compatible_types" title="c/language/type">compatibility of function types</a> ignores top-level qualifiers of the function parameters, pointers to functions whose parameters only differ in their top-level qualifiers are interchangeable:</p> +<div class="c source-c"><pre data-language="c">int f(int), fc(const int); +int (*pc)(const int) = f; // OK +int (*p)(int) = fc; // OK +pc = p; // OK</pre></div> <h4 id="Pointers_to_void"> Pointers to void</h4> <p>Pointer to object of any type can be <a href="conversion" title="c/language/conversion">implicitly converted</a> to pointer to <code>void</code> (optionally <a href="const" title="c/language/const">const</a> or <a href="volatile" title="c/language/volatile">volatile</a>-qualified), and vice versa:</p> +<div class="c source-c"><pre data-language="c">int n=1, *p=&n; +void* pv = p; // int* to void* +int* p2 = pv; // void* to int* +printf("%d\n", *p2); // prints 1</pre></div> <p>Pointers to void are used to pass objects of unknown type, which is common in generic interfaces: <code><a href="../memory/malloc" title="c/memory/malloc">malloc</a></code> returns <code>void*</code>, <code><a href="../algorithm/qsort" title="c/algorithm/qsort">qsort</a></code> expects a user-provided callback that accepts two <code>const void*</code> arguments. <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_create.html">pthread_create</a> expects a user-provided callback that accepts and returns <code>void*</code>. In all cases, it is the caller's responsibility to convert the pointer to the correct type before use.</p> +<h3 id="Null_pointers"> Null pointers</h3> <p>Pointers of every type have a special value known as <i>null pointer value</i> of that type. A pointer whose value is null does not point to an object or a function (dereferencing a null pointer is undefined behavior), and compares equal to all pointers of the same type whose value is also <i>null</i>.</p> +<p>To initialize a pointer to null or to assign the null value to an existing pointer, a null pointer constant (<code><a href="../types/null" title="c/types/NULL">NULL</a></code>, or any other integer constant with the value zero) may be used. <a href="initialization" title="c/language/initialization">static initialization</a> also initializes pointers to their null values.</p> +<p>Null pointers can indicate the absence of an object or can be used to indicate other types of error conditions. In general, a function that receives a pointer argument almost always needs to check if the value is null and handle that case differently (for example, <code><a href="../memory/free" title="c/memory/free">free</a></code> does nothing when a null pointer is passed).</p> +<h3 id="Notes"> Notes</h3> <p>Although any pointer to object <a href="cast" title="c/language/cast">can be cast</a> to pointer to object of a different type, dereferencing a pointer to the type different from the declared type of the object is almost always undefined behavior. See <a href="object#Strict_aliasing" title="c/language/object">strict aliasing</a> for details.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>It is possible to indicate to a function that accesses objects through pointers that those pointers do not alias. See <a href="restrict" title="c/language/restrict">restrict</a> for details.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <p>lvalue expressions of array type, when used in most contexts, undergo an <a href="conversion" title="c/language/conversion">implicit conversion</a> to the pointer to the first element of the array. See <a href="array#Array_to_pointer_conversion" title="c/language/array">array</a> for details.</p> +<div class="c source-c"><pre data-language="c">char *str = "abc"; // "abc" is a char[4] array, str is a pointer to 'a'</pre></div> <p>Pointers to char are often <a href="../string/byte" title="c/string/byte">used to represent strings</a>. To represent a valid byte string, a pointer must be pointing at a char that is an element of an array of char, and there must be a char with the value zero at some index greater or equal to the index of the element referenced by the pointer.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.7.6.1 Pointer declarators (p: 93-94) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.7.6.1 Pointer declarators (p: 130) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.7.5.1 Pointer declarators (p: 115-116) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.5.4.1 Pointer declarators </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/pointer" title="cpp/language/pointer">C++ documentation</a></span> for <span class=""><span>Pointer declaration</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/pointer" class="_attribution-link">https://en.cppreference.com/w/c/language/pointer</a> + </p> +</div> diff --git a/devdocs/c/language%2Fpunctuators.html b/devdocs/c/language%2Fpunctuators.html new file mode 100644 index 00000000..50b603d2 --- /dev/null +++ b/devdocs/c/language%2Fpunctuators.html @@ -0,0 +1,175 @@ + <h1 id="firstHeading" class="firstHeading">Punctuation</h1> <p>These are the punctuation symbols in C. The meaning of each symbol is detailed in the linked pages.</p> +<h3 id=".7B_.7D"> <code>{</code> <code>}</code> +</h3> <ul> +<li> In a <a href="struct" title="c/language/struct">struct</a> or <a href="union" title="c/language/union">union</a> definition, delimit the <span class="t-spar">struct-declaration-list</span>. </li> +<li> In an <a href="enum" title="c/language/enum">enum</a> definition, delimit the enumerator list. </li> +<li> Delimit a <a href="statements#Compound_statements" title="c/language/statements">compound statement</a>. The compound statement may be part of a <a href="function_definition" title="c/language/function definition">function definition</a>. </li> +<li> In <a href="initialization" title="c/language/initialization">initialization</a>, delimit the initializers. </li> +</ul> <h3 id=".5B_.5D"> <code>[</code> <code>]</code> +</h3> <ul> +<li> <a href="operator_member_access#Subscript" title="c/language/operator member access">Subscript operator</a>. </li> +<li> Part of <a href="declarations#Declarators" title="c/language/declarations">array declarator</a> in a <a href="declarations" title="c/language/declarations">declaration</a> or a <a href="type#Type_names" title="c/language/type">type-id</a>. </li> +<li> In <a href="initialization" title="c/language/initialization">initialization</a>, introduce a designator for an array element. <span class="t-mark-rev t-since-c99">(since C99)</span> </li> +<li> In an <a href="attributes" title="c/language/attributes">attribute specifier</a>, delimit the attributes. <span class="t-mark-rev t-since-c23">(since C23)</span> </li> +</ul> <h3 id=".23"> <code>#</code> +</h3> <ul> +<li> Introduce a <a href="../preprocessor" title="c/preprocessor">preprocessing directive</a>. </li> +<li> The <a href="../preprocessor/replace#.23_and_.23.23_operators" title="c/preprocessor/replace">preprocessing operator for stringification</a>. </li> +</ul> <h3 id=".23.23"> <code>##</code> +</h3> <ul><li> The <a href="../preprocessor/replace#.23_and_.23.23_operators" title="c/preprocessor/replace">preprocessing operator for token pasting</a>. </li></ul> <h3 id=".28_.29"> <code>(</code> <code>)</code> +</h3> <ul> +<li> In an expression, <a href="expressions#Primary_expressions" title="c/language/expressions">indicate grouping</a>. </li> +<li> <a href="operator_other#Function_call" title="c/language/operator other">Function call operator</a>. </li> +<li> In a <a href="sizeof" title="c/language/sizeof"><code>sizeof</code></a><span class="t-rev-inl t-since-c11"><span>, <a href="_alignof" title="c/language/ Alignof"><code>_Alignof</code></a></span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> <span class="t-rev-inl t-since-c23"><span>, <a href="typeof" title="c/language/typeof"><code>typeof</code></a> or <a href="https://en.cppreference.com/mwiki/index.php?title=c/language/typeof_unqual&action=edit&redlink=1" class="new" title="c/language/typeof unqual (page does not exist)"><code>typeof_unqual</code></a></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> expression, delimit the operand. </li> +<li> In an <a href="cast" title="c/language/cast">explicit cast</a>, delimit the type-id. </li> +<li> In a <a href="compound_literal" title="c/language/compound literal">compound literal</a>, delimit the type-id. <span class="t-mark-rev t-since-c99">(since C99)</span> </li> +<li> In a <a href="declarations" title="c/language/declarations">declaration</a> or a <a href="type#Type_names" title="c/language/type">type-id</a>, indicate grouping. </li> +<li> In a <a href="function_declaration" title="c/language/function declaration">function declarator</a> (in a <a href="declarations" title="c/language/declarations">declaration</a> or a <a href="type#Type_names" title="c/language/type">type-id</a>), delimit the parameter list. </li> +<li> In an <a href="if" title="c/language/if"><code>if</code></a>, <a href="switch" title="c/language/switch"><code>switch</code></a>, <a href="while" title="c/language/while"><code>while</code></a>, <a href="do" title="c/language/do"><code>do-while</code></a>, or <a href="for" title="c/language/for"><code>for</code></a> statement, delimit the controlling clause. </li> +<li> In a <a href="../preprocessor/replace#Function-like_macros" title="c/preprocessor/replace">function-like macro definition</a>, delimit the macro parameters. </li> +<li> In a <a href="../preprocessor/replace#Function-like_macros" title="c/preprocessor/replace">function-like macro invocation</a>, delimit the macro arguments or prevent commas from being interpreted as argument separators. </li> +<li> Part of a <code>defined</code><span class="t-rev-inl t-since-c23"><span>, <code>__has_include</code>, <code>__has_embed</code> or <code>__has_c_attribute</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> preprocessing operator. </li> +<li> Part of a <a href="generic" title="c/language/generic">generic selection expression</a>. <span class="t-mark-rev t-since-c11">(since C11)</span> </li> +<li> In an <a href="atomic" title="c/language/atomic"><code>_Atomic</code></a> type specifier, delimit the type-id. <span class="t-mark-rev t-since-c11">(since C11)</span> </li> +<li> In a <a href="_static_assert" title="c/language/ Static assert">static assertion declaration</a>, delimit the operands. <span class="t-mark-rev t-since-c11">(since C11)</span> </li> +<li> In an <a href="_alignas" title="c/language/ Alignas"><code>_Alignas</code></a> specifier, delimit the operand. <span class="t-mark-rev t-since-c11">(since C11)</span> </li> +<li> In an <a href="attributes" title="c/language/attributes">attribute</a>, delimit the attribute arguments. <span class="t-mark-rev t-since-c23">(since C23)</span> </li> +<li> In a bit-precise integer type name (_BitInt<span class="br0">(</span>N<span class="br0">)</span>), delimit the size. <span class="t-mark-rev t-since-c23">(since C23)</span> </li> +<li> Part of <a href="../preprocessor/replace" title="c/preprocessor/replace"><code>__VA_OPT__</code></a> replacement in a variadic macro definition. <span class="t-mark-rev t-since-c23">(since C23)</span> </li> +<li> In a preprocessor parameter used in <a href="../preprocessor/embed" title="c/preprocessor/embed"><code>#embed</code> directives</a> and <code>__has_embed</code> preprocessing expressions, delimit the preprocessor parameter clause. <span class="t-mark-rev t-since-c23">(since C23)</span> </li> +</ul> <h3 id=".3B"> <code>;</code> +</h3> <ul> +<li> Indicate the end of </li> +<ul> +<li> a <a href="statements" title="c/language/statements">statement</a> (including the init-statement of a for statement) </li> +<li> a <a href="declarations" title="c/language/declarations">declaration</a> or <span class="t-spar">struct-declaration-list</span> </li> +</ul> +<li> Separate the second and third clauses of a <a href="for" title="c/language/for">for statement</a>. </li> +</ul> <h3 id=":"> <code>:</code> +</h3> <ul> +<li> Part of <a href="operator_other#Conditional_operator" title="c/language/operator other">conditional operator</a>. </li> +<li> Part of <a href="statements#Labels" title="c/language/statements">label declaration</a>. </li> +<li> In a <a href="bit_field" title="c/language/bit field">bit-field member declaration</a>, introduce the width. </li> +<li> Introduce an <a href="enum" title="c/language/enum">enum base</a>, which specifies the underlying type of the enum. <span class="t-mark-rev t-since-c23">(since C23)</span> </li> +<li> In a <a href="generic" title="c/language/generic">generic association</a>, delimit the type-id or <code>default</code> and the selected expression. <span class="t-mark-rev t-since-c11">(since C11)</span> </li> +</ul> <h3 id="..."> <code>...</code> +</h3> <ul> +<li> In the <a href="function_declaration#Parameter_list" title="c/language/function declaration">parameter list</a> of a function declarator, signify a <a href="variadic" title="c/language/variadic">variadic function</a>. </li> +<li> In a <a href="../preprocessor/replace" title="c/preprocessor/replace">macro definition</a>, signify a variadic macro. <span class="t-mark-rev t-since-c99">(since C99)</span> </li> +</ul> <h3 id=".3F"> <code>?</code> +</h3> <ul><li> Part of <a href="operator_other#Conditional_operator" title="c/language/operator other">conditional operator</a>. </li></ul> <h3 id="::"> <code>::</code> +</h3> <ul> +<li> In an <a href="attributes" title="c/language/attributes">attribute</a>, indicate attribute scope. <span class="t-mark-rev t-since-c23">(since C23)</span> </li> +<li> In a preprocessor prefixed parameter (used by <a href="../preprocessor/embed" title="c/preprocessor/embed"><code>#embed</code></a> and <code>__has_embed</code>), indicate scope. <span class="t-mark-rev t-since-c23">(since C23)</span> </li> +</ul> <h3 id="."> <code>.</code> +</h3> <ul> +<li> <a href="operator_member_access#Member_access" title="c/language/operator member access">Member access operator</a>. </li> +<li> In <a href="initialization" title="c/language/initialization">initialization</a>, introduce a designator for a struct/union member. <span class="t-mark-rev t-since-c99">(since C99)</span> </li> +</ul> <h3 id="-.3E"> <code>-></code> +</h3> <ul><li> <a href="operator_member_access#Member_access_through_pointer" title="c/language/operator member access">Member access operator</a>. </li></ul> <h3 id=".7E"> <code>~</code> +</h3> <ul><li> <a href="operator_arithmetic#Bitwise_logic" title="c/language/operator arithmetic">Unary complement operator (a.k.a. bitwise not operator)</a>. </li></ul> <h3 id=".21"> <code>!</code> +</h3> <ul><li> <a href="operator_logical#Logical_NOT" title="c/language/operator logical">Logical not operator</a>. </li></ul> <h3 id=".2B"> <code>+</code> +</h3> <ul> +<li> <a href="operator_arithmetic#Unary_arithmetic" title="c/language/operator arithmetic">Unary plus operator</a>. </li> +<li> <a href="operator_arithmetic#Additive_operators" title="c/language/operator arithmetic">Binary plus operator</a>. </li> +</ul> <h3 id="-"> <code>-</code> +</h3> <ul> +<li> <a href="operator_arithmetic#Unary_arithmetic" title="c/language/operator arithmetic">Unary minus operator</a>. </li> +<li> <a href="operator_arithmetic#Additive_operators" title="c/language/operator arithmetic">Binary minus operator</a>. </li> +</ul> <h3 id=".2A"> <code>*</code> +</h3> <ul> +<li> <a href="operator_member_access#Dereference" title="c/language/operator member access">Indirection operator</a>. </li> +<li> <a href="operator_arithmetic#Multiplicative_operators" title="c/language/operator arithmetic">Multiplication operator</a>. </li> +<li> Pointer operator operator in a <a href="declarations#Declarators" title="c/language/declarations">declarator</a> or in a <a href="type#Type_names" title="c/language/type">type-id</a>. </li> +<li> Placeholder for the length of a variable-length array declarator in a <a href="function_declaration" title="c/language/function declaration">function declaration</a>. <span class="t-mark-rev t-since-c99">(since C99)</span> </li> +</ul> <h3 id=".2F"> <code>/</code> +</h3> <ul><li> <a href="operator_arithmetic#Multiplicative_operators" title="c/language/operator arithmetic">Division operator</a>. </li></ul> <h3 id=".25"> <code>%</code> +</h3> <ul><li> <a href="operator_arithmetic#Multiplicative_operators" title="c/language/operator arithmetic">Modulo operator</a>. </li></ul> <h3 id=".5E"> <code>^</code> +</h3> <ul><li> <a href="operator_arithmetic#Bitwise_logic" title="c/language/operator arithmetic">Bitwise xor operator</a>. </li></ul> <h3 id=".26"> <code>&</code> +</h3> <ul> +<li> <a href="operator_member_access#Address_of" title="c/language/operator member access">Address-of operator</a>. </li> +<li> <a href="operator_arithmetic#Bitwise_logic" title="c/language/operator arithmetic">Bitwise and operator</a>. </li> +</ul> <h3 id=".7C"> <code>|</code> +</h3> <ul><li> <a href="operator_arithmetic#Bitwise_logic" title="c/language/operator arithmetic">Bitwise or operator</a>. </li></ul> <h3 id=".3D"> <code>=</code> +</h3> <ul> +<li> <a href="operator_assignment#Simple_assignment" title="c/language/operator assignment">Simple assignment operator</a>. </li> +<li> In <a href="initialization" title="c/language/initialization">initialization</a>, delimit the object and the initializer list. </li> +<li> In an <a href="enum" title="c/language/enum">enum definition</a>, introduce the value of enumeration constant. </li> +</ul> <h3 id=".2B.3D"> <code>+=</code> +</h3> <ul><li> <a href="operator_assignment#Compound_assignment" title="c/language/operator assignment">Compound assignment operator</a>. </li></ul> <h3 id="-.3D"> <code>-=</code> +</h3> <ul><li> <a href="operator_assignment#Compound_assignment" title="c/language/operator assignment">Compound assignment operator</a>. </li></ul> <h3 id=".2A.3D"> <code>*=</code> +</h3> <ul><li> <a href="operator_assignment#Compound_assignment" title="c/language/operator assignment">Compound assignment operator</a>. </li></ul> <h3 id=".2F.3D"> <code>/=</code> +</h3> <ul><li> <a href="operator_assignment#Compound_assignment" title="c/language/operator assignment">Compound assignment operator</a>. </li></ul> <h3 id=".25.3D"> <code>%=</code> +</h3> <ul><li> <a href="operator_assignment#Compound_assignment" title="c/language/operator assignment">Compound assignment operator</a>. </li></ul> <h3 id=".5E.3D"> <code>^=</code> +</h3> <ul><li> <a href="operator_assignment#Compound_assignment" title="c/language/operator assignment">Compound assignment operator</a>. </li></ul> <h3 id=".26.3D"> <code>&=</code> +</h3> <ul><li> <a href="operator_assignment#Compound_assignment" title="c/language/operator assignment">Compound assignment operator</a>. </li></ul> <h3 id=".7C.3D"> <code>|=</code> +</h3> <ul><li> <a href="operator_assignment#Compound_assignment" title="c/language/operator assignment">Compound assignment operator</a>. </li></ul> <h3 id=".3D.3D"> <code>==</code> +</h3> <ul><li> <a href="operator_comparison#Equality_operators" title="c/language/operator comparison">Equality operator</a>. </li></ul> <h3 id=".21.3D"> <code>!=</code> +</h3> <ul><li> <a href="operator_comparison#Equality_operators" title="c/language/operator comparison">Inequality operator</a>. </li></ul> <h3 id=".3C"> <code><</code> +</h3> <ul> +<li> <a href="operator_comparison#Relational_operators" title="c/language/operator comparison">Less-than operator</a>. </li> +<li> Introduce a header name in </li> +<ul> +<li> a <a href="../preprocessor/include" title="c/preprocessor/include"><code>#include</code> directive</a> </li> +<li> a <a href="../preprocessor/include" title="c/preprocessor/include"><code>__has_include</code> preprocessing expression</a> <span class="t-mark-rev t-since-c23">(since C23)</span> </li> +<li> a <a href="../preprocessor/embed" title="c/preprocessor/embed"><code>#embed</code> directive</a> <span class="t-mark-rev t-since-c23">(since C23)</span> </li> +<li> a <a href="../preprocessor/embed" title="c/preprocessor/embed"><code>__has_embed</code> preprocessing expression</a> <span class="t-mark-rev t-since-c23">(since C23)</span> </li> +<li> implementation-defined locations within a <a href="../preprocessor/impl" title="c/preprocessor/impl"><code>#pragma</code> directive</a> </li> +</ul> +</ul> <h3 id=".3E"> <code>></code> +</h3> <ul> +<li> <a href="operator_comparison#Relational_operators" title="c/language/operator comparison">Greater-than operator</a>. </li> +<li> Indicate the end of a header name in </li> +<ul> +<li> a <a href="../preprocessor/include" title="c/preprocessor/include"><code>#include</code> directive</a> </li> +<li> a <a href="../preprocessor/include" title="c/preprocessor/include"><code>__has_include</code> preprocessing expression</a> <span class="t-mark-rev t-since-c23">(since C23)</span> </li> +<li> a <a href="../preprocessor/embed" title="c/preprocessor/embed"><code>#embed</code> directive</a> <span class="t-mark-rev t-since-c23">(since C23)</span> </li> +<li> a <a href="../preprocessor/embed" title="c/preprocessor/embed"><code>__has_embed</code> preprocessing expression</a> <span class="t-mark-rev t-since-c23">(since C23)</span> </li> +<li> implementation-defined locations within a <a href="../preprocessor/impl" title="c/preprocessor/impl"><code>#pragma</code> directive</a> </li> +</ul> +</ul> <h3 id=".3C.3D"> <code><=</code> +</h3> <ul><li> <a href="operator_comparison#Relational_operators" title="c/language/operator comparison">Less-than-or-equal-to operator</a>. </li></ul> <h3 id=".3E.3D"> <code>>=</code> +</h3> <ul><li> <a href="operator_comparison#Relational_operators" title="c/language/operator comparison">Greater-than-or-equal-to operator</a>. </li></ul> <h3 id=".26.26"> <code>&&</code> +</h3> <ul><li> <a href="operator_logical#Logical_AND" title="c/language/operator logical">Logical and operator</a>. </li></ul> <h3 id=".7C.7C"> <code>||</code> +</h3> <ul><li> <a href="operator_logical#Logical_OR" title="c/language/operator logical">Logical or operator</a>. </li></ul> <h3 id=".3C.3C"> <code><<</code> +</h3> <ul><li> <a href="operator_arithmetic#Shift_operators" title="c/language/operator arithmetic">Bitwise shift operator</a>. </li></ul> <h3 id=".3E.3E"> <code>>></code> +</h3> <ul><li> <a href="operator_arithmetic#Shift_operators" title="c/language/operator arithmetic">Bitwise shift operator</a>. </li></ul> <h3 id=".3C.3C.3D"> <code><<=</code> +</h3> <ul><li> <a href="operator_assignment#Compound_assignment" title="c/language/operator assignment">Compound assignment operator</a>. </li></ul> <h3 id=".3E.3E.3D"> <code>>>=</code> +</h3> <ul><li> <a href="operator_assignment#Compound_assignment" title="c/language/operator assignment">Compound assignment operator</a>. </li></ul> <h3 id=".2B.2B"> <code>++</code> +</h3> <ul><li> <a href="operator_incdec" title="c/language/operator incdec">Increment operator</a>. </li></ul> <h3 id="--"> <code>--</code> +</h3> <ul><li> <a href="operator_incdec" title="c/language/operator incdec">Decrement operator</a>. </li></ul> <h3 id=".2C"> <code>,</code> +</h3> <ul> +<li> <a href="operator_other#Comma_operator" title="c/language/operator other">Comma operator</a>. </li> +<li> List separator in </li> +<ul> +<li> the declarator list in a <a href="declarations" title="c/language/declarations">declaration</a> </li> +<li> initializer list in <a href="initialization" title="c/language/initialization">initialization</a><span class="t-rev-inl t-since-c99"><span>, including <a href="compound_literal" title="c/language/compound literal">compound literals</a></span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> </li> +<li> the argument list in a <a href="operator_other#Function_call" title="c/language/operator other">function call expression</a> </li> +<li> the enumerator list in an <a href="enum" title="c/language/enum">enum</a> declaration </li> +<li> a function parameter list </li> +<li> the macro parameter list in a <a href="../preprocessor/replace#Function-like_macros" title="c/preprocessor/replace">function-like macro definition</a> </li> +<li> the macro argument list in a <a href="../preprocessor/replace#Function-like_macros" title="c/preprocessor/replace">function-like macro invocation</a>, unless found between an inner set of parentheses </li> +<li> the generic association list in a <a href="generic" title="c/language/generic">generic selection expression</a> <span class="t-mark-rev t-since-c11">(since C11)</span> </li> +<li> an <a href="attributes" title="c/language/attributes">attribute</a> list <span class="t-mark-rev t-since-c23">(since C23)</span> </li> +</ul> +<li> In a <a href="_static_assert" title="c/language/ Static assert">static assertion declaration</a>, separate the arguments. <span class="t-mark-rev t-since-c11">(since C11)</span> </li> +<li> In a <a href="generic" title="c/language/generic">generic selection expression</a>, separate the controlling expression and the generic association list. <span class="t-mark-rev t-since-c11">(since C11)</span> </li> +</ul> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.4.6 Punctuators (p: 68-69) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.4.6 Punctuators (p: 52-53) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.4.6 Punctuators (p: 72-73) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.4.6 Punctuators (p: 63-64) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.1.6 Punctuators </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <a href="operator_alternative" title="c/language/operator alternative"> Alternative representations</a> <span class="t-mark-rev t-since-c95">(C95)</span> </td> <td> alternative spellings for certain operators </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/punctuators" title="cpp/language/punctuators">C++ documentation</a></span> for <span class=""><span>Punctuation</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/punctuators" class="_attribution-link">https://en.cppreference.com/w/c/language/punctuators</a> + </p> +</div> diff --git a/devdocs/c/language%2Frestrict.html b/devdocs/c/language%2Frestrict.html new file mode 100644 index 00000000..10843a1a --- /dev/null +++ b/devdocs/c/language%2Frestrict.html @@ -0,0 +1,160 @@ + <h1 id="firstHeading" class="firstHeading">restrict type qualifier <span class="t-mark-rev t-since-c99">(since C99)</span> +</h1> <p>Each individual type in the C <a href="type" title="c/language/type">type system</a> has several <i>qualified</i> versions of that type, corresponding to one, two, or all three of the <a href="const" title="c/language/const"><code>const</code></a>, <a href="volatile" title="c/language/volatile"><code>volatile</code></a>, and, for pointers to object types, <code>restrict</code> qualifiers. This page describes the effects of the <code>restrict</code> qualifier.</p> +<p>Only a pointer to an <a href="type" title="c/language/type">object type</a> <span class="t-rev-inl t-since-c23"><span>or a (possibly multi-dimensional) array thereof</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> may be restrict-qualified; in particular, the following are <i>erroneous</i>:</p> +<ul> +<li> <code>int restrict *p</code> </li> +<li> <code>float (* restrict f9)(void)</code> </li> +</ul> <p>Restrict semantics apply to lvalue expressions only; for example, a cast to restrict-qualified pointer or a function call returning a restrict-qualified pointer are not lvalues and the qualifier has no effect.</p> +<p>During each execution of a block in which a restricted pointer <code>P</code> is declared (typically each execution of a function body in which <code>P</code> is a function parameter), if some object that is accessible through <code>P</code> (directly or indirectly) is modified, by any means, then all accesses to that object (both reads and writes) in that block must occur through <code>P</code> (directly or indirectly), otherwise the behavior is undefined:</p> +<div class="c source-c"><pre data-language="c">void f(int n, int * restrict p, int * restrict q) +{ + while (n-- > 0) + *p++ = *q++; // none of the objects modified through *p is the same + // as any of the objects read through *q + // compiler free to optimize, vectorize, page map, etc. +} + +void g(void) +{ + extern int d[100]; + f(50, d + 50, d); // OK + f(50, d + 1, d); // Undefined behavior: d[1] is accessed through both p and q in f +}</pre></div> <p>If the object is never modified, it may be aliased and accessed through different restrict-qualified pointers (note that if the objects pointed to by aliased restrict-qualified pointers are, in turn, pointers, this aliasing can inhibit optimization).</p> +<p>Assignment from one restricted pointer to another is undefined behavior, except when assigning from a pointer to an object in some outer block to a pointer in some inner block (including using a restricted pointer argument when calling a function with a restricted pointer parameter) or when returning from a function (and otherwise when the block of the from-pointer ended):</p> +<div class="c source-c"><pre data-language="c">int* restrict p1 = &a; +int* restrict p2 = &b; +p1 = p2; // undefined behavior</pre></div> <p>Restricted pointers can be assigned to unrestricted pointers freely, the optimization opportunities remain in place as long as the compiler is able to analyze the code:</p> +<div class="c source-c"><pre data-language="c">void f(int n, float * restrict r, float * restrict s) +{ + float *p = r, *q = s; // OK + while (n-- > 0) + *p++ = *q++; // almost certainly optimized just like *r++ = *s++ +}</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>If an array type is declared with the restrict type qualifier (through the use of <a href="typedef" title="c/language/typedef">typedef</a>), the array type is not restrict-qualified, but its element type is:</p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td> <p>An array type and its element type are always considered to be identically restrict-qualified:</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <div class="c source-c"><pre data-language="c">typedef int *array_t[10]; + +restrict array_t a; // the type of a is int *restrict[10] +// Notes: clang and icc reject this on the grounds that array_t is not a pointer type + +void *unqual_ptr = &a; // OK until C23; error since C23 +// Notes: clang applies the rule in C++/C23 even in C89-C17 modes</pre></div> <p>In a function declaration, the keyword <code>restrict</code> may appear inside the square brackets that are used to declare an array type of a function parameter. It qualifies the pointer type to which the array type is transformed:</p> +<div class="c source-c"><pre data-language="c">void f(int m, int n, float a[restrict m][n], float b[restrict m][n]); + +void g12(int n, float (*p)[n]) +{ + f(10, n, p, p+10); // OK + f(20, n, p, p+10); // possibly undefined behavior (depending on what f does) +}</pre></div> <h3 id="Notes"> Notes</h3> <p>The intended use of the restrict qualifier (like the register storage class) is to promote optimization, and deleting all instances of the qualifier from all preprocessing translation units composing a conforming program does not change its meaning (i.e., observable behavior).</p> +<p>The compiler is free to ignore any or all aliasing implications of uses of <code>restrict</code>.</p> +<p>To avoid undefined behavior, the programmer must ensure that the aliasing assertions made by the restrict-qualified pointers are not violated.</p> +<p>Many compilers provide, as a language extension, the opposite of <code>restrict</code>: an attribute indicating that pointers may alias even if their types differ: <a rel="nofollow" class="external text" href="https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html#index-g_t_0040code_007bmay_005falias_007d-type-attribute-3667"><code>may_alias</code></a> (gcc),</p> +<h3 id="Usage_patterns"> Usage patterns</h3> <p>There are several common usage patterns for restrict-qualified pointers:</p> +<h4 id="File_scope"> File scope</h4> <p>A file-scope restrict-qualified pointer has to point into a single array object for the duration of the program. That array object may not be referenced both through the restricted pointer and through either its declared name (if it has one) or another restricted pointer.</p> +<p>File scope restricted pointers are useful in providing access to dynamically allocated global arrays; the restrict semantics make it possible to optimize references through this pointer as effectively as references to a static array through its declared name:</p> +<div class="c source-c"><pre data-language="c">float *restrict a, *restrict b; +float c[100]; + +int init(int n) +{ + float * t = malloc(2*n*sizeof(float)); + a = t; // a refers to 1st half + b = t + n; // b refers to 2nd half +} +// compiler can deduce from the restrict qualifiers that +// there is no potential aliasing among the names a, b, and c</pre></div> <h4 id="Function_parameter"> Function parameter</h4> <p>The most popular use case for restrict-qualified pointers is the use as function parameters.</p> +<p>In the following example, the compiler may infer that there is no aliasing of modified objects, and so optimize the loop aggressively. Upon entry to <code>f</code>, the restricted pointer a must provide exclusive access to its associated array. In particular, within <code>f</code> neither <code>b</code> nor <code>c</code> may point into the array associated with <code>a</code>, because neither is assigned a pointer value based on <code>a</code>. For <code>b</code>, this is evident from the const-qualifier in its declaration, but for <code>c</code>, an inspection of the body of <code>f</code> is required:</p> +<div class="c source-c"><pre data-language="c">float x[100]; +float *c; + +void f(int n, float * restrict a, float * const b) +{ + int i; + for ( i=0; i<n; i++ ) + a[i] = b[i] + c[i]; +} + +void g3(void) +{ + float d[100], e[100]; + c = x; f(100, d, e); // OK + f( 50, d, d+50); // OK + f( 99, d+1, d); // undefined behavior + c = d; f( 99, d+1, e); // undefined behavior + f( 99, e, d+1); // OK +}</pre></div> <p>Note that it is permitted for c to point into the array associated with b. Note also that, for these purposes, the "array" associated with a particular pointer means only that portion of an array object which is actually referenced through that pointer.</p> +<p>Note that in the example above, the compiler can infer that a and b do not alias because b's constness guarantees that it cannot become dependent on a in the body of the function. Equivalently, the programmer could write <code>void f(int n, float * a, float const * restrict b)</code>, in which case the compiler can reason that objects referenced through b cannot be modified, and so no modified object can be referenced using both b and a. If the programmer were to write <code>void f(int n, float * restrict a, float * b)</code>, the compiler would be unable to infer non-aliasing of a and b without examining the body of the function.</p> +<p>In general, it is best to explicitly annotate all non-aliasing pointers in a function's prototype with <code>restrict</code>.</p> +<h4 id="Block_scope"> Block scope</h4> <p>A block scope restrict-qualified pointer makes an aliasing assertion that is limited to its block. It allows local assertions that apply only to important blocks, such as tight loops. It also makes it possible to convert a function that takes restrict-qualified pointers into a macro:</p> +<div class="c source-c"><pre data-language="c">float x[100]; +float *c; + +#define f3(N, A, B) \ +do \ +{ int n = (N); \ + float * restrict a = (A); \ + float * const b = (B); \ + int i; \ + for ( i=0; i<n; i++ ) \ + a[i] = b[i] + c[i]; \ +} while(0)</pre></div> <h4 id="Struct_members"> Struct members</h4> <p>The scope of the aliasing assertion made by a restrict-qualified pointer that is a member of a struct is the scope of the identifier used to access the struct.</p> +<p>Even if the struct is declared at file scope, when the identifier used to access the struct has block scope, the aliasing assertions in the struct also have block scope; the aliasing assertions are only in effect within a block execution or a function call, depending on how the object of this struct type was created:</p> +<div class="c source-c"><pre data-language="c">struct t // Restricted pointers assert that +{ + int n; // members point to disjoint storage. + float * restrict p; + float * restrict q; +}; + +void ff(struct t r, struct t s) +{ + struct t u; + // r,s,u have block scope + // r.p, r.q, s.p, s.q, u.p, u.q should all point to + // disjoint storage during each execution of ff. + // ... +}</pre></div> <h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/restrict" title="c/keyword/restrict"><code>restrict</code></a></p> +<h3 id="Example"> Example</h3> <p>code generation example; compile with -S (gcc, clang, etc) or /FA (visual studio)</p> +<div class="c source-c"><pre data-language="c">int foo(int *a, int *b) +{ + *a = 5; + *b = 6; + return *a + *b; +} + +int rfoo(int *restrict a, int *restrict b) +{ + *a = 5; + *b = 6; + return *a + *b; +}</pre></div> <p>Possible output:</p> +<div class="asm source-asm"><pre data-language="c">; generated code on 64bit Intel platform: +foo: + movl $5, (%rdi) ; store 5 in *a + movl $6, (%rsi) ; store 6 in *b + movl (%rdi), %eax ; read back from *a in case previous store modified it + addl $6, %eax ; add 6 to the value read from *a + ret + +rfoo: + movl $11, %eax ; the result is 11, a compile-time constant + movl $5, (%rdi) ; store 5 in *a + movl $6, (%rsi) ; store 6 in *b + ret</pre></div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.7.3.1 Formal definition of restrict (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.7.3.1 Formal definition of restrict (p: 89-90) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.7.3.1 Formal definition of restrict (p: 123-125) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.7.3.1 Formal definition of restrict (p: 110-112) </li></ul> +</ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/restrict" class="_attribution-link">https://en.cppreference.com/w/c/language/restrict</a> + </p> +</div> diff --git a/devdocs/c/language%2Freturn.html b/devdocs/c/language%2Freturn.html new file mode 100644 index 00000000..33a0ef72 --- /dev/null +++ b/devdocs/c/language%2Freturn.html @@ -0,0 +1,70 @@ + <h1 id="firstHeading" class="firstHeading">return statement</h1> <p>Terminates current function and returns specified value to the caller function.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span> <code>return</code> <span class="t-spar">expression</span> <code>;</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span> <code>return</code> <code>;</code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">expression</span> </td> <td> - </td> <td> expression used for initializing the return value of the function </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">attr-spec-seq</span> </td> <td> - </td> <td> <span class="t-mark-rev t-since-c23">(C23)</span>optional list of <a href="attributes" title="c/language/attributes">attributes</a>, applied to the <code>return</code> statement </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <div class="t-li1"> +<span class="t-li">1)</span> Evaluates the <span class="t-spar">expression</span>, terminates the current function and returns the result of the <span class="t-spar">expression</span> to the caller (the value returned becomes the value of the function call expression). Only valid if the function return type is not <code>void</code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Terminates the current function. Only valid if the function return type is <code>void</code>.</div> <p>If the type of the <span class="t-spar">expression</span> is different from the return type of the function, its value is <a href="conversion" title="c/language/conversion">converted</a> as if by assignment to an object whose type is the return type of the function, except that overlap between object representations is permitted:</p> +<div class="c source-c"><pre data-language="c">struct s { double i; } f(void); // function returning struct s +union { struct { int f1; struct s f2; } u1; + struct { struct s f3; int f4; } u2; } g; +struct s f(void) +{ + return g.u1.f2; +} +int main(void) +{ +// g.u2.f3 = g.u1.f2; // undefined behavior (overlap in assignment) + g.u2.f3 = f(); // well-defined +}</pre></div> <p>If the return type is a real floating type, the result may be represented in <a href="../types/limits/flt_eval_method" title="c/types/limits/FLT EVAL METHOD">greater range and precision</a> than implied by the new type.</p> +<p>Reaching the end of a function returning <code>void</code> is equivalent to <code>return;</code>. Reaching the end of any other value-returning function is undefined behavior if the result of the function is used in an expression (it is allowed to discard such return value). For <code>main</code>, see <a href="main_function" title="c/language/main function"><code>main</code> function</a>.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <p>Executing the <code>return</code> statement in a <a href="_noreturn" title="c/language/ Noreturn">no-return function</a> is undefined behavior.</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/return" title="c/keyword/return"><code>return</code></a></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +void fa(int i) +{ + if (i == 2) + return; + printf("fa(): %d\n", i); +} // implied return; + +int fb(int i) +{ + if (i > 4) + return 4; + printf("fb(): %d\n", i); + return 2; +} + +int main(void) +{ + fa(2); + fa(1); + int i = fb(5); // the return value 4 used to initializes i + i = fb(i); // the return value 2 used as rhs of assignment + printf("main(): %d\n", i); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">fa(): 1 +fb(): 4 +main(): 2</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.8.6.4 The return statement (p: 111-112) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.8.6.4 The return statement (p: 154) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.8.6.4 The return statement (p: 139) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.6.6.4 The return statement </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/return" title="cpp/language/return">C++ documentation</a></span> for <span class=""><span><code>return</code> statement</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/return" class="_attribution-link">https://en.cppreference.com/w/c/language/return</a> + </p> +</div> diff --git a/devdocs/c/language%2Fscalar_initialization.html b/devdocs/c/language%2Fscalar_initialization.html new file mode 100644 index 00000000..d0fd3411 --- /dev/null +++ b/devdocs/c/language%2Fscalar_initialization.html @@ -0,0 +1,50 @@ + <h1 id="firstHeading" class="firstHeading">Scalar initialization</h1> <p>When <a href="initialization" title="c/language/initialization">initializing</a> an object of <a href="type#Type_groups" title="c/language/type">scalar type</a>, the initializer must be a single expression</p> +<p>The initializer for a scalar (an object of integer type including booleans and enumerated types, floating type including complex and imaginary, and pointer type including pointer to function) must be a single expression, optionally enclosed in braces<span class="t-rev-inl t-since-c23"><span>, or an empty initializer</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>:</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>=</code> <span class="t-spar">expression</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>=</code> <code>{</code> <span class="t-spar">expression</span> <code>}</code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>=</code> <code>{</code> <code>}</code> </td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1,2)</span> The expression is evaluated, and its value, after <a href="conversion" title="c/language/conversion">conversion as if by assignment</a> to the type of the object, becomes the initial value of the object being initialized.</div> <div class="t-li1"> +<span class="t-li">3)</span> The object is <a href="initialization#Empty_initialization" title="c/language/initialization">empty-initialized</a>, i.e. initialized to numeric zero for an object of an arithmetic or enumeration type, or null pointer value for an object of a pointer type.</div> <h3 id="Notes"> Notes</h3> <p>Because of the rules that apply to conversions as if by assignment, <a href="const" title="c/language/const"><code>const</code></a> and <a href="volatile" title="c/language/volatile"><code>volatile</code></a> qualifiers on the declared type are ignored when determining which type to convert the <span class="t-spar">expression</span> to.</p> +<p>See <a href="initialization" title="c/language/initialization">initialization</a> for the rules that apply when no initializer is used.</p> +<p>As with all other initializations, <span class="t-spar">expression</span> must be a <a href="constant_expression" title="c/language/constant expression">constant expression</a> when initializing objects of static or thread-local <a href="storage_duration" title="c/language/storage duration">storage duration</a>.</p> +<p>The <span class="t-spar">expression</span> cannot be a <a href="operator_other#Comma_operator" title="c/language/operator other">comma operator</a> (unless parenthesized) because the comma at the top level would be interpreted as the beginning of the next declarator.</p> +<p>When initializing objects of floating-point type, all computations for the objects with automatic <a href="storage_duration" title="c/language/storage duration">storage duration</a> are done as-if at execution time and are affected by the <a href="../numeric/fenv/fe_round" title="c/numeric/fenv/FE round">current rounding</a>; floating-point errors are reported as specified in <a href="../numeric/math/math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>. For objects of static and thread-local storage duration, computations are done as-if at compile time, and no exceptions are raised:</p> +<div class="c source-c"><pre data-language="c">void f(void) +{ +#pragma STDC FENV_ACCESS ON + static float v = 1.1e75; // does not raise exceptions: static init + + float u[] = { 1.1e75 }; // raises FE_INEXACT + float w = 1.1e75; // raises FE_INEXACT + + double x = 1.1e75; // may raise FE_INEXACT (depends on FLT_EVAL_METHOD) + float y = 1.1e75f; // may raise FE_INEXACT (depends on FLT_EVAL_METHOD) + + long double z = 1.1e75; // does not raise exceptions (conversion is exact) +}</pre></div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdbool.h> +int main(void) +{ + bool b = true; + const double d = 3.14; + int k = 3.15; // conversion from double to int + int n = {12}, // optional braces + *p = &n, // non-constant expression OK for automatic variable + (*fp)(void) = main; + enum {RED, BLUE} e = RED; // enumerations are scalar types as well +}</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.7.9/11 Initialization (p: 101) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.7.9/11 Initialization (p: 140) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.7.8/11 Initialization (p: 126) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 6.5.7 Initialization </li></ul> +</ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/scalar_initialization" class="_attribution-link">https://en.cppreference.com/w/c/language/scalar_initialization</a> + </p> +</div> diff --git a/devdocs/c/language%2Fscope.html b/devdocs/c/language%2Fscope.html new file mode 100644 index 00000000..654166df --- /dev/null +++ b/devdocs/c/language%2Fscope.html @@ -0,0 +1,128 @@ + <h1 id="firstHeading" class="firstHeading">Scope</h1> <p>Each <a href="identifier" title="c/language/identifier">identifier</a> that appears in a C program is <i>visible</i> (that is, may be used) only in some possibly discontiguous portion of the source code called its <i>scope</i>.</p> +<p>Within a scope, an identifier may designate more than one entity only if the entities are in different <a href="name_space" title="c/language/name space">name spaces</a>.</p> +<p>C has four kinds of scopes:</p> +<ul> +<li> block scope </li> +<li> file scope </li> +<li> function scope </li> +<li> function prototype scope </li> +</ul> <h3 id="Nested_scopes"> Nested scopes</h3> <p>If two different entities named by the same identifier are in scope at the same time, and they belong to the same <a href="name_space" title="c/language/name space">name space</a>, the scopes are nested (no other form of scope overlap is allowed), and the declaration that appears in the inner scope hides the declaration that appears in the outer scope:</p> +<div class="c source-c"><pre data-language="c">// The name space here is ordinary identifiers. + +int a; // file scope of name a begins here + +void f(void) +{ + int a = 1; // the block scope of the name a begins here; hides file-scope a + { + int a = 2; // the scope of the inner a begins here, outer a is hidden + printf("%d\n", a); // inner a is in scope, prints 2 + } // the block scope of the inner a ends here + printf("%d\n", a); // the outer a is in scope, prints 1 +} // the scope of the outer a ends here + +void g(int a); // name a has function prototype scope; hides file-scope a</pre></div> <h3 id="Block_scope"> Block scope</h3> <p>The scope of any identifier declared inside a <a href="statements#Compound_statements" title="c/language/statements">compound statement</a>, including function bodies, <span class="t-rev-inl t-since-c99"><span>or in any expression, declaration, or statement appearing in <a href="if" title="c/language/if">if</a>, <a href="switch" title="c/language/switch">switch</a>, <a href="for" title="c/language/for">for</a>, <a href="while" title="c/language/while">while</a>, or <a href="do" title="c/language/do">do-while</a> statement</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>, or within the parameter list of a <a href="function_definition" title="c/language/function definition">function definition</a> begins at the point of declaration and ends at the end of the block or statement in which it was declared.</p> +<div class="c source-c"><pre data-language="c">void f(int n) // scope of the function parameter 'n' begins +{ // the body of the function begins + ++n; // 'n' is in scope and refers to the function parameter +// int n = 2; // error: cannot redeclare identifier in the same scope + for(int n = 0; n<10; ++n) { // scope of loop-local 'n' begins + printf("%d\n", n); // prints 0 1 2 3 4 5 6 7 8 9 + } // scope of the loop-local 'n' ends + // the function parameter 'n' is back in scope + printf("%d\n", n); // prints the value of the parameter +} // scope of function parameter 'n' ends +int a = n; // Error: name 'n' is not in scope</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>Until C99, selection and iteration statements did not establish their own block scopes (although if a compound statement was used in the statement, it had its usual block scope):</p> +<div class="c source-c"><pre data-language="c">enum {a, b}; +int different(void) +{ + if (sizeof(enum {b, a}) != sizeof(int)) + return a; // a == 1 + return b; // b == 0 in C89, b == 1 in C99 +}</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <p>Block-scope variables have <a href="storage_duration" title="c/language/storage duration">no linkage</a> and <a href="storage_duration" title="c/language/storage duration">automatic storage duration</a> by default. Note that storage duration for non-VLA local variables begins when the block is entered, but until the declaration is seen, the variable is not in scope and cannot be accessed.</p> +<h3 id="File_scope"> File scope</h3> <p>The scope of any identifier declared outside of any block or parameter list begins at the point of declaration and ends at the end of the translation unit.</p> +<div class="c source-c"><pre data-language="c">int i; // scope of i begins +static int g(int a) { return a; } // scope of g begins (note, "a" has block scope) +int main(void) +{ + i = g(2); // i and g are in scope +}</pre></div> <p>File-scope identifiers have <a href="storage_duration" title="c/language/storage duration">external linkage</a> and <a href="storage_duration" title="c/language/storage duration">static storage duration</a> by default.</p> +<h3 id="Function_scope"> Function scope</h3> <p>A <a href="statements#Labels" title="c/language/statements">label (and only a label)</a> declared inside a function is in scope everywhere in that function, in all nested blocks, before and after its own declaration. Note: a label is declared implicitly, by using an otherwise unused identifier before the colon character before any statement.</p> +<div class="c source-c"><pre data-language="c">void f() +{ + { + goto label; // label in scope even though declared later +label:; + } + goto label; // label ignores block scope +} + +void g() +{ + goto label; // error: label not in scope in g() +}</pre></div> <h3 id="Function_prototype_scope"> Function prototype scope</h3> <p>The scope of a name introduced in the parameter list of a <a href="function_declaration" title="c/language/function declaration">function declaration</a> that is not a definition ends at the end of the function <a href="declarations" title="c/language/declarations">declarator</a>.</p> +<div class="c source-c"><pre data-language="c">int f(int n, + int a[n]); // n is in scope and refers to the first parameter</pre></div> <p>Note that if there are multiple or nested declarators in the declaration, the scope ends at the end of the nearest enclosing function declarator:</p> +<div class="c source-c"><pre data-language="c">void f ( // function name 'f' is at file scope + long double f, // the identifier 'f' is now in scope, file-scope 'f' is hidden + char (**a)[10 * sizeof f] // 'f' refers to the first parameter, which is in scope +); + +enum{ n = 3 }; +int (*(*g)(int n))[n]; // the scope of the function parameter 'n' + // ends at the end of its function declarator + // in the array declarator, global n is in scope +// (this declares a pointer to function returning a pointer to an array of 3 int)</pre></div> <h3 id="Point_of_declaration"> Point of declaration</h3> <p>The scope of structure, union, and enumeration tags begins immediately after the appearance of the tag in a type specifier that declares the tag.</p> +<div class="c source-c"><pre data-language="c">struct Node { + struct Node* next; // Node is in scope and refers to this struct +};</pre></div> <p>The scope of enumeration constant begins immediately after the appearance of its defining enumerator in an enumerator list.</p> +<div class="c source-c"><pre data-language="c">enum { x = 12 }; +{ + enum { x = x + 1, // new x is not in scope until the comma, x is initialized to 13 + y = x + 1 // the new enumerator x is now in scope, y is initialized to 14 + }; +}</pre></div> <p>The scope of any other identifier begins just after the end of its declarator and before the initializer, if any:</p> +<div class="c source-c"><pre data-language="c">int x = 2; // scope of the first 'x' begins +{ + int x[x]; // scope of the newly declared x begins after the declarator (x[x]). + // Within the declarator, the outer 'x' is still in scope. + // This declares a VLA array of 2 int. +}</pre></div> <div class="c source-c"><pre data-language="c">unsigned char x = 32; // scope of the outer 'x' begins +{ + unsigned char x = x; + // scope of the inner 'x' begins before the initializer (= x) + // this does not initialize the inner 'x' with the value 32, + // this initializes the inner 'x' with its own, indeterminate, value +} + +unsigned long factorial(unsigned long n) +// declarator ends, 'factorial' is in scope from this point +{ + return n<2 ? 1 : n*factorial(n-1); // recursive call +}</pre></div> <p>As a special case, the scope of a <a href="type" title="c/language/type">type name</a> that is not a declaration of an identifier is considered to begin just after the place within the type name where the identifier would appear were it not omitted.</p> +<h3 id="Notes"> Notes</h3> <p>Prior to C89, identifiers with external linkage had file scope even when introduced within a block, and because of that, a C89 compiler is not required to diagnose the use of an extern identifier that has gone out of scope (such use is undefined behavior).</p> +<p>Local variables within a loop body can hide variables declared in the init clause of a <a href="for" title="c/language/for">for</a> loop in C (their scope is nested), but cannot do that in C++.</p> +<p>Unlike C++, C has no struct scope: names declared within a struct/union/enum declaration are in the same scope as the struct declaration (except that data members are in their own <a href="name_space" title="c/language/name space">member name space</a>):</p> +<div class="c source-c"><pre data-language="c">struct foo { + struct baz {}; + enum color {RED, BLUE}; +}; +struct baz b; // baz is in scope +enum color x = RED; // color and RED are in scope</pre></div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.2.1 Scopes of identifiers (p: 28-29) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.2.1 Scopes of identifiers (p: 35-36) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.2.1 Scopes of identifiers (p: 29-30) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.1.2.1 Scopes of identifiers </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/scope" title="cpp/language/scope">C++ documentation</a></span> for <span class=""><span>Scope</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/scope" class="_attribution-link">https://en.cppreference.com/w/c/language/scope</a> + </p> +</div> diff --git a/devdocs/c/language%2Fsizeof.html b/devdocs/c/language%2Fsizeof.html new file mode 100644 index 00000000..afac1a41 --- /dev/null +++ b/devdocs/c/language%2Fsizeof.html @@ -0,0 +1,69 @@ + <h1 id="firstHeading" class="firstHeading">sizeof operator</h1> <p>Queries size of the object or type.</p> +<p>Used when actual size of the object must be known.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>sizeof(</code> <span class="t-spar">type</span> <code>)</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>sizeof</code> <span class="t-spar">expression</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>Both versions return a value of type <code><a href="../types/size_t" title="c/types/size t">size_t</a></code>.</p> +<h3 id="Explanation"> Explanation</h3> <div class="t-li1"> +<span class="t-li">1)</span> Returns the size, in bytes, of the <a href="object#Object_representation" title="c/language/object">object representation</a> of <span class="t-spar">type</span> +</div> <div class="t-li1"> +<span class="t-li">2)</span> Returns the size, in bytes, of the object representation of the type of <span class="t-spar">expression</span>. No implicit conversions are applied to <span class="t-spar">expression</span>.</div> <h3 id="Notes"> Notes</h3> <p>Depending on the computer architecture, a <a href="https://en.wikipedia.org/wiki/byte" class="extiw" title="enwiki:byte">byte</a> may consist of 8 or more bits, the exact number provided as <code><a href="../types/limits" title="c/types/limits">CHAR_BIT</a></code>.</p> +<p><code>sizeof(char)</code>, <code>sizeof(signed char)</code>, and <code>sizeof(unsigned char)</code> always return <code>1</code>.</p> +<p>sizeof cannot be used with function types, incomplete types (including <code>void</code>), or <a href="bit_field" title="c/language/bit field">bit-field</a> lvalues.</p> +<p>When applied to an operand that has <a href="struct" title="c/language/struct">structure</a> or <a href="union" title="c/language/union">union</a> type, the result is the total number of bytes in such an object, including internal and trailing padding. The trailing padding is such that if the object were an element of an array, the alignment requirement of the next element of this array would be satisfied, in other words, <code>sizeof(T)</code> returns the size of an element of a <code>T[]</code> array.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>If <span class="t-spar">type</span> is a <a href="array" title="c/language/array">VLA</a> type and changing the value of its size expression would not affect the result of <code>sizeof</code>, it is unspecified whether or not the size expression is evaluated.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <p><span class="t-rev-inl t-since-c99"><span>Except if the type of <span class="t-spar">expression</span> is a <a href="array" title="c/language/array">VLA</a>,</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span><span class="t-spar">expression</span> is not evaluated and the <code>sizeof</code> operator may be used in an integer <a href="constant_expression" title="c/language/constant expression">constant expression</a>.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>If the type of <span class="t-spar">expression</span> is a <a href="array" title="c/language/array">variable-length array</a> type, <span class="t-spar">expression</span> is evaluated and the size of the array it evaluates to is calculated at run time.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <p>Number of elements in any <a href="array" title="c/language/array">array</a> <code>a</code> <span class="t-rev-inl t-since-c99"><span>including VLA</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> may be determined with the expression <code>sizeof a / sizeof a[0]</code>. Note that if <code>a</code> has pointer type (such as after array-to-pointer conversion of function parameter type adjustment), this expression would simply divide the number of bytes in a pointer type by the number of bytes in the pointed type.</p> +<h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/sizeof" title="c/keyword/sizeof"><code>sizeof</code></a></p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>Sample output corresponds to a platform with 64-bit pointers and 32-bit int</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> + +int main(void) +{ + short x; + // type argument: + printf("sizeof(float) = %zu\n", sizeof(float)); + printf("sizeof(void(*)(void)) = %zu\n", sizeof(void(*)(void))); + printf("sizeof(char[10]) = %zu\n", sizeof(char[10])); +// printf("sizeof(void(void)) = %zu\n", sizeof(void(void))); // Error: function type +// printf("sizeof(char[]) = %zu\n", sizeof(char[])); // Error: incomplete type + + // expression argument: + printf("sizeof 'a' = %zu\n", sizeof 'a'); // type of 'a' is int +// printf("sizeof main = %zu\n", sizeof main); // Error: Function type + printf("sizeof &main = %zu\n", sizeof &main); + printf("sizeof \"hello\" = %zu\n", sizeof "hello"); // type is char[6] + printf("sizeof x = %zu\n", sizeof x); // type of x is short + printf("sizeof (x+1) = %zu\n", sizeof(x + 1)); // type of x+1 is int +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">sizeof(float) = 4 +sizeof(void(*)(void)) = 8 +sizeof(char[10]) = 10 +sizeof 'a' = 4 +sizeof &main = 8 +sizeof "hello" = 6 +sizeof x = 2 +sizeof (x+1) = 4</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.5.3.4 The sizeof and alignof operators (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.5.3.4 The sizeof and _Alignof operators (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.5.3.4 The sizeof and _Alignof operators (p: 90-91) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.5.3.4 The sizeof operator (p: 80-81) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.3.3.4 The sizeof operator </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/sizeof" title="cpp/language/sizeof">C++ documentation</a></span> for <span class=""><span><code>sizeof</code> operator</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/sizeof" class="_attribution-link">https://en.cppreference.com/w/c/language/sizeof</a> + </p> +</div> diff --git a/devdocs/c/language%2Fstatements.html b/devdocs/c/language%2Fstatements.html new file mode 100644 index 00000000..09713f6a --- /dev/null +++ b/devdocs/c/language%2Fstatements.html @@ -0,0 +1,113 @@ + <h1 id="firstHeading" class="firstHeading">Statements</h1> <p>Statements are fragments of the C program that are executed in sequence. The body of any function is a compound statement, which, in turn is a sequence of statements and declarations:</p> +<div class="c source-c"><pre data-language="c">int main(void) +{ // start of a compound statement + int n = 1; // declaration (not a statement) + n = n+1; // expression statement + printf("n = %d\n", n); // expression statement + return 0; // return statement +} // end of compound statement, end of function body</pre></div> <p><br> There are five types of statements:</p> +<div class="t-li1"> +<span class="t-li">1)</span> <a href="#Compound_statements">compound statements</a> +</div> <div class="t-li1"> +<span class="t-li">2)</span> <a href="#Expression_statements">expression statements</a> +</div> <div class="t-li1"> +<span class="t-li">3)</span> <a href="#Selection_statements">selection statements</a> +</div> <div class="t-li1"> +<span class="t-li">4)</span> <a href="#Iteration_statements">iteration statements</a> +</div> <div class="t-li1"> +<span class="t-li">5)</span> <a href="#Jump_statements">jump statements</a> +</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>An <a href="attributes" title="c/language/attributes">attribute specifier sequence</a> (<span class="t-spar">attr-spec-seq</span>) can be applied to an unlabeled statement, in which case (except for an expression statement) the attributes are applied to the respective statement.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Labels"> Labels</h3> <p>Any statement can be <i>labeled</i>, by providing a name followed by a colon before the statement itself.</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span><span class="t-mark-rev t-since-c23">(since C23)</span> <span class="t-spar">identifier</span> <code>:</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span><span class="t-mark-rev t-since-c23">(since C23)</span> <code>case</code> <span class="t-spar">constant-expression</span> <code>:</code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span><span class="t-mark-rev t-since-c23">(since C23)</span> <code>default</code> <code>:</code> </td> <td> (3) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> Target for <a href="goto" title="c/language/goto">goto</a>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Case label in a <a href="switch" title="c/language/switch">switch</a> statement.</div> <div class="t-li1"> +<span class="t-li">3)</span> Default label in a <a href="switch" title="c/language/switch">switch</a> statement.</div> <p>Any statement (but not a declaration) may be preceded by any number of <i>labels</i>, each of which declares <span class="t-spar">identifier</span> to be a label name, which must be unique within the enclosing function (in other words, label names have <a href="scope" title="c/language/scope">function scope</a>).</p> +<p>Label declaration has no effect on its own, does not alter the flow of control, or modify the behavior of the statement that follows in any way.</p> +<table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>A label shall be followed by a statement.</p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td> <p>A label can appear without its following statement. If a label appears alone in a block, it behaves as if it is followed by a <a href="#Expression_statements">null statement</a>.</p> +<p>The optional <a href="attributes" title="c/language/attributes"><span class="t-spar">attr-spec-seq</span></a> is applied to the label.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Compound_statements"> Compound statements</h3> <p>A compound statement, or <i>block</i>, is a brace-enclosed sequence of statements and declarations.</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>{</code> <span class="t-spar">statement</span> <code>|</code> <span class="t-spar">declaration</span>...<span class="t-mark">(optional)</span> <code>} </code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-until-c23">(until C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span> <code>{</code> <span class="t-spar">unlabeled-statement</span> <code>|</code> <span class="t-spar">label</span> <code>|</code> <span class="t-spar">declaration</span>...<span class="t-mark">(optional)</span> <code>} </code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <p>The compound statement allows a set of declarations and statements to be grouped into one unit that can be used anywhere a single statement is expected (for example, in an <a href="if" title="c/language/if">if</a> statement or an iteration statement):</p> +<div class="c source-c"><pre data-language="c">if (expr) // start of if-statement +{ // start of block + int n = 1; // declaration + printf("%d\n", n); // expression statement +} // end of block, end of if-statement</pre></div> <p>Each compound statement introduces its own <a href="scope" title="c/language/scope">block scope</a>.</p> +<p>The initializers of the variables with automatic <a href="storage_duration" title="c/language/storage duration">storage duration</a> declared inside a block and the VLA declarators are executed when flow of control passes over these declarations in order, as if they were statements:</p> +<div class="c source-c"><pre data-language="c">int main(void) +{ // start of block + { // start of block + puts("hello"); // expression statement + int n = printf("abc\n"); // declaration, prints "abc", stores 4 in n + int a[n*printf("1\n")]; // declaration, prints "1", allocates 8*sizeof(int) + printf("%zu\n", sizeof(a)); // expression statement + } // end of block, scope of n and a ends + int n = 7; // n can be reused +}</pre></div> <h3 id="Expression_statements"> Expression statements</h3> <p>An expression followed by a semicolon is a statement.</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="t-spar">expression</span><span class="t-mark">(optional)</span> <code>;</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span> <span class="t-spar">expression</span> <code>;</code> </td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <p>Most statements in a typical C program are expression statements, such as assignments or function calls.</p> +<p>An expression statement without an expression is called a <i>null statement</i>. It is often used to provide an empty body to a <a href="for" title="c/language/for">for</a> or <a href="while" title="c/language/while">while</a> loop. It can also be used to carry a label in the end of a compound statement or before a declaration:</p> +<div class="c source-c"><pre data-language="c">puts("hello"); // expression statement +char *s; +while (*s++ != '\0') + ; // null statement</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>The optional <a href="attributes" title="c/language/attributes"><span class="t-spar">attr-spec-seq</span></a> is applied to the expression.</p> +<p>An <span class="t-spar">attr-spec-seq</span> followed by <code>;</code> does not form an expression statement. It forms an <a href="declarations" title="c/language/declarations">attribute declaration</a> instead.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Selection_statements"> Selection statements</h3> <p>The selection statements choose between one of several statements depending on the value of an expression.</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span><span class="t-mark-rev t-since-c23">(since C23)</span> <code>if</code> <code>(</code> <span class="t-spar">expression</span> <code>)</code> <span class="t-spar">statement</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span><span class="t-mark-rev t-since-c23">(since C23)</span> <code>if</code> <code>(</code> <span class="t-spar">expression</span> <code>)</code> <span class="t-spar">statement</span> <code>else</code> <span class="t-spar">statement</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span><span class="t-mark-rev t-since-c23">(since C23)</span> <code>switch</code> <code>(</code> <span class="t-spar">expression</span> <code>)</code> <span class="t-spar">statement</span> </td> <td> (3) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> <a href="if" title="c/language/if">if</a> statement</div> <div class="t-li1"> +<span class="t-li">2)</span> <a href="if" title="c/language/if">if</a> statement with an else clause</div> <div class="t-li1"> +<span class="t-li">3)</span> <a href="switch" title="c/language/switch">switch</a> statement</div> <h3 id="Iteration_statements"> Iteration statements</h3> <p>The iteration statements repeatedly execute a statement.</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span><span class="t-mark-rev t-since-c23">(since C23)</span> <code>while</code> <code>(</code> <span class="t-spar">expression</span> <code>)</code> <span class="t-spar">statement</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span><span class="t-mark-rev t-since-c23">(since C23)</span> <code>do</code> <span class="t-spar">statement</span> <code>while</code> <code>(</code> <span class="t-spar">expression</span> <code>)</code> <code>;</code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span><span class="t-mark-rev t-since-c23">(since C23)</span> <code>for</code> <code>(</code> <span class="t-spar">init-clause</span> <code>;</code> <span class="t-spar">expression</span><span class="t-mark">(optional)</span> <code>;</code> <span class="t-spar">expression</span><span class="t-mark">(optional)</span> <code>)</code> <span class="t-spar">statement</span> </td> <td> (3) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> <a href="while" title="c/language/while">while</a> loop</div> <div class="t-li1"> +<span class="t-li">2)</span> <a href="do" title="c/language/do">do-while</a> loop</div> <div class="t-li1"> +<span class="t-li">3)</span> <a href="for" title="c/language/for">for</a> loop</div> <h3 id="Jump_statements"> Jump statements</h3> <p>The jump statements unconditionally transfer flow control.</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span><span class="t-mark-rev t-since-c23">(since C23)</span> <code>break</code> <code>;</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span><span class="t-mark-rev t-since-c23">(since C23)</span> <code>continue</code> <code>;</code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span><span class="t-mark-rev t-since-c23">(since C23)</span> <code>return</code> <span class="t-spar">expression</span><span class="t-mark">(optional)</span> <code>;</code> </td> <td> (3) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span><span class="t-mark-rev t-since-c23">(since C23)</span> <code>goto</code> <span class="t-spar">identifier</span> <code>;</code> </td> <td> (4) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> <a href="break" title="c/language/break">break</a> statement</div> <div class="t-li1"> +<span class="t-li">2)</span> <a href="continue" title="c/language/continue">continue</a> statement</div> <div class="t-li1"> +<span class="t-li">3)</span> <a href="return" title="c/language/return">return</a> statement with an optional expression</div> <div class="t-li1"> +<span class="t-li">4)</span> <a href="goto" title="c/language/goto">goto</a> statement</div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.8 Statements and blocks (p: 106-112) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.8 Statements and blocks (p: 146-154) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.8 Statements and blocks (p: 131-139) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.6 STATEMENTS </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/statements" title="cpp/language/statements">C++ documentation</a></span> for <span class=""><span>Statements</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/statements" class="_attribution-link">https://en.cppreference.com/w/c/language/statements</a> + </p> +</div> diff --git a/devdocs/c/language%2Fstatic_assert.html b/devdocs/c/language%2Fstatic_assert.html new file mode 100644 index 00000000..edc18201 --- /dev/null +++ b/devdocs/c/language%2Fstatic_assert.html @@ -0,0 +1,58 @@ + <h1 id="firstHeading" class="firstHeading">Static assertion <span class="t-mark-rev t-since-c11">(since C11)</span> +</h1> <h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>_Static_assert</code> <code>(</code> <span class="t-spar">expression</span> <code>,</code> <span class="t-spar">message</span> <code>)</code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span><span class="t-mark-rev t-deprecated-c23">(deprecated in C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>static_assert</code> <code>(</code> <span class="t-spar">expression</span> <code>,</code> <span class="t-spar">message</span> <code>)</code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>_Static_assert</code> <code>(</code> <span class="t-spar">expression</span> <code>)</code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span><span class="t-mark-rev t-deprecated-c23">(deprecated in C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>static_assert</code> <code>(</code> <span class="t-spar">expression</span> <code>)</code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">expression</span> </td> <td> - </td> <td> any <a href="constant_expression" title="c/language/constant expression">integer constant expression</a> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">message</span> </td> <td> - </td> <td> any <a href="string_literal" title="c/language/string literal">string literal</a> </td> +</tr> +</table> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>This keyword is also available as convenience macro <a href="../error/static_assert" title="c/error/static assert"><code>static_assert</code></a>, available in the header <a href="../error" title="c/error"><code><assert.h></code></a>.</p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td> <p>Both of <code>static_assert</code> and <code>_Static_assert</code> have the same effects. <code>_Static_assert</code> is a deprecated spelling that is kept for compatibility.</p> +<p>An implementation may also define <code>static_assert</code> and/or <code>_Static_assert</code> as predefined macros, and <code>static_assert</code> is no longer provided by <a href="../error" title="c/error"><code><assert.h></code></a>.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Explanation"> Explanation</h3> <p>The constant expression is evaluated at compile time and compared to zero. If it compares equal to zero, a compile-time error occurs and the compiler <span class="t-rev-inl t-until-c23"><span>must display <span class="t-spar">message</span> as part of the error message (except that characters not in <a href="charset" title="c/language/charset">basic character set</a> are not required to be displayed)</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span>should display <span class="t-spar">message</span> (if provided) as part of the error message</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>.</p> +<p>Otherwise, if <span class="t-spar">expression</span> does not equal zero, nothing happens; no code is emitted.</p> +<h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/_static_assert" title="c/keyword/ Static assert"><code>_Static_assert</code></a>, <a href="../keyword/static_assert" title="c/keyword/static assert"><code>static_assert</code></a></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <assert.h> // no longer needed since C23 + +int main(void) +{ + // Test if math works, C23: + static_assert((2 + 2) % 3 == 1, "Whoa dude, you knew!"); + // Pre-C23 alternative: + _Static_assert(2 + 2 * 2 == 6, "Lucky guess!?"); + + // This will produce an error at compile time. + // static_assert(sizeof(int) < sizeof(char), "Unmet condition!"); + + constexpr int _42 = 2 * 3 * 2 * 3 + 2 * 3; + static_assert(_42 == 42); // the message string can be omitted. + + // const int _13 = 13; + // Compile time error - not an integer constant expression: + // static_assert(_13 == 13); +}</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.7.11 Static assertions (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.7.10 Static assertions (p: 105) </li> +<li> 7.2 Diagnostics <assert.h> (p: 135) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.7.10 Static assertions (p: 145) </li> +<li> 7.2 Diagnostics <assert.h> (p: 186-187) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../error/assert" title="c/error/assert"> <span class="t-lines"><span>assert</span></span></a></div> </td> <td> aborts the program if the user-specified condition is not <code>true</code>. May be disabled for release builds <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/static_assert" title="cpp/language/static assert">C++ documentation</a></span> for <span class=""><span><code>static_assert</code> declaration</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/static_assert" class="_attribution-link">https://en.cppreference.com/w/c/language/static_assert</a> + </p> +</div> diff --git a/devdocs/c/language%2Fstatic_storage_duration.html b/devdocs/c/language%2Fstatic_storage_duration.html new file mode 100644 index 00000000..2ca1a227 --- /dev/null +++ b/devdocs/c/language%2Fstatic_storage_duration.html @@ -0,0 +1,32 @@ + <h1 id="firstHeading" class="firstHeading">Static storage duration</h1> <p>An object whose identifier is declared without the storage-class specifier <code>_Thread_local</code>, and either with external or internal <a href="storage_duration#Linkage" title="c/language/storage duration">linkage</a> or with the storage-class specifier <code>static</code>, has static storage duration. Its lifetime is the entire execution of the program and its stored value is initialized only once, prior to program startup.</p> +<h3 id="Notes"> Notes</h3> <p>Since its stored value is initialized only once, an object with static storage duration can profile the invocations of a function.</p> +<p>The other use of the keyword <code>static</code> is <a href="file_scope" title="c/language/file scope">file scope</a>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +void f (void) +{ + static int count = 0; // static variable + int i = 0; // automatic variable + printf("%d %d\n", i++, count++); +} + +int main(void) +{ + for (int ndx=0; ndx<10; ++ndx) + f(); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">0 0 +0 1 +0 2 +0 3 +0 4 +0 5 +0 6 +0 7 +0 8 +0 9</pre></div> </div> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/static_storage_duration" class="_attribution-link">https://en.cppreference.com/w/c/language/static_storage_duration</a> + </p> +</div> diff --git a/devdocs/c/language%2Fstorage_duration.html b/devdocs/c/language%2Fstorage_duration.html new file mode 100644 index 00000000..558ffa50 --- /dev/null +++ b/devdocs/c/language%2Fstorage_duration.html @@ -0,0 +1,144 @@ + <h1 id="firstHeading" class="firstHeading">Storage-class specifiers</h1> <p>Specify <i>storage duration</i> and <i>linkage</i> of objects and functions:</p> +<ul> +<li> +<code>auto</code> - automatic duration and no linkage </li> +<li> +<code>register</code> - automatic duration and no linkage; address of this variable cannot be taken </li> +<li> +<code>static</code> - static duration and internal linkage (unless at block scope) </li> +<li> +<code>extern</code> - static duration and external linkage (unless already declared internal) </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <ul><li> +<span class="t-rev-inl t-until-c23"><span><code>_Thread_local</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>thread_local</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> - thread storage duration </li></ul> </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <h3 id="Explanation"> Explanation</h3> <p>Storage-class specifiers appear in <a href="declarations" title="c/language/declarations">declarations</a><span class="t-rev-inl t-since-c23"><span> and <a href="compound_literal" title="c/language/compound literal">compound literal</a> expressions</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>. At most one specifier may be used<span class="t-rev-inl t-since-c11"><span>, except that <span class="t-rev-inl t-until-c23"><span>_Thread_local</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><a href="http://en.cppreference.com/w/c/thread/thread_local"><span class="kw1032">thread_local</span></a></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> may be combined with <span class="kw4">static</span> or <span class="kw2">extern</span> to adjust linkage</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span>. The storage-class specifiers determine two independent properties of the names they declare: <i>storage duration</i> and <i>linkage</i>.</p> +<div class="t-li1"> +<span class="t-li">1)</span> The <span class="kw4">auto</span> specifier is only allowed for objects declared at block scope (except function parameter lists). It indicates automatic storage duration and no linkage, which are the defaults for these kinds of declarations.</div> <div class="t-li1"> +<span class="t-li">2)</span> The <span class="kw4">register</span> specifier is only allowed for objects declared at block scope, including function parameter lists. It indicates automatic storage duration and no linkage (which is the default for these kinds of declarations), but additionally hints the optimizer to store the value of this variable in a CPU register if possible. Regardless of whether this optimization takes place or not, variables declared <span class="kw4">register</span> cannot be used as arguments to the <a href="operator_member_access" title="c/language/operator member access">address-of operator</a><span class="t-rev-inl t-since-c11"><span>, cannot use <a href="_alignas" title="c/language/ Alignas">alignas</a></span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span>, and <span class="kw4">register</span> arrays are not convertible to pointers.</div> <div class="t-li1"> +<span class="t-li">3)</span> The <span class="kw4">static</span> specifier specifies both static storage duration<span class="t-rev-inl t-since-c11"><span> (unless combined with _Thread_local)</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> and internal linkage (unless used at block scope). It can be used with functions at file scope and with variables at both file and block scope, but not in function parameter lists.</div> <div class="t-li1"> +<span class="t-li">4)</span> The <span class="kw2">extern</span> specifier specifies static storage duration<span class="t-rev-inl t-since-c11"><span> (unless combined with <span class="t-rev-inl t-until-c23"><span>_Thread_local</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><a href="http://en.cppreference.com/w/c/thread/thread_local"><span class="kw1032">thread_local</span></a></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>)</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> and external linkage. It can be used with function and object declarations in both file and block scope (excluding function parameter lists). If <span class="kw2">extern</span> appears on a redeclaration of an identifier that was already declared with internal linkage, the linkage remains internal. Otherwise (if the prior declaration was external, no-linkage, or is not in scope), the linkage is external.</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <span class="t-li">5)</span> <span class="t-rev-inl t-until-c23"><span>_Thread_local</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><a href="http://en.cppreference.com/w/c/thread/thread_local"><span class="kw1032">thread_local</span></a></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> indicates <i>thread storage duration</i>. It cannot be used with function declarations. If it is used on a declaration of an object, it must be present on every declaration of the same object. If it is used on a block-scope declaration, it must be combined with either <span class="kw4">static</span> or <span class="kw2">extern</span> to decide linkage. </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <p>If no storage-class specifier is provided, the defaults are:</p> +<dl> +<dd> <span class="kw2">extern</span> for all functions </dd> +<dd> <span class="kw2">extern</span> for objects at file scope </dd> +<dd> <span class="kw4">auto</span> for objects at block scope </dd> +</dl> <p>For any struct or union declared with a storage-class specifier, the storage duration (but not linkage) applies to their members, recursively.</p> +<p>Function declarations at block scope can use <span class="kw2">extern</span> or none at all. Function declarations at file scope can use <span class="kw2">extern</span> or <span class="kw4">static</span>.</p> +<p>Function parameters cannot use any storage-class specifiers other than <span class="kw4">register</span>. Note that <span class="kw4">static</span> has special meaning in function parameters of array type.</p> +<h3 id="Storage_duration"> Storage duration</h3> <p>Every <a href="object" title="c/language/object">object</a> has a property called <i>storage duration</i>, which limits the object <a href="lifetime" title="c/language/lifetime">lifetime</a>. There are four kinds of storage duration in C:</p> +<ul> +<li> +<i><b>automatic</b></i> storage duration. The storage is allocated when the <a href="statements#Compound_statements" title="c/language/statements">block</a> in which the object was declared is entered and deallocated when it is exited by any means (<a href="goto" title="c/language/goto">goto</a>, <a href="return" title="c/language/return">return</a>, reaching the end). <span class="t-rev-inl t-since-c99"><span>One exception is the <a href="array#Variable-length_arrays" title="c/language/array">VLAs</a>; their storage is allocated when the declaration is executed, not on block entry, and deallocated when the declaration goes out of scope, not when the block is exited</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>. If the block is entered recursively, a new allocation is performed for every recursion level. All function parameters and non-<span class="kw4">static</span> block-scope objects have this storage duration, <span class="t-rev-inl t-until-c23"><span>as well as <a href="compound_literal" title="c/language/compound literal">compound literals</a> used at block scope</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span> </li> +<li> +<i><b>static</b></i> storage duration. The storage duration is the entire execution of the program, and the value stored in the object is initialized only once, prior to <a href="main_function" title="c/language/main function">main function</a>. All objects declared <span class="kw4">static</span> and all objects with either internal or external linkage<span class="t-rev-inl t-since-c11"><span> that aren't declared <span class="t-rev-inl t-until-c23"><span>_Thread_local</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><a href="http://en.cppreference.com/w/c/thread/thread_local"><span class="kw1032">thread_local</span></a></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span></span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> have this storage duration. </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <ul><li> +<i><b>thread</b></i> storage duration. The storage duration is the entire execution of the thread in which it was created, and the value stored in the object is initialized when the thread is started. Each thread has its own, distinct, object. If the thread that executes the expression that accesses this object is not the thread that executed its initialization, the behavior is implementation-defined. All objects declared <span class="t-rev-inl t-until-c23"><span>_Thread_local</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><a href="http://en.cppreference.com/w/c/thread/thread_local"><span class="kw1032">thread_local</span></a></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> have this storage duration. </li></ul> </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <ul><li> +<i><b>allocated</b></i> storage duration. The storage is allocated and deallocated on request, using <a href="../memory" title="c/memory">dynamic memory allocation</a> functions. </li></ul> <h4 id="Linkage"> Linkage</h4> <p>Linkage refers to the ability of an identifier (variable or function) to be referred to in other scopes. If a variable or function with the same identifier is declared in several scopes, but cannot be referred to from all of them, then several instances of the variable are generated. The following linkages are recognized:</p> +<ul> +<li> +<i><b>no linkage</b></i>. The identifier can be referred to only from the scope it is in. All function parameters and all non-<span class="kw2">extern</span> block-scope variables (including the ones declared <span class="kw4">static</span>) have this linkage. </li> +<ul> +<li> +<i><b>internal linkage</b></i>. The identifier can be referred to from all scopes in the current translation unit. All <span class="kw4">static</span> file-scope identifiers (both functions and variables) have this linkage. </li> +<li> +<i><b>external linkage</b></i>. The identifier can be referred to from any other translation units in the entire program. All non-<span class="kw4">static</span> functions, all <span class="kw2">extern</span> variables (unless earlier declared <span class="kw4">static</span>), and all file-scope non-<span class="kw4">static</span> variables have this linkage. </li> +</ul> +</ul> <p>If the same identifier appears with both internal and external linkage in the same translation unit, the behavior is undefined. This is possible when <a href="extern" title="c/language/extern">tentative definitions</a> are used.</p> +<h4 id="Linkage_and_libraries"> Linkage and libraries</h4> <p>Declarations with external linkage are commonly made available in header files so that all translation units that <a href="../preprocessor/include" title="c/preprocessor/include">#include</a> the file may refer to the same identifier that are defined elsewhere.</p> +<p>Any declaration with internal linkage that appears in a header file results in a separate and distinct object in each translation unit that includes that file.</p> +<table class="t-rev-begin"> <tr class="t-rev"> +<td> <p>Library interface, header file "flib.h":</p> +<div class="c source-c"><pre data-language="c">#ifndef FLIB_H +#define FLIB_H +void f(void); // function declaration with external linkage +extern int state; // variable declaration with external linkage +static const int size = 5; // definition of a read-only variable with internal linkage +enum { MAX = 10 }; // constant definition +inline int sum (int a, int b) { return a + b; } // inline function definition +#endif // FLIB_H</pre></div> <p>Library implementation, source file "flib.c":</p> +<div class="c source-c"><pre data-language="c">#include "flib.h" + +static void local_f(int s) {} // definition with internal linkage (only used in this file) +static int local_state; // definition with internal linkage (only used in this file) + +int state; // definition with external linkage (used by main.c) +void f(void) { local_f(state); } // definition with external linkage (used by main.c)</pre></div> <p>Application code, source file "main.c":</p> +<div class="c source-c"><pre data-language="c">#include "flib.h" + +int main(void) +{ + int x[MAX] = {size}; // uses the constant and the read-only variable + state = 7; // modifies state in flib.c + f(); // calls f() in flib.c +}</pre></div> </td> <td></td> +</tr> </table> <h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/auto" title="c/keyword/auto"><code>auto</code></a>, <a href="../keyword/register" title="c/keyword/register"><code>register</code></a>, <a href="../keyword/static" title="c/keyword/static"><code>static</code></a>, <a href="../keyword/extern" title="c/keyword/extern"><code>extern</code></a>, <a href="../keyword/_thread_local" title="c/keyword/ Thread local"><code>_Thread_local</code></a> <a href="../keyword/thread_local" title="c/keyword/thread local"><code>thread_local</code></a></p> +<h3 id="Notes"> Notes</h3> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>The keyword _Thread_local is usually used through the convenience macro <code><a href="../thread/thread_local" title="c/thread/thread local">thread_local</a></code>, defined in the header <a href="../thread" title="c/thread"><code><threads.h></code></a>.</p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> </table> <p>The <a href="typedef" title="c/language/typedef"><code>typedef</code></a><span class="t-rev-inl t-since-c23"><span> and <a href="constexpr" title="c/language/constexpr"><code>constexpr</code></a></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> specifiers are formally listed as storage-class specifiers in the C language grammar, but do not specify storage.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>The auto specifier is also used for type inference.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <p>Names at file scope that are <span class="kw4">const</span> and not <span class="kw2">extern</span> have external linkage in C (as the default for all file-scope declarations), but internal linkage in C++.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +// static storage duration +int A; + +int main(void) +{ + printf("&A = %p\n", (void*)&A); + + // automatic storage duration + int A = 1; // hides global A + printf("&A = %p\n", (void*)&A); + + // allocated storage duration + int* ptr_1 = malloc(sizeof(int)); // start allocated storage duration + printf("address of int in allocated memory = %p\n", (void*)ptr_1); + free(ptr_1); // stop allocated storage duration +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">&A = 0x600ae4 +&A = 0x7ffefb064f5c +address of int in allocated memory = 0x1f28c30</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 6.2.2 Linkages of identifiers (p: 35-36) </li> +<li> 6.2.4 Storage durations of objects (p: 36-37) </li> +<li> 6.7.1 Storage-class specifiers (p: 97-100) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.2.2 Linkages of identifiers (p: 29-30) </li> +<li> 6.2.4 Storage durations of objects (p: 30) </li> +<li> 6.7.1 Storage-class specifiers (p: 79) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.2.2 Linkages of identifiers (p: 36-37) </li> +<li> 6.2.4 Storage durations of objects (p: 38-39) </li> +<li> 6.7.1 Storage-class specifiers (p: 109-110) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 6.2.2 Linkages of identifiers (p: 30-31) </li> +<li> 6.2.4 Storage durations of objects (p: 32) </li> +<li> 6.7.1 Storage-class specifiers (p: 98-99) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 3.1.2.2 Linkages of identifiers </li> +<li> 3.1.2.4 Storage durations of objects </li> +<li> 3.5.1 Storage-class specifiers </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/storage_duration" title="cpp/language/storage duration">C++ documentation</a></span> for <span class=""><span>Storage class specifiers</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/storage_duration" class="_attribution-link">https://en.cppreference.com/w/c/language/storage_duration</a> + </p> +</div> diff --git a/devdocs/c/language%2Fstring_literal.html b/devdocs/c/language%2Fstring_literal.html new file mode 100644 index 00000000..39b28812 --- /dev/null +++ b/devdocs/c/language%2Fstring_literal.html @@ -0,0 +1,123 @@ + <h1 id="firstHeading" class="firstHeading">String literals</h1> <p>Constructs an unnamed object of specified character array type in-place, used when a character string needs to be embedded in source code.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>"</code> <span class="t-spar">s-char-sequence</span> <code>"</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>u8"</code> <span class="t-spar">s-char-sequence</span> <code>"</code> </td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>u"</code> <span class="t-spar">s-char-sequence</span> <code>"</code> </td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>U"</code> <span class="t-spar">s-char-sequence</span> <code>"</code> </td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>L"</code> <span class="t-spar">s-char-sequence</span> <code>"</code> </td> <td> (5) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>where</p> +<table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">s-char-sequence</span> </td> <td> - </td> <td> zero or more characters, each of which is either a multibyte character from the source character set (excluding (<code>"</code>), <code>\</code>, and newline), or character escape, hex escape, octal escape<span class="t-rev-inl t-since-c99"><span>, or universal character name</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> as defined in <a href="escape" title="c/language/escape">escape sequences</a>. </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> <i>character string literal</i>: The type of the literal is <code>char[N]</code>, where <code>N</code> is the size of the string in code units of the execution narrow encoding, including the null terminator. Each <code>char</code> element in the array is initialized from the next character in <span class="t-spar">s-char-sequence</span> using the execution character set.</div> <div class="t-li1"> +<span class="t-li">2)</span> <i>UTF-8 string literal</i>: The type of the literal is <span class="t-rev-inl t-until-c23"><span><code>char[N]</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>char8_t[N]</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, where <code>N</code> is the size of the string in UTF-8 code units including the null terminator. Each <span class="t-rev-inl t-until-c23"><span><code>char</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>char8_t</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> element in the array is initialized from the next multibyte character in <span class="t-spar">s-char-sequence</span> using UTF-8 encoding.</div> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <span class="t-li">3)</span> 16-bit wide string literal: The type of the literal is <code>char16_t[N]</code>, where <code>N</code> is the size of the string in code units of implementation-defined 16-bit encoding (typically UTF-16), including the null terminator. Each <code>char16_t</code> element in the array is initialized as if by executing <code><a href="../string/multibyte/mbrtoc16" title="c/string/multibyte/mbrtoc16">mbrtoc16</a></code> in implementation-defined locale. <span class="t-li">4)</span> 32-bit wide string literal: The type of the literal is <code>char32_t[N]</code>, where <code>N</code> is the size of the string in code units of implementation-defined 32-bit encoding (typically UTF-32), including the null terminator. Each <code>char32_t</code> element in the array is initialized as if by executing <code><a href="../string/multibyte/mbrtoc32" title="c/string/multibyte/mbrtoc32">mbrtoc32</a></code> in implementation-defined locale. </td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td> <span class="t-li">3)</span> <i>UTF-16 string literal</i>: The type of the literal is <code>char16_t[N]</code>, where <code>N</code> is the size of the string in UTF-16 code units including the null terminator. Each <code>char16_t</code> element in the array is initialized from the next multibyte character in <span class="t-spar">s-char-sequence</span> using UTF-16 encoding. <span class="t-li">4)</span> <i>UTF-32 string literal</i>: The type of the literal is <code>char32_t[N]</code>, where <code>N</code> is the size of the string in UTF-32 code units including the null terminator. Each <code>char32_t</code> element in the array is initialized from the next multibyte character in <span class="t-spar">s-char-sequence</span> using UTF-32 encoding. </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <div class="t-li1"> +<span class="t-li">5)</span> wide string literal: The type of the literal is <code>wchar_t[N]</code>, where <code>N</code> is the size of the string in code units of the execution wide encoding, including the null terminator. Each <code>wchar_t</code> element in the array is initialized as if by executing <code><a href="../string/multibyte/mbstowcs" title="c/string/multibyte/mbstowcs">mbstowcs</a></code> in implementation-defined locale.</div> <h3 id="Explanation"> Explanation</h3> <p>First, at <a href="translation_phases" title="c/language/translation phases">translation phase 6</a> (after macro expansion), the adjacent string literals (that is, string literals separated by whitespace only) are concatenated.</p> +<table class="t-rev-begin"> <tr class="t-rev t-until-c99"> +<td> <p>Only two narrow or two wide string literals may be concatenated.</p> +</td> <td><span class="t-mark-rev t-until-c99">(until C99)</span></td> +</tr> <tr class="t-rev t-since-c99"> +<td> <p>If one literal is unprefixed, the resulting string literal has the width/encoding specified by the prefixed literal.</p> +<div class="c source-c"><pre data-language="c">L"Δx = %" PRId16 // at phase 4, PRId16 expands to "d" + // at phase 6, L"Δx = %" and "d" form L"Δx = %d"</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <table class="t-rev-begin"> <tr class="t-rev t-since-c11 t-until-c23"> +<td> <p>If the two string literals have different encoding prefixes, concatenation is implementation-defined, except that a UTF-8 string literal and a wide string literal cannot be concatenated.</p> +</td> <td> +<span class="t-mark-rev t-since-c11">(since C11)</span><br><span class="t-mark-rev t-until-c23">(until C23)</span> +</td> +</tr> <tr class="t-rev t-since-c23"> +<td> <p>If the two string literals have different encoding prefixes, concatenation is ill-formed.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <p>Secondly, at <a href="translation_phases" title="c/language/translation phases">translation phase 7</a>, a terminating null character is added to each string literal, and then each literal initializes an unnamed array with static <a href="storage_duration" title="c/language/storage duration">storage duration</a> and length just enough to contain the contents of the string literal plus one for the null terminator.</p> +<div class="c source-c"><pre data-language="c">char* p = "\x12" "3"; // creates a static char[3] array holding {'\x12', '3', '\0'} + // sets p to point to the first element of the array</pre></div> <p>String literals are <b>not modifiable</b> (and in fact may be placed in read-only memory such as <code>.rodata</code>). If a program attempts to modify the static array formed by a string literal, the behavior is undefined.</p> +<div class="c source-c"><pre data-language="c">char* p = "Hello"; +p[1] = 'M'; // Undefined behavior +char a[] = "Hello"; +a[1] = 'M'; // OK: a is not a string literal</pre></div> <p>It is neither required nor forbidden for identical string literals to refer to the same location in memory. Moreover, overlapping string literals or string literals that are substrings of other string literals may be combined.</p> +<div class="c source-c"><pre data-language="c">"def" == 3+"abcdef"; // may be 1 or 0, implementation-defined</pre></div> <h3 id="Notes"> Notes</h3> <p>A string literal is not necessarily a string; if a string literal has embedded null characters, it represents an array which contains more than one string:</p> +<div class="c source-c"><pre data-language="c">char* p = "abc\0def"; // strlen(p) == 3, but the array has size 8</pre></div> <p>If a valid hex digit follows a hex escape in a string literal, it would fail to compile as an invalid escape sequence, but string concatenation can be used as a workaround:</p> +<div class="c source-c"><pre data-language="c">//char* p = "\xfff"; // error: hex escape sequence out of range +char* p = "\xff""f"; // okay, the literal is char[3] holding {'\xff', 'f', '\0'}</pre></div> <p>String literals can be used to <a href="array_initialization" title="c/language/array initialization">initialize arrays</a>, and if the size of the array is one less the size of the string literal, the null terminator is ignored:</p> +<div class="c source-c"><pre data-language="c">char a1[] = "abc"; // a1 is char[4] holding {'a', 'b', 'c', '\0'} +char a2[4] = "abc"; // a2 is char[4] holding {'a', 'b', 'c', '\0'} +char a3[3] = "abc"; // a3 is char[3] holding {'a', 'b', 'c'}</pre></div> <p>The encoding of character string literals <span class="t-v">(1)</span> and wide string literals <span class="t-v">(5)</span> is implementation-defined. For example, gcc selects them with the <a rel="nofollow" class="external text" href="https://gcc.gnu.org/onlinedocs/cpp/Invocation.html">commandline options</a> <code>-fexec-charset</code> and <code>-fwide-exec-charset</code>.</p> +<p>Although mixed wide string literal concatenation is allowed in C11, almost all compilers reject such concatenation (the only known exception is <a rel="nofollow" class="external text" href="http://sdcc.sourceforge.net/">SDCC</a>), and its usage experience is unknown. As a result, allowance of mixed wide string literal concatenation is removed in C23.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <inttypes.h> +#include <locale.h> +#include <stddef.h> +#include <stdio.h> +#include <stdlib.h> +#include <uchar.h> + +int main(void) +{ + char s1[] = "a猫🍌"; // or "a\u732B\U0001F34C" +#if __STDC_VERSION__ >= 202311L + char8_t +#else + char +#endif + s2[] = u8"a猫🍌"; + char16_t s3[] = u"a猫🍌"; + char32_t s4[] = U"a猫🍌"; + wchar_t s5[] = L"a猫🍌"; + + setlocale(LC_ALL, "en_US.utf8"); + printf(" \"%s\" is a char[%zu] holding { ", s1, sizeof s1 / sizeof *s1); + for(size_t n = 0; n < sizeof s1 / sizeof *s1; ++n) + printf("0x%02X ", +(unsigned char)s1[n]); + puts("}"); + printf( +#if __STDC_VERSION__ >= 202311L + "u8\"%s\" is a char8_t[%zu] holding { " +#else + "u8\"%s\" is a char[%zu] holding { " +#endif +, s2, sizeof s2 / sizeof *s2); + for(size_t n = 0; n < sizeof s2 / sizeof *s2; ++n) +#if __STDC_VERSION__ >= 202311L + printf("0x%02X ", s2[n]); +#else + printf("0x%02X ", +(unsigned char)s2[n]); +#endif + puts("}"); + printf(" u\"a猫🍌\" is a char16_t[%zu] holding { ", sizeof s3 / sizeof *s3); + for(size_t n = 0; n < sizeof s3 / sizeof *s3; ++n) + printf("0x%04" PRIXLEAST16" ", s3[n]); + puts("}"); + printf(" U\"a猫🍌\" is a char32_t[%zu] holding { ", sizeof s4 / sizeof *s4); + for(size_t n = 0; n < sizeof s4 / sizeof *s4; ++n) + printf("0x%08" PRIXLEAST32" ", s4[n]); + puts("}"); + printf(" L\"%ls\" is a wchar_t[%zu] holding { ", s5, sizeof s5 / sizeof *s5); + for(size_t n = 0; n < sizeof s5 / sizeof *s5; ++n) + printf("0x%08X ", (unsigned)s5[n]); + puts("}"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c"> + "a猫🍌" is a char[9] holding { 0x61 0xE7 0x8C 0xAB 0xF0 0x9F 0x8D 0x8C 0x00 } +u8"a猫🍌" is a char[9] holding { 0x61 0xE7 0x8C 0xAB 0xF0 0x9F 0x8D 0x8C 0x00 } + u"a猫🍌" is a char16_t[5] holding { 0x0061 0x732B 0xD83C 0xDF4C 0x0000 } + U"a猫🍌" is a char32_t[4] holding { 0x00000061 0x0000732B 0x0001F34C 0x00000000 } + L"a猫🍌" is a wchar_t[4] holding { 0x00000061 0x0000732B 0x0001F34C 0x00000000 }</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.4.5 String literals (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.4.5 String literals (p: 50-52) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.4.5 String literals (p: 70-72) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.4.5 String literals (p: 62-63) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.1.4 String literals </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/string_literal" title="cpp/language/string literal">C++ documentation</a></span> for <span class=""><span>string literal</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/string_literal" class="_attribution-link">https://en.cppreference.com/w/c/language/string_literal</a> + </p> +</div> diff --git a/devdocs/c/language%2Fstruct.html b/devdocs/c/language%2Fstruct.html new file mode 100644 index 00000000..3e59cdb5 --- /dev/null +++ b/devdocs/c/language%2Fstruct.html @@ -0,0 +1,163 @@ + <h1 id="firstHeading" class="firstHeading">Struct declaration</h1> <p>A struct is a type consisting of a sequence of members whose storage is allocated in an ordered sequence (as opposed to union, which is a type consisting of a sequence of members whose storage overlaps).</p> +<p>The <a href="declarations" title="c/language/declarations">type specifier</a> for a struct is identical to the <a href="union" title="c/language/union"><code>union</code></a> type specifier except for the keyword used:</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>struct</code> <span class="t-spar">attr-spec-seq</span> <span class="t-mark">(optional)</span> <span class="t-spar">name</span> <span class="t-mark">(optional)</span> <code>{</code> <span class="t-spar">struct-declaration-list</span> <code>}</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>struct</code> <span class="t-spar">attr-spec-seq</span> <span class="t-mark">(optional)</span> <span class="t-spar">name</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> Struct definition: introduces the new type struct <span class="t-spar">name</span> and defines its meaning</div> <div class="t-li1"> +<span class="t-li">2)</span> If used on a line of its own, as in <code>struct</code> <span class="t-spar">name</span> <code>;</code>, <i>declares</i> but doesn't define the struct <code>name</code> (see forward declaration below). In other contexts, names the previously-declared struct, and <span class="t-spar">attr-spec-seq</span> is not allowed.</div> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">name</span> </td> <td> - </td> <td> the name of the struct that's being defined </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">struct-declaration-list</span> </td> <td> - </td> <td> any number of variable declarations, <a href="bit_field" title="c/language/bit field">bit-field</a> declarations, and <a href="static_assert" title="c/language/static assert" class="mw-redirect">static assert</a> declarations. Members of incomplete type and members of function type are not allowed (except for the flexible array member described below) </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">attr-spec-seq</span> </td> <td> - </td> <td> <span class="t-mark-rev t-since-c23">(C23)</span>optional list of <a href="attributes" title="c/language/attributes">attributes</a>, applied to the struct type </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>Within a struct object, addresses of its elements (and the addresses of the bit-field allocation units) increase in order in which the members were defined. A pointer to a struct can be cast to a pointer to its first member (or, if the member is a bit-field, to its allocation unit). Likewise, a pointer to the first member of a struct can be cast to a pointer to the enclosing struct. There may be unnamed padding between any two members of a struct or after the last member, but not before the first member. The size of a struct is at least as large as the sum of the sizes of its members.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>If a struct defines at least one named member, it is allowed to additionally declare its last member with incomplete array type. When an element of the flexible array member is accessed (in an expression that uses operator <code>.</code> or <code>-></code> with the flexible array member's name as the right-hand-side operand), then the struct behaves as if the array member had the longest size fitting in the memory allocated for this object. If no additional storage was allocated, it behaves as if an array with 1 element, except that the behavior is undefined if that element is accessed or a pointer one past that element is produced. Initialization and the assignment operator ignore the flexible array member. <code>sizeof</code> omits it, but may have more trailing padding than the omission would imply. Structures with flexible array members (or unions who have a recursive-possibly structure member with flexible array member) cannot appear as array elements or as members of other structures.</p> +<div class="c source-c"><pre data-language="c">struct s { int n; double d[]; }; // s.d is a flexible array member + +struct s t1 = { 0 }; // OK, d is as if double d[1], but UB to access +struct s t2 = { 1, { 4.2 } }; // error: initialization ignores flexible array + +// if sizeof (double) == 8 +struct s *s1 = malloc(sizeof (struct s) + 64); // as if d was double d[8] +struct s *s2 = malloc(sizeof (struct s) + 40); // as if d was double d[5] + +s1 = malloc(sizeof (struct s) + 10); // now as if d was double d[1]. Two bytes excess. +double *dp = &(s1->d[0]); // OK +*dp = 42; // OK +s1->d[1]++; // Undefined behavior. 2 excess bytes can't be accessed + // as double. + +s2 = malloc(sizeof (struct s) + 6); // same, but UB to access because 2 bytes are + // missing to complete 1 double +dp = &(s2->d[0]); // OK, can take address just fine +*dp = 42; // undefined behavior + +*s1 = *s2; // only copies s.n, not any element of s.d + // except those caught in sizeof (struct s)</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <p>Similar to union, an unnamed member of a struct whose type is a struct without <span class="t-spar">name</span> is known as <i>anonymous struct</i>. Every member of an anonymous struct is considered to be a member of the enclosing struct or union, keeping their structure layout. This applies recursively if the enclosing struct or union is also anonymous.</p> +<div class="c source-c"><pre data-language="c">struct v +{ + union // anonymous union + { + struct { int i, j; }; // anonymous structure + struct { long k, l; } w; + }; + int m; +} v1; + +v1.i = 2; // valid +v1.k = 3; // invalid: inner structure is not anonymous +v1.w.k = 5; // valid</pre></div> <p>Similar to union, the behavior of the program is undefined if struct is defined without any named members (including those obtained via anonymous nested structs or unions).</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <h3 id="Forward_declaration"> Forward declaration</h3> <p>A declaration of the following form</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <code>struct</code> <span class="t-spar">attr-spec-seq</span> <span class="t-mark">(optional)</span> <span class="t-spar">name</span> <code>;</code> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>hides any previously declared meaning for the name <span class="t-spar">name</span> in the tag name space and declares <span class="t-spar">name</span> as a new struct name in current scope, which will be defined later. Until the definition appears, this struct name has <a href="type#Incomplete_types" title="c/language/type">incomplete type</a>.</p> +<p>This allows structs that refer to each other:</p> +<div class="c source-c"><pre data-language="c">struct y; +struct x { struct y *p; /* ... */ }; +struct y { struct x *q; /* ... */ };</pre></div> <p>Note that a new struct name may also be introduced just by using a struct tag within another declaration, but if a previously declared struct with the same name exists in the tag <a href="name_space" title="c/language/name space">name space</a>, the tag would refer to that name</p> +<div class="c source-c"><pre data-language="c">struct s* p = NULL; // tag naming an unknown struct declares it +struct s { int a; }; // definition for the struct pointed to by p +void g(void) +{ + struct s; // forward declaration of a new, local struct s + // this hides global struct s until the end of this block + struct s *p; // pointer to local struct s + // without the forward declaration above, + // this would point at the file-scope s + struct s { char* p; }; // definitions of the local struct s +}</pre></div> <h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/struct" title="c/keyword/struct"><code>struct</code></a></p> +<h3 id="Notes"> Notes</h3> <p>See <a href="struct_initialization" title="c/language/struct initialization">struct initialization</a> for the rules regarding the initializers for structs.</p> +<p>Because members of incomplete type are not allowed, and a struct type is not complete until the end of the definition, a struct cannot have a member of its own type. A pointer to its own type is allowed, and is commonly used to implement nodes in linked lists or trees.</p> +<p>Because a struct declaration does not establish <a href="scope" title="c/language/scope">scope</a>, nested types, enumerations and enumerators introduced by declarations within <span class="t-spar">struct-declaration-list</span> are visible in the surrounding scope where the struct is defined.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stddef.h> +#include <stdio.h> + +int main(void) +{ + // Declare the struct type. + struct car + { + char* make; + int year; + }; + // Declare and initialize an object of a previously-declared struct type. + struct car c = {.year = 1923, .make = "Nash"}; + printf("1) Car: %d %s\n", c.year, c.make); + + // Declare a struct type, an object of that type, and a pointer to it. + struct spaceship + { + char* model; + int max_speed; + } ship = {"T-65 X-wing starfighter", 1050}, + *pship = &ship; + printf("2) Spaceship: %s. Max speed: %d km/h\n\n", ship.model, ship.max_speed); + + // Address increase in order of definition. Padding may be inserted. + struct A { char a; double b; char c; }; + printf( + "3) Offset of char a = %zu\n" + "4) Offset of double b = %zu\n" + "5) Offset of char c = %zu\n" + "6) Size of struct A = %zu\n\n", + offsetof(struct A, a), + offsetof(struct A, b), + offsetof(struct A, c), + sizeof(struct A) + ); + struct B { char a; char b; double c; }; + printf( + "7) Offset of char a = %zu\n" + "8) Offset of char b = %zu\n" + "9) Offset of double c = %zu\n" + "A) Size of struct B = %zu\n\n", + offsetof(struct B, a), + offsetof(struct B, b), + offsetof(struct B, c), + sizeof(struct B) + ); + + // A pointer to a struct can be cast to a pointer + // to its first member and vice versa. + char** pmodel = (char **)pship; + printf("B) %s\n", *pmodel); + pship = (struct spaceship *)pmodel; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">1) Car: 1923 Nash +2) Spaceship: T-65 X-wing starfighter. Max speed: 1050 km/h + +3) Offset of char a = 0 +4) Offset of double b = 8 +5) Offset of char c = 16 +6) Size of struct A = 24 + +7) Offset of char a = 0 +8) Offset of char b = 1 +9) Offset of double c = 8 +A) Size of struct B = 16 + +B) T-65 X-wing starfighter</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.7.2.1 Structure and union specifiers (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.7.2.1 Structure and union specifiers (p: 81-84) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.7.2.1 Structure and union specifiers (p: 112-117) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.7.2.1 Structure and union specifiers (p: 101-104) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.5.2.1 Structure and union specifiers </li></ul> +</ul> <h3 id="See_also"> See also</h3> <ul> +<li> <a href="operator_member_access" title="c/language/operator member access">struct and union member access</a> </li> +<li> <a href="bit_field" title="c/language/bit field">bit-field</a> </li> +<li> <a href="struct_initialization" title="c/language/struct initialization">struct initialization</a> </li> +</ul> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/class" title="cpp/language/class">C++ documentation</a></span> for <span class=""><span>Class declaration</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/struct" class="_attribution-link">https://en.cppreference.com/w/c/language/struct</a> + </p> +</div> diff --git a/devdocs/c/language%2Fstruct_initialization.html b/devdocs/c/language%2Fstruct_initialization.html new file mode 100644 index 00000000..f97f90ae --- /dev/null +++ b/devdocs/c/language%2Fstruct_initialization.html @@ -0,0 +1,125 @@ + <h1 id="firstHeading" class="firstHeading">Struct and union initialization</h1> <p>When <a href="initialization" title="c/language/initialization">initializing</a> an object of <a href="struct" title="c/language/struct">struct</a> or <a href="union" title="c/language/union">union</a> type, the initializer must be a <span class="t-rev-inl t-until-c23"><span>non-empty,</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span> brace-enclosed, comma-separated list of initializers for the members:</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>=</code> <code>{</code> <span class="t-spar">expression</span> <code>,</code> <code>...</code> <code>}</code> </td> <td> (1) </td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>=</code> <code>{</code> <span class="t-spar">designator</span><span class="t-mark">(optional)</span> <span class="t-spar">expression</span> <code>,</code> <code>...</code> <code>}</code> </td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>=</code> <code>{</code> <code>}</code> </td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <p>where the <span class="t-spar">designator</span> is a sequence (whitespace-separated or adjacent) of individual member designators of the form <code>.</code> <span class="t-spar">member</span> and <a href="array_initialization" title="c/language/array initialization">array designators</a> of the form <code>[</code> <span class="t-spar">index</span> <code>]</code>.</p> +<p>All members that are not initialized explicitly are <a href="initialization#Empty_initialization" title="c/language/initialization">empty-initialized</a>.</p> +<h3 id="Explanation"> Explanation</h3> <p>When initializing a <a href="union" title="c/language/union">union</a>, the initializer list must have only one member, which initializes the first member of the union<span class="t-rev-inl t-since-c99"><span> unless a designated initializer is used</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>.</p> +<div class="c source-c"><pre data-language="c">union { int x; char c[4]; } + u = {1}, // makes u.x active with value 1 + u2 = { .c={'\1'} }; // makes u2.c active with value {'\1','\0','\0','\0'}</pre></div> <p>When initializing a <a href="struct" title="c/language/struct">struct</a>, the first initializer in the list initializes the first declared member<span class="t-rev-inl t-since-c99"><span> (unless a designator is specified)</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>, and all subsequent initializers <span class="t-rev-inl t-since-c99"><span>without designators </span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>initialize the struct members declared after the one initialized by the previous expression.</p> +<div class="c source-c"><pre data-language="c">struct point {double x,y,z;} p = {1.2, 1.3}; // p.x=1.2, p.y=1.3, p.z=0.0 +div_t answer = {.quot = 2, .rem = -1 }; // order of elements in div_t may vary</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>A designator causes the following initializer to initialize the struct member described by the designator. Initialization then continues forward in order of declaration, beginning with the next element declared after the one described by the designator.</p> +<div class="c source-c"><pre data-language="c">struct {int sec,min,hour,day,mon,year;} z + = {.day=31,12,2014,.sec=30,15,17}; // initializes z to {30,15,17,31,12,2014}</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <p>It's an error to provide more initializers than members.</p> +<h3 id="Nested_initialization"> Nested initialization</h3> <p>If the members of the struct or union are arrays, structs, or unions, the corresponding initializers in the brace-enclosed list of initializers are any initializers that are valid for those members, except that their braces may be omitted as follows:</p> +<p>If the nested initializer begins with an opening brace, the entire nested initializer up to its closing brace initializes the corresponding member object. Each left opening brace establishes a new <i>current object</i>. The members of the current object are initialized in their natural order<span class="t-rev-inl t-since-c99"><span>, unless designators are used</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>: array elements in subscript order, struct members in declaration order, only the first declared member of any union. The subobjects within the current object that are not explicitly initialized by the closing brace are <a href="initialization#Empty_initialization" title="c/language/initialization">empty-initialized</a>.</p> +<div class="c source-c"><pre data-language="c">struct example { + struct addr_t { + uint32_t port; + } addr; + union { + uint8_t a8[4]; + uint16_t a16[2]; + } in_u; +}; +struct example ex = { // start of initializer list for struct example + { // start of initializer list for ex.addr + 80 // initialized struct's only member + }, // end of initializer list for ex.addr + { // start of initializer-list for ex.in_u + {127,0,0,1} // initializes first element of the union + } };</pre></div> <p>If the nested initializer does not begin with an opening brace, only enough initializers from the list are taken to account for the elements or members of the member array, struct or union; any remaining initializers are left to initialize the next struct member:</p> +<div class="c source-c"><pre data-language="c">struct example ex = {80, 127, 0, 0, 1}; // 80 initializes ex.addr.port + // 127 initializes ex.in_u.a8[0] + // 0 initializes ex.in_u.a8[1] + // 0 initializes ex.in_u.a8[2] + // 1 initializes ex.in_u.a8[3]</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>When designators are nested, the designators for the members follow the designators for the enclosing structs/unions/arrays. Within any nested bracketed initializer list, the outermost designator refers to the <i>current object</i> and selects the subobject to be initialized within the <i>current object</i> only.</p> +<div class="c source-c"><pre data-language="c">struct example ex2 = { // current object is ex2, designators are for members of example + .in_u.a8[0]=127, 0, 0, 1, .addr=80}; +struct example ex3 = {80, .in_u={ // changes current object to the union ex.in_u + 127, + .a8[2]=1 // this designator refers to the member of in_u + } };</pre></div> <p>If any subobject is explicitly initialized twice (which may happen when designators are used), the initializer that appears later in the list is the one used (the earlier initializer may not be evaluated):</p> +<div class="c source-c"><pre data-language="c">struct {int n;} s = {printf("a\n"), // this may be printed or skipped + .n=printf("b\n")}; // always printed</pre></div> <p>Although any non-initialized subobjects are initialized implicitly, implicit initialization of a subobject never overrides explicit initialization of the same subobject if it appeared earlier in the initializer list (choose clang to observe the correct output):</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> +typedef struct { int k; int l; int a[2]; } T; +typedef struct { int i; T t; } S; +T x = {.l = 43, .k = 42, .a[1] = 19, .a[0] = 18 }; + // x initialized to {42, 43, {18, 19} } +int main(void) +{ + S l = { 1, // initializes l.i to 1 + .t = x, // initializes l.t to {42, 43, {18, 19} } + .t.l = 41, // changes l.t to {42, 41, {18, 19} } + .t.a[1] = 17 // changes l.t to {42, 41, {18, 17} } + }; + printf("l.t.k is %d\n", l.t.k); // .t = x sets l.t.k to 42 explicitly + // .t.l = 41 would zero out l.t.k implicitly +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">l.t.k is 42</pre></div> <p>However, when an initializer begins with a left open brace, its <i>current object</i> is fully re-initialized and any prior explicit initializers for any of its subobjects are ignored:</p> +<div class="c source-c"><pre data-language="c">struct fred { char s[4]; int n; }; +struct fred x[ ] = { { { "abc" }, 1 }, // inits x[0] to { {'a','b','c','\0'}, 1 } + [0].s[0] = 'q' // changes x[0] to { {'q','b','c','\0'}, 1 } + }; +struct fred y[ ] = { { { "abc" }, 1 }, // inits y[0] to { {'a','b','c','\0'}, 1 } + [0] = { // current object is now the entire y[0] object + .s[0] = 'q' + } // replaces y[0] with { {'q','\0','\0','\0'}, 0 } + };</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>The initializer list may have a trailing comma, which is ignored.</p> +<div class="c source-c"><pre data-language="c">struct {double x,y;} p = {1.0, + 2.0, // trailing comma OK + };</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>In C, the braced list of initializers cannot be empty (note that C++ allows empty lists, and also note that a <a href="struct" title="c/language/struct">struct</a> in C cannot be empty):</p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td> <p>The initializer list can be empty in C as in C++:</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <div class="c source-c"><pre data-language="c">struct {int n;} s = {0}; // OK +struct {int n;} s = {}; // Error until C23: initializer-list cannot be empty + // OK since C23: s.n is initialized to 0 +struct {} s = {}; // Error: struct cannot be empty</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-until-c99"> +<td> <p>Every expression in the initializer list must be a <a href="constant_expression" title="c/language/constant expression">constant expression</a> when initializing aggregates of any storage duration.</p> +</td> <td><span class="t-mark-rev t-until-c99">(until C99)</span></td> +</tr> <tr class="t-rev t-since-c99"> +<td> <p>As with all other <a href="initialization" title="c/language/initialization">initialization</a>, every expression in the initializer list must be a <a href="constant_expression" title="c/language/constant expression">constant expression</a> when initializing aggregates of static<span class="t-rev-inl t-since-c11"><span> or thread-local</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> <a href="storage_duration" title="c/language/storage duration">storage duration</a>:</p> +<div class="c source-c"><pre data-language="c">static struct {char* p} s = {malloc(1)}; // error</pre></div> <p>The <a href="eval_order" title="c/language/eval order">order of evaluation</a> of the subexpressions in any initializer is indeterminately sequenced (but not in C++ since C++11):</p> +<div class="c source-c"><pre data-language="c">int n = 1; +struct {int x,y;} p = {n++, n++}; // unspecified, but well-defined behavior: + // n is incremented twice in arbitrary order + // p equal {1,2} and {2,1} are both valid</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <time.h> + +int main(void) +{ + char buff[70]; + // designated initializers simplify the use of structs whose + // order of members is unspecified + struct tm my_time = { .tm_year=2012-1900, .tm_mon=9, .tm_mday=9, + .tm_hour=8, .tm_min=10, .tm_sec=20 }; + strftime(buff, sizeof buff, "%A %c", &my_time); + puts(buff); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Sunday Sun Oct 9 08:10:20 2012</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.7.9/12-39 Initialization (p: 101-105) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.7.9/12-38 Initialization (p: 140-144) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.7.8/12-38 Initialization (p: 126-130) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 6.5.7 Initialization </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/aggregate_initialization" title="cpp/language/aggregate initialization">C++ documentation</a></span> for <span class=""><span>Aggregate initialization</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/struct_initialization" class="_attribution-link">https://en.cppreference.com/w/c/language/struct_initialization</a> + </p> +</div> diff --git a/devdocs/c/language%2Fswitch.html b/devdocs/c/language%2Fswitch.html new file mode 100644 index 00000000..83c773e6 --- /dev/null +++ b/devdocs/c/language%2Fswitch.html @@ -0,0 +1,88 @@ + <h1 id="firstHeading" class="firstHeading">switch statement</h1> <p>Executes code according to the value of an integral argument.</p> +<p>Used where one or several out of many branches of code need to be executed according to an integral value.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span> <code>switch (</code> <span class="t-spar">expression</span> <code>)</code> <span class="t-spar">statement</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">attr-spec-seq</span> </td> <td> - </td> <td> <span class="t-mark-rev t-since-c23">(C23)</span>optional list of <a href="attributes" title="c/language/attributes">attributes</a>, applied to the <code>switch</code> statement </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">expression</span> </td> <td> - </td> <td> any <a href="expressions" title="c/language/expressions">expression</a> of <a href="type#Type_groups" title="c/language/type">integer type</a> (char, signed or unsigned integer, or enumeration) </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">statement</span> </td> <td> - </td> <td> any <a href="statements" title="c/language/statements">statement</a> (typically a compound statement). <code>case:</code> and <code>default:</code> labels are permitted in <span class="t-spar">statement</span>, and <code>break;</code> statement has special meaning. </td> +</tr> +</table> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>case</code> <span class="t-spar">constant-expression</span> <code>:</code> <span class="t-spar">statement</span> </td> <td> (1) </td> <td> <span class="t-mark-rev t-until-c23">(until C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span> <code>case</code> <span class="t-spar">constant-expression</span> <code>:</code> <span class="t-spar">statement</span><span class="t-mark">(optional)</span> </td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>default</code> <code>:</code> <span class="t-spar">statement</span> </td> <td> (2) </td> <td> <span class="t-mark-rev t-until-c23">(until C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span> <code>default</code> <code>:</code> <span class="t-spar">statement</span><span class="t-mark">(optional)</span> </td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">constant-expression</span> </td> <td> - </td> <td> any integer <a href="constant_expression" title="c/language/constant expression">constant expression</a> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">attr-spec-seq</span> </td> <td> - </td> <td> <span class="t-mark-rev t-since-c23">(C23)</span>optional list of <a href="attributes" title="c/language/attributes">attributes</a>, applied to the label </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>The body of a switch statement may have an arbitrary number of <code>case:</code> labels, as long as the values of all <span class="t-spar">constant-expressions</span> are unique (after <a href="conversion" title="c/language/conversion">conversion</a> to the <a href="conversion#Integer_promotions" title="c/language/conversion">promoted type</a> of <span class="t-spar">expression</span>). At most one <code>default:</code> label may be present (although nested switch statements may use their own <code>default:</code> labels or have <code>case:</code> labels whose constants are identical to the ones used in the enclosing switch).</p> +<p>If <span class="t-spar">expression</span> evaluates to the value that is equal to the value of one of <span class="t-spar">constant-expression</span>s after conversion to the promoted type of <span class="t-spar">expression</span>, then control is transferred to the statement that is labeled with that <span class="t-spar">constant-expression</span>.</p> +<p>If <span class="t-spar">expression</span> evaluates to a value that doesn't match any of the <code>case:</code> labels, and the <code>default:</code> label is present, control is transferred to the statement labeled with the <code>default:</code> label.</p> +<p>If <span class="t-spar">expression</span> evaluates to a value that doesn't match any of the <code>case:</code> labels, and the <code>default:</code> label is not present, none of the switch body is executed.</p> +<p>The <a href="break" title="c/language/break">break</a> statement, when encountered anywhere in <span class="t-spar">statement</span>, exits the switch statement:</p> +<div class="c source-c"><pre data-language="c">switch(1) { + case 1 : puts("1"); // prints "1", + case 2 : puts("2"); // then prints "2" ("fall-through") +}</pre></div> <div class="c source-c"><pre data-language="c">switch(1) { + case 1 : puts("1"); // prints "1" + break; // and exits the switch + case 2 : puts("2"); + break; +}</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>As with all other selection and iteration statements, the switch statement establishes <a href="scope" title="c/language/scope">block scope</a>: any identifier introduced in the <span class="t-spar">expression</span> goes out of scope after the <span class="t-spar">statement</span>.</p> +<p>If a VLA or another identifier with variably-modified type has a <code>case:</code> or a <code>default:</code> label within its scope, the entire switch statement must be in its scope (in other words, a VLA must be declared either before the entire switch or after the last label):</p> +<div class="c source-c"><pre data-language="c">switch (expr) +{ + int i = 4; // not a VLA; OK to declare here + f(i); // never called +// int a[i]; // error: VLA cannot be declared here + case 0: + i = 17; + default: + int a[i]; // OK to declare VLA here + printf("%d\n", i); // prints 17 if expr == 0, prints indeterminate value otherwise +}</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/switch" title="c/keyword/switch"><code>switch</code></a>, <a href="../keyword/case" title="c/keyword/case"><code>case</code></a>, <a href="../keyword/default" title="c/keyword/default"><code>default</code></a></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +void func(int x) +{ + printf("func(%d): ", x); + switch(x) + { + case 1: printf("case 1, "); + case 2: printf("case 2, "); + case 3: printf("case 3.\n"); break; + case 4: printf("case 4, "); + case 5: + case 6: printf("case 5 or case 6, "); + default: printf("default.\n"); + } +} + +int main(void) +{ + for(int i = 1; i < 9; ++i) func(i); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">func(1): case 1, case 2, case 3. +func(2): case 2, case 3. +func(3): case 3. +func(4): case 4, case 5 or case 6, default. +func(5): case 5 or case 6, default. +func(6): case 5 or case 6, default. +func(7): default. +func(8): default.</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.8.4.2 The switch statement (p: 108-109) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.8.4.2 The switch statement (p: 149-150) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.8.4.2 The switch statement (p: 134-135) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.6.4.2 The switch statement </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/switch" title="cpp/language/switch">C++ documentation</a></span> for <span class=""><span><code>switch</code> statement</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/switch" class="_attribution-link">https://en.cppreference.com/w/c/language/switch</a> + </p> +</div> diff --git a/devdocs/c/language%2Fthread_storage_duration.html b/devdocs/c/language%2Fthread_storage_duration.html new file mode 100644 index 00000000..8f92d562 --- /dev/null +++ b/devdocs/c/language%2Fthread_storage_duration.html @@ -0,0 +1,14 @@ + <h1 id="firstHeading" class="firstHeading">Thread storage duration</h1> <p>An object whose identifier is declared with the storage-class specifier <code>_Thread_local</code> <span class="t-mark-rev t-since-c11">(since C11)</span> has thread storage duration. Its lifetime is the entire execution of the thread for which it is created, and its stored value is initialized when the thread is started. There is a distinct object per thread, and use of the declared name in an expression refers to the object associated with the thread evaluating the expression. The result of attempting to indirectly access an object with thread storage duration from a thread other than the one with which the object is associated is implementation-defined.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">const double PI = 3.14159; /* const variable is global to all threads */ +_Thread_local unsigned int seed; /* seed is a thread-specific variable */ + +int main(void) +{ + return 0; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">(none)</pre></div> </div> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/thread_storage_duration" class="_attribution-link">https://en.cppreference.com/w/c/language/thread_storage_duration</a> + </p> +</div> diff --git a/devdocs/c/language%2Ftranslation_phases.html b/devdocs/c/language%2Ftranslation_phases.html new file mode 100644 index 00000000..2f629e71 --- /dev/null +++ b/devdocs/c/language%2Ftranslation_phases.html @@ -0,0 +1,105 @@ + <h1 id="firstHeading" class="firstHeading">Phases of translation</h1> <p>The C source file is processed by the compiler <i>as if</i> the following phases take place, in this exact order. Actual implementation may combine these actions or process them differently as long as the behavior is the same.</p> +<h3 id="Phase_1"> Phase 1</h3> <div class="t-li1"> +<span class="t-li">1)</span> The individual bytes of the source code file (which is generally a text file in some multibyte encoding such as UTF-8) are mapped, in implementation defined manner, to the characters of the <i>source character set</i>. In particular, OS-dependent end-of-line indicators are replaced by newline characters. The <i>source character set</i> is a multibyte character set which includes the <i>basic source character set</i> as a single-byte subset, consisting of the following 96 characters:</div> <div class="t-li2"> +<span class="t-li">a)</span> 5 whitespace characters (space, horizontal tab, vertical tab, form feed, new-line)</div> <div class="t-li2"> +<span class="t-li">b)</span> 10 digit characters from <code>'0'</code> to <code>'9'</code> +</div> <div class="t-li2"> +<span class="t-li">c)</span> 52 letters from <code>'a'</code> to <code>'z'</code> and from <code>'A'</code> to <code>'Z'</code> +</div> <div class="t-li2"> +<span class="t-li">d)</span> 29 punctuation characters: <code>_ { } [ ] # ( ) < > % : ; . ? * + - / ^ & | ~ ! = , \ " '</code> +</div> <div class="t-li1"> +<span class="t-li">2)</span> <span class="t-rev-inl t-until-c23"><span><a href="operator_alternative" title="c/language/operator alternative">Trigraph sequences</a> are replaced by corresponding single-character representations.</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span> +</div> <h3 id="Phase_2"> Phase 2</h3> <div class="t-li1"> +<span class="t-li">1)</span> Whenever backslash appears at the end of a line (immediately followed by the newline character), both backslash and newline are deleted, combining two physical source lines into one logical source line. This is a single-pass operation: a line ending in two backslashes followed by an empty line does not combine three lines into one. <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +#define PUTS p\ +u\ +t\ +s +/* Line splicing is in phase 2 while macros + * are tokenized in phase 3 and expanded in phase 4, + * so the above is equivalent to #define PUTS puts + */ + +int main(void) +{ + /* Use line splicing to call puts */ PUT\ +S\ +("Output ends here\\ +0Not printed" /* After line splicing, the remaining backslash + * escapes the 0, ending the string early. + */ +); +}</pre></div> </div> +</div> <div class="t-li1"> +<span class="t-li">2)</span> If a non-empty source file does not end with a newline character after this step (whether it had no newline originally, or it ended with a backslash), the behavior is undefined.</div> <h3 id="Phase_3"> Phase 3</h3> <div class="t-li1"> +<span class="t-li">1)</span> The source file is decomposed into <a href="../comment" title="c/comment">comment</a>, sequences of whitespace characters (space, horizontal tab, new-line, vertical tab, and form-feed), and <i>preprocessing tokens</i>, which are the following</div> <div class="t-li2"> +<span class="t-li">a)</span> header names: <code><stdio.h></code> or <code>"myfile.h"</code> +</div> <div class="t-li2"> +<span class="t-li">b)</span> <a href="identifier" title="c/language/identifier">identifiers</a> +</div> <div class="t-li2"> +<span class="t-li">c)</span> preprocessing numbers, which cover <a href="integer_constant" title="c/language/integer constant">integer constants</a> and <a href="floating_constant" title="c/language/floating constant">floating constants</a>, but also cover some invalid tokens such as <code>1..E+3.foo</code> or <code>0JBK</code> +</div> <div class="t-li2"> +<span class="t-li">d)</span> <a href="character_constant" title="c/language/character constant">character constants</a> and <a href="string_literal" title="c/language/string literal">string literals</a> +</div> <div class="t-li2"> +<span class="t-li">e)</span> operators and punctuators, such as <code>+</code>, <code><<=</code>, <code><%</code>, or <code>##</code>.</div> <div class="t-li2"> +<span class="t-li">f)</span> individual non-whitespace characters that do not fit in any other category</div> <div class="t-li1"> +<span class="t-li">2)</span> Each comment is replaced by one space character</div> <div class="t-li1"> +<span class="t-li">3)</span> Newlines are kept, and it's implementation-defined whether non-newline whitespace sequences may be collapsed into single space characters.</div> <p> If the input has been parsed into preprocessing tokens up to a given character, the next preprocessing token is generally taken to be the longest sequence of characters that could constitute a preprocessing token, even if that would cause subsequent analysis to fail. This is commonly known as <i>maximal munch</i>.</p> +<div class="c source-c"><pre data-language="c">int foo = 1; +// int bar = 0xE+foo; // error: invalid preprocessing number 0xE+foo +int bar = 0xE/*Comment expands to a space*/+foo; // OK: 0xE + foo +int baz = 0xE + foo; // OK: 0xE + foo +int pub = bar+++baz; // OK: bar++ + baz +int ham = bar++-++baz; // OK: bar++ - ++baz +// int qux = bar+++++baz; // error: bar++ ++ +baz, not bar++ + ++baz +int qux = bar+++/*Saving comment*/++baz; // OK: bar++ + ++baz</pre></div> <p>The sole exception to the maximal munch rule is:</p> +<ul><li> Header name preprocessing tokens are only formed within a <a href="../preprocessor/include" title="c/preprocessor/include"><code> #include</code></a> <span class="t-rev-inl t-since-c23"><span>or <a href="../preprocessor/embed" title="c/preprocessor/embed"><code> #embed</code></a></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> directive, <span class="t-rev-inl t-since-c23"><span>in <a href="../preprocessor/include" title="c/preprocessor/include"><code>__has_include</code></a> and <a href="../preprocessor/embed" title="c/preprocessor/embed"><code>__has_embed</code></a> expressions</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> and in implementation-defined locations within a <a href="../preprocessor/impl" title="c/preprocessor/impl"><code> #pragma</code></a> directive. </li></ul> <div class="c source-c"><pre data-language="c">#define MACRO_1 1 +#define MACRO_2 2 +#define MACRO_3 3 +#define MACRO_EXPR (MACRO_1 <MACRO_2> MACRO_3) // OK: <MACRO_2> is not a header-name</pre></div> <h3 id="Phase_4"> Phase 4</h3> <div class="t-li1"> +<span class="t-li">1)</span> <a href="../preprocessor" title="c/preprocessor">Preprocessor</a> is executed.</div> <div class="t-li1"> +<span class="t-li">2)</span> Each file introduced with the <a href="../preprocessor/include" title="c/preprocessor/include">#include</a> directive goes through phases 1 through 4, recursively.</div> <div class="t-li1"> +<span class="t-li">3)</span> At the end of this phase, all preprocessor directives are removed from the source.</div> <h3 id="Phase_5"> Phase 5</h3> <div class="t-li1"> +<span class="t-li">1)</span> All characters and <a href="escape" title="c/language/escape">escape sequences</a> in <a href="character_constant" title="c/language/character constant">character constants</a> and <a href="string_literal" title="c/language/string literal">string literals</a> are converted from <i>source character set</i> to <i>execution character set</i> (which may be a multibyte character set such as UTF-8, as long as all 96 characters from the <i>basic source character set</i> listed in phase 1 have single-byte representations). If the character specified by an escape sequence isn't a member of the execution character set, the result is implementation-defined, but is guaranteed to not be a null (wide) character.</div> <p>Note: the conversion performed at this stage can be controlled by command line options in some implementations: gcc and clang use <code>-finput-charset</code> to specify the encoding of the source character set, <code>-fexec-charset</code> and <code>-fwide-exec-charset</code> to specify the encodings of the execution character set in the string literals and character constants <span class="t-rev-inl t-since-c11"><span>that don't have an encoding prefix</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span>.</p> +<h3 id="Phase_6"> Phase 6</h3> <p>Adjacent <a href="string_literal" title="c/language/string literal">string literals</a> are concatenated.</p> +<h3 id="Phase_7"> Phase 7</h3> <p>Compilation takes place: the tokens are syntactically and semantically analyzed and translated as a translation unit.</p> +<h3 id="Phase_8"> Phase 8</h3> <p>Linking takes place: Translation units and library components needed to satisfy external references are collected into a program image which contains information needed for execution in its execution environment (the OS).</p> +<h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 5.1.1.2 Translation phases (p: TBD) </li> +<li> 5.2.1 Character sets (p: TBD) </li> +<li> 6.4 Lexical elements (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 5.1.1.2 Translation phases (p: 9-10) </li> +<li> 5.2.1 Character sets (p: 17) </li> +<li> 6.4 Lexical elements (p: 41-54) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 5.1.1.2 Translation phases (p: 10-11) </li> +<li> 5.2.1 Character sets (p: 22-24) </li> +<li> 6.4 Lexical elements (p: 57-75) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 5.1.1.2 Translation phases (p: 9-10) </li> +<li> 5.2.1 Character sets (p: 17-19) </li> +<li> 6.4 Lexical elements (p: 49-66) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 2.1.1.2 Translation phases </li> +<li> 2.2.1 Character sets </li> +<li> 3.1 Lexical elements </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/translation_phases" title="cpp/language/translation phases">C++ documentation</a></span> for <span class=""><span>Phases of translation</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/translation_phases" class="_attribution-link">https://en.cppreference.com/w/c/language/translation_phases</a> + </p> +</div> diff --git a/devdocs/c/language%2Ftype.html b/devdocs/c/language%2Ftype.html new file mode 100644 index 00000000..c7b398c4 --- /dev/null +++ b/devdocs/c/language%2Ftype.html @@ -0,0 +1,233 @@ + <h1 id="firstHeading" class="firstHeading">Type</h1> <p><small>(See also <a href="arithmetic_types" title="c/language/arithmetic types">arithmetic types</a> for the details on most built-in types and <a href="../types" title="c/types">the list of type-related utilities</a> that are provided by the C library.)</small></p> +<p><a href="object" title="c/language/object">Objects</a>, <a href="functions" title="c/language/functions">functions</a>, and <a href="expressions" title="c/language/expressions">expressions</a> have a property called <i>type</i>, which determines the interpretation of the binary value stored in an object or evaluated by the expression.</p> +<h3 id="Type_classification"> Type classification</h3> <p>The C type system consists of the following types:</p> +<ul> +<li>the type <code>void</code> </li> +<li>basic types </li> +<li>the type <code>char</code> </li> +<li>signed integer types </li> +<ul><li>standard: <code>signed char</code>, <code>short</code>, <code>int</code>, <code>long</code><span class="t-rev-inl t-since-c99"><span>, <code>long long</code></span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> </li></ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <ul><li>bit-precise: <code>_BitInt(N)</code> where N is an integer constant expression that specifies the number of bits that are used to represent the type, including the sign bit. Each value of N designates a distinct type. </li></ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> <tr class="t-rev t-since-c99"> +<td> <ul><li>extended: implementation defined, e.g. <code>__int128</code> </li></ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <ul> +<li>unsigned integer types </li> +<ul><li>standard: <span class="t-rev-inl t-since-c99"><span><code>_Bool</code>,</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> <code>unsigned char</code>, <code>unsigned short</code>, <code>unsigned int</code>, <code>unsigned long</code><span class="t-rev-inl t-since-c99"><span>, <code>unsigned long long</code></span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> </li></ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <ul><li>bit-precise: <code>unsigned _BitInt(N)</code> where N is an integer constant expression that specifies the number of bits that are used to represent the type. Each value of N designates a distinct type. This category includes the type <code>unsigned _BitInt(1)</code> which does not have a corresponding bit-precise signed integer type </li></ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> <tr class="t-rev t-since-c99"> +<td> <ul><li>extended: implementation-defined, e.g. <code>__uint128</code> </li></ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <ul> +<li>floating-point types </li> +<ul><li>real floating-point types: <code>float</code>, <code>double</code>, <code>long double</code> </li></ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <ul><li>decimal real floating-point types: <code>_Decimal32</code>, <code>_Decimal64</code>, <code>_Decimal128</code> </li></ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> <tr class="t-rev t-since-c99"> +<td> <ul> +<li>complex types: <code>float _Complex</code>, <code>double _Complex</code>, <code>long double _Complex</code> </li> +<li>imaginary types: <code>float _Imaginary</code>, <code>double _Imaginary</code>, <code>long double _Imaginary</code> </li> +</ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <ul> +<li> <a href="enum" title="c/language/enum">enumerated types</a> </li> +<li> derived types </li> +<ul> +<li> <a href="array" title="c/language/array">array types</a> </li> +<li> <a href="struct" title="c/language/struct">structure types</a> </li> +<li> <a href="union" title="c/language/union">union types</a> </li> +<li> <a href="functions" title="c/language/functions">function types</a> </li> +<li> <a href="pointer" title="c/language/pointer">pointer types</a> </li> +</ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <ul><li> <a href="atomic" title="c/language/atomic">atomic types</a> </li></ul> </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <p>For every type listed above several qualified versions of its type may exist, corresponding to the combinations of one, two, or all three of the <a href="const" title="c/language/const"><code>const</code></a>, <a href="volatile" title="c/language/volatile"><code>volatile</code></a>, and <a href="restrict" title="c/language/restrict"><code>restrict</code></a> qualifiers (where allowed by the qualifier's semantics).</p> +<h4 id="Type_groups"> Type groups</h4> <ul> +<li> <i>object types</i>: all types that aren't function types </li> +<li> <i>character types</i>: <code>char</code>, <code>signed char</code>, <code>unsigned char</code> </li> +<li> <i>integer types</i>: <code>char</code>, signed integer types, unsigned integer types, enumerated types </li> +<li> <i>real types</i>: integer types and real floating types </li> +<li> <a href="arithmetic_types" title="c/language/arithmetic types">arithmetic types</a>: integer types and floating types </li> +<li> <i>scalar types</i>: arithmetic types, pointer types<span class="t-rev-inl t-since-c23"><span>, and <code><a href="../types/nullptr_t" title="c/types/nullptr t">nullptr_t</a></code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> </li> +<li> <i>aggregate types</i>: array types and structure types </li> +<li> <i>derived declarator types</i>: array types, function types, and pointer types </li> +</ul> <p>Constructing a complete object type such that the number of bytes in its object representation is not representable in the type <code><a href="../types/size_t" title="c/types/size t">size_t</a></code> (i.e. the result type of <a href="sizeof" title="c/language/sizeof"><code>sizeof</code></a> operator)<span class="t-rev-inl t-since-c99"><span>, including forming such a VLA type at runtime,</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> is undefined behavior.</p> +<h3 id="Compatible_types"> Compatible types</h3> <p>In a C program, the declarations referring to the same object or function in <i>different translation units</i> do not have to use the same type. They only have to use sufficiently similar types, formally known as <i>compatible types</i>. Same applies to function calls and lvalue accesses; argument types must be <i>compatible</i> with parameter types and lvalue expression type must be <i>compatible</i> with the object type that is accessed.</p> +<p>The types <code>T</code> and <code>U</code> are compatible, if</p> +<ul> +<li> they are the same type (same name or aliases introduced by a <a href="typedef" title="c/language/typedef"><code>typedef</code></a>) </li> +<li> they are identically cvr-qualified versions of compatible unqualified types </li> +<li> they are pointer types and are pointing to compatible types </li> +<li> they are array types, and </li> +<ul> +<li> their element types are compatible, and </li> +<li> if both have constant size, that size is the same. Note: arrays of unknown bound are compatible with any array of compatible element type. <span class="t-rev-inl t-since-c99"><span>VLA is compatible with any array of compatible element type.</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> </li> +</ul> +<li> they are both structure/union/enumeration types, and </li> +<li> +<span class="t-mark-rev t-since-c99">(C99)</span>if one is declared with a tag, the other must also be declared with the same tag. </li> +<li> if both are completed types, their members must correspond exactly in number, be declared with compatible types, and have matching names. </li> +<li> additionally, if they are enumerations, corresponding members must also have the same values. </li> +<li> additionally, if they are structures or unions, </li> +<ul> +<li> Corresponding members must be declared in the same order (structures only) </li> +<li> Corresponding <a href="bit_field" title="c/language/bit field">bit-fields</a> must have the same widths. </li> +</ul> +<li> one is an enumerated type and the other is that enumeration's underlying type </li> +<li> they are function types, and </li> +<ul> +<li> their return types are compatible </li> +<li> they both use parameter lists, the number of parameters (including the use of the ellipsis) is the same, and the corresponding parameter, after applying array-to-pointer and function-to-pointer type adjustments and after stripping top-level qualifiers, have compatible types </li> +</ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <ul> +<li> one is an old-style (parameter-less) definition, the other has a parameter list, the parameter list does not use an ellipsis and each parameter is compatible (after function parameter type adjustment) with the corresponding old-style parameter after default argument promotions </li> +<li> one is an old-style (parameter-less) declaration, the other has a parameter list, the parameter list does not use an ellipsis, and all parameters (after function parameter type adjustment) are unaffected by default argument promotions </li> +</ul> </td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> </table> <p>The type <code>char</code> is not compatible with <code>signed char</code> and not compatible with <code>unsigned char</code>.</p> +<p>If two declarations refer to the same object or function and do not use compatible types, the behavior of the program is undefined.</p> +<div class="c source-c"><pre data-language="c">// Translation Unit 1 +struct S { int a; }; +extern struct S *x; // compatible with TU2's x, but not with TU3's x + +// Translation Unit 2 +struct S; +extern struct S *x; // compatible with both x's + +// Translation Unit 3 +struct S { float a; }; +extern struct S *x; // compatible with TU2's x, but not with TU1's x + +// the behavior is undefined</pre></div> <div class="c source-c"><pre data-language="c">// Translation Unit 1 +#include <stdio.h> + +struct s { int i; }; // compatible with TU3's s, but not TU2's +extern struct s x = {0}; // compatible with TU3's x +extern void f(void); // compatible with TU2's f + +int main() +{ + f(); + return x.i; +} + +// Translation Unit 2 +struct s { float f; }; // compatible with TU4's s, but not TU1's s +extern struct s y = {3.14}; // compatible with TU4's y +void f() // compatible with TU1's f +{ + return; +} + +// Translation Unit 3 +struct s { int i; }; // compatible with TU1's s, but not TU2's s +extern struct s x; // compatible with TU1's x + +// Translation Unit 4 +struct s { float f; }; // compatible with TU2's s, but not TU1's s +extern struct s y; // compatible with TU2's y + +// the behavior is well-defined: only multiple declarations +// of objects and functions must have compatible types, not the types themselves</pre></div> <p>Note: C++ has no concept of compatible types. A C program that declares two types that are compatible but not identical in different translation units is not a valid C++ program.</p> +<h3 id="Composite_types"> Composite types</h3> <p>A composite type can be constructed from two types that are compatible; it is a type that is compatible with both of the two types and satisfies the following conditions:</p> +<ul> +<li>If both types are array types, the following rules are applied: </li> +<ul><li>If one type is an array of known constant size, the composite type is an array of that size. </li></ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <ul> +<li>Otherwise, if one type is a VLA whose size is specified by an expression that is not evaluated, a program necessitating the composite type of both types has undefined behavior. </li> +<li>Otherwise, if one type is a VLA whose size is specified, the composite type is a VLA of that size. </li> +<li>Otherwise, if one type is a VLA of unspecified size, the composite type is a VLA of unspecified size. </li> +</ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <ul><li>Otherwise, both types are arrays of unknown size and the composite type is an array of unknown size. </li></ul> The element type of the composite type is the composite type of the two element types. <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <ul><li>If only one type is a function type with a parameter type list (a function prototype), the composite type is a function prototype with the parameter type list. </li></ul> </td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> </table> <ul><li>If both types are function types with parameter type lists, the type of each parameter in the composite parameter type list is the composite type of the corresponding parameters. </li></ul> <p>These rules apply recursively to the types from which the two types are derived.</p> +<div class="c source-c"><pre data-language="c">// Given the following two file scope declarations: +int f(int (*)(), double (*)[3]); +int f(int (*)(char *), double (*)[]); // C23: Error: conflicting types for 'f' +// The resulting composite type for the function is: +int f(int (*)(char *), double (*)[3]);</pre></div> <p>For an identifier with internal or external <a href="storage_duration" title="c/language/storage duration">linkage</a> declared in a scope in which a prior declaration of that identifier is visible, if the prior declaration specifies internal or external linkage, the type of the identifier at the later declaration becomes the composite type.</p> +<h3 id="Incomplete_types"> Incomplete types</h3> <p>An incomplete type is an object type that lacks sufficient information to determine the size of the objects of that type. An incomplete type may be completed at some point in the translation unit.</p> +<p>The following types are incomplete:</p> +<ul> +<li> the type <code>void</code>. This type cannot be completed. </li> +<li> array type of unknown size. It can be completed by a later declaration that specifies the size. </li> +</ul> <div class="c source-c"><pre data-language="c">extern char a[]; // the type of a is incomplete (this typically appears in a header) +char a[10]; // the type of a is now complete (this typically appears in a source file)</pre></div> <ul><li> structure or union type of unknown content. It can be completed by a declaration of the same structure or union that defines its content later in the same scope. </li></ul> <div class="c source-c"><pre data-language="c">struct node +{ + struct node *next; // struct node is incomplete at this point +}; // struct node is complete at this point</pre></div> <h3 id="Type_names"> Type names</h3> <p>A type may have to be named in context other than the <a href="declarations" title="c/language/declarations">declaration</a>. In these situations, <i>type name</i> is used, which is, grammatically, exactly the same as a list of <i>type-specifiers</i> and <i>type-qualifiers</i>, followed by the <i>declarator</i> (see <a href="declarations" title="c/language/declarations">declarations</a>) as would be used to declare a single object or function of this type, except that the identifier is omitted:</p> +<div class="c source-c"><pre data-language="c">int n; // declaration of an int +sizeof(int); // use of type name + +int *a[3]; // declaration of an array of 3 pointers to int +sizeof(int *[3]); // use of type name + +int (*p)[3]; // declaration of a pointer to array of 3 int +sizeof(int (*)[3]); // use of type name + +int (*a)[*] // declaration of pointer to VLA (in a function parameter) +sizeof(int (*)[*]) // use of type name (in a function parameter) + +int *f(void); // declaration of function +sizeof(int *(void)); // use of type name + +int (*p)(void); // declaration of pointer to function +sizeof(int (*)(void)); // use of type name + +int (*const a[])(unsigned int, ...) = {0}; // array of pointers to functions +sizeof(int (*const [])(unsigned int, ...)); // use of type name</pre></div> <p>Except the redundant parentheses around the identifier are meaningful in a type-name and represent "function with no parameter specification":</p> +<div class="c source-c"><pre data-language="c">int (n); // declares n of type int +sizeof(int ()); // uses type "function returning int"</pre></div> <p>Type names are used in the following situations:</p> +<ul> +<li> <a href="cast" title="c/language/cast">cast</a> </li> +<li> <a href="sizeof" title="c/language/sizeof">sizeof</a> </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <ul><li> <a href="compound_literal" title="c/language/compound literal">compound literal</a> </li></ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> <tr class="t-rev t-since-c11"> +<td> <ul> +<li> <a href="generic" title="c/language/generic">generic selection</a> </li> +<li> <a href="_alignof" title="c/language/ Alignof">_Alignof</a> </li> +<li> <a href="_alignas" title="c/language/ Alignas">_Alignas</a> </li> +<li> <a href="atomic" title="c/language/atomic">_Atomic</a> (when used as a type specifier) </li> +</ul> </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <p><br> A type name may introduce a new type:</p> +<div class="c source-c"><pre data-language="c">void* p = (void*)(struct X { int i; } *)0; +// type name "struct X {int i;}*" used in the cast expression +// introduces the new type "struct X" +struct X x = {1}; // struct X is now in scope</pre></div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 6.2.5 Types (p: TBD) </li> +<li> 6.2.6 Representations of types (p: TBD) </li> +<li> 6.2.7 Compatible type and composite type (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.2.5 Types (p: 31-33) </li> +<li> 6.2.6 Representations of types (p: 31-35) </li> +<li> 6.2.7 Compatible type and composite type (p: 35-36) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.2.5 Types (p: 39-43) </li> +<li> 6.2.6 Representations of types (p: 44-46) </li> +<li> 6.2.7 Compatible type and composite type (p: 47-48) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 6.2.5 Types (p: 33-37) </li> +<li> 6.2.6 Representations of types (p: 37-40) </li> +<li> 6.2.7 Compatible type and composite type (p: 40-41) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 3.1.2.5 Types </li> +<li> 3.1.2.6 Compatible type and composite type </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/type" title="cpp/language/type">C++ documentation</a></span> for <span class=""><span>Type</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/type" class="_attribution-link">https://en.cppreference.com/w/c/language/type</a> + </p> +</div> diff --git a/devdocs/c/language%2Ftypedef.html b/devdocs/c/language%2Ftypedef.html new file mode 100644 index 00000000..5deaefd3 --- /dev/null +++ b/devdocs/c/language%2Ftypedef.html @@ -0,0 +1,60 @@ + <h1 id="firstHeading" class="firstHeading">Typedef declaration</h1> <p>The <i>typedef declaration</i> provides a way to declare an identifier as a type alias, to be used to replace a possibly complex <a href="type#Type_names" title="c/language/type">type name</a></p> +<p>The keyword <code>typedef</code> is used in a <a href="declarations" title="c/language/declarations">declaration</a>, in the grammatical position of a <a href="storage_duration" title="c/language/storage duration">storage-class specifier</a>, except that it does not affect storage or linkage:</p> +<div class="c source-c"><pre data-language="c">typedef int int_t; // declares int_t to be an alias for the type int +typedef char char_t, *char_p, (*fp)(void); // declares char_t to be an alias for char + // char_p to be an alias for char* + // fp to be an alias for char(*)(void)</pre></div> <h3 id="Explanation"> Explanation</h3> <p>If a <a href="declarations" title="c/language/declarations">declaration</a> uses <code>typedef</code> as storage-class specifier, every declarator in it defines an identifier as an alias to the type specified. Since only one storage-class specifier is permitted in a declaration, typedef declaration cannot be <a href="storage_duration" title="c/language/storage duration">static or extern</a>.</p> +<p>typedef declaration does not introduce a distinct type, it only establishes a synonym for an existing type, thus typedef names are <a href="type#Compatible_types" title="c/language/type">compatible</a> with the types they alias. Typedef names share the <a href="name_space" title="c/language/name space">name space</a> with ordinary identifiers such as enumerators, variables and function.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>A typedef for a VLA can only appear at block scope. The length of the array is evaluated each time the flow of control passes over the typedef declaration, as opposed to the declaration of the array itself:</p> +<div class="c source-c"><pre data-language="c">void copyt(int n) +{ + typedef int B[n]; // B is a VLA, its size is n, evaluated now + n += 1; + B a; // size of a is n from before +=1 + int b[n]; // a and b are different sizes + for (int i = 1; i < n; i++) + a[i-1] = b[i]; +}</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>typedef name may be an <a href="type#Incomplete_types" title="c/language/type">incomplete type</a>, which may be completed as usual:</p> +<div class="c source-c"><pre data-language="c">typedef int A[]; // A is int[] +A a = {1, 2}, b = {3,4,5}; // type of a is int[2], type of b is int[3]</pre></div> <p>typedef declarations are often used to inject names from the tag <a href="name_space" title="c/language/name space">name space</a> into the ordinary name space:</p> +<div class="c source-c"><pre data-language="c">typedef struct tnode tnode; // tnode in ordinary name space + // is an alias to tnode in tag name space +struct tnode { + int count; + tnode *left, *right; // same as struct tnode *left, *right; +}; // now tnode is also a complete type +tnode s, *sp; // same as struct tnode s, *sp;</pre></div> <p>They can even avoid using the tag name space at all:</p> +<div class="c source-c"><pre data-language="c">typedef struct { double hi, lo; } range; +range z, *zp;</pre></div> <p>Typedef names are also commonly used to simplify the syntax of complex declarations:</p> +<div class="c source-c"><pre data-language="c">// array of 5 pointers to functions returning pointers to arrays of 3 ints +int (*(*callbacks[5])(void))[3] + +// same with typedefs +typedef int arr_t[3]; // arr_t is array of 3 int +typedef arr_t* (*fp)(void); // pointer to function returning arr_t* +fp callbacks[5];</pre></div> <p>Libraries often expose system-dependent or configuration-dependent types as typedef names, to present a consistent interface to the users or to other library components:</p> +<div class="c source-c"><pre data-language="c">#if defined(_LP64) +typedef int wchar_t; +#else +typedef long wchar_t; +#endif</pre></div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.7.8 Type definitions (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.7.8 Type definitions (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.7.8 Type definitions (p: 137-138) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.7.7 Type definitions (p: 123-124) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.5.6 Type definitions </li></ul> +</ul> <h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/typedef" title="c/keyword/typedef"><code>typedef</code></a></p> +<h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/typedef" title="cpp/language/typedef">C++ documentation</a></span> for <span class=""><span><code>typedef</code> declaration</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/typedef" class="_attribution-link">https://en.cppreference.com/w/c/language/typedef</a> + </p> +</div> diff --git a/devdocs/c/language%2Ftypeof.html b/devdocs/c/language%2Ftypeof.html new file mode 100644 index 00000000..b9f1c4e0 --- /dev/null +++ b/devdocs/c/language%2Ftypeof.html @@ -0,0 +1,21 @@ + <h1 id="firstHeading" class="firstHeading">typeof operators <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <p>Determines the type of an object.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>typeof(</code> <span class="t-spar">type</span> <code>)</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>typeof(</code> <span class="t-spar">expression</span> <code>)</code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>typeof_unqual(</code> <span class="t-spar">type</span> <code>)</code> </td> <td> (3) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>typeof_unqual(</code> <span class="t-spar">expression</span> <code>)</code> </td> <td> (4) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <div class="t-li1"> +<span class="t-li">1)</span> produces the type-name with any nested typeof-specifier evaluated </div> <div class="t-li1"> +<span class="t-li">2)</span> yields the type-name representing the type of its operand. No implicit conversions are applied to <span class="t-spar">expression</span>.</div> <div class="t-li1"> +<span class="t-li">3,4)</span> the same as <span class="t-v">(1)</span> and <span class="t-v">(2)</span> respectively but remove qualifiers</div> <h3 id="Notes"> Notes</h3> <p><code>typeof</code> and <code>typeof_unqual</code> are collectively called the <i>typeof operators</i>. The <code>typeof</code> operators cannot be applied to bit-field members. If the type of the operand is a variably modified type, the operand is evaluated; otherwise, the operand is not evaluated. The result of the <code>typeof_unqual</code> operator is the non-atomic unqualified type that would result from the <code>typeof</code> operator. The <code>typeof</code> operator preserves all qualifiers.</p> +<h3 id="Example"> Example</h3> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.7.2.5 The typeof specifiers (p: 115-118) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/decltype" title="cpp/language/decltype">C++ documentation</a></span> for <code>decltype</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/typeof" class="_attribution-link">https://en.cppreference.com/w/c/language/typeof</a> + </p> +</div> diff --git a/devdocs/c/language%2Ftypes.html b/devdocs/c/language%2Ftypes.html new file mode 100644 index 00000000..9c57b336 --- /dev/null +++ b/devdocs/c/language%2Ftypes.html @@ -0,0 +1,233 @@ + <h1 id="firstHeading" class="firstHeading">Type</h1> <p><small>(See also <a href="arithmetic_types" title="c/language/arithmetic types">arithmetic types</a> for the details on most built-in types and <a href="../types" title="c/types">the list of type-related utilities</a> that are provided by the C library.)</small></p> +<p><a href="object" title="c/language/object">Objects</a>, <a href="functions" title="c/language/functions">functions</a>, and <a href="expressions" title="c/language/expressions">expressions</a> have a property called <i>type</i>, which determines the interpretation of the binary value stored in an object or evaluated by the expression.</p> +<h3 id="Type_classification"> Type classification</h3> <p>The C type system consists of the following types:</p> +<ul> +<li>the type <code>void</code> </li> +<li>basic types </li> +<li>the type <code>char</code> </li> +<li>signed integer types </li> +<ul><li>standard: <code>signed char</code>, <code>short</code>, <code>int</code>, <code>long</code><span class="t-rev-inl t-since-c99"><span>, <code>long long</code></span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> </li></ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <ul><li>bit-precise: <code>_BitInt(N)</code> where N is an integer constant expression that specifies the number of bits that are used to represent the type, including the sign bit. Each value of N designates a distinct type. </li></ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> <tr class="t-rev t-since-c99"> +<td> <ul><li>extended: implementation defined, e.g. <code>__int128</code> </li></ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <ul> +<li>unsigned integer types </li> +<ul><li>standard: <span class="t-rev-inl t-since-c99"><span><code>_Bool</code>,</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> <code>unsigned char</code>, <code>unsigned short</code>, <code>unsigned int</code>, <code>unsigned long</code><span class="t-rev-inl t-since-c99"><span>, <code>unsigned long long</code></span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> </li></ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <ul><li>bit-precise: <code>unsigned _BitInt(N)</code> where N is an integer constant expression that specifies the number of bits that are used to represent the type. Each value of N designates a distinct type. This category includes the type <code>unsigned _BitInt(1)</code> which does not have a corresponding bit-precise signed integer type </li></ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> <tr class="t-rev t-since-c99"> +<td> <ul><li>extended: implementation-defined, e.g. <code>__uint128</code> </li></ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <ul> +<li>floating-point types </li> +<ul><li>real floating-point types: <code>float</code>, <code>double</code>, <code>long double</code> </li></ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <ul><li>decimal real floating-point types: <code>_Decimal32</code>, <code>_Decimal64</code>, <code>_Decimal128</code> </li></ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> <tr class="t-rev t-since-c99"> +<td> <ul> +<li>complex types: <code>float _Complex</code>, <code>double _Complex</code>, <code>long double _Complex</code> </li> +<li>imaginary types: <code>float _Imaginary</code>, <code>double _Imaginary</code>, <code>long double _Imaginary</code> </li> +</ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <ul> +<li> <a href="enum" title="c/language/enum">enumerated types</a> </li> +<li> derived types </li> +<ul> +<li> <a href="array" title="c/language/array">array types</a> </li> +<li> <a href="struct" title="c/language/struct">structure types</a> </li> +<li> <a href="union" title="c/language/union">union types</a> </li> +<li> <a href="functions" title="c/language/functions">function types</a> </li> +<li> <a href="pointer" title="c/language/pointer">pointer types</a> </li> +</ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <ul><li> <a href="atomic" title="c/language/atomic">atomic types</a> </li></ul> </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <p>For every type listed above several qualified versions of its type may exist, corresponding to the combinations of one, two, or all three of the <a href="const" title="c/language/const"><code>const</code></a>, <a href="volatile" title="c/language/volatile"><code>volatile</code></a>, and <a href="restrict" title="c/language/restrict"><code>restrict</code></a> qualifiers (where allowed by the qualifier's semantics).</p> +<h4 id="Type_groups"> Type groups</h4> <ul> +<li> <i>object types</i>: all types that aren't function types </li> +<li> <i>character types</i>: <code>char</code>, <code>signed char</code>, <code>unsigned char</code> </li> +<li> <i>integer types</i>: <code>char</code>, signed integer types, unsigned integer types, enumerated types </li> +<li> <i>real types</i>: integer types and real floating types </li> +<li> <a href="arithmetic_types" title="c/language/arithmetic types">arithmetic types</a>: integer types and floating types </li> +<li> <i>scalar types</i>: arithmetic types, pointer types<span class="t-rev-inl t-since-c23"><span>, and <code><a href="../types/nullptr_t" title="c/types/nullptr t">nullptr_t</a></code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> </li> +<li> <i>aggregate types</i>: array types and structure types </li> +<li> <i>derived declarator types</i>: array types, function types, and pointer types </li> +</ul> <p>Constructing a complete object type such that the number of bytes in its object representation is not representable in the type <code><a href="../types/size_t" title="c/types/size t">size_t</a></code> (i.e. the result type of <a href="sizeof" title="c/language/sizeof"><code>sizeof</code></a> operator)<span class="t-rev-inl t-since-c99"><span>, including forming such a VLA type at runtime,</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> is undefined behavior.</p> +<h3 id="Compatible_types"> Compatible types</h3> <p>In a C program, the declarations referring to the same object or function in <i>different translation units</i> do not have to use the same type. They only have to use sufficiently similar types, formally known as <i>compatible types</i>. Same applies to function calls and lvalue accesses; argument types must be <i>compatible</i> with parameter types and lvalue expression type must be <i>compatible</i> with the object type that is accessed.</p> +<p>The types <code>T</code> and <code>U</code> are compatible, if</p> +<ul> +<li> they are the same type (same name or aliases introduced by a <a href="typedef" title="c/language/typedef"><code>typedef</code></a>) </li> +<li> they are identically cvr-qualified versions of compatible unqualified types </li> +<li> they are pointer types and are pointing to compatible types </li> +<li> they are array types, and </li> +<ul> +<li> their element types are compatible, and </li> +<li> if both have constant size, that size is the same. Note: arrays of unknown bound are compatible with any array of compatible element type. <span class="t-rev-inl t-since-c99"><span>VLA is compatible with any array of compatible element type.</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span> </li> +</ul> +<li> they are both structure/union/enumeration types, and </li> +<li> +<span class="t-mark-rev t-since-c99">(C99)</span>if one is declared with a tag, the other must also be declared with the same tag. </li> +<li> if both are completed types, their members must correspond exactly in number, be declared with compatible types, and have matching names. </li> +<li> additionally, if they are enumerations, corresponding members must also have the same values. </li> +<li> additionally, if they are structures or unions, </li> +<ul> +<li> Corresponding members must be declared in the same order (structures only) </li> +<li> Corresponding <a href="bit_field" title="c/language/bit field">bit-fields</a> must have the same widths. </li> +</ul> +<li> one is an enumerated type and the other is that enumeration's underlying type </li> +<li> they are function types, and </li> +<ul> +<li> their return types are compatible </li> +<li> they both use parameter lists, the number of parameters (including the use of the ellipsis) is the same, and the corresponding parameter, after applying array-to-pointer and function-to-pointer type adjustments and after stripping top-level qualifiers, have compatible types </li> +</ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <ul> +<li> one is an old-style (parameter-less) definition, the other has a parameter list, the parameter list does not use an ellipsis and each parameter is compatible (after function parameter type adjustment) with the corresponding old-style parameter after default argument promotions </li> +<li> one is an old-style (parameter-less) declaration, the other has a parameter list, the parameter list does not use an ellipsis, and all parameters (after function parameter type adjustment) are unaffected by default argument promotions </li> +</ul> </td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> </table> <p>The type <code>char</code> is not compatible with <code>signed char</code> and not compatible with <code>unsigned char</code>.</p> +<p>If two declarations refer to the same object or function and do not use compatible types, the behavior of the program is undefined.</p> +<div class="c source-c"><pre data-language="c">// Translation Unit 1 +struct S { int a; }; +extern struct S *x; // compatible with TU2's x, but not with TU3's x + +// Translation Unit 2 +struct S; +extern struct S *x; // compatible with both x's + +// Translation Unit 3 +struct S { float a; }; +extern struct S *x; // compatible with TU2's x, but not with TU1's x + +// the behavior is undefined</pre></div> <div class="c source-c"><pre data-language="c">// Translation Unit 1 +#include <stdio.h> + +struct s { int i; }; // compatible with TU3's s, but not TU2's +extern struct s x = {0}; // compatible with TU3's x +extern void f(void); // compatible with TU2's f + +int main() +{ + f(); + return x.i; +} + +// Translation Unit 2 +struct s { float f; }; // compatible with TU4's s, but not TU1's s +extern struct s y = {3.14}; // compatible with TU4's y +void f() // compatible with TU1's f +{ + return; +} + +// Translation Unit 3 +struct s { int i; }; // compatible with TU1's s, but not TU2's s +extern struct s x; // compatible with TU1's x + +// Translation Unit 4 +struct s { float f; }; // compatible with TU2's s, but not TU1's s +extern struct s y; // compatible with TU2's y + +// the behavior is well-defined: only multiple declarations +// of objects and functions must have compatible types, not the types themselves</pre></div> <p>Note: C++ has no concept of compatible types. A C program that declares two types that are compatible but not identical in different translation units is not a valid C++ program.</p> +<h3 id="Composite_types"> Composite types</h3> <p>A composite type can be constructed from two types that are compatible; it is a type that is compatible with both of the two types and satisfies the following conditions:</p> +<ul> +<li>If both types are array types, the following rules are applied: </li> +<ul><li>If one type is an array of known constant size, the composite type is an array of that size. </li></ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <ul> +<li>Otherwise, if one type is a VLA whose size is specified by an expression that is not evaluated, a program necessitating the composite type of both types has undefined behavior. </li> +<li>Otherwise, if one type is a VLA whose size is specified, the composite type is a VLA of that size. </li> +<li>Otherwise, if one type is a VLA of unspecified size, the composite type is a VLA of unspecified size. </li> +</ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <ul><li>Otherwise, both types are arrays of unknown size and the composite type is an array of unknown size. </li></ul> The element type of the composite type is the composite type of the two element types. <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <ul><li>If only one type is a function type with a parameter type list (a function prototype), the composite type is a function prototype with the parameter type list. </li></ul> </td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> </table> <ul><li>If both types are function types with parameter type lists, the type of each parameter in the composite parameter type list is the composite type of the corresponding parameters. </li></ul> <p>These rules apply recursively to the types from which the two types are derived.</p> +<div class="c source-c"><pre data-language="c">// Given the following two file scope declarations: +int f(int (*)(), double (*)[3]); +int f(int (*)(char *), double (*)[]); // C23: Error: conflicting types for 'f' +// The resulting composite type for the function is: +int f(int (*)(char *), double (*)[3]);</pre></div> <p>For an identifier with internal or external <a href="storage_duration" title="c/language/storage duration">linkage</a> declared in a scope in which a prior declaration of that identifier is visible, if the prior declaration specifies internal or external linkage, the type of the identifier at the later declaration becomes the composite type.</p> +<h3 id="Incomplete_types"> Incomplete types</h3> <p>An incomplete type is an object type that lacks sufficient information to determine the size of the objects of that type. An incomplete type may be completed at some point in the translation unit.</p> +<p>The following types are incomplete:</p> +<ul> +<li> the type <code>void</code>. This type cannot be completed. </li> +<li> array type of unknown size. It can be completed by a later declaration that specifies the size. </li> +</ul> <div class="c source-c"><pre data-language="c">extern char a[]; // the type of a is incomplete (this typically appears in a header) +char a[10]; // the type of a is now complete (this typically appears in a source file)</pre></div> <ul><li> structure or union type of unknown content. It can be completed by a declaration of the same structure or union that defines its content later in the same scope. </li></ul> <div class="c source-c"><pre data-language="c">struct node +{ + struct node *next; // struct node is incomplete at this point +}; // struct node is complete at this point</pre></div> <h3 id="Type_names"> Type names</h3> <p>A type may have to be named in context other than the <a href="declarations" title="c/language/declarations">declaration</a>. In these situations, <i>type name</i> is used, which is, grammatically, exactly the same as a list of <i>type-specifiers</i> and <i>type-qualifiers</i>, followed by the <i>declarator</i> (see <a href="declarations" title="c/language/declarations">declarations</a>) as would be used to declare a single object or function of this type, except that the identifier is omitted:</p> +<div class="c source-c"><pre data-language="c">int n; // declaration of an int +sizeof(int); // use of type name + +int *a[3]; // declaration of an array of 3 pointers to int +sizeof(int *[3]); // use of type name + +int (*p)[3]; // declaration of a pointer to array of 3 int +sizeof(int (*)[3]); // use of type name + +int (*a)[*] // declaration of pointer to VLA (in a function parameter) +sizeof(int (*)[*]) // use of type name (in a function parameter) + +int *f(void); // declaration of function +sizeof(int *(void)); // use of type name + +int (*p)(void); // declaration of pointer to function +sizeof(int (*)(void)); // use of type name + +int (*const a[])(unsigned int, ...) = {0}; // array of pointers to functions +sizeof(int (*const [])(unsigned int, ...)); // use of type name</pre></div> <p>Except the redundant parentheses around the identifier are meaningful in a type-name and represent "function with no parameter specification":</p> +<div class="c source-c"><pre data-language="c">int (n); // declares n of type int +sizeof(int ()); // uses type "function returning int"</pre></div> <p>Type names are used in the following situations:</p> +<ul> +<li> <a href="cast" title="c/language/cast">cast</a> </li> +<li> <a href="sizeof" title="c/language/sizeof">sizeof</a> </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <ul><li> <a href="compound_literal" title="c/language/compound literal">compound literal</a> </li></ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> <tr class="t-rev t-since-c11"> +<td> <ul> +<li> <a href="generic" title="c/language/generic">generic selection</a> </li> +<li> <a href="_alignof" title="c/language/ Alignof">_Alignof</a> </li> +<li> <a href="_alignas" title="c/language/ Alignas">_Alignas</a> </li> +<li> <a href="atomic" title="c/language/atomic">_Atomic</a> (when used as a type specifier) </li> +</ul> </td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <p><br> A type name may introduce a new type:</p> +<div class="c source-c"><pre data-language="c">void* p = (void*)(struct X { int i; } *)0; +// type name "struct X {int i;}*" used in the cast expression +// introduces the new type "struct X" +struct X x = {1}; // struct X is now in scope</pre></div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 6.2.5 Types (p: TBD) </li> +<li> 6.2.6 Representations of types (p: TBD) </li> +<li> 6.2.7 Compatible type and composite type (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.2.5 Types (p: 31-33) </li> +<li> 6.2.6 Representations of types (p: 31-35) </li> +<li> 6.2.7 Compatible type and composite type (p: 35-36) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.2.5 Types (p: 39-43) </li> +<li> 6.2.6 Representations of types (p: 44-46) </li> +<li> 6.2.7 Compatible type and composite type (p: 47-48) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 6.2.5 Types (p: 33-37) </li> +<li> 6.2.6 Representations of types (p: 37-40) </li> +<li> 6.2.7 Compatible type and composite type (p: 40-41) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 3.1.2.5 Types </li> +<li> 3.1.2.6 Compatible type and composite type </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/type" title="cpp/language/type">C++ documentation</a></span> for <span class=""><span>Type</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/types" class="_attribution-link">https://en.cppreference.com/w/c/language/types</a> + </p> +</div> diff --git a/devdocs/c/language%2Funion.html b/devdocs/c/language%2Funion.html new file mode 100644 index 00000000..bd3b949b --- /dev/null +++ b/devdocs/c/language%2Funion.html @@ -0,0 +1,80 @@ + <h1 id="firstHeading" class="firstHeading">Union declaration</h1> <p>A union is a type consisting of a sequence of members whose storage overlaps (as opposed to struct, which is a type consisting of a sequence of members whose storage is allocated in an ordered sequence). The value of at most one of the members can be stored in a union at any one time.</p> +<p>The <a href="declarations" title="c/language/declarations">type specifier</a> for a union is identical to the <a href="struct" title="c/language/struct"><code>struct</code></a> type specifier except for the keyword used:</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>union</code> <span class="t-spar">attr-spec-seq</span> <span class="t-mark">(optional)</span> <span class="t-spar">name</span> <span class="t-mark">(optional)</span> <code>{</code> <span class="t-spar">struct-declaration-list</span> <code>}</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>union</code> <span class="t-spar">attr-spec-seq</span> <span class="t-mark">(optional)</span> <span class="t-spar">name</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">name</span> </td> <td> - </td> <td> the name of the union that's being defined </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">struct-declaration-list</span> </td> <td> - </td> <td> any number of variable declarations, <a href="bit_field" title="c/language/bit field">bit-field</a> declarations, and static assert declarations. Members of incomplete type and members of function type are not allowed. </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">attr-spec-seq</span> </td> <td> - </td> <td> <span class="t-mark-rev t-since-c23">(C23)</span>optional list of <a href="attributes" title="c/language/attributes">attributes</a>, applied to the union type, not allowed for <span class="t-v">(2)</span> if such form is not followed by a <code>;</code> (i.e. not a forward declaration). </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>The union is only as big as necessary to hold its largest member (additional unnamed trailing padding may also be added). The other members are allocated in the same bytes as part of that largest member.</p> +<p>A pointer to a union can be cast to a pointer to each of its members (if a union has bit-field members, the pointer to a union can be cast to the pointer to the bit-field's underlying type). Likewise, a pointer to any member of a union can be cast to a pointer to the enclosing union.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>If the member used to access the contents of a union is not the same as the member last used to store a value, the object representation of the value that was stored is reinterpreted as an object representation of the new type (this is known as <i>type punning</i>). If the size of the new type is larger than the size of the last-written type, the contents of the excess bytes are unspecified (and may be a trap representation). Before C99 TC3 (DR 283) this behaviour was undefined, but commonly implemented this way.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <p>Similar to struct, an unnamed member of a union whose type is a union without <span class="t-spar">name</span> is known as <i>anonymous union</i>. Every member of an anonymous union is considered to be a member of the enclosing struct or union keeping their union layout. This applies recursively if the enclosing struct or union is also anonymous.</p> +<div class="c source-c"><pre data-language="c">struct v +{ + union // anonymous union + { + struct { int i, j; }; // anonymous structure + struct { long k, l; } w; + }; + int m; +} v1; + +v1.i = 2; // valid +v1.k = 3; // invalid: inner structure is not anonymous +v1.w.k = 5; // valid</pre></div> <p>Similar to struct, the behavior of the program is undefined if union is defined without any named members (including those obtained via anonymous nested structs or unions).</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/union" title="c/keyword/union"><code>union</code></a></p> +<h3 id="Notes"> Notes</h3> <p>See <a href="struct_initialization" title="c/language/struct initialization">struct initialization</a> for the rules about initialization of structs and unions.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <assert.h> +#include <stdint.h> +#include <stdio.h> + +int main(void) +{ + union S + { + uint32_t u32; + uint16_t u16[2]; + uint8_t u8; + } s = {0x12345678}; // s.u32 is now the active member + printf("Union S has size %zu and holds %x\n", sizeof s, s.u32); + s.u16[0] = 0x0011; // s.u16 is now the active member + // reading from s.u32 or from s.u8 reinterprets the object representation +// printf("s.u8 is now %x\n", s.u8); // unspecified, typically 11 or 00 +// printf("s.u32 is now %x\n", s.u32); // unspecified, typically 12340011 or 00115678 + + // pointers to all members of a union compare equal to themselves and the union + assert((uint8_t*)&s == &s.u8); + + // this union has 3 bytes of trailing padding + union pad + { + char c[5]; // occupies 5 bytes + float f; // occupies 4 bytes, imposes alignment 4 + } p = {.f = 1.23}; // the size is 8 to satisfy float's alignment + printf("size of union of char[5] and float is %zu\n", sizeof p); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Union S has size 4 and holds 12345678 +size of union of char[5] and float is 8</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.7.2.1 Structure and union specifiers (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.7.2.1 Structure and union specifiers (p: 81-84) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.7.2.1 Structure and union specifiers (p: 112-117) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.7.2.1 Structure and union specifiers (p: 101-104) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.5.2.1 Structure and union specifiers </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/union" title="cpp/language/union">C++ documentation</a></span> for <span class=""><span>Union declaration</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/union" class="_attribution-link">https://en.cppreference.com/w/c/language/union</a> + </p> +</div> diff --git a/devdocs/c/language%2Fvalue_category.html b/devdocs/c/language%2Fvalue_category.html new file mode 100644 index 00000000..8306ec83 --- /dev/null +++ b/devdocs/c/language%2Fvalue_category.html @@ -0,0 +1,58 @@ + <h1 id="firstHeading" class="firstHeading">Value categories</h1> <p>Each <a href="expressions" title="c/language/expressions">expression</a> in C (an operator with its arguments, a function call, a constant, a variable name, etc) is characterized by two independent properties: a <a href="type#Type" title="c/language/type">type</a> and a <a href="expressions#General" title="c/language/expressions">value category</a>.</p> +<p>Every expression belongs to one of three value categories: lvalue, non-lvalue object (rvalue), and function designator.</p> +<h3 id="Lvalue_expressions"> Lvalue expressions</h3> <p>Lvalue expression is any expression with <a href="type#Type_groups" title="c/language/type">object type</a> other than the type <code>void</code>, which potentially designates an <a href="object" title="c/language/object">object</a> (the behavior is undefined if an lvalue does not actually designate an object when it is evaluated). In other words, lvalue expression evaluates to the <i>object identity</i>. The name of this value category ("left value") is historic and reflects the use of lvalue expressions as the left-hand operand of the assignment operator in the CPL programming language.</p> +<p>Lvalue expressions can be used in the following <i>lvalue contexts</i>:</p> +<ul> +<li> as the operand of the <a href="operator_member_access" title="c/language/operator member access">address-of operator</a> (except if the lvalue designates a <a href="bit_field" title="c/language/bit field">bit-field</a> or was declared <a href="storage_duration" title="c/language/storage duration">register</a>). </li> +<li> as the operand of the pre/post <a href="operator_incdec" title="c/language/operator incdec">increment and decrement operators</a>. </li> +<li> as the left-hand operand of the <a href="operator_member_access" title="c/language/operator member access">member access</a> (dot) operator. </li> +<li> as the left-hand operand of the <a href="operator_assignment" title="c/language/operator assignment">assignment and compound assignment</a> operators. </li> +</ul> <p>If an lvalue expression is used in any context other than <a href="sizeof" title="c/language/sizeof"><code>sizeof</code></a>, <a href="_alignof" title="c/language/ Alignof"><code>_Alignof</code></a>, or the operators listed above, non-array lvalues of any complete type undergo <a href="conversion" title="c/language/conversion">lvalue conversion</a>, which models the memory load of the value of the object from its location. Similarly, array lvalues undergo <a href="conversion" title="c/language/conversion">array-to-pointer conversion</a> when used in any context other than <code>sizeof</code>, <code>_Alignof</code>, address-of operator, or array initialization from a string literal.</p> +<p>The semantics of <a href="const" title="c/language/const"><code>const</code></a>/<a href="volatile" title="c/language/volatile"><code>volatile</code></a>/<a href="restrict" title="c/language/restrict"><code>restrict</code></a>-qualifiers and <a href="atomic" title="c/language/atomic">atomic</a> types apply to lvalues only (lvalue conversion strips the qualifiers and removes atomicity).</p> +<p>The following expressions are lvalues:</p> +<ul> +<li> identifiers, including function named parameters, provided they were declared as designating objects (not functions or enumeration constants) </li> +<li> <a href="string_literal" title="c/language/string literal">string literals</a> </li> +<li> <span class="t-mark-rev t-since-c99">(C99)</span> <a href="compound_literal" title="c/language/compound literal">compound literals</a> </li> +<li> parenthesized expression if the unparenthesized expression is an lvalue </li> +<li> the result of a member access (dot) operator if its left-hand argument is lvalue </li> +<li> the result of a member access through pointer <code>-></code> operator </li> +<li> the result of the indirection (unary <code>*</code>) operator applied to a pointer to object </li> +<li> the result of the subscription operator (<code>[]</code>) </li> +</ul> <h4 id="Modifiable_lvalue_expressions"> Modifiable lvalue expressions</h4> <p>A <i>modifiable lvalue</i> is any lvalue expression of complete, non-array type which is not <a href="const" title="c/language/const">const</a>-qualified, and, if it's a struct/union, has no members that are <a href="const" title="c/language/const">const</a>-qualified, recursively.</p> +<p>Only modifiable lvalue expressions may be used as arguments to increment/decrement, and as left-hand arguments of assignment and compound assignment operators.</p> +<h3 id="Non-lvalue_object_expressions"> Non-lvalue object expressions</h3> <p>Known as <i>rvalues</i>, non-lvalue object expressions are the expressions of object types that do not designate objects, but rather values that have no object identity or storage location. The address of a non-lvalue object expression cannot be taken.</p> +<p>The following expressions are non-lvalue object expressions:</p> +<ul> +<li> integer, character, and floating constants </li> +<li> all operators not specified to return lvalues, including </li> +<ul> +<li> any function call expression </li> +<li> any cast expression (note that compound literals, which look similar, are lvalues) </li> +<li> member access operator (dot) applied to a non-lvalue structure/union, <code>f().x</code>, <code>(x,s1).a</code>, <code>(s1=s2).m</code> </li> +<li> results of all arithmetic, relational, logical, and bitwise operators </li> +<li> results of increment and decrement operators (note: pre-forms are lvalues in C++) </li> +<li> results of assignment operators (note: also lvalues in C++) </li> +<li> the conditional operator (note: is lvalue in C++ if both the second and third operands are lvalues of the same type) </li> +<li> the comma operator (note: is lvalue in C++ if the second operand is) </li> +<li> the address-of operator, even if neutralized by application to the result of unary <code>*</code> operator </li> +</ul> +</ul> <p>As a special case, expressions of type <code>void</code> are assumed to be non-lvalue object expressions that yield a value which has no representation and requires no storage.</p> +<p>Note that a struct/union rvalue that has a member (possibly nested) of array type does in fact designate an object with <a href="lifetime" title="c/language/lifetime">temporary lifetime</a>. This object can be accessed through lvalue expressions that form by indexing the array member or by indirection through the pointer obtained by array-to-pointer conversion of the array member.</p> +<h3 id="Function_designator_expression"> Function designator expression</h3> <p>A function designator (the identifier introduced by a <a href="function_declaration" title="c/language/function declaration">function declaration</a>) is an expression of function type. When used in any context other than the address-of operator, <a href="sizeof" title="c/language/sizeof"><code>sizeof</code></a>, and <a href="_alignof" title="c/language/ Alignof"><code>_Alignof</code></a> (the last two generate compile errors when applied to functions), the function designator is always converted to a non-lvalue pointer to function. Note that the function-call operator is defined for pointers to functions and not for function designators themselves.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.3.2.1 Lvalues, arrays, and function designators (p: 40) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.3.2.1 Lvalues, arrays, and function designators (p: 54-55) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.3.2.1 Lvalues, arrays, and function designators (p: 46) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.2.2.1 Lvalues and function designators </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/value_category" title="cpp/language/value category">C++ documentation</a></span> for <span class=""><span>Value categories</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/value_category" class="_attribution-link">https://en.cppreference.com/w/c/language/value_category</a> + </p> +</div> diff --git a/devdocs/c/language%2Fvariadic.html b/devdocs/c/language%2Fvariadic.html new file mode 100644 index 00000000..610036e5 --- /dev/null +++ b/devdocs/c/language%2Fvariadic.html @@ -0,0 +1,73 @@ + <h1 id="firstHeading" class="firstHeading">Variadic arguments</h1> <p>Variadic functions are functions that may be called with different number of arguments.</p> +<p>Only prototyped <a href="function_declaration" title="c/language/function declaration">function declarations</a> may be variadic. This is indicated by the parameter of the form <code>...</code> which must appear last in the parameter list<span class="t-rev-inl t-until-c23"><span> and must follow at least one named parameter</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span>. The ellipsis parameter and the proceeding parameter must be delimited by <code>,</code>.</p> +<div class="c source-c"><pre data-language="c">// Prototyped declaration +int printx(const char* fmt, ...); // function declared this way +printx("hello world"); // may be called with one +printx("a=%d b=%d", a, b); // or more arguments + +int printz(...); // OK since C23 and in C++ +// Error until C23: ... must follow at least one named parameter + +// int printy(..., const char* fmt); // Error: ... must be the last +// int printa(const char* fmt...); // Error in C: ',' is required; OK in C++</pre></div> <p>At the <a href="operator_other#Function_call" title="c/language/operator other">function call</a>, each argument that is a part of the variable argument list undergoes special implicit conversions known as <a href="conversion#Default_argument_promotions" title="c/language/conversion">default argument promotions</a>.</p> +<p>Within the body of a function that uses variadic arguments, the values of these arguments may be accessed using the <a href="../variadic" title="c/variadic"><code><stdarg.h></code> library facilities</a>:</p> +<table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdarg.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="../variadic/va_start" title="c/variadic/va start"> <span class="t-lines"><span>va_start</span></span></a></div> </td> <td> enables access to variadic function arguments <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../variadic/va_arg" title="c/variadic/va arg"> <span class="t-lines"><span>va_arg</span></span></a></div> </td> <td> accesses the next variadic function argument <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../variadic/va_copy" title="c/variadic/va copy"> <span class="t-lines"><span>va_copy</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> makes a copy of the variadic function arguments <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../variadic/va_end" title="c/variadic/va end"> <span class="t-lines"><span>va_end</span></span></a></div> </td> <td> ends traversal of the variadic function arguments <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../variadic/va_list" title="c/variadic/va list"> <span class="t-lines"><span>va_list</span></span></a></div> </td> <td> holds the information needed by va_start, va_arg, va_end, and va_copy <br> <span class="t-mark">(typedef)</span> </td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>Although old-style (prototype-less) <a href="function_declaration" title="c/language/function declaration">function declarations</a> allow the subsequent function calls to use any number of arguments, they are not allowed to be variadic (as of C89). The definition of such function must specify a fixed number of parameters and cannot use the <code>stdarg.h</code> macros.</p> +<div class="c source-c"><pre data-language="c">// old-style declaration, removed in C23 +int printx(); // function declared this way +printx("hello world"); // may be called with one +printx("a=%d b=%d", a, b); // or more arguments +// the behavior of at least one of these calls is undefined, depending on +// the number of parameters the function is defined to take</pre></div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <time.h> +#include <stdarg.h> + +void tlog(const char* fmt,...) +{ + char msg[50]; + strftime(msg, sizeof msg, "%T", localtime(&(time_t){time(NULL)})); + printf("[%s] ", msg); + va_list args; + va_start(args, fmt); + vprintf(fmt, args); + va_end(args); +} + +int main(void) +{ + tlog("logging %d %d %d...\n", 1, 2, 3); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">[10:21:38] logging 1 2 3...</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.7.6.3/9 Function declarators (including prototypes) (p: 96) </li> +<li> 7.16 Variable arguments <stdarg.h> (p: 197-199) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.7.6.3/9 Function declarators (including prototypes) (p: 133) </li> +<li> 7.16 Variable arguments <stdarg.h> (p: 269-272) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 6.7.5.3/9 Function declarators (including prototypes) (p: 119) </li> +<li> 7.15 Variable arguments <stdarg.h> (p: 249-252) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 3.5.4.3/5 Function declarators (including prototypes) </li> +<li> 4.8 VARIABLE ARGUMENTS <stdarg.h> </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/variadic_arguments" title="cpp/language/variadic arguments">C++ documentation</a></span> for <span class=""><span>Variadic arguments</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/variadic" class="_attribution-link">https://en.cppreference.com/w/c/language/variadic</a> + </p> +</div> diff --git a/devdocs/c/language%2Fvolatile.html b/devdocs/c/language%2Fvolatile.html new file mode 100644 index 00000000..fa12c267 --- /dev/null +++ b/devdocs/c/language%2Fvolatile.html @@ -0,0 +1,86 @@ + <h1 id="firstHeading" class="firstHeading">volatile type qualifier</h1> <p>Each individual type in the C <a href="type" title="c/language/type">type system</a> has several <i>qualified</i> versions of that type, corresponding to one, two, or all three of the <a href="const" title="c/language/const"><code>const</code></a>, <code>volatile</code>, and, for pointers to object types, <a href="restrict" title="c/language/restrict"><code>restrict</code></a> qualifiers. This page describes the effects of the <code>volatile</code> qualifier.</p> +<p>Every access (both read and write) made through an lvalue expression of volatile-qualified type is considered an observable side effect for the purpose of optimization and is evaluated strictly according to the rules of the abstract machine (that is, all writes are completed at some time before the next sequence point). This means that within a single thread of execution, a volatile access cannot be optimized out or reordered relative to another visible side effect that is separated by a <a href="eval_order" title="c/language/eval order">sequence point</a> from the volatile access.</p> +<p>A cast of a non-volatile value to a volatile type has no effect. To access a non-volatile object using volatile semantics, its address must be cast to a pointer-to-volatile and then the access must be made through that pointer.</p> +<p>Any attempt to read or write to an object whose type is volatile-qualified through a non-volatile lvalue results in undefined behavior:</p> +<div class="c source-c"><pre data-language="c">volatile int n = 1; // object of volatile-qualified type +int* p = (int*)&n; +int val = *p; // undefined behavior</pre></div> <p>A member of a volatile-qualified structure or union type acquires the qualification of the type it belongs to (both when accessed using the <code>.</code> operator or the <code>-></code> operator):</p> +<div class="c source-c"><pre data-language="c">struct s { int i; const int ci; } s; +// the type of s.i is int, the type of s.ci is const int +volatile struct s vs; +// the types of vs.i and vs.ci are volatile int and const volatile int</pre></div> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>If an array type is declared with the volatile type qualifier (through the use of <a href="typedef" title="c/language/typedef"><code>typedef</code></a>), the array type is not volatile-qualified, but its element type is.</p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td> <p>An array type and its element type are always considered to be identically volatile-qualified.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <div class="c source-c"><pre data-language="c">typedef int A[2][3]; +volatile A a = {{4, 5, 6}, {7, 8, 9}}; // array of array of volatile int +int* pi = a[0]; // Error: a[0] has type volatile int* +void *unqual_ptr = a; // OK until C23; error since C23 +// Notes: clang applies the rule in C++/C23 even in C89-C17 modes</pre></div> <p>If a function type is declared with the volatile type qualified (through the use of <a href="typedef" title="c/language/typedef"><code>typedef</code></a>), the behavior is undefined.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>In a function declaration, the keyword <code>volatile</code> may appear inside the square brackets that are used to declare an array type of a function parameter. It qualifies the pointer type to which the array type is transformed.</p> +<p>The following two declarations declare the same function:</p> +<div class="c source-c"><pre data-language="c">void f(double x[volatile], const double y[volatile]); +void f(double * volatile x, const double * volatile y);</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <p>A pointer to a non-volatile type can be implicitly converted to a pointer to the volatile-qualified version of the same or <a href="compatible_type" title="c/language/compatible type" class="mw-redirect">compatible</a> type. The reverse conversion requires a cast expression.</p> +<div class="c source-c"><pre data-language="c">int* p = 0; +volatile int* vp = p; // OK: adds qualifiers (int to volatile int) +p = vp; // Error: discards qualifiers (volatile int to int) +p = (int*)vp; // OK: cast</pre></div> <p>Note that pointer to pointer to <code>T</code> is not convertible to pointer to pointer to <code>volatile T</code>; for two types to be compatible, their qualifications must be identical:</p> +<div class="c source-c"><pre data-language="c">char *p = 0; +volatile char **vpp = &p; // Error: char* and volatile char* are not compatible types +char * volatile *pvp = &p; // OK, adds qualifiers (char* to char*volatile)</pre></div> <h3 id="Uses_of_volatile"> Uses of volatile</h3> <div class="t-li1"> +<span class="t-li">1)</span> <a href="static_storage_duration" title="c/language/static storage duration"><code>static</code></a> <code>volatile</code> objects model memory-mapped I/O ports, and <code>static</code> <code>const</code> <code>volatile</code> objects model memory-mapped input ports, such as a real-time clock: <div class="c source-c"><pre data-language="c">volatile short *ttyport = (volatile short*)TTYPORT_ADDR; +for(int i = 0; i < N; ++i) + *ttyport = a[i]; // *ttyport is an lvalue of type volatile short</pre></div> +</div> <div class="t-li1"> +<span class="t-li">2)</span> <code>static</code> <code>volatile</code> objects of type <code><a href="../program/sig_atomic_t" title="c/program/sig atomic t">sig_atomic_t</a></code> are used for communication with <code><a href="../program/signal" title="c/program/signal">signal</a></code> handlers.</div> <div class="t-li1"> +<span class="t-li">3)</span> <code>volatile</code> variables that are local to a function that contains an invocation of the <code><a href="../program/setjmp" title="c/program/setjmp">setjmp</a></code> macro are the only local variables guaranteed to retain their values after <code><a href="../program/longjmp" title="c/program/longjmp">longjmp</a></code> returns.</div> <div class="t-li1"> +<span class="t-li">4)</span> In addition, volatile variables can be used to disable certain forms of optimization, e.g. to disable dead store elimination or constant folding for micro-benchmarks.</div> <p>Note that volatile variables are not suitable for communication between threads; they do not offer atomicity, synchronization, or memory ordering. A read from a volatile variable that is modified by another thread without synchronization or concurrent modification from two unsynchronized threads is undefined behavior due to a data race.</p> +<h3 id="Keywords"> Keywords</h3> <p><a href="https://en.cppreference.com/w/cpp/keyword/volatile" title="cpp/keyword/volatile"><code>volatile</code></a></p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>demonstrates the use of volatile to disable optimizations</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <time.h> + +int main(void) +{ + clock_t t = clock(); + double d = 0.0; + for (int n = 0; n < 10000; ++n) + for (int m = 0; m < 10000; ++m) + d += d * n * m; // reads from and writes to a non-volatile + printf("Modified a non-volatile variable 100m times. " + "Time used: %.2f seconds\n", + (double)(clock() - t)/CLOCKS_PER_SEC); + + t = clock(); + volatile double vd = 0.0; + for (int n = 0; n < 10000; ++n) + for (int m = 0; m < 10000; ++m) { + double prod = vd * n * m; // reads from a volatile + vd += prod; // reads from and writes to a volatile + } + printf("Modified a volatile variable 100m times. " + "Time used: %.2f seconds\n", + (double)(clock() - t)/CLOCKS_PER_SEC); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Modified a non-volatile variable 100m times. Time used: 0.00 seconds +Modified a volatile variable 100m times. Time used: 0.79 seconds</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.7.3 Type qualifiers (p: 87-90) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.7.3 Type qualifiers (p: 121-123) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.7.3 Type qualifiers (p: 108-110) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 6.5.3 Type qualifiers </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/cv" title="cpp/language/cv">C++ documentation</a></span> for <span class=""><span>cv (<code>const</code> and <code>volatile</code>) type qualifiers</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/volatile" class="_attribution-link">https://en.cppreference.com/w/c/language/volatile</a> + </p> +</div> diff --git a/devdocs/c/language%2Fwhile.html b/devdocs/c/language%2Fwhile.html new file mode 100644 index 00000000..72920439 --- /dev/null +++ b/devdocs/c/language%2Fwhile.html @@ -0,0 +1,59 @@ + <h1 id="firstHeading" class="firstHeading">while loop</h1> <p>Executes a <span class="t-spar">statement</span> repeatedly, until the value of <span class="t-spar">expression</span> becomes equal to zero. The test takes place before each iteration.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <span class="t-spar">attr-spec-seq</span><span class="t-mark">(optional)</span> <code>while (</code> <span class="t-spar">expression</span> <code>)</code> <span class="t-spar">statement</span> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">expression</span> </td> <td> - </td> <td> any <a href="expressions" title="c/language/expressions">expression</a> of <a href="type#Type_groups" title="c/language/type">scalar type</a>. This expression is evaluated before each iteration, and if it compares equal to zero, the loop is exited. </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">statement</span> </td> <td> - </td> <td> any <a href="statements" title="c/language/statements">statement</a>, typically a compound statement, which serves as the body of the loop </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">attr-spec-seq</span> </td> <td> - </td> <td> <span class="t-mark-rev t-since-c23">(C23)</span>optional list of <a href="attributes" title="c/language/attributes">attributes</a>, applied to the loop statement </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>A <code>while</code> statement causes the <span class="t-spar">statement</span> (also called <i>the loop body</i>) to be executed repeatedly until the <span class="t-spar">expression</span> (also called <i>controlling expression</i>) compares equal to zero. The repetition occurs regardless of whether the loop body is entered normally or by a <a href="goto" title="c/language/goto">goto</a> into the middle of <span class="t-spar">statement</span>.</p> +<p>The evaluation of <span class="t-spar">expression</span> takes place before each execution of <span class="t-spar">statement</span> (unless entered by a goto). If the controlling expression needs to be evaluated after the loop body, the <a href="do" title="c/language/do">do-while loop</a> may be used.</p> +<p>If the execution of the loop needs to be terminated at some point, <a href="break" title="c/language/break"> break statement</a> can be used as a terminating statement.</p> +<p>If the execution of the loop needs to be continued at the end of the loop body, <a href="continue" title="c/language/continue"> continue statement</a> can be used as a shortcut.</p> +<p>A program with an endless loop has undefined behavior if the loop has no observable behavior (I/O, volatile accesses, atomic or synchronization operation) in any part of its <span class="t-spar">statement</span> or <span class="t-spar">expression</span>. This allows the compilers to optimize out all unobservable loops without proving that they terminate. The only exceptions are the loops where <span class="t-spar">expression</span> is a constant expression; <code>while(true)</code> is always an endless loop.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>As with all other selection and iteration statements, the while statement establishes <a href="scope" title="c/language/scope">block scope</a>: any identifier introduced in the <span class="t-spar">expression</span> goes out of scope after the <span class="t-spar">statement</span>.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>Boolean and pointer expressions are often used as loop controlling expressions. The boolean value <code>false</code> and the null pointer value of any pointer type compare equal to zero.</p> +<h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/while" title="c/keyword/while"><code>while</code></a></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> +#include <string.h> +enum { SIZE = 8 }; +int main(void) +{ + // trivial example + int array[SIZE], n = 0; + while(n < SIZE) array[n++] = rand() % 2; + puts("Array filled!"); + n = 0; + while(n < SIZE) printf("%d ", array[n++]); + printf("\n"); + + // classic strcpy() implementation + // (copies a null-terminated string from src to dst) + char src[] = "Hello, world", dst[sizeof src], *p = dst, *q = src; + while((*p++ = *q++)) // double parentheses (that are not strictly necessary) + // used to suppress warnings, ensuring that this is an + // assignment (as opposed to a comparison) by intention, + // whose result is used as a truth value + ; // null statement + puts(dst); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Array filled! +1 0 1 1 1 1 0 0 +Hello, world</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.8.5.1 The while statement (p: 109) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.8.5.1 The while statement (p: 151) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.8.5.1 The while statement (p: 136) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.6.5.1 The while statement </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/while" title="cpp/language/while">C++ documentation</a></span> for <span class=""><span><code>while</code> loop</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/while" class="_attribution-link">https://en.cppreference.com/w/c/language/while</a> + </p> +</div> diff --git a/devdocs/c/language.html b/devdocs/c/language.html new file mode 100644 index 00000000..a06d6090 --- /dev/null +++ b/devdocs/c/language.html @@ -0,0 +1,27 @@ + <h1 id="firstHeading" class="firstHeading">C language</h1> <p>This is a reference of the core C language constructs.</p> +<table> <tr valign="top"> <td> <p><b><a href="language/basic_concepts" title="c/language/basic concepts"> Basic concepts</a></b></p> +<p><a href="comment" title="c/comment"> Comments</a><br> <a href="language/ascii" title="c/language/ascii"> ASCII chart</a><br> <a href="language/charset" title="c/language/charset"> Character sets and encodings</a><br> <a href="language/translation_phases" title="c/language/translation phases"> Translation phases</a><br> <a href="language/punctuators" title="c/language/punctuators"> Punctuation</a><br> <a href="language/identifier" title="c/language/identifier"> Identifier </a> - <a href="language/scope" title="c/language/scope"> Scope</a> - <a href="language/lifetime" title="c/language/lifetime"> Lifetime</a><br> <a href="language/name_space" title="c/language/name space"> Lookup and Name Spaces</a><br> <a href="language/type" title="c/language/type"> Type</a> - <a href="language/arithmetic_types" title="c/language/arithmetic types"> Arithmetic types</a><br> <a href="language/object" title="c/language/object"> Objects and Alignment</a> <br> <a href="language/main_function" title="c/language/main function"> The <code>main</code> function</a><br> <a href="language/as_if" title="c/language/as if"> As-if rule</a><br> <a href="language/behavior" title="c/language/behavior"> Undefined behavior</a><br> <a href="language/memory_model" title="c/language/memory model"> Memory model and Data races</a><br></p> +<p><b><a href="keyword" title="c/keyword"> Keywords</a></b></p> +<p><b><a href="preprocessor" title="c/preprocessor"> Preprocessor</a></b></p> +<p><a href="preprocessor/conditional" title="c/preprocessor/conditional"> <code>#if</code> - <code>#ifdef</code> - <code>#ifndef</code> - <code>#elif</code></a><br> <a href="preprocessor/conditional" title="c/preprocessor/conditional"> <code>#elifdef</code> - <code>#elifndef</code></a><span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="preprocessor/replace" title="c/preprocessor/replace"> <code>#define</code> - <code>#</code> - <code>##</code></a><br> <a href="preprocessor/include" title="c/preprocessor/include"><code>#include</code></a> - <a href="preprocessor/impl" title="c/preprocessor/impl"><code>#pragma</code></a><br> <a href="preprocessor/line" title="c/preprocessor/line"><code>#line</code></a> - <a href="preprocessor/error" title="c/preprocessor/error"><code>#error</code></a><br> <a href="preprocessor/error" title="c/preprocessor/error"><code>#warning</code></a><span class="t-mark-rev t-since-c23">(C23)</span> - <a href="preprocessor/embed" title="c/preprocessor/embed"><code>#embed</code></a><span class="t-mark-rev t-since-c23">(C23)</span></p> +<p><b><a href="language/statements" title="c/language/statements"> Statements</a></b></p> +<p><a href="language/if" title="c/language/if"><code>if</code></a> - <a href="language/switch" title="c/language/switch"><code>switch</code></a><br> <a href="language/for" title="c/language/for"><code>for</code></a><br> <a href="language/while" title="c/language/while"><code>while</code></a> - <a href="language/do" title="c/language/do"><code>do</code>-<code>while</code></a><br> <a href="language/continue" title="c/language/continue"><code>continue</code></a> - <a href="language/break" title="c/language/break"><code>break</code></a><br> <a href="language/goto" title="c/language/goto"><code>goto</code></a> - <a href="language/return" title="c/language/return"><code>return</code></a><br></p> +</td> <td> <p><b><a href="language/expressions" title="c/language/expressions"> Expressions</a></b></p> +<p><a href="language/value_category" title="c/language/value category"> Value categories</a><br> <a href="language/eval_order" title="c/language/eval order"> Evaluation order and sequencing</a><br> <a href="language/expressions#Constants_and_literals" title="c/language/expressions"> Constants and literals</a><br> <a href="language/integer_constant" title="c/language/integer constant">Integer constants</a><br> <a href="language/floating_constant" title="c/language/floating constant">Floating constants</a><br> <a href="language/character_constant" title="c/language/character constant">Character constants</a><br> <a href="language/bool_constant" title="c/language/bool constant"><code>true</code>/<code>false</code></a><span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="language/nullptr" title="c/language/nullptr"><code>nullptr</code></a><span class="t-mark-rev t-since-c23">(C23)</span><br> <a href="language/string_literal" title="c/language/string literal">String literals</a><br> <a href="language/compound_literal" title="c/language/compound literal">Compound literals</a><span class="t-mark-rev t-since-c99">(C99)</span><br> <a href="language/constant_expression" title="c/language/constant expression"> Constant expressions</a><br> <a href="language/conversion" title="c/language/conversion"> Implicit conversions</a> <br> <a href="language/expressions#Operators" title="c/language/expressions">Operators</a><br> <a href="language/operator_member_access" title="c/language/operator member access"> Member access and indirection</a><br> <a href="language/operator_logical" title="c/language/operator logical"> Logical</a> - <a href="language/operator_comparison" title="c/language/operator comparison"> Comparison</a><br> <a href="language/operator_arithmetic" title="c/language/operator arithmetic"> Arithmetic</a> - <a href="language/operator_assignment" title="c/language/operator assignment"> Assignment</a><br> <a href="language/operator_incdec" title="c/language/operator incdec"> Increment and Decrement</a><br> <a href="language/operator_other" title="c/language/operator other"> Call, Comma, Ternary</a><br> <a href="language/sizeof" title="c/language/sizeof"><code>sizeof</code></a> - <a href="language/_alignof" title="c/language/ Alignof"><code>_Alignof</code></a><span class="t-mark-rev t-since-c11">(C11)</span><br> <a href="language/cast" title="c/language/cast"> Cast operators</a><br> <a href="language/operator_precedence" title="c/language/operator precedence"> Operator precedence</a><br> <a href="language/generic" title="c/language/generic"> Generic selection</a><span class="t-mark-rev t-since-c11">(C11)</span><br></p> +<p><b><a href="language/initialization" title="c/language/initialization"> Initialization</a></b></p> +<p><a href="language/scalar_initialization" title="c/language/scalar initialization"> Scalar</a><br> <a href="language/array_initialization" title="c/language/array initialization"> Array</a><br> <a href="language/struct_initialization" title="c/language/struct initialization"> Structure/Union </a><br></p> +</td> <td> <p><b><a href="language/declarations" title="c/language/declarations"> Declarations</a></b></p> +<p><a href="language/pointer" title="c/language/pointer"> Pointers</a> - <a href="language/array" title="c/language/array"> Arrays</a><br> <a href="language/enum" title="c/language/enum"> Enumerations</a><br> <a href="language/storage_duration" title="c/language/storage duration"> Storage duration and Linkage </a><br> <a href="language/const" title="c/language/const"><code>const</code></a> - <a href="language/volatile" title="c/language/volatile"><code>volatile</code></a> - <a href="language/restrict" title="c/language/restrict"><code>restrict</code></a><span class="t-mark-rev t-since-c99">(C99)</span><br> <a href="language/struct" title="c/language/struct"><code>struct</code></a> - <a href="language/union" title="c/language/union"><code>union</code></a> - <a href="language/bit_field" title="c/language/bit field"> Bit-fields</a><br> <a href="language/_alignas" title="c/language/ Alignas"><code>_Alignas</code></a><span class="t-mark-rev t-since-c11">(C11)</span> - <a href="language/typedef" title="c/language/typedef"><code>typedef</code></a><br> <a href="language/_static_assert" title="c/language/ Static assert"><code>_Static_assert</code></a><span class="t-mark-rev t-since-c11">(C11)</span><br> <a href="language/atomic" title="c/language/atomic"> Atomic types</a><span class="t-mark-rev t-since-c11">(C11)</span><br> <a href="language/extern" title="c/language/extern"> External and tentative definitions</a><br> <a href="language/attributes" title="c/language/attributes"> Attributes</a><span class="t-mark-rev t-since-c23">(C23)</span><br></p> +<p><b><a href="language/functions" title="c/language/functions"> Functions</a></b></p> +<p><a href="language/function_declaration" title="c/language/function declaration"> Function declaration</a><br> <a href="language/function_definition" title="c/language/function definition"> Function definition</a><br> <a href="language/inline" title="c/language/inline"><code>inline</code></a><span class="t-mark-rev t-since-c99">(C99)</span><br> <a href="language/_noreturn" title="c/language/ Noreturn"><code>_Noreturn</code></a><span class="t-mark-rev t-since-c11">(C11)</span><span class="t-mark-rev t-deprecated-c23">(deprecated in C23)</span><br> <a href="language/variadic" title="c/language/variadic"> Variadic arguments</a><br></p> +<p><b>Miscellaneous</b></p> +<p><a href="language/history" title="c/language/history"> History of C</a><br> <a href="language/conformance" title="c/language/conformance"> Conformance</a><br> <a href="language/asm" title="c/language/asm"> Inline assembly</a><br> <a href="https://en.cppreference.com/mwiki/index.php?title=c/language/signal&action=edit&redlink=1" class="new" title="c/language/signal (page does not exist)"> Signal handling</a> <br> <a href="language/analyzability" title="c/language/analyzability"> Analyzability</a><span class="t-mark-rev t-since-c11">(C11)</span><br></p> +<br> </td> +</tr> +</table> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language" title="cpp/language">C++ documentation</a></span> for <span class=""><span>C++ language constructs</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language" class="_attribution-link">https://en.cppreference.com/w/c/language</a> + </p> +</div> diff --git a/devdocs/c/locale%2Flc_categories.html b/devdocs/c/locale%2Flc_categories.html new file mode 100644 index 00000000..a4a55fb5 --- /dev/null +++ b/devdocs/c/locale%2Flc_categories.html @@ -0,0 +1,50 @@ + <h1 id="firstHeading" class="firstHeading">LC_ALL, LC_COLLATE, LC_CTYPE, LC_MONETARY, LC_NUMERIC, LC_TIME</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><locale.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define LC_ALL /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define LC_COLLATE /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define LC_CTYPE /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define LC_MONETARY /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define LC_NUMERIC /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define LC_TIME /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Each of the above macro constants expand to integer constant expressions with distinct values that are suitable for use as the first argument of <code><a href="setlocale" title="c/locale/setlocale">setlocale</a></code>.</p> +<table class="t-dsc-begin"> <tr class="t-dsc-hitem"> <th> Constant </th> <th> Explanation </th> +</tr> <tr class="t-dsc"> <td> <code>LC_ALL</code> </td> <td> selects the entire C locale </td> +</tr> <tr class="t-dsc"> <td> <code>LC_COLLATE</code> </td> <td> selects the collation category of the C locale </td> +</tr> <tr class="t-dsc"> <td> <code>LC_CTYPE</code> </td> <td> selects the character classification category of the C locale </td> +</tr> <tr class="t-dsc"> <td> <code>LC_MONETARY</code> </td> <td> selects the monetary formatting category of the C locale </td> +</tr> <tr class="t-dsc"> <td> <code>LC_NUMERIC</code> </td> <td> selects the numeric formatting category of the C locale </td> +</tr> <tr class="t-dsc"> <td> <code>LC_TIME</code> </td> <td> selects the time formatting category of the C locale </td> +</tr> </table> <p>Additional macro constants, with names that begin with <code>LC_</code> followed by at least one uppercase letter, may be defined in <code>locale.h</code>. For example, the POSIX specification requires <code>LC_MESSAGES</code> (which controls, among other things, <code><a href="../io/perror" title="c/io/perror">perror</a></code> and <code><a href="../string/byte/strerror" title="c/string/byte/strerror">strerror</a></code>), ISO/IEC 30112:2014 (<a rel="nofollow" class="external text" href="https://www.open-std.org/JTC1/SC35/WG5/docs/30112d10.pdf">2014 draft</a>) additionally defines <code>LC_IDENTIFICATION</code>, <code>LC_XLITERATE</code>, <code>LC_NAME</code>, <code>LC_ADDRESS</code>, <code>LC_TELEPHONE</code>, <code>LC_PAPER</code>, <code>LC_MEASUREMENT</code>, and <code>LC_KEYBOARD</code>, which are supported by the GNU C library (except for <code>LC_XLITERATE</code>).</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <time.h> +#include <wchar.h> + +int main(void) +{ + setlocale(LC_ALL, "en_US.UTF-8"); // the C locale will be the UTF-8 enabled English + setlocale(LC_NUMERIC, "de_DE.utf8"); // decimal dot will be German + setlocale(LC_TIME, "ja_JP.utf8"); // date/time formatting will be Japanese + wchar_t str[100]; + time_t t = time(NULL); + wcsftime(str, 100, L"%A %c", localtime(&t)); + wprintf(L"Number: %.2f\nDate: %Ls\n", 3.14, str); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Number: 3,14 +Date: 金曜日 2023年09月15日 20時04分14秒</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.11/3 Localization <locale.h> (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.11/3 Localization <locale.h> (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.11/3 Localization <locale.h> (p: 224) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.11/3 Localization <locale.h> (p: 205) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.4 LOCALIZATION <locale.h> </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="setlocale" title="c/locale/setlocale"> <span class="t-lines"><span>setlocale</span></span></a></div> </td> <td> gets and sets the current C locale <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/locale/LC_categories" title="cpp/locale/LC categories">C++ documentation</a></span> for <span class=""><span>locale categories</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/locale/LC_categories" class="_attribution-link">https://en.cppreference.com/w/c/locale/LC_categories</a> + </p> +</div> diff --git a/devdocs/c/locale%2Flconv.html b/devdocs/c/locale%2Flconv.html new file mode 100644 index 00000000..1194b651 --- /dev/null +++ b/devdocs/c/locale%2Flconv.html @@ -0,0 +1,71 @@ + <h1 id="firstHeading" class="firstHeading">lconv</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><locale.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">struct lconv;</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>The struct <code>lconv</code> contains numeric and monetary formatting rules as defined by a C locale. Objects of this struct may be obtained with <code><a href="localeconv" title="c/locale/localeconv">localeconv</a></code>. The members of <code>lconv</code> are values of type <code>char</code> and of type <code>char*</code>. Each <code>char*</code> member except <code>decimal_point</code> may be pointing at a null character (that is, at an empty C-string). The members of type <code>char</code> are all non-negative numbers, any of which may be <code><a href="../types/limits" title="c/types/limits">CHAR_MAX</a></code> if the corresponding value is not available in the current C locale.</p> +<h3 id="Member_objects"> Member objects</h3> <h4 id="Non-monetary_numeric_formatting_parameters"> Non-monetary numeric formatting parameters</h4> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char*</span> decimal_point</span></span></div> </td> <td> the character used as the decimal point <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char*</span> thousands_sep</span></span></div> </td> <td> the character used to separate groups of digits before the decimal point <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char*</span> grouping</span></span></div> </td> <td> a string whose elements indicate the sizes of digit groups <br> <span class="t-mark">(public member object)</span> </td> +</tr> </table> <h4 id="Monetary_numeric_formatting_parameters"> Monetary numeric formatting parameters</h4> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char*</span> mon_decimal_point</span></span></div> </td> <td> the character used as the decimal point <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char*</span> mon_thousands_sep</span></span></div> </td> <td> the character used to separate groups of digits before the decimal point <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char*</span> mon_grouping</span></span></div> </td> <td> a string whose elements indicate the sizes of digit groups <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char*</span> positive_sign</span></span></div> </td> <td> a string used to indicate non-negative monetary quantity <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char*</span> negative_sign</span></span></div> </td> <td> a string used to indicate negative monetary quantity <br> <span class="t-mark">(public member object)</span> </td> +</tr> </table> <h4 id="Local_monetary_numeric_formatting_parameters"> Local monetary numeric formatting parameters</h4> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char*</span> currency_symbol</span></span></div> </td> <td> the symbol used for currency in the current C locale <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char</span> frac_digits</span></span></div> </td> <td> the number of digits after the decimal point to display in a monetary quantity <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char</span> p_cs_precedes</span></span></div> </td> <td> <code>1</code> if currency_symbol is placed before non-negative value, <code>0</code> if after <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char</span> n_cs_precedes</span></span></div> </td> <td> <code>1</code> if currency_symbol is placed before negative value, <code>0</code> if after <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char</span> p_sep_by_space</span></span></div> </td> <td> indicates the separation of <code>currency_symbol</code>, <code>positive_sign</code>, and the non-negative monetary value <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char</span> n_sep_by_space</span></span></div> </td> <td> indicates the separation of <code>currency_symbol</code>, <code>negative_sign</code>, and the negative monetary value <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char</span> p_sign_posn</span></span></div> </td> <td> indicates the position of <code>positive_sign</code> in a non-negative monetary value <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char</span> n_sign_posn</span></span></div> </td> <td> indicates the position of <code>negative_sign</code> in a negative monetary value <br> <span class="t-mark">(public member object)</span> </td> +</tr> </table> <h4 id="International_monetary_numeric_formatting_parameters"> International monetary numeric formatting parameters</h4> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char*</span> int_curr_symbol</span></span></div> </td> <td> the string used as international currency name in the current C locale <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char</span> int_frac_digits</span></span></div> </td> <td> the number of digits after the decimal point to display in an international monetary quantity <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char</span> int_p_cs_precedes</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> <code>1</code> if int_curr_symbol is placed before non-negative international monetary value, <code>0</code> if after <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char</span> int_n_cs_precedes</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> <code>1</code> if int_curr_symbol is placed before negative international monetary value, <code>0</code> if after <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char</span> int_p_sep_by_space</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> indicates the separation of <code>int_curr_symbol</code>, <code>positive_sign</code>, and the non-negative international monetary value <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char</span> int_n_sep_by_space</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> indicates the separation of <code>int_curr_symbol</code>, <code>negative_sign</code>, and the negative international monetary value <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char</span> int_p_sign_posn</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> indicates the position of <code>positive_sign</code> in a non-negative international monetary value <br> <span class="t-mark">(public member object)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><span class="t-dsc-small">char</span> int_n_sign_posn</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> indicates the position of <code>negative_sign</code> in a negative international monetary value <br> <span class="t-mark">(public member object)</span> </td> +</tr> </table> <p><br> The characters of the C-strings pointed to by <code>grouping</code> and <code>mon_grouping</code> are interpreted according to their numeric values. When the terminating <code>'\0'</code> is encountered, the last value seen is assumed to repeat for the remainder of digits. If <code><a href="../types/limits" title="c/types/limits">CHAR_MAX</a></code> is encountered, no further digits are grouped. The typical grouping of three digits at a time is <code>"\003"</code>.</p> +<p>The values of <code>p_sep_by_space</code>, <code>n_sep_by_space</code>, <code>int_p_sep_by_space</code>, <code>int_n_sep_by_space</code> are interpreted as follows:</p> +<table class="t-dsc-begin"> <tr class="t-dsc"> <td> 0 </td> <td> no space separates the currency symbol and the value </td> +</tr> <tr class="t-dsc"> <td> 1 </td> <td> sign sticks to the currency symbol, value is separated by a space </td> +</tr> <tr class="t-dsc"> <td> 2 </td> <td> sign sticks to the value. Currency symbol is separated by a space </td> +</tr> </table> <p>The values of <code>p_sign_posn</code>, <code>n_sign_posn</code>, <code>int_p_sign_posn</code>, <code>int_n_sign_posn</code> are interpreted as follows:</p> +<table class="t-dsc-begin"> <tr class="t-dsc"> <td> 0 </td> <td> parentheses around the value and the currency symbol are used to represent the sign </td> +</tr> <tr class="t-dsc"> <td> 1 </td> <td> sign before the value and the currency symbol </td> +</tr> <tr class="t-dsc"> <td> 2 </td> <td> sign after the value and the currency symbol </td> +</tr> <tr class="t-dsc"> <td> 3 </td> <td> sign before the currency symbol </td> +</tr> <tr class="t-dsc"> <td> 4 </td> <td> sign after the currency symbol </td> +</tr> </table> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> + +int main(void) +{ + setlocale(LC_ALL, "ja_JP.UTF-8"); + struct lconv *lc = localeconv(); + printf("Japanese currency symbol: %s(%s)\n", lc->currency_symbol, lc->int_curr_symbol); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Japanese currency symbol: ￥(JPY )</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.11/2 Localization <locale.h> (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.11/2 Localization <locale.h> (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.11/2 Localization <locale.h> (p: 223) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.11/2 Localization <locale.h> (p: 204) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.4 LOCALIZATION <locale.h> </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="localeconv" title="c/locale/localeconv"> <span class="t-lines"><span>localeconv</span></span></a></div> </td> <td> queries numeric and monetary formatting details of the current locale <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/locale/lconv" title="cpp/locale/lconv">C++ documentation</a></span> for <code>lconv</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/locale/lconv" class="_attribution-link">https://en.cppreference.com/w/c/locale/lconv</a> + </p> +</div> diff --git a/devdocs/c/locale%2Flocaleconv.html b/devdocs/c/locale%2Flocaleconv.html new file mode 100644 index 00000000..d4222e7d --- /dev/null +++ b/devdocs/c/locale%2Flocaleconv.html @@ -0,0 +1,33 @@ + <h1 id="firstHeading" class="firstHeading">localeconv</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><locale.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">struct lconv *localeconv(void);</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>The <code>localeconv</code> function obtains a pointer to a static object of type <code><a href="lconv" title="c/locale/lconv">lconv</a></code>, which represents numeric and monetary formatting rules of the current C locale.</p> +<h3 id="Parameters"> Parameters</h3> <p>(none)</p> +<h3 id="Return_value"> Return value</h3> <p>pointer to the current <code><a href="lconv" title="c/locale/lconv">lconv</a></code> object.</p> +<h3 id="Notes"> Notes</h3> <p>Modifying the object references through the returned pointer is undefined behavior.</p> +<p><code>localeconv</code> modifies a static object, calling it from different threads without synchronization is undefined behavior.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <locale.h> + +int main(void) +{ + setlocale(LC_MONETARY, "en_IN.utf8"); + struct lconv *lc = localeconv(); + printf("Local Currency Symbol : %s\n", lc->currency_symbol); + printf("International Currency Symbol: %s\n", lc->int_curr_symbol); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Local Currency Symbol : ₹ +International Currency Symbol: INR</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.11.2.1 The localeconv function (p: 225-230) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.11.2.1 The localeconv function (p: 206-211) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.4.2.1 The localeconv function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="setlocale" title="c/locale/setlocale"> <span class="t-lines"><span>setlocale</span></span></a></div> </td> <td> gets and sets the current C locale <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="lconv" title="c/locale/lconv"> <span class="t-lines"><span>lconv</span></span></a></div> </td> <td> formatting details, returned by <code>localeconv</code> <br><span class="t-mark">(struct)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/locale/localeconv" title="cpp/locale/localeconv">C++ documentation</a></span> for <code>localeconv</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/locale/localeconv" class="_attribution-link">https://en.cppreference.com/w/c/locale/localeconv</a> + </p> +</div> diff --git a/devdocs/c/locale%2Fsetlocale.html b/devdocs/c/locale%2Fsetlocale.html new file mode 100644 index 00000000..23244989 --- /dev/null +++ b/devdocs/c/locale%2Fsetlocale.html @@ -0,0 +1,49 @@ + <h1 id="firstHeading" class="firstHeading">setlocale</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><locale.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">char* setlocale( int category, const char* locale );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>The <code>setlocale</code> function installs the specified system locale or its portion as the new C locale. The modifications remain in effect and influences the execution of all locale-sensitive C library functions until the next call to <code>setlocale</code>. If <code>locale</code> is a null pointer, <code>setlocale</code> queries the current C locale without modifying it.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> category </td> <td> - </td> <td> locale category identifier, one of the <a href="lc_categories" title="c/locale/LC categories">LC_xxx</a> macros. May be null. </td> +</tr> <tr class="t-par"> <td> locale </td> <td> - </td> <td> system-specific locale identifier. Can be <code>""</code> for the user-preferred locale or <code>"C"</code> for the minimal locale </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>pointer to a narrow null-terminated string identifying the C locale after applying the changes, if any, or null pointer on failure.</p> +<p>A copy of the returned string along with the category used in this call to <code>setlocale</code> may be used later in the program to restore the locale back to the state at the end of this call.</p> +<h3 id="Notes"> Notes</h3> <p>During program startup, the equivalent of <code>setlocale<span class="br0">(</span><a href="http://en.cppreference.com/w/c/locale/LC_categories"><span class="kw903">LC_ALL</span></a>, <span class="st0">"C"</span><span class="br0">)</span><span class="sy4">;</span></code> is executed before any user code is run.</p> +<p>Although the return type is <code>char*</code>, modifying the pointed-to characters is undefined behavior.</p> +<p>Because <code>setlocale</code> modifies global state which affects execution of locale-dependent functions, it is undefined behavior to call it from one thread, while another thread is executing any of the following functions: <code><a href="../io/fprintf" title="c/io/fprintf">fprintf</a></code>, <code><a href="../string/byte/isprint" title="c/string/byte/isprint">isprint</a></code>, <code><a href="../string/wide/iswdigit" title="c/string/wide/iswdigit">iswdigit</a></code>, <code><a href="localeconv" title="c/locale/localeconv">localeconv</a></code>, <code><a href="../string/byte/tolower" title="c/string/byte/tolower">tolower</a></code>, <code><a href="../io/fscanf" title="c/io/fscanf">fscanf</a></code>, <code><a href="../string/byte/ispunct" title="c/string/byte/ispunct">ispunct</a></code>, <code><a href="../string/wide/iswgraph" title="c/string/wide/iswgraph">iswgraph</a></code>, <code><a href="../string/multibyte/mblen" title="c/string/multibyte/mblen">mblen</a></code>, <code><a href="../string/byte/toupper" title="c/string/byte/toupper">toupper</a></code>, <code><a href="../string/byte/isalnum" title="c/string/byte/isalnum">isalnum</a></code>, <code><a href="../string/byte/isspace" title="c/string/byte/isspace">isspace</a></code>, <code><a href="../string/wide/iswlower" title="c/string/wide/iswlower">iswlower</a></code>, <code><a href="../string/multibyte/mbstowcs" title="c/string/multibyte/mbstowcs">mbstowcs</a></code>, <code><a href="../string/wide/towlower" title="c/string/wide/towlower">towlower</a></code>, <code><a href="../string/byte/isalpha" title="c/string/byte/isalpha">isalpha</a></code>, <code><a href="../string/byte/isupper" title="c/string/byte/isupper">isupper</a></code>, <code><a href="../string/wide/iswprint" title="c/string/wide/iswprint">iswprint</a></code>, <code><a href="../string/multibyte/mbtowc" title="c/string/multibyte/mbtowc">mbtowc</a></code>, <code><a href="../string/wide/towupper" title="c/string/wide/towupper">towupper</a></code>, <code><a href="../string/byte/isblank" title="c/string/byte/isblank">isblank</a></code>, <code><a href="../string/wide/iswalnum" title="c/string/wide/iswalnum">iswalnum</a></code>, <code><a href="../string/wide/iswpunct" title="c/string/wide/iswpunct">iswpunct</a></code>, <code>setlocale</code>, <code><a href="../string/wide/wcscoll" title="c/string/wide/wcscoll">wcscoll</a></code>, <code><a href="../string/byte/iscntrl" title="c/string/byte/iscntrl">iscntrl</a></code>, <code><a href="../string/wide/iswalpha" title="c/string/wide/iswalpha">iswalpha</a></code>, <code><a href="../string/wide/iswspace" title="c/string/wide/iswspace">iswspace</a></code>, <code><a href="../string/byte/strcoll" title="c/string/byte/strcoll">strcoll</a></code>, <code><a href="../string/wide/wcstof" title="c/string/wide/wcstof">wcstod</a></code>, <code><a href="../string/byte/isdigit" title="c/string/byte/isdigit">isdigit</a></code>, <code><a href="../string/wide/iswblank" title="c/string/wide/iswblank">iswblank</a></code>, <code><a href="../string/wide/iswupper" title="c/string/wide/iswupper">iswupper</a></code>, <code><a href="../string/byte/strerror" title="c/string/byte/strerror">strerror</a></code>, <code><a href="../string/multibyte/wcstombs" title="c/string/multibyte/wcstombs">wcstombs</a></code>, <code><a href="../string/byte/isgraph" title="c/string/byte/isgraph">isgraph</a></code>, <code><a href="../string/wide/iswcntrl" title="c/string/wide/iswcntrl">iswcntrl</a></code>, <code><a href="../string/wide/iswxdigit" title="c/string/wide/iswxdigit">iswxdigit</a></code>, <code><a href="../string/byte/strtof" title="c/string/byte/strtof">strtod</a></code>, <code><a href="../string/wide/wcsxfrm" title="c/string/wide/wcsxfrm">wcsxfrm</a></code>, <code><a href="../string/byte/islower" title="c/string/byte/islower">islower</a></code>, <code><a href="../string/wide/iswctype" title="c/string/wide/iswctype">iswctype</a></code>, <code><a href="../string/byte/isxdigit" title="c/string/byte/isxdigit">isxdigit</a></code>.</p> +<p>POSIX also defines a locale named "POSIX", which is always accessible and is exactly equivalent to the default minimal "C" locale.</p> +<p>POSIX also specifies that the returned pointer, not just the contents of the pointed-to string, may be invalidated by subsequent calls to <code>setlocale</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <locale.h> +#include <time.h> +#include <wchar.h> + +int main(void) +{ + // the C locale will be UTF-8 enabled English; + // decimal dot will be German + // date and time formatting will be Japanese + setlocale(LC_ALL, "en_US.UTF-8"); + setlocale(LC_NUMERIC, "de_DE.utf8"); + setlocale(LC_TIME, "ja_JP.utf8"); + + wchar_t str[100]; + time_t t = time(NULL); + wcsftime(str, 100, L"%A %c", localtime(&t)); + wprintf(L"Number: %.2f\nDate: %ls\n", 3.14, str); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Number: 3,14 +Date: 月曜日 2017年09月25日 13時00分15秒</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.11.1.1 The setlocale function (p: 163-164) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.11.1.1 The setlocale function (p: 224-225) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.11.1.1 The setlocale function (p: 205-206) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.4.1.1 The setlocale function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="lc_categories" title="c/locale/LC categories"> <span class="t-lines"><span>LC_ALL</span><span>LC_COLLATE</span><span>LC_CTYPE</span><span>LC_MONETARY</span><span>LC_NUMERIC</span><span>LC_TIME</span></span></a></div> </td> <td> locale categories for <code>setlocale</code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/locale/setlocale" title="cpp/locale/setlocale">C++ documentation</a></span> for <code>setlocale</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/locale/setlocale" class="_attribution-link">https://en.cppreference.com/w/c/locale/setlocale</a> + </p> +</div> diff --git a/devdocs/c/locale.html b/devdocs/c/locale.html new file mode 100644 index 00000000..5fd68956 --- /dev/null +++ b/devdocs/c/locale.html @@ -0,0 +1,29 @@ + <h1 id="firstHeading" class="firstHeading">Localization support</h1> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><locale.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="locale/setlocale" title="c/locale/setlocale"> <span class="t-lines"><span>setlocale</span></span></a></div> </td> <td> gets and sets the current C locale <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="locale/localeconv" title="c/locale/localeconv"> <span class="t-lines"><span>localeconv</span></span></a></div> </td> <td> queries numeric and monetary formatting details of the current locale <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="locale/lconv" title="c/locale/lconv"> <span class="t-lines"><span>lconv</span></span></a></div> </td> <td> formatting details, returned by <code><a href="http://en.cppreference.com/w/c/locale/localeconv"><span class="kw902">localeconv</span></a></code> <br><span class="t-mark">(struct)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Locale_categories"> Locale categories </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="locale/lc_categories" title="c/locale/LC categories"> <span class="t-lines"><span>LC_ALL</span><span>LC_COLLATE</span><span>LC_CTYPE</span><span>LC_MONETARY</span><span>LC_NUMERIC</span><span>LC_TIME</span></span></a></div> </td> <td> locale categories for <code><a href="http://en.cppreference.com/w/c/locale/setlocale"><span class="kw901">setlocale</span></a></code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.11 Localization <locale.h> (p: 223-230) </li> +<li> 7.31.6 Localization <locale.h> (p: 455) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.11 Localization <locale.h> (p: 204-211) </li> +<li> 7.26.5 Localization <locale.h> (p: 401) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 4.4 LOCALIZATION <locale.h> </li> +<li> 4.13.3 Localization <locale.h> </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/locale" title="cpp/locale">C++ documentation</a></span> for <span class=""><span>Localization library</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/locale" class="_attribution-link">https://en.cppreference.com/w/c/locale</a> + </p> +</div> diff --git a/devdocs/c/memory%2Faligned_alloc.html b/devdocs/c/memory%2Faligned_alloc.html new file mode 100644 index 00000000..839438f0 --- /dev/null +++ b/devdocs/c/memory%2Faligned_alloc.html @@ -0,0 +1,42 @@ + <h1 id="firstHeading" class="firstHeading">aligned_alloc</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">void *aligned_alloc( size_t alignment, size_t size );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Allocate <code>size</code> bytes of uninitialized storage whose alignment is specified by <code>alignment</code>. The <code>size</code> parameter must be an integral multiple of <code>alignment</code>.</p> +<p><code>aligned_alloc</code> is thread-safe: it behaves as though only accessing the memory locations visible through its argument, and not any static storage.</p> +<p>A previous call to <code><a href="free" title="c/memory/free">free</a></code> or <code><a href="realloc" title="c/memory/realloc">realloc</a></code> that deallocates a region of memory <i>synchronizes-with</i> a call to <code>aligned_alloc</code> that allocates the same or a part of the same region of memory. This synchronization occurs after any access to the memory by the deallocating function and before any access to the memory by <code>aligned_alloc</code>. There is a single total order of all allocation and deallocation functions operating on each particular region of memory.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> alignment </td> <td> - </td> <td> specifies the alignment. Must be a valid alignment supported by the implementation. </td> +</tr> <tr class="t-par"> <td> size </td> <td> - </td> <td> number of bytes to allocate. An integral multiple of <code>alignment</code> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>On success, returns the pointer to the beginning of newly allocated memory. To avoid a memory leak, the returned pointer must be deallocated with <code><a href="free" title="c/memory/free">free</a></code> or <code><a href="realloc" title="c/memory/realloc">realloc</a></code>.</p> +<p>On failure, returns a null pointer.</p> +<h3 id="Notes"> Notes</h3> <p>Passing a <code>size</code> which is not an integral multiple of <code>alignment</code> or an <code>alignment</code> which is not valid or not supported by the implementation causes the function to fail and return a null pointer (C11, as published, specified undefined behavior in this case, this was corrected by <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/summary.htm#dr_460">DR460</a>). Removal of size restrictions to make it possible to allocate small objects at restrictive alignment boundaries (similar to <a href="../language/_alignas" title="c/language/ Alignas"><code>alignas</code></a>) has been proposed by <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2072.htm">N2072</a>.</p> +<p>As an example of the "supported by the implementation" requirement, POSIX function <a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/posix_memalign.html"><code>posix_memalign</code></a> accepts any <code>alignment</code> that is a power of two and a multiple of <code>sizeof(void *)</code>, and POSIX-based implementations of <code>aligned_alloc</code> inherit this requirements.</p> +<p>Fundamental alignments are always supported. If <code>alignment</code> is a power of two and not greater than <code>_Alignof<span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/max_align_t"><span class="kw104">max_align_t</span></a><span class="br0">)</span></code>, <code>aligned_alloc</code> may simply call <code><a href="malloc" title="c/memory/malloc">malloc</a></code>.</p> +<p>Regular <code><a href="malloc" title="c/memory/malloc">malloc</a></code> aligns memory suitable for any object type with a fundamental alignment. The <code>aligned_alloc</code> is useful for over-aligned allocations, such as to <a href="https://en.wikipedia.org/wiki/Streaming_SIMD_Extensions" class="extiw" title="enwiki:Streaming SIMD Extensions">SSE</a>, cache line, or <a href="https://en.wikipedia.org/wiki/Page_(computer_memory)#Multiple_page_sizes" class="extiw" title="enwiki:Page (computer memory)">VM page</a> boundary.</p> +<p>This function is not supported in Microsoft C Runtime library because its implementation of <code>std::free</code> is <a rel="nofollow" class="external text" href="https://learn.microsoft.com/en-us/cpp/standard-library/cstdlib#remarks-6">unable to handle aligned allocations</a> of any kind. Instead, MS CRT provides <a rel="nofollow" class="external text" href="https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/aligned-malloc"><code>_aligned_malloc</code></a> (to be freed with <a rel="nofollow" class="external text" href="https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/aligned-free"><code>_aligned_free</code></a>).</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + int *p1 = malloc(10*sizeof *p1); + printf("default-aligned addr: %p\n", (void*)p1); + free(p1); + + int *p2 = aligned_alloc(1024, 1024*sizeof *p2); + printf("1024-byte aligned addr: %p\n", (void*)p2); + free(p2); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">default-aligned addr: 0x1e40c20 +1024-byte aligned addr: 0x1e41000</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.22.3.1 The aligned_alloc function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22.3.1 The aligned_alloc function (p: 253) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.3.1 The aligned_alloc function (p: 347-348) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/memory/c/aligned_alloc" title="cpp/memory/c/aligned alloc">C++ documentation</a></span> for <code>aligned_alloc</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/memory/aligned_alloc" class="_attribution-link">https://en.cppreference.com/w/c/memory/aligned_alloc</a> + </p> +</div> diff --git a/devdocs/c/memory%2Fcalloc.html b/devdocs/c/memory%2Fcalloc.html new file mode 100644 index 00000000..4c0abf87 --- /dev/null +++ b/devdocs/c/memory%2Fcalloc.html @@ -0,0 +1,62 @@ + <h1 id="firstHeading" class="firstHeading">calloc</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">void* calloc( size_t num, size_t size );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Allocates memory for an array of <code>num</code> objects of <code>size</code> and initializes all bytes in the allocated storage to zero.</p> +<p>If allocation succeeds, returns a pointer to the lowest (first) byte in the allocated memory block that is suitably aligned for any object type with <a href="../language/object#Alignment" title="c/language/object">fundamental alignment</a>.</p> +<p>If <code>size</code> is zero, the behavior is implementation defined (null pointer may be returned, or some non-null pointer may be returned that may not be used to access storage).</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <p><code>calloc</code> is thread-safe: it behaves as though only accessing the memory locations visible through its argument, and not any static storage.</p> +<p>A previous call to <code><a href="free" title="c/memory/free">free</a></code> or <code><a href="realloc" title="c/memory/realloc">realloc</a></code> that deallocates a region of memory <i>synchronizes-with</i> a call to <code>calloc</code> that allocates the same or a part of the same region of memory. This synchronization occurs after any access to the memory by the deallocating function and before any access to the memory by <code>calloc</code>. There is a single total order of all allocation and deallocation functions operating on each particular region of memory.</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> num </td> <td> - </td> <td> number of objects </td> +</tr> <tr class="t-par"> <td> size </td> <td> - </td> <td> size of each object </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>On success, returns the pointer to the beginning of newly allocated memory. To avoid a memory leak, the returned pointer must be deallocated with <code><a href="free" title="c/memory/free">free()</a></code> or <code><a href="realloc" title="c/memory/realloc">realloc()</a></code>.</p> +<p>On failure, returns a null pointer.</p> +<h3 id="Notes"> Notes</h3> <p>Due to the alignment requirements, the number of allocated bytes is not necessarily equal to <code>num * size</code>.</p> +<p>Initialization to all bits zero does not guarantee that a floating-point or a pointer would be initialized to <span class="nu16">0.0</span> and the null pointer value, respectively (although that is true on all common platforms).</p> +<p>Originally (in C89), support for zero size was added to accommodate code such as</p> +<div class="c source-c"><pre data-language="c">OBJ* p = calloc(0, sizeof(OBJ)); // "zero-length" placeholder +... +while(1) +{ + p = realloc(p, c * sizeof(OBJ)); // reallocations until size settles + ... // code that may change c or break out of loop +}</pre></div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + int* p1 = calloc(4, sizeof(int)); // allocate and zero out an array of 4 int + int* p2 = calloc(1, sizeof(int[4])); // same, naming the array type directly + int* p3 = calloc(4, sizeof *p3); // same, without repeating the type name + + if (p2) + { + for (int n = 0; n < 4; ++n) // print the array + printf("p2[%d] == %d\n", n, p2[n]); + } + + free(p1); + free(p2); + free(p3); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">p2[0] == 0 +p2[1] == 0 +p2[2] == 0 +p2[3] == 0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.22.3.2 The calloc function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22.3.2 The calloc function (p: 253) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.3.2 The calloc function (p: 348) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.3.1 The calloc function (p: 313) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.3.1 The calloc function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/memory/c/calloc" title="cpp/memory/c/calloc">C++ documentation</a></span> for <code>calloc</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/memory/calloc" class="_attribution-link">https://en.cppreference.com/w/c/memory/calloc</a> + </p> +</div> diff --git a/devdocs/c/memory%2Ffree.html b/devdocs/c/memory%2Ffree.html new file mode 100644 index 00000000..47298dbf --- /dev/null +++ b/devdocs/c/memory%2Ffree.html @@ -0,0 +1,50 @@ + <h1 id="firstHeading" class="firstHeading">free</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">void free( void *ptr );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Deallocates the space previously allocated by <code><a href="malloc" title="c/memory/malloc">malloc()</a></code>, <code><a href="calloc" title="c/memory/calloc">calloc()</a></code><span class="t-rev-inl t-since-c11"><span>, <code>aligned_alloc()</code>,</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> or <code><a href="realloc" title="c/memory/realloc">realloc()</a></code>.</p> +<p>If <code>ptr</code> is a null pointer, the function does nothing.</p> +<p>The behavior is undefined if the value of <code>ptr</code> does not equal a value returned earlier by <code><a href="malloc" title="c/memory/malloc">malloc()</a></code>, <code><a href="calloc" title="c/memory/calloc">calloc()</a></code>, <code><a href="realloc" title="c/memory/realloc">realloc()</a></code><span class="t-rev-inl t-since-c11"><span>, or <code>aligned_alloc()</code></span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span>.</p> +<p>The behavior is undefined if the memory area referred to by <code>ptr</code> has already been deallocated, that is, <code>free()</code><span class="t-rev-inl t-since-c23"><span>, <code>free_sized()</code>, <code>free_aligned_sized()</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, or <code><a href="realloc" title="c/memory/realloc">realloc()</a></code> has already been called with <code>ptr</code> as the argument and no calls to <code><a href="malloc" title="c/memory/malloc">malloc()</a></code>, <code><a href="calloc" title="c/memory/calloc">calloc()</a></code>, <code><a href="realloc" title="c/memory/realloc">realloc()</a></code><span class="t-rev-inl t-since-c11"><span>, or <code>aligned_alloc()</code></span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> resulted in a pointer equal to <code>ptr</code> afterwards.</p> +<p>The behavior is undefined if after <code>free()</code> returns, an access is made through the pointer <code>ptr</code> (unless another allocation function happened to result in a pointer value equal to <code>ptr</code>).</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <p><code>free</code> is thread-safe: it behaves as though only accessing the memory locations visible through its argument, and not any static storage.</p> +<p>A call to <code>free</code> that deallocates a region of memory <i>synchronizes-with</i> a call to any subsequent allocation function that allocates the same or a part of the same region of memory. This synchronization occurs after any access to the memory by the deallocating function and before any access to the memory by the allocation function. There is a single total order of all allocation and deallocation functions operating on each particular region of memory.</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ptr </td> <td> - </td> <td> pointer to the memory to deallocate </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="Notes"> Notes</h3> <p>The function accepts (and does nothing with) the null pointer to reduce the amount of special-casing. Whether allocation succeeds or not, the pointer returned by an allocation function can be passed to <code>free()</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdlib.h> + +int main(void) +{ + int *p1 = malloc(10*sizeof *p1); + free(p1); // every allocated pointer must be freed + + int *p2 = calloc(10, sizeof *p2); + int *p3 = realloc(p2, 1000*sizeof *p3); + if(p3) // p3 not null means p2 was freed by realloc + free(p3); + else // p3 null means p2 was not freed + free(p2); +}</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.24.3.3 The free function </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22.3.3 The free function (p: 254) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.3.3 The free function (p: 348) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.3.2 The free function (p: 313) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.3.2 The free function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="malloc" title="c/memory/malloc"> <span class="t-lines"><span>malloc</span></span></a></div> </td> <td> allocates memory <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="free_sized" title="c/memory/free sized"> <span class="t-lines"><span>free_sized</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> deallocates previously allocated sized memory <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="free_aligned_sized" title="c/memory/free aligned sized"> <span class="t-lines"><span>free_aligned_sized</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> deallocates previously allocated sized and aligned memory <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/memory/c/free" title="cpp/memory/c/free">C++ documentation</a></span> for <code>free</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/memory/free" class="_attribution-link">https://en.cppreference.com/w/c/memory/free</a> + </p> +</div> diff --git a/devdocs/c/memory%2Ffree_aligned_sized.html b/devdocs/c/memory%2Ffree_aligned_sized.html new file mode 100644 index 00000000..f4aeba49 --- /dev/null +++ b/devdocs/c/memory%2Ffree_aligned_sized.html @@ -0,0 +1,20 @@ + <h1 id="firstHeading" class="firstHeading">free_aligned_sized</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">void free_aligned_sized( void* ptr, size_t alignment, size_t size);</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <p>If <code>ptr</code> is a null pointer or the result obtained from a call to <code>aligned_alloc</code>, where <code>alignment</code> is equal to the requested allocation alignment and <code>size</code> is equal to the requested allocation size, this function is equivalent to <code><a href="http://en.cppreference.com/w/c/memory/free"><span class="kw406">free</span></a><span class="br0">(</span>ptr<span class="br0">)</span></code>. Otherwise, the behavior is undefined.</p> +<p>Note: The result of an <code><a href="malloc" title="c/memory/malloc">malloc</a></code>, <code><a href="calloc" title="c/memory/calloc">calloc</a></code>, or <code><a href="realloc" title="c/memory/realloc">realloc</a></code> call may not be passed to <code>free_aligned_sized</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ptr </td> <td> - </td> <td> pointer to the memory to deallocate </td> +</tr> <tr class="t-par"> <td> alignment </td> <td> - </td> <td> alignment of memory to deallocate </td> +</tr> <tr class="t-par"> <td> size </td> <td> - </td> <td> size of memory to deallocate </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="Example"> Example</h3> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="aligned_alloc" title="c/memory/aligned alloc"> <span class="t-lines"><span>aligned_alloc</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> allocates aligned memory <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="free" title="c/memory/free"> <span class="t-lines"><span>free</span></span></a></div> </td> <td> deallocates previously allocated memory <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="free_sized" title="c/memory/free sized"> <span class="t-lines"><span>free_sized</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> deallocates previously allocated sized memory <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="malloc" title="c/memory/malloc"> <span class="t-lines"><span>malloc</span></span></a></div> </td> <td> allocates memory <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/memory/free_aligned_sized" class="_attribution-link">https://en.cppreference.com/w/c/memory/free_aligned_sized</a> + </p> +</div> diff --git a/devdocs/c/memory%2Ffree_sized.html b/devdocs/c/memory%2Ffree_sized.html new file mode 100644 index 00000000..36a5ad8f --- /dev/null +++ b/devdocs/c/memory%2Ffree_sized.html @@ -0,0 +1,70 @@ + <h1 id="firstHeading" class="firstHeading">free_sized</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">void free_sized( void* ptr, size_t size );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <p>Deallocates the space previously allocated by <code><a href="malloc" title="c/memory/malloc">malloc()</a></code>, <code><a href="calloc" title="c/memory/calloc">calloc()</a></code>, or <code><a href="realloc" title="c/memory/realloc">realloc()</a></code> (but not <code>aligned_alloc()</code>).</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ptr </td> <td> - </td> <td> pointer to the memory to deallocate </td> +</tr> <tr class="t-par"> <td> size </td> <td> - </td> <td> size of memory previously passed to an allocation function </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="Notes"> Notes</h3> <h3 id="Possible_implementation"> Possible implementation</h3> <div class="c source-c"><pre data-language="c">void free_sized(void* ptr, size_t /*size*/) +{ + free(ptr); +}</pre></div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stddef.h> +#include <stdio.h> +#include <stdlib.h> + +typedef struct +{ + size_t size; // current number of elements + size_t capacity; // reserved number of elements + void** data; +} PtrVector; + +PtrVector vector_create(size_t initial_capacity) +{ + PtrVector ret = + { + .capacity = initial_capacity, + .data = (void**) malloc(initial_capacity * sizeof(void*)) + }; + return ret; +} + +void vector_delete(PtrVector* self) +{ + free_sized(self->data, self->capacity * sizeof(void*)); +} + +void vector_push_back(PtrVector* self, void* value) +{ + if (self->size == self->capacity) + { + self->capacity *= 2; + self->data = (void**) realloc(self->data, self->capacity * sizeof(void*)); + } + self->data[self->size++] = value; +} + +int main() +{ + int data = 42; + float pi = 3.141592f; + PtrVector v = vector_create(8); + vector_push_back(&v, &data); + vector_push_back(&v, &pi); + printf("data[0] = %i\n", *(int*)v.data[0]); + printf("data[1] = %f\n", *(float*)v.data[1]); + vector_delete(&v); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">data[0] = 42 +data[1] = 3.141592</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.24.3.4 The free_sized function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="free" title="c/memory/free"> <span class="t-lines"><span>free</span></span></a></div> </td> <td> deallocates previously allocated memory <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="free_aligned_sized" title="c/memory/free aligned sized"> <span class="t-lines"><span>free_aligned_sized</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> deallocates previously allocated sized and aligned memory <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="malloc" title="c/memory/malloc"> <span class="t-lines"><span>malloc</span></span></a></div> </td> <td> allocates memory <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/memory/free_sized" class="_attribution-link">https://en.cppreference.com/w/c/memory/free_sized</a> + </p> +</div> diff --git a/devdocs/c/memory%2Fmalloc.html b/devdocs/c/memory%2Fmalloc.html new file mode 100644 index 00000000..05f8d1f2 --- /dev/null +++ b/devdocs/c/memory%2Fmalloc.html @@ -0,0 +1,52 @@ + <h1 id="firstHeading" class="firstHeading">malloc</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">void *malloc( size_t size );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Allocates <code>size</code> bytes of uninitialized storage.</p> +<p>If allocation succeeds, returns a pointer that is suitably aligned for any object type with <a href="../language/object#Alignment" title="c/language/object">fundamental alignment</a>.</p> +<p>If <code>size</code> is zero, the behavior of <code>malloc</code> is implementation-defined. For example, a null pointer may be returned. Alternatively, a non-null pointer may be returned; but such a pointer should not be <a href="../language/operator_member_access" title="c/language/operator member access">dereferenced</a>, and should be passed to <code><a href="free" title="c/memory/free">free</a></code> to avoid memory leaks.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <p><code>malloc</code> is thread-safe: it behaves as though only accessing the memory locations visible through its argument, and not any static storage.</p> +<p>A previous call to <code><a href="free" title="c/memory/free">free</a></code> or <code><a href="realloc" title="c/memory/realloc">realloc</a></code> that deallocates a region of memory <i>synchronizes-with</i> a call to <code>malloc</code> that allocates the same or a part of the same region of memory. This synchronization occurs after any access to the memory by the deallocating function and before any access to the memory by <code>malloc</code>. There is a single total order of all allocation and deallocation functions operating on each particular region of memory.</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> size </td> <td> - </td> <td> number of bytes to allocate </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>On success, returns the pointer to the beginning of newly allocated memory. To avoid a memory leak, the returned pointer must be deallocated with <code><a href="free" title="c/memory/free">free()</a></code> or <code><a href="realloc" title="c/memory/realloc">realloc()</a></code>.</p> +<p>On failure, returns a null pointer.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + int *p1 = malloc(4*sizeof(int)); // allocates enough for an array of 4 int + int *p2 = malloc(sizeof(int[4])); // same, naming the type directly + int *p3 = malloc(4*sizeof *p3); // same, without repeating the type name + + if(p1) { + for(int n=0; n<4; ++n) // populate the array + p1[n] = n*n; + for(int n=0; n<4; ++n) // print it back out + printf("p1[%d] == %d\n", n, p1[n]); + } + + free(p1); + free(p2); + free(p3); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">p1[0] == 0 +p1[1] == 1 +p1[2] == 4 +p1[3] == 9</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22.3.4 The malloc function (p: 254) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.3.4 The malloc function (p: 349) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.3.3 The malloc function (p: 314) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.3.3 The malloc function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="free" title="c/memory/free"> <span class="t-lines"><span>free</span></span></a></div> </td> <td> deallocates previously allocated memory <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/memory/c/malloc" title="cpp/memory/c/malloc">C++ documentation</a></span> for <code>malloc</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/memory/malloc" class="_attribution-link">https://en.cppreference.com/w/c/memory/malloc</a> + </p> +</div> diff --git a/devdocs/c/memory%2Frealloc.html b/devdocs/c/memory%2Frealloc.html new file mode 100644 index 00000000..65d5948d --- /dev/null +++ b/devdocs/c/memory%2Frealloc.html @@ -0,0 +1,102 @@ + <h1 id="firstHeading" class="firstHeading">realloc</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">void *realloc( void *ptr, size_t new_size );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Reallocates the given area of memory. If <code>ptr</code> is not NULL, it must be previously allocated by <code><a href="malloc" title="c/memory/malloc">malloc</a></code>, <code><a href="calloc" title="c/memory/calloc">calloc</a></code> or <code>realloc</code> and not yet freed with a call to <code><a href="free" title="c/memory/free">free</a></code> or <code>realloc</code>. Otherwise, the results are undefined.</p> +<p>The reallocation is done by either:</p> +<div class="t-li1"> +<span class="t-li">a)</span> expanding or contracting the existing area pointed to by <code>ptr</code>, if possible. The contents of the area remain unchanged up to the lesser of the new and old sizes. If the area is expanded, the contents of the new part of the array are undefined.</div> <div class="t-li1"> +<span class="t-li">b)</span> allocating a new memory block of size <code>new_size</code> bytes, copying memory area with size equal the lesser of the new and the old sizes, and freeing the old block.</div> <p>If there is not enough memory, the old memory block is not freed and null pointer is returned.</p> +<p>If <code>ptr</code> is <code><a href="../types/null" title="c/types/NULL">NULL</a></code>, the behavior is the same as calling <code><a href="http://en.cppreference.com/w/c/memory/malloc"><span class="kw403">malloc</span></a><span class="br0">(</span>new_size<span class="br0">)</span></code>.</p> +<p>Otherwise,</p> +<table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>if <code>new_size</code> is zero, the behavior is implementation defined (null pointer may be returned (in which case the old memory block may or may not be freed), or some non-null pointer may be returned that may not be used to access storage). <span class="t-rev-inl t-since-c17"><span>Such usage is deprecated (via <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2396.htm#dr_400">C DR 400</a>).</span><span><span class="t-mark-rev t-until-c17">(since C17)</span></span></span></p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td> <p>if <code>new_size</code> is zero, the behavior is undefined.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <p><code>realloc</code> is thread-safe: it behaves as though only accessing the memory locations visible through its argument, and not any static storage.</p> +<p>A previous call to <code><a href="free" title="c/memory/free">free</a></code> or <code>realloc</code> that deallocates a region of memory <i>synchronizes-with</i> a call to any allocation function, including <code>realloc</code> that allocates the same or a part of the same region of memory. This synchronization occurs after any access to the memory by the deallocating function and before any access to the memory by <code>realloc</code>. There is a single total order of all allocation and deallocation functions operating on each particular region of memory.</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ptr </td> <td> - </td> <td> pointer to the memory area to be reallocated </td> +</tr> <tr class="t-par"> <td> new_size </td> <td> - </td> <td> new size of the array in bytes </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>On success, returns the pointer to the beginning of newly allocated memory. To avoid a memory leak, the returned pointer must be deallocated with <code><a href="free" title="c/memory/free">free</a></code> or <code>realloc</code>. The original pointer <code>ptr</code> is invalidated and any access to it is undefined behavior (even if reallocation was in-place).</p> +<p>On failure, returns a null pointer. The original pointer <code>ptr</code> remains valid and may need to be deallocated with <code><a href="free" title="c/memory/free">free</a></code> or <code>realloc</code>.</p> +<h3 id="Notes"> Notes</h3> <p>Originally (in C89), support for zero size was added to accommodate code such as</p> +<div class="c source-c"><pre data-language="c">OBJ *p = calloc(0, sizeof(OBJ)); // "zero-length" placeholder +/*...*/ +while (1) +{ + p = realloc(p, c * sizeof(OBJ)); // reallocations until size settles + /* code that may change c or break out of loop */ +}</pre></div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <assert.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> + +void print_storage_info(const int* next, const int* prev, int ints) +{ + if (next) + printf("%s location: %p. Size: %d ints (%ld bytes).\n", + (next != prev ? "New" : "Old"), (void*)next, ints, ints * sizeof(int)); + else + printf("Allocation failed.\n"); +} + +int main(void) +{ + const int pattern[] = {1, 2, 3, 4, 5, 6, 7, 8}; + const int pattern_size = sizeof pattern / sizeof(int); + int *next = NULL, *prev = NULL; + + if ((next = (int*)malloc(pattern_size * sizeof *next))) // allocates an array + { + memcpy(next, pattern, sizeof pattern); // fills the array + print_storage_info(next, prev, pattern_size); + } + else + return EXIT_FAILURE; + + // Reallocate in cycle using the following values as a new storage size. + const int realloc_size[] = {10, 12, 512, 32768, 65536, 32768}; + + for (int i = 0; i != sizeof realloc_size / sizeof(int); ++i) + { + if ((next = (int*)realloc(prev = next, realloc_size[i] * sizeof(int)))) + { + print_storage_info(next, prev, realloc_size[i]); + assert(!memcmp(next, pattern, sizeof pattern)); // is pattern held + } + else // if realloc failed, the original pointer needs to be freed + { + free(prev); + return EXIT_FAILURE; + } + } + + free(next); // finally, frees the storage + return EXIT_SUCCESS; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">New location: 0x144c010. Size: 8 ints (32 bytes). +Old location: 0x144c010. Size: 10 ints (40 bytes). +New location: 0x144c450. Size: 12 ints (48 bytes). +Old location: 0x144c450. Size: 512 ints (2048 bytes). +Old location: 0x144c450. Size: 32768 ints (131072 bytes). +New location: 0x7f490c5bd010. Size: 65536 ints (262144 bytes). +Old location: 0x7f490c5bd010. Size: 32768 ints (131072 bytes).</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.22.3.5 The realloc function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22.3.5 The realloc function (p: 254) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.3.5 The realloc function (p: 349) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.3.4 The realloc function (p: 314) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.3.4 The realloc function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/memory/c/realloc" title="cpp/memory/c/realloc">C++ documentation</a></span> for <code>realloc</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/memory/realloc" class="_attribution-link">https://en.cppreference.com/w/c/memory/realloc</a> + </p> +</div> diff --git a/devdocs/c/memory.html b/devdocs/c/memory.html new file mode 100644 index 00000000..9fd74682 --- /dev/null +++ b/devdocs/c/memory.html @@ -0,0 +1,18 @@ + <h1 id="firstHeading" class="firstHeading">Dynamic memory management</h1> <h3 id="Functions"> Functions</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdlib.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="memory/malloc" title="c/memory/malloc"> <span class="t-lines"><span>malloc</span></span></a></div> </td> <td> allocates memory <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="memory/calloc" title="c/memory/calloc"> <span class="t-lines"><span>calloc</span></span></a></div> </td> <td> allocates and zeroes memory <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="memory/realloc" title="c/memory/realloc"> <span class="t-lines"><span>realloc</span></span></a></div> </td> <td> expands previously allocated memory block <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="memory/free" title="c/memory/free"> <span class="t-lines"><span>free</span></span></a></div> </td> <td> deallocates previously allocated memory <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="memory/free_sized" title="c/memory/free sized"> <span class="t-lines"><span>free_sized</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> deallocates previously allocated sized memory <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="memory/free_aligned_sized" title="c/memory/free aligned sized"> <span class="t-lines"><span>free_aligned_sized</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> deallocates previously allocated sized and aligned memory <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="memory/aligned_alloc" title="c/memory/aligned alloc"> <span class="t-lines"><span>aligned_alloc</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> allocates aligned memory <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/memory/c" title="cpp/memory/c">C++ documentation</a></span> for <span class=""><span>C memory management library</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/memory" class="_attribution-link">https://en.cppreference.com/w/c/memory</a> + </p> +</div> diff --git a/devdocs/c/metadata b/devdocs/c/metadata new file mode 100644 index 00000000..b6a53b3c --- /dev/null +++ b/devdocs/c/metadata @@ -0,0 +1,2 @@ +(1 (name . "C") (slug . "c") (type . "cppref") (mtime . 1704475550) (db_size . 4722426) (attribution . "© cppreference.com<br> + Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0."))
\ No newline at end of file diff --git a/devdocs/c/numeric%2Fcomplex%2Fcabs.html b/devdocs/c/numeric%2Fcomplex%2Fcabs.html new file mode 100644 index 00000000..5db11848 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcabs.html @@ -0,0 +1,47 @@ + <h1 id="firstHeading" class="firstHeading">cabsf, cabs, cabsl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float cabsf( float complex z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double cabs( double complex z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double cabsl( long double complex z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define fabs( z )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the complex absolute value (also known as norm, modulus, or magnitude) of <code>z</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: if <code>z</code> has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code> or <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, <code>cabsl</code> is called. If <code>z</code> has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code> or <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, <code>cabsf</code> is called. If <code>z</code> has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code> or <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, <code>cabs</code> is called. For real and integer types, the corresponding version of <code><a href="../math/fabs" title="c/numeric/math/fabs">fabs</a></code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> z </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, returns the absolute value (norm, magnitude) of <code>z</code>.</p> +<p>Errors and special cases are handled as if the function is implemented as <code><a href="http://en.cppreference.com/w/c/numeric/math/hypot"><span class="kw667">hypot</span></a><span class="br0">(</span><a href="http://en.cppreference.com/w/c/numeric/complex/creal"><span class="kw754">creal</span></a><span class="br0">(</span>z<span class="br0">)</span>, <a href="http://en.cppreference.com/w/c/numeric/complex/cimag"><span class="kw751">cimag</span></a><span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span></code></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <complex.h> + +int main(void) +{ + double complex z = 1.0 + 1.0*I; + printf("%.1f%+.1fi cartesian is rho=%f theta=%f polar\n", + creal(z), cimag(z), cabs(z), carg(z)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">1.0+1.0i cartesian is rho=1.414214 theta=0.785398 polar</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.8.1 The cabs functions (p: 195) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.8.1 The cabs functions (p: 177) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="carg" title="c/numeric/complex/carg"> <span class="t-lines"><span>carg</span><span>cargf</span><span>cargl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the phase angle of a complex number <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../math/abs" title="c/numeric/math/abs"> <span class="t-lines"><span>abs</span><span>labs</span><span>llabs</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes absolute value of an integral value (\(\small{|x|}\)|x|) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../math/fabs" title="c/numeric/math/fabs"> <span class="t-lines"><span>fabs</span><span>fabsf</span><span>fabsl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes absolute value of a floating-point value (\(\small{|x|}\)|x|) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../math/hypot" title="c/numeric/math/hypot"> <span class="t-lines"><span>hypot</span><span>hypotf</span><span>hypotl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes square root of the sum of the squares of two given numbers (\(\scriptsize{\sqrt{x^2+y^2} }\)<span class="t-mrad"><span>√</span><span>x<sup class="t-su">2</sup>+y<sup class="t-su">2</sup></span></span>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/abs" title="cpp/numeric/complex/abs">C++ documentation</a></span> for <code>abs</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/cabs" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/cabs</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fcacos.html b/devdocs/c/numeric%2Fcomplex%2Fcacos.html new file mode 100644 index 00000000..d5f7cc0a --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcacos.html @@ -0,0 +1,76 @@ + <h1 id="firstHeading" class="firstHeading">cacosf, cacos, cacosl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float complex cacosf( float complex z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double complex cacos( double complex z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double complex cacosl( long double complex z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define acos( z )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the complex arc cosine of <code>z</code> with branch cuts outside the interval [−1,+1] along the real axis.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>z</code> has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>cacosl</code> is called. if <code>z</code> has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>cacos</code> is called, if <code>z</code> has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>cacosf</code> is called. If <code>z</code> is real or integer, then the macro invokes the corresponding real function (<code>acosf</code>, <code><a href="http://en.cppreference.com/w/c/numeric/math/acos"><span class="kw673">acos</span></a></code>, <code>acosl</code>). If <code>z</code> is imaginary, then the macro invokes the corresponding complex number version.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> z </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, complex arc cosine of <code>z</code> is returned, in the range a strip unbounded along the imaginary axis and in the interval [0; π] along the real axis.</p> +<h3 id="Error_handling_and_special_values"> Error handling and special values</h3> <p>Errors are reported consistent with <a href="../math/math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic,</p> +<ul> +<li> <code>cacos<span class="br0">(</span><a href="http://en.cppreference.com/w/c/numeric/complex/conj"><span class="kw760">conj</span></a><span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span> <span class="sy1">==</span> <a href="http://en.cppreference.com/w/c/numeric/complex/conj"><span class="kw760">conj</span></a><span class="br0">(</span>cacos<span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span></code> </li> +<li> If <code>z</code> is <code>±0+0i</code>, the result is <code>π/2-0i</code> </li> +<li> If <code>z</code> is <code>±0+NaNi</code>, the result is <code>π/2+NaNi</code> </li> +<li> If <code>z</code> is <code>x+∞i</code> (for any finite x), the result is <code>π/2-∞i</code> </li> +<li> If <code>z</code> is <code>x+NaNi</code> (for any nonzero finite x), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> may be raised. </li> +<li> If <code>z</code> is <code>-∞+yi</code> (for any positive finite y), the result is <code>π-∞i</code> </li> +<li> If <code>z</code> is <code>+∞+yi</code> (for any positive finite y), the result is <code>+0-∞i</code> </li> +<li> If <code>z</code> is <code>-∞+∞i</code>, the result is <code>3π/4-∞i</code> </li> +<li> If <code>z</code> is <code>+∞+∞i</code>, the result is <code>π/4-∞i</code> </li> +<li> If <code>z</code> is <code>±∞+NaNi</code>, the result is <code>NaN±∞i</code> (the sign of the imaginary part is unspecified) </li> +<li> If <code>z</code> is <code>NaN+yi</code> (for any finite y), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> may be raised </li> +<li> If <code>z</code> is <code>NaN+∞i</code>, the result is <code>NaN-∞i</code> </li> +<li> If <code>z</code> is <code>NaN+NaNi</code>, the result is <code>NaN+NaNi</code> </li> +</ul> <h3 id="Notes"> Notes</h3> <p>Inverse cosine (or arc cosine) is a multivalued function and requires a branch cut on the complex plane. The branch cut is conventially placed at the line segments (-∞,-1) and (1,∞) of the real axis. The mathematical definition of the principal value of arc cosine is acos z =</p> +<span><span>1</span><span>/</span><span>2</span></span>π + <i>i</i>ln(<i>i</i>z + <span class="t-mrad"><span>√</span><span>1-z<sup class="t-su">2</sup></span></span>) <p>For any z, acos(z) = π - acos(-z)</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <complex.h> + +int main(void) +{ + double complex z = cacos(-2); + printf("cacos(-2+0i) = %f%+fi\n", creal(z), cimag(z)); + + double complex z2 = cacos(conj(-2)); // or CMPLX(-2, -0.0) + printf("cacos(-2-0i) (the other side of the cut) = %f%+fi\n", creal(z2), cimag(z2)); + + // for any z, acos(z) = pi - acos(-z) + double pi = acos(-1); + double complex z3 = ccos(pi-z2); + printf("ccos(pi - cacos(-2-0i) = %f%+fi\n", creal(z3), cimag(z3)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">cacos(-2+0i) = 3.141593-1.316958i +cacos(-2-0i) (the other side of the cut) = 3.141593+1.316958i +ccos(pi - cacos(-2-0i) = 2.000000+0.000000i</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.5.1 The cacos functions (p: 190) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> G.6.1.1 The cacos functions (p: 539) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.5.1 The cacos functions (p: 172) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> G.6.1.1 The cacos functions (p: 474) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="casin" title="c/numeric/complex/casin"> <span class="t-lines"><span>casin</span><span>casinf</span><span>casinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc sine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="catan" title="c/numeric/complex/catan"> <span class="t-lines"><span>catan</span><span>catanf</span><span>catanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc tangent <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ccos" title="c/numeric/complex/ccos"> <span class="t-lines"><span>ccos</span><span>ccosf</span><span>ccosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex cosine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../math/acos" title="c/numeric/math/acos"> <span class="t-lines"><span>acos</span><span>acosf</span><span>acosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc cosine (\({\small\arccos{x} }\)arccos(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/acos" title="cpp/numeric/complex/acos">C++ documentation</a></span> for <code>acos</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/cacos" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/cacos</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fcacosh.html b/devdocs/c/numeric%2Fcomplex%2Fcacosh.html new file mode 100644 index 00000000..9da0e7a1 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcacosh.html @@ -0,0 +1,80 @@ + <h1 id="firstHeading" class="firstHeading">cacoshf, cacosh, cacoshl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float complex cacoshf( float complex z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double complex cacosh( double complex z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double complex cacoshl( long double complex z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define acosh( z )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes complex arc hyperbolic cosine of a complex value <code>z</code> with branch cut at values less than 1 along the real axis.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>z</code> has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>cacoshl</code> is called. if <code>z</code> has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>cacosh</code> is called, if <code>z</code> has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>cacoshf</code> is called. If <code>z</code> is real or integer, then the macro invokes the corresponding real function (<code>acoshf</code>, <code><a href="http://en.cppreference.com/w/c/numeric/math/acosh"><span class="kw680">acosh</span></a></code>, <code>acoshl</code>). If <code>z</code> is imaginary, then the macro invokes the corresponding complex number version and the return type is complex.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> z </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The complex arc hyperbolic cosine of <code>z</code> in the interval [0; ∞) along the real axis and in the interval [−iπ; +iπ] along the imaginary axis.</p> +<h3 id="Error_handling_and_special_values"> Error handling and special values</h3> <p>Errors are reported consistent with <a href="../math/math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a></p> +<p>If the implementation supports IEEE floating-point arithmetic,</p> +<ul> +<li> <code>cacosh<span class="br0">(</span><a href="http://en.cppreference.com/w/c/numeric/complex/conj"><span class="kw760">conj</span></a><span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span> <span class="sy1">==</span> <a href="http://en.cppreference.com/w/c/numeric/complex/conj"><span class="kw760">conj</span></a><span class="br0">(</span>cacosh<span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span></code> </li> +<li> If <code>z</code> is <code>±0+0i</code>, the result is <code>+0+iπ/2</code> </li> +<li> If <code>z</code> is <code>+x+∞i</code> (for any finite x), the result is <code>+∞+iπ/2</code> </li> +<li> If <code>z</code> is <code>+x+NaNi</code> (for non-zero finite x), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> may be raised. </li> +<li> If <code>z</code> is <code>0+NaNi</code>, the result is <code>NaN±iπ/2</code>, where the sign of the imaginary part is unspecified </li> +<li> If <code>z</code> is <code>-∞+yi</code> (for any positive finite y), the result is <code>+∞+iπ</code> </li> +<li> If <code>z</code> is <code>+∞+yi</code> (for any positive finite y), the result is <code>+∞+0i</code> </li> +<li> If <code>z</code> is <code>-∞+∞i</code>, the result is <code>+∞+3iπ/4</code> </li> +<li> If <code>z</code> is <code>+∞+∞i</code>, the result is <code>+∞+iπ/4</code> </li> +<li> If <code>z</code> is <code>±∞+NaNi</code>, the result is <code>+∞+NaNi</code> </li> +<li> If <code>z</code> is <code>NaN+yi</code> (for any finite y), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> may be raised. </li> +<li> If <code>z</code> is <code>NaN+∞i</code>, the result is <code>+∞+NaNi</code> </li> +<li> If <code>z</code> is <code>NaN+NaNi</code>, the result is <code>NaN+NaNi</code> </li> +</ul> <h3 id="Notes"> Notes</h3> <p>Although the C standard names this function "complex arc hyperbolic cosine", the inverse functions of the hyperbolic functions are the area functions. Their argument is the area of a hyperbolic sector, not an arc. The correct name is "complex inverse hyperbolic cosine", and, less common, "complex area hyperbolic cosine".</p> +<p>Inverse hyperbolic cosine is a multivalued function and requires a branch cut on the complex plane. The branch cut is conventionally placed at the line segment (-∞,+1) of the real axis.</p> +<p>The mathematical definition of the principal value of the inverse hyperbolic cosine is acosh z = ln(z + <span class="t-mrad"><span>√</span><span>z+1</span></span> <span class="t-mrad"><span>√</span><span>z-1</span></span>) For any z, acosh(z) =</p> +<span><span>√z-1</span><span>/</span><span>√1-z</span></span> acos(z), or simply i acos(z) in the upper half of the complex plane. <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <complex.h> + +int main(void) +{ + double complex z = cacosh(0.5); + printf("cacosh(+0.5+0i) = %f%+fi\n", creal(z), cimag(z)); + + double complex z2 = conj(0.5); // or cacosh(CMPLX(0.5, -0.0)) in C11 + printf("cacosh(+0.5-0i) (the other side of the cut) = %f%+fi\n", creal(z2), cimag(z2)); + + // in upper half-plane, acosh(z) = i*acos(z) + double complex z3 = casinh(1+I); + printf("casinh(1+1i) = %f%+fi\n", creal(z3), cimag(z3)); + double complex z4 = I*casin(1+I); + printf("I*asin(1+1i) = %f%+fi\n", creal(z4), cimag(z4)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">cacosh(+0.5+0i) = 0.000000-1.047198i +cacosh(+0.5-0i) (the other side of the cut) = 0.500000-0.000000i +casinh(1+1i) = 1.061275+0.666239i +I*asin(1+1i) = -1.061275+0.666239i</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.6.1 The cacosh functions (p: 192) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> G.6.2.1 The cacosh functions (p: 539-540) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.6.1 The cacosh functions (p: 174) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> G.6.2.1 The cacosh functions (p: 474-475) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="cacos" title="c/numeric/complex/cacos"> <span class="t-lines"><span>cacos</span><span>cacosf</span><span>cacosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc cosine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="casinh" title="c/numeric/complex/casinh"> <span class="t-lines"><span>casinh</span><span>casinhf</span><span>casinhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc hyperbolic sine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="catanh" title="c/numeric/complex/catanh"> <span class="t-lines"><span>catanh</span><span>catanhf</span><span>catanhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc hyperbolic tangent <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ccosh" title="c/numeric/complex/ccosh"> <span class="t-lines"><span>ccosh</span><span>ccoshf</span><span>ccoshl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex hyperbolic cosine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../math/acosh" title="c/numeric/math/acosh"> <span class="t-lines"><span>acosh</span><span>acoshf</span><span>acoshl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes inverse hyperbolic cosine (\({\small\operatorname{arcosh}{x} }\)arcosh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/acosh" title="cpp/numeric/complex/acosh">C++ documentation</a></span> for <code>acosh</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/cacosh" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/cacosh</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fcarg.html b/devdocs/c/numeric%2Fcomplex%2Fcarg.html new file mode 100644 index 00000000..608d566f --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcarg.html @@ -0,0 +1,55 @@ + <h1 id="firstHeading" class="firstHeading">cargf, carg, cargl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float cargf( float complex z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double carg( double complex z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double cargl( long double complex z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define carg( z )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the argument (also called phase angle) of <code>z</code>, with a branch cut along the negative real axis.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: if <code>z</code> has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, or <code>long double</code>, <code>cargl</code> is called. If <code>z</code> has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, or <code>float</code>, <code>cargf</code> is called. If <code>z</code> has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, <code>double</code>, or any integer type, <code>carg</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> z </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, returns the phase angle of <code>z</code> in the interval [−π; π].</p> +<p>Errors and special cases are handled as if the function is implemented as <code><a href="http://en.cppreference.com/w/c/numeric/math/atan2"><span class="kw675">atan2</span></a><span class="br0">(</span><a href="http://en.cppreference.com/w/c/numeric/complex/cimag"><span class="kw751">cimag</span></a><span class="br0">(</span>z<span class="br0">)</span>, <a href="http://en.cppreference.com/w/c/numeric/complex/creal"><span class="kw754">creal</span></a><span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span></code></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <complex.h> + +int main(void) +{ + double complex z1 = 1.0+0.0*I; + printf("phase angle of %.1f%+.1fi is %f\n", creal(z1), cimag(z1), carg(z1)); + + double complex z2 = 0.0+1.0*I; + printf("phase angle of %.1f%+.1fi is %f\n", creal(z2), cimag(z2), carg(z2)); + + double complex z3 = -1.0+0.0*I; + printf("phase angle of %.1f%+.1fi is %f\n", creal(z3), cimag(z3), carg(z3)); + + double complex z4 = conj(z3); // or CMPLX(-1, -0.0) + printf("phase angle of %.1f%+.1fi (the other side of the cut) is %f\n", + creal(z4), cimag(z4), carg(z4)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">phase angle of 1.0+0.0i is 0.000000 +phase angle of 0.0+1.0i is 1.570796 +phase angle of -1.0+0.0i is 3.141593 +phase angle of -1.0-0.0i (the other side of the cut) is -3.141593</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.9.1 The carg functions (p: 196) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.9.1 The carg functions (p: 178) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="cabs" title="c/numeric/complex/cabs"> <span class="t-lines"><span>cabs</span><span>cabsf</span><span>cabsl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the magnitude of a complex number <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../math/atan2" title="c/numeric/math/atan2"> <span class="t-lines"><span>atan2</span><span>atan2f</span><span>atan2l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc tangent, using signs to determine quadrants <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/arg" title="cpp/numeric/complex/arg">C++ documentation</a></span> for <code>arg</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/carg" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/carg</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fcasin.html b/devdocs/c/numeric%2Fcomplex%2Fcasin.html new file mode 100644 index 00000000..379708be --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcasin.html @@ -0,0 +1,59 @@ + <h1 id="firstHeading" class="firstHeading">casinf, casin, casinl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float complex casinf( float complex z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double complex casin( double complex z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double complex casinl( long double complex z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define asin( z )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the complex arc sine of <code>z</code> with branch cuts outside the interval [−1,+1] along the real axis.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>z</code> has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>casinl</code> is called. if <code>z</code> has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>casin</code> is called, if <code>z</code> has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>casinf</code> is called. If <code>z</code> is real or integer, then the macro invokes the corresponding real function (<code>asinf</code>, <code><a href="http://en.cppreference.com/w/c/numeric/math/asin"><span class="kw672">asin</span></a></code>, <code>asinl</code>). If <code>z</code> is imaginary, then the macro invokes the corresponding real version of the function <code><a href="../math/asinh" title="c/numeric/math/asinh">asinh</a></code>, implementing the formula \(\small \arcsin({\rm i}y) = {\rm i}{\rm arsinh}(y)\)arcsin(iy) = i arsinh(y), and the return type of the macro is imaginary.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> z </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, complex arc sine of <code>z</code> is returned, in the range of a strip unbounded along the imaginary axis and in the interval [−π/2; +π/2] along the real axis.</p> +<p>Errors and special cases are handled as if the operation is implemented by <code><span class="sy2">-</span>I <span class="sy2">*</span> <a href="http://en.cppreference.com/w/c/numeric/complex/casinh"><span class="kw799">casinh</span></a><span class="br0">(</span>I<span class="sy2">*</span>z<span class="br0">)</span></code></p> +<h3 id="Notes"> Notes</h3> <p>Inverse sine (or arc sine) is a multivalued function and requires a branch cut on the complex plane. The branch cut is conventionally placed at the line segments (-∞,-1) and (1,∞) of the real axis.</p> +<p>The mathematical definition of the principal value of arc sine is \(\small \arcsin z = -{\rm i}\ln({\rm i}z+\sqrt{1-z^2})\)arcsin z = -<i>i</i>ln(<i>i</i>z + <span class="t-mrad"><span>√</span><span>1-z<sup class="t-su">2</sup></span></span>) For any z, \(\small{ \arcsin(z) = \arccos(-z) - \frac{\pi}{2} }\)arcsin(z) = acos(-z) -</p> +<span><span>π</span><span>/</span><span>2</span></span> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <complex.h> + +int main(void) +{ + double complex z = casin(-2); + printf("casin(-2+0i) = %f%+fi\n", creal(z), cimag(z)); + + double complex z2 = casin(conj(-2)); // or CMPLX(-2, -0.0) + printf("casin(-2-0i) (the other side of the cut) = %f%+fi\n", creal(z2), cimag(z2)); + + // for any z, asin(z) = acos(-z) - pi/2 + double pi = acos(-1); + double complex z3 = csin(cacos(conj(-2))-pi/2); + printf("csin(cacos(-2-0i)-pi/2) = %f%+fi\n", creal(z3), cimag(z3)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">casin(-2+0i) = -1.570796+1.316958i +casin(-2-0i) (the other side of the cut) = -1.570796-1.316958i +csin(cacos(-2-0i)-pi/2) = 2.000000+0.000000i</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.5.2 The casin functions (p: 190) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.5.2 The casin functions (p: 172) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="cacos" title="c/numeric/complex/cacos"> <span class="t-lines"><span>cacos</span><span>cacosf</span><span>cacosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc cosine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="catan" title="c/numeric/complex/catan"> <span class="t-lines"><span>catan</span><span>catanf</span><span>catanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc tangent <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="csin" title="c/numeric/complex/csin"> <span class="t-lines"><span>csin</span><span>csinf</span><span>csinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex sine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../math/asin" title="c/numeric/math/asin"> <span class="t-lines"><span>asin</span><span>asinf</span><span>asinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc sine (\({\small\arcsin{x} }\)arcsin(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/asin" title="cpp/numeric/complex/asin">C++ documentation</a></span> for <code>asin</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/casin" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/casin</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fcasinh.html b/devdocs/c/numeric%2Fcomplex%2Fcasinh.html new file mode 100644 index 00000000..9ef02d9c --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcasinh.html @@ -0,0 +1,77 @@ + <h1 id="firstHeading" class="firstHeading">casinhf, casinh, casinhl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float complex casinhf( float complex z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double complex casinh( double complex z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double complex casinhl( long double complex z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define asinh( z )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the complex arc hyperbolic sine of <code>z</code> with branch cuts outside the interval [−i; +i] along the imaginary axis.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>z</code> has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>casinhl</code> is called. if <code>z</code> has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>casinh</code> is called, if <code>z</code> has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>casinhf</code> is called. If <code>z</code> is real or integer, then the macro invokes the corresponding real function (<code>asinhf</code>, <code><a href="http://en.cppreference.com/w/c/numeric/math/asinh"><span class="kw679">asinh</span></a></code>, <code>asinhl</code>). If <code>z</code> is imaginary, then the macro invokes the corresponding real version of the function <code><a href="../math/asin" title="c/numeric/math/asin">asin</a></code>, implementing the formula asinh(iy) = i asin(y), and the return type is imaginary.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> z </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the complex arc hyperbolic sine of <code>z</code> is returned, in the range of a strip mathematically unbounded along the real axis and in the interval [−iπ/2; +iπ/2] along the imaginary axis.</p> +<h3 id="Error_handling_and_special_values"> Error handling and special values</h3> <p>Errors are reported consistent with <a href="../math/math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a></p> +<p>If the implementation supports IEEE floating-point arithmetic,</p> +<ul> +<li> <code>casinh<span class="br0">(</span><a href="http://en.cppreference.com/w/c/numeric/complex/conj"><span class="kw760">conj</span></a><span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span> <span class="sy1">==</span> <a href="http://en.cppreference.com/w/c/numeric/complex/conj"><span class="kw760">conj</span></a><span class="br0">(</span>casinh<span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span></code> </li> +<li> <code>casinh(-z) == -casinh(z)</code> </li> +<li> If <code>z</code> is <code>+0+0i</code>, the result is <code>+0+0i</code> </li> +<li> If <code>z</code> is <code>x+∞i</code> (for any positive finite x), the result is <code>+∞+π/2</code> </li> +<li> If <code>z</code> is <code>x+NaNi</code> (for any finite x), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> may be raised </li> +<li> If <code>z</code> is <code>+∞+yi</code> (for any positive finite y), the result is <code>+∞+0i</code> </li> +<li> If <code>z</code> is <code>+∞+∞i</code>, the result is <code>+∞+iπ/4</code> </li> +<li> If <code>z</code> is <code>+∞+NaNi</code>, the result is <code>+∞+NaNi</code> </li> +<li> If <code>z</code> is <code>NaN+0i</code>, the result is <code>NaN+0i</code> </li> +<li> If <code>z</code> is <code>NaN+yi</code> (for any finite nonzero y), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> may be raised </li> +<li> If <code>z</code> is <code>NaN+∞i</code>, the result is <code>±∞+NaNi</code> (the sign of the real part is unspecified) </li> +<li> If <code>z</code> is <code>NaN+NaNi</code>, the result is <code>NaN+NaNi</code> </li> +</ul> <h3 id="Notes"> Notes</h3> <p>Although the C standard names this function "complex arc hyperbolic sine", the inverse functions of the hyperbolic functions are the area functions. Their argument is the area of a hyperbolic sector, not an arc. The correct name is "complex inverse hyperbolic sine", and, less common, "complex area hyperbolic sine".</p> +<p>Inverse hyperbolic sine is a multivalued function and requires a branch cut on the complex plane. The branch cut is conventionally placed at the line segments (-<i>i</i>∞,-<i>i</i>) and (<i>i</i>,<i>i</i>∞) of the imaginary axis.</p> +<p>The mathematical definition of the principal value of the inverse hyperbolic sine is asinh z = ln(z + <span class="t-mrad"><span>√</span><span>1+z<sup class="t-su">2</sup></span></span>) For any z, asinh(z) =</p> +<span><span>asin(iz)</span><span>/</span><span>i</span></span> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <complex.h> + +int main(void) +{ + double complex z = casinh(0+2*I); + printf("casinh(+0+2i) = %f%+fi\n", creal(z), cimag(z)); + + double complex z2 = casinh(-conj(2*I)); // or casinh(CMPLX(-0.0, 2)) in C11 + printf("casinh(-0+2i) (the other side of the cut) = %f%+fi\n", creal(z2), cimag(z2)); + + // for any z, asinh(z) = asin(iz)/i + double complex z3 = casinh(1+2*I); + printf("casinh(1+2i) = %f%+fi\n", creal(z3), cimag(z3)); + double complex z4 = casin((1+2*I)*I)/I; + printf("casin(i * (1+2i))/i = %f%+fi\n", creal(z4), cimag(z4)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">casinh(+0+2i) = 1.316958+1.570796i +casinh(-0+2i) (the other side of the cut) = -1.316958+1.570796i +casinh(1+2i) = 1.469352+1.063440i +casin(i * (1+2i))/i = 1.469352+1.063440i</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.6.2 The casinh functions (p: 192-193) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> G.6.2.2 The casinh functions (p: 540) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.6.2 The casinh functions (p: 174-175) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> G.6.2.2 The casinh functions (p: 475) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="cacosh" title="c/numeric/complex/cacosh"> <span class="t-lines"><span>cacosh</span><span>cacoshf</span><span>cacoshl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc hyperbolic cosine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="catanh" title="c/numeric/complex/catanh"> <span class="t-lines"><span>catanh</span><span>catanhf</span><span>catanhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc hyperbolic tangent <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="csinh" title="c/numeric/complex/csinh"> <span class="t-lines"><span>csinh</span><span>csinhf</span><span>csinhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex hyperbolic sine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../math/asinh" title="c/numeric/math/asinh"> <span class="t-lines"><span>asinh</span><span>asinhf</span><span>asinhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes inverse hyperbolic sine (\({\small\operatorname{arsinh}{x} }\)arsinh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/asinh" title="cpp/numeric/complex/asinh">C++ documentation</a></span> for <code>asinh</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/casinh" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/casinh</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fcatan.html b/devdocs/c/numeric%2Fcomplex%2Fcatan.html new file mode 100644 index 00000000..c74f6eef --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcatan.html @@ -0,0 +1,56 @@ + <h1 id="firstHeading" class="firstHeading">catanf, catan, catanl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float complex catanf( float complex z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double complex catan( double complex z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double complex catanl( long double complex z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define atan( z )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the complex arc tangent of <code>z</code> with branch cuts outside the interval [−i,+i] along the imaginary axis.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>z</code> has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>catanl</code> is called. if <code>z</code> has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>catan</code> is called, if <code>z</code> has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>catanf</code> is called. If <code>z</code> is real or integer, then the macro invokes the corresponding real function (<code>atanf</code>, <code><a href="http://en.cppreference.com/w/c/numeric/math/atan"><span class="kw674">atan</span></a></code>, <code>atanl</code>). If <code>z</code> is imaginary, then the macro invokes the corresponding real version of the function <code><a href="../math/atanh" title="c/numeric/math/atanh">atanh</a></code>, implementing the formula atan(iy) = i atanh(y), and the return type of the macro is imaginary.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> z </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, complex arc tangent of <code>z</code> is returned, in the range of a strip unbounded along the imaginary axis and in the interval [−π/2; +π/2] along the real axis.</p> +<p>Errors and special cases are handled as if the operation is implemented by <code><span class="sy2">-</span>I <span class="sy2">*</span> <a href="http://en.cppreference.com/w/c/numeric/complex/catanh"><span class="kw802">catanh</span></a><span class="br0">(</span>I<span class="sy2">*</span>z<span class="br0">)</span></code>.</p> +<h3 id="Notes"> Notes</h3> <p>Inverse tangent (or arc tangent) is a multivalued function and requires a branch cut on the complex plane. The branch cut is conventionally placed at the line segments (-∞i,-i) and (+i,+∞i) of the imaginary axis. The mathematical definition of the principal value of inverse tangent is atan z = -</p> +<span><span>1</span><span>/</span><span>2</span></span> i [ln(1 - iz) - ln (1 + iz] <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <float.h> +#include <complex.h> + +int main(void) +{ + double complex z = catan(2*I); + printf("catan(+0+2i) = %f%+fi\n", creal(z), cimag(z)); + + double complex z2 = catan(-conj(2*I)); // or CMPLX(-0.0, 2) + printf("catan(-0+2i) (the other side of the cut) = %f%+fi\n", creal(z2), cimag(z2)); + + double complex z3 = 2*catan(2*I*DBL_MAX); // or CMPLX(0, INFINITY) + printf("2*catan(+0+i*Inf) = %f%+fi\n", creal(z3), cimag(z3)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">catan(+0+2i) = 1.570796+0.549306i +catan(-0+2i) (the other side of the cut) = -1.570796+0.549306i +2*catan(+0+i*Inf) = 3.141593+0.000000i</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.5.3 The catan functions (p: 191) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.5.3 The catan functions (p: 173) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="casin" title="c/numeric/complex/casin"> <span class="t-lines"><span>casin</span><span>casinf</span><span>casinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc sine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="cacos" title="c/numeric/complex/cacos"> <span class="t-lines"><span>cacos</span><span>cacosf</span><span>cacosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc cosine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ctan" title="c/numeric/complex/ctan"> <span class="t-lines"><span>ctan</span><span>ctanf</span><span>ctanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex tangent <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../math/atan" title="c/numeric/math/atan"> <span class="t-lines"><span>atan</span><span>atanf</span><span>atanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc tangent (\({\small\arctan{x} }\)arctan(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/atan" title="cpp/numeric/complex/atan">C++ documentation</a></span> for <code>atan</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/catan" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/catan</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fcatanh.html b/devdocs/c/numeric%2Fcomplex%2Fcatanh.html new file mode 100644 index 00000000..23fd8cf7 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcatanh.html @@ -0,0 +1,78 @@ + <h1 id="firstHeading" class="firstHeading">catanhf, catanh, catanhl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float complex catanhf( float complex z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double complex catanh( double complex z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double complex catanhl( long double complex z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define atanh( z )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the complex arc hyperbolic tangent of <code>z</code> with branch cuts outside the interval [−1; +1] along the real axis.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>z</code> has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>catanhl</code> is called. if <code>z</code> has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>catanh</code> is called, if <code>z</code> has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>catanhf</code> is called. If <code>z</code> is real or integer, then the macro invokes the corresponding real function (<code>atanhf</code>, <code><a href="http://en.cppreference.com/w/c/numeric/math/atanh"><span class="kw681">atanh</span></a></code>, <code>atanhl</code>). If <code>z</code> is imaginary, then the macro invokes the corresponding real version of <code><a href="http://en.cppreference.com/w/c/numeric/math/atan"><span class="kw674">atan</span></a></code>, implementing the formula atanh(iy) = i atan(y), and the return type is imaginary.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> z </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the complex arc hyperbolic tangent of <code>z</code> is returned, in the range of a half-strip mathematically unbounded along the real axis and in the interval [−iπ/2; +iπ/2] along the imaginary axis.</p> +<h3 id="Error_handling_and_special_values"> Error handling and special values</h3> <p>Errors are reported consistent with <a href="../math/math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a></p> +<p>If the implementation supports IEEE floating-point arithmetic,</p> +<ul> +<li> <code>catanh<span class="br0">(</span><a href="http://en.cppreference.com/w/c/numeric/complex/conj"><span class="kw760">conj</span></a><span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span> <span class="sy1">==</span> <a href="http://en.cppreference.com/w/c/numeric/complex/conj"><span class="kw760">conj</span></a><span class="br0">(</span>catanh<span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span></code> </li> +<li> <code>catanh(-z) == -catanh(z)</code> </li> +<li> If <code>z</code> is <code>+0+0i</code>, the result is <code>+0+0i</code> </li> +<li> If <code>z</code> is <code>+0+NaNi</code>, the result is <code>+0+NaNi</code> </li> +<li> If <code>z</code> is <code>+1+0i</code>, the result is <code>+∞+0i</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_DIVBYZERO</a></code> is raised </li> +<li> If <code>z</code> is <code>x+∞i</code> (for any finite positive x), the result is <code>+0+iπ/2</code> </li> +<li> If <code>z</code> is <code>x+NaNi</code> (for any finite nonzero x), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> may be raised </li> +<li> If <code>z</code> is <code>+∞+yi</code> (for any finite positive y), the result is <code>+0+iπ/2</code> </li> +<li> If <code>z</code> is <code>+∞+∞i</code>, the result is <code>+0+iπ/2</code> </li> +<li> If <code>z</code> is <code>+∞+NaNi</code>, the result is <code>+0+NaNi</code> </li> +<li> If <code>z</code> is <code>NaN+yi</code> (for any finite y), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> may be raised </li> +<li> If <code>z</code> is <code>NaN+∞i</code>, the result is <code>±0+iπ/2</code> (the sign of the real part is unspecified) </li> +<li> If <code>z</code> is <code>NaN+NaNi</code>, the result is <code>NaN+NaNi</code> </li> +</ul> <h3 id="Notes"> Notes</h3> <p>Although the C standard names this function "complex arc hyperbolic tangent", the inverse functions of the hyperbolic functions are the area functions. Their argument is the area of a hyperbolic sector, not an arc. The correct name is "complex inverse hyperbolic tangent", and, less common, "complex area hyperbolic tangent".</p> +<p>Inverse hyperbolic tangent is a multivalued function and requires a branch cut on the complex plane. The branch cut is conventionally placed at the line segmentd (-∞,-1] and [+1,+∞) of the real axis. The mathematical definition of the principal value of the inverse hyperbolic tangent is atanh z =</p> +<span><span>ln(1+z)-ln(z-1)</span><span>/</span><span>2</span></span>. <p><br> For any z, atanh(z) =</p> +<span><span>atan(iz)</span><span>/</span><span>i</span></span> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <complex.h> + +int main(void) +{ + double complex z = catanh(2); + printf("catanh(+2+0i) = %f%+fi\n", creal(z), cimag(z)); + + double complex z2 = catanh(conj(2)); // or catanh(CMPLX(2, -0.0)) in C11 + printf("catanh(+2-0i) (the other side of the cut) = %f%+fi\n", creal(z2), cimag(z2)); + + // for any z, atanh(z) = atan(iz)/i + double complex z3 = catanh(1+2*I); + printf("catanh(1+2i) = %f%+fi\n", creal(z3), cimag(z3)); + double complex z4 = catan((1+2*I)*I)/I; + printf("catan(i * (1+2i))/i = %f%+fi\n", creal(z4), cimag(z4)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">catanh(+2+0i) = 0.549306+1.570796i +catanh(+2-0i) (the other side of the cut) = 0.549306-1.570796i +catanh(1+2i) = 0.173287+1.178097i +catan(i * (1+2i))/i = 0.173287+1.178097i</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.6.3 The catanh functions (p: 193) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> G.6.2.3 The catanh functions (p: 540-541) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.6.3 The catanh functions (p: 175) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> G.6.2.3 The catanh functions (p: 475-476) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="casinh" title="c/numeric/complex/casinh"> <span class="t-lines"><span>casinh</span><span>casinhf</span><span>casinhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc hyperbolic sine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="cacosh" title="c/numeric/complex/cacosh"> <span class="t-lines"><span>cacosh</span><span>cacoshf</span><span>cacoshl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc hyperbolic cosine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ctanh" title="c/numeric/complex/ctanh"> <span class="t-lines"><span>ctanh</span><span>ctanhf</span><span>ctanhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex hyperbolic tangent <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../math/atanh" title="c/numeric/math/atanh"> <span class="t-lines"><span>atanh</span><span>atanhf</span><span>atanhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes inverse hyperbolic tangent (\({\small\operatorname{artanh}{x} }\)artanh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/atanh" title="cpp/numeric/complex/atanh">C++ documentation</a></span> for <code>atanh</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/catanh" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/catanh</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fccos.html b/devdocs/c/numeric%2Fcomplex%2Fccos.html new file mode 100644 index 00000000..99cece77 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fccos.html @@ -0,0 +1,52 @@ + <h1 id="firstHeading" class="firstHeading">ccosf, ccos, ccosl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float complex ccosf( float complex z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double complex ccos( double complex z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double complex ccosl( long double complex z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define cos( z )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the complex cosine of <code>z</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>z</code> has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>ccosl</code> is called. if <code>z</code> has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>ccos</code> is called, if <code>z</code> has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>ccosf</code> is called. If <code>z</code> is real or integer, then the macro invokes the corresponding real function (<code>cosf</code>, <code><a href="http://en.cppreference.com/w/c/numeric/math/cos"><span class="kw670">cos</span></a></code>, <code>cosl</code>). If <code>z</code> is imaginary, then the macro invokes the corresponding real version of the function <code><a href="../math/cosh" title="c/numeric/math/cosh">cosh</a></code>, implementing the formula cos(iy) = cosh(y), and the return type is real.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> z </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the complex cosine of <code>z</code> is returned.</p> +<p>Errors and special cases are handled as if the operation is implemented by <code><a href="http://en.cppreference.com/w/c/numeric/complex/ccosh"><span class="kw805">ccosh</span></a><span class="br0">(</span>I<span class="sy2">*</span>z<span class="br0">)</span></code>.</p> +<h3 id="Notes"> Notes</h3> <p>The cosine is an entire function on the complex plane, and has no branch cuts. Mathematical definition of the cosine is cos z =</p> +<span><span>eiz+e-iz</span><span>/</span><span>2</span></span> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <complex.h> + +int main(void) +{ + double complex z = ccos(1); // behaves like real cosine along the real line + printf("cos(1+0i) = %f%+fi ( cos(1)=%f)\n", creal(z), cimag(z), cos(1)); + + double complex z2 = ccos(I); // behaves like real cosh along the imaginary line + printf("cos(0+1i) = %f%+fi (cosh(1)=%f)\n", creal(z2), cimag(z2), cosh(1)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">cos(1+0i) = 0.540302-0.000000i ( cos(1)=0.540302) +cos(0+1i) = 1.543081-0.000000i (cosh(1)=1.543081)</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.5.4 The ccos functions (p: 191) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.5.4 The ccos functions (p: 173) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="csin" title="c/numeric/complex/csin"> <span class="t-lines"><span>csin</span><span>csinf</span><span>csinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex sine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ctan" title="c/numeric/complex/ctan"> <span class="t-lines"><span>ctan</span><span>ctanf</span><span>ctanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex tangent <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="cacos" title="c/numeric/complex/cacos"> <span class="t-lines"><span>cacos</span><span>cacosf</span><span>cacosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc cosine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../math/cos" title="c/numeric/math/cos"> <span class="t-lines"><span>cos</span><span>cosf</span><span>cosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes cosine (\({\small\cos{x} }\)cos(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/cos" title="cpp/numeric/complex/cos">C++ documentation</a></span> for <code>cos</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/ccos" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/ccos</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fccosh.html b/devdocs/c/numeric%2Fcomplex%2Fccosh.html new file mode 100644 index 00000000..5c6efd4b --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fccosh.html @@ -0,0 +1,71 @@ + <h1 id="firstHeading" class="firstHeading">ccoshf, ccosh, ccoshl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float complex ccoshf( float complex z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double complex ccosh( double complex z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double complex ccoshl( long double complex z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define cosh( z )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the complex hyperbolic cosine of <code>z</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>z</code> has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>ccoshl</code> is called. if <code>z</code> has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>ccosh</code> is called, if <code>z</code> has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>ccoshf</code> is called. If <code>z</code> is real or integer, then the macro invokes the corresponding real function (<code>coshf</code>, <code><a href="http://en.cppreference.com/w/c/numeric/math/cosh"><span class="kw677">cosh</span></a></code>, <code>coshl</code>). If <code>z</code> is imaginary, then the macro invokes the corresponding real version of the function <code><a href="../math/cos" title="c/numeric/math/cos">cos</a></code>, implementing the formula cosh(iy) = cos(y), and the return type is real.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> z </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, complex hyperbolic cosine of <code>z</code> is returned</p> +<h3 id="Error_handling_and_special_values"> Error handling and special values</h3> <p>Errors are reported consistent with <a href="../math/math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a></p> +<p>If the implementation supports IEEE floating-point arithmetic,</p> +<ul> +<li> <code>ccosh<span class="br0">(</span><a href="http://en.cppreference.com/w/c/numeric/complex/conj"><span class="kw760">conj</span></a><span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span> <span class="sy1">==</span> <a href="http://en.cppreference.com/w/c/numeric/complex/conj"><span class="kw760">conj</span></a><span class="br0">(</span>ccosh<span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span></code> </li> +<li> <code>ccosh(z) == ccosh(-z)</code> </li> +<li> If <code>z</code> is <code>+0+0i</code>, the result is <code>1+0i</code> </li> +<li> If <code>z</code> is <code>+0+∞i</code>, the result is <code>NaN±0i</code> (the sign of the imaginary part is unspecified) and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised </li> +<li> If <code>z</code> is <code>+0+NaNi</code>, the result is <code>NaN±0i</code> (the sign of the imaginary part is unspecified) </li> +<li> If <code>z</code> is <code>x+∞i</code> (for any finite non-zero x), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised </li> +<li> If <code>z</code> is <code>x+NaNi</code> (for any finite non-zero x), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> may be raised </li> +<li> If <code>z</code> is <code>+∞+0i</code>, the result is <code>+∞+0i</code> </li> +<li> If <code>z</code> is <code>+∞+yi</code> (for any finite non-zero y), the result is <code>+∞cis(y)</code> </li> +<li> If <code>z</code> is <code>+∞+∞i</code>, the result is <code>±∞+NaNi</code> (the sign of the real part is unspecified) and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised </li> +<li> If <code>z</code> is <code>+∞+NaN</code>, the result is <code>+∞+NaN</code> </li> +<li> If <code>z</code> is <code>NaN+0i</code>, the result is <code>NaN±0i</code> (the sign of the imaginary part is unspecified) </li> +<li> If <code>z</code> is <code>NaN+yi</code> (for any finite non-zero y), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> may be raised </li> +<li> If <code>z</code> is <code>NaN+NaNi</code>, the result is <code>NaN+NaNi</code> </li> +</ul> <p>where cis(y) is cos(y) + i sin(y)</p> +<h3 id="Notes"> Notes</h3> Mathematical definition of hyperbolic cosine is cosh z = <span><span>ez+e-z</span><span>/</span><span>2</span></span> <p>Hyperbolic cosine is an entire function in the complex plane and has no branch cuts. It is periodic with respect to the imaginary component, with period 2πi</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <complex.h> + +int main(void) +{ + double complex z = ccosh(1); // behaves like real cosh along the real line + printf("cosh(1+0i) = %f%+fi (cosh(1)=%f)\n", creal(z), cimag(z), cosh(1)); + + double complex z2 = ccosh(I); // behaves like real cosine along the imaginary line + printf("cosh(0+1i) = %f%+fi ( cos(1)=%f)\n", creal(z2), cimag(z2), cos(1)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">cosh(1+0i) = 1.543081+0.000000i (cosh(1)=1.543081) +cosh(0+1i) = 0.540302+0.000000i ( cos(1)=0.540302)</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.6.4 The ccosh functions (p: 193) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> G.6.2.4 The ccosh functions (p: 541) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.6.4 The ccosh functions (p: 175) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> G.6.2.4 The ccosh functions (p: 476) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="csinh" title="c/numeric/complex/csinh"> <span class="t-lines"><span>csinh</span><span>csinhf</span><span>csinhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex hyperbolic sine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ctanh" title="c/numeric/complex/ctanh"> <span class="t-lines"><span>ctanh</span><span>ctanhf</span><span>ctanhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex hyperbolic tangent <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="cacosh" title="c/numeric/complex/cacosh"> <span class="t-lines"><span>cacosh</span><span>cacoshf</span><span>cacoshl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc hyperbolic cosine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../math/cosh" title="c/numeric/math/cosh"> <span class="t-lines"><span>cosh</span><span>coshf</span><span>coshl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes hyperbolic cosine (\({\small\cosh{x} }\)cosh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/cosh" title="cpp/numeric/complex/cosh">C++ documentation</a></span> for <code>cosh</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/ccosh" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/ccosh</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fcexp.html b/devdocs/c/numeric%2Fcomplex%2Fcexp.html new file mode 100644 index 00000000..a8c4195b --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcexp.html @@ -0,0 +1,66 @@ + <h1 id="firstHeading" class="firstHeading">cexpf, cexp, cexpl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float complex cexpf( float complex z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double complex cexp( double complex z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double complex cexpl( long double complex z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define exp( z )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the complex base-<i>e</i> exponential of <code>z</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>z</code> has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>cexpl</code> is called. if <code>z</code> has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>cexp</code> is called, if <code>z</code> has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>cexpf</code> is called. If <code>z</code> is real or integer, then the macro invokes the corresponding real function (<code>expf</code>, <code><a href="http://en.cppreference.com/w/c/numeric/math/exp"><span class="kw657">exp</span></a></code>, <code>expl</code>). If <code>z</code> is imaginary, the corresponding complex argument version is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> z </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, <i>e</i> raised to the power of <code>z</code>, \(\small e^z\)e<sup class="t-su">z</sup> is returned.</p> +<h3 id="Error_handling_and_special_values"> Error handling and special values</h3> <p>Errors are reported consistent with <a href="../math/math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic,</p> +<ul> +<li> <code>cexp<span class="br0">(</span><a href="http://en.cppreference.com/w/c/numeric/complex/conj"><span class="kw760">conj</span></a><span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span> <span class="sy1">==</span> <a href="http://en.cppreference.com/w/c/numeric/complex/conj"><span class="kw760">conj</span></a><span class="br0">(</span>cexp<span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span></code> </li> +<li> If <code>z</code> is <code>±0+0i</code>, the result is <code>1+0i</code> </li> +<li> If <code>z</code> is <code>x+∞i</code> (for any finite x), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised. </li> +<li> If <code>z</code> is <code>x+NaNi</code> (for any finite x), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> may be raised. </li> +<li> If <code>z</code> is <code>+∞+0i</code>, the result is <code>+∞+0i</code> </li> +<li> If <code>z</code> is <code>-∞+yi</code> (for any finite y), the result is <code>+0cis(y)</code> </li> +<li> If <code>z</code> is <code>+∞+yi</code> (for any finite nonzero y), the result is <code>+∞cis(y)</code> </li> +<li> If <code>z</code> is <code>-∞+∞i</code>, the result is <code>±0±0i</code> (signs are unspecified) </li> +<li> If <code>z</code> is <code>+∞+∞i</code>, the result is <code>±∞+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised (the sign of the real part is unspecified) </li> +<li> If <code>z</code> is <code>-∞+NaNi</code>, the result is <code>±0±0i</code> (signs are unspecified) </li> +<li> If <code>z</code> is <code>+∞+NaNi</code>, the result is <code>±∞+NaNi</code> (the sign of the real part is unspecified) </li> +<li> If <code>z</code> is <code>NaN+0i</code>, the result is <code>NaN+0i</code> </li> +<li> If <code>z</code> is <code>NaN+yi</code> (for any nonzero y), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> may be raised </li> +<li> If <code>z</code> is <code>NaN+NaNi</code>, the result is <code>NaN+NaNi</code> </li> +</ul> <p>where \(\small{\rm cis}(y)\)cis(y) is \(\small \cos(y)+{\rm i}\sin(y)\)cos(y) + i sin(y)</p> +<h3 id="Notes"> Notes</h3> <p>The complex exponential function \(\small e^z\)e<sup class="t-su">z</sup> for \(\small z = x + {\rm i}y\)z = x+iy equals \(\small e^x {\rm cis}(y)\)e<sup class="t-su">x</sup> cis(y), or, \(\small e^x (\cos(y)+{\rm i}\sin(y))\)e<sup class="t-su">x</sup> (cos(y) + i sin(y))</p> +<p>The exponential function is an <i>entire function</i> in the complex plane and has no branch cuts.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <complex.h> + +int main(void) +{ + double PI = acos(-1); + double complex z = cexp(I * PI); // Euler's formula + printf("exp(i*pi) = %.1f%+.1fi\n", creal(z), cimag(z)); + +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">exp(i*pi) = -1.0+0.0i</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.7.1 The cexp functions (p: 194) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> G.6.3.1 The cexp functions (p: 543) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.7.1 The cexp functions (p: 176) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> G.6.3.1 The cexp functions (p: 478) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="clog" title="c/numeric/complex/clog"> <span class="t-lines"><span>clog</span><span>clogf</span><span>clogl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex natural logarithm <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../math/exp" title="c/numeric/math/exp"> <span class="t-lines"><span>exp</span><span>expf</span><span>expl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes <i>e</i> raised to the given power (\({\small e^x}\)e<sup>x</sup>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/exp" title="cpp/numeric/complex/exp">C++ documentation</a></span> for <code>exp</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/cexp" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/cexp</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fcimag.html b/devdocs/c/numeric%2Fcomplex%2Fcimag.html new file mode 100644 index 00000000..4218e76c --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcimag.html @@ -0,0 +1,41 @@ + <h1 id="firstHeading" class="firstHeading">cimagf, cimag, cimagl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float cimagf( float complex z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double cimag( double complex z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double cimagl( long double complex z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define cimag( z )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Returns the imaginary part of <code>z</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: if <code>z</code> has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, or <code>long double</code>, <code>cimagl</code> is called. If <code>z</code> has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, or <code>float</code>, <code>cimagf</code> is called. If <code>z</code> has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, <code>double</code>, or any integer type, <code>cimag</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> z </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The imaginary part of <code>z</code>.</p> +<p>This function is fully specified for all possible inputs and is not subject to any errors described in <a href="../math/math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a></p> +<h3 id="Notes"> Notes</h3> <p>For any complex variable <code>z</code>, <code>z <span class="sy1">==</span> <a href="http://en.cppreference.com/w/c/numeric/complex/creal"><span class="kw751">creal</span></a><span class="br0">(</span>z<span class="br0">)</span> <span class="sy2">+</span> I<span class="sy2">*</span>cimag<span class="br0">(</span>z<span class="br0">)</span></code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <complex.h> + +int main(void) +{ + double complex z = 1.0 + 2.0*I; + printf("%f%+fi\n", creal(z), cimag(z)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">1.000000+2.000000i</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.9.2 The cimag functions (p: 197) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.9.2 The cimag functions (p: 178-179) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="creal" title="c/numeric/complex/creal"> <span class="t-lines"><span>creal</span><span>crealf</span><span>creall</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the real part of a complex number <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/imag2" title="cpp/numeric/complex/imag2">C++ documentation</a></span> for <code>imag</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/cimag" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/cimag</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fclog.html b/devdocs/c/numeric%2Fcomplex%2Fclog.html new file mode 100644 index 00000000..3cc04584 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fclog.html @@ -0,0 +1,74 @@ + <h1 id="firstHeading" class="firstHeading">clogf, clog, clogl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float complex clogf( float complex z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double complex clog( double complex z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double complex clogl( long double complex z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define log( z )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the complex natural (base-<i>e</i>) logarithm of <code>z</code> with branch cut along the negative real axis.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>z</code> has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>clogl</code> is called. if <code>z</code> has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>clog</code> is called, if <code>z</code> has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>clogf</code> is called. If <code>z</code> is real or integer, then the macro invokes the corresponding real function (<code>logf</code>, <code><a href="http://en.cppreference.com/w/c/numeric/math/log"><span class="kw660">log</span></a></code>, <code>logl</code>). If <code>z</code> is imaginary, the corresponding complex number version is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> z </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the complex natural logarithm of <code>z</code> is returned, in the range of a strip in the interval [−iπ, +iπ] along the imaginary axis and mathematically unbounded along the real axis.</p> +<h3 id="Error_handling_and_special_values"> Error handling and special values</h3> <p>Errors are reported consistent with <a href="../math/math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a></p> +<p>If the implementation supports IEEE floating-point arithmetic,</p> +<ul> +<li> The function is continuous onto the branch cut taking into account the sign of imaginary part </li> +<li> <code>clog<span class="br0">(</span><a href="http://en.cppreference.com/w/c/numeric/complex/conj"><span class="kw760">conj</span></a><span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span> <span class="sy1">==</span> <a href="http://en.cppreference.com/w/c/numeric/complex/conj"><span class="kw760">conj</span></a><span class="br0">(</span>clog<span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span></code> </li> +<li> If <code>z</code> is <code>-0+0i</code>, the result is <code>-∞+πi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_DIVBYZERO</a></code> is raised </li> +<li> If <code>z</code> is <code>+0+0i</code>, the result is <code>-∞+0i</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_DIVBYZERO</a></code> is raised </li> +<li> If <code>z</code> is <code>x+∞i</code> (for any finite x), the result is <code>+∞+πi/2</code> </li> +<li> If <code>z</code> is <code>x+NaNi</code> (for any finite x), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> may be raised </li> +<li> If <code>z</code> is <code>-∞+yi</code> (for any finite positive y), the result is <code>+∞+πi</code> </li> +<li> If <code>z</code> is <code>+∞+yi</code> (for any finite positive y), the result is <code>+∞+0i</code> </li> +<li> If <code>z</code> is <code>-∞+∞i</code>, the result is <code>+∞+3πi/4</code> </li> +<li> If <code>z</code> is <code>+∞+∞i</code>, the result is <code>+∞+πi/4</code> </li> +<li> If <code>z</code> is <code>±∞+NaNi</code>, the result is <code>+∞+NaNi</code> </li> +<li> If <code>z</code> is <code>NaN+yi</code> (for any finite y), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> may be raised </li> +<li> If <code>z</code> is <code>NaN+∞i</code>, the result is <code>+∞+NaNi</code> </li> +<li> If <code>z</code> is <code>NaN+NaNi</code>, the result is <code>NaN+NaNi</code> </li> +</ul> <h3 id="Notes"> Notes</h3> <p>The natural logarithm of a complex number z with polar coordinate components (r,θ) equals ln r + i(θ+2nπ), with the principal value ln r + iθ</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <complex.h> + +int main(void) +{ + double complex z = clog(I); // r = 1, θ = pi/2 + printf("2*log(i) = %.1f%+fi\n", creal(2*z), cimag(2*z)); + + double complex z2 = clog(sqrt(2)/2 + sqrt(2)/2*I); // r = 1, θ = pi/4 + printf("4*log(sqrt(2)/2+sqrt(2)i/2) = %.1f%+fi\n", creal(4*z2), cimag(4*z2)); + + double complex z3 = clog(-1); // r = 1, θ = pi + printf("log(-1+0i) = %.1f%+fi\n", creal(z3), cimag(z3)); + + double complex z4 = clog(conj(-1)); // or clog(CMPLX(-1, -0.0)) in C11 + printf("log(-1-0i) (the other side of the cut) = %.1f%+fi\n", creal(z4), cimag(z4)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">2*log(i) = 0.0+3.141593i +4*log(sqrt(2)/2+sqrt(2)i/2) = 0.0+3.141593i +log(-1+0i) = 0.0+3.141593i +log(-1-0i) (the other side of the cut) = 0.0-3.141593i</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.7.2 The clog functions (p: 195) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> G.6.3.2 The clog functions (p: 543-544) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.7.2 The clog functions (p: 176-177) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> G.6.3.2 The clog functions (p: 478-479) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="cexp" title="c/numeric/complex/cexp"> <span class="t-lines"><span>cexp</span><span>cexpf</span><span>cexpl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex base-e exponential <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../math/log" title="c/numeric/math/log"> <span class="t-lines"><span>log</span><span>logf</span><span>logl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes natural (base-<i>e</i>) logarithm (\({\small \ln{x} }\)ln(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/log" title="cpp/numeric/complex/log">C++ documentation</a></span> for <code>log</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/clog" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/clog</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fcmplx.html b/devdocs/c/numeric%2Fcomplex%2Fcmplx.html new file mode 100644 index 00000000..12dde11f --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcmplx.html @@ -0,0 +1,33 @@ + <h1 id="firstHeading" class="firstHeading">CMPLXF, CMPLX, CMPLXL</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">float complex CMPLXF( float real, float imag );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">double complex CMPLX( double real, double imag );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">long double complex CMPLXL( long double real, long double imag );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Each of these macros expands to an expression that evaluates to the value of the specified complex type, with the real part having the value of <code>real</code> (converted to the specified argument type) and the imaginary part having the value of <code>imag</code> (converted to the specified argument type)</p> +<p>The expressions are suitable for use as initializers for objects with static or thread storage duration, as long as the expressions <code>real</code> and <code>imag</code> are also suitable.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> real </td> <td> - </td> <td> the real part of the complex number to return </td> +</tr> <tr class="t-par"> <td> imag </td> <td> - </td> <td> the imaginary part of the complex number to return </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>A complex number composed of <code>real</code> and <code>imag</code> as the real and imaginary parts.</p> +<h3 id="Notes"> Notes</h3> <p>These macros are implemented as if the imaginary types are supported (even if they are otherwise not supported and <code><a href="imaginary_i" title="c/numeric/complex/Imaginary I">_Imaginary_I</a></code> is actually undefined) and as if defined as follows:</p> +<div class="c source-c"><pre data-language="c">#define CMPLX(x, y) ((double complex)((double)(x) + _Imaginary_I * (double)(y))) +#define CMPLXF(x, y) ((float complex)((float)(x) + _Imaginary_I * (float)(y))) +#define CMPLXL(x, y) ((long double complex)((long double)(x) + \ + _Imaginary_I * (long double)(y)))</pre></div> <h3 id="Example"> Example</h3> <div class="t-example t-example-std-c11"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <complex.h> + +int main(void) +{ + double complex z = CMPLX(0.0, -0.0); + printf("z = %.1f%+.1fi\n", creal(z), cimag(z)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">z = 0.0-0.0i</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.3.9.3 The CMPLX macros (p: 197) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="imaginary_i" title="c/numeric/complex/Imaginary I"> <span class="t-lines"><span>_Imaginary_I</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> the imaginary unit constant i <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/complex" title="cpp/numeric/complex/complex">C++ documentation</a></span> for <code>complex</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/CMPLX" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/CMPLX</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fcomplex.html b/devdocs/c/numeric%2Fcomplex%2Fcomplex.html new file mode 100644 index 00000000..9ca58d2c --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcomplex.html @@ -0,0 +1,37 @@ + <h1 id="firstHeading" class="firstHeading">complex</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define complex _Complex</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>This macro expands to a type specifier used to identify <a href="../../language/arithmetic_types#Complex_floating_types" title="c/language/arithmetic types">complex types</a>.</p> +<p>A program may undefine and perhaps then redefine the <code>complex</code> macro.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <complex.h> +#include <math.h> + +void print_complex(const char* note, complex z) +{ + printf("%s %f%+f*i\n", note, creal(z), cimag(z)); +} + +int main(void) +{ + double complex z = -1.0 + 2.0*I; + print_complex("z =", z); + print_complex("z\u00B2 =", z * z); + double complex z2 = ccos(2.0 * carg(z)) + csin(2.0 * carg(z))*I; + print_complex("z\u00B2 =", cabs(z) * cabs(z) * z2); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">z = -1.000000+2.000000*i +z² = -3.000000-4.000000*i +z² = -3.000000-4.000000*i</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.3.1/4 complex (p: 136) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.3.1/4 complex (p: 188) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.3.1/2 complex (p: 170) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="imaginary" title="c/numeric/complex/imaginary"> <span class="t-lines"><span>imaginary</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> imaginary type macro <br> <span class="t-mark">(keyword macro)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/complex" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/complex</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fcomplex_i.html b/devdocs/c/numeric%2Fcomplex%2Fcomplex_i.html new file mode 100644 index 00000000..9ccc4b52 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcomplex_i.html @@ -0,0 +1,40 @@ + <h1 id="firstHeading" class="firstHeading">_Complex_I</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define _Complex_I /* unspecified */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>The <code>_Complex_I</code> macro expands to a value of type <code>const float _Complex</code> with the value of the imaginary unit.</p> +<h3 id="Notes"> Notes</h3> <p>This macro may be used when <code>I</code> is not available, such as when it has been undefined by the application.</p> +<p>Unlike <code><a href="imaginary_i" title="c/numeric/complex/Imaginary I">_Imaginary_I</a></code> and <code><a href="cmplx" title="c/numeric/complex/CMPLX">CMPLX</a></code>, use of this macro to construct a complex number may lose the sign of zero on the imaginary part.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <complex.h> + +#undef I +#define J _Complex_I // can be used to redefine I + +int main(void) +{ + // can be used to construct a complex number + double complex z = 1.0 + 2.0 * _Complex_I; + printf("1.0 + 2.0 * _Complex_I = %.1f%+.1fi\n", creal(z), cimag(z)); + + // sign of zero may not be preserved + double complex z2 = 0.0 + -0.0 * _Complex_I; + printf("0.0 + -0.0 * _Complex_I = %.1f%+.1fi\n", creal(z2), cimag(z2)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">1.0 + 2.0 * _Complex_I = 1.0+2.0i +0.0 + -0.0 * _Complex_I = 0.0+0.0i</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.3.1/4 _Complex_I (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.3.1/4 _Complex_I (p: 136) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.3.1/4 _Complex_I (p: 188) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.3.1/2 _Complex_I (p: 170) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="imaginary_i" title="c/numeric/complex/Imaginary I"> <span class="t-lines"><span>_Imaginary_I</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> the imaginary unit constant i <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="i" title="c/numeric/complex/I"> <span class="t-lines"><span>I</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> the complex or imaginary unit constant i <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/Complex_I" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/Complex_I</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fconj.html b/devdocs/c/numeric%2Fcomplex%2Fconj.html new file mode 100644 index 00000000..f59d1427 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fconj.html @@ -0,0 +1,43 @@ + <h1 id="firstHeading" class="firstHeading">conjf, conj, conjl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float complex conjf( float complex z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double complex conj( double complex z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double complex conjl( long double complex z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define conj( z )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the <a href="https://en.wikipedia.org/wiki/Complex_conjugate" class="extiw" title="enwiki:Complex conjugate">complex conjugate</a> of <code>z</code> by reversing the sign of the imaginary part.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: if <code>z</code> has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, or <code>long double</code>, <code>conjl</code> is called. If <code>z</code> has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, or <code>float</code>, <code>conjf</code> is called. If <code>z</code> has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, <code>double</code>, or any integer type, <code>conj</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> z </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The complex conjugate of <code>z</code>.</p> +<h3 id="Notes"> Notes</h3> <p>On C99 implementations that do not implement <code>I</code> as <code><a href="imaginary_i" title="c/numeric/complex/Imaginary I">_Imaginary_I</a></code>, <code>conj</code> may be used to obtain complex numbers with negative zero imaginary part. In C11, the macro <code><a href="cmplx" title="c/numeric/complex/CMPLX">CMPLX</a></code> is used for that purpose.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <complex.h> + +int main(void) +{ + double complex z = 1.0 + 2.0*I; + double complex z2 = conj(z); + printf("The conjugate of %.1f%+.1fi is %.1f%+.1fi\n", + creal(z), cimag(z), creal(z2), cimag(z2)); + + printf("Their product is %.1f%+.1fi\n", creal(z*z2), cimag(z*z2)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">The conjugate of 1.0+2.0i is 1.0-2.0i +Their product is 5.0+0.0i</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.9.4 The conj functions (p: 198) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.9.3 The conj functions (p: 179) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/conj" title="cpp/numeric/complex/conj">C++ documentation</a></span> for <code>conj</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/conj" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/conj</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fcpow.html b/devdocs/c/numeric%2Fcomplex%2Fcpow.html new file mode 100644 index 00000000..6a1e6196 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcpow.html @@ -0,0 +1,56 @@ + <h1 id="firstHeading" class="firstHeading">cpowf, cpow, cpowl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float complex cpowf( float complex x, float complex y );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double complex cpow( double complex x, double complex y );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double complex cpowl( long double complex x, long double complex y );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define pow( x, y )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the complex power function x<sup class="t-su">y</sup>, with branch cut for the first parameter along the negative real axis.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If any argument has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>cpowl</code> is called. if any argument has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>cpow</code> is called, if any argument has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>cpowf</code> is called. If the arguments are real or integer, then the macro invokes the corresponding real function (<code>powf</code>, <code><a href="http://en.cppreference.com/w/c/numeric/math/pow"><span class="kw668">pow</span></a></code>, <code>powl</code>). If any argument is imaginary, the corresponding complex number version is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> x, y </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the complex power x<sup class="t-su">y</sup>, is returned.</p> +<p>Errors and special cases are handled as if the operation is implemented by <code><a href="http://en.cppreference.com/w/c/numeric/complex/cexp"><span class="kw769">cexp</span></a><span class="br0">(</span>y<span class="sy2">*</span><a href="http://en.cppreference.com/w/c/numeric/complex/clog"><span class="kw772">clog</span></a><span class="br0">(</span>x<span class="br0">)</span><span class="br0">)</span></code>, except that the implementation is allowed to treat special cases more carefully.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <complex.h> + +int main(void) +{ + double complex z = cpow(1.0+2.0*I, 2); + printf("(1+2i)^2 = %.1f%+.1fi\n", creal(z), cimag(z)); + + double complex z2 = cpow(-1, 0.5); + printf("(-1+0i)^0.5 = %.1f%+.1fi\n", creal(z2), cimag(z2)); + + double complex z3 = cpow(conj(-1), 0.5); // other side of the cut + printf("(-1-0i)^0.5 = %.1f%+.1fi\n", creal(z3), cimag(z3)); + + double complex z4 = cpow(I, I); // i^i = exp(-pi/2) + printf("i^i = %f%+fi\n", creal(z4), cimag(z4)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">(1+2i)^2 = -3.0+4.0i +(-1+0i)^0.5 = 0.0+1.0i +(-1-0i)^0.5 = 0.0-1.0i +i^i = 0.207880+0.000000i</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.8.2 The cpow functions (p: 195-196) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> G.6.4.1 The cpow functions (p: 544) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.8.2 The cpow functions (p: 177) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> G.6.4.1 The cpow functions (p: 479) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="csqrt" title="c/numeric/complex/csqrt"> <span class="t-lines"><span>csqrt</span><span>csqrtf</span><span>csqrtl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex square root <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../math/pow" title="c/numeric/math/pow"> <span class="t-lines"><span>pow</span><span>powf</span><span>powl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes a number raised to the given power (\(\small{x^y}\)x<sup>y</sup>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/pow" title="cpp/numeric/complex/pow">C++ documentation</a></span> for <code>pow</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/cpow" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/cpow</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fcproj.html b/devdocs/c/numeric%2Fcomplex%2Fcproj.html new file mode 100644 index 00000000..f74622ea --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcproj.html @@ -0,0 +1,49 @@ + <h1 id="firstHeading" class="firstHeading">cprojf, cproj, cprojl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float complex cprojf( float complex z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double complex cproj( double complex z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double complex cprojl( long double complex z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define cproj( z )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the projection of <code>z</code> on the Riemann sphere.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: if <code>z</code> has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, or <code>long double</code>, <code>cprojl</code> is called. If <code>z</code> has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, or <code>float</code>, <code>cprojf</code> is called. If <code>z</code> has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, <code>double</code>, or any integer type, <code>cproj</code> is called.</div> <p>For most <code>z</code>, <code>cproj(z)==z</code>, but all complex infinities, even the numbers where one component is infinite and the other is NaN, become positive real infinity, <code>INFINITY+0.0*I</code> or <code>INFINITY-0.0*I</code>. The sign of the imaginary (zero) component is the sign of <code><a href="http://en.cppreference.com/w/c/numeric/complex/cimag"><span class="kw751">cimag</span></a><span class="br0">(</span>z<span class="br0">)</span></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> z </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The projection of <code>z</code> on the Riemann sphere.</p> +<p>This function is fully specified for all possible inputs and is not subject to any errors described in <a href="../math/math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a></p> +<h3 id="Notes"> Notes</h3> <p>The <code>cproj</code> function helps model the Riemann sphere by mapping all infinities to one (give or take the sign of the imaginary zero), and should be used just before any operation, especially comparisons, that might give spurious results for any of the other infinities.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <complex.h> +#include <math.h> + +int main(void) +{ + double complex z1 = cproj(1 + 2*I); + printf("cproj(1+2i) = %.1f%+.1fi\n", creal(z1),cimag(z1)); + + double complex z2 = cproj(INFINITY+2.0*I); + printf("cproj(Inf+2i) = %.1f%+.1fi\n", creal(z2),cimag(z2)); + + double complex z3 = cproj(INFINITY-2.0*I); + printf("cproj(Inf-2i) = %.1f%+.1fi\n", creal(z3),cimag(z3)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">cproj(1+2i) = 1.0+2.0i +cproj(Inf+2i) = inf+0.0i +cproj(Inf-2i) = inf-0.0i</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.9.5 The cproj functions (p: 198) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.9.4 The cproj functions (p: 179) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/proj" title="cpp/numeric/complex/proj">C++ documentation</a></span> for <code>proj</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/cproj" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/cproj</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fcreal.html b/devdocs/c/numeric%2Fcomplex%2Fcreal.html new file mode 100644 index 00000000..e0d77c3f --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcreal.html @@ -0,0 +1,41 @@ + <h1 id="firstHeading" class="firstHeading">crealf, creal, creall</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float crealf( float complex z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double creal( double complex z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double creall( long double complex z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define creal( z )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Returns the real part of <code>z</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: if <code>z</code> has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, or <code>long double</code>, <code>creall</code> is called. If <code>z</code> has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, or <code>float</code>, <code>crealf</code> is called. If <code>z</code> has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, <code>double</code>, or any integer type, <code>creal</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> z </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The real part of <code>z</code>.</p> +<p>This function is fully specified for all possible inputs and is not subject to any errors described in <a href="../math/math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a></p> +<h3 id="Notes"> Notes</h3> <p>For any complex variable <code>z</code>, <code>z <span class="sy1">==</span> creal<span class="br0">(</span>z<span class="br0">)</span> <span class="sy2">+</span> I<span class="sy2">*</span><a href="http://en.cppreference.com/w/c/numeric/complex/cimag"><span class="kw751">cimag</span></a><span class="br0">(</span>z<span class="br0">)</span></code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <complex.h> + +int main(void) +{ + double complex z = 1.0 + 2.0*I; + printf("%f%+fi\n", creal(z), cimag(z)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">1.000000+2.000000i</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.9.6 The creal functions (p: 198-199) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.9.5 The creal functions (p: 180) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="cimag" title="c/numeric/complex/cimag"> <span class="t-lines"><span>cimag</span><span>cimagf</span><span>cimagl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the imaginary part a complex number <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/real2" title="cpp/numeric/complex/real2">C++ documentation</a></span> for <code>real</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/creal" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/creal</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fcsin.html b/devdocs/c/numeric%2Fcomplex%2Fcsin.html new file mode 100644 index 00000000..5e69806e --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcsin.html @@ -0,0 +1,58 @@ + <h1 id="firstHeading" class="firstHeading">csinf, csin, csinl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float complex csinf( float complex z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double complex csin( double complex z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double complex csinl( long double complex z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define sin( z )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the complex sine of <code>z</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>z</code> has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>csinl</code> is called. if <code>z</code> has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>csin</code> is called, if <code>z</code> has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>csinf</code> is called. If <code>z</code> is real or integer, then the macro invokes the corresponding real function (<code>sinf</code>, <code><a href="http://en.cppreference.com/w/c/numeric/math/sin"><span class="kw669">sin</span></a></code>, <code>sinl</code>). If <code>z</code> is imaginary, then the macro invokes the corresponding real version of the function <code><a href="../math/sinh" title="c/numeric/math/sinh">sinh</a></code>, implementing the formula sin(iy) = i ∙ sinh(y), and the return type of the macro is imaginary.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> z </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the complex sine of <code>z</code>.</p> +<p>Errors and special cases are handled as if the operation is implemented by <code><span class="sy2">-</span>I <span class="sy2">*</span> <a href="http://en.cppreference.com/w/c/numeric/complex/csinh"><span class="kw808">csinh</span></a><span class="br0">(</span>I<span class="sy2">*</span>z<span class="br0">)</span></code></p> +<h3 id="Notes"> Notes</h3> <p>The sine is an entire function on the complex plane, and has no branch cuts. Mathematical definition of the sine is sin z =</p> +<span><span>eiz-e-iz</span><span>/</span><span>2i</span></span> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <complex.h> + +int main(void) +{ + double complex z = csin(1); // behaves like real sine along the real line + printf("sin(1+0i) = %f%+fi ( sin(1)=%f)\n", creal(z), cimag(z), sin(1)); + + double complex z2 = csin(I); // behaves like sinh along the imaginary line + printf("sin(0+1i) = %f%+fi (sinh(1)=%f)\n", creal(z2), cimag(z2), sinh(1)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">sin(1+0i) = 0.841471+0.000000i ( sin(1)=0.841471) +sin(0+1i) = 0.000000+1.175201i (sinh(1)=1.175201)</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.3.5.5 The csin functions (p: 138-139) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 397) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.5.5 The csin functions (p: 191-192) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.5.5 The csin functions (p: 173) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="ccos" title="c/numeric/complex/ccos"> <span class="t-lines"><span>ccos</span><span>ccosf</span><span>ccosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex cosine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ctan" title="c/numeric/complex/ctan"> <span class="t-lines"><span>ctan</span><span>ctanf</span><span>ctanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex tangent <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="casin" title="c/numeric/complex/casin"> <span class="t-lines"><span>casin</span><span>casinf</span><span>casinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc sine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../math/sin" title="c/numeric/math/sin"> <span class="t-lines"><span>sin</span><span>sinf</span><span>sinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes sine (\({\small\sin{x} }\)sin(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/sin" title="cpp/numeric/complex/sin">C++ documentation</a></span> for <code>sin</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/csin" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/csin</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fcsinh.html b/devdocs/c/numeric%2Fcomplex%2Fcsinh.html new file mode 100644 index 00000000..49d937e5 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcsinh.html @@ -0,0 +1,71 @@ + <h1 id="firstHeading" class="firstHeading">csinhf, csinh, csinhl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float complex csinhf( float complex z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double complex csinh( double complex z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double complex csinhl( long double complex z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define sinh( z )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the complex hyperbolic sine of <code>z</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>z</code> has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>csinhl</code> is called. if <code>z</code> has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>csinh</code> is called, if <code>z</code> has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>csinhf</code> is called. If <code>z</code> is real or integer, then the macro invokes the corresponding real function (<code>sinhf</code>, <code><a href="http://en.cppreference.com/w/c/numeric/math/sinh"><span class="kw676">sinh</span></a></code>, <code>sinhl</code>). If <code>z</code> is imaginary, then the macro invokes the corresponding real version of the function <code><a href="../math/sin" title="c/numeric/math/sin">sin</a></code>, implementing the formula sinh(iy) = i sin(y), and the return type is imaginary.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> z </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, complex hyperbolic sine of <code>z</code> is returned</p> +<h3 id="Error_handling_and_special_values"> Error handling and special values</h3> <p>Errors are reported consistent with <a href="../math/math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a></p> +<p>If the implementation supports IEEE floating-point arithmetic,</p> +<ul> +<li> <code>csinh<span class="br0">(</span><a href="http://en.cppreference.com/w/c/numeric/complex/conj"><span class="kw760">conj</span></a><span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span> <span class="sy1">==</span> <a href="http://en.cppreference.com/w/c/numeric/complex/conj"><span class="kw760">conj</span></a><span class="br0">(</span>csinh<span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span></code> </li> +<li> <code>csinh(z) == -csinh(-z)</code> </li> +<li> If <code>z</code> is <code>+0+0i</code>, the result is <code>+0+0i</code> </li> +<li> If <code>z</code> is <code>+0+∞i</code>, the result is <code>±0+NaNi</code> (the sign of the real part is unspecified) and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised </li> +<li> If <code>z</code> is <code>+0+NaNi</code>, the result is <code>±0+NaNi</code> </li> +<li> If <code>z</code> is <code>x+∞i</code> (for any positive finite x), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised </li> +<li> If <code>z</code> is <code>x+NaNi</code> (for any positive finite x), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> may be raised </li> +<li> If <code>z</code> is <code>+∞+0i</code>, the result is <code>+∞+0i</code> </li> +<li> If <code>z</code> is <code>+∞+yi</code> (for any positive finite y), the result is <code>+∞cis(y)</code> </li> +<li> If <code>z</code> is <code>+∞+∞i</code>, the result is <code>±∞+NaNi</code> (the sign of the real part is unspecified) and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised </li> +<li> If <code>z</code> is <code>+∞+NaNi</code>, the result is <code>±∞+NaNi</code> (the sign of the real part is unspecified) </li> +<li> If <code>z</code> is <code>NaN+0i</code>, the result is <code>NaN+0i</code> </li> +<li> If <code>z</code> is <code>NaN+yi</code> (for any finite nonzero y), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> may be raised </li> +<li> If <code>z</code> is <code>NaN+NaNi</code>, the result is <code>NaN+NaNi</code> </li> +</ul> <p>where cis(y) is cos(y) + i sin(y)</p> +<h3 id="Notes"> Notes</h3> Mathematical definition of hyperbolic sine is sinh z = <span><span>ez-e-z</span><span>/</span><span>2</span></span> <p>Hyperbolic sine is an entire function in the complex plane and has no branch cuts. It is periodic with respect to the imaginary component, with period 2πi</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <complex.h> + +int main(void) +{ + double complex z = csinh(1); // behaves like real sinh along the real line + printf("sinh(1+0i) = %f%+fi (sinh(1)=%f)\n", creal(z), cimag(z), sinh(1)); + + double complex z2 = csinh(I); // behaves like sine along the imaginary line + printf("sinh(0+1i) = %f%+fi ( sin(1)=%f)\n", creal(z2), cimag(z2), sin(1)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">sinh(1+0i) = 1.175201+0.000000i (sinh(1)=1.175201) +sinh(0+1i) = 0.000000+0.841471i ( sin(1)=0.841471)</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.6.5 The csinh functions (p: 194) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> G.6.2.5 The csinh functions (p: 541-542) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.6.5 The csinh functions (p: 175-176) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> G.6.2.5 The csinh functions (p: 476-477) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="ccosh" title="c/numeric/complex/ccosh"> <span class="t-lines"><span>ccosh</span><span>ccoshf</span><span>ccoshl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex hyperbolic cosine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ctanh" title="c/numeric/complex/ctanh"> <span class="t-lines"><span>ctanh</span><span>ctanhf</span><span>ctanhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex hyperbolic tangent <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="casinh" title="c/numeric/complex/casinh"> <span class="t-lines"><span>casinh</span><span>casinhf</span><span>casinhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc hyperbolic sine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../math/sinh" title="c/numeric/math/sinh"> <span class="t-lines"><span>sinh</span><span>sinhf</span><span>sinhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes hyperbolic sine (\({\small\sinh{x} }\)sinh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/sinh" title="cpp/numeric/complex/sinh">C++ documentation</a></span> for <code>sinh</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/csinh" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/csinh</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fcsqrt.html b/devdocs/c/numeric%2Fcomplex%2Fcsqrt.html new file mode 100644 index 00000000..66c0b835 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fcsqrt.html @@ -0,0 +1,62 @@ + <h1 id="firstHeading" class="firstHeading">csqrtf, csqrt, csqrtl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float complex csqrtf( float complex z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double complex csqrt( double complex z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double complex csqrtl( long double complex z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define sqrt( z )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the complex square root of <code>z</code> with branch cut along the negative real axis.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>z</code> has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>csqrtl</code> is called. if <code>z</code> has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>csqrt</code> is called, if <code>z</code> has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>csqrtf</code> is called. If <code>z</code> is real or integer, then the macro invokes the corresponding real function (<code>sqrtf</code>, <code><a href="http://en.cppreference.com/w/c/numeric/math/sqrt"><span class="kw665">sqrt</span></a></code>, <code>sqrtl</code>). If <code>z</code> is imaginary, the corresponding complex number version is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> z </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, returns the square root of <code>z</code>, in the range of the right half-plane, including the imaginary axis ([0; +∞) along the real axis and (−∞; +∞) along the imaginary axis.)</p> +<h3 id="Error_handling_and_special_values"> Error handling and special values</h3> <p>Errors are reported consistent with <a href="../math/math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a></p> +<p>If the implementation supports IEEE floating-point arithmetic,</p> +<ul> +<li> The function is continuous onto the branch cut taking into account the sign of imaginary part </li> +<li> <code>csqrt<span class="br0">(</span><a href="http://en.cppreference.com/w/c/numeric/complex/conj"><span class="kw760">conj</span></a><span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span> <span class="sy1">==</span> <a href="http://en.cppreference.com/w/c/numeric/complex/conj"><span class="kw760">conj</span></a><span class="br0">(</span>csqrt<span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span></code> </li> +<li> If <code>z</code> is <code>±0+0i</code>, the result is <code>+0+0i</code> </li> +<li> If <code>z</code> is <code>x+∞i</code>, the result is <code>+∞+∞i</code> even if x is NaN </li> +<li> If <code>z</code> is <code>x+NaNi</code>, the result is <code>NaN+NaNi</code> (unless x is ±∞) and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> may be raised </li> +<li> If <code>z</code> is <code>-∞+yi</code>, the result is <code>+0+∞i</code> for finite positive y </li> +<li> If <code>z</code> is <code>+∞+yi</code>, the result is <code>+∞+0i)</code> for finite positive y </li> +<li> If <code>z</code> is <code>-∞+NaNi</code>, the result is <code>NaN±∞i</code> (sign of imaginary part unspecified) </li> +<li> If <code>z</code> is <code>+∞+NaNi</code>, the result is <code>+∞+NaNi</code> </li> +<li> If <code>z</code> is <code>NaN+yi</code>, the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> may be raised </li> +<li> If <code>z</code> is <code>NaN+NaNi</code>, the result is <code>NaN+NaNi</code> </li> +</ul> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <complex.h> + +int main(void) +{ + double complex z1 = csqrt(-4); + printf("Square root of -4 is %.1f%+.1fi\n", creal(z1), cimag(z1)); + + double complex z2 = csqrt(conj(-4)); // or, in C11, CMPLX(-4, -0.0) + printf("Square root of -4-0i, the other side of the cut, is " + "%.1f%+.1fi\n", creal(z2), cimag(z2)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Square root of -4 is 0.0+2.0i +Square root of -4-0i, the other side of the cut, is 0.0-2.0i</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.8.3 The csqrt functions (p: 196) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> G.6.4.2 The csqrt functions (p: 544) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.8.3 The csqrt functions (p: 178) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> G.6.4.2 The csqrt functions (p: 479) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="cpow" title="c/numeric/complex/cpow"> <span class="t-lines"><span>cpow</span><span>cpowf</span><span>cpowl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex power function <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../math/sqrt" title="c/numeric/math/sqrt"> <span class="t-lines"><span>sqrt</span><span>sqrtf</span><span>sqrtl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes square root (\(\small{\sqrt{x} }\)<span class="t-mrad"><span>√</span><span>x</span></span>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/sqrt" title="cpp/numeric/complex/sqrt">C++ documentation</a></span> for <code>sqrt</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/csqrt" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/csqrt</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fctan.html b/devdocs/c/numeric%2Fcomplex%2Fctan.html new file mode 100644 index 00000000..7eff9416 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fctan.html @@ -0,0 +1,54 @@ + <h1 id="firstHeading" class="firstHeading">ctanf, ctan, ctanl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float complex ctanf( float complex z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double complex ctan( double complex z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double complex ctanl( long double complex z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define tan( z )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the complex tangent of <code>z</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>z</code> has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>ctanl</code> is called. if <code>z</code> has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>ctan</code> is called, if <code>z</code> has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>ctanf</code> is called. If <code>z</code> is real or integer, then the macro invokes the corresponding real function (<code>tanf</code>, <code><a href="http://en.cppreference.com/w/c/numeric/math/tan"><span class="kw671">tan</span></a></code>, <code>tanl</code>). If <code>z</code> is imaginary, then the macro invokes the corresponding real version of the function <code><a href="../math/tanh" title="c/numeric/math/tanh">tanh</a></code>, implementing the formula tan(iy) = i tanh(y), and the return type is imaginary.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> z </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the complex tangent of <code>z</code> is returned.</p> +<p>Errors and special cases are handled as if the operation is implemented by <code><span class="sy2">-</span>i <span class="sy2">*</span> <a href="http://en.cppreference.com/w/c/numeric/complex/ctanh"><span class="kw811">ctanh</span></a><span class="br0">(</span>i<span class="sy2">*</span>z<span class="br0">)</span></code>, where <code>i</code> is the imaginary unit.</p> +<h3 id="Notes"> Notes</h3> <p>Tangent is an analytical function on the complex plain and has no branch cuts. It is periodic with respect to the real component, with period πi, and has poles of the first order along the real line, at coordinates (π(1/2 + n), 0). However no common floating-point representation is able to represent π/2 exactly, thus there is no value of the argument for which a pole error occurs. Mathematical definition of the tangent is tan z =</p> +<span><span>i(e-iz-eiz)</span><span>/</span><span>e-iz+eiz</span></span> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <complex.h> + +int main(void) +{ + double complex z = ctan(1); // behaves like real tangent along the real line + printf("tan(1+0i) = %f%+fi ( tan(1)=%f)\n", creal(z), cimag(z), tan(1)); + + double complex z2 = ctan(I); // behaves like tanh along the imaginary line + printf("tan(0+1i) = %f%+fi (tanh(1)=%f)\n", creal(z2), cimag(z2), tanh(1)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">tan(1+0i) = 1.557408+0.000000i ( tan(1)=1.557408) +tan(0+1i) = 0.000000+0.761594i (tanh(1)=0.761594)</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.5.6 The ctan functions (p: 192) </li> +<li> 7.25 Type-generic complex <tgmath.h> (p: 373-375) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.5.6 The ctan functions (p: 174) </li> +<li> 7.22 Type-generic complex <tgcomplex.h> (p: 335-337) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="ctanh" title="c/numeric/complex/ctanh"> <span class="t-lines"><span>ctanh</span><span>ctanhf</span><span>ctanhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex hyperbolic tangent <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="csin" title="c/numeric/complex/csin"> <span class="t-lines"><span>csin</span><span>csinf</span><span>csinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex sine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ccos" title="c/numeric/complex/ccos"> <span class="t-lines"><span>ccos</span><span>ccosf</span><span>ccosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex cosine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="catan" title="c/numeric/complex/catan"> <span class="t-lines"><span>catan</span><span>catanf</span><span>catanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc tangent <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../math/tan" title="c/numeric/math/tan"> <span class="t-lines"><span>tan</span><span>tanf</span><span>tanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes tangent (\({\small\tan{x} }\)tan(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/tan" title="cpp/numeric/complex/tan">C++ documentation</a></span> for <code>tan</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/ctan" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/ctan</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fctanh.html b/devdocs/c/numeric%2Fcomplex%2Fctanh.html new file mode 100644 index 00000000..d3d586b4 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fctanh.html @@ -0,0 +1,67 @@ + <h1 id="firstHeading" class="firstHeading">ctanhf, ctanh, ctanhl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float complex ctanhf( float complex z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double complex ctanh( double complex z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double complex ctanhl( long double complex z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define tanh( z )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the complex hyperbolic tangent of <code>z</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>z</code> has type <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>ctanhl</code> is called. if <code>z</code> has type <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>ctanh</code> is called, if <code>z</code> has type <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code>ctanhf</code> is called. If <code>z</code> is real or integer, then the macro invokes the corresponding real function (<code>tanhf</code>, <code><a href="http://en.cppreference.com/w/c/numeric/math/tanh"><span class="kw678">tanh</span></a></code>, <code>tanhl</code>). If <code>z</code> is imaginary, then the macro invokes the corresponding real version of the function <code><a href="../math/tan" title="c/numeric/math/tan">tan</a></code>, implementing the formula tanh(iy) = i tan(y), and the return type is imaginary.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> z </td> <td> - </td> <td> complex argument </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, complex hyperbolic tangent of <code>z</code> is returned</p> +<h3 id="Error_handling_and_special_values"> Error handling and special values</h3> <p>Errors are reported consistent with <a href="../math/math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a></p> +<p>If the implementation supports IEEE floating-point arithmetic,</p> +<ul> +<li> <code>ctanh<span class="br0">(</span><a href="http://en.cppreference.com/w/c/numeric/complex/conj"><span class="kw760">conj</span></a><span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span> <span class="sy1">==</span> <a href="http://en.cppreference.com/w/c/numeric/complex/conj"><span class="kw760">conj</span></a><span class="br0">(</span>ctanh<span class="br0">(</span>z<span class="br0">)</span><span class="br0">)</span></code> </li> +<li> <code>ctanh(-z) == -ctanh(z)</code> </li> +<li> If <code>z</code> is <code>+0+0i</code>, the result is <code>+0+0i</code> </li> +<li> If <code>z</code> is <code>x+∞i</code> (for any<sup id="cite_ref-1" class="reference"><a href="#cite_note-1">[1]</a></sup> finite x), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised </li> +<li> If <code>z</code> is <code>x+NaN</code> (for any<sup id="cite_ref-2" class="reference"><a href="#cite_note-2">[2]</a></sup> finite x), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> may be raised </li> +<li> If <code>z</code> is <code>+∞+yi</code> (for any finite positive y), the result is <code>1+0i</code> </li> +<li> If <code>z</code> is <code>+∞+∞i</code>, the result is <code>1±0i</code> (the sign of the imaginary part is unspecified) </li> +<li> If <code>z</code> is <code>+∞+NaNi</code>, the result is <code>1±0i</code> (the sign of the imaginary part is unspecified) </li> +<li> If <code>z</code> is <code>NaN+0i</code>, the result is <code>NaN+0i</code> </li> +<li> If <code>z</code> is <code>NaN+yi</code> (for any non-zero y), the result is <code>NaN+NaNi</code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> may be raised </li> +<li> If <code>z</code> is <code>NaN+NaNi</code>, the result is <code>NaN+NaNi</code> </li> +</ul> <ol class="references"> <li id="cite_note-1"> <span class="reference-text">per <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1892.htm#dr_471">DR471</a>, this only holds for non-zero x. If <code>z</code> is <code>0+∞i</code>, the result should be <code>0+NaNi</code></span> </li> <li id="cite_note-2"> <span class="reference-text">per <a rel="nofollow" class="external text" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1892.htm#dr_471">DR471</a>, this only holds for non-zero x. If <code>z</code> is <code>0+NaNi</code>, the result should be <code>0+NaNi</code></span> </li> </ol> <h3 id="Notes"> Notes</h3> Mathematical definition of hyperbolic tangent is tanh z = <span><span>ez-e-z</span><span>/</span><span>ez+e-z</span></span> <p>Hyperbolic tangent is an analytical function on the complex plane and has no branch cuts. It is periodic with respect to the imaginary component, with period πi, and has poles of the first order along the imaginary line, at coordinates (0, π(1/2 + n)). However no common floating-point representation is able to represent π/2 exactly, thus there is no value of the argument for which a pole error occurs.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <complex.h> + +int main(void) +{ + double complex z = ctanh(1); // behaves like real tanh along the real line + printf("tanh(1+0i) = %f%+fi (tanh(1)=%f)\n", creal(z), cimag(z), tanh(1)); + + double complex z2 = ctanh(I); // behaves like tangent along the imaginary line + printf("tanh(0+1i) = %f%+fi ( tan(1)=%f)\n", creal(z2), cimag(z2), tan(1)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">tanh(1+0i) = 0.761594+0.000000i (tanh(1)=0.761594) +tanh(0+1i) = 0.000000+1.557408i ( tan(1)=1.557408)</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.6.6 The ctanh functions (p: 194) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> G.6.2.6 The ctanh functions (p: 542) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.6.6 The ctanh functions (p: 176) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> G.6.2.6 The ctanh functions (p: 477) </li> +<li> G.7 Type-generic math <tgmath.h> (p: 480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="csinh" title="c/numeric/complex/csinh"> <span class="t-lines"><span>csinh</span><span>csinhf</span><span>csinhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex hyperbolic sine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ccosh" title="c/numeric/complex/ccosh"> <span class="t-lines"><span>ccosh</span><span>ccoshf</span><span>ccoshl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex hyperbolic cosine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="catanh" title="c/numeric/complex/catanh"> <span class="t-lines"><span>catanh</span><span>catanhf</span><span>catanhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc hyperbolic tangent <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../math/tanh" title="c/numeric/math/tanh"> <span class="t-lines"><span>tanh</span><span>tanhf</span><span>tanhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes hyperbolic tangent (\({\small\tanh{x} }\)tanh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/tanh" title="cpp/numeric/complex/tanh">C++ documentation</a></span> for <code>tanh</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/ctanh" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/ctanh</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fi.html b/devdocs/c/numeric%2Fcomplex%2Fi.html new file mode 100644 index 00000000..d1d3f90d --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fi.html @@ -0,0 +1,45 @@ + <h1 id="firstHeading" class="firstHeading">I </h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define I /* unspecified */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>The <code>I</code> macro expands to either <code><a href="complex_i" title="c/numeric/complex/Complex I">_Complex_I</a></code> or <code><a href="imaginary_i" title="c/numeric/complex/Imaginary I">_Imaginary_I</a></code>. If the implementation does not support imaginary types, then the macro always expands to <code><a href="complex_i" title="c/numeric/complex/Complex I">_Complex_I</a></code>.</p> +<p>A program may undefine and perhaps then redefine the macro <code>I</code>.</p> +<h3 id="Notes"> Notes</h3> <p>The macro is not named <code>i</code>, which is the name of the imaginary unit in mathematics, because the name <code>i</code> was already used in many C programs, e.g. as a loop counter variable.</p> +<p>The macro <code>I</code> is often used to form complex numbers, with expressions such as <code>x + y*I</code>. If <code>I</code> is defined as <code><a href="complex_i" title="c/numeric/complex/Complex I">_Complex_I</a></code>, then such expression may create a value with imaginary component <code>+0.0</code> even when <code>y</code> is <code>-0.0</code>, which is significant for complex number functions with branch cuts. The macro <code><a href="cmplx" title="c/numeric/complex/CMPLX">CMPLX</a></code> provides a way to construct a complex number precisely.</p> +<p>GCC provides a non-portable extension that allows imaginary constants to be specified with the suffix <code>i</code> on integer literals: <code>1.0fi</code>, <code>1.0i</code>, and <code>1.0li</code> are imaginary units in GNU C. A similar approach is part of standard C++ as of C++14 (<code>1.0if</code>, <code>1.0i</code>, and <code>1.0il</code> are the imaginary units in C++)</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <complex.h> + +int main(void) +{ + printf("I = %.1f%+.1fi\n", creal(I), cimag(I)); + + double complex z1 = I * I; // imaginary unit squared + printf("I * I = %.1f%+.1fi\n", creal(z1), cimag(z1)); + + double complex z = 1.0 + 2.0*I; // usual way to form a complex number pre-C11 + printf("z = %.1f%+.1fi\n", creal(z), cimag(z)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">I = 0.0+1.0i +I * I = -1.0+0.0i +z = 1.0+2.0i</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.1/6 I (p: 188) </li> +<li> G.6/1 I (p: 537) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.1/4 I (p: 170) </li> +<li> G.6/1 I (p: 472) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="imaginary_i" title="c/numeric/complex/Imaginary I"> <span class="t-lines"><span>_Imaginary_I</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> the imaginary unit constant i <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex_i" title="c/numeric/complex/Complex I"> <span class="t-lines"><span>_Complex_I</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> the complex unit constant i <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="cmplx" title="c/numeric/complex/CMPLX"> <span class="t-lines"><span>CMPLX</span><span>CMPLXF</span><span>CMPLXL</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> constructs a complex number from real and imaginary parts <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex/operator%22%22i" title='cpp/numeric/complex/operator""i'>C++ documentation</a></span> for <code>operator""i</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/I" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/I</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fimaginary.html b/devdocs/c/numeric%2Fcomplex%2Fimaginary.html new file mode 100644 index 00000000..5b1db5b0 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fimaginary.html @@ -0,0 +1,47 @@ + <h1 id="firstHeading" class="firstHeading">imaginary</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define imaginary _Imaginary</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>This macro expands to the keyword <a href="../../keyword/_imaginary" title="c/keyword/ Imaginary"><code>_Imaginary</code></a>.</p> +<p>This is a convenience macro that makes it possible to use <code>float imaginary</code>, <code>double imaginary</code>, and <code>long double imaginary</code> as an alternative way to write the three pure imaginary C types <code>float _Imaginary</code>, <code>double _Imaginary</code>, and <code>long double _Imaginary</code></p> +<p>As with any pure imaginary number support in C, this macro is only defined if the imaginary numbers are supported.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99 t-until-c11"> +<td> <p>A compiler that defines <code>__STDC_IEC_559_COMPLEX__</code> is not required to support imaginary numbers. POSIX recommends checking if the macro <code><a href="http://en.cppreference.com/w/c/numeric/complex/Imaginary_I"><span class="kw745">_Imaginary_I</span></a></code> is defined to identify imaginary number support.</p> +</td> <td> +<span class="t-mark-rev t-since-c99">(since C99)</span><br><span class="t-mark-rev t-until-c11">(until C11)</span> +</td> +</tr> <tr class="t-rev t-since-c11"> +<td> <p>Imaginary numbers are supported if <code>__STDC_IEC_559_COMPLEX__</code> is defined.</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>Programs are allowed to undefine and perhaps redefine the <code>imaginary</code> macro.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <complex.h> + +int main(void) +{ + double imaginary i = -2.0*I; // pure imaginary + double f = 1.0; // pure real + double complex z = f + i; // complex number + printf("z = %.1f%+.1fi\n", creal(z), cimag(z)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">z = 1.0-2.0i</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.3.1/5 imaginary (p: 136) </li> +<li> G.6/1 imaginary (p: 391-392) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.1/5 imaginary (p: 188) </li> +<li> G.6/1 imaginary (p: 537) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.1/3 imaginary (p: 170) </li> +<li> G.6/1 imaginary (p: 472) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="complex" title="c/numeric/complex/complex"> <span class="t-lines"><span>complex</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> complex type macro <br> <span class="t-mark">(keyword macro)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/imaginary" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/imaginary</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex%2Fimaginary_i.html b/devdocs/c/numeric%2Fcomplex%2Fimaginary_i.html new file mode 100644 index 00000000..553a7a26 --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex%2Fimaginary_i.html @@ -0,0 +1,46 @@ + <h1 id="firstHeading" class="firstHeading">_Imaginary_I</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><complex.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define _Imaginary_I /* unspecified */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>The <code>_Imaginary_I</code> macro expands to a value of type <code>const float _Imaginary</code> with the value of the imaginary unit.</p> +<p>As with any pure imaginary number support in C, this macro is only defined if the imaginary numbers are supported.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99 t-until-c11"> +<td> <p>A compiler that defines <code>__STDC_IEC_559_COMPLEX__</code> is not required to support imaginary numbers. POSIX recommends checking if the macro <code>_Imaginary_I</code> is defined to identify imaginary number support.</p> +</td> <td> +<span class="t-mark-rev t-since-c99">(since C99)</span><br><span class="t-mark-rev t-until-c11">(until C11)</span> +</td> +</tr> <tr class="t-rev t-since-c11"> +<td> <p>Imaginary numbers are supported if <code>__STDC_IEC_559_COMPLEX__</code> is defined.</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>This macro allows for the precise way to assemble a complex number from its real and imaginary components, e.g. with <code><span class="br0">(</span><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a><span class="br0">)</span><span class="br0">(</span><span class="br0">(</span><span class="kw4">double</span><span class="br0">)</span>x <span class="sy2">+</span> _Imaginary_I <span class="sy2">*</span> <span class="br0">(</span><span class="kw4">double</span><span class="br0">)</span>y<span class="br0">)</span></code>. This pattern was standardized in C11 as the macro <code><a href="http://en.cppreference.com/w/c/numeric/complex/CMPLX"><span class="kw747">CMPLX</span></a></code>. Note that if <code><a href="http://en.cppreference.com/w/c/numeric/complex/Complex_I"><span class="kw744">_Complex_I</span></a></code> is used instead, this expression is allowed to convert negative zero to positive zero in the imaginary position.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <complex.h> +#include <math.h> + +int main(void) +{ + double complex z1 = 0.0 + INFINITY * _Imaginary_I; + printf("z1 = %.1f%+.1fi\n", creal(z1), cimag(z1)); + + double complex z2 = 0.0 + INFINITY * _Complex_I; + printf("z2 = %.1f%+.1fi\n", creal(z2), cimag(z2)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">z1 = 0.0+Infi +z2 = NaN+Infi</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.3.1/5 _Imaginary_I (p: 188) </li> +<li> G.6/1 _Imaginary_I (p: 537) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.3.1/3 _Imaginary_I (p: 170) </li> +<li> G.6/1 _Imaginary_I (p: 472) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="complex_i" title="c/numeric/complex/Complex I"> <span class="t-lines"><span>_Complex_I</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> the complex unit constant i <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="i" title="c/numeric/complex/I"> <span class="t-lines"><span>I</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> the complex or imaginary unit constant i <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex/Imaginary_I" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex/Imaginary_I</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fcomplex.html b/devdocs/c/numeric%2Fcomplex.html new file mode 100644 index 00000000..70ae214f --- /dev/null +++ b/devdocs/c/numeric%2Fcomplex.html @@ -0,0 +1,139 @@ + <h1 id="firstHeading" class="firstHeading">Complex number arithmetic</h1> <table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <p>If the macro constant <code>__STDC_NO_COMPLEX__</code> is defined by the implementation, the complex types, the header <code><complex.h></code> and all of the names listed here are not provided.</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <p>The C programming language, as of C99, supports complex number math with the three built-in types <code>double _Complex</code>, <code>float _Complex</code>, and <code>long double _Complex</code> (see <a href="../keyword/_complex" title="c/keyword/ Complex"><code>_Complex</code></a>). When the header <code><complex.h></code> is included, the three complex number types are also accessible as <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>, <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code>.</p> +<p>In addition to the complex types, the three imaginary types may be supported: <code>double _Imaginary</code>, <code>float _Imaginary</code>, and <code>long double _Imaginary</code> (see <a href="../keyword/_imaginary" title="c/keyword/ Imaginary"><code>_Imaginary</code></a>). When the header <code><complex.h></code> is included, the three imaginary types are also accessible as <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>, and <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/imaginary"><span class="kw745">imaginary</span></a></code>.</p> +<p>Standard arithmetic operators <code>+, -, *, /</code> can be used with real, complex, and imaginary types in any combination.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99 t-until-c11"> +<td> <p>A compiler that defines <code>__STDC_IEC_559_COMPLEX__</code> is recommended, but not required to support imaginary numbers. POSIX recommends checking if the macro <code><a href="complex/imaginary_i" title="c/numeric/complex/Imaginary I">_Imaginary_I</a></code> is defined to identify imaginary number support.</p> +</td> <td> +<span class="t-mark-rev t-since-c99">(since C99)</span><br><span class="t-mark-rev t-until-c11">(until C11)</span> +</td> +</tr> <tr class="t-rev t-since-c11"> +<td> <p>Imaginary numbers are supported if <code>__STDC_IEC_559_COMPLEX__</code> <span class="t-rev-inl t-since-c23"><span>or <code>__STDC_IEC_60559_COMPLEX__</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> is defined.</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><complex.h></code> </th> +</tr> <tr> <td colspan="2"> <h5 id="Types"> Types </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/imaginary" title="c/numeric/complex/imaginary"> <span class="t-lines"><span>imaginary</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> imaginary type macro <br> <span class="t-mark">(keyword macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/complex" title="c/numeric/complex/complex"> <span class="t-lines"><span>complex</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> complex type macro <br> <span class="t-mark">(keyword macro)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="The_imaginary_constant"> The imaginary constant </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/imaginary_i" title="c/numeric/complex/Imaginary I"> <span class="t-lines"><span>_Imaginary_I</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> the imaginary unit constant i <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/complex_i" title="c/numeric/complex/Complex I"> <span class="t-lines"><span>_Complex_I</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> the complex unit constant i <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/i" title="c/numeric/complex/I"> <span class="t-lines"><span>I</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> the complex or imaginary unit constant i <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Manipulation"> Manipulation </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/cmplx" title="c/numeric/complex/CMPLX"> <span class="t-lines"><span>CMPLX</span><span>CMPLXF</span><span>CMPLXL</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> constructs a complex number from real and imaginary parts <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/creal" title="c/numeric/complex/creal"> <span class="t-lines"><span>creal</span><span>crealf</span><span>creall</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the real part of a complex number <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/cimag" title="c/numeric/complex/cimag"> <span class="t-lines"><span>cimag</span><span>cimagf</span><span>cimagl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the imaginary part a complex number <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/cabs" title="c/numeric/complex/cabs"> <span class="t-lines"><span>cabs</span><span>cabsf</span><span>cabsl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the magnitude of a complex number <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/carg" title="c/numeric/complex/carg"> <span class="t-lines"><span>carg</span><span>cargf</span><span>cargl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the phase angle of a complex number <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/conj" title="c/numeric/complex/conj"> <span class="t-lines"><span>conj</span><span>conjf</span><span>conjl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex conjugate <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/cproj" title="c/numeric/complex/cproj"> <span class="t-lines"><span>cproj</span><span>cprojf</span><span>cprojl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the projection on Riemann sphere <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Exponential_functions"> Exponential functions </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/cexp" title="c/numeric/complex/cexp"> <span class="t-lines"><span>cexp</span><span>cexpf</span><span>cexpl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex base-e exponential <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/clog" title="c/numeric/complex/clog"> <span class="t-lines"><span>clog</span><span>clogf</span><span>clogl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex natural logarithm <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Power_functions"> Power functions </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/cpow" title="c/numeric/complex/cpow"> <span class="t-lines"><span>cpow</span><span>cpowf</span><span>cpowl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex power function <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/csqrt" title="c/numeric/complex/csqrt"> <span class="t-lines"><span>csqrt</span><span>csqrtf</span><span>csqrtl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex square root <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Trigonometric_functions"> Trigonometric functions </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/csin" title="c/numeric/complex/csin"> <span class="t-lines"><span>csin</span><span>csinf</span><span>csinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex sine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/ccos" title="c/numeric/complex/ccos"> <span class="t-lines"><span>ccos</span><span>ccosf</span><span>ccosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex cosine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/ctan" title="c/numeric/complex/ctan"> <span class="t-lines"><span>ctan</span><span>ctanf</span><span>ctanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex tangent <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/casin" title="c/numeric/complex/casin"> <span class="t-lines"><span>casin</span><span>casinf</span><span>casinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc sine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/cacos" title="c/numeric/complex/cacos"> <span class="t-lines"><span>cacos</span><span>cacosf</span><span>cacosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc cosine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/catan" title="c/numeric/complex/catan"> <span class="t-lines"><span>catan</span><span>catanf</span><span>catanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc tangent <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Hyperbolic_functions"> Hyperbolic functions </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/csinh" title="c/numeric/complex/csinh"> <span class="t-lines"><span>csinh</span><span>csinhf</span><span>csinhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex hyperbolic sine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/ccosh" title="c/numeric/complex/ccosh"> <span class="t-lines"><span>ccosh</span><span>ccoshf</span><span>ccoshl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex hyperbolic cosine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/ctanh" title="c/numeric/complex/ctanh"> <span class="t-lines"><span>ctanh</span><span>ctanhf</span><span>ctanhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex hyperbolic tangent <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/casinh" title="c/numeric/complex/casinh"> <span class="t-lines"><span>casinh</span><span>casinhf</span><span>casinhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc hyperbolic sine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/cacosh" title="c/numeric/complex/cacosh"> <span class="t-lines"><span>cacosh</span><span>cacoshf</span><span>cacoshl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc hyperbolic cosine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="complex/catanh" title="c/numeric/complex/catanh"> <span class="t-lines"><span>catanh</span><span>catanhf</span><span>catanhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc hyperbolic tangent <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>The following function names are <span class="t-rev-inl t-since-c23"><span>potentially</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> reserved for future addition to <code>complex.h</code> and are not available for use in the programs that include that header: <code>cerf</code>, <code>cerfc</code>, <code>cexp2</code>, <code>cexpm1</code>, <code>clog10</code>, <code>clog1p</code>, <code>clog2</code>, <code>clgamma</code>, <code>ctgamma</code><span class="t-rev-inl t-since-c23"><span>, <code>csinpi</code>, <code>ccospi</code>, <code>ctanpi</code>, <code>casinpi</code>, <code>cacospi</code>, <code>catanpi</code>, <code>ccompoundn</code>, <code>cpown</code>, <code>cpowr</code>, <code>crootn</code>, <code>crsqrt</code>, <code>cexp10m1</code>, <code>cexp10</code>, <code>cexp2m1</code>, <code>clog10p1</code>, <code>clog2p1</code>, <code>clogp1</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, along with their -f and -l suffixed variants.</p> +<p>Although the C standard names the inverse hyperbolics with "complex arc hyperbolic sine" etc., the inverse functions of the hyperbolic functions are the area functions. Their argument is the area of a hyperbolic sector, not an arc. The correct names are "complex inverse hyperbolic sine" etc. Some authors use "complex area hyperbolic sine" etc.</p> +<p>A complex or imaginary number is infinite if one of its parts is infinite, even if the other part is NaN.</p> +<p>A complex or imaginary number is finite if both parts are neither infinities nor NaNs.</p> +<p>A complex or imaginary number is a zero if both parts are positive or negative zeroes.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <complex.h> +#include <tgmath.h> + +int main(void) +{ + double complex z1 = I * I; // imaginary unit squared + printf("I * I = %.1f%+.1fi\n", creal(z1), cimag(z1)); + + double complex z2 = pow(I, 2); // imaginary unit squared + printf("pow(I, 2) = %.1f%+.1fi\n", creal(z2), cimag(z2)); + + double PI = acos(-1); + double complex z3 = exp(I * PI); // Euler's formula + printf("exp(I*PI) = %.1f%+.1fi\n", creal(z3), cimag(z3)); + + double complex z4 = 1+2*I, z5 = 1-2*I; // conjugates + printf("(1+2i)*(1-2i) = %.1f%+.1fi\n", creal(z4*z5), cimag(z4*z5)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">I * I = -1.0+0.0i +pow(I, 2) = -1.0+0.0i +exp(I*PI) = -1.0+0.0i +(1+2i)*(1-2i) = 5.0+0.0i</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.10.8.3/1/2 <code>__STDC_NO_COMPLEX__</code> (p: 128) </li> +<li> 6.10.8.3/1/2 <code>__STDC_IEC_559_COMPLEX__</code> (p: 128) </li> +<li> 7.3 Complex arithmetic <code><complex.h></code> (p: 136-144) </li> +<li> 7.25 Type-generic math <code><tgmath.h></code> (p: 272-273) </li> +<li> 7.31.1 Complex arithmetic <code><complex.h></code> (p: 391) </li> +<li> Annex G (normative) IEC 60559-compatible complex arithmetic (p: 469-479) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.10.8.3/1/2 <code>__STDC_NO_COMPLEX__</code> (p: 177) </li> +<li> 6.10.8.3/1/2 <code>__STDC_IEC_559_COMPLEX__</code> (p: 177) </li> +<li> 7.3 Complex arithmetic <code><complex.h></code> (p: 188-199) </li> +<li> 7.25 Type-generic math <code><tgmath.h></code> (p: 373-375) </li> +<li> 7.31.1 Complex arithmetic <code><complex.h></code> (p: 455) </li> +<li> Annex G (normative) IEC 60559-compatible complex arithmetic (p: 532-545) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 6.10.8/2 <code>__STDC_IEC_559_COMPLEX__</code> (p: 161) </li> +<li> 7.3 Complex arithmetic <code><complex.h></code> (p: 170-180) </li> +<li> 7.22 Type-generic math <code><tgmath.h></code> (p: 335-337) </li> +<li> 7.26.1 Complex arithmetic <code><complex.h></code> (p: 401) </li> +<li> Annex G (informative) IEC 60559-compatible complex arithmetic (p: 467-480) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/complex" title="cpp/numeric/complex">C++ documentation</a></span> for <span class=""><span>Complex number arithmetic</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/complex" class="_attribution-link">https://en.cppreference.com/w/c/numeric/complex</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Ffenv%2Ffe_dfl_env.html b/devdocs/c/numeric%2Ffenv%2Ffe_dfl_env.html new file mode 100644 index 00000000..bbc17453 --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Ffe_dfl_env.html @@ -0,0 +1,80 @@ + <h1 id="firstHeading" class="firstHeading">FE_DFL_ENV</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><fenv.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FE_DFL_ENV /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>The macro constant <code>FE_DFL_ENV</code> expands to an expression of type <code>const fenv_t*</code>, which points to a full copy of the default floating-point environment, that is, the environment as loaded at program startup.</p> +<p>Additional macros that begin with <code>FE_</code> followed by uppercase letters, and have the type <code>const fenv_t*</code>, may be supported by an implementation.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <fenv.h> + +#pragma STDC FENV_ACCESS ON + +void show_fe_exceptions(void) +{ + printf("current exceptions raised: "); + if(fetestexcept(FE_DIVBYZERO)) printf(" FE_DIVBYZERO"); + if(fetestexcept(FE_INEXACT)) printf(" FE_INEXACT"); + if(fetestexcept(FE_INVALID)) printf(" FE_INVALID"); + if(fetestexcept(FE_OVERFLOW)) printf(" FE_OVERFLOW"); + if(fetestexcept(FE_UNDERFLOW)) printf(" FE_UNDERFLOW"); + if(fetestexcept(FE_ALL_EXCEPT)==0) printf(" none"); + printf("\n"); +} + +void show_fe_rounding_method(void) +{ + printf("current rounding method: "); + switch (fegetround()) { + case FE_TONEAREST: printf ("FE_TONEAREST"); break; + case FE_DOWNWARD: printf ("FE_DOWNWARD"); break; + case FE_UPWARD: printf ("FE_UPWARD"); break; + case FE_TOWARDZERO: printf ("FE_TOWARDZERO"); break; + default: printf ("unknown"); + }; + printf("\n"); +} + +void show_fe_environment(void) +{ + show_fe_exceptions(); + show_fe_rounding_method(); +} + +int main() +{ + printf("On startup:\n"); + show_fe_environment(); + + // Change environment + fesetround(FE_DOWNWARD); // change rounding mode + feraiseexcept(FE_INVALID); // raise exception + printf("\nBefore restoration:\n"); + show_fe_environment(); + + fesetenv(FE_DFL_ENV); // restore + printf("\nAfter restoring default environment:\n"); + show_fe_environment(); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">On startup: +current exceptions raised: none +current rounding method: FE_TONEAREST + +Before restoration: +current exceptions raised: FE_INVALID +current rounding method: FE_DOWNWARD + +After restoring default environment: +current exceptions raised: none +current rounding method: FE_TONEAREST</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.6/9 Floating-point environment <fenv.h> (p: 208) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.6/8 Floating-point environment <fenv.h> (p: 188-189) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="feenv" title="c/numeric/fenv/feenv"> <span class="t-lines"><span>fegetenv</span><span>fesetenv</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> saves or restores the current floating-point environment <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="feupdateenv" title="c/numeric/fenv/feupdateenv"> <span class="t-lines"><span>feupdateenv</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> restores the floating-point environment and raises the previously raise exceptions <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/fenv/FE_DFL_ENV" title="cpp/numeric/fenv/FE DFL ENV">C++ documentation</a></span> for <code>FE_DFL_ENV</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/fenv/FE_DFL_ENV" class="_attribution-link">https://en.cppreference.com/w/c/numeric/fenv/FE_DFL_ENV</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Ffenv%2Ffe_exceptions.html b/devdocs/c/numeric%2Ffenv%2Ffe_exceptions.html new file mode 100644 index 00000000..aa31da7a --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Ffe_exceptions.html @@ -0,0 +1,87 @@ + <h1 id="firstHeading" class="firstHeading"><small>FE_DIVBYZERO, FE_INEXACT, FE_INVALID, FE_OVERFLOW, FE_UNDERFLOW, FE_ALL_EXCEPT</small></h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><fenv.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FE_DIVBYZERO /*implementation defined power of 2*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FE_INEXACT /*implementation defined power of 2*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FE_INVALID /*implementation defined power of 2*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FE_OVERFLOW /*implementation defined power of 2*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FE_UNDERFLOW /*implementation defined power of 2*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FE_ALL_EXCEPT FE_DIVBYZERO | FE_INEXACT | \ + FE_INVALID | FE_OVERFLOW | \ + FE_UNDERFLOW</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>All these macro constants (except <code>FE_ALL_EXCEPT</code>) expand to integer constant expressions that are distinct powers of 2, which uniquely identify all supported floating-point exceptions. Each macro is only defined if it is supported.</p> +<p>The macro constant <code>FE_ALL_EXCEPT</code>, which expands to the bitwise OR of all other <code>FE_*</code>, is always defined and is zero if floating-point exceptions are not supported by the implementation.</p> +<table class="t-dsc-begin"> <tr class="t-dsc-hitem"> <th> Constant </th> <th> Explanation </th> +</tr> <tr class="t-dsc"> <td> <code>FE_DIVBYZERO</code> </td> <td> pole error occurred in an earlier floating-point operation </td> +</tr> <tr class="t-dsc"> <td> <code>FE_INEXACT</code> </td> <td> inexact result: rounding was necessary to store the result of an earlier floating-point operation </td> +</tr> <tr class="t-dsc"> <td> <code>FE_INVALID</code> </td> <td> domain error occurred in an earlier floating-point operation </td> +</tr> <tr class="t-dsc"> <td> <code>FE_OVERFLOW</code> </td> <td> the result of an earlier floating-point operation was too large to be representable </td> +</tr> <tr class="t-dsc"> <td> <code>FE_UNDERFLOW</code> </td> <td> the result of an earlier floating-point operation was subnormal with a loss of precision </td> +</tr> <tr class="t-dsc"> <td> <code>FE_ALL_EXCEPT</code> </td> <td> bitwise OR of all supported floating-point exceptions </td> +</tr> </table> <p>The implementation may define additional macro constants in <code><fenv.h></code> to identify additional floating-point exceptions. All such constants begin with <code>FE_</code> followed by at least one uppercase letter.</p> +<p>See <a href="../math/math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a> for further details.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> +#include <fenv.h> + +#pragma STDC FENV_ACCESS ON +void show_fe_exceptions(void) +{ + printf("exceptions raised:"); + if(fetestexcept(FE_DIVBYZERO)) printf(" FE_DIVBYZERO"); + if(fetestexcept(FE_INEXACT)) printf(" FE_INEXACT"); + if(fetestexcept(FE_INVALID)) printf(" FE_INVALID"); + if(fetestexcept(FE_OVERFLOW)) printf(" FE_OVERFLOW"); + if(fetestexcept(FE_UNDERFLOW)) printf(" FE_UNDERFLOW"); + feclearexcept(FE_ALL_EXCEPT); + printf("\n"); +} + +int main(void) +{ + printf("MATH_ERREXCEPT is %s\n", + math_errhandling & MATH_ERREXCEPT ? "set" : "not set"); + + printf("0.0/0.0 = %f\n", 0.0/0.0); + show_fe_exceptions(); + + printf("1.0/0.0 = %f\n", 1.0/0.0); + show_fe_exceptions(); + + printf("1.0/10.0 = %f\n", 1.0/10.0); + show_fe_exceptions(); + + printf("sqrt(-1) = %f\n", sqrt(-1)); + show_fe_exceptions(); + + printf("DBL_MAX*2.0 = %f\n", DBL_MAX*2.0); + show_fe_exceptions(); + + printf("nextafter(DBL_MIN/pow(2.0,52),0.0) = %.1f\n", + nextafter(DBL_MIN/pow(2.0,52),0.0)); + show_fe_exceptions(); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">MATH_ERREXCEPT is set +0.0/0.0 = nan +exceptions raised: FE_INVALID +1.0/0.0 = inf +exceptions raised: FE_DIVBYZERO +1.0/10.0 = 0.100000 +exceptions raised: FE_INEXACT +sqrt(-1) = -nan +exceptions raised: FE_INVALID +DBL_MAX*2.0 = inf +exceptions raised: FE_INEXACT FE_OVERFLOW +nextafter(DBL_MIN/pow(2.0,52),0.0) = 0.0 +exceptions raised: FE_INEXACT FE_UNDERFLOW</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.6/6 Floating-point environment <fenv.h> (p: 207) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.6/5 Floating-point environment <fenv.h> (p: 188) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../math/math_errhandling" title="c/numeric/math/math errhandling"> <span class="t-lines"><span>math_errhandling</span><span>MATH_ERRNO</span><span>MATH_ERREXCEPT</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> defines the error handling mechanism used by the common mathematical functions <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/fenv/FE_exceptions" title="cpp/numeric/fenv/FE exceptions">C++ documentation</a></span> for <span class=""><span>floating-point exception macros</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/fenv/FE_exceptions" class="_attribution-link">https://en.cppreference.com/w/c/numeric/fenv/FE_exceptions</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Ffenv%2Ffe_round.html b/devdocs/c/numeric%2Ffenv%2Ffe_round.html new file mode 100644 index 00000000..716eed9d --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Ffe_round.html @@ -0,0 +1,71 @@ + <h1 id="firstHeading" class="firstHeading">FE_DOWNWARD, FE_TONEAREST, FE_TOWARDZERO, FE_UPWARD</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><fenv.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FE_DOWNWARD /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FE_TONEAREST /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FE_TOWARDZERO /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FE_UPWARD /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Each of these macro constants expands to a nonnegative integer constant expression, which can be used with <code><a href="feround" title="c/numeric/fenv/feround">fesetround</a></code> and <code><a href="feround" title="c/numeric/fenv/feround">fegetround</a></code> to indicate one of the supported floating-point rounding modes. The implementation may define additional rounding mode constants in <a href="../fenv" title="c/numeric/fenv"><code><fenv.h></code></a>, which should all begin with <code>FE_</code> followed by at least one uppercase letter. Each macro is only defined if it is supported.</p> +<table class="t-dsc-begin"> <tr class="t-dsc-hitem"> <th> Constant </th> <th> Explanation </th> +</tr> <tr class="t-dsc"> <td> <code>FE_DOWNWARD</code> </td> <td> rounding towards negative infinity </td> +</tr> <tr class="t-dsc"> <td> <code>FE_TONEAREST</code> </td> <td> rounding towards nearest representable value </td> +</tr> <tr class="t-dsc"> <td> <code>FE_TOWARDZERO</code> </td> <td> rounding towards zero </td> +</tr> <tr class="t-dsc"> <td> <code>FE_UPWARD</code> </td> <td> rounding towards positive infinity </td> +</tr> </table> <p>Additional rounding modes may be supported by an implementation.</p> +<p>The current rounding mode affects the following:</p> +<ul><li> results of floating-point arithmetic operators outside of constant expressions </li></ul> <div class="c source-c"><pre data-language="c">double x = 1; +x / 10; // 0.09999999999999999167332731531132594682276248931884765625 or + // 0.1000000000000000055511151231257827021181583404541015625</pre></div> <ul><li> results of standard library <a href="../math" title="c/numeric/math">mathematical functions</a> </li></ul> <div class="c source-c"><pre data-language="c">sqrt(2); // 1.41421356237309492343001693370752036571502685546875 or + // 1.4142135623730951454746218587388284504413604736328125</pre></div> <ul><li> floating-point to floating-point implicit conversion and casts </li></ul> <div class="c source-c"><pre data-language="c">double d = 1 + DBL_EPSILON; +float f = d; // 1.00000000000000000000000 or + // 1.00000011920928955078125</pre></div> <ul><li> string conversions such as <code><a href="../../string/byte/strtof" title="c/string/byte/strtof">strtod</a></code> or <code><a href="../../io/fprintf" title="c/io/fprintf">printf</a></code> </li></ul> <div class="c source-c"><pre data-language="c">strtof("0.1", NULL); // 0.0999999940395355224609375 or + // 0.100000001490116119384765625</pre></div> <ul><li> the library rounding functions <code><a href="../math/nearbyint" title="c/numeric/math/nearbyint">nearbyint</a></code>, <code><a href="../math/rint" title="c/numeric/math/rint">rint</a></code>, <code><a href="../math/rint" title="c/numeric/math/rint">lrint</a></code> </li></ul> <div class="c source-c"><pre data-language="c">lrint(2.1); // 2 or 3</pre></div> <p>The current rounding mode does NOT affect the following:</p> +<ul> +<li> floating-point to integer implicit conversion and casts (always towards zero) </li> +<li> results of floating-point arithmetic operators in constant expressions executed at compile time (always to nearest) </li> +<li> the library functions <code><a href="../math/round" title="c/numeric/math/round">round</a></code>, <code><a href="../math/round" title="c/numeric/math/round">lround</a></code>, <code><a href="../math/round" title="c/numeric/math/round">llround</a></code>, <code><a href="../math/ceil" title="c/numeric/math/ceil">ceil</a></code>, <code><a href="../math/floor" title="c/numeric/math/floor">floor</a></code>, <code><a href="../math/trunc" title="c/numeric/math/trunc">trunc</a></code> </li> +</ul> <p>As with any <a href="../fenv" title="c/numeric/fenv">floating-point environment</a> functionality, rounding is only guaranteed if <code>#pragma STDC FENV_ACCESS ON</code> is set.</p> +<p>Compilers that do not support the pragma may offer their own ways to support current rounding mode. For example Clang and GCC have the option <code>-frounding-math</code> intended to disable optimizations that would change the meaning of rounding-sensitive code.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <fenv.h> +#include <math.h> +#include <stdio.h> +#include <stdlib.h> + +// #pragma STDC FENV_ACCESS ON + +int main() +{ + fesetround(FE_DOWNWARD); + puts("rounding down: "); + printf(" pi = %.22f\n", acosf(-1)); + printf("strtof(\"1.1\") = %.22f\n", strtof("1.1", NULL)); + printf(" rint(2.1) = %.22f\n\n", rintf(2.1)); + fesetround(FE_UPWARD); + puts("rounding up: "); + printf(" pi = %.22f\n", acosf(-1)); + printf("strtof(\"1.1\") = %.22f\n", strtof("1.1", NULL)); + printf(" rint(2.1) = %.22f\n", rintf(2.1)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">rounding down: + pi = 3.1415925025939941406250 +strtof("1.1") = 1.0999999046325683593750 + rint(2.1) = 2.0000000000000000000000 + +rounding up: + pi = 3.1415927410125732421875 +strtof("1.1") = 1.1000000238418579101563 + rint(2.1) = 3.0000000000000000000000</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.6/8 Floating-point environment <fenv.h> (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.6/8 Floating-point environment <fenv.h> (p: 151) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.6/8 Floating-point environment <fenv.h> (p: 207) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.6/7 Floating-point environment <fenv.h> (p: 188) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="feround" title="c/numeric/fenv/feround"> <span class="t-lines"><span>fegetround</span><span>fesetround</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> gets or sets rounding direction <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/fenv/FE_round" title="cpp/numeric/fenv/FE round">C++ documentation</a></span> for <span class=""><span>floating-point rounding macros</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/fenv/FE_round" class="_attribution-link">https://en.cppreference.com/w/c/numeric/fenv/FE_round</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Ffenv%2Ffeclearexcept.html b/devdocs/c/numeric%2Ffenv%2Ffeclearexcept.html new file mode 100644 index 00000000..04dbc3ee --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Ffeclearexcept.html @@ -0,0 +1,63 @@ + <h1 id="firstHeading" class="firstHeading">feclearexcept</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><fenv.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int feclearexcept( int excepts );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Attempts to clear the floating-point exceptions that are listed in the bitmask argument <code>excepts</code>, which is a bitwise OR of the <a href="fe_exceptions" title="c/numeric/fenv/FE exceptions">floating-point exception macros</a>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> excepts </td> <td> - </td> <td> bitmask listing the exception flags to clear </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>0</code> if all indicated exceptions were successfully cleared or if <code>excepts</code> is zero. Returns a non-zero value on error.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <fenv.h> +#include <stdio.h> +#include <math.h> +#include <float.h> + +/* + * A possible implementation of hypot which makes use of many advanced + * floating-point features. + */ +double hypot_demo(double a, double b) { + const int range_problem = FE_OVERFLOW | FE_UNDERFLOW; + feclearexcept(range_problem); + // try a fast algorithm + double result = sqrt(a * a + b * b); + if (!fetestexcept(range_problem)) // no overflow or underflow + return result; // return the fast result + // do a more complicated calculation to avoid overflow or underflow + int a_exponent,b_exponent; + frexp(a, &a_exponent); + frexp(b, &b_exponent); + + if (a_exponent - b_exponent > DBL_MAX_EXP) + return fabs(a) + fabs(b); // we can ignore the smaller value + // scale so that fabs(a) is near 1 + double a_scaled = scalbn(a, -a_exponent); + double b_scaled = scalbn(b, -a_exponent); + // overflow and underflow is now impossible + result = sqrt(a_scaled * a_scaled + b_scaled * b_scaled); + // undo scaling + return scalbn(result, a_exponent); +} + +int main(void) +{ + // Normal case takes the fast route + printf("hypot(%f, %f) = %f\n", 3.0, 4.0, hypot_demo(3.0, 4.0)); + // Extreme case takes the slow but more accurate route + printf("hypot(%e, %e) = %e\n", DBL_MAX / 2.0, + DBL_MAX / 2.0, + hypot_demo(DBL_MAX / 2.0, DBL_MAX / 2.0)); + + return 0; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">hypot(3.000000, 4.000000) = 5.000000 +hypot(8.988466e+307, 8.988466e+307) = 1.271161e+308</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.6.2.1 The feclearexcept function (p: 209) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.6.2.1 The feclearexcept function (p: 190) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fetestexcept" title="c/numeric/fenv/fetestexcept"> <span class="t-lines"><span>fetestexcept</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> determines which of the specified floating-point status flags are set <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/fenv/feclearexcept" title="cpp/numeric/fenv/feclearexcept">C++ documentation</a></span> for <code>feclearexcept</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/fenv/feclearexcept" class="_attribution-link">https://en.cppreference.com/w/c/numeric/fenv/feclearexcept</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Ffenv%2Ffeenv.html b/devdocs/c/numeric%2Ffenv%2Ffeenv.html new file mode 100644 index 00000000..55c9bb86 --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Ffeenv.html @@ -0,0 +1,116 @@ + <h1 id="firstHeading" class="firstHeading">fegetenv, fesetenv</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><fenv.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int fegetenv( fenv_t* envp );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int fesetenv( const fenv_t* envp );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>1) Attempts to store the status of the floating-point environment in the object pointed to by <code>envp</code>.</p> +<p>2) Attempts to establish the floating-point environment from the object pointed to by <code>envp</code>. The value of that object must be previously obtained by a call to <code><a href="feholdexcept" title="c/numeric/fenv/feholdexcept">feholdexcept</a></code> or <code>fegetenv</code> or be a floating-point macro constant. If any of the floating-point status flags are set in <code>envp</code>, they become set in the environment (and are then testable with <code><a href="fetestexcept" title="c/numeric/fenv/fetestexcept">fetestexcept</a></code>), but the corresponding floating-point exceptions are not raised (execution continues uninterrupted)</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> envp </td> <td> - </td> <td> pointer to the object of type <code>fenv_t</code> which holds the status of the floating-point environment </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>0</code> on success, non-zero otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <fenv.h> + +#pragma STDC FENV_ACCESS ON + +void show_fe_exceptions(void) +{ + printf("current exceptions raised: "); + if(fetestexcept(FE_DIVBYZERO)) printf(" FE_DIVBYZERO"); + if(fetestexcept(FE_INEXACT)) printf(" FE_INEXACT"); + if(fetestexcept(FE_INVALID)) printf(" FE_INVALID"); + if(fetestexcept(FE_OVERFLOW)) printf(" FE_OVERFLOW"); + if(fetestexcept(FE_UNDERFLOW)) printf(" FE_UNDERFLOW"); + if(fetestexcept(FE_ALL_EXCEPT)==0) printf(" none"); + printf("\n"); +} + +void show_fe_rounding_method(void) +{ + printf("current rounding method: "); + switch (fegetround()) { + case FE_TONEAREST: printf ("FE_TONEAREST"); break; + case FE_DOWNWARD: printf ("FE_DOWNWARD"); break; + case FE_UPWARD: printf ("FE_UPWARD"); break; + case FE_TOWARDZERO: printf ("FE_TOWARDZERO"); break; + default: printf ("unknown"); + }; + printf("\n"); +} + +void show_fe_environment(void) +{ + show_fe_exceptions(); + show_fe_rounding_method(); +} + +int main(void) +{ + fenv_t curr_env; + int rtn; + + /* Show default environment. */ + show_fe_environment(); + printf("\n"); + + /* Perform some computation under default environment. */ + printf("+11.5 -> %+4.1f\n", rint(+11.5)); /* midway between two integers */ + printf("+12.5 -> %+4.1f\n", rint(+12.5)); /* midway between two integers */ + show_fe_environment(); + printf("\n"); + + /* Save current environment. */ + rtn = fegetenv(&curr_env); + + /* Perform some computation with new rounding method. */ + feclearexcept(FE_ALL_EXCEPT); + fesetround(FE_DOWNWARD); + printf("1.0/0.0 = %f\n", 1.0/0.0); + printf("+11.5 -> %+4.1f\n", rint(+11.5)); + printf("+12.5 -> %+4.1f\n", rint(+12.5)); + show_fe_environment(); + printf("\n"); + + /* Restore previous environment. */ + rtn = fesetenv(&curr_env); + show_fe_environment(); + + return 0; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">current exceptions raised: none +current rounding method: FE_TONEAREST + ++11.5 -> +12.0 ++12.5 -> +12.0 +current exceptions raised: FE_INEXACT +current rounding method: FE_TONEAREST + +1.0/0.0 = inf ++11.5 -> +11.0 ++12.5 -> +12.0 +current exceptions raised: FE_DIVBYZERO FE_INEXACT +current rounding method: FE_DOWNWARD + +current exceptions raised: FE_INEXACT +current rounding method: FE_TONEAREST</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.6.4.1 The fegetenv function (p: 213) </li> +<li> 7.6.4.3 The fesetenv function (p: 214) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.6.4.1 The fegetenv function (p: 194) </li> +<li> 7.6.4.3 The fesetenv function (p: 195) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="feholdexcept" title="c/numeric/fenv/feholdexcept"> <span class="t-lines"><span>feholdexcept</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> saves the environment, clears all status flags and ignores all future errors <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="feupdateenv" title="c/numeric/fenv/feupdateenv"> <span class="t-lines"><span>feupdateenv</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> restores the floating-point environment and raises the previously raise exceptions <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fe_dfl_env" title="c/numeric/fenv/FE DFL ENV"> <span class="t-lines"><span>FE_DFL_ENV</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> default floating-point environment <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/fenv/feenv" title="cpp/numeric/fenv/feenv">C++ documentation</a></span> for <code>fegetenv, fesetenv</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/fenv/feenv" class="_attribution-link">https://en.cppreference.com/w/c/numeric/fenv/feenv</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Ffenv%2Ffeexceptflag.html b/devdocs/c/numeric%2Ffenv%2Ffeexceptflag.html new file mode 100644 index 00000000..04da8f88 --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Ffeexceptflag.html @@ -0,0 +1,68 @@ + <h1 id="firstHeading" class="firstHeading">fegetexceptflag, fesetexceptflag</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><fenv.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int fegetexceptflag( fexcept_t* flagp, int excepts );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int fesetexceptflag( const fexcept_t* flagp, int excepts );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>1) Attempts to obtain the full contents of the floating-point exception flags that are listed in the bitmask argument <code>excepts</code>, which is a bitwise OR of the <a href="fe_exceptions" title="c/numeric/fenv/FE exceptions">floating-point exception macros</a>.</p> +<p>2) Attempts to copy the full contents of the floating-point exception flags that are listed in <code>excepts</code> from <code>flagp</code> into the floating-point environment. Does not raise any exceptions, only modifies the flags.</p> +<p>The full contents of a floating-point exception flag is not necessarily a boolean value indicating whether the exception is raised or cleared. For example, it may be a struct which includes the boolean status and the address of the code that triggered the exception. These functions obtain all such content and obtain/store it in <code>flagp</code> in implementation-defined format.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> flagp </td> <td> - </td> <td> pointer to an <code>fexcept_t</code> object where the flags will be stored or read from </td> +</tr> <tr class="t-par"> <td> excepts </td> <td> - </td> <td> bitmask listing the exception flags to get/set </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>0</code> on success, non-zero otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <fenv.h> + +#pragma STDC FENV_ACCESS ON + +void show_fe_exceptions(void) +{ + printf("current exceptions raised: "); + if(fetestexcept(FE_DIVBYZERO)) printf(" FE_DIVBYZERO"); + if(fetestexcept(FE_INEXACT)) printf(" FE_INEXACT"); + if(fetestexcept(FE_INVALID)) printf(" FE_INVALID"); + if(fetestexcept(FE_OVERFLOW)) printf(" FE_OVERFLOW"); + if(fetestexcept(FE_UNDERFLOW)) printf(" FE_UNDERFLOW"); + if(fetestexcept(FE_ALL_EXCEPT)==0) printf(" none"); + printf("\n"); +} + +int main(void) +{ + fexcept_t excepts; + + /* Setup a "current" set of exception flags. */ + feraiseexcept(FE_INVALID); + show_fe_exceptions(); + + /* Save current exception flags. */ + fegetexceptflag(&excepts,FE_ALL_EXCEPT); + + /* Temporarily raise two other exceptions. */ + feclearexcept(FE_ALL_EXCEPT); + feraiseexcept(FE_OVERFLOW | FE_INEXACT); + show_fe_exceptions(); + + /* Restore previous exception flags. */ + fesetexceptflag(&excepts,FE_ALL_EXCEPT); + show_fe_exceptions(); + + return 0; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">current exceptions raised: FE_INVALID +current exceptions raised: FE_INEXACT FE_OVERFLOW +current exceptions raised: FE_INVALID</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.6.2.2 The fegetexceptflag function (p: 210) </li> +<li> 7.6.2.4 The fesetexceptflag function (p: 211) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.6.2.2 The fegetexceptflag function (p: 191) </li> +<li> 7.6.2.4 The fesetexceptflag function (p: 192) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/fenv/feexceptflag" title="cpp/numeric/fenv/feexceptflag">C++ documentation</a></span> for <code>fegetexceptflag, fesetexceptflag</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/fenv/feexceptflag" class="_attribution-link">https://en.cppreference.com/w/c/numeric/fenv/feexceptflag</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Ffenv%2Ffeholdexcept.html b/devdocs/c/numeric%2Ffenv%2Ffeholdexcept.html new file mode 100644 index 00000000..bb870968 --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Ffeholdexcept.html @@ -0,0 +1,74 @@ + <h1 id="firstHeading" class="firstHeading">feholdexcept</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><fenv.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int feholdexcept( fenv_t* envp );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>First, saves the current floating-point environment to the object pointed to by <code>envp</code> (similar to <code><a href="feenv" title="c/numeric/fenv/feenv">fegetenv</a></code>), then clears all floating-point status flags, and then installs the non-stop mode: future floating-point exceptions will not interrupt execution (will not trap), until the floating-point environment is restored by <code><a href="feupdateenv" title="c/numeric/fenv/feupdateenv">feupdateenv</a></code> or <code><a href="feenv" title="c/numeric/fenv/feenv">fesetenv</a></code>.</p> +<p>This function may be used in the beginning of a subroutine that must hide the floating-point exceptions it may raise from the caller. If only some exceptions must be suppressed, while others must be reported, the non-stop mode is usually ended with a call to <code><a href="feupdateenv" title="c/numeric/fenv/feupdateenv">feupdateenv</a></code> after clearing the unwanted exceptions.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> envp </td> <td> - </td> <td> pointer to the object of type <code>fenv_t</code> where the floating-point environment will be stored </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>0</code> on success, non-zero otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <fenv.h> +#include <float.h> + +#pragma STDC FENV_ACCESS ON + +void show_fe_exceptions(void) +{ + printf("current exceptions raised: "); + if(fetestexcept(FE_DIVBYZERO)) printf(" FE_DIVBYZERO"); + if(fetestexcept(FE_INEXACT)) printf(" FE_INEXACT"); + if(fetestexcept(FE_INVALID)) printf(" FE_INVALID"); + if(fetestexcept(FE_OVERFLOW)) printf(" FE_OVERFLOW"); + if(fetestexcept(FE_UNDERFLOW)) printf(" FE_UNDERFLOW"); + if(fetestexcept(FE_ALL_EXCEPT)==0) printf(" none"); + printf("\n"); +} + +double x2 (double x) /* times two */ +{ + fenv_t curr_excepts; + + /* Save and clear current f-p environment. */ + feholdexcept(&curr_excepts); + + /* Raise inexact and overflow exceptions. */ + printf("In x2(): x = %f\n", x=x*2.0); + show_fe_exceptions(); + feclearexcept(FE_INEXACT); /* hide inexact exception from caller */ + + /* Merge caller's exceptions (FE_INVALID) */ + /* with remaining x2's exceptions (FE_OVERFLOW). */ + feupdateenv(&curr_excepts); + return x; +} + +int main(void) +{ + feclearexcept(FE_ALL_EXCEPT); + feraiseexcept(FE_INVALID); /* some computation with invalid argument */ + show_fe_exceptions(); + printf("x2(DBL_MAX) = %f\n", x2(DBL_MAX)); + show_fe_exceptions(); + + return 0; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">current exceptions raised: FE_INVALID +In x2(): x = inf +current exceptions raised: FE_INEXACT FE_OVERFLOW +x2(DBL_MAX) = inf +current exceptions raised: FE_INVALID FE_OVERFLOW</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.6.4.2 The feholdexcept function (p: 213-214) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.6.4.2 The feholdexcept function (p: 194-195) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="feupdateenv" title="c/numeric/fenv/feupdateenv"> <span class="t-lines"><span>feupdateenv</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> restores the floating-point environment and raises the previously raise exceptions <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="feenv" title="c/numeric/fenv/feenv"> <span class="t-lines"><span>fegetenv</span><span>fesetenv</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> saves or restores the current floating-point environment <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fe_dfl_env" title="c/numeric/fenv/FE DFL ENV"> <span class="t-lines"><span>FE_DFL_ENV</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> default floating-point environment <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/fenv/feholdexcept" title="cpp/numeric/fenv/feholdexcept">C++ documentation</a></span> for <code>feholdexcept</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/fenv/feholdexcept" class="_attribution-link">https://en.cppreference.com/w/c/numeric/fenv/feholdexcept</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Ffenv%2Fferaiseexcept.html b/devdocs/c/numeric%2Ffenv%2Fferaiseexcept.html new file mode 100644 index 00000000..ca35e49d --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Fferaiseexcept.html @@ -0,0 +1,55 @@ + <h1 id="firstHeading" class="firstHeading">feraiseexcept</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><fenv.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int feraiseexcept( int excepts );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Attempts to raise all floating-point exceptions listed in <code>excepts</code> (a bitwise OR of the <a href="fe_exceptions" title="c/numeric/fenv/FE exceptions">floating-point exception macros</a>). If one of the exceptions is <code><a href="fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_OVERFLOW</a></code> or <code><a href="http://en.cppreference.com/w/c/numeric/fenv/FE_exceptions"><span class="kw733">FE_UNDERFLOW</span></a></code>, this function may additionally raise <code><a href="fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code>. The order in which the exceptions are raised is unspecified, except that <code><a href="fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_OVERFLOW</a></code> and <code><a href="http://en.cppreference.com/w/c/numeric/fenv/FE_exceptions"><span class="kw733">FE_UNDERFLOW</span></a></code> are always raised before <code><a href="fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> excepts </td> <td> - </td> <td> bitmask listing the exception flags to raise </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>0</code> if all listed exceptions were raised, non-zero value otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <fenv.h> + +#pragma STDC FENV_ACCESS ON + +void show_fe_exceptions(void) +{ + printf("current exceptions raised: "); + if(fetestexcept(FE_DIVBYZERO)) printf(" FE_DIVBYZERO"); + if(fetestexcept(FE_INEXACT)) printf(" FE_INEXACT"); + if(fetestexcept(FE_INVALID)) printf(" FE_INVALID"); + if(fetestexcept(FE_OVERFLOW)) printf(" FE_OVERFLOW"); + if(fetestexcept(FE_UNDERFLOW)) printf(" FE_UNDERFLOW"); + if(fetestexcept(FE_ALL_EXCEPT)==0) printf(" none"); + feclearexcept(FE_ALL_EXCEPT); + printf("\n"); +} + +double some_computation(void) +{ + /* Computation reaches a state that causes overflow. */ + int r = feraiseexcept(FE_OVERFLOW | FE_INEXACT); + printf("feraiseexcept() %s\n", (r?"fails":"succeeds")); + return 0.0; +} + +int main(void) +{ + some_computation(); + show_fe_exceptions(); + + return 0; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">feraiseexcept() succeeds +current exceptions raised: FE_INEXACT FE_OVERFLOW</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.6.2.3 The feraiseexcept function (p: 210) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.6.2.3 The feraiseexcept function (p: 191) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="feclearexcept" title="c/numeric/fenv/feclearexcept"> <span class="t-lines"><span>feclearexcept</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> clears the specified floating-point status flags <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fetestexcept" title="c/numeric/fenv/fetestexcept"> <span class="t-lines"><span>fetestexcept</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> determines which of the specified floating-point status flags are set <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/fenv/feraiseexcept" title="cpp/numeric/fenv/feraiseexcept">C++ documentation</a></span> for <code>feraiseexcept</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/fenv/feraiseexcept" class="_attribution-link">https://en.cppreference.com/w/c/numeric/fenv/feraiseexcept</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Ffenv%2Fferound.html b/devdocs/c/numeric%2Ffenv%2Fferound.html new file mode 100644 index 00000000..7bbe06b4 --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Fferound.html @@ -0,0 +1,88 @@ + <h1 id="firstHeading" class="firstHeading">fegetround, fesetround</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><fenv.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int fesetround( int round );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int fegetround();</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>1) Attempts to establish the floating-point rounding direction equal to the argument <code>round</code>, which is expected to be one of the <a href="fe_round" title="c/numeric/fenv/FE round">floating-point rounding macros</a>.</p> +<p>2) Returns the value of the <a href="fe_round" title="c/numeric/fenv/FE round">floating-point rounding macro</a> that corresponds to the current rounding direction.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> round </td> <td> - </td> <td> rounding direction, one of <a href="fe_round" title="c/numeric/fenv/FE round">floating-point rounding macros</a> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>1) <code>0</code> on success, non-zero otherwise.</p> +<p>2) the <a href="fe_round" title="c/numeric/fenv/FE round">floating-point rounding macro</a> describing the current rounding direction or a negative value if the direction cannot be determined.</p> +<h3 id="Notes"> Notes</h3> <p>The current rounding mode, reflecting the effects of the most recent <code>fesetround</code>, can also be queried with <code><a href="../../types/limits/flt_rounds" title="c/types/limits/FLT ROUNDS">FLT_ROUNDS</a></code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <fenv.h> +#include <math.h> +#include <stdio.h> + +// #pragma STDC FENV_ACCESS ON + +void show_fe_current_rounding_direction(void) +{ + printf("current rounding direction: "); + switch (fegetround()) { + case FE_TONEAREST: printf ("FE_TONEAREST"); break; + case FE_DOWNWARD: printf ("FE_DOWNWARD"); break; + case FE_UPWARD: printf ("FE_UPWARD"); break; + case FE_TOWARDZERO: printf ("FE_TOWARDZERO"); break; + default: printf ("unknown"); + }; + printf("\n"); +} + +int main(void) +{ + /* Default rounding direction */ + show_fe_current_rounding_direction(); + printf("+11.5 -> %+4.1f\n", rint(+11.5)); /* midway between two integers */ + printf("+12.5 -> %+4.1f\n", rint(+12.5)); /* midway between two integers */ + + /* Save current rounding direction. */ + int curr_direction = fegetround(); + + /* Temporarily change current rounding direction. */ + fesetround(FE_DOWNWARD); + show_fe_current_rounding_direction(); + printf("+11.5 -> %+4.1f\n", rint(+11.5)); + printf("+12.5 -> %+4.1f\n", rint(+12.5)); + + /* Restore default rounding direction. */ + fesetround(curr_direction); + show_fe_current_rounding_direction(); + + return 0; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">current rounding direction: FE_TONEAREST ++11.5 -> +12.0 ++12.5 -> +12.0 +current rounding direction: FE_DOWNWARD ++11.5 -> +11.0 ++12.5 -> +12.0 +current rounding direction: FE_TONEAREST</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.6.3.1 The fegetround function (p: TBD) </li> +<li> 7.6.3.2 The fesetround function (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.6.3.1 The fegetround function (p: TBD) </li> +<li> 7.6.3.2 The fesetround function (p: TBD) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.6.3.1 The fegetround function (p: 212) </li> +<li> 7.6.3.2 The fesetround function (p: 212-213) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.6.3.1 The fegetround function (p: 193) </li> +<li> 7.6.3.2 The fesetround function (p: 193-194) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../math/nearbyint" title="c/numeric/math/nearbyint"> <span class="t-lines"><span>nearbyint</span><span>nearbyintf</span><span>nearbyintl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> rounds to an integer using current rounding mode <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../math/rint" title="c/numeric/math/rint"> <span class="t-lines"><span>rint</span><span>rintf</span><span>rintl</span><span>lrint</span><span>lrintf</span><span>lrintl</span><span>llrint</span><span>llrintf</span><span>llrintl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> rounds to an integer using current rounding mode with <br> exception if the result differs <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/fenv/feround" title="cpp/numeric/fenv/feround">C++ documentation</a></span> for <code>fegetround, fesetround</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/fenv/feround" class="_attribution-link">https://en.cppreference.com/w/c/numeric/fenv/feround</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Ffenv%2Ffetestexcept.html b/devdocs/c/numeric%2Ffenv%2Ffetestexcept.html new file mode 100644 index 00000000..6e100461 --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Ffetestexcept.html @@ -0,0 +1,60 @@ + <h1 id="firstHeading" class="firstHeading">fetestexcept</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><fenv.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int fetestexcept( int excepts );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Determines which of the specified subset of the floating-point exceptions are currently set. The argument <code>excepts</code> is a bitwise OR of the <a href="fe_exceptions" title="c/numeric/fenv/FE exceptions">floating-point exception macros</a>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> excepts </td> <td> - </td> <td> bitmask listing the exception flags to test </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Bitwise OR of the floating-point exception macros that are both included in <code>excepts</code> and correspond to floating-point exceptions currently set.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <fenv.h> +#include <float.h> + +#pragma STDC FENV_ACCESS ON + +void show_fe_exceptions(void) +{ + printf("current exceptions raised: "); + if(fetestexcept(FE_DIVBYZERO)) printf(" FE_DIVBYZERO"); + if(fetestexcept(FE_INEXACT)) printf(" FE_INEXACT"); + if(fetestexcept(FE_INVALID)) printf(" FE_INVALID"); + if(fetestexcept(FE_OVERFLOW)) printf(" FE_OVERFLOW"); + if(fetestexcept(FE_UNDERFLOW)) printf(" FE_UNDERFLOW"); + if(fetestexcept(FE_ALL_EXCEPT)==0) printf(" none"); + printf("\n"); +} + +int main(void) +{ + /* Show default set of exception flags. */ + show_fe_exceptions(); + + /* Perform some computations which raise exceptions. */ + printf("1.0/0.0 = %f\n", 1.0/0.0); /* FE_DIVBYZERO */ + printf("1.0/10.0 = %f\n", 1.0/10.0); /* FE_INEXACT */ + printf("sqrt(-1) = %f\n", sqrt(-1)); /* FE_INVALID */ + printf("DBL_MAX*2.0 = %f\n", DBL_MAX*2.0); /* FE_INEXACT FE_OVERFLOW */ + printf("nextafter(DBL_MIN/pow(2.0,52),0.0) = %.1f\n", + nextafter(DBL_MIN/pow(2.0,52),0.0)); /* FE_INEXACT FE_UNDERFLOW */ + show_fe_exceptions(); + + return 0; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">current exceptions raised: none +1.0/0.0 = inf +1.0/10.0 = 0.100000 +sqrt(-1) = -nan +DBL_MAX*2.0 = inf +nextafter(DBL_MIN/pow(2.0,52),0.0) = 0.0 +current exceptions raised: FE_DIVBYZERO FE_INEXACT FE_INVALID FE_OVERFLOW FE_UNDERFLOW</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.6.2.5 The fetestexcept function (p: 211-212) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.6.2.5 The fetestexcept function (p: 192-193) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="feclearexcept" title="c/numeric/fenv/feclearexcept"> <span class="t-lines"><span>feclearexcept</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> clears the specified floating-point status flags <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/fenv/fetestexcept" title="cpp/numeric/fenv/fetestexcept">C++ documentation</a></span> for <code>fetestexcept</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/fenv/fetestexcept" class="_attribution-link">https://en.cppreference.com/w/c/numeric/fenv/fetestexcept</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Ffenv%2Ffeupdateenv.html b/devdocs/c/numeric%2Ffenv%2Ffeupdateenv.html new file mode 100644 index 00000000..e05e65a3 --- /dev/null +++ b/devdocs/c/numeric%2Ffenv%2Ffeupdateenv.html @@ -0,0 +1,74 @@ + <h1 id="firstHeading" class="firstHeading">feupdateenv</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><fenv.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int feupdateenv( const fenv_t* envp );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>First, remembers the currently raised floating-point exceptions, then restores the floating-point environment from the object pointed to by <code>envp</code> (similar to <code><a href="feenv" title="c/numeric/fenv/feenv">fesetenv</a></code>), then raises the floating-point exceptions that were saved.</p> +<p>This function may be used to end the non-stop mode established by an earlier call to <code><a href="feholdexcept" title="c/numeric/fenv/feholdexcept">feholdexcept</a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> envp </td> <td> - </td> <td> pointer to the object of type <code>fenv_t</code> set by an earlier call to <code><a href="feholdexcept" title="c/numeric/fenv/feholdexcept">feholdexcept</a></code> or <code>fegetenv</code> or equal to <code><a href="fe_dfl_env" title="c/numeric/fenv/FE DFL ENV">FE_DFL_ENV</a></code> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>0</code> on success, non-zero otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <fenv.h> +#include <float.h> + +#pragma STDC FENV_ACCESS ON + +void show_fe_exceptions(void) +{ + printf("current exceptions raised: "); + if(fetestexcept(FE_DIVBYZERO)) printf(" FE_DIVBYZERO"); + if(fetestexcept(FE_INEXACT)) printf(" FE_INEXACT"); + if(fetestexcept(FE_INVALID)) printf(" FE_INVALID"); + if(fetestexcept(FE_OVERFLOW)) printf(" FE_OVERFLOW"); + if(fetestexcept(FE_UNDERFLOW)) printf(" FE_UNDERFLOW"); + if(fetestexcept(FE_ALL_EXCEPT)==0) printf(" none"); + printf("\n"); +} + +double x2 (double x) /* times two */ +{ + fenv_t curr_excepts; + + /* Save and clear current f-p environment. */ + feholdexcept(&curr_excepts); + + /* Raise inexact and overflow exceptions. */ + printf("In x2(): x = %f\n", x=x*2.0); + show_fe_exceptions(); + feclearexcept(FE_INEXACT); /* hide inexact exception from caller */ + + /* Merge caller's exceptions (FE_INVALID) */ + /* with remaining x2's exceptions (FE_OVERFLOW). */ + feupdateenv(&curr_excepts); + return x; +} + +int main(void) +{ + feclearexcept(FE_ALL_EXCEPT); + feraiseexcept(FE_INVALID); /* some computation with invalid argument */ + show_fe_exceptions(); + printf("x2(DBL_MAX) = %f\n", x2(DBL_MAX)); + show_fe_exceptions(); + + return 0; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">current exceptions raised: FE_INVALID +In x2(): x = inf +current exceptions raised: FE_INEXACT FE_OVERFLOW +x2(DBL_MAX) = inf +current exceptions raised: FE_INVALID FE_OVERFLOW</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.6.4.4 The feupdateenv function (p: 214-215) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.6.4.4 The feupdateenv function (p: 195-196) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="feholdexcept" title="c/numeric/fenv/feholdexcept"> <span class="t-lines"><span>feholdexcept</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> saves the environment, clears all status flags and ignores all future errors <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="feenv" title="c/numeric/fenv/feenv"> <span class="t-lines"><span>fegetenv</span><span>fesetenv</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> saves or restores the current floating-point environment <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fe_dfl_env" title="c/numeric/fenv/FE DFL ENV"> <span class="t-lines"><span>FE_DFL_ENV</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> default floating-point environment <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/fenv/feupdateenv" title="cpp/numeric/fenv/feupdateenv">C++ documentation</a></span> for <code>feupdateenv</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/fenv/feupdateenv" class="_attribution-link">https://en.cppreference.com/w/c/numeric/fenv/feupdateenv</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Ffenv.html b/devdocs/c/numeric%2Ffenv.html new file mode 100644 index 00000000..6cec45e9 --- /dev/null +++ b/devdocs/c/numeric%2Ffenv.html @@ -0,0 +1,52 @@ + <h1 id="firstHeading" class="firstHeading">Floating-point environment</h1> <p>The floating-point environment is the set of floating-point status flags and control modes supported by the implementation. It is thread-local, each thread inherits the initial state of its floating-point environment from the parent thread. Floating-point operations modify the floating-point status flags to indicate abnormal results or auxiliary information. The state of floating-point control modes affects the outcomes of some floating-point operations.</p> +<p>The floating-point environment access and modification is only meaningful when <a href="https://en.cppreference.com/w/cpp/preprocessor/impl" title="cpp/preprocessor/impl"><code> #pragma STDC FENV_ACCESS</code></a> is set to <code>ON</code>. Otherwise the implementation is free to assume that floating-point control modes are always the default ones and that floating-point status flags are never tested or modified. In practice, few current compilers, such as HP aCC, Oracle Studio, and IBM XL, support the <span class="co2">#pragma</span> explicitly, but most compilers allow meaningful access to the floating-point environment anyway.</p> +<h3 id="Types"> Types</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><fenv.h></code> </th> +</tr> <tr class="t-dsc"> <td> <code>fenv_t</code> </td> <td> The type representing the entire floating-point environment </td> +</tr> <tr class="t-dsc"> <td> <code>fexcept_t</code> </td> <td> The type representing all floating-point status flags collectively </td> +</tr> </table> <h3 id="Functions"> Functions</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fenv/feclearexcept" title="c/numeric/fenv/feclearexcept"> <span class="t-lines"><span>feclearexcept</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> clears the specified floating-point status flags <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fenv/fetestexcept" title="c/numeric/fenv/fetestexcept"> <span class="t-lines"><span>fetestexcept</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> determines which of the specified floating-point status flags are set <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fenv/feraiseexcept" title="c/numeric/fenv/feraiseexcept"> <span class="t-lines"><span>feraiseexcept</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> raises the specified floating-point exceptions <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fenv/feexceptflag" title="c/numeric/fenv/feexceptflag"> <span class="t-lines"><span>fegetexceptflag</span><span>fesetexceptflag</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> copies the state of the specified floating-point status flags from or to the floating-point environment <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fenv/feround" title="c/numeric/fenv/feround"> <span class="t-lines"><span>fegetround</span><span>fesetround</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> gets or sets rounding direction <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fenv/feenv" title="c/numeric/fenv/feenv"> <span class="t-lines"><span>fegetenv</span><span>fesetenv</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> saves or restores the current floating-point environment <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fenv/feholdexcept" title="c/numeric/fenv/feholdexcept"> <span class="t-lines"><span>feholdexcept</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> saves the environment, clears all status flags and ignores all future errors <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fenv/feupdateenv" title="c/numeric/fenv/feupdateenv"> <span class="t-lines"><span>feupdateenv</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> restores the floating-point environment and raises the previously raise exceptions <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <h3 id="Macros"> Macros</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions"> <span class="t-lines"><span>FE_ALL_EXCEPT</span><span>FE_DIVBYZERO</span><span>FE_INEXACT</span><span>FE_INVALID</span><span>FE_OVERFLOW</span><span>FE_UNDERFLOW</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> floating-point exceptions <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fenv/fe_round" title="c/numeric/fenv/FE round"> <span class="t-lines"><span>FE_DOWNWARD</span><span>FE_TONEAREST</span><span>FE_TOWARDZERO</span><span>FE_UPWARD</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> floating-point rounding direction <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fenv/fe_dfl_env" title="c/numeric/fenv/FE DFL ENV"> <span class="t-lines"><span>FE_DFL_ENV</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> default floating-point environment <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.6 Floating-point environment <fenv.h> (p: TBD) </li> +<li> 7.31.4 Floating-point environment <fenv.h> (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.6 Floating-point environment <fenv.h> (p: 150-156) </li> +<li> 7.31.4 Floating-point environment <fenv.h> (p: 332) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.6 Floating-point environment <fenv.h> (p: 206-215) </li> +<li> 7.31.4 Floating-point environment <fenv.h> (p: 455) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.6 Floating-point environment <fenv.h> (p: 187-196) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/fenv" title="cpp/numeric/fenv">C++ documentation</a></span> for <code>Floating-point environment</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/fenv" class="_attribution-link">https://en.cppreference.com/w/c/numeric/fenv</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fabs.html b/devdocs/c/numeric%2Fmath%2Fabs.html new file mode 100644 index 00000000..8564aeff --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fabs.html @@ -0,0 +1,53 @@ + <h1 id="firstHeading" class="firstHeading">abs, labs, llabs, imaxabs</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int abs( int n );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">long labs( long n );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long long llabs( long long n );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><inttypes.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">intmax_t imaxabs( intmax_t n );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Computes the absolute value of an integer number. The behavior is undefined if the result cannot be represented by the return type.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> n </td> <td> - </td> <td> integer value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The absolute value of <code>n</code> (i.e. <code>|n|</code>), if it is representable.</p> +<h3 id="Notes"> Notes</h3> <p>In 2's complement systems, the absolute value of the most-negative value is out of range, e.g. for 32-bit 2's complement type <code>int</code>, <code><a href="../../types/limits" title="c/types/limits">INT_MIN</a></code> is <code>-2147483648</code>, but the would-be result <code>2147483648</code> is greater than <code><a href="../../types/limits" title="c/types/limits">INT_MAX</a></code>, which is <code>2147483647</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> +#include <limits.h> + +int main(void) +{ + printf("abs(+3) = %d\n", abs(+3)); + printf("abs(-3) = %d\n", abs(-3)); + +// printf("%+d\n", abs(INT_MIN)); // undefined behavior on 2's complement systems +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">abs(+3) = 3 +abs(-3) = 3</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.8.2.1 The imaxabs function (p: 159) </li> +<li> 7.22.6.1 The abs, labs and llabs functions (p: 259) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.8.2.1 The imaxabs function (p: 218) </li> +<li> 7.22.6.1 The abs, labs and llabs functions (p: 356) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.8.2.1 The imaxabs function (p: 199-200) </li> +<li> 7.20.6.1 The abs, labs and llabs functions (p: 320) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 4.10.6.1 The abs function </li> +<li> 4.10.6.3 The labs function </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fabs" title="c/numeric/math/fabs"> <span class="t-lines"><span>fabs</span><span>fabsf</span><span>fabsl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes absolute value of a floating-point value (\(\small{|x|}\)|x|) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../complex/cabs" title="c/numeric/complex/cabs"> <span class="t-lines"><span>cabs</span><span>cabsf</span><span>cabsl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the magnitude of a complex number <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/abs" title="cpp/numeric/math/abs">C++ documentation</a></span> for <code>abs</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/abs" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/abs</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Facos.html b/devdocs/c/numeric%2Fmath%2Facos.html new file mode 100644 index 00000000..f697b7ed --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Facos.html @@ -0,0 +1,99 @@ + <h1 id="firstHeading" class="firstHeading">acos, acosf, acosl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float acosf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double acos( double arg );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double acosl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal32 acosd32( _Decimal32 arg );</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal64 acosd64( _Decimal64 arg );</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal128 acosd128( _Decimal128 arg );</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define acos( arg )</pre> +</td> <td> (7) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-6)</span> Computes the principal value of the arc cosine of <code>arg</code>.</div> <div class="t-li1"> +<span class="t-li">7)</span> Type-generic macro: If the argument has type <code>long double</code>, <span class="t-v">(3)</span> (<code>acosl</code>) is called. Otherwise, if the argument has integer type or the type <code>double</code>, <span class="t-v">(2)</span> (<code>acos</code>) is called. Otherwise, <span class="t-v">(1)</span> (<code>acosf</code>) is called. If the argument is complex, then the macro invokes the corresponding complex function (<code><a href="../complex/cacos" title="c/numeric/complex/cacos">cacosf</a></code>, <code><a href="../complex/cacos" title="c/numeric/complex/cacos">cacos</a></code>, <code><a href="../complex/cacos" title="c/numeric/complex/cacos">cacosl</a></code>).</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>The functions <span class="t-v">(4-6)</span> are declared if and only if the implementation predefines <code>__STDC_IEC_60559_DFP__</code> (i.e. the implementation supports decimal floating-point numbers).</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating-point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the arc cosine of <code>arg</code> (arccos(arg)) in the range [0 ; π], is returned.</p> +<p>If a domain error occurs, an implementation-defined value is returned (NaN where supported).</p> +<p>If a range error occurs due to underflow, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>Domain error occurs if <code>arg</code> is outside the range <code>[-1.0; 1.0]</code>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559):</p> +<ul> +<li> If the argument is +1, the value <code>+0</code> is returned; </li> +<li> If |arg| > 1, a domain error occurs and NaN is returned; </li> +<li> if the argument is NaN, NaN is returned. </li> +</ul> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <errno.h> +#include <fenv.h> +#include <math.h> +#include <stdio.h> +#include <string.h> + +#ifndef __GNUC__ +#pragma STDC FENV_ACCESS ON +#endif + +int main(void) +{ + printf("acos(-1) = %f\n", acos(-1)); + printf("acos(0.0) = %f 2*acos(0.0) = %f\n", acos(0), 2 * acos(0)); + printf("acos(0.5) = %f 3*acos(0.5) = %f\n", acos(0.5), 3 * acos(0.5)); + printf("acos(1) = %f\n", acos(1)); + + // error handling + errno = 0; feclearexcept(FE_ALL_EXCEPT); + printf("acos(1.1) = %f\n", acos(1.1)); + if (errno == EDOM) + perror(" errno == EDOM"); + if (fetestexcept(FE_INVALID)) + puts(" FE_INVALID raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">acos(-1) = 3.141593 +acos(0.0) = 1.570796 2*acos(0.0) = 3.141593 +acos(0.5) = 1.047198 3*acos(0.5) = 3.141593 +acos(1) = 0.000000 +acos(1.1) = nan + errno == EDOM: Numerical argument out of domain + FE_INVALID raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.12.4.1 The acos functions (p: TBD) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: TBD) </li> +<li> F.10.1.1 The acos functions (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.4.1 The acos functions (p: 173) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.1.1 The acos functions (p: 378) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.4.1 The acos functions (p: 238) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.1.1 The acos functions (p: 518) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.4.1 The acos functions (p: 218) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.1.1 The acos functions (p: 455) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.2.1 The acos function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="asin" title="c/numeric/math/asin"> <span class="t-lines"><span>asin</span><span>asinf</span><span>asinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc sine (\({\small\arcsin{x} }\)arcsin(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atan" title="c/numeric/math/atan"> <span class="t-lines"><span>atan</span><span>atanf</span><span>atanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc tangent (\({\small\arctan{x} }\)arctan(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atan2" title="c/numeric/math/atan2"> <span class="t-lines"><span>atan2</span><span>atan2f</span><span>atan2l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc tangent, using signs to determine quadrants <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="cos" title="c/numeric/math/cos"> <span class="t-lines"><span>cos</span><span>cosf</span><span>cosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes cosine (\({\small\cos{x} }\)cos(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../complex/cacos" title="c/numeric/complex/cacos"> <span class="t-lines"><span>cacos</span><span>cacosf</span><span>cacosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc cosine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/acos" title="cpp/numeric/math/acos">C++ documentation</a></span> for <code>acos</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/acos" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/acos</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Facosh.html b/devdocs/c/numeric%2Fmath%2Facosh.html new file mode 100644 index 00000000..2288743c --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Facosh.html @@ -0,0 +1,87 @@ + <h1 id="firstHeading" class="firstHeading">acosh, acoshf, acoshl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float acoshf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double acosh( double arg );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double acoshl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define acosh( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the inverse hyperbolic cosine of <code>arg</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If the argument has type <code>long double</code>, <code>acoshl</code> is called. Otherwise, if the argument has integer type or the type <code>double</code>, <code>acosh</code> is called. Otherwise, <code>acoshf</code> is called. If the argument is complex, then the macro invokes the corresponding complex function (<code><a href="http://en.cppreference.com/w/c/numeric/complex/cacosh"><span class="kw799">cacoshf</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/cacosh"><span class="kw798">cacosh</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/cacosh"><span class="kw800">cacoshl</span></a></code>).</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value representing the area of a hyperbolic sector </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the inverse hyperbolic cosine of <code>arg</code> (cosh<sup class="t-su">-1</sup>(arg), or arcosh(arg)) on the interval [0, +∞], is returned.</p> +<p>If a domain error occurs, an implementation-defined value is returned (NaN where supported).</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the argument is less than 1, a domain error occurs.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> if the argument is less than 1, <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised an NaN is returned </li> +<li> if the argument is 1, +0 is returned </li> +<li> if the argument is +∞, +∞ is returned </li> +<li> if the argument is NaN, NaN is returned. </li> +</ul> <h3 id="Notes"> Notes</h3> <p>Although the C standard names this function "arc hyperbolic cosine", the inverse functions of the hyperbolic functions are the area functions. Their argument is the area of a hyperbolic sector, not an arc. The correct name is "inverse hyperbolic cosine" (used by POSIX) or "area hyperbolic cosine".</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> +#include <errno.h> +#include <fenv.h> +#pragma STDC FENV_ACCESS ON + +int main(void) +{ + printf("acosh(1) = %f\nacosh(10) = %f\n", acosh(1), acosh(10)); + printf("acosh(DBL_MAX) = %f\nacosh(Inf) = %f\n", acosh(DBL_MAX), acosh(INFINITY)); + // error handling + errno = 0; feclearexcept(FE_ALL_EXCEPT); + printf("acosh(0.5) = %f\n", acosh(0.5)); + if (errno == EDOM) + perror(" errno == EDOM"); + if (fetestexcept(FE_INVALID)) + puts(" FE_INVALID raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">acosh(1) = 0.000000 +acosh(10) = 2.993223 +acosh(DBL_MAX) = 710.475860 +acosh(Inf) = inf +acosh(0.5) = -nan + errno == EDOM: Numerical argument out of domain + FE_INVALID raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.12.5.1 The acosh functions (p: TBD) </li> +<li> 7.27 Type-generic math <tgmath.h> (p: TBD) </li> +<li> F.10.2.1 The acosh functions (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.5.1 The acosh functions (p: 175) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.2.1 The acosh functions (p: 379) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.5.1 The acosh functions (p: 240) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.2.1 The acosh functions (p: 520) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.5.1 The acosh functions (p: 221) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.2.1 The acosh functions (p: 457) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="asinh" title="c/numeric/math/asinh"> <span class="t-lines"><span>asinh</span><span>asinhf</span><span>asinhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes inverse hyperbolic sine (\({\small\operatorname{arsinh}{x} }\)arsinh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atanh" title="c/numeric/math/atanh"> <span class="t-lines"><span>atanh</span><span>atanhf</span><span>atanhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes inverse hyperbolic tangent (\({\small\operatorname{artanh}{x} }\)artanh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="cosh" title="c/numeric/math/cosh"> <span class="t-lines"><span>cosh</span><span>coshf</span><span>coshl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes hyperbolic cosine (\({\small\cosh{x} }\)cosh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../complex/cacosh" title="c/numeric/complex/cacosh"> <span class="t-lines"><span>cacosh</span><span>cacoshf</span><span>cacoshl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc hyperbolic cosine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/acosh" title="cpp/numeric/math/acosh">C++ documentation</a></span> for <code>acosh</code> </td> +</tr> </table> <h3 id="External_links"> External links</h3> <table> <tr style="vertical-align:top;"> <td> </td> <td> +<a rel="nofollow" class="external text" href="http://mathworld.wolfram.com/InverseHyperbolicCosine.html">Weisstein, Eric W. "Inverse Hyperbolic Cosine."</a> From MathWorld — A Wolfram Web Resource. </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/acosh" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/acosh</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fasin.html b/devdocs/c/numeric%2Fmath%2Fasin.html new file mode 100644 index 00000000..bef4c96d --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fasin.html @@ -0,0 +1,98 @@ + <h1 id="firstHeading" class="firstHeading">asin, asinf, asinl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float asinf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double asin( double arg );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double asinl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal32 asind32( _Decimal32 arg );</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal64 asind64( _Decimal64 arg );</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal128 asind128( _Decimal128 arg );</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define asin( arg )</pre> +</td> <td> (7) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-6)</span> Computes the principal values of the arc sine of <code>arg</code>.</div> <div class="t-li1"> +<span class="t-li">7)</span> Type-generic macro: If the argument has type <code>long double</code>, <span class="t-v">(3)</span> (<code>asinl</code>) is called. Otherwise, if the argument has integer type or the type <code>double</code>, <span class="t-v">(2)</span> (<code>asin</code>) is called. Otherwise, <span class="t-v">(1)</span> (<code>asinf</code>) is called. If the argument is complex, then the macro invokes the corresponding complex function (<code><a href="../complex/casin" title="c/numeric/complex/casin">casinf</a></code>, <code><a href="../complex/casin" title="c/numeric/complex/casin">casin</a></code>, <code><a href="../complex/casin" title="c/numeric/complex/casin">casinl</a></code>).</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>The functions <span class="t-v">(4-6)</span> are declared if and only if the implementation predefines <code>__STDC_IEC_60559_DFP__</code> (i.e. the implementation supports decimal floating-point numbers).</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating-point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> If no errors occur, the arc sine of <code>arg</code> (arcsin(arg)) in the range [-<span><span>π</span><span>/</span><span>2</span></span> ; +<span><span>π</span><span>/</span><span>2</span></span>], is returned. <p>If a domain error occurs, an implementation-defined value is returned (NaN where supported).</p> +<p>If a range error occurs due to underflow, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>Domain error occurs if <code>arg</code> is outside the range <code>[-1.0; 1.0]</code>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559):</p> +<ul> +<li> if the argument is ±0, it is returned unmodified; </li> +<li> if |arg| > 1, a domain error occurs and NaN is returned; </li> +<li> if the argument is NaN, NaN is returned. </li> +</ul> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <errno.h> +#include <fenv.h> +#include <math.h> +#include <stdio.h> +#include <string.h> + +#ifndef __GNUC__ +#pragma STDC FENV_ACCESS ON +#endif + +int main(void) +{ + printf("asin( 1.0) = %+f, 2*asin( 1.0)=%+f\n", asin(1), 2 * asin(1)); + printf("asin(-0.5) = %+f, 6*asin(-0.5)=%+f\n", asin(-0.5), 6 * asin(-0.5)); + + // special values + printf("asin(0.0) = %1f, asin(-0.0)=%f\n", asin(+0.0), asin(-0.0)); + + // error handling + errno = 0; feclearexcept(FE_ALL_EXCEPT); + printf("asin(1.1) = %f\n", asin(1.1)); + if (errno == EDOM) + perror(" errno == EDOM"); + if (fetestexcept(FE_INVALID)) + puts(" FE_INVALID raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">asin( 1.0) = +1.570796, 2*asin( 1.0)=+3.141593 +asin(-0.5) = -0.523599, 6*asin(-0.5)=-3.141593 +asin(0.0) = 0.000000, asin(-0.0)=-0.000000 +asin(1.1) = nan + errno == EDOM: Numerical argument out of domain + FE_INVALID raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.12.4.2 The asin functions (p: TBD) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: TBD) </li> +<li> F.10.1.2 The asin functions (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.4.2 The asin functions (p: 174) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.1.2 The asin functions (p: 378) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.4.2 The asin functions (p: 238) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.1.2 The asin functions (p: 518) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.4.2 The asin functions (p: 219) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.1.2 The asin functions (p: 456) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.2.2 The asin function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="acos" title="c/numeric/math/acos"> <span class="t-lines"><span>acos</span><span>acosf</span><span>acosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc cosine (\({\small\arccos{x} }\)arccos(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atan" title="c/numeric/math/atan"> <span class="t-lines"><span>atan</span><span>atanf</span><span>atanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc tangent (\({\small\arctan{x} }\)arctan(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atan2" title="c/numeric/math/atan2"> <span class="t-lines"><span>atan2</span><span>atan2f</span><span>atan2l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc tangent, using signs to determine quadrants <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="sin" title="c/numeric/math/sin"> <span class="t-lines"><span>sin</span><span>sinf</span><span>sinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes sine (\({\small\sin{x} }\)sin(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../complex/casin" title="c/numeric/complex/casin"> <span class="t-lines"><span>casin</span><span>casinf</span><span>casinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc sine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/asin" title="cpp/numeric/math/asin">C++ documentation</a></span> for <code>asin</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/asin" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/asin</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fasinh.html b/devdocs/c/numeric%2Fmath%2Fasinh.html new file mode 100644 index 00000000..9944cbc7 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fasinh.html @@ -0,0 +1,59 @@ + <h1 id="firstHeading" class="firstHeading">asinh, asinhf, asinhl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float asinhf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double asinh( double arg );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double asinhl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define asinh( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the inverse hyperbolic sine of <code>arg</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If the argument has type <code>long double</code>, <code>asinhl</code> is called. Otherwise, if the argument has integer type or the type <code>double</code>, <code>asinh</code> is called. Otherwise, <code>asinhf</code> is called. If the argument is complex, then the macro invokes the corresponding complex function (<code><a href="http://en.cppreference.com/w/c/numeric/complex/casinh"><span class="kw802">casinhf</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/casinh"><span class="kw801">casinh</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/casinh"><span class="kw803">casinhl</span></a></code>).</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value representing the area of a hyperbolic sector </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the inverse hyperbolic sine of <code>arg</code> (sinh<sup class="t-su">-1</sup>(arg), or arsinh(arg)), is returned.</p> +<p>If a range error occurs due to underflow, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> if the argument is ±0 or ±∞, it is returned unmodified </li> +<li> if the argument is NaN, NaN is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p>Although the C standard names this function "arc hyperbolic sine", the inverse functions of the hyperbolic functions are the area functions. Their argument is the area of a hyperbolic sector, not an arc. The correct name is "inverse hyperbolic sine" (used by POSIX) or "area hyperbolic sine".</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> + +int main(void) +{ + printf("asinh(1) = %f\nasinh(-1) = %f\n", asinh(1), asinh(-1)); + // special values + printf("asinh(+0) = %f\nasinh(-0) = %f\n", asinh(0.0), asinh(-0.0)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">asinh(1) = 0.881374 +asinh(-1) = -0.881374 +asinh(+0) = 0.000000 +asinh(-0) = -0.000000</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.5.2 The asinh functions (p: 240-241) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.2.2 The asinh functions (p: 520) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.5.2 The asinh functions (p: 221) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.2.2 The asinh functions (p: 457) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="acosh" title="c/numeric/math/acosh"> <span class="t-lines"><span>acosh</span><span>acoshf</span><span>acoshl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes inverse hyperbolic cosine (\({\small\operatorname{arcosh}{x} }\)arcosh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atanh" title="c/numeric/math/atanh"> <span class="t-lines"><span>atanh</span><span>atanhf</span><span>atanhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes inverse hyperbolic tangent (\({\small\operatorname{artanh}{x} }\)artanh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="sinh" title="c/numeric/math/sinh"> <span class="t-lines"><span>sinh</span><span>sinhf</span><span>sinhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes hyperbolic sine (\({\small\sinh{x} }\)sinh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../complex/casinh" title="c/numeric/complex/casinh"> <span class="t-lines"><span>casinh</span><span>casinhf</span><span>casinhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc hyperbolic sine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/asinh" title="cpp/numeric/math/asinh">C++ documentation</a></span> for <code>asinh</code> </td> +</tr> </table> <h3 id="External_links"> External links</h3> <table> <tr> <td> +<a rel="nofollow" class="external text" href="https://mathworld.wolfram.com/InverseHyperbolicSine.html">Weisstein, Eric W. "Inverse Hyperbolic Sine."</a> From MathWorld — A Wolfram Web Resource. </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/asinh" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/asinh</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fatan.html b/devdocs/c/numeric%2Fmath%2Fatan.html new file mode 100644 index 00000000..4ba682e3 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fatan.html @@ -0,0 +1,79 @@ + <h1 id="firstHeading" class="firstHeading">atan, atanf, atanl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float atanf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double atan( double arg );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double atanl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal32 atand32( _Decimal32 arg );</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal64 atand64( _Decimal64 arg );</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal128 atand128( _Decimal128 arg );</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define atan( arg )</pre> +</td> <td> (7) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-6)</span> Computes the principal value of the arc tangent of <code>arg</code>.</div> <div class="t-li1"> +<span class="t-li">7)</span> Type-generic macro: If the argument has type <code>long double</code>, <span class="t-v">(3)</span> (atanl) is called. Otherwise, if the argument has integer type or the type <code>double</code>, <span class="t-v">(2)</span> (<code>atan</code>) is called. Otherwise, <span class="t-v">(1)</span> (<code>atanf</code>) is called. If the argument is complex, then the macro invokes the corresponding complex function (<code><a href="../complex/catan" title="c/numeric/complex/catan">catanf</a></code>, <code><a href="../complex/catan" title="c/numeric/complex/catan">catan</a></code>, <code><a href="../complex/catan" title="c/numeric/complex/catan">catanl</a></code>).</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>The functions <span class="t-v">(4-6)</span> are declared if and only if the implementation predefines <code>__STDC_IEC_60559_DFP__</code> (i.e. the implementation supports decimal floating-point numbers).</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> If no errors occur, the arc tangent of <code>arg</code> (arctan(arg)) in the range [- <span><span>π</span><span>/</span><span>2</span></span> ; +<span><span>π</span><span>/</span><span>2</span></span>] radians, is returned. <p>If a range error occurs due to underflow, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559):</p> +<ul> +<li> if the argument is ±0, it is returned unmodified; </li> +<li> if the argument is +∞, +π/2 is returned; </li> +<li> if the argument is -∞, -π/2 is returned; </li> +<li> if the argument is NaN, NaN is returned. </li> +</ul> <h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/atan.html">POSIX specifies</a> that in case of underflow, <code>arg</code> is returned unmodified, and if that is not supported, an implementation-defined value no greater than <code><a href="../../types/limits" title="c/types/limits">DBL_MIN</a></code>, <code><a href="../../types/limits" title="c/types/limits">FLT_MIN</a></code>, and <code><a href="../../types/limits" title="c/types/limits">LDBL_MIN</a></code> is returned.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <math.h> +#include <stdio.h> + +int main(void) +{ + printf("atan(1) = %f, 4*atan(1)=%f\n", atan(1), 4 * atan(1)); + // special values + printf("atan(Inf) = %f, 2*atan(Inf) = %f\n", atan(INFINITY), 2 * atan(INFINITY)); + printf("atan(-0.0) = %+f, atan(+0.0) = %+f\n", atan(-0.0), atan(0)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">atan(1) = 0.785398, 4*atan(1)=3.141593 +atan(Inf) = 1.570796, 2*atan(Inf) = 3.141593 +atan(-0.0) = -0.000000, atan(+0.0) = +0.000000</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.12.4.3 The atan functions (p: TBD) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: TBD) </li> +<li> F.10.1.3 The atan functions (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.4.3 The atan functions (p: 174) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.1.3 The atan functions (p: 378) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.4.3 The atan functions (p: 238-239) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.1.3 The atan functions (p: 519) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.4.3 The atan functions (p: 219) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.1.3 The atan functions (p: 456) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.2.3 The atan function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="atan2" title="c/numeric/math/atan2"> <span class="t-lines"><span>atan2</span><span>atan2f</span><span>atan2l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc tangent, using signs to determine quadrants <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="asin" title="c/numeric/math/asin"> <span class="t-lines"><span>asin</span><span>asinf</span><span>asinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc sine (\({\small\arcsin{x} }\)arcsin(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="acos" title="c/numeric/math/acos"> <span class="t-lines"><span>acos</span><span>acosf</span><span>acosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc cosine (\({\small\arccos{x} }\)arccos(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="tan" title="c/numeric/math/tan"> <span class="t-lines"><span>tan</span><span>tanf</span><span>tanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes tangent (\({\small\tan{x} }\)tan(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../complex/catan" title="c/numeric/complex/catan"> <span class="t-lines"><span>catan</span><span>catanf</span><span>catanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc tangent <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/atan" title="cpp/numeric/math/atan">C++ documentation</a></span> for <code>atan</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/atan" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/atan</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fatan2.html b/devdocs/c/numeric%2Fmath%2Fatan2.html new file mode 100644 index 00000000..94dcdd22 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fatan2.html @@ -0,0 +1,103 @@ + <h1 id="firstHeading" class="firstHeading">atan2, atan2f, atan2l</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float atan2f( float y, float x );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double atan2( double y, double x );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double atan2l( long double y, long double x );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal32 atan2d32( _Decimal32 y, _Decimal32 x );</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal64 atan2d64( _Decimal64 y, _Decimal64 x );</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal128 atan2d128( _Decimal128 y, _Decimal128 x );</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define atan2( y, x )</pre> +</td> <td> (7) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-6)</span> Computes the arc tangent of <code>y / x</code> using the signs of arguments to determine the correct quadrant.</div> <div class="t-li1"> +<span class="t-li">7)</span> Type-generic macro: If any argument has type <code>long double</code>, <span class="t-v">(3)</span> (<code>atan2l</code>) is called. Otherwise, if any argument has integer type or has type <code>double</code>, <span class="t-v">(2)</span> (<code>atan2</code>) is called. Otherwise, <span class="t-v">(1)</span> (<code>atan2f</code>) is called.</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>The functions <span class="t-v">(4-6)</span> are declared if and only if the implementation predefines <code>__STDC_IEC_60559_DFP__</code> (i.e. the implementation supports decimal floating-point numbers).</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> x, y </td> <td> - </td> <td> floating-point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> If no errors occur, the arc tangent of <code>y / x</code> (arctan(<span><span>y</span><span>/</span><span>x</span></span>)) in the range [-π ; +π] radians, is returned. <div class="t-plot"> <div class="t-plot-left">Y argument</div> <div class="t-plot-right">Return value</div> <div class="t-plot-image-left-right"><a href="https://en.cppreference.com/w/File:math-atan2.png" class="image"><img alt="math-atan2.png" src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAR0AAADwCAMAAAAKGUChAAADAFBMVEX+/v75/LS75KA+lrf+4Y1sxKXm9Zn////p9pzr96D1+6/T7ZzB5qDP7J3K6p50x6X//r3+yHbh85nz+qzVPU78/rnF6J9EnbTaRUze8Zn+5ZP+76P/8ajwZ0TkVEm24aH09PTuY0Xr6+uP0qTa8Jru+KSi2aQziLzROU7Pz8+W1aTKMUyw36O7IUlXsaz+7J5HoLN7e3v+znyuE0bw+aj9wnHpW0dmwaWzGEfGLUuRkZGs3aQ2gbq4HUjx8fE7e7fnWUj/+rY2jrvXQU7AJkqb16T3gkxNY6xQYKn+55bNNk2BzaV7yqWqDkX9uWrbR0v1dUeo26T/+LPqXkY+d7X1cUT+6Zr+0X78pFxIa7D//LnZQ037nFjiUUo5kLr/86s7k7hBdLT4h0/hUEqnC0T8qV76l1b+3on2fUo0i7xDcbJUrq3+zHv+ynhUW6j0bUP9u2xKaK7+3YjgTktSq67+24b+2YTzakOGz6TlVkg5frj9s2VatKpQqa9JorHDKkr9xXT2ekg0hLtct6r/9q9Op7D5+fn9vm2jBkPdSkv9wG/5lFVLpLH+45D9tmf7oFrsYEZgvKdFbrFivqb9sWL+1oNXV6b9rWDeTErR0Jr5jFH+1IHl5eUoKk/9r2KMBDn9/f35kVNeual1uJJjISnKdUM/k6yYMzMkJCVrOjTEQkIrZne904qpjFVlZmVzYETe3t6Vpm0jR1xTYFVycnK8vLzHx8dtcFPyyXrR6ZgcFh4mOlZwqYUUCRY7j6tTVVFXECRtSDn0zX2EhITe3qVwVTvW1tb8p10zhrvbekbDzIYqLi+0tLSOjmFfu6hKSk4sV2NFRUCYmJjC2Y5rg12KxJZIm6LSxYejo6N9KCvUu3WmzpNJdl/cfkg0OzeMjIxXqZmurq4+Pz2SeElklnaenp7Tsm22x3/vxnjg4KbBoGE3NjGpOTmmpqY1f5Wrq6vORkWmuHeSZjk4hqCQSyzrv3OpqanX25ru7K4ydovXZz+zsoStYDg+/rT+/KD55LewV9JtAAAgAElEQVR42uybX2hTWR7Hz4Nwnws+iKCkeTLIPLSi7AYmCF0KK8xEEGnB9UVn1IcZKhUr4sOOL+lEcfTB0GCCU+EuaQJpC5OW4otNSivLCNI+mcKu2GKRGJmyWJ/3/D+/c+65yW3+wK72VzOdJDf3zye/3/f3554iBznYEOK/tR9HPoRpr6EgD7Jn1MoHLY+WPxj4w/Ji2W+krh85vlAgGvqDkP6GThQ+gwezfgB58GvbIO82lt04lmP7HcLXkIcWp0Mvl52I2MbDqTE2vm/mKuw/fFfmd4L8Tk3bGiHmdsi6L+R7ffo+PFv7nQ9yvJ7DYYsT4F+UPDF2cg4KRL7pN6PIt7oDiUrsrLXjqy/ReO7jTdI1kSVK2ovo1jXBomFtyFCwjUzPQUhza3/dsbytolNKhPgSfPZgi1IfvTD36ucOcHPPHv20oIH0aFfmiOAGAiiiyyO/pqcrvQInylXDAZKBWgsk7RE4euyP1oLZccwQUk4SWO0tCUf+2+1OPCmyHa3yS5rBP8XLEuSYlyEUGcHMj4CAIbilA5RBkwrbc+0T+guOzy48H/H7bT24/zvaMcx6x0hutkIBWcsM/+ql2Y8T4JXW9tPetnbdMRO8oTt+UQtEGJlVhX/8++zNs4nnY949+e1FnA88v4bnA/OJcXxQDEpddcRFIMMC65ilrAUXpRXowTWho0oU7ICqQDZDC0Bpp8FBzTNn0JbN81W1cw5NFdysELUMg7Q6IkBT43i39L7l61qtCI/3mDYXC4oH6Zsi0IuqnIXUCZvtmNmyaNsjsCWC+gG131/DjGoR7ABEfCB/QJYzM/MRsjy3bYWAzxqFTkCt0Tsh7ROB9ep/09DefGdvvrM339mb77Q130GhbDbEIiSWzSb25jvaxrPPokurEfLkzbNoaTq0N9+BB83OOc50H/m/tXkn8e8Pe/OdyYQwclax+ZfzZDsSVRsfvvj5TmK6XH7Jfmbxfub6pmf5O5GN0Bc/34m5v/7MbDFCX40+Y+9kf1vZm+/EXAzmV05nJYucF1P09ez0ymTsi5/vUDrcd9CHUjg8XUKf/kCzq28ic327nO+E5yY5ruyL+cnPYb4Tc7+j9vN32Heyr5eW1kLO21fOp2fYPu1uvjP3bCrEnkZezvUtfQ7znZj7DTeqO23Md9D8/FSIwpl89sEJTc1+BvMdTOcYsW+OBaDTZL4TmQrRV8NTWNA3PvBNJ8Ox/y8LhySimHuMG6bT5nwnwiNr9ilW95dr/PXslJtv3crNbLmJzezalqNAd/7EbReR5TPfEXSI76CNVxxg2M0V0tewXbx4ET/Onz9/mNpNbCexnSB2htiDXmyHeg8dOnQD/xu5MTJyltrps6dP3759+wqxwcHBC8QePXr0r388eXL37t1Ldy/9jdj9+8PDw8+/JzYx8fjx44cPb9269Qu2b7FdvTqO7c74nePYfiLWg+1HbD9g6yc2RCwzlFr4T1R6h6Tz9WKk3flOhOmOM7n6xkmQ6KIWduMYj+BD8Sg+gg7F84Di6SV4CCFsnM9pSofyMehgPJcuWehMcDq3IJ072AQcPzqZd8VaVMpQzP2a2Ve70x3LfCf2Ymo2gbKrs2ju5Wx0epJvEnaTSeU9Bp2bgs4Jk86NIHTu3vWhQ+A8ZK7zC2FD6BA2gk5Pj0FniFlmofhuKyrnOzH3K25upM35zvzr19EsCr0KIbSy9iIh5juEjsd77LH1gPOx+I6IrcFBxsekc/++SYd7jqRzh7uOosPZKDoZDKeS2YK6o+h0Z/0OoUO9R/Ix6VA+Z0BsHRKxNTJC+eyezoSio1Tn+HEOp6cH0pFhNYTDqpJKUToiZ/2FmxvpzvodRgd6jwwtzXvapjN8n9GZmOC+o8fVuN1z+rWwWkhJOkx3/s7NjQSvxncz32F0lPf4xRYPLcXnxu7oDA8PN6TD4DSiUykuZCgd2TfF8n/mVo20PERpON/BOSsJveci057Dtrwl6fTquqzoXAlCx9TkcZmwfhIJyyLINKyE73DdyR/l5rZIp9l8R9BheNIyuM4DOidPWGNr13SeN6JjVWSlOQvMcxgdMd/JHz3FrBrpzvodTCceF8GVNOlgPieFMoPYao2ON2OBSpDT6RF0DM+pUM1JpcbGcGTJ+U6ewzlajXRn/U7YPRCPM0CGNMuyB3iPqTw3qPJwOrdboXNVVIIgX5lxxVK5RofNd/JHuFUj3Vm/A+hQPILOxY7QuXTJoOPV5HGWzu94Woh+LaxSHM6Ypjv7uVVb7bOarN/BdA54vKdB4jIqQkmH8AlG57GgY8SVRZH7medUhOZwOnK+kx/ghumsTPdNLyXYdYdeLnVm/Y5Gx5PYz3uV2ZPUVU5vREdVO1KTBR3QYOlxJT2nItmMXWeqzLrQ/MA5ZpjOh7dOYnWNXttk9PdSZ9bvhN1zB4J5j8xbMGuNQF220tG7LEZHlcnjmiTbCh2cylVYcTqiVs6fU3RiIceZXqJvrZRKpc6s38F0zgk6pjQLPsp7JB2L8zSj89yPjkeSNUWWYUXZXB/VdIeddj3H6p3Yezp5SPyWLZU6s36H0KHec0BEF5Bm5T1QeXo16QlAhzVZqscCgSV7c1Xq6J0nC6sxZhjO6BaY7+ST3EjOchJ9r+iVRd84pVJn1u9QOgwP56N7j5G4VEmolTxB6cjRjuo/VWuuCh1Bh8xzqOcAOutgvpNPM7tGclZi6e0kUeXQ9NLSxkY01on1O4yOv/fAorBtOhOwUPYUgt4yUKTyMUFndHQUznfy17hhOom+T5Ooz4lEUCKRKJUSqBPrd8Ku0H3Oh2rPNpBmo+FSRY+nUVcDsIZ05OxCJSweV3oZqIpA4TmEzjrUHRr8+BRxZH2awlZy+vpIzlpdjXZovjMwoNGh3rOdFondk9Z172mNjhrs3LHkK1no8MaTk6FsRi+vw5zFPftwtWvzHUEHek8ynS64OUqHa89N3Xv0rN4CHW3oBT0HjNhrC8pvRkc5nnUw38nfZHay2rX5zoDCc07hSca36znhPUqZZWw1ylpUeOx0ZGDJUbtGRyt0MkMZ5Tmj1C5fxr4D5ju8RT6Z69p8h9EZAHRI4koWtutu2kOHNeuwVbfTuWCj422x5LgUKjJls1UcykDPwWTIY98+TXf4PYGW6TSf7+xnrYrmPYVqsuC6daU9MnGdALFlNluQzhONDhh8wWw+DlsILV3VlpcXMqAGpH6D/zE6cr5zhluua/Od/aKVGwB03Hh8MZ5M16tJpcyw6tHGPDY6jww63xt0PKrTAzynv7hZ2ZzJZFJcj0e572A4mA6Y7wA6XZrvkAkA8B4mzfWqu4g9yC2kPYnLbLdUN+FD576NzrfCdWRn/oOis7O5ujO0PLMD6VwmJunw+U4vt1zX5juYDcMD6Rwo1As5t45ze71+zU7ngYfOaUjnn4DOsI/veOMK+w2VneLyu9qWEh2BZp+hO7387nWua/MdNj+C2kPDq+BWt7HzVJ9WQdEM+i0rHew9jeg8fnwLuA7oPn8U+WqoOFPB2SqT2SwvmJ4j6cj5TpnfPNoNnV3Odyib/VB7KJ3t7WSyXt2uunFwl8szBzNluREdfpOPuY7emstSZ6j4frNC6NQIHMBmn7B1MN8p32B26GPb63f85jti+mhJXfHC4uJ2Mg1aCnlr3VQeSeeKHx292JFxJdsrzGahNlQrljeLmVRmLCUy+ShNVfsYn3v7YK1cppU6tlzb63f85jtHjhwBdAZg4VOvLrrbtKfweI9FlxvRee5VHS7JGp1yZatYe1pbF9lKlxwM5949qDtlDmfkY9vrd/zmO4KOIATFOVfFaT0dr1P3UUWhTkfNwCx0WELXqh1VCIo5u2wgNmvvZjZrvxdJVIkaUAXVPUZHzXfKfKR9+mOkO3+fRekI7zH54NRF2orCYjUtpVkuXIHCbGQtPzrsRo1Oh6er/v4dUiHPVIqVWk15jiY5BM5BON8pczhnP7a7fsd3vqPoCHU2etK4m6tTPFY6vc3p8EpZb7GgJBM6O++3cDqf2WI14JiXDfUcEVlsvlO+ze1ju+t3fOc74o6ZN7x4YejituKp5j1Smb263JSOmFwY6WqoWHy/jlPVZiZl9xyK5t7Bg5ruXOFGIiuRFe1kIpwNd2r9zqlTFjqUD6Oz7W4XFutJ1ZHChkJKD2gm7HRExjIlmefyoZ1KcfVdprJcSVk8554wTkfkLLboY3AQ+85KaYr/TVZoKfp6I9Sh+Y6gYxXnc6Ruri/myMQHthSG8jBdlnQGJR1yQ4LerGGaDBOWlq5od7W5XNtZzxA9vq7JMY+pg8T+Cuc75UFF59OLKf53Na/XHGc+0aH5Dr1Pf0QnZPRduQJWnzSYZ2h4xE1j0WoZdGS18xBWgrzUESUyu+e5WsykQCY3g4oanO+UL3DDdNAKp5N4P7f2X9rONiaq9IrjY0Jyq/2iqyauWIPTbNoJpQQVA6RSzZK2Y1I0WAmyNWZ3RUzjrqxGCeGDtjGDLyluNlLL7qxl05rSrs5gYAZDu2XiLNDuMKVQU9g0gQrdxpds2kzqS9Z+6HPO837vc2FGuEd3Y9xI4m//53/O87/PHSZ6cs13KgPDIfxFOB6PD8t8x0nHce5at5tF8VI9Sm/xkzrfeHQ6YhfkntwkggtNOYTOowcd/GRlH1WCTlDznXehXrv2v98QV+Z0wt294VgqnFu+Ex6cKkliQ1UM9vbOyHynsJDdgrE1mL4Z8gc5+tojnIc9nHChM8I8WUhHHK9EonPrEZGNPDzYLIfpZn0wGFTznaF3Wf2X04H/+d2jljX+WW75Tl/SV5AaBrlUhLV8R9DR7PnlNWrks04+59J6i+2E0pfNdMjEUjdBg3Lw0Yy7HXM0wWCtmu8MfUDrIuss/N3Qw1Gfb2wip3yH/BnLN4ibVEUF3M0VvkPvlmWnnvMUj31lxt6SM91Oh08s7Cs6zUv1roKnD7SnTrJjlXRjphoKJxicVPKdoYusyEQPxbv9IZ+/xO+biFQGUj055Tv+VNzni5TAF47FK//9sFLkO4DGJh/jaD+vN5fqPJuk8SxIp81A555NOXnOrmJsgusnFd8ZOswqE7BiJYMlPZa/L2yFppLJQG75TkEqZvl6k+y3urpHRb5TKMowvNZIcxbq0ZdCZefhAaGJDj4AxVxHCXUYHWgrYcfHG01znFVtba2a7wz9kFVmse9nDU74uqZHAc1oiNCJiXyHozHpR7oP0uG3w14XSyHQ0cWTJR1FO/fgiSc7PTTaLUeDQ+gEJ5V8ZwiviV+6lA2d+fOd+Fh4dCwUjoSt2Zh/arpAnLPKy8sLTfpxmg+bXCcU9Wg7Dy6EzJYlHboLCtdpE6sOTUrtbeWwnCCznFpa6q48RC/61tVlFpvvdMUrJsK+ymSlNTwxMxGW+Y5KZ1ehYXqJ2bVbm1yCDnMeSeeITmekQaXDt2SuHLxqyya5UI4yqhTdYGm+UzeCVZfxLN+ht8U18Qj7cajnvKYexXnoSd1IB0+gbJyLLVnCud0h0hzNjtmkWq+QoXRkvjPUwCrjWb5TLsoESLQXb67dmnpseOTQQjqHGR2M25l0qCXzA8Q9XTk6G82NJR2Z7wxdYZXxLN9x0ik0DXd8lkxv0HH18LGOz9UNdGhuCrZzlXoypMkoHaWthOc0OpXjQFNcXDyp5DtDV1llvMp3EqdPny4368fQXixQFerBsc6NmU4tlQ7blIEODCzYdXCYH9Xb6qTccpRzQ9BER/cdvBZOKuPV+1kJ9hKPsbt2mfAozcV6S4wtOtNNdITroCWLUc7g6Hbsqptirh02s6L0xkJ7e8ar+zuJKkHntKHBdP2I0Y546M7csk3gYb4M4pF0RrgnM0vGYa4sgVI49gVHBcPhcDroO1EGpzrj1f2dBH07zqQgg35MeGRvNTcvQAfhENNRPAeVozeVo6WKlZpU8p1oNauMV/d3jHQM+tHMeR23ZsCDdPYy8XA6r0k66DocDqOjttXxxvnMuNhWqu9E6W3wtgsZr+7vJKpE6YAEIoN+4GGOUI9IemRrKXRGuCcDHWLJNGMXylHtWDNjk27ySU0q+U6Uvmx74cKcV/d3ElVFOh1JqNAWbiirD7dmmOv8QMHEs0+jUyfoUDhMOXY49s3YLBxKR+Y7UXp1rBToeHN/J1FUVFRV5SogAcipHjix87WH7YR4ULfTwcZqotJh4wrbChznuGo5+oHKCYbUhg1qvhNlr0qemfPq/g7SKZICqlpQP6p62NZDe8tIp4HTYZYMfUUPnnKQL2Q4+RwO0lF8h72dfWbOq/s7Cf7Gu6t+nOajq4edR5EO+jLYskKH9hVIh8GBtjopzlVwHLfrRoMjwGBNKvlOFJ8VkgI6gUhfSYi+gBTpi1Quzf0dQcfOyK4gzX5QP+ukenBwofMcO4a2LOlcka4DcOiGLAc5cxyXEZ6vlKAj8p3oUVaEjj8VtvrwpbV4dwH75MHF39/Jio6mnzU6np8L68HTlkoHTllwuQDHOXdkaCt5IlebioKpVVa/Yk02go7YlTezInTuTltWLAUf3hVPhay+kqW5v5Ogn0LigqjK5kCa/WB7wd7D1h7qPNhajA5uOwCnCUwHj563b9w6pSrHpptik2wUOAc136Fv/z24MRSwKgYta3gAGiqUjJREwkuT7yyWDqrHnU4Dkw41nc2bybRSVkDZVU4ndqgG2AAdme9E38Pq6CAzi9DxETrwat90fHjws6XJdxLblTIicgJi9ox8cC3EtYc6D5lae/YcOSLo4LJD+4rCocNqPuGYVQNwSKn5TpS9TNuhdJZllUQs624qtCT5TmJ7mRmPGPJO++HDS6jnBC6FbOVx0KluYpa8GT3n1EmEQ1ecoEE4TjCECtENpyPynSh/cYu6sq9vxgqQHhvvIv8szftZiTKVjquCBCJFP6y9sLmAD5lb6MvQWozOSENrK/RVKSrnllSONGOb4birBuus4jsFUX7tErZBOtFLSqyCkkhfb88S5Tv8k8XKjIzEoihHmB0PG+wH6FTX6JBtp5VKhyoHRzlVjj6oNN2YqIhSZ1Y/vXPZ2DjnWb7D2ZTRFiszSMhFP8J82ORC6yG9dWwfpYOm3NoO05wcIGCUn6J2LJrKYTeuYM7y6lTynX5+up/zLN8ps5exzdQlSBMQlc8rVD0t2FuEzo+/Q+lcudreThbBVauwrWhX6WyMC/E8dNR8p58/2kl7lu+UOcto1LqAhP1wcybqITsz9hbxZUHncns19hUcPAEOG1WMjUs/qXDO2qpT2Xf6+XOvOc/yHfywRxOi7fMh4h0m2utlaK4DMLiIeDidkavEdUqhr0hbUcchfxemGxfRuGhGakfmO/38Xk/as3yH0dnCfrhDsilIx0PVQ6wH6DTv2UPpNBA6sAgeRc8xwdFlMw8VqBpSnUq+088vZqQ9y3e22KpsIUBFRXqLUfch+oET+4EdO4jz7KN06ognE0t+A6YVdBXtqVpFN+oWbMZSI4r+slPJd/r5qTXtWb6zxYHHJCI3QBzP16G7oLladuxV6IDroHLQcuiKw+HkSzrztFKNXrrvSDpe5TtbXCuLHhN8wJ5fIXjOH9hIeuvYviN/unbx0sjl9qYzZ46SaXUSVxylpSQYF9GgVOxsanbu7FTynX7enmmv3s9KfF+rhTDpiCSfwkK0HzhUtGx7u/kY0KlraG1qW/UGaSvoKkU23Gtc7VfjoVVNp5Lv9DNPz4bOc+Y7WdDRZWTDUyXtB73nxMYde7/SjHSutLeVHn0k4Eg2FM0GFyrz0dnZqe7K/NiR9ur9LBudBVnZIUlEML/WrIG9p+XtTXu+uHZx5Gp16SrSVo15iEaCMTWTOw8DHe47vD3TXt3fSRySlRUdxbE5H7QgEBCxZ6Ke1zfuRToNl5vOPAI4PzXBcfNdG416W3Uq+U4/x5z26v6Omc6hbLSkMwIBISCinpZt+widy9UETkceQyO4CCZnnUDq6+nPevj3znoHG6Aj853+g4KOR/d3VDrGmh+SJIQtdpriObCx+Ytrh9vbiHJANyAb7Wzg2kP1C1anku/0cwGmF31/JxT2d9FJXhD2K/nOuXPnDh16DkQqJEmIGFDhLqKeTYRO06Mb7+URNvlUNEobOWC4Y1lpK813OGbcBv3s+2dZXf6cv3+WPzLTR6/Hh3tnIo9lvpMVHXdWCiDWYOWAZy+h03rjdt56lE3+5OQG1WOyVooLHT6z+BcC7UxFZnr9+B8q+pLwPCuXfCfZ56tM9cCvIxVWuNsvfOdcLjUvKkaJECr/9Lf/ufbBjdu1xRtQM+mbN9Pkb+JwkpW5l5bvcMqETk93pZXEj4oLpEKQoeaS74Sm4T2JCfia3QGfb/quOGedW1w5YSGiT3/9YC4v/+BZFMrT8afk5yKQaHSUfId/SULn81l4zgep+0yvZT2e9eWS7/hTcfzeZD4rPNBDv58E66xfeFKJX839q5NV/ZPxmvrZ+yufdi5BPVN9h5KefBYNWDP4PAtaAj5sMNYdyiXfqYT3JOCzHElX9cD7SzzfGfhonhpwq48WqoHpO7+8/tcnUB8vezK+etns/bVPP36Oum+rZ2q+wwVFtFMx5rMCAwXsic0oPhXNOt/pGiM8Zu/C+0vTMV9XKs7zne73vaju3/3lzj+vv7h86+oVK5Yt2zp4//7g07WOes7OkvkOamct0ok99Fl3Z+H3pwinicHc8p3RQX98tgDeX5qK+EfHQtx33v9ZtvWm+Mnqe6K+S+qtt/bv3//Oj179wbe/9bU/fPjNf/z+qzf//uUXvrT8pa1bV39yJ/0JocRKI1S/dv4y02H5Dv/DZKIXjMf8vY/h+2f5pwP+sVhu+U7XaDLZ4/P3+a3Q58mZsMh3sqPzpqEkGMHmnVcBzh9/8uHf/kzofOPm9RdfWL78JcJn62oiohUrJCGKSf7IgY7iO8sEHeIYyeTjLvj+Wdb/aTufkDazNQ6nKSb+jaBci6uIfyoWkQpCQYMFQXoh2RTcuJF2qcKFggsp6kJJVm4ctwqiIIUZJDUq1EizEIKoY6e9cegiWFpS7mKgpQx0Pe855z3nvOd83xdtc7/TzjADM8I88/x+7/nefqn54+Pz/9N+Z/0aBi5AqDESzPj41BRD8zC2OPL61z9nqoDOUPTlb3WhkOKDhGodeP516zqD9DH2O/Lr+LbfWSfJuSmXR4oLO8yZX4DN2NjD57HY5CTAme6rOjrqeNwbBHtaQ9XVBJBEZGkkUd2Ejt7v1N6czs/td9Zv7opB5pEAw/PEtGHePI+ddE8AnOTcUtXWUcfdoWD9y986QwxPF8HT7E4H4BBEt8rQUXdlBF3r235n/VoeBhNlzDMJhgVqjKF5vnjSPTKx/euf89ObK42MzuNoEOzpbG0KoT8ckalQ7S0XTre8C8nonWZNx5/9jk1H/ygHZ9ywBthA4YA4k2DO9vJM38WqoNMbrI8wPIKOhUcAuuVNyG5uDsvY78gv5Nt+Z/3fnufRI6cy4+M6TsSbGGMzMvEEYgVwlh5UJYDO6N3eaLCFhatV8sGEDVgpc0+aS+6wleVz1oCi49N+B+igJv/xZPNMHemMgKMyFYstLoI4T5g5yem5TUlnKBqtb2kBPJ0QLs3HBFSrCV0HCeQx9jv4dQZ+9+vzWetlhaHS2GSeIhzuTXf3yMhtgHN/HtS5EHTuQbSiwfqWCHYP4Kk28RgZq70RJKN3uhQdnz6fte7BhAij2SAZbBveN89BG4AzOfKEmbOwPAPqrFYJdyBavcFgS4TbI/lYgJoVIYNReTpyZnXh+d2v93eupzNOAjU1RepGhgraeJJ3zvZ9yBVXpzHO3IFoseZpiSh7UJ8aqo82qJnSYX3t0tbGfqeG0vHj/Z318tK4gMFAMTTPeagAzcSTJzDK7y9AruYuVh80SjoQrWh9vcADfBBQjdU/nga5SGTsd2rw+Pb+jjedcXI86MQ0HWbO/WVBp6qxMWHSaXjF7bHpkHwNeNGRP8SpNXqnukI6176/k3VXho4nUja8bbQ4izxVzByAc2dhOQmts7QCwVLusF4OKjyKjwsgUyBHUdNkqf1ONR7f3t/Jeo1tQkfNKFnF6M2irBwOB0pnHlpnc9Wiw8dWA8ej9TH4OGeY5yxrNvY7IQEn5Nv7O1kLizG6lTW2NxwNjHFgA8PqNocDpTMNuQJ1JJ17dyFabKiz5mF46hz61HT9iEBwjP0O/1JwfHt/J+shDaXz1M6UpDPJY4VwoHSm51gnazqjnA7DE1H2CDzKHicfh0AUUrPRO0inybf3d7KCyjOHNrJrtDbam5i85EwwONscTjLJ1FlagctOVWNC0oGZLuSh9oRCLnwGBqg/A14BM/Y7TXgonbWd/j3xGZL2nb2ddxsV7Xey1JlfyLGaWGnDy5ixkXD4tFpYYKUzB62zytQhdIaYPPzSQ+xxBwSIusoY1CzdUfudVnE6CZ1U7mP4e47/isTeXqBdfUPmn9vvZJ1pMspGwjHFwcrRsYJczfdxOixYicRsPG7Q4c3TUCcmF8Vj0BkoJ5DAc0rvyp14yH5n7cVaOA1/wN/v9QeGX/RUtN/JmtZMqUPRGN6cnAhxOBuMFZjDc7V58QDpzHYIOo+HsHmIPaqbqT3OgLlZJOjI3hFsvr3MaHcOXgyH2zmTcHrneOdDqqL9jhudp/qoEW54g+YAHG4ONDLkitG5YHQakY4YWryX2VT3DJcdL5uRoY+x36nDAzPr3Qt+9oEO5IntezYGc+n9T/mK9jtZK04yTzJQRqRiWDjYOLfltEoqdcTEsuhgtjgdN3u0P650DEandL/TgHQK2h2ZLFDrbD8czh1XtN+x6EwZ1pjeLLLTrVJlmDMzw1tHTCygExd0dLTEpYfYI/F4A+ryoKP3Ow14Cnq/A60cgFZOnben3r4LpD59rmi/kyVg4IfZxPR+Y4aKw9mWcGZmQJ0+VIfRacyUSoUSp3MX6Qh5ZGSAog0AABM+SURBVDUTezzwONzhfzJ7JyIO0NH7HD7RA+1vDwL5zB7/JpkV7Hey7j2snxjU5Y+HCtnY5kyz1tm8WBHBAjpXmUymBM8SSh5dzDRcVryuJ9RszKwWxFPwa7+Tld7QK/HYQ0pHpsoyh8FhdJLzjE7f3BxTh7uTSDQWZjsutzq4O5KOKmZtj9LHkKcMnWZJR/ROiziRgl/7nSxtG0Mb9EbAwTEOaKQ5IlbsAYLD6VtaYupgKTN33ljucHkMPM72cQFkITql+516PAW/9jvZp9b8RjS0cGIkVbY5y/B4xUpHtA7WTqKxeHRUOpJ0KJ6IhafJo33ogKf2GL0TrJDO9fsdt7ahZIxQTaA4CGeBDXMOB3IFDxGKDoz0DnYf5HSIPAJPBCaxCpddztVl6Qyc0v1OEE/Bt/2OW6bMvjH7WMWK0VkWldwnWodPLBzobKILOjJaUf5/Wg4uN3uc/nQ5LoinZL+zE9V0fNrvUHHG3MRBNLKOlTmQK3YN5JfkOXZNXpXzPBE36TjkYXTc7JH6uNyeJZ5Tst/ZieIp+LbfUXXjXjgqVZNiua465466JDM6SwadxNHWbLx0SenYxWzZYwwvj/rhgGjv7PTiKfi23xlzXnBiWpzubjXHsY61OeymM4+tA53MH0AFneLVVTFehJklbsuajsDTwou5jg52u3yqHXcfTUftd36Gzg/udzxmONfmxEiVBUcMc6EOtM7FCnYyo5OIl4oFRgdreQgftrzsMdrHxmMAOiX7ncwQnoJf7+9kPQrHCpXTHHy84pW8tLSJlx2kszU7W7qSdMxoybFldU+r3c01VrhqNB15V848xlPw6/2drOWNEkfc/zgcPavUtLqvS4c/fvLWUXRKxVnAc6TpPLajVd6ekLN9aog78vfBoHQqe3+n7f3gOf9uG4H9vT32iQm536FVTMv4pLvbM1biGsgfIfpk6wAcVcrF4lac33fEc6igcyM8julVYxE6JfudzF08hQrf30ntDK7t8Fe4w4Pvz88P9HOWA40e4+TZwS5kbo686ixtqsuOGOhbpUyuuCXoCDy9vUa2xONjmXC51TPS0fudzKiAM1qo8P2d/Fl7eP+M98/gmrHfcfPGnFXe5lA6YA4+oMN1Jx6/LGUyl5rOEB1b9ZSOZU9TqFy8amroficziqdQ4fs751dtgfThMCM1uNOf+6r3O05vNBpVx2bnLFA4onVWVLAEHbgNwk8vOvWkmC17ypePpCPuO5l74owW6fs7qbUN/K/eaF9r3yi33/mc4yf9/VMqnD5c45/PahOflcCnUHuKL+o2xjrGC7J88FR0ptEcPrBUJys6/NdsbDp0qmPzlLEn5EyXMbOQzr0iec5K7x22ib9u+/Dhw6e1cvudtR5+2vb/agvkD1Pynzz7qHqHeBNbdKtjXCGTzlF0sJI3ORxNJ5G5gnNWcqMTJXQ87Wly6FNt0RG90yGOoIPn/PwQv5HW5+NA+KDtJvudtbN04OubwEb7RqA/FRh+caCes8yH8RN1AcTCMUe5MGeB5GqJlY5UR7pTKG1tbR1pOhIPbR4ve8zRrp+8UCC635F0OigdKBD8Rlpvv35+lw/caL/zfud7rieQhkjljj+y36xQ7ndiMffKGXGJFc2VpnNhBIvRSRxBsuKXXnTI3GpooNfCcunCAjJ6Z5afo1Kuh39XMDjtEC2kM3z2Jn1wlr/RfieQ7oF/M5VPhdvyB/kNvd9x3HBIHUtvyCWQj6ukamTeOvyuQ4LFaucyzn9Rgl14dLaiUYonEnHao0Z7kyud6mq630E68Vlw5zzDTw+l8zkcyH2obL+jhji541BzCJw7DnPENJc3QUqntNXR0XGNPDJbDnvoU7sVL7rfycTxFOl+J81bGWbX2/fkGxv95H7HKmOXQa7gkGugfsDC1rkBHcQTlFNd0FHd7MBTho7Y72QSio7e46R6DtdSgbbjdOB7rj3/V09l+x1Zxicu3iCd18ScZDKJ6hA6GCz2yxGSzmyHRUfLEzXwqOox8XjxMXongYe28kF/rj8fHt7Lh1Mfj48PApXtd2gZG8NKmXPni2FOkl4EFZ0qyx2+VxZ0Rr3ptNDqqXv1ra7T6GZaP0iI7ncyjXiKfu13di02kyPGJQfYwE/FZnk56SidFaOTG7nthjuKzpBJh+KR7wtYeEIhFzp6v/MDdH5uv+NFR5qz/fo6OquCzgM50CUdpztybNl0It50HMPLuCtX4Sn6td/ZpY1DzJHPndm/kQ0ZVy50qmx3LrdQnlFHLTuaR9vTKfm0etlj9A6h48/ns3apN4474N+7f+zqRlbzypuOqB2gA09ZBh060w17IkYz//flq7q6b/97pdbNNiFjv/NA0fHp81m7RqZUqkSsvpx92d794298uuLmzFsXQTKw9DOopHNPR4tnC7c8QUXHMbfqXn4DOmff5ORq/ae86wltIzvjj4p0Dq53YQ81e1oxhF0UQqlOCyrMYcFQ6F4Weuml+Nrmuoc9pL0sO/fg6xSGLAiBjBiPLAlJrXUQ6LBSqpHkLIKEOA41OgTbBEPAt8578/58782biaSxaEOerMSWR88zP33f7/u+33xvRuVmSd/5Mhr7zze1PisVnevqsFweVpnlEHS+1aEDbecPsu3c47aTYDwCniiub7XrJ+2kvPCXkr6zT8fzTa3P8hMC+XWZhKtq9/KSkQ6M5TrbEY6l2I5A53f34wmznDKH8LRa7S017/lERofyzr+j8fj5ptZn+YJwIOPsDX0czXfK3RtRmIskmZOODp2vVdvZldEBxZYUt6jOfNILqWdr0Zpp80IpZj2mo7qp/h1fpuM9Vln5w2oO8/ExD1dR8Qn9SkYnilg6z9pNtB3KPDApXEwWIUZP6jgzlKjnE4gO4Z3gYTS+r26qf8eHhMMop3qZCy4r/uVObkeyHFZBcHQeKaaTgI6I6TjjUUp12Xq2t2Zv2m96h+327M2hRM3RWAB9J/hNNB5WN9W/I6NDSefSD9HxK9XLHclyVNaRClCd7dzToQN8ixcUstbTas1mT05OJpM2pOYIIcg7wQMKT3VT/Tu+JALS6iHXva7610GQ45ZDKfnBA8A6Ap14uqOxHQ3zJKDzU3tr1locTmZ3pcBO0FkAfSf4lo7qpvp3fCk93sMJ4PA6dxOUy7nLHehXrDIH6LAq4kvVdpZBR0PMFJ8oLWy9PrirCD4YnwXQd4K/0VHdVP+OLywn6njzj6tBrtyNyvIdyXI468glFsgFV0FHpIS/4sTMS4rZyeuTBS0qpNC1APpOQBSDcFQ31b/jM8OJTGfvOsgF/vAmqO4AywGULAKWKEAlcKh+EeOdb2DUYgmz4lvAuxb1Ns56DtvCuwg+C8g7f6cj2FT/js8DOSWdvdxludq9DnbA6RmphBCsI0osCZx029H5lpL1YHy2ZzjraffqCvksgL4T/JYOgI51FA52j59CZZBR36FhnBMy1nNuqrAuj1kOF3Y0ESsFHQzPNyBqfSaVW7GSAoNz0pq1fhLG82lkO0zfCXao+wN0Bkeue1Rz6VqtTiGjvqOiUy1Xg6C8DDr7+yBi3QG28x1H5x5FZzcRHdW3tgE8B616e1ZvtSE5L0CuHOQoPIHQd2zTMKZjmxz+6dtKIaO+AwM5Bucmd3ypYAOTZD3ryLbDeYfbTgwdNaoLqQcqqU8O260nbRC6Pv1U4p1ol2+qXYl33PqcoFA4ogu1Mug7lI1zsk5KwJEsh5cQvIgQomAq70SF6C5HBySEclTXWU+PWg7HZwH0nWCPWn0g1meF4MyLxHSsmiOW9q2r7+z9WVgOx4ZFKxbMFb/CxbkcsVTPAjELCmCK7UToqL4FuecNE+IFOkLfCVi0hTELg0P6BQr1frFzdJVN34F+Vb7M7eSWRefRvlJjaXhH1KHAdmDKkxrWI7lna3YA8FkAfSf4SkaHXDnwvG+jft4ema5tm5WmnU3fgeDQk3og0QHBXLAOlL14npzAO5SYue3E8+VYVJfi1t3wcXigohPxjh/JC3/5IhD6zgD71ziP12cZ5tGw1sym74hQjk/q5TjnSGkgqM1l6QKyso53WNj6PO5bn8XrCYmYxXmKNoAHxiyfnb8NNqbvcMs5rh4nWo7QvDTCTprtJGc8MV5O8q3Qejg8HB0UoRONL/yN6TvMcspay+HnIISsQ4WdRzBi3fk4yXYgK8ejVjxufSTFLW4/3HqgvuOz3hp/Y/oOt5xyLFylobO/v6/zq6VsB8KjMo8mrGPz4dYj8Q7r6vM3pu9oOEdgI4UrmXVoeQ6zwa81MYvlO5/vQl4m4Ki+JaGjUA+HB+o7Puu19jem7+ijFbecd6ETYXNHsh0NKytRS+VlDTPL1sOdC+o7/h8FOhvSdyTLAehwy+ElBOm5+F4qse7cidoLYC4YRyeqJXaT0FGK0Y+UuL4tORfUd3y2OsjfmL4jcQ4rIEArCkx1ogpLKUA/VjlZl+8ovHxfV2zp4zq3nihySbxDV/v+1c+s7zjnNv1xMB3ZQt+J3CoXC+Y/AD1Qgw4QBaVMOdmzduO8rJbqjHp+rfet0Lm2oL7js5X0ftb+nYteJR+h1Rh7pZrL9R3Vclii80MsSSYB6zEosaSIpfcsrg4qUes+5+VfyOgA79rmOvO2oGao7/j0IhV/8rP27wwKlTx51Z2cGXZlwOssAE7McpLQefRIsh2NZ2F0voNBS5fxyLwcK9Y11tM+PIS5MrtuUDdz/w5Gh2Q4GJlXc74+K7g+Pg6/8CiT8TN+KOPlzy/xFxwPX/6Inw/DB/6Sx9Mf//mfp+G/T2Pj2dNnz8g/unEQPcSYHczkcXACeYddsKy7Ju+cHR1RoZWhQ1ZLjKdM3zkqvmdjJPQdfjXA7pr9O4MRGRbC6NA7SAwM49WFPq9GvDqLydEIbiLllkgbC2KbyRYulzfJIUU4QWxiq8uu69vN3L9DbAdf0qh3YeQrnuKf8WJWOiSp9UOkDQn9MmlzGIbILxDSzoVS6yIxB0fn992s/TveeadhIW/oocK4UeyzndMqH2v4sFDW1p2AQ5Wkx8SG1WXXW+9m7d8pXF1dmchu2MhwRk1XKU7f4axr/TJ1o/iLaOWprS672UNX1Fm4hbvv4O/dZvidl0nfUcswnXdyimAfQsIMOi/V8QUgHDZrkjnCzWMzKujQhcY9zyrW8fms/Lhpnb+ws+g7KZYulSS8DkEGRCrp0JZwJOm5tPfCp0DnHwIdZBt2iZztcwcuvWfU2vqOsXIKDhwWrTxJLERm4SpzMqbjlQdeLhz1+I+jiZ1F3xEKCOIfqYIGQuAdxjJCCnyH/IKRMEXsLUn/w3e6Vp4N15i/IKOJz4ae1umZCLNXyKDvILOUZ+sFp3NTuLQm7UCF6Vm03N8K2a5kJekodKao3H1rJRAPfdiNaRPfBwyfaOn3B4mpFXGkqUO/c87PHTUNy5tk2K6N2PJgw6o13Qz6TqP2LzP67WBSGI1NjZNzdxyR4pUAWZvPr/JJOgqZySJrgSbenFyPNcYy7Hu3X3RqU7KqKpxz7qXxdKHWaUb7Y04aTbxWGIRtMblXRKhZMV3PRk6tgEbO+vqO53XMCKqjInLHb9OI4tUoLF5JtedN42mtIG4y0wU5nT1F9utGGnM4Q89oDrH52kX7HUzkOEN6BYZSHaHaadKU42KpN3fNYTPfq0wmlUGG/h2nQ5zAsF+9JVfcTc4uzA4uXsl9Rr1Jv1ayE3Jre3KByEz0SpqnaRlLc2gZTschzSTFsBpEYsS3tzA6+Pt6P0Sol5CeoLzjWHihvu06eNgr9+80a2Q0CTrRMb0+M1CxhuJFzSDadkQOYkJuFZn3yJpLpV+B7mn+xVl0Y8GwoItuM5lCO40hvnIAppsw/KLTnisRGJiYsAixnfCVcclA07GLNArFbazPchpkOPj2mCbZgBwtXocdSwbMaFvP6oQ2io88MrsISYQk7sc/2uN5dFNKI4+9qlcyYhmkcMRCxUSMQsMPrWOn1HsMHWTU+sg47aF4OLzt9VnMdvCtaO1J2t3u0PgtssPiNXznhWcgYhPCCcB2fKaQG1B+mFo9m8OB0XyBece7iG5jmVZWMd6Z91DIadlrw3f17zhXnTPHwM5g9q5KNTutzBmMG/j+tuOpUao1zicOSI+kz8vsnYUz4bu3euNRv+im1krzWqPewL1agxdno/EZStnYGlWm+D6wJWT3zi961poF3wr9O85oNPLCci00IKvRtNP1HaeBK+GCY9iDUcNK1nfITHYzjwyTzJmq7wxG4RE7hdCKQ+9FafqOGe7rgPx9lG828gkS0u2uz3qf9Z3Y1re+Put91ne0f/9W12e9z/rOqvvxYek7xoo1/oel76z29g9N30kKmrfXv/M+6zvxD+22+3c0/JGg7yz5MJZ4Zb15sm27Vv9OktfG9Z1l/D9htkR9RyEwlMrT8v6gBH3nVvt3kCwaLMdjRoq+Y6hF+/+EiW5pfZZ6SOs83xE5l3tqPqos+7Bi/07C+ixJQUk7aW3Et9TqO6lnxFcinvjf1JnY7es7hpxM6TI8tQxDYEsE+UPVd/QclqDvgApnWXtAmj3blL6zglHG2Wlpvvr/HP8FhDF+su3i6TYAAAAASUVORK5CYII=" width="285" height="240" srcset="https://upload.cppreference.com/mwiki/images/thumb/9/91/math-atan2.png/428px-math-atan2.png 1.5x, https://upload.cppreference.com/mwiki/images/thumb/9/91/math-atan2.png/570px-math-atan2.png 2x"></a></div> <div class="t-plot-bottom">X argument</div> </div> <p>If a domain error occurs, an implementation-defined value is returned.</p> +<p>If a range error occurs due to underflow, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>Domain error may occur if <code>x</code> and <code>y</code> are both zero.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559):</p> +<ul> +<li> If <code>x</code> and <code>y</code> are both zero, domain error <i>does not</i> occur; </li> +<li> If <code>x</code> and <code>y</code> are both zero, range error does not occur either; </li> +<li> If <code>y</code> is zero, pole error does not occur; </li> +<li> If <code>y</code> is <code>±0</code> and <code>x</code> is negative or <code>-0</code>, <code>±π</code> is returned; </li> +<li> If <code>y</code> is <code>±0</code> and <code>x</code> is positive or <code>+0</code>, <code>±0</code> is returned; </li> +<li> If <code>y</code> is <code>±∞</code> and <code>x</code> is finite, <code>±π/2</code> is returned; </li> +<li> If <code>y</code> is <code>±∞</code> and <code>x</code> is <code>-∞</code>, <code>±3π/4</code> is returned; </li> +<li> If <code>y</code> is <code>±∞</code> and <code>x</code> is <code>+∞</code>, <code>±π/4</code> is returned; </li> +<li> If <code>x</code> is <code>±0</code> and <code>y</code> is negative, <code>-π/2</code> is returned; </li> +<li> If <code>x</code> is <code>±0</code> and <code>y</code> is positive, <code>+π/2</code> is returned; </li> +<li> If <code>x</code> is <code>-∞</code> and <code>y</code> is finite and positive, <code>+π</code> is returned; </li> +<li> If <code>x</code> is <code>-∞</code> and <code>y</code> is finite and negative, <code>-π</code> is returned; </li> +<li> If <code>x</code> is <code>+∞</code> and <code>y</code> is finite and positive, <code>+0</code> is returned; </li> +<li> If <code>x</code> is <code>+∞</code> and <code>y</code> is finite and negative, <code>-0</code> is returned; </li> +<li> If either <code>x</code> is NaN or <code>y</code> is NaN, NaN is returned. </li> +</ul> <h3 id="Notes"> Notes</h3> <p><code>atan2(y, x)</code> is equivalent to <code><a href="http://en.cppreference.com/w/c/numeric/complex/carg"><span class="kw756">carg</span></a><span class="br0">(</span>x <span class="sy2">+</span> I<span class="sy2">*</span>y<span class="br0">)</span></code>.</p> +<p><a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/atan2.html">POSIX specifies</a> that in case of underflow, <code>y / x</code> is the value returned, and if that is not supported, an implementation-defined value no greater than <code><a href="../../types/limits" title="c/types/limits">DBL_MIN</a></code>, <code><a href="../../types/limits" title="c/types/limits">FLT_MIN</a></code>, and <code><a href="../../types/limits" title="c/types/limits">LDBL_MIN</a></code> is returned.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <math.h> +#include <stdio.h> + +int main(void) +{ + // normal usage: the signs of the two arguments determine the quadrant + // atan2(1,1) = +pi/4, Quad I + printf("(+1,+1) cartesian is (%f,%f) polar\n", hypot( 1, 1), atan2( 1, 1)); + // atan2(1, -1) = +3pi/4, Quad II + printf("(+1,-1) cartesian is (%f,%f) polar\n", hypot( 1,-1), atan2( 1,-1)); + // atan2(-1,-1) = -3pi/4, Quad III + printf("(-1,-1) cartesian is (%f,%f) polar\n", hypot(-1,-1), atan2(-1,-1)); + // atan2(-1,-1) = -pi/4, Quad IV + printf("(-1,+1) cartesian is (%f,%f) polar\n", hypot(-1, 1), atan2(-1, 1)); + + // special values + printf("atan2(0, 0) = %f atan2(0, -0)=%f\n", atan2(0,0), atan2(0,-0.0)); + printf("atan2(7, 0) = %f atan2(7, -0)=%f\n", atan2(7,0), atan2(7,-0.0)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">(+1,+1) cartesian is (1.414214,0.785398) polar +(+1,-1) cartesian is (1.414214,2.356194) polar +(-1,-1) cartesian is (1.414214,-2.356194) polar +(-1,+1) cartesian is (1.414214,-0.785398) polar +atan2(0, 0) = 0.000000 atan2(0, -0)=3.141593 +atan2(7, 0) = 1.570796 atan2(7, -0)=1.570796</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.12.4.4 The atan2 functions (p: TBD) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: TBD) </li> +<li> F.10.1.4 The atan2 functions (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.4.4 The atan2 functions (p: 174) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.1.4 The atan2 functions (p: 378) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.4.4 The atan2 functions (p: 239) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.1.4 The atan2 functions (p: 519) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.4.4 The atan2 functions (p: 219) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.1.4 The atan2 functions (p: 456) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.2.4 The atan2 function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="asin" title="c/numeric/math/asin"> <span class="t-lines"><span>asin</span><span>asinf</span><span>asinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc sine (\({\small\arcsin{x} }\)arcsin(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="acos" title="c/numeric/math/acos"> <span class="t-lines"><span>acos</span><span>acosf</span><span>acosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc cosine (\({\small\arccos{x} }\)arccos(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atan" title="c/numeric/math/atan"> <span class="t-lines"><span>atan</span><span>atanf</span><span>atanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc tangent (\({\small\arctan{x} }\)arctan(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../complex/carg" title="c/numeric/complex/carg"> <span class="t-lines"><span>carg</span><span>cargf</span><span>cargl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the phase angle of a complex number <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/atan2" title="cpp/numeric/math/atan2">C++ documentation</a></span> for <code>atan2</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/atan2" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/atan2</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fatanh.html b/devdocs/c/numeric%2Fmath%2Fatanh.html new file mode 100644 index 00000000..68ec0eb7 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fatanh.html @@ -0,0 +1,84 @@ + <h1 id="firstHeading" class="firstHeading">atanh, atanhf, atanhl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float atanhf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double atanh( double arg );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double atanhl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define atanh( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the inverse hyperbolic tangent of <code>arg</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If the argument has type <code>long double</code>, <code>atanhl</code> is called. Otherwise, if the argument has integer type or the type <code>double</code>, <code>atanh</code> is called. Otherwise, <code>atanhf</code> is called. If the argument is complex, then the macro invokes the corresponding complex function (<code><a href="http://en.cppreference.com/w/c/numeric/complex/catanh"><span class="kw805">catanhf</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/catanh"><span class="kw804">catanh</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/catanh"><span class="kw806">catanhl</span></a></code>).</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value representing the area of a hyperbolic sector </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the inverse hyperbolic tangent of <code>arg</code> (tanh<sup class="t-su">-1</sup>(arg), or artanh(arg)), is returned.</p> +<p>If a domain error occurs, an implementation-defined value is returned (NaN where supported).</p> +<p>If a pole error occurs, <code><a href="huge_val" title="c/numeric/math/HUGE VAL">±HUGE_VAL</a></code>, <code>±HUGE_VALF</code>, or <code>±HUGE_VALL</code> is returned (with the correct sign).</p> +<p>If a range error occurs due to underflow, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the argument is not on the interval [-1, +1], a range error occurs.</p> +<p>If the argument is ±1, a pole error occurs.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> if the argument is ±0, it is returned unmodified </li> +<li> if the argument is ±1, ±∞ is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_DIVBYZERO</a></code> is raised. </li> +<li> if |arg|>1, NaN is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised. </li> +<li> if the argument is NaN, NaN is returned. </li> +</ul> <h3 id="Notes"> Notes</h3> <p>Although the C standard names this function "arc hyperbolic tangent", the inverse functions of the hyperbolic functions are the area functions. Their argument is the area of a hyperbolic sector, not an arc. The correct name is "inverse hyperbolic tangent" (used by POSIX) or "area hyperbolic tangent".</p> +<p><a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/atanh.html">POSIX specifies</a> that in case of underflow, <code>arg</code> is returned unmodified, and if that is not supported, an implementation-defined value no greater than <code><a href="../../types/limits" title="c/types/limits">DBL_MIN</a></code>, <code><a href="../../types/limits" title="c/types/limits">FLT_MIN</a></code>, and <code><a href="../../types/limits" title="c/types/limits">LDBL_MIN</a></code> is returned.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> +#include <errno.h> +#include <fenv.h> +// #pragma STDC FENV_ACCESS ON + +int main(void) +{ + printf("atanh(0) = %f\natanh(-0) = %f\n", atanh(0), atanh(-0.0)); + printf("atanh(0.9) = %f\n", atanh(0.9)); + //error handling + errno = 0; feclearexcept(FE_ALL_EXCEPT); + printf("atanh(-1) = %f\n", atanh(-1)); + if (errno == ERANGE) + perror(" errno == ERANGE"); + if (fetestexcept(FE_DIVBYZERO)) + puts(" FE_DIVBYZERO raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">atanh(0) = 0.000000 +atanh(-0) = -0.000000 +atanh(0.9) = 1.472219 +atanh(-1) = -inf + errno == ERANGE: Numerical result out of range + FE_DIVBYZERO raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.5.3 The atanh functions (p: TBD) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: TBD) </li> +<li> F.10.2.3 The atanh functions (p: TBD) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.5.3 The atanh functions (p: 241) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.2.3 The atanh functions (p: 520) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.5.3 The atanh functions (p: 221-222) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.2.3 The atanh functions (p: 457) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="asinh" title="c/numeric/math/asinh"> <span class="t-lines"><span>asinh</span><span>asinhf</span><span>asinhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes inverse hyperbolic sine (\({\small\operatorname{arsinh}{x} }\)arsinh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="acosh" title="c/numeric/math/acosh"> <span class="t-lines"><span>acosh</span><span>acoshf</span><span>acoshl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes inverse hyperbolic cosine (\({\small\operatorname{arcosh}{x} }\)arcosh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="tanh" title="c/numeric/math/tanh"> <span class="t-lines"><span>tanh</span><span>tanhf</span><span>tanhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes hyperbolic tangent (\({\small\tanh{x} }\)tanh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../complex/catanh" title="c/numeric/complex/catanh"> <span class="t-lines"><span>catanh</span><span>catanhf</span><span>catanhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex arc hyperbolic tangent <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/atanh" title="cpp/numeric/math/atanh">C++ documentation</a></span> for <code>atanh</code> </td> +</tr> </table> <h3 id="External_links"> External links</h3> <table> <tr> <td> +<a rel="nofollow" class="external text" href="https://mathworld.wolfram.com/InverseHyperbolicTangent.html">Weisstein, Eric W. "Inverse Hyperbolic Tangent."</a> From MathWorld — A Wolfram Web Resource. </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/atanh" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/atanh</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fcbrt.html b/devdocs/c/numeric%2Fmath%2Fcbrt.html new file mode 100644 index 00000000..bb548272 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fcbrt.html @@ -0,0 +1,71 @@ + <h1 id="firstHeading" class="firstHeading">cbrt, cbrtf, cbrtl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float cbrtf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double cbrt( double arg );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double cbrtl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define cbrt( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the cube root of <code>arg</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>arg</code> has type <code>long double</code>, <code>cbrtl</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>cbrt</code> is called. Otherwise, <code>cbrtf</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the cube root of <code>arg</code> (\(\small{\sqrt[3]{arg} }\)<span class="t-mrad"><span>3</span><span>√</span><span>arg</span></span>), is returned.</p> +<p>If a range error occurs due to underflow, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> if the argument is ±0 or ±∞, it is returned, unchanged </li> +<li> if the argument is NaN, NaN is returned. </li> +</ul> <h3 id="Notes"> Notes</h3> <code>cbrt(arg)</code> is not equivalent to <code><a href="http://en.cppreference.com/w/c/numeric/math/pow"><span class="kw667">pow</span></a><span class="br0">(</span>arg, <span class="nu16">1.0</span><span class="sy2">/</span><span class="nu0">3</span><span class="br0">)</span></code> because the rational number \(\small{\frac1{3} }\)<span><span>1</span><span>/</span><span>3</span></span> is typically not equal to <code>1.0/3</code> and <code>std::pow</code> cannot raise a negative base to a fractional exponent. Moreover, <code>cbrt(arg)</code> usually gives more accurate results than <code><a href="http://en.cppreference.com/w/c/numeric/math/pow"><span class="kw667">pow</span></a><span class="br0">(</span>arg, <span class="nu16">1.0</span><span class="sy2">/</span><span class="nu0">3</span><span class="br0">)</span></code> (see example). <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <float.h> +#include <math.h> + +int main(void) +{ + printf("Normal use:\n" + "cbrt(729) = %f\n", cbrt(729)); + printf("cbrt(-0.125) = %f\n", cbrt(-0.125)); + printf("Special values:\n" + "cbrt(-0) = %f\n", cbrt(-0.0)); + printf("cbrt(+inf) = %f\n", cbrt(INFINITY)); + printf("Accuracy:\n" + "cbrt(343) = %.*f\n", DBL_DECIMAL_DIG, cbrt(343)); + printf("pow(343,1.0/3) = %.*f\n", DBL_DECIMAL_DIG, pow(343, 1.0/3)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Normal use: +cbrt(729) = 9.000000 +cbrt(-0.125) = -0.500000 +Special values: +cbrt(-0) = -0.000000 +cbrt(+inf) = inf +Accuracy: +cbrt(343) = 7.00000000000000000 +pow(343,1.0/3) = 6.99999999999999911</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.7.1 The cbrt functions (p: 180-181) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.4.1 The cbrt functions (p: 381-) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.7.1 The cbrt functions (p: 247) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.4.1 The cbrt functions (p: 524) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.7.1 The cbrt functions (p: 228) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.4.1 The cbrt functions (p: 460) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="pow" title="c/numeric/math/pow"> <span class="t-lines"><span>pow</span><span>powf</span><span>powl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes a number raised to the given power (\(\small{x^y}\)x<sup>y</sup>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="sqrt" title="c/numeric/math/sqrt"> <span class="t-lines"><span>sqrt</span><span>sqrtf</span><span>sqrtl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes square root (\(\small{\sqrt{x} }\)<span class="t-mrad"><span>√</span><span>x</span></span>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="hypot" title="c/numeric/math/hypot"> <span class="t-lines"><span>hypot</span><span>hypotf</span><span>hypotl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes square root of the sum of the squares of two given numbers (\(\scriptsize{\sqrt{x^2+y^2} }\)<span class="t-mrad"><span>√</span><span>x<sup class="t-su">2</sup>+y<sup class="t-su">2</sup></span></span>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/cbrt" title="cpp/numeric/math/cbrt">C++ documentation</a></span> for <code>cbrt</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/cbrt" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/cbrt</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fceil.html b/devdocs/c/numeric%2Fmath%2Fceil.html new file mode 100644 index 00000000..76c99e95 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fceil.html @@ -0,0 +1,74 @@ + <h1 id="firstHeading" class="firstHeading">ceil, ceilf, ceill</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float ceilf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double ceil( double arg );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double ceill( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define ceil( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the smallest integer value not less than <code>arg</code>. </div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>arg</code> has type <code>long double</code>, <code>ceill</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>ceil</code> is called. Otherwise, <code>ceilf</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the smallest integer value not less than <code>arg</code>, that is ⌈arg⌉, is returned.</p> +<div class="t-plot"> <div class="t-plot-left">Return value</div> <div class="t-plot-image-left"><img alt="math-ceil.svg" src="data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9Im5vIj8+CjwhRE9DVFlQRSBzdmcgUFVCTElDICItLy9XM0MvL0RURCBTVkcgMS4xLy9FTiIgImh0dHA6Ly93d3cudzMub3JnL0dyYXBoaWNzL1NWRy8xLjEvRFREL3N2ZzExLmR0ZCI+CjwhLS0gQ3JlYXRlZCB3aXRoIG1hdHBsb3RsaWIgKGh0dHA6Ly9tYXRwbG90bGliLnNvdXJjZWZvcmdlLm5ldC8pIC0tPgo8c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIGhlaWdodD0iMjAwcHgiIHZlcnNpb249IjEuMSIgdmlld0JveD0iMCAwIDIwMCAyMDAiIHdpZHRoPSIyMDBweCI+CiA8ZGVmcz4KICA8c3R5bGUgdHlwZT0idGV4dC9jc3MiPgoqe3N0cm9rZS1saW5lY2FwOnNxdWFyZTtzdHJva2UtbGluZWpvaW46cm91bmQ7fQogIDwvc3R5bGU+CiA8L2RlZnM+CiA8ZyBpZD0iZmlndXJlXzEiPgogIDxnIGlkPSJwYXRjaF8xIj4KICAgPHBhdGggZD0iIE0wIDIwMCBMMjAwIDIwMCBMMjAwIDAgTDAgMCB6ICIgc3R5bGU9ImZpbGw6I2ZmZmZmZjsiLz4KICA8L2c+CiAgPGcgaWQ9ImF4ZXNfMSI+CiAgIDxnIGlkPSJwYXRjaF8yIj4KICAgIDxwYXRoIGQ9IiBNMjUgMTc3LjUgTDE4MCAxNzcuNSBMMTgwIDIyLjUgTDI1IDIyLjUgeiAiIHN0eWxlPSJmaWxsOiNmZmZmZmY7Ii8+CiAgIDwvZz4KICAgPGcgaWQ9Im1hdHBsb3RsaWIuYXhpc18xIj4KICAgIDxnIGlkPSJ4dGlja18xIj4KICAgICA8ZyBpZD0ibGluZTJkXzEiPgogICAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTM2LjA3MTQgMTc3LjUgTDM2LjA3MTQgMjIuNSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDtzdHJva2UtZGFzaGFycmF5OjEuMDAwMDAwLDMuMDAwMDAwO3N0cm9rZS1kYXNob2Zmc2V0OjAuMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMiI+CiAgICAgIDxkZWZzPgogICAgICAgPHBhdGggZD0iIE0wIDAgTDAgLTQiIGlkPSJtMDAxMmRkNGVlZiIgc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICAgPC9kZWZzPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjM2LjA3MTQyODU3MTQiIHhsaW5rOmhyZWY9IiNtMDAxMmRkNGVlZiIgeT0iMTc3LjUiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzMiPgogICAgICA8ZGVmcz4KICAgICAgIDxwYXRoIGQ9IiBNMCAwIEwwIDQiIGlkPSJtNDc2MzQ0OTY5YyIgc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICAgPC9kZWZzPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjM2LjA3MTQyODU3MTQiIHhsaW5rOmhyZWY9IiNtNDc2MzQ0OTY5YyIgeT0iMjIuNSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzEiPgogICAgICA8IS0tIOKIkjMgLS0+CiAgICAgIDxkZWZzPgogICAgICAgPHBhdGggZD0iIE00MC41NzgxIDM5LjMxMjUgUTQ3LjY1NjIgMzcuNzk2OSA1MS42MjUgMzMgUTU1LjYwOTQgMjguMjE4OCA1NS42MDk0IDIxLjE4NzUgUTU1LjYwOTQgMTAuNDA2MiA0OC4xODc1IDQuNDg0MzggUTQwLjc2NTYgLTEuNDIxODggMjcuMDkzOCAtMS40MjE4OCBRMjIuNTE1NiAtMS40MjE4OCAxNy42NTYyIC0wLjUxNTYyNSBRMTIuNzk2OSAwLjM5MDYyNSA3LjYyNSAyLjIwMzEyIEw3LjYyNSAxMS43MTg4IFExMS43MTg4IDkuMzI4MTIgMTYuNTkzOCA4LjEwOTM4IFEyMS40ODQ0IDYuODkwNjIgMjYuODEyNSA2Ljg5MDYyIFEzNi4wNzgxIDYuODkwNjIgNDAuOTM3NSAxMC41NDY5IFE0NS43OTY5IDE0LjIwMzEgNDUuNzk2OSAyMS4xODc1IFE0NS43OTY5IDI3LjY0MDYgNDEuMjgxMiAzMS4yNjU2IFEzNi43NjU2IDM0LjkwNjIgMjguNzE4OCAzNC45MDYyIEwyMC4yMTg4IDM0LjkwNjIgTDIwLjIxODggNDMuMDE1NiBMMjkuMTA5NCA0My4wMTU2IFEzNi4zNzUgNDMuMDE1NiA0MC4yMzQ0IDQ1LjkyMTkgUTQ0LjA5MzggNDguODI4MSA0NC4wOTM4IDU0LjI5NjkgUTQ0LjA5MzggNTkuOTA2MiA0MC4xMDk0IDYyLjkwNjIgUTM2LjE0MDYgNjUuOTIxOSAyOC43MTg4IDY1LjkyMTkgUTI0LjY1NjIgNjUuOTIxOSAyMC4wMTU2IDY1LjAzMTIgUTE1LjM3NSA2NC4xNTYyIDkuODEyNSA2Mi4zMTI1IEw5LjgxMjUgNzEuMDkzOCBRMTUuNDM3NSA3Mi42NTYyIDIwLjM0MzggNzMuNDM3NSBRMjUuMjUgNzQuMjE4OCAyOS41OTM4IDc0LjIxODggUTQwLjgyODEgNzQuMjE4OCA0Ny4zNTk0IDY5LjEwOTQgUTUzLjkwNjIgNjQuMDE1NiA1My45MDYyIDU1LjMyODEgUTUzLjkwNjIgNDkuMjY1NiA1MC40Mzc1IDQ1LjA5MzggUTQ2Ljk2ODggNDAuOTIxOSA0MC41NzgxIDM5LjMxMjUiIGlkPSJEZWphVnVTYW5zLTMzIi8+CiAgICAgICA8cGF0aCBkPSIgTTEwLjU5MzggMzUuNSBMNzMuMTg3NSAzNS41IEw3My4xODc1IDI3LjIwMzEgTDEwLjU5MzggMjcuMjAzMSB6ICIgaWQ9IkRlamFWdVNhbnMtMjIxMiIvPgogICAgICA8L2RlZnM+CiAgICAgIDxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDMwLjI3NDg2NjA3MTQgMTkxLjY3OTY4NzUpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0yMjEyIi8+CiAgICAgICA8dXNlIHg9IjgzLjc4OTA2MjUiIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTMzIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICA8L2c+CiAgICA8ZyBpZD0ieHRpY2tfMiI+CiAgICAgPGcgaWQ9ImxpbmUyZF80Ij4KICAgICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE01OC4yMTQzIDE3Ny41IEw1OC4yMTQzIDIyLjUiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWRhc2hhcnJheToxLjAwMDAwMCwzLjAwMDAwMDtzdHJva2UtZGFzaG9mZnNldDowLjA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzUiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjU4LjIxNDI4NTcxNDMiIHhsaW5rOmhyZWY9IiNtMDAxMmRkNGVlZiIgeT0iMTc3LjUiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzYiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjU4LjIxNDI4NTcxNDMiIHhsaW5rOmhyZWY9IiNtNDc2MzQ0OTY5YyIgeT0iMjIuNSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzIiPgogICAgICA8IS0tIOKIkjIgLS0+CiAgICAgIDxkZWZzPgogICAgICAgPHBhdGggZD0iIE0xOS4xODc1IDguMjk2ODggTDUzLjYwOTQgOC4yOTY4OCBMNTMuNjA5NCAwIEw3LjMyODEyIDAgTDcuMzI4MTIgOC4yOTY4OCBRMTIuOTM3NSAxNC4xMDk0IDIyLjYyNSAyMy44OTA2IFEzMi4zMjgxIDMzLjY4NzUgMzQuODEyNSAzNi41MzEyIFEzOS41NDY5IDQxLjg0MzggNDEuNDIxOSA0NS41MzEyIFE0My4zMTI1IDQ5LjIxODggNDMuMzEyNSA1Mi43ODEyIFE0My4zMTI1IDU4LjU5MzggMzkuMjM0NCA2Mi4yNSBRMzUuMTU2MiA2NS45MjE5IDI4LjYwOTQgNjUuOTIxOSBRMjMuOTY4OCA2NS45MjE5IDE4LjgxMjUgNjQuMzEyNSBRMTMuNjcxOSA2Mi43MDMxIDcuODEyNSA1OS40MjE5IEw3LjgxMjUgNjkuMzkwNiBRMTMuNzY1NiA3MS43ODEyIDE4LjkzNzUgNzMgUTI0LjEyNSA3NC4yMTg4IDI4LjQyMTkgNzQuMjE4OCBRMzkuNzUgNzQuMjE4OCA0Ni40ODQ0IDY4LjU0NjkgUTUzLjIxODggNjIuODkwNiA1My4yMTg4IDUzLjQyMTkgUTUzLjIxODggNDguOTIxOSA1MS41MzEyIDQ0Ljg5MDYgUTQ5Ljg1OTQgNDAuODc1IDQ1LjQwNjIgMzUuNDA2MiBRNDQuMTg3NSAzMy45ODQ0IDM3LjY0MDYgMjcuMjE4OCBRMzEuMTA5NCAyMC40NTMxIDE5LjE4NzUgOC4yOTY4OCIgaWQ9IkRlamFWdVNhbnMtMzIiLz4KICAgICAgPC9kZWZzPgogICAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSg1Mi41MDc3MjMyMTQzIDE5MS42Nzk2ODc1KXNjYWxlKDAuMDkgLTAuMDkpIj4KICAgICAgIDx1c2UgeGxpbms6aHJlZj0iI0RlamFWdVNhbnMtMjIxMiIvPgogICAgICAgPHVzZSB4PSI4My43ODkwNjI1IiB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMiIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICAgPGcgaWQ9Inh0aWNrXzMiPgogICAgIDxnIGlkPSJsaW5lMmRfNyI+CiAgICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNODAuMzU3MSAxNzcuNSBMODAuMzU3MSAyMi41IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF84Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSI4MC4zNTcxNDI4NTcxIiB4bGluazpocmVmPSIjbTAwMTJkZDRlZWYiIHk9IjE3Ny41Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF85Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSI4MC4zNTcxNDI4NTcxIiB4bGluazpocmVmPSIjbTQ3NjM0NDk2OWMiIHk9IjIyLjUiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0idGV4dF8zIj4KICAgICAgPCEtLSDiiJIxIC0tPgogICAgICA8ZGVmcz4KICAgICAgIDxwYXRoIGQ9IiBNMTIuNDA2MiA4LjI5Njg4IEwyOC41MTU2IDguMjk2ODggTDI4LjUxNTYgNjMuOTIxOSBMMTAuOTg0NCA2MC40MDYyIEwxMC45ODQ0IDY5LjM5MDYgTDI4LjQyMTkgNzIuOTA2MiBMMzguMjgxMiA3Mi45MDYyIEwzOC4yODEyIDguMjk2ODggTDU0LjM5MDYgOC4yOTY4OCBMNTQuMzkwNiAwIEwxMi40MDYyIDAgeiAiIGlkPSJEZWphVnVTYW5zLTMxIi8+CiAgICAgIDwvZGVmcz4KICAgICAgPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNzQuNjE1NDI0MTA3MSAxOTEuNTYxNTYyNSlzY2FsZSgwLjA5IC0wLjA5KSI+CiAgICAgICA8dXNlIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTIyMTIiLz4KICAgICAgIDx1c2UgeD0iODMuNzg5MDYyNSIgeGxpbms6aHJlZj0iI0RlamFWdVNhbnMtMzEiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgIDwvZz4KICAgIDxnIGlkPSJ4dGlja180Ij4KICAgICA8ZyBpZD0ibGluZTJkXzEwIj4KICAgICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0xMDIuNSAxNzcuNSBMMTAyLjUgMjIuNSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDtzdHJva2UtZGFzaGFycmF5OjEuMDAwMDAwLDMuMDAwMDAwO3N0cm9rZS1kYXNob2Zmc2V0OjAuMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMTEiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjEwMi41IiB4bGluazpocmVmPSIjbTAwMTJkZDRlZWYiIHk9IjE3Ny41Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8xMiI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTAyLjUiIHhsaW5rOmhyZWY9IiNtNDc2MzQ0OTY5YyIgeT0iMjIuNSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzQiPgogICAgICA8IS0tIDAgLS0+CiAgICAgIDxkZWZzPgogICAgICAgPHBhdGggZD0iIE0zMS43ODEyIDY2LjQwNjIgUTI0LjE3MTkgNjYuNDA2MiAyMC4zMjgxIDU4LjkwNjIgUTE2LjUgNTEuNDIxOSAxNi41IDM2LjM3NSBRMTYuNSAyMS4zOTA2IDIwLjMyODEgMTMuODkwNiBRMjQuMTcxOSA2LjM5MDYyIDMxLjc4MTIgNi4zOTA2MiBRMzkuNDUzMSA2LjM5MDYyIDQzLjI4MTIgMTMuODkwNiBRNDcuMTI1IDIxLjM5MDYgNDcuMTI1IDM2LjM3NSBRNDcuMTI1IDUxLjQyMTkgNDMuMjgxMiA1OC45MDYyIFEzOS40NTMxIDY2LjQwNjIgMzEuNzgxMiA2Ni40MDYyIE0zMS43ODEyIDc0LjIxODggUTQ0LjA0NjkgNzQuMjE4OCA1MC41MTU2IDY0LjUxNTYgUTU2Ljk4NDQgNTQuODI4MSA1Ni45ODQ0IDM2LjM3NSBRNTYuOTg0NCAxNy45Njg4IDUwLjUxNTYgOC4yNjU2MiBRNDQuMDQ2OSAtMS40MjE4OCAzMS43ODEyIC0xLjQyMTg4IFExOS41MzEyIC0xLjQyMTg4IDEzLjA2MjUgOC4yNjU2MiBRNi41OTM3NSAxNy45Njg4IDYuNTkzNzUgMzYuMzc1IFE2LjU5Mzc1IDU0LjgyODEgMTMuMDYyNSA2NC41MTU2IFExOS41MzEyIDc0LjIxODggMzEuNzgxMiA3NC4yMTg4IiBpZD0iRGVqYVZ1U2Fucy0zMCIvPgogICAgICA8L2RlZnM+CiAgICAgIDxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDEwMC4yMzI0MjE4NzUgMTkxLjY3OTY4NzUpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMCIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICAgPGcgaWQ9Inh0aWNrXzUiPgogICAgIDxnIGlkPSJsaW5lMmRfMTMiPgogICAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTEyNC42NDMgMTc3LjUgTDEyNC42NDMgMjIuNSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDtzdHJva2UtZGFzaGFycmF5OjEuMDAwMDAwLDMuMDAwMDAwO3N0cm9rZS1kYXNob2Zmc2V0OjAuMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMTQiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjEyNC42NDI4NTcxNDMiIHhsaW5rOmhyZWY9IiNtMDAxMmRkNGVlZiIgeT0iMTc3LjUiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzE1Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxMjQuNjQyODU3MTQzIiB4bGluazpocmVmPSIjbTQ3NjM0NDk2OWMiIHk9IjIyLjUiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0idGV4dF81Ij4KICAgICAgPCEtLSAxIC0tPgogICAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMjIuNjg5NTc1ODkzIDE5MS41NjE1NjI1KXNjYWxlKDAuMDkgLTAuMDkpIj4KICAgICAgIDx1c2UgeGxpbms6aHJlZj0iI0RlamFWdVNhbnMtMzEiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgIDwvZz4KICAgIDxnIGlkPSJ4dGlja182Ij4KICAgICA8ZyBpZD0ibGluZTJkXzE2Ij4KICAgICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0xNDYuNzg2IDE3Ny41IEwxNDYuNzg2IDIyLjUiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWRhc2hhcnJheToxLjAwMDAwMCwzLjAwMDAwMDtzdHJva2UtZGFzaG9mZnNldDowLjA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzE3Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxNDYuNzg1NzE0Mjg2IiB4bGluazpocmVmPSIjbTAwMTJkZDRlZWYiIHk9IjE3Ny41Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8xOCI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTQ2Ljc4NTcxNDI4NiIgeGxpbms6aHJlZj0iI200NzYzNDQ5NjljIiB5PSIyMi41Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9InRleHRfNiI+CiAgICAgIDwhLS0gMiAtLT4KICAgICAgPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMTQ0LjcwMzA1ODAzNiAxOTEuNjc5Njg3NSlzY2FsZSgwLjA5IC0wLjA5KSI+CiAgICAgICA8dXNlIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTMyIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICA8L2c+CiAgICA8ZyBpZD0ieHRpY2tfNyI+CiAgICAgPGcgaWQ9ImxpbmUyZF8xOSI+CiAgICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMTY4LjkyOSAxNzcuNSBMMTY4LjkyOSAyMi41IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8yMCI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTY4LjkyODU3MTQyOSIgeGxpbms6aHJlZj0iI20wMDEyZGQ0ZWVmIiB5PSIxNzcuNSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMjEiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjE2OC45Mjg1NzE0MjkiIHhsaW5rOmhyZWY9IiNtNDc2MzQ0OTY5YyIgeT0iMjIuNSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzciPgogICAgICA8IS0tIDMgLS0+CiAgICAgIDxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDE2Ni43NjkyNzQ1NTQgMTkxLjY3OTY4NzUpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMyIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICA8L2c+CiAgIDxnIGlkPSJtYXRwbG90bGliLmF4aXNfMiI+CiAgICA8ZyBpZD0ieXRpY2tfMSI+CiAgICAgPGcgaWQ9ImxpbmUyZF8yMiI+CiAgICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMjUgMTY2LjQyOSBMMTgwIDE2Ni40MjkiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWRhc2hhcnJheToxLjAwMDAwMCwzLjAwMDAwMDtzdHJva2UtZGFzaG9mZnNldDowLjA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzIzIj4KICAgICAgPGRlZnM+CiAgICAgICA8cGF0aCBkPSIgTTAgMCBMNCAwIiBpZD0ibWU4YTg1ZjdiZjYiIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICAgIDwvZGVmcz4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIyNS4wIiB4bGluazpocmVmPSIjbWU4YTg1ZjdiZjYiIHk9IjE2Ni40Mjg1NzE0MjkiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzI0Ij4KICAgICAgPGRlZnM+CiAgICAgICA8cGF0aCBkPSIgTTAgMCBMLTQgMCIgaWQ9Im0xYTMyMDA1ZGVhIiBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgICA8L2RlZnM+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTgwLjAiIHhsaW5rOmhyZWY9IiNtMWEzMjAwNWRlYSIgeT0iMTY2LjQyODU3MTQyOSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzgiPgogICAgICA8IS0tIOKIkjMgLS0+CiAgICAgIDxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDUuOTA2ODc1IDE2OS43MDQ0MzA4MDQpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0yMjEyIi8+CiAgICAgICA8dXNlIHg9IjgzLjc4OTA2MjUiIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTMzIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICA8L2c+CiAgICA8ZyBpZD0ieXRpY2tfMiI+CiAgICAgPGcgaWQ9ImxpbmUyZF8yNSI+CiAgICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMjUgMTQ0LjI4NiBMMTgwIDE0NC4yODYiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWRhc2hhcnJheToxLjAwMDAwMCwzLjAwMDAwMDtzdHJva2UtZGFzaG9mZnNldDowLjA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzI2Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIyNS4wIiB4bGluazpocmVmPSIjbWU4YTg1ZjdiZjYiIHk9IjE0NC4yODU3MTQyODYiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzI3Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxODAuMCIgeGxpbms6aHJlZj0iI20xYTMyMDA1ZGVhIiB5PSIxNDQuMjg1NzE0Mjg2Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9InRleHRfOSI+CiAgICAgIDwhLS0g4oiSMiAtLT4KICAgICAgPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNi4wODY4NzUgMTQ3LjYyNTU1ODAzNilzY2FsZSgwLjA5IC0wLjA5KSI+CiAgICAgICA8dXNlIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTIyMTIiLz4KICAgICAgIDx1c2UgeD0iODMuNzg5MDYyNSIgeGxpbms6aHJlZj0iI0RlamFWdVNhbnMtMzIiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgIDwvZz4KICAgIDxnIGlkPSJ5dGlja18zIj4KICAgICA8ZyBpZD0ibGluZTJkXzI4Ij4KICAgICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0yNSAxMjIuMTQzIEwxODAgMTIyLjE0MyIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDtzdHJva2UtZGFzaGFycmF5OjEuMDAwMDAwLDMuMDAwMDAwO3N0cm9rZS1kYXNob2Zmc2V0OjAuMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMjkiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjI1LjAiIHhsaW5rOmhyZWY9IiNtZThhODVmN2JmNiIgeT0iMTIyLjE0Mjg1NzE0MyIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMzAiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjE4MC4wIiB4bGluazpocmVmPSIjbTFhMzIwMDVkZWEiIHk9IjEyMi4xNDI4NTcxNDMiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0idGV4dF8xMCI+CiAgICAgIDwhLS0g4oiSMSAtLT4KICAgICAgPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNi4wMTY1NjI1IDEyNS40MjM2MzgzOTMpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0yMjEyIi8+CiAgICAgICA8dXNlIHg9IjgzLjc4OTA2MjUiIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTMxIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICA8L2c+CiAgICA8ZyBpZD0ieXRpY2tfNCI+CiAgICAgPGcgaWQ9ImxpbmUyZF8zMSI+CiAgICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMjUgMTAwIEwxODAgMTAwIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8zMiI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMjUuMCIgeGxpbms6aHJlZj0iI21lOGE4NWY3YmY2IiB5PSIxMDAuMCIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMzMiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjE4MC4wIiB4bGluazpocmVmPSIjbTFhMzIwMDVkZWEiIHk9IjEwMC4wIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9InRleHRfMTEiPgogICAgICA8IS0tIDAgLS0+CiAgICAgIDxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDEyLjk2NDg0Mzc1IDEwMy4yNzU4NTkzNzUpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMCIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICAgPGcgaWQ9Inl0aWNrXzUiPgogICAgIDxnIGlkPSJsaW5lMmRfMzQiPgogICAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTI1IDc3Ljg1NzEgTDE4MCA3Ny44NTcxIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8zNSI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMjUuMCIgeGxpbms6aHJlZj0iI21lOGE4NWY3YmY2IiB5PSI3Ny44NTcxNDI4NTcxIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8zNiI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTgwLjAiIHhsaW5rOmhyZWY9IiNtMWEzMjAwNWRlYSIgeT0iNzcuODU3MTQyODU3MSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzEyIj4KICAgICAgPCEtLSAxIC0tPgogICAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMy41OTM0Mzc1IDgxLjEzNzkyNDEwNzEpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICAgPGcgaWQ9Inl0aWNrXzYiPgogICAgIDxnIGlkPSJsaW5lMmRfMzciPgogICAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTI1IDU1LjcxNDMgTDE4MCA1NS43MTQzIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8zOCI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMjUuMCIgeGxpbms6aHJlZj0iI21lOGE4NWY3YmY2IiB5PSI1NS43MTQyODU3MTQzIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8zOSI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTgwLjAiIHhsaW5rOmhyZWY9IiNtMWEzMjAwNWRlYSIgeT0iNTUuNzE0Mjg1NzE0MyIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzEzIj4KICAgICAgPCEtLSAyIC0tPgogICAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMy4zMzQ2ODc1IDU5LjA1NDEyOTQ2NDMpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMiIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICAgPGcgaWQ9Inl0aWNrXzciPgogICAgIDxnIGlkPSJsaW5lMmRfNDAiPgogICAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTI1IDMzLjU3MTQgTDE4MCAzMy41NzE0IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF80MSI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMjUuMCIgeGxpbms6aHJlZj0iI21lOGE4NWY3YmY2IiB5PSIzMy41NzE0Mjg1NzE0Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF80MiI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTgwLjAiIHhsaW5rOmhyZWY9IiNtMWEzMjAwNWRlYSIgeT0iMzMuNTcxNDI4NTcxNCIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzE0Ij4KICAgICAgPCEtLSAzIC0tPgogICAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMy4xODE0MDYyNSAzNi44NDcyODc5NDY0KXNjYWxlKDAuMDkgLTAuMDkpIj4KICAgICAgIDx1c2UgeGxpbms6aHJlZj0iI0RlamFWdVNhbnMtMzMiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgIDwvZz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzQzIj4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMjQuNTU3MSAxNjYuNDI5IEwzNi4wNzE0IDE2Ni40MjkiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzQ0Ij4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMzYuMDcxNCAxNDQuMjg2IEw1OC4yMTQzIDE0NC4yODYiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzQ1Ij4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNNTguMjE0MyAxMjIuMTQzIEw4MC4zNTcxIDEyMi4xNDMiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzQ2Ij4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNODAuMzU3MSAxMDAgTDEwMi41IDEwMCIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDBmZjtzdHJva2Utd2lkdGg6MC41OyIvPgogICA8L2c+CiAgIDxnIGlkPSJsaW5lMmRfNDciPgogICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0xMDIuNSA3Ny44NTcxIEwxMjQuNjQzIDc3Ljg1NzEiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzQ4Ij4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMTI0LjY0MyA1NS43MTQzIEwxNDYuNzg2IDU1LjcxNDMiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzQ5Ij4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMTQ2Ljc4NiAzMy41NzE0IEwxNjguOTI5IDMzLjU3MTQiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzUwIj4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMzYuMDcxNCAxNjYuNDI5IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMGZmOyIvPgogICAgPGRlZnM+CiAgICAgPHBhdGggZD0iIE0wIDMuNzUgQzAuOTk0NTEyIDMuNzUgMS45NDg0MiAzLjM1NDg4IDIuNjUxNjUgMi42NTE2NSBDMy4zNTQ4OCAxLjk0ODQyIDMuNzUgMC45OTQ1MTIgMy43NSAwIEMzLjc1IC0wLjk5NDUxMiAzLjM1NDg4IC0xLjk0ODQyIDIuNjUxNjUgLTIuNjUxNjUgQzEuOTQ4NDIgLTMuMzU0ODggMC45OTQ1MTIgLTMuNzUgMCAtMy43NSBDLTAuOTk0NTEyIC0zLjc1IC0xLjk0ODQyIC0zLjM1NDg4IC0yLjY1MTY1IC0yLjY1MTY1IEMtMy4zNTQ4OCAtMS45NDg0MiAtMy43NSAtMC45OTQ1MTIgLTMuNzUgMCBDLTMuNzUgMC45OTQ1MTIgLTMuMzU0ODggMS45NDg0MiAtMi42NTE2NSAyLjY1MTY1IEMtMS45NDg0MiAzLjM1NDg4IC0wLjk5NDUxMiAzLjc1IDAgMy43NSB6ICIgaWQ9Im1lNTNiN2JiNmQyIiBzdHlsZT0ic3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgPC9kZWZzPgogICAgPGcgY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSI+CiAgICAgPHVzZSBzdHlsZT0iZmlsbDojMDAwMGZmO3N0cm9rZTojMDAwMGZmO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjM2LjA3MTQyODU3MTQiIHhsaW5rOmhyZWY9IiNtZTUzYjdiYjZkMiIgeT0iMTY2LjQyODU3MTQyOSIvPgogICAgPC9nPgogICA8L2c+CiAgIDxnIGlkPSJsaW5lMmRfNTEiPgogICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0zNi4wNzE0IDE0NC4yODYiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDgwMDA7Ii8+CiAgICA8ZGVmcz4KICAgICA8cGF0aCBkPSIgTTAgMy43NSBDMC45OTQ1MTIgMy43NSAxLjk0ODQyIDMuMzU0ODggMi42NTE2NSAyLjY1MTY1IEMzLjM1NDg4IDEuOTQ4NDIgMy43NSAwLjk5NDUxMiAzLjc1IDAgQzMuNzUgLTAuOTk0NTEyIDMuMzU0ODggLTEuOTQ4NDIgMi42NTE2NSAtMi42NTE2NSBDMS45NDg0MiAtMy4zNTQ4OCAwLjk5NDUxMiAtMy43NSAwIC0zLjc1IEMtMC45OTQ1MTIgLTMuNzUgLTEuOTQ4NDIgLTMuMzU0ODggLTIuNjUxNjUgLTIuNjUxNjUgQy0zLjM1NDg4IC0xLjk0ODQyIC0zLjc1IC0wLjk5NDUxMiAtMy43NSAwIEMtMy43NSAwLjk5NDUxMiAtMy4zNTQ4OCAxLjk0ODQyIC0yLjY1MTY1IDIuNjUxNjUgQy0xLjk0ODQyIDMuMzU0ODggLTAuOTk0NTEyIDMuNzUgMCAzLjc1IHogIiBpZD0ibWUyNzgwNjQyZTIiIHN0eWxlPSJzdHJva2U6IzAwMDBmZjtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICA8L2RlZnM+CiAgICA8ZyBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIj4KICAgICA8dXNlIHN0eWxlPSJmaWxsOiNmZmZmZmY7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMzYuMDcxNDI4NTcxNCIgeGxpbms6aHJlZj0iI21lMjc4MDY0MmUyIiB5PSIxNDQuMjg1NzE0Mjg2Ii8+CiAgICA8L2c+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF81MiI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTU4LjIxNDMgMTQ0LjI4NiIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6I2ZmMDAwMDsiLz4KICAgIDxnIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiPgogICAgIDx1c2Ugc3R5bGU9ImZpbGw6IzAwMDBmZjtzdHJva2U6IzAwMDBmZjtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSI1OC4yMTQyODU3MTQzIiB4bGluazpocmVmPSIjbWU1M2I3YmI2ZDIiIHk9IjE0NC4yODU3MTQyODYiLz4KICAgIDwvZz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzUzIj4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNNTguMjE0MyAxMjIuMTQzIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDBiZmJmOyIvPgogICAgPGcgY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSI+CiAgICAgPHVzZSBzdHlsZT0iZmlsbDojZmZmZmZmO3N0cm9rZTojMDAwMGZmO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjU4LjIxNDI4NTcxNDMiIHhsaW5rOmhyZWY9IiNtZTI3ODA2NDJlMiIgeT0iMTIyLjE0Mjg1NzE0MyIvPgogICAgPC9nPgogICA8L2c+CiAgIDxnIGlkPSJsaW5lMmRfNTQiPgogICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE04MC4zNTcxIDEyMi4xNDMiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiNiZjAwYmY7Ii8+CiAgICA8ZyBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIj4KICAgICA8dXNlIHN0eWxlPSJmaWxsOiMwMDAwZmY7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iODAuMzU3MTQyODU3MSIgeGxpbms6aHJlZj0iI21lNTNiN2JiNmQyIiB5PSIxMjIuMTQyODU3MTQzIi8+CiAgICA8L2c+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF81NSI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTgwLjM1NzEgMTAwIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojYmZiZjAwOyIvPgogICAgPGcgY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSI+CiAgICAgPHVzZSBzdHlsZT0iZmlsbDojZmZmZmZmO3N0cm9rZTojMDAwMGZmO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjgwLjM1NzE0Mjg1NzEiIHhsaW5rOmhyZWY9IiNtZTI3ODA2NDJlMiIgeT0iMTAwLjAiLz4KICAgIDwvZz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzU2Ij4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMTAyLjUgMTAwIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwOyIvPgogICAgPGcgY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSI+CiAgICAgPHVzZSBzdHlsZT0iZmlsbDojMDAwMGZmO3N0cm9rZTojMDAwMGZmO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjEwMi41IiB4bGluazpocmVmPSIjbWU1M2I3YmI2ZDIiIHk9IjEwMC4wIi8+CiAgICA8L2c+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF81NyI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTEwMi41IDc3Ljg1NzEiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwZmY7Ii8+CiAgICA8ZyBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIj4KICAgICA8dXNlIHN0eWxlPSJmaWxsOiNmZmZmZmY7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTAyLjUiIHhsaW5rOmhyZWY9IiNtZTI3ODA2NDJlMiIgeT0iNzcuODU3MTQyODU3MSIvPgogICAgPC9nPgogICA8L2c+CiAgIDxnIGlkPSJsaW5lMmRfNTgiPgogICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0xMjQuNjQzIDc3Ljg1NzEiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDgwMDA7Ii8+CiAgICA8ZyBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIj4KICAgICA8dXNlIHN0eWxlPSJmaWxsOiMwMDAwZmY7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTI0LjY0Mjg1NzE0MyIgeGxpbms6aHJlZj0iI21lNTNiN2JiNmQyIiB5PSI3Ny44NTcxNDI4NTcxIi8+CiAgICA8L2c+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF81OSI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTEyNC42NDMgNTUuNzE0MyIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6I2ZmMDAwMDsiLz4KICAgIDxnIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiPgogICAgIDx1c2Ugc3R5bGU9ImZpbGw6I2ZmZmZmZjtzdHJva2U6IzAwMDBmZjtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxMjQuNjQyODU3MTQzIiB4bGluazpocmVmPSIjbWUyNzgwNjQyZTIiIHk9IjU1LjcxNDI4NTcxNDMiLz4KICAgIDwvZz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzYwIj4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMTQ2Ljc4NiA1NS43MTQzIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDBiZmJmOyIvPgogICAgPGcgY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSI+CiAgICAgPHVzZSBzdHlsZT0iZmlsbDojMDAwMGZmO3N0cm9rZTojMDAwMGZmO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjE0Ni43ODU3MTQyODYiIHhsaW5rOmhyZWY9IiNtZTUzYjdiYjZkMiIgeT0iNTUuNzE0Mjg1NzE0MyIvPgogICAgPC9nPgogICA8L2c+CiAgIDxnIGlkPSJsaW5lMmRfNjEiPgogICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0xNDYuNzg2IDMzLjU3MTQiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiNiZjAwYmY7Ii8+CiAgICA8ZyBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIj4KICAgICA8dXNlIHN0eWxlPSJmaWxsOiNmZmZmZmY7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTQ2Ljc4NTcxNDI4NiIgeGxpbms6aHJlZj0iI21lMjc4MDY0MmUyIiB5PSIzMy41NzE0Mjg1NzE0Ii8+CiAgICA8L2c+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF82MiI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTE2OC45MjkgMzMuNTcxNCIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6I2JmYmYwMDsiLz4KICAgIDxnIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiPgogICAgIDx1c2Ugc3R5bGU9ImZpbGw6IzAwMDBmZjtzdHJva2U6IzAwMDBmZjtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxNjguOTI4NTcxNDI5IiB4bGluazpocmVmPSIjbWU1M2I3YmI2ZDIiIHk9IjMzLjU3MTQyODU3MTQiLz4KICAgIDwvZz4KICAgPC9nPgogICA8ZyBpZD0icGF0Y2hfMyI+CiAgICA8cGF0aCBkPSIgTTI1IDIyLjUgTDE4MCAyMi41IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwOyIvPgogICA8L2c+CiAgIDxnIGlkPSJwYXRjaF80Ij4KICAgIDxwYXRoIGQ9IiBNMTgwIDE3Ny41IEwxODAgMjIuNSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDsiLz4KICAgPC9nPgogICA8ZyBpZD0icGF0Y2hfNSI+CiAgICA8cGF0aCBkPSIgTTI1IDE3Ny41IEwxODAgMTc3LjUiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwMDA7Ii8+CiAgIDwvZz4KICAgPGcgaWQ9InBhdGNoXzYiPgogICAgPHBhdGggZD0iIE0yNSAxNzcuNSBMMjUgMjIuNSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDsiLz4KICAgPC9nPgogIDwvZz4KIDwvZz4KIDxkZWZzPgogIDxjbGlwUGF0aCBpZD0icDQwZmVjMTE1M2YiPgogICA8cmVjdCBoZWlnaHQ9IjE1NS4wIiB3aWR0aD0iMTU1LjAiIHg9IjI1LjAiIHk9IjIyLjUiLz4KICA8L2NsaXBQYXRoPgogPC9kZWZzPgo8L3N2Zz4K" width="200" height="200"></div> <div class="t-plot-bottom">Argument</div> </div> <h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> The current <a href="../fenv/fe_round" title="c/numeric/fenv/FE round">rounding mode</a> has no effect. </li> +<li> If <code>arg</code> is ±∞, it is returned, unmodified </li> +<li> If <code>arg</code> is ±0, it is returned, unmodified </li> +<li> If arg is NaN, NaN is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p><code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> may be (but isn't required to be) raised when rounding a non-integer finite value.</p> +<p>The largest representable floating-point values are exact integers in all standard floating-point formats, so this function never overflows on its own; however the result may overflow any integer type (including <code><a href="../../types/integer" title="c/types/integer">intmax_t</a></code>), when stored in an integer variable.</p> +<p>This function (for double argument) behaves as if (except for the freedom to not raise <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code>) implemented by</p> +<div class="c source-c"><pre data-language="c">#include <math.h> +#include <fenv.h> +#pragma STDC FENV_ACCESS ON +double ceil(double x) +{ + double result; + int save_round = fegetround(); + fesetround(FE_UPWARD); + result = rint(x); // or nearbyint + fesetround(save_round); + return result; +}</pre></div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <math.h> +#include <stdio.h> +int main(void) +{ + printf("ceil(+2.4) = %+.1f\n", ceil(2.4)); + printf("ceil(-2.4) = %+.1f\n", ceil(-2.4)); + printf("ceil(-0.0) = %+.1f\n", ceil(-0.0)); + printf("ceil(-Inf) = %+f\n", ceil(-INFINITY)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">ceil(+2.4) = +3.0 +ceil(-2.4) = -2.0 +ceil(-0.0) = -0.0 +ceil(-Inf) = -inf</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.9.1 The ceil functions (p: 251) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.6.1 The ceil functions (p: 526) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.9.1 The ceil functions (p: 231-232) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.6.1 The ceil functions (p: 462-463) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.6.1 The ceil function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="floor" title="c/numeric/math/floor"> <span class="t-lines"><span>floor</span><span>floorf</span><span>floorl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes largest integer not greater than the given value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="trunc" title="c/numeric/math/trunc"> <span class="t-lines"><span>trunc</span><span>truncf</span><span>truncl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> rounds to nearest integer not greater in magnitude than the given value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="round" title="c/numeric/math/round"> <span class="t-lines"><span>round</span><span>roundf</span><span>roundl</span><span>lround</span><span>lroundf</span><span>lroundl</span><span>llround</span><span>llroundf</span><span>llroundl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> rounds to nearest integer, rounding away from zero in halfway cases <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="nearbyint" title="c/numeric/math/nearbyint"> <span class="t-lines"><span>nearbyint</span><span>nearbyintf</span><span>nearbyintl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> rounds to an integer using current rounding mode <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="rint" title="c/numeric/math/rint"> <span class="t-lines"><span>rint</span><span>rintf</span><span>rintl</span><span>lrint</span><span>lrintf</span><span>lrintl</span><span>llrint</span><span>llrintf</span><span>llrintl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> rounds to an integer using current rounding mode with <br> exception if the result differs <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/ceil" title="cpp/numeric/math/ceil">C++ documentation</a></span> for <code>ceil</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/ceil" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/ceil</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fcopysign.html b/devdocs/c/numeric%2Fmath%2Fcopysign.html new file mode 100644 index 00000000..3e67f811 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fcopysign.html @@ -0,0 +1,51 @@ + <h1 id="firstHeading" class="firstHeading">copysign, copysignf, copysignl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float copysignf( float x, float y );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double copysign( double x, double y );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double copysignl( long double x, long double y );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define copysign(x, y)</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Composes a floating point value with the magnitude of <code>x</code> and the sign of <code>y</code>. </div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If any argument has type <code>long double</code>, <code>copysignl</code> is called. Otherwise, if any argument has integer type or has type <code>double</code>, <code>copysign</code> is called. Otherwise, <code>copysignf</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> x, y </td> <td> - </td> <td> floating point values </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the floating point value with the magnitude of <code>x</code> and the sign of <code>y</code> is returned.</p> +<p>If <code>x</code> is NaN, then NaN with the sign of <code>y</code> is returned.</p> +<p>If <code>y</code> is -0, the result is only negative if the implementation supports the signed zero consistently in arithmetic operations.</p> +<h3 id="Error_handling"> Error handling</h3> <p>This function is not subject to any errors specified in <a href="math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul><li> The returned value is exact (<code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> is never raised) and independent of the current <a href="../fenv/fe_round" title="c/numeric/fenv/FE round">rounding mode</a>. </li></ul> <h3 id="Notes"> Notes</h3> <p><code>copysign</code> is the only portable way to manipulate the sign of a NaN value (to examine the sign of a NaN, <code><a href="signbit" title="c/numeric/math/signbit">signbit</a></code> may also be used).</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> + +int main(void) +{ + printf("copysign(1.0,+2.0) = %+.1f\n", copysign(1.0,+2.0)); + printf("copysign(1.0,-2.0) = %+.1f\n", copysign(1.0,-2.0)); + printf("copysign(INFINITY,-2.0) = %f\n", copysign(INFINITY,-2.0)); + printf("copysign(NAN,-2.0) = %f\n", copysign(NAN,-2.0)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">copysign(1.0,+2.0) = +1.0 +copysign(1.0,-2.0) = -1.0 +copysign(INFINITY,-2.0) = -inf +copysign(NAN,-2.0) = -nan</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.11.1 The copysign functions (p: 255) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.8.1 The copysign functions (p: 529) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.11.1 The copysign functions (p: 236) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.8.1 The copysign functions (p: 465) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fabs" title="c/numeric/math/fabs"> <span class="t-lines"><span>fabs</span><span>fabsf</span><span>fabsl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes absolute value of a floating-point value (\(\small{|x|}\)|x|) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="signbit" title="c/numeric/math/signbit"> <span class="t-lines"><span>signbit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number is negative <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/copysign" title="cpp/numeric/math/copysign">C++ documentation</a></span> for <code>copysign</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/copysign" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/copysign</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fcos.html b/devdocs/c/numeric%2Fmath%2Fcos.html new file mode 100644 index 00000000..7dea37f1 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fcos.html @@ -0,0 +1,103 @@ + <h1 id="firstHeading" class="firstHeading">cos, cosf, cosl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float cosf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double cos( double arg );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double cosl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal32 cosd32( _Decimal32 arg );</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal64 cosd64( _Decimal64 arg );</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal128 cosd128( _Decimal128 arg );</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define cos( arg )</pre> +</td> <td> (7) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-6)</span> Computes the cosine of <code>arg</code> (measured in radians).</div> <div class="t-li1"> +<span class="t-li">7)</span> Type-generic macro: If the argument has type <code>long double</code>, <span class="t-v">(3)</span> (<code>cosl</code>) is called. Otherwise, if the argument has integer type or the type <code>double</code>, <span class="t-v">(2)</span> (<code>cos</code>) is called. Otherwise, <span class="t-v">(1)</span> (<code>cosf</code>) is called. If the argument is complex, then the macro invokes the corresponding complex function (<code><a href="../complex/ccos" title="c/numeric/complex/ccos">ccosf</a></code>, <code><a href="../complex/ccos" title="c/numeric/complex/ccos">ccos</a></code>, <code><a href="../complex/ccos" title="c/numeric/complex/ccos">ccosl</a></code>).</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>The functions <span class="t-v">(4-6)</span> are declared if and only if the implementation predefines <code>__STDC_IEC_60559_DFP__</code> (i.e. the implementation supports decimal floating-point numbers).</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating-point value representing angle in radians </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the cosine of <code>arg</code> (cos(arg)) in the range [-1 ; +1], is returned.</p> +<table class="t-rev-begin"> <tr class="t-rev t-until-c99"> +<td> <p>The result may have little or no significance if the magnitude of <code>arg</code> is large.</p> +</td> <td><span class="t-mark-rev t-until-c99">(until C99)</span></td> +</tr> </table> <p>If a domain error occurs, an implementation-defined value is returned (NaN where supported).</p> +<p>If a range error occurs due to underflow, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559):</p> +<ul> +<li> if the argument is ±0, the result is <code>1.0</code>; </li> +<li> if the argument is ±∞, NaN is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised; </li> +<li> if the argument is NaN, NaN is returned. </li> +</ul> <h3 id="Notes"> Notes</h3> <p>The case where the argument is infinite is not specified to be a domain error in C, but it is defined as a <a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/cos.html">domain error in POSIX</a>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <errno.h> +#include <fenv.h> +#include <math.h> +#include <stdio.h> + +#ifndef __GNUC__ +#pragma STDC FENV_ACCESS ON +#endif + +int main(void) +{ + const double pi = acos(-1); + + // typical usage + printf("cos(pi/3) = %f\n", cos(pi / 3)); + printf("cos(pi/2) = %f\n", cos(pi / 2)); + printf("cos(-3*pi/4) = %f\n", cos(-3 * pi / 4)); + + // special values + printf("cos(+0) = %f\n", cos(0.0)); + printf("cos(-0) = %f\n", cos(-0.0)); + + // error handling + feclearexcept(FE_ALL_EXCEPT); + printf("cos(INFINITY) = %f\n", cos(INFINITY)); + if (fetestexcept(FE_INVALID)) + puts(" FE_INVALID raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">cos(pi/3) = 0.500000 +cos(pi/2) = 0.000000 +cos(-3*pi/4) = -0.707107 +cos(+0) = 1.000000 +cos(-0) = 1.000000 +cos(INFINITY) = -nan + FE_INVALID raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.12.4.5 The cos functions (p: TBD) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: TBD) </li> +<li> F.10.1.5 The cos functions (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.4.5 The cos functions (p: 174) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.1.5 The cos functions (p: 378) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.4.5 The cos functions (p: 239) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.1.5 The cos functions (p: 519) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.4.5 The cos functions (p: 220) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.1.5 The cos functions (p: 456) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.2.5 The cos function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="sin" title="c/numeric/math/sin"> <span class="t-lines"><span>sin</span><span>sinf</span><span>sinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes sine (\({\small\sin{x} }\)sin(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="tan" title="c/numeric/math/tan"> <span class="t-lines"><span>tan</span><span>tanf</span><span>tanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes tangent (\({\small\tan{x} }\)tan(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="acos" title="c/numeric/math/acos"> <span class="t-lines"><span>acos</span><span>acosf</span><span>acosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc cosine (\({\small\arccos{x} }\)arccos(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../complex/ccos" title="c/numeric/complex/ccos"> <span class="t-lines"><span>ccos</span><span>ccosf</span><span>ccosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex cosine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/cos" title="cpp/numeric/math/cos">C++ documentation</a></span> for <code>cos</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/cos" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/cos</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fcosh.html b/devdocs/c/numeric%2Fmath%2Fcosh.html new file mode 100644 index 00000000..493b5d19 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fcosh.html @@ -0,0 +1,77 @@ + <h1 id="firstHeading" class="firstHeading">cosh, coshf, coshl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float coshf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double cosh( double arg );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double coshl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define cosh( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the hyperbolic cosine of <code>arg</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If the argument has type <code>long double</code>, <code>coshl</code> is called. Otherwise, if the argument has integer type or the type <code>double</code>, <code>cosh</code> is called. Otherwise, <code>coshf</code> is called. If the argument is complex, then the macro invokes the corresponding complex function (<code><a href="http://en.cppreference.com/w/c/numeric/complex/ccosh"><span class="kw808">ccoshf</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/ccosh"><span class="kw807">ccosh</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/ccosh"><span class="kw809">ccoshl</span></a></code>).</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value representing a hyperbolic angle </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> If no errors occur, the hyperbolic cosine of <code>arg</code> (cosh(arg), or <span><span>earg+e-arg</span><span>/</span><span>2</span></span>) is returned. <p>If a range error due to overflow occurs, <code><a href="huge_val" title="c/numeric/math/HUGE VAL">+HUGE_VAL</a></code>, <code>+HUGE_VALF</code>, or <code>+HUGE_VALL</code> is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> if the argument is ±0, 1 is returned </li> +<li> If the argument is ±∞, +∞ is returned </li> +<li> if the argument is NaN, NaN is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p>For the IEEE-compatible type <code>double</code>, if |arg| > 710.5, then <code>cosh(arg)</code> overflows.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <errno.h> +#include <fenv.h> + +// #pragma STDC FENV_ACCESS ON +int main(void) +{ + printf("cosh(1) = %f\ncosh(-1)= %f\n", cosh(1), cosh(-1)); + printf("log(sinh(1) + cosh(1))=%f\n", log(sinh(1)+cosh(1))); + // special values + printf("cosh(+0) = %f\ncosh(-0) = %f\n", cosh(0.0), cosh(-0.0)); + // error handling + errno=0; feclearexcept(FE_ALL_EXCEPT); + printf("cosh(710.5) = %f\n", cosh(710.5)); + if(errno == ERANGE) perror(" errno == ERANGE"); + if(fetestexcept(FE_OVERFLOW)) puts(" FE_OVERFLOW raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">cosh(1) = 1.543081 +cosh(-1)= 1.543081 +log(sinh(1) + cosh(1))=1.000000 +cosh(+0) = 1.000000 +cosh(-0) = 1.000000 +cosh(710.5) = inf + errno == ERANGE: Numerical result out of range + FE_OVERFLOW raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.5.4 The cosh functions (p: 176) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.2.4 The cosh functions (p: 379) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.5.4 The cosh functions (p: 241) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.2.4 The cosh functions (p: 520) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.5.4 The cosh functions (p: 222) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.2.4 The cosh functions (p: 457) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.3.1 The cosh function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="sinh" title="c/numeric/math/sinh"> <span class="t-lines"><span>sinh</span><span>sinhf</span><span>sinhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes hyperbolic sine (\({\small\sinh{x} }\)sinh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="tanh" title="c/numeric/math/tanh"> <span class="t-lines"><span>tanh</span><span>tanhf</span><span>tanhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes hyperbolic tangent (\({\small\tanh{x} }\)tanh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="acosh" title="c/numeric/math/acosh"> <span class="t-lines"><span>acosh</span><span>acoshf</span><span>acoshl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes inverse hyperbolic cosine (\({\small\operatorname{arcosh}{x} }\)arcosh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../complex/ccosh" title="c/numeric/complex/ccosh"> <span class="t-lines"><span>ccosh</span><span>ccoshf</span><span>ccoshl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex hyperbolic cosine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/cosh" title="cpp/numeric/math/cosh">C++ documentation</a></span> for <code>cosh</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/cosh" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/cosh</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fcospi.html b/devdocs/c/numeric%2Fmath%2Fcospi.html new file mode 100644 index 00000000..f260c5fb --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fcospi.html @@ -0,0 +1,77 @@ + <h1 id="firstHeading" class="firstHeading">cospi, cospif, cospil, cospid32, cospid64, cospid128</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">float cospif( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">double cospi( double arg );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">long double cospil( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal32 cospid32( _Decimal32 arg );</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal64 cospid64( _Decimal64 arg );</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal128 cospid128( _Decimal128 arg );</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">#define cospi( arg )</pre> +</td> <td> (7) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-6)</span> Computes the cosine of <code>π·arg</code> measured in radians, thus regarding <code>arg</code> as a measurement in half-revolutions.</div> <div class="t-li1"> +<span class="t-li">7)</span> Type-generic macro: calls the correct function based on the type of <code>arg</code>. If the argument has integer type, <span class="t-v">(2)</span> (<code>cospi</code>) is called.</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>The functions <span class="t-v">(4-6)</span> are declared if and only if the implementation predefines <code>__STDC_IEC_60559_DFP__</code> (i.e. the implementation supports decimal floating-point numbers).</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating-point value whose product with <code>π</code> represents an angle in radians </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the cosine of <code>π·arg</code> (cos(π×arg)) in the range [-1, +1], is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559):</p> +<ul> +<li> if the argument is ±0, the result is <code>1.0</code>; </li> +<li> if the argument is ±∞, NaN is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised; </li> +<li> if the argument is NaN, NaN is returned. </li> +</ul> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <errno.h> +#include <fenv.h> +#include <math.h> +#include <stdio.h> + +#ifndef __GNUC__ +#pragma STDC FENV_ACCESS ON +#endif + +#if __STDC_VERSION__ < 202311L +// A naive implementation of a subset of cospi family +double cospi(double arg) +{ + return cos(arg * (double)3.1415926535897932384626433); +} +#endif + +int main(void) +{ + const double pi = acos(-1); + + // typical usage + printf("cospi(1) = %f, cos(pi) = %f\n", cospi(1), cos(pi)); + printf("cospi(0.5) = %f, cos(pi/2) = %f\n", cospi(0.5), cos(pi / 2)); + printf("cospi(-0.75) = %f, cos(-3*pi/4) = %f\n", cospi(-0.75), cos(-3 * pi / 4)); + + // special values + printf("cospi(+0) = %f\n", cospi(0.0)); + printf("cospi(-0) = %f\n", cospi(-0.0)); + + // error handling + feclearexcept(FE_ALL_EXCEPT); + printf("cospi(INFINITY) = %f\n", cospi(INFINITY)); + if (fetestexcept(FE_INVALID)) + puts(" FE_INVALID raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">cospi(1) = -1.000000, cos(pi) = -1.000000 +cospi(0.5) = 0.000000, cos(pi/2) = 0.000000 +cospi(-0.75) = -0.707107, cos(-3*pi/4) = -0.707107 +cospi(+0) = 1.000000 +cospi(-0) = 1.000000 +cospi(INFINITY) = -nan + FE_INVALID raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.12.4.12 The cospi functions (p: 247) </li> +<li> 7.27 Type generic math <tgmath.h> (p: 387) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="cos" title="c/numeric/math/cos"> <span class="t-lines"><span>cos</span><span>cosf</span><span>cosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes cosine (\({\small\cos{x} }\)cos(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/cospi" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/cospi</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fdiv.html b/devdocs/c/numeric%2Fmath%2Fdiv.html new file mode 100644 index 00000000..529a3c32 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fdiv.html @@ -0,0 +1,120 @@ + <h1 id="firstHeading" class="firstHeading">div, ldiv, lldiv, imaxdiv</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">div_t div( int x, int y );</pre> +</td> <td> (1) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">ldiv_t ldiv( long x, long y );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">lldiv_t lldiv( long long x, long long y );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><inttypes.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">imaxdiv_t imaxdiv( intmax_t x, intmax_t y );</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Computes both the quotient and the remainder of the division of the numerator <code>x</code> by the denominator <code>y</code>.</p> +<table class="t-rev-begin"> <tr class="t-rev t-until-c99"> +<td> <p>Computes quotient and remainder simultaneously. The quotient is the algebraic quotient with any fractional part discarded (truncated towards zero). The remainder is such that <code>quot * y + rem == x</code>.</p> +</td> <td><span class="t-mark-rev t-until-c99">(until C99)</span></td> +</tr> <tr class="t-rev t-since-c99"> +<td> <p>Computes the quotient (the result of the expression <code>x / y</code>) and remainder (the result of the expression <code>x % y</code>) simultaneously.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> x, y </td> <td> - </td> <td> integer values </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If both the remainder and the quotient can be represented as objects of the corresponding type (<code>int</code>, <code>long</code>, <code>long long</code>, <code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw118">intmax_t</span></a></code>, respectively), returns both as an object of type <code>div_t</code>, <code>ldiv_t</code>, <code>lldiv_t</code>, <code>imaxdiv_t</code> defined as follows:</p> +<div class="t-member"> <h2 id="div_t"> div_t</h2> <div class="c source-c"><pre data-language="c">struct div_t { int quot; int rem; };</pre></div> <p>or</p> +<div class="c source-c"><pre data-language="c">struct div_t { int rem; int quot; };</pre></div> </div> <div class="t-member"> <h2 id="ldiv_t"> ldiv_t</h2> <div class="c source-c"><pre data-language="c">struct ldiv_t { long quot; long rem; };</pre></div> <p>or</p> +<div class="c source-c"><pre data-language="c">struct ldiv_t { long rem; long quot; };</pre></div> </div> <div class="t-member"> <h2 id="lldiv_t"> lldiv_t</h2> <div class="c source-c"><pre data-language="c">struct lldiv_t { long long quot; long long rem; };</pre></div> <p>or</p> +<div class="c source-c"><pre data-language="c">struct lldiv_t { long long rem; long long quot; };</pre></div> </div> <div class="t-member"> <h2 id="imaxdiv_t"> imaxdiv_t</h2> <div class="c source-c"><pre data-language="c">struct imaxdiv_t { intmax_t quot; intmax_t rem; };</pre></div> <p>or</p> +<div class="c source-c"><pre data-language="c">struct imaxdiv_t { intmax_t rem; intmax_t quot; };</pre></div> </div> <p>If either the remainder or the quotient cannot be represented, the behavior is undefined.</p> +<h3 id="Notes"> Notes</h3> <p>Until C99, the rounding direction of the quotient and the sign of the remainder in the built-in division and remainder operators was implementation-defined if either of the operands was negative, but it was well-defined in <code>div</code> and <code>ldiv</code>.</p> +<p>On many platforms, a single CPU instruction obtains both the quotient and the remainder, and this function may leverage that, although compilers are generally able to merge nearby <code>/</code> and <code>%</code> where suitable.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <assert.h> +#include <limits.h> +#include <math.h> +#include <stdio.h> +#include <stdlib.h> + +void reverse(char* first, char* last) +{ + for (--last; first < last; ++first, --last) + { + char c = *last; + *last = *first; + *first = c; + } +} + +// returns empty buffer in case of buffer overflow +char* itoa(int n, int base, char* buf, size_t buf_size) +{ + assert(2 <= base && base <= 16 && buf && buf_size); + div_t dv = {.quot = n}; + char* p = buf; + do + { + if (!--buf_size) + return (*buf = '\0'), buf; + dv = div(dv.quot, base); + *p++ = "0123456789abcdef"[abs(dv.rem)]; + } + while(dv.quot); + if (n < 0) + *p++ = '-'; + *p = '\0'; + reverse(buf, p); + return buf; +} + +int main(void) +{ + char buf[16]; + printf("%s\n", itoa(0, 2, buf, sizeof buf)); + printf("%s\n", itoa(007, 3, buf, sizeof buf)); + printf("%s\n", itoa(12346, 10, buf, sizeof buf)); + printf("%s\n", itoa(-12346, 10, buf, sizeof buf)); + printf("%s\n", itoa(-42, 2, buf, sizeof buf)); + printf("%s\n", itoa(INT_MAX, 16, buf, sizeof buf)); + printf("%s\n", itoa(INT_MIN, 16, buf, sizeof buf)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">0 +21 +12346 +-12346 +-101010 +7fffffff +-80000000</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.8.2.2 The imaxdiv function (p: TBD) </li> +<li> 7.22.6.2 The div, ldiv and lldiv functions (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.8.2.2 The imaxdiv function (p: 159) </li> +<li> 7.22.6.2 The div, ldiv and lldiv functions (p: 259) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.8.2.2 The imaxdiv function (p: 219) </li> +<li> 7.22.6.2 The div, ldiv and lldiv functions (p: 356) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.8.2.2 The imaxdiv function (p: 200) </li> +<li> 7.20.6.2 The div, ldiv and lldiv functions (p: 320) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 4.10 div_t, ldiv_t </li> +<li> 4.10.6.2 The div function </li> +<li> 4.10.6.4 The ldiv function </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fmod" title="c/numeric/math/fmod"> <span class="t-lines"><span>fmod</span><span>fmodf</span><span>fmodl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes remainder of the floating-point division operation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="remainder" title="c/numeric/math/remainder"> <span class="t-lines"><span>remainder</span><span>remainderf</span><span>remainderl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes signed remainder of the floating-point division operation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="remquo" title="c/numeric/math/remquo"> <span class="t-lines"><span>remquo</span><span>remquof</span><span>remquol</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes signed remainder as well as the three last bits of the division operation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/div" title="cpp/numeric/math/div">C++ documentation</a></span> for <code>div</code> </td> +</tr> </table> <h3 id="External_links"> External links</h3> <table> <tr style="vertical-align:top;"> <td>1. </td> <td> +<a href="https://en.wikipedia.org/wiki/Euclidean_division" class="extiw" title="enwiki:Euclidean division">Euclidean division</a> — From Wikipedia. </td> +</tr> <tr style="vertical-align:top;"> <td>2. </td> <td> +<a href="https://en.wikipedia.org/wiki/Modulo" class="extiw" title="enwiki:Modulo">Modulo (and Truncated division)</a> — From Wikipedia. </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/div" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/div</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Ferf.html b/devdocs/c/numeric%2Fmath%2Ferf.html new file mode 100644 index 00000000..a4223e04 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ferf.html @@ -0,0 +1,69 @@ + <h1 id="firstHeading" class="firstHeading">erf, erff, erfl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float erff( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double erf( double arg );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double erfl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define erf( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the <a href="https://en.wikipedia.org/wiki/Error_function" class="extiw" title="enwiki:Error function">error function</a> of <code>arg</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>arg</code> has type <code>long double</code>, <code>erfl</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>erf</code> is called. Otherwise, <code>erff</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> If no errors occur, value of the error function of <code>arg</code>, that is \(\frac{2}{\sqrt{\pi} }\int_{0}^{arg}{e^{-{t^2} }\mathsf{d}t}\)<span><span>2</span><span>/</span><span>√π</span></span>∫<sub class="t-su t-su-b">arg0</sub><i>e</i><sup>-t<sup class="t-su">2</sup></sup>d<i>t</i>, is returned. If a range error occurs due to underflow, the correct result (after rounding), that is \(\frac{2\cdot arg}{\sqrt{\pi} }\)<span><span>2*arg</span><span>/</span><span>√π</span></span>, is returned. <h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> If the argument is ±0, ±0 is returned </li> +<li> If the argument is ±∞, ±1 is returned </li> +<li> If the argument is NaN, NaN is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p>Underflow is guaranteed if <code><span class="sy3">|</span>arg<span class="sy3">|</span> <span class="sy1"><</span> <a href="http://en.cppreference.com/w/c/types/limits"><span class="kw375">DBL_MIN</span></a><span class="sy2">*</span><span class="br0">(</span><a href="http://en.cppreference.com/w/c/numeric/math/sqrt"><span class="kw665">sqrt</span></a><span class="br0">(</span>π<span class="br0">)</span><span class="sy2">/</span><span class="nu0">2</span><span class="br0">)</span></code>. \(\operatorname{erf}(\frac{x}{\sigma \sqrt{2} })\)erf(</p> +<span><span>x</span><span>/</span><span>σ√2</span></span>) is the probability that a measurement whose errors are subject to a normal distribution with standard deviation \(\sigma\)σ is less than \(x\)x away from the mean value. <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <math.h> +#include <stdio.h> + +double phi(double x1, double x2) +{ + return (erf(x2 / sqrt(2)) - erf(x1 / sqrt(2))) / 2; +} + +int main(void) +{ + puts("normal variate probabilities:"); + for (int n = -4; n < 4; ++n) + printf("[%2d:%2d]: %5.2f%%\n", n, n + 1, 100 * phi(n, n + 1)); + + puts("special values:"); + printf("erf(-0) = %f\n", erf(-0.0)); + printf("erf(Inf) = %f\n", erf(INFINITY)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">normal variate probabilities: +[-4:-3]: 0.13% +[-3:-2]: 2.14% +[-2:-1]: 13.59% +[-1: 0]: 34.13% +[ 0: 1]: 34.13% +[ 1: 2]: 13.59% +[ 2: 3]: 2.14% +[ 3: 4]: 0.13% +special values: +erf(-0) = -0.000000 +erf(Inf) = 1.000000</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.8.1 The erf functions (p: 249) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.5.1 The erf functions (p: 525) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.8.1 The erf functions (p: 230) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.5.1 The erf functions (p: 462) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="erfc" title="c/numeric/math/erfc"> <span class="t-lines"><span>erfc</span><span>erfcf</span><span>erfcl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes complementary error function <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/erf" title="cpp/numeric/math/erf">C++ documentation</a></span> for <code>erf</code> </td> +</tr> </table> <h3 id="External_links"> External links</h3> <table> <tr> <td> +<a rel="nofollow" class="external text" href="https://mathworld.wolfram.com/Erf.html">Weisstein, Eric W. "Erf."</a> From MathWorld — A Wolfram Web Resource. </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/erf" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/erf</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Ferfc.html b/devdocs/c/numeric%2Fmath%2Ferfc.html new file mode 100644 index 00000000..cbbc7e72 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ferfc.html @@ -0,0 +1,75 @@ + <h1 id="firstHeading" class="firstHeading">erfc, erfcf, erfcl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float erfcf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double erfc( double arg );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double erfcl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define erfc( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the <a href="https://en.wikipedia.org/wiki/Complementary_error_function" class="extiw" title="enwiki:Complementary error function">complementary error function</a> of <code>arg</code>, that is <code><span class="nu16">1.0</span> <span class="sy2">-</span> <a href="http://en.cppreference.com/w/c/numeric/math/erf"><span class="kw682">erf</span></a><span class="br0">(</span>arg<span class="br0">)</span></code>, but without loss of precision for large <code>arg</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>arg</code> has type <code>long double</code>, <code>erfcl</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>erfc</code> is called. Otherwise, <code>erfcf</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> If no errors occur, value of the complementary error function of <code>arg</code>, that is \(\frac{2}{\sqrt{\pi} }\int_{arg}^{\infty}{e^{-{t^2} }\mathsf{d}t}\)<span><span>2</span><span>/</span><span>√π</span></span>∫<sub class="t-su t-su-b">∞arg</sub><i>e</i><sup>-t<sup class="t-su">2</sup></sup>d<i>t</i> or \({\small 1-\operatorname{erf}(arg)}\)1-erf(arg), is returned. <p>If a range error occurs due to underflow, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> If the argument is +∞, +0 is returned. </li> +<li> If the argument is -∞, 2 is returned. </li> +<li> If the argument is NaN, NaN is returned. </li> +</ul> <h3 id="Notes"> Notes</h3> <p>For the IEEE-compatible type <code>double</code>, underflow is guaranteed if <code>arg</code> > <code>26.55</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> + +double normalCDF(double x) // Phi(-∞, x) aka N(x) +{ + return erfc(-x / sqrt(2)) / 2; +} + +int main(void) +{ + puts("normal cumulative distribution function:"); + for(double n = 0; n < 1; n += 0.1) + printf("normalCDF(%.2f) %5.2f%%\n", n, 100 * normalCDF(n)); + + printf("special values:\n" + "erfc(-Inf) = %f\n" + "erfc(Inf) = %f\n", + erfc(-INFINITY), + erfc(INFINITY)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">normal cumulative distribution function: +normalCDF(0.00) 50.00% +normalCDF(0.10) 53.98% +normalCDF(0.20) 57.93% +normalCDF(0.30) 61.79% +normalCDF(0.40) 65.54% +normalCDF(0.50) 69.15% +normalCDF(0.60) 72.57% +normalCDF(0.70) 75.80% +normalCDF(0.80) 78.81% +normalCDF(0.90) 81.59% +normalCDF(1.00) 84.13% +special values: +erfc(-Inf) = 2.000000 +erfc(Inf) = 0.000000</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.8.2 The erfc functions (p: 249-250) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.5.2 The erfc functions (p: 525) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.8.2 The erfc functions (p: 230) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.5.2 The erfc functions (p: 462) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="erf" title="c/numeric/math/erf"> <span class="t-lines"><span>erf</span><span>erff</span><span>erfl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes error function <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/erfc" title="cpp/numeric/math/erfc">C++ documentation</a></span> for <code>erfc</code> </td> +</tr> </table> <h3 id="External_links"> External links</h3> <table> <tr> <td> +<a rel="nofollow" class="external text" href="https://mathworld.wolfram.com/Erfc.html">Weisstein, Eric W. "Erfc."</a> From MathWorld — A Wolfram Web Resource. </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/erfc" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/erfc</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fexp.html b/devdocs/c/numeric%2Fmath%2Fexp.html new file mode 100644 index 00000000..0d02bb24 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fexp.html @@ -0,0 +1,90 @@ + <h1 id="firstHeading" class="firstHeading">exp, expf, expl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float expf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double exp( double arg );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double expl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define exp( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes e (<a href="https://en.wikipedia.org/wiki/E_(mathematical_constant)" class="extiw" title="enwiki:E (mathematical constant)">Euler's number</a>, <span class="nu16">2.7182818</span>...) raised to the given power <code>arg</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>arg</code> has type <code>long double</code>, <code>expl</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>exp</code> is called. Otherwise, <code>expf</code> is called. If <code>arg</code> is complex or imaginary, then the macro invokes the corresponding complex function (<code><a href="http://en.cppreference.com/w/c/numeric/complex/cexp"><span class="kw769">cexpf</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/cexp"><span class="kw768">cexp</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/cexp"><span class="kw770">cexpl</span></a></code>).</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the base-<i>e</i> exponential of <code>arg</code> (e<sup class="t-su">arg</sup>) is returned.</p> +<p>If a range error occurs due to overflow, <code><a href="huge_val" title="c/numeric/math/HUGE VAL">+HUGE_VAL</a></code>, <code>+HUGE_VALF</code>, or <code>+HUGE_VALL</code> is returned.</p> +<p>If a range error occurs due to underflow, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> If the argument is ±0, 1 is returned </li> +<li> If the argument is -∞, +0 is returned </li> +<li> If the argument is +∞, +∞ is returned </li> +<li> If the argument is NaN, NaN is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p>For IEEE-compatible type <code>double</code>, overflow is guaranteed if 709.8 < arg, and underflow is guaranteed if arg < -708.4.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <errno.h> +#include <fenv.h> +#include <float.h> +#include <math.h> +#include <stdio.h> +// #pragma STDC FENV_ACCESS ON + +int main(void) +{ + printf("exp(1) = %f\n", exp(1)); + printf("FV of $100, continuously compounded at 3%% for 1 year = %f\n", + 100*exp(0.03)); + // special values + printf("exp(-0) = %f\n", exp(-0.0)); + printf("exp(-Inf) = %f\n", exp(-INFINITY)); + //error handling + errno = 0; feclearexcept(FE_ALL_EXCEPT); + printf("exp(710) = %f\n", exp(710)); + if (errno == ERANGE) + perror(" errno == ERANGE"); + if (fetestexcept(FE_OVERFLOW)) + puts(" FE_OVERFLOW raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">exp(1) = 2.718282 +FV of $100, continuously compounded at 3% for 1 year = 103.045453 +exp(-0) = 1.000000 +exp(-Inf) = 0.000000 +exp(710) = inf + errno == ERANGE: Numerical result out of range + FE_OVERFLOW raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.12.6.1 The exp functions (p: TBD) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: TBD) </li> +<li> F.10.3.1 The exp functions (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.6.1 The exp functions (p: 175) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.3.1 The exp functions (p: 379) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.6.1 The exp functions (p: 242) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.3.1 The exp functions (p: 520) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.6.1 The exp functions (p: 223) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.3.1 The exp functions (p: 458) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.4.1 The exp function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="exp2" title="c/numeric/math/exp2"> <span class="t-lines"><span>exp2</span><span>exp2f</span><span>exp2l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes <i>2</i> raised to the given power (\({\small 2^x}\)2<sup>x</sup>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="expm1" title="c/numeric/math/expm1"> <span class="t-lines"><span>expm1</span><span>expm1f</span><span>expm1l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes <i>e</i> raised to the given power, minus one (\({\small e^x-1}\)e<sup>x</sup>-1) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="log" title="c/numeric/math/log"> <span class="t-lines"><span>log</span><span>logf</span><span>logl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes natural (base-<i>e</i>) logarithm (\({\small \ln{x} }\)ln(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../complex/cexp" title="c/numeric/complex/cexp"> <span class="t-lines"><span>cexp</span><span>cexpf</span><span>cexpl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex base-e exponential <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/exp" title="cpp/numeric/math/exp">C++ documentation</a></span> for <code>exp</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/exp" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/exp</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fexp2.html b/devdocs/c/numeric%2Fmath%2Fexp2.html new file mode 100644 index 00000000..66fa43ca --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fexp2.html @@ -0,0 +1,77 @@ + <h1 id="firstHeading" class="firstHeading">exp2, exp2f, exp2l</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float exp2f( float n );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double exp2( double n );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double exp2l( long double n );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define exp2( n )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes 2 raised to the given power <code>n</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>n</code> has type <code>long double</code>, <code>exp2l</code> is called. Otherwise, if <code>n</code> has integer type or the type <code>double</code>, <code>exp2</code> is called. Otherwise, <code>exp2f</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> n </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the base-<i>2</i> exponential of <code>n</code> (2<sup class="t-su">n</sup>) is returned.</p> +<p>If a range error due to overflow occurs, <code><a href="huge_val" title="c/numeric/math/HUGE VAL">+HUGE_VAL</a></code>, <code>+HUGE_VALF</code>, or <code>+HUGE_VALL</code> is returned.</p> +<p>If a range error occurs due to underflow, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> If the argument is ±0, 1 is returned </li> +<li> If the argument is -∞, +0 is returned </li> +<li> If the argument is +∞, +∞ is returned </li> +<li> If the argument is NaN, NaN is returned </li> +</ul> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> +#include <errno.h> +#include <fenv.h> +// #pragma STDC FENV_ACCESS ON +int main(void) +{ + printf("exp2(5) = %f\n", exp2(5)); + printf("exp2(0.5) = %f\n", exp2(0.5)); + printf("exp2(-4) = %f\n", exp2(-4)); + // special values + printf("exp2(-0.9) = %f\n", exp2(-0.9)); + printf("exp2(-Inf) = %f\n", exp2(-INFINITY)); + //error handling + errno = 0; feclearexcept(FE_ALL_EXCEPT); + printf("exp2(1024) = %f\n", exp2(1024)); + if(errno == ERANGE) perror(" errno == ERANGE"); + if(fetestexcept(FE_OVERFLOW)) puts(" FE_OVERFLOW raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">exp2(5) = 32.000000 +exp2(0.5) = 1.414214 +exp2(-4) = 0.062500 +exp2(-0.9) = 0.535887 +exp2(-Inf) = 0.000000 +exp2(1024) = Inf + errno == ERANGE: Result too large + FE_OVERFLOW raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.6.2 The exp2 functions (p: 177) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.3.2 The exp2 functions (p: 379) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.6.2 The exp2 functions (p: 242-243) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.3.2 The exp2 functions (p: 521) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.6.2 The exp2 functions (p: 223) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.3.2 The exp2 functions (p: 458) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="exp" title="c/numeric/math/exp"> <span class="t-lines"><span>exp</span><span>expf</span><span>expl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes <i>e</i> raised to the given power (\({\small e^x}\)e<sup>x</sup>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="expm1" title="c/numeric/math/expm1"> <span class="t-lines"><span>expm1</span><span>expm1f</span><span>expm1l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes <i>e</i> raised to the given power, minus one (\({\small e^x-1}\)e<sup>x</sup>-1) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="log2" title="c/numeric/math/log2"> <span class="t-lines"><span>log2</span><span>log2f</span><span>log2l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes base-2 logarithm (\({\small \log_{2}{x} }\)log<sub>2</sub>(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/exp2" title="cpp/numeric/math/exp2">C++ documentation</a></span> for <code>exp2</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/exp2" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/exp2</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fexpm1.html b/devdocs/c/numeric%2Fmath%2Fexpm1.html new file mode 100644 index 00000000..75918aa8 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fexpm1.html @@ -0,0 +1,83 @@ + <h1 id="firstHeading" class="firstHeading">expm1, expm1f, expm1l</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float expm1f( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double expm1( double arg );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double expm1l( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define expm1( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the <i>e</i> (Euler's number, <code>2.7182818</code>) raised to the given power <code>arg</code>, minus <code>1.0</code>. This function is more accurate than the expression <code><a href="http://en.cppreference.com/w/c/numeric/math/exp"><span class="kw657">exp</span></a><span class="br0">(</span>arg<span class="br0">)</span><span class="sy2">-</span><span class="nu16">1.0</span></code> if <code>arg</code> is close to zero.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>arg</code> has type <code>long double</code>, <code>expm1l</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>expm1</code> is called. Otherwise, <code>expm1f</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur e<sup class="t-su">arg</sup>-1 is returned.</p> +<p>If a range error due to overflow occurs, <code><a href="huge_val" title="c/numeric/math/HUGE VAL">+HUGE_VAL</a></code>, <code>+HUGE_VALF</code>, or <code>+HUGE_VALL</code> is returned.</p> +<p>If a range error occurs due to underflow, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <code>math_errhandling</code>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> If the argument is ±0, it is returned, unmodified </li> +<li> If the argument is -∞, -1 is returned </li> +<li> If the argument is +∞, +∞ is returned </li> +<li> If the argument is NaN, NaN is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p>The functions <code>expm1</code> and <code><a href="log1p" title="c/numeric/math/log1p">log1p</a></code> are useful for financial calculations, for example, when calculating small daily interest rates: (1+x)<sup class="t-su">n</sup>-1 can be expressed as <code>expm1<span class="br0">(</span>n <span class="sy2">*</span> <a href="http://en.cppreference.com/w/c/numeric/math/log1p"><span class="kw661">log1p</span></a><span class="br0">(</span>x<span class="br0">)</span><span class="br0">)</span></code>. These functions also simplify writing accurate inverse hyperbolic functions.</p> +<p>For IEEE-compatible type <code>double</code>, overflow is guaranteed if 709.8 < arg.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> +#include <errno.h> +#include <fenv.h> +// #pragma STDC FENV_ACCESS ON +int main(void) +{ + printf("expm1(1) = %f\n", expm1(1)); + printf("Interest earned in 2 days on $100, compounded daily at 1%%\n" + " on a 30/360 calendar = %f\n", + 100*expm1(2*log1p(0.01/360))); + printf("exp(1e-16)-1 = %g, but expm1(1e-16) = %g\n", + exp(1e-16)-1, expm1(1e-16)); + // special values + printf("expm1(-0) = %f\n", expm1(-0.0)); + printf("expm1(-Inf) = %f\n", expm1(-INFINITY)); + //error handling + errno = 0; feclearexcept(FE_ALL_EXCEPT); + printf("expm1(710) = %f\n", expm1(710)); + if(errno == ERANGE) perror(" errno == ERANGE"); + if(fetestexcept(FE_OVERFLOW)) puts(" FE_OVERFLOW raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">expm1(1) = 1.718282 +Interest earned in 2 days on $100, compounded daily at 1% + on a 30/360 calendar = 0.005556 +exp(1e-16)-1 = 0, but expm1(1e-16) = 1e-16 +expm1(-0) = -0.000000 +expm1(-Inf) = -1.000000 +expm1(710) = inf + errno == ERANGE: Result too large + FE_OVERFLOW raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.6.3 The expm1 functions (p: 177) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.3.3 The expm1 functions (p: 379) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.6.3 The expm1 functions (p: 243) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.3.3 The expm1 functions (p: 521) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.6.3 The expm1 functions (p: 223-224) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.3.3 The expm1 functions (p: 458) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="exp" title="c/numeric/math/exp"> <span class="t-lines"><span>exp</span><span>expf</span><span>expl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes <i>e</i> raised to the given power (\({\small e^x}\)e<sup>x</sup>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="exp2" title="c/numeric/math/exp2"> <span class="t-lines"><span>exp2</span><span>exp2f</span><span>exp2l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes <i>2</i> raised to the given power (\({\small 2^x}\)2<sup>x</sup>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="log1p" title="c/numeric/math/log1p"> <span class="t-lines"><span>log1p</span><span>log1pf</span><span>log1pl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes natural (base-<i>e</i>) logarithm of 1 plus the given number (\({\small \ln{(1+x)} }\)ln(1+x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/expm1" title="cpp/numeric/math/expm1">C++ documentation</a></span> for <code>expm1</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/expm1" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/expm1</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Ffabs.html b/devdocs/c/numeric%2Fmath%2Ffabs.html new file mode 100644 index 00000000..a4944087 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffabs.html @@ -0,0 +1,96 @@ + <h1 id="firstHeading" class="firstHeading">fabs, fabsf, fabsl, fabsd32, fabsd64, fabsd128</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float fabsf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double fabs( double arg );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double fabsl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal32 fabsd32( _Decimal32 arg );</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal64 fabsd64( _Decimal64 arg );</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal128 fabsd128( _Decimal128 arg );</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define fabs( arith )</pre> +</td> <td> (7) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-6)</span> Computes the absolute value of a floating point value <code>arg</code>. <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>The functions with decimal floating point parameters are declared if and only if the implementation predefines <code>__STDC_IEC_60559_DFP__</code> (i.e. the implementation supports decimal floating point numbers).</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> +</div> <div class="t-li1"> +<span class="t-li">7)</span> Type-generic macro: If the argument has type <span class="t-rev-inl t-since-c23"><span><code>_Decimal128</code>, <code>_Decimal64</code>, <code>_Decimal32</code>,</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span><code>long double</code>, <code>double</code>, or <code>float</code>, <span class="t-rev-inl t-since-c23"><span><code>fabsd128</code>, <code>fabsd64</code>, <code>fabsd32</code>,</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span><code>fabsl</code>, <code>fabs</code>, or <code>fabsf</code> is called, respectively. Otherwise, if the argument has integer type, <code>fabs</code> is called. Otherwise, if the argument is complex, then the macro invokes the corresponding complex function (<code><a href="../complex/cabs" title="c/numeric/complex/cabs">cabsf</a></code>, <code><a href="../complex/cabs" title="c/numeric/complex/cabs">cabs</a></code>, <code><a href="../complex/cabs" title="c/numeric/complex/cabs">cabsl</a></code>). Otherwise, the behavior is undefined.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> <tr class="t-par"> <td> arith </td> <td> - </td> <td> floating point or integer value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If successful, returns the absolute value of <code>arg</code> (\(\small |arg| \)|arg|). The value returned is exact and does not depend on any rounding modes.</p> +<h3 id="Error_handling"> Error handling</h3> <p>This function is not subject to any of the error conditions specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> If the argument is ±0, +0 is returned </li> +<li> If the argument is ±∞, +∞ is returned </li> +<li> If the argument is NaN, NaN is returned </li> +</ul> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <math.h> +#include <stdio.h> + +#define PI 3.14159 + +// This numerical integration assumes all area is positive. +double integrate(double f(double), + double a, double b, // assume a < b + unsigned steps) // assume steps > 0 +{ + const double dx = (b - a) / steps; + double sum = 0.0; + for (double x = a; x < b; x += dx) + sum += fabs(f(x)); + return dx * sum; +} + +int main(void) +{ + printf("fabs(+3) = %f\n", fabs(+3.0)); + printf("fabs(-3) = %f\n", fabs(-3.0)); + // special values + printf("fabs(-0) = %f\n", fabs(-0.0)); + printf("fabs(-Inf) = %f\n", fabs(-INFINITY)); + + printf("Area under sin(x) in [-PI, PI] = %f\n", integrate(sin, -PI, PI, 5101)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">fabs(+3) = 3.000000 +fabs(-3) = 3.000000 +fabs(-0) = 0.000000 +fabs(-Inf) = inf +Area under sin(x) in [-PI, PI] = 4.000000</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.12.7.2 The fabs functions (p: TBD) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: TBD) </li> +<li> F.10.4.2 The fabs functions (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.7.2 The fabs functions (p: 181) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.4.2 The fabs functions (p: 382) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.7.2 The fabs functions (p: 248) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.4.2 The fabs functions (p: 524) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.7.2 The fabs functions (p: 228-229) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.4.2 The fabs functions (p: 460) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.6.2 The fabs function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="abs" title="c/numeric/math/abs"> <span class="t-lines"><span>abs</span><span>labs</span><span>llabs</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes absolute value of an integral value (\(\small{|x|}\)|x|) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="copysign" title="c/numeric/math/copysign"> <span class="t-lines"><span>copysign</span><span>copysignf</span><span>copysignl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> produces a value with the magnitude of a given value and the sign of another given value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="signbit" title="c/numeric/math/signbit"> <span class="t-lines"><span>signbit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number is negative <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../complex/cabs" title="c/numeric/complex/cabs"> <span class="t-lines"><span>cabs</span><span>cabsf</span><span>cabsl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the magnitude of a complex number <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/fabs" title="cpp/numeric/math/fabs">C++ documentation</a></span> for <code>fabs</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/fabs" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/fabs</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Ffdim.html b/devdocs/c/numeric%2Fmath%2Ffdim.html new file mode 100644 index 00000000..4d64f3ac --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffdim.html @@ -0,0 +1,63 @@ + <h1 id="firstHeading" class="firstHeading">fdim, fdimf, fdiml</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float fdimf( float x, float y );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double fdim( double x, double y );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double fdiml( long double x, long double y );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define fdim( x, y )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Returns the positive difference between <code>x</code> and <code>y</code>, that is, if <code>x>y</code>, returns <code>x-y</code>, otherwise (if <code>x≤y</code>), returns +0.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If any argument has type <code>long double</code>, <code>fdiml</code> is called. Otherwise, if any argument has integer type or has type <code>double</code>, <code>fdim</code> is called. Otherwise, <code>fdimf</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> x, y </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If successful, returns the positive difference between x and y.</p> +<p>If a range error due to overflow occurs, <code><a href="huge_val" title="c/numeric/math/HUGE VAL">+HUGE_VAL</a></code>, <code>+HUGE_VALF</code>, or <code>+HUGE_VALL</code> is returned.</p> +<p>If a range error due to underflow occurs, the correct value (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <code>math_errhandling</code>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul><li> If either argument is NaN, NaN is returned </li></ul> <h3 id="Notes"> Notes</h3> <p>Equivalent to <code><a href="http://en.cppreference.com/w/c/numeric/math/fmax"><span class="kw651">fmax</span></a><span class="br0">(</span>x<span class="sy2">-</span>y, <span class="nu0">0</span><span class="br0">)</span></code> except for the NaN handling requirements.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <errno.h> +#include <fenv.h> +// #pragma STDC FENV_ACCESS ON +int main(void) +{ + printf("fdim(4, 1) = %f, fdim(1, 4)=%f\n", fdim(4,1), fdim(1,4)); + printf("fdim(4,-1) = %f, fdim(1,-4)=%f\n", fdim(4,-1), fdim(1,-4)); + //error handling + errno = 0; feclearexcept(FE_ALL_EXCEPT); + printf("fdim(1e308, -1e308) = %f\n", fdim(1e308, -1e308)); + if(errno == ERANGE) perror(" errno == ERANGE"); + if(fetestexcept(FE_OVERFLOW)) puts(" FE_OVERFLOW raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">fdim(4, 1) = 3.000000, fdim(1, 4)=0.000000 +fdim(4,-1) = 5.000000, fdim(1,-4)=5.000000 +fdim(1e308, -1e308) = inf + errno == ERANGE: Numerical result out of range + FE_OVERFLOW raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.12.1 The fdim functions (p: 187-188) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.9.1 The fdim functions (p: 386) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.12.1 The fdim functions (p: 257) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.9.1 The fdim functions (p: 530) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.12.1 The fdim functions (p: 238) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.9.1 The fdim functions (p: 466) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="abs" title="c/numeric/math/abs"> <span class="t-lines"><span>abs</span><span>labs</span><span>llabs</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes absolute value of an integral value (\(\small{|x|}\)|x|) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fmax" title="c/numeric/math/fmax"> <span class="t-lines"><span>fmax</span><span>fmaxf</span><span>fmaxl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> determines larger of two floating-point values <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/fdim" title="cpp/numeric/math/fdim">C++ documentation</a></span> for <code>fdim</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/fdim" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/fdim</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Ffloat_t.html b/devdocs/c/numeric%2Fmath%2Ffloat_t.html new file mode 100644 index 00000000..e9783b11 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffloat_t.html @@ -0,0 +1,34 @@ + <h1 id="firstHeading" class="firstHeading">float_t, double_t</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">typedef /*implementation defined*/ float_t</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">typedef /*implementation defined*/ double_t</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>The types <code>float_t</code> and <code>double_t</code> are floating types at least as wide as <code>float</code> and <code>double</code>, respectively, and such that <code>double_t</code> is at least as wide as <code>float_t</code>. The value of <code><a href="../../types/limits/flt_eval_method" title="c/types/limits/FLT EVAL METHOD">FLT_EVAL_METHOD</a></code> determines the types of <code>float_t</code> and <code>double_t</code>.</p> +<table class="t-dsc-begin"> <tr class="t-dsc-hitem"> <th> FLT_EVAL_METHOD </th> <th> Explanation </th> +</tr> <tr class="t-dsc"> <td> <code>0</code> </td> <td> <code>float_t</code> and <code>double_t</code> are equivalent to <code>float</code> and <code>double</code>, respectively </td> +</tr> <tr class="t-dsc"> <td> <code>1</code> </td> <td> both <code>float_t</code> and <code>double_t</code> are equivalent to <code>double</code> </td> +</tr> <tr class="t-dsc"> <td> <code>2</code> </td> <td> both <code>float_t</code> and <code>double_t</code> are equivalent to <code>long double</code> </td> +</tr> <tr class="t-dsc"> <td> <code>other</code> </td> <td> both <code>float_t</code> and <code>double_t</code> are implementation defined </td> +</tr> </table> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <float.h> +#include <math.h> +#include <stdio.h> + +int main(void) +{ + printf("%d\n", FLT_EVAL_METHOD); + printf("%zu %zu\n", sizeof(float),sizeof(float_t)); + printf("%zu %zu\n", sizeof(double),sizeof(double_t)); + return 0; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">0 +4 4 +8 8</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.12 Mathematics <math.h> (p: 231) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.12 Mathematics <math.h> (p: 212) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../../types/limits/flt_eval_method" title="c/types/limits/FLT EVAL METHOD"> <span class="t-lines"><span>FLT_EVAL_METHOD</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> use of extended precision for intermediate results: 0 not used, 1 <code>double</code> is used instead of <code>float</code>, 2: <code>long double</code> is used <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/float_t" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/float_t</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Ffloor.html b/devdocs/c/numeric%2Fmath%2Ffloor.html new file mode 100644 index 00000000..54153acb --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffloor.html @@ -0,0 +1,58 @@ + <h1 id="firstHeading" class="firstHeading">floor, floorf, floorl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float floorf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double floor( double arg );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double floorl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define floor( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the largest integer value not greater than <code>arg</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>arg</code> has type <code>long double</code>, <code>floorl</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>floor</code> is called. Otherwise, <code>floorf</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the largest integer value not greater than <code>arg</code>, that is ⌊arg⌋, is returned.</p> +<div class="t-plot"> <div class="t-plot-left">Return value</div> <div class="t-plot-image-left"><img alt="math-floor.svg" src="data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9Im5vIj8+CjwhRE9DVFlQRSBzdmcgUFVCTElDICItLy9XM0MvL0RURCBTVkcgMS4xLy9FTiIgImh0dHA6Ly93d3cudzMub3JnL0dyYXBoaWNzL1NWRy8xLjEvRFREL3N2ZzExLmR0ZCI+CjwhLS0gQ3JlYXRlZCB3aXRoIG1hdHBsb3RsaWIgKGh0dHA6Ly9tYXRwbG90bGliLnNvdXJjZWZvcmdlLm5ldC8pIC0tPgo8c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIGhlaWdodD0iMjAwcHgiIHZlcnNpb249IjEuMSIgdmlld0JveD0iMCAwIDIwMCAyMDAiIHdpZHRoPSIyMDBweCI+CiA8ZGVmcz4KICA8c3R5bGUgdHlwZT0idGV4dC9jc3MiPgoqe3N0cm9rZS1saW5lY2FwOnNxdWFyZTtzdHJva2UtbGluZWpvaW46cm91bmQ7fQogIDwvc3R5bGU+CiA8L2RlZnM+CiA8ZyBpZD0iZmlndXJlXzEiPgogIDxnIGlkPSJwYXRjaF8xIj4KICAgPHBhdGggZD0iIE0wIDIwMCBMMjAwIDIwMCBMMjAwIDAgTDAgMCB6ICIgc3R5bGU9ImZpbGw6I2ZmZmZmZjsiLz4KICA8L2c+CiAgPGcgaWQ9ImF4ZXNfMSI+CiAgIDxnIGlkPSJwYXRjaF8yIj4KICAgIDxwYXRoIGQ9IiBNMjUgMTc3LjUgTDE4MCAxNzcuNSBMMTgwIDIyLjUgTDI1IDIyLjUgeiAiIHN0eWxlPSJmaWxsOiNmZmZmZmY7Ii8+CiAgIDwvZz4KICAgPGcgaWQ9Im1hdHBsb3RsaWIuYXhpc18xIj4KICAgIDxnIGlkPSJ4dGlja18xIj4KICAgICA8ZyBpZD0ibGluZTJkXzEiPgogICAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTM2LjA3MTQgMTc3LjUgTDM2LjA3MTQgMjIuNSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDtzdHJva2UtZGFzaGFycmF5OjEuMDAwMDAwLDMuMDAwMDAwO3N0cm9rZS1kYXNob2Zmc2V0OjAuMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMiI+CiAgICAgIDxkZWZzPgogICAgICAgPHBhdGggZD0iIE0wIDAgTDAgLTQiIGlkPSJtMDAxMmRkNGVlZiIgc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICAgPC9kZWZzPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjM2LjA3MTQyODU3MTQiIHhsaW5rOmhyZWY9IiNtMDAxMmRkNGVlZiIgeT0iMTc3LjUiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzMiPgogICAgICA8ZGVmcz4KICAgICAgIDxwYXRoIGQ9IiBNMCAwIEwwIDQiIGlkPSJtNDc2MzQ0OTY5YyIgc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICAgPC9kZWZzPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjM2LjA3MTQyODU3MTQiIHhsaW5rOmhyZWY9IiNtNDc2MzQ0OTY5YyIgeT0iMjIuNSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzEiPgogICAgICA8IS0tIOKIkjMgLS0+CiAgICAgIDxkZWZzPgogICAgICAgPHBhdGggZD0iIE00MC41NzgxIDM5LjMxMjUgUTQ3LjY1NjIgMzcuNzk2OSA1MS42MjUgMzMgUTU1LjYwOTQgMjguMjE4OCA1NS42MDk0IDIxLjE4NzUgUTU1LjYwOTQgMTAuNDA2MiA0OC4xODc1IDQuNDg0MzggUTQwLjc2NTYgLTEuNDIxODggMjcuMDkzOCAtMS40MjE4OCBRMjIuNTE1NiAtMS40MjE4OCAxNy42NTYyIC0wLjUxNTYyNSBRMTIuNzk2OSAwLjM5MDYyNSA3LjYyNSAyLjIwMzEyIEw3LjYyNSAxMS43MTg4IFExMS43MTg4IDkuMzI4MTIgMTYuNTkzOCA4LjEwOTM4IFEyMS40ODQ0IDYuODkwNjIgMjYuODEyNSA2Ljg5MDYyIFEzNi4wNzgxIDYuODkwNjIgNDAuOTM3NSAxMC41NDY5IFE0NS43OTY5IDE0LjIwMzEgNDUuNzk2OSAyMS4xODc1IFE0NS43OTY5IDI3LjY0MDYgNDEuMjgxMiAzMS4yNjU2IFEzNi43NjU2IDM0LjkwNjIgMjguNzE4OCAzNC45MDYyIEwyMC4yMTg4IDM0LjkwNjIgTDIwLjIxODggNDMuMDE1NiBMMjkuMTA5NCA0My4wMTU2IFEzNi4zNzUgNDMuMDE1NiA0MC4yMzQ0IDQ1LjkyMTkgUTQ0LjA5MzggNDguODI4MSA0NC4wOTM4IDU0LjI5NjkgUTQ0LjA5MzggNTkuOTA2MiA0MC4xMDk0IDYyLjkwNjIgUTM2LjE0MDYgNjUuOTIxOSAyOC43MTg4IDY1LjkyMTkgUTI0LjY1NjIgNjUuOTIxOSAyMC4wMTU2IDY1LjAzMTIgUTE1LjM3NSA2NC4xNTYyIDkuODEyNSA2Mi4zMTI1IEw5LjgxMjUgNzEuMDkzOCBRMTUuNDM3NSA3Mi42NTYyIDIwLjM0MzggNzMuNDM3NSBRMjUuMjUgNzQuMjE4OCAyOS41OTM4IDc0LjIxODggUTQwLjgyODEgNzQuMjE4OCA0Ny4zNTk0IDY5LjEwOTQgUTUzLjkwNjIgNjQuMDE1NiA1My45MDYyIDU1LjMyODEgUTUzLjkwNjIgNDkuMjY1NiA1MC40Mzc1IDQ1LjA5MzggUTQ2Ljk2ODggNDAuOTIxOSA0MC41NzgxIDM5LjMxMjUiIGlkPSJEZWphVnVTYW5zLTMzIi8+CiAgICAgICA8cGF0aCBkPSIgTTEwLjU5MzggMzUuNSBMNzMuMTg3NSAzNS41IEw3My4xODc1IDI3LjIwMzEgTDEwLjU5MzggMjcuMjAzMSB6ICIgaWQ9IkRlamFWdVNhbnMtMjIxMiIvPgogICAgICA8L2RlZnM+CiAgICAgIDxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDMwLjI3NDg2NjA3MTQgMTkxLjY3OTY4NzUpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0yMjEyIi8+CiAgICAgICA8dXNlIHg9IjgzLjc4OTA2MjUiIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTMzIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICA8L2c+CiAgICA8ZyBpZD0ieHRpY2tfMiI+CiAgICAgPGcgaWQ9ImxpbmUyZF80Ij4KICAgICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE01OC4yMTQzIDE3Ny41IEw1OC4yMTQzIDIyLjUiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWRhc2hhcnJheToxLjAwMDAwMCwzLjAwMDAwMDtzdHJva2UtZGFzaG9mZnNldDowLjA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzUiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjU4LjIxNDI4NTcxNDMiIHhsaW5rOmhyZWY9IiNtMDAxMmRkNGVlZiIgeT0iMTc3LjUiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzYiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjU4LjIxNDI4NTcxNDMiIHhsaW5rOmhyZWY9IiNtNDc2MzQ0OTY5YyIgeT0iMjIuNSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzIiPgogICAgICA8IS0tIOKIkjIgLS0+CiAgICAgIDxkZWZzPgogICAgICAgPHBhdGggZD0iIE0xOS4xODc1IDguMjk2ODggTDUzLjYwOTQgOC4yOTY4OCBMNTMuNjA5NCAwIEw3LjMyODEyIDAgTDcuMzI4MTIgOC4yOTY4OCBRMTIuOTM3NSAxNC4xMDk0IDIyLjYyNSAyMy44OTA2IFEzMi4zMjgxIDMzLjY4NzUgMzQuODEyNSAzNi41MzEyIFEzOS41NDY5IDQxLjg0MzggNDEuNDIxOSA0NS41MzEyIFE0My4zMTI1IDQ5LjIxODggNDMuMzEyNSA1Mi43ODEyIFE0My4zMTI1IDU4LjU5MzggMzkuMjM0NCA2Mi4yNSBRMzUuMTU2MiA2NS45MjE5IDI4LjYwOTQgNjUuOTIxOSBRMjMuOTY4OCA2NS45MjE5IDE4LjgxMjUgNjQuMzEyNSBRMTMuNjcxOSA2Mi43MDMxIDcuODEyNSA1OS40MjE5IEw3LjgxMjUgNjkuMzkwNiBRMTMuNzY1NiA3MS43ODEyIDE4LjkzNzUgNzMgUTI0LjEyNSA3NC4yMTg4IDI4LjQyMTkgNzQuMjE4OCBRMzkuNzUgNzQuMjE4OCA0Ni40ODQ0IDY4LjU0NjkgUTUzLjIxODggNjIuODkwNiA1My4yMTg4IDUzLjQyMTkgUTUzLjIxODggNDguOTIxOSA1MS41MzEyIDQ0Ljg5MDYgUTQ5Ljg1OTQgNDAuODc1IDQ1LjQwNjIgMzUuNDA2MiBRNDQuMTg3NSAzMy45ODQ0IDM3LjY0MDYgMjcuMjE4OCBRMzEuMTA5NCAyMC40NTMxIDE5LjE4NzUgOC4yOTY4OCIgaWQ9IkRlamFWdVNhbnMtMzIiLz4KICAgICAgPC9kZWZzPgogICAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSg1Mi41MDc3MjMyMTQzIDE5MS42Nzk2ODc1KXNjYWxlKDAuMDkgLTAuMDkpIj4KICAgICAgIDx1c2UgeGxpbms6aHJlZj0iI0RlamFWdVNhbnMtMjIxMiIvPgogICAgICAgPHVzZSB4PSI4My43ODkwNjI1IiB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMiIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICAgPGcgaWQ9Inh0aWNrXzMiPgogICAgIDxnIGlkPSJsaW5lMmRfNyI+CiAgICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNODAuMzU3MSAxNzcuNSBMODAuMzU3MSAyMi41IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF84Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSI4MC4zNTcxNDI4NTcxIiB4bGluazpocmVmPSIjbTAwMTJkZDRlZWYiIHk9IjE3Ny41Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF85Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSI4MC4zNTcxNDI4NTcxIiB4bGluazpocmVmPSIjbTQ3NjM0NDk2OWMiIHk9IjIyLjUiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0idGV4dF8zIj4KICAgICAgPCEtLSDiiJIxIC0tPgogICAgICA8ZGVmcz4KICAgICAgIDxwYXRoIGQ9IiBNMTIuNDA2MiA4LjI5Njg4IEwyOC41MTU2IDguMjk2ODggTDI4LjUxNTYgNjMuOTIxOSBMMTAuOTg0NCA2MC40MDYyIEwxMC45ODQ0IDY5LjM5MDYgTDI4LjQyMTkgNzIuOTA2MiBMMzguMjgxMiA3Mi45MDYyIEwzOC4yODEyIDguMjk2ODggTDU0LjM5MDYgOC4yOTY4OCBMNTQuMzkwNiAwIEwxMi40MDYyIDAgeiAiIGlkPSJEZWphVnVTYW5zLTMxIi8+CiAgICAgIDwvZGVmcz4KICAgICAgPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNzQuNjE1NDI0MTA3MSAxOTEuNTYxNTYyNSlzY2FsZSgwLjA5IC0wLjA5KSI+CiAgICAgICA8dXNlIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTIyMTIiLz4KICAgICAgIDx1c2UgeD0iODMuNzg5MDYyNSIgeGxpbms6aHJlZj0iI0RlamFWdVNhbnMtMzEiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgIDwvZz4KICAgIDxnIGlkPSJ4dGlja180Ij4KICAgICA8ZyBpZD0ibGluZTJkXzEwIj4KICAgICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0xMDIuNSAxNzcuNSBMMTAyLjUgMjIuNSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDtzdHJva2UtZGFzaGFycmF5OjEuMDAwMDAwLDMuMDAwMDAwO3N0cm9rZS1kYXNob2Zmc2V0OjAuMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMTEiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjEwMi41IiB4bGluazpocmVmPSIjbTAwMTJkZDRlZWYiIHk9IjE3Ny41Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8xMiI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTAyLjUiIHhsaW5rOmhyZWY9IiNtNDc2MzQ0OTY5YyIgeT0iMjIuNSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzQiPgogICAgICA8IS0tIDAgLS0+CiAgICAgIDxkZWZzPgogICAgICAgPHBhdGggZD0iIE0zMS43ODEyIDY2LjQwNjIgUTI0LjE3MTkgNjYuNDA2MiAyMC4zMjgxIDU4LjkwNjIgUTE2LjUgNTEuNDIxOSAxNi41IDM2LjM3NSBRMTYuNSAyMS4zOTA2IDIwLjMyODEgMTMuODkwNiBRMjQuMTcxOSA2LjM5MDYyIDMxLjc4MTIgNi4zOTA2MiBRMzkuNDUzMSA2LjM5MDYyIDQzLjI4MTIgMTMuODkwNiBRNDcuMTI1IDIxLjM5MDYgNDcuMTI1IDM2LjM3NSBRNDcuMTI1IDUxLjQyMTkgNDMuMjgxMiA1OC45MDYyIFEzOS40NTMxIDY2LjQwNjIgMzEuNzgxMiA2Ni40MDYyIE0zMS43ODEyIDc0LjIxODggUTQ0LjA0NjkgNzQuMjE4OCA1MC41MTU2IDY0LjUxNTYgUTU2Ljk4NDQgNTQuODI4MSA1Ni45ODQ0IDM2LjM3NSBRNTYuOTg0NCAxNy45Njg4IDUwLjUxNTYgOC4yNjU2MiBRNDQuMDQ2OSAtMS40MjE4OCAzMS43ODEyIC0xLjQyMTg4IFExOS41MzEyIC0xLjQyMTg4IDEzLjA2MjUgOC4yNjU2MiBRNi41OTM3NSAxNy45Njg4IDYuNTkzNzUgMzYuMzc1IFE2LjU5Mzc1IDU0LjgyODEgMTMuMDYyNSA2NC41MTU2IFExOS41MzEyIDc0LjIxODggMzEuNzgxMiA3NC4yMTg4IiBpZD0iRGVqYVZ1U2Fucy0zMCIvPgogICAgICA8L2RlZnM+CiAgICAgIDxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDEwMC4yMzI0MjE4NzUgMTkxLjY3OTY4NzUpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMCIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICAgPGcgaWQ9Inh0aWNrXzUiPgogICAgIDxnIGlkPSJsaW5lMmRfMTMiPgogICAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTEyNC42NDMgMTc3LjUgTDEyNC42NDMgMjIuNSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDtzdHJva2UtZGFzaGFycmF5OjEuMDAwMDAwLDMuMDAwMDAwO3N0cm9rZS1kYXNob2Zmc2V0OjAuMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMTQiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjEyNC42NDI4NTcxNDMiIHhsaW5rOmhyZWY9IiNtMDAxMmRkNGVlZiIgeT0iMTc3LjUiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzE1Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxMjQuNjQyODU3MTQzIiB4bGluazpocmVmPSIjbTQ3NjM0NDk2OWMiIHk9IjIyLjUiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0idGV4dF81Ij4KICAgICAgPCEtLSAxIC0tPgogICAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMjIuNjg5NTc1ODkzIDE5MS41NjE1NjI1KXNjYWxlKDAuMDkgLTAuMDkpIj4KICAgICAgIDx1c2UgeGxpbms6aHJlZj0iI0RlamFWdVNhbnMtMzEiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgIDwvZz4KICAgIDxnIGlkPSJ4dGlja182Ij4KICAgICA8ZyBpZD0ibGluZTJkXzE2Ij4KICAgICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0xNDYuNzg2IDE3Ny41IEwxNDYuNzg2IDIyLjUiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWRhc2hhcnJheToxLjAwMDAwMCwzLjAwMDAwMDtzdHJva2UtZGFzaG9mZnNldDowLjA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzE3Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxNDYuNzg1NzE0Mjg2IiB4bGluazpocmVmPSIjbTAwMTJkZDRlZWYiIHk9IjE3Ny41Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8xOCI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTQ2Ljc4NTcxNDI4NiIgeGxpbms6aHJlZj0iI200NzYzNDQ5NjljIiB5PSIyMi41Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9InRleHRfNiI+CiAgICAgIDwhLS0gMiAtLT4KICAgICAgPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMTQ0LjcwMzA1ODAzNiAxOTEuNjc5Njg3NSlzY2FsZSgwLjA5IC0wLjA5KSI+CiAgICAgICA8dXNlIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTMyIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICA8L2c+CiAgICA8ZyBpZD0ieHRpY2tfNyI+CiAgICAgPGcgaWQ9ImxpbmUyZF8xOSI+CiAgICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMTY4LjkyOSAxNzcuNSBMMTY4LjkyOSAyMi41IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8yMCI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTY4LjkyODU3MTQyOSIgeGxpbms6aHJlZj0iI20wMDEyZGQ0ZWVmIiB5PSIxNzcuNSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMjEiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjE2OC45Mjg1NzE0MjkiIHhsaW5rOmhyZWY9IiNtNDc2MzQ0OTY5YyIgeT0iMjIuNSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzciPgogICAgICA8IS0tIDMgLS0+CiAgICAgIDxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDE2Ni43NjkyNzQ1NTQgMTkxLjY3OTY4NzUpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMyIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICA8L2c+CiAgIDxnIGlkPSJtYXRwbG90bGliLmF4aXNfMiI+CiAgICA8ZyBpZD0ieXRpY2tfMSI+CiAgICAgPGcgaWQ9ImxpbmUyZF8yMiI+CiAgICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMjUgMTY2LjQyOSBMMTgwIDE2Ni40MjkiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWRhc2hhcnJheToxLjAwMDAwMCwzLjAwMDAwMDtzdHJva2UtZGFzaG9mZnNldDowLjA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzIzIj4KICAgICAgPGRlZnM+CiAgICAgICA8cGF0aCBkPSIgTTAgMCBMNCAwIiBpZD0ibWU4YTg1ZjdiZjYiIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICAgIDwvZGVmcz4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIyNS4wIiB4bGluazpocmVmPSIjbWU4YTg1ZjdiZjYiIHk9IjE2Ni40Mjg1NzE0MjkiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzI0Ij4KICAgICAgPGRlZnM+CiAgICAgICA8cGF0aCBkPSIgTTAgMCBMLTQgMCIgaWQ9Im0xYTMyMDA1ZGVhIiBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgICA8L2RlZnM+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTgwLjAiIHhsaW5rOmhyZWY9IiNtMWEzMjAwNWRlYSIgeT0iMTY2LjQyODU3MTQyOSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzgiPgogICAgICA8IS0tIOKIkjMgLS0+CiAgICAgIDxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDUuOTA2ODc1IDE2OS43MDQ0MzA4MDQpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0yMjEyIi8+CiAgICAgICA8dXNlIHg9IjgzLjc4OTA2MjUiIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTMzIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICA8L2c+CiAgICA8ZyBpZD0ieXRpY2tfMiI+CiAgICAgPGcgaWQ9ImxpbmUyZF8yNSI+CiAgICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMjUgMTQ0LjI4NiBMMTgwIDE0NC4yODYiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWRhc2hhcnJheToxLjAwMDAwMCwzLjAwMDAwMDtzdHJva2UtZGFzaG9mZnNldDowLjA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzI2Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIyNS4wIiB4bGluazpocmVmPSIjbWU4YTg1ZjdiZjYiIHk9IjE0NC4yODU3MTQyODYiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzI3Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxODAuMCIgeGxpbms6aHJlZj0iI20xYTMyMDA1ZGVhIiB5PSIxNDQuMjg1NzE0Mjg2Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9InRleHRfOSI+CiAgICAgIDwhLS0g4oiSMiAtLT4KICAgICAgPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNi4wODY4NzUgMTQ3LjYyNTU1ODAzNilzY2FsZSgwLjA5IC0wLjA5KSI+CiAgICAgICA8dXNlIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTIyMTIiLz4KICAgICAgIDx1c2UgeD0iODMuNzg5MDYyNSIgeGxpbms6aHJlZj0iI0RlamFWdVNhbnMtMzIiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgIDwvZz4KICAgIDxnIGlkPSJ5dGlja18zIj4KICAgICA8ZyBpZD0ibGluZTJkXzI4Ij4KICAgICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0yNSAxMjIuMTQzIEwxODAgMTIyLjE0MyIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDtzdHJva2UtZGFzaGFycmF5OjEuMDAwMDAwLDMuMDAwMDAwO3N0cm9rZS1kYXNob2Zmc2V0OjAuMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMjkiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjI1LjAiIHhsaW5rOmhyZWY9IiNtZThhODVmN2JmNiIgeT0iMTIyLjE0Mjg1NzE0MyIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMzAiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjE4MC4wIiB4bGluazpocmVmPSIjbTFhMzIwMDVkZWEiIHk9IjEyMi4xNDI4NTcxNDMiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0idGV4dF8xMCI+CiAgICAgIDwhLS0g4oiSMSAtLT4KICAgICAgPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNi4wMTY1NjI1IDEyNS40MjM2MzgzOTMpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0yMjEyIi8+CiAgICAgICA8dXNlIHg9IjgzLjc4OTA2MjUiIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTMxIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICA8L2c+CiAgICA8ZyBpZD0ieXRpY2tfNCI+CiAgICAgPGcgaWQ9ImxpbmUyZF8zMSI+CiAgICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMjUgMTAwIEwxODAgMTAwIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8zMiI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMjUuMCIgeGxpbms6aHJlZj0iI21lOGE4NWY3YmY2IiB5PSIxMDAuMCIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMzMiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjE4MC4wIiB4bGluazpocmVmPSIjbTFhMzIwMDVkZWEiIHk9IjEwMC4wIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9InRleHRfMTEiPgogICAgICA8IS0tIDAgLS0+CiAgICAgIDxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDEyLjk2NDg0Mzc1IDEwMy4yNzU4NTkzNzUpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMCIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICAgPGcgaWQ9Inl0aWNrXzUiPgogICAgIDxnIGlkPSJsaW5lMmRfMzQiPgogICAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTI1IDc3Ljg1NzEgTDE4MCA3Ny44NTcxIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8zNSI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMjUuMCIgeGxpbms6aHJlZj0iI21lOGE4NWY3YmY2IiB5PSI3Ny44NTcxNDI4NTcxIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8zNiI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTgwLjAiIHhsaW5rOmhyZWY9IiNtMWEzMjAwNWRlYSIgeT0iNzcuODU3MTQyODU3MSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzEyIj4KICAgICAgPCEtLSAxIC0tPgogICAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMy41OTM0Mzc1IDgxLjEzNzkyNDEwNzEpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICAgPGcgaWQ9Inl0aWNrXzYiPgogICAgIDxnIGlkPSJsaW5lMmRfMzciPgogICAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTI1IDU1LjcxNDMgTDE4MCA1NS43MTQzIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8zOCI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMjUuMCIgeGxpbms6aHJlZj0iI21lOGE4NWY3YmY2IiB5PSI1NS43MTQyODU3MTQzIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8zOSI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTgwLjAiIHhsaW5rOmhyZWY9IiNtMWEzMjAwNWRlYSIgeT0iNTUuNzE0Mjg1NzE0MyIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzEzIj4KICAgICAgPCEtLSAyIC0tPgogICAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMy4zMzQ2ODc1IDU5LjA1NDEyOTQ2NDMpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMiIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICAgPGcgaWQ9Inl0aWNrXzciPgogICAgIDxnIGlkPSJsaW5lMmRfNDAiPgogICAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTI1IDMzLjU3MTQgTDE4MCAzMy41NzE0IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF80MSI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMjUuMCIgeGxpbms6aHJlZj0iI21lOGE4NWY3YmY2IiB5PSIzMy41NzE0Mjg1NzE0Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF80MiI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTgwLjAiIHhsaW5rOmhyZWY9IiNtMWEzMjAwNWRlYSIgeT0iMzMuNTcxNDI4NTcxNCIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzE0Ij4KICAgICAgPCEtLSAzIC0tPgogICAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMy4xODE0MDYyNSAzNi44NDcyODc5NDY0KXNjYWxlKDAuMDkgLTAuMDkpIj4KICAgICAgIDx1c2UgeGxpbms6aHJlZj0iI0RlamFWdVNhbnMtMzMiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgIDwvZz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzQzIj4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMzYuMDcxNCAxNjYuNDI5IEw1OC4yMTQzIDE2Ni40MjkiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzQ0Ij4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNNTguMjE0MyAxNDQuMjg2IEw4MC4zNTcxIDE0NC4yODYiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzQ1Ij4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNODAuMzU3MSAxMjIuMTQzIEwxMDIuNSAxMjIuMTQzIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMGZmO3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF80NiI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTEwMi41IDEwMCBMMTI0LjY0MyAxMDAiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzQ3Ij4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMTI0LjY0MyA3Ny44NTcxIEwxNDYuNzg2IDc3Ljg1NzEiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzQ4Ij4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMTQ2Ljc4NiA1NS43MTQzIEwxNjguOTI5IDU1LjcxNDMiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzQ5Ij4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMTY4LjkyOSAzMy41NzE0IEwxODAgMzMuNTcxNCIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDBmZjtzdHJva2Utd2lkdGg6MC41OyIvPgogICA8L2c+CiAgIDxnIGlkPSJsaW5lMmRfNTAiPgogICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0zNi4wNzE0IDE2Ni40MjkiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwZmY7Ii8+CiAgICA8ZGVmcz4KICAgICA8cGF0aCBkPSIgTTAgMy43NSBDMC45OTQ1MTIgMy43NSAxLjk0ODQyIDMuMzU0ODggMi42NTE2NSAyLjY1MTY1IEMzLjM1NDg4IDEuOTQ4NDIgMy43NSAwLjk5NDUxMiAzLjc1IDAgQzMuNzUgLTAuOTk0NTEyIDMuMzU0ODggLTEuOTQ4NDIgMi42NTE2NSAtMi42NTE2NSBDMS45NDg0MiAtMy4zNTQ4OCAwLjk5NDUxMiAtMy43NSAwIC0zLjc1IEMtMC45OTQ1MTIgLTMuNzUgLTEuOTQ4NDIgLTMuMzU0ODggLTIuNjUxNjUgLTIuNjUxNjUgQy0zLjM1NDg4IC0xLjk0ODQyIC0zLjc1IC0wLjk5NDUxMiAtMy43NSAwIEMtMy43NSAwLjk5NDUxMiAtMy4zNTQ4OCAxLjk0ODQyIC0yLjY1MTY1IDIuNjUxNjUgQy0xLjk0ODQyIDMuMzU0ODggLTAuOTk0NTEyIDMuNzUgMCAzLjc1IHogIiBpZD0ibWU1M2I3YmI2ZDIiIHN0eWxlPSJzdHJva2U6IzAwMDBmZjtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICA8L2RlZnM+CiAgICA8ZyBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIj4KICAgICA8dXNlIHN0eWxlPSJmaWxsOiMwMDAwZmY7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMzYuMDcxNDI4NTcxNCIgeGxpbms6aHJlZj0iI21lNTNiN2JiNmQyIiB5PSIxNjYuNDI4NTcxNDI5Ii8+CiAgICA8L2c+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF81MSI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTU4LjIxNDMgMTY2LjQyOSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwODAwMDsiLz4KICAgIDxkZWZzPgogICAgIDxwYXRoIGQ9IiBNMCAzLjc1IEMwLjk5NDUxMiAzLjc1IDEuOTQ4NDIgMy4zNTQ4OCAyLjY1MTY1IDIuNjUxNjUgQzMuMzU0ODggMS45NDg0MiAzLjc1IDAuOTk0NTEyIDMuNzUgMCBDMy43NSAtMC45OTQ1MTIgMy4zNTQ4OCAtMS45NDg0MiAyLjY1MTY1IC0yLjY1MTY1IEMxLjk0ODQyIC0zLjM1NDg4IDAuOTk0NTEyIC0zLjc1IDAgLTMuNzUgQy0wLjk5NDUxMiAtMy43NSAtMS45NDg0MiAtMy4zNTQ4OCAtMi42NTE2NSAtMi42NTE2NSBDLTMuMzU0ODggLTEuOTQ4NDIgLTMuNzUgLTAuOTk0NTEyIC0zLjc1IDAgQy0zLjc1IDAuOTk0NTEyIC0zLjM1NDg4IDEuOTQ4NDIgLTIuNjUxNjUgMi42NTE2NSBDLTEuOTQ4NDIgMy4zNTQ4OCAtMC45OTQ1MTIgMy43NSAwIDMuNzUgeiAiIGlkPSJtZTI3ODA2NDJlMiIgc3R5bGU9InN0cm9rZTojMDAwMGZmO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgIDwvZGVmcz4KICAgIDxnIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiPgogICAgIDx1c2Ugc3R5bGU9ImZpbGw6I2ZmZmZmZjtzdHJva2U6IzAwMDBmZjtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSI1OC4yMTQyODU3MTQzIiB4bGluazpocmVmPSIjbWUyNzgwNjQyZTIiIHk9IjE2Ni40Mjg1NzE0MjkiLz4KICAgIDwvZz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzUyIj4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNNTguMjE0MyAxNDQuMjg2IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojZmYwMDAwOyIvPgogICAgPGcgY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSI+CiAgICAgPHVzZSBzdHlsZT0iZmlsbDojMDAwMGZmO3N0cm9rZTojMDAwMGZmO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjU4LjIxNDI4NTcxNDMiIHhsaW5rOmhyZWY9IiNtZTUzYjdiYjZkMiIgeT0iMTQ0LjI4NTcxNDI4NiIvPgogICAgPC9nPgogICA8L2c+CiAgIDxnIGlkPSJsaW5lMmRfNTMiPgogICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE04MC4zNTcxIDE0NC4yODYiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMGJmYmY7Ii8+CiAgICA8ZyBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIj4KICAgICA8dXNlIHN0eWxlPSJmaWxsOiNmZmZmZmY7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iODAuMzU3MTQyODU3MSIgeGxpbms6aHJlZj0iI21lMjc4MDY0MmUyIiB5PSIxNDQuMjg1NzE0Mjg2Ii8+CiAgICA8L2c+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF81NCI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTgwLjM1NzEgMTIyLjE0MyIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6I2JmMDBiZjsiLz4KICAgIDxnIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiPgogICAgIDx1c2Ugc3R5bGU9ImZpbGw6IzAwMDBmZjtzdHJva2U6IzAwMDBmZjtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSI4MC4zNTcxNDI4NTcxIiB4bGluazpocmVmPSIjbWU1M2I3YmI2ZDIiIHk9IjEyMi4xNDI4NTcxNDMiLz4KICAgIDwvZz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzU1Ij4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMTAyLjUgMTIyLjE0MyIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6I2JmYmYwMDsiLz4KICAgIDxnIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiPgogICAgIDx1c2Ugc3R5bGU9ImZpbGw6I2ZmZmZmZjtzdHJva2U6IzAwMDBmZjtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxMDIuNSIgeGxpbms6aHJlZj0iI21lMjc4MDY0MmUyIiB5PSIxMjIuMTQyODU3MTQzIi8+CiAgICA8L2c+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF81NiI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTEwMi41IDEwMCIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDsiLz4KICAgIDxnIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiPgogICAgIDx1c2Ugc3R5bGU9ImZpbGw6IzAwMDBmZjtzdHJva2U6IzAwMDBmZjtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxMDIuNSIgeGxpbms6aHJlZj0iI21lNTNiN2JiNmQyIiB5PSIxMDAuMCIvPgogICAgPC9nPgogICA8L2c+CiAgIDxnIGlkPSJsaW5lMmRfNTciPgogICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0xMjQuNjQzIDEwMCIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDBmZjsiLz4KICAgIDxnIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiPgogICAgIDx1c2Ugc3R5bGU9ImZpbGw6I2ZmZmZmZjtzdHJva2U6IzAwMDBmZjtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxMjQuNjQyODU3MTQzIiB4bGluazpocmVmPSIjbWUyNzgwNjQyZTIiIHk9IjEwMC4wIi8+CiAgICA8L2c+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF81OCI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTEyNC42NDMgNzcuODU3MSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwODAwMDsiLz4KICAgIDxnIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiPgogICAgIDx1c2Ugc3R5bGU9ImZpbGw6IzAwMDBmZjtzdHJva2U6IzAwMDBmZjtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxMjQuNjQyODU3MTQzIiB4bGluazpocmVmPSIjbWU1M2I3YmI2ZDIiIHk9Ijc3Ljg1NzE0Mjg1NzEiLz4KICAgIDwvZz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzU5Ij4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMTQ2Ljc4NiA3Ny44NTcxIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojZmYwMDAwOyIvPgogICAgPGcgY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSI+CiAgICAgPHVzZSBzdHlsZT0iZmlsbDojZmZmZmZmO3N0cm9rZTojMDAwMGZmO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjE0Ni43ODU3MTQyODYiIHhsaW5rOmhyZWY9IiNtZTI3ODA2NDJlMiIgeT0iNzcuODU3MTQyODU3MSIvPgogICAgPC9nPgogICA8L2c+CiAgIDxnIGlkPSJsaW5lMmRfNjAiPgogICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0xNDYuNzg2IDU1LjcxNDMiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMGJmYmY7Ii8+CiAgICA8ZyBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIj4KICAgICA8dXNlIHN0eWxlPSJmaWxsOiMwMDAwZmY7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTQ2Ljc4NTcxNDI4NiIgeGxpbms6aHJlZj0iI21lNTNiN2JiNmQyIiB5PSI1NS43MTQyODU3MTQzIi8+CiAgICA8L2c+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF82MSI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTE2OC45MjkgNTUuNzE0MyIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6I2JmMDBiZjsiLz4KICAgIDxnIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiPgogICAgIDx1c2Ugc3R5bGU9ImZpbGw6I2ZmZmZmZjtzdHJva2U6IzAwMDBmZjtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxNjguOTI4NTcxNDI5IiB4bGluazpocmVmPSIjbWUyNzgwNjQyZTIiIHk9IjU1LjcxNDI4NTcxNDMiLz4KICAgIDwvZz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzYyIj4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMTY4LjkyOSAzMy41NzE0IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojYmZiZjAwOyIvPgogICAgPGcgY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSI+CiAgICAgPHVzZSBzdHlsZT0iZmlsbDojMDAwMGZmO3N0cm9rZTojMDAwMGZmO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjE2OC45Mjg1NzE0MjkiIHhsaW5rOmhyZWY9IiNtZTUzYjdiYjZkMiIgeT0iMzMuNTcxNDI4NTcxNCIvPgogICAgPC9nPgogICA8L2c+CiAgIDxnIGlkPSJwYXRjaF8zIj4KICAgIDxwYXRoIGQ9IiBNMjUgMjIuNSBMMTgwIDIyLjUiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwMDA7Ii8+CiAgIDwvZz4KICAgPGcgaWQ9InBhdGNoXzQiPgogICAgPHBhdGggZD0iIE0xODAgMTc3LjUgTDE4MCAyMi41IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwOyIvPgogICA8L2c+CiAgIDxnIGlkPSJwYXRjaF81Ij4KICAgIDxwYXRoIGQ9IiBNMjUgMTc3LjUgTDE4MCAxNzcuNSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDsiLz4KICAgPC9nPgogICA8ZyBpZD0icGF0Y2hfNiI+CiAgICA8cGF0aCBkPSIgTTI1IDE3Ny41IEwyNSAyMi41IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwOyIvPgogICA8L2c+CiAgPC9nPgogPC9nPgogPGRlZnM+CiAgPGNsaXBQYXRoIGlkPSJwNDBmZWMxMTUzZiI+CiAgIDxyZWN0IGhlaWdodD0iMTU1LjAiIHdpZHRoPSIxNTUuMCIgeD0iMjUuMCIgeT0iMjIuNSIvPgogIDwvY2xpcFBhdGg+CiA8L2RlZnM+Cjwvc3ZnPgo=" width="200" height="200"></div> <div class="t-plot-bottom">Argument</div> </div> <h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> The current <a href="../fenv/fe_round" title="c/numeric/fenv/FE round">rounding mode</a> has no effect. </li> +<li> If <code>arg</code> is ±∞, it is returned, unmodified </li> +<li> If <code>arg</code> is ±0, it is returned, unmodified </li> +<li> If arg is NaN, NaN is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p><code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> may be (but isn't required to be) raised when rounding a non-integer finite value.</p> +<p>The largest representable floating-point values are exact integers in all standard floating-point formats, so this function never overflows on its own; however the result may overflow any integer type (including <code><a href="../../types/integer" title="c/types/integer">intmax_t</a></code>), when stored in an integer variable.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <math.h> +#include <stdio.h> +int main(void) +{ + printf("floor(+2.7) = %+.1f\n", floor(2.7)); + printf("floor(-2.7) = %+.1f\n", floor(-2.7)); + printf("floor(-0.0) = %+.1f\n", floor(-0.0)); + printf("floor(-Inf) = %+f\n", floor(-INFINITY)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">floor(+2.7) = +2.0 +floor(-2.7) = -3.0 +floor(-0.0) = -0.0 +floor(-Inf) = -inf</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.9.2 The floor functions (p: 251) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.6.2 The floor functions (p: 526) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.9.2 The floor functions (p: 232) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.6.2 The floor functions (p: 463) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.6.3 The floor function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="ceil" title="c/numeric/math/ceil"> <span class="t-lines"><span>ceil</span><span>ceilf</span><span>ceill</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes smallest integer not less than the given value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="trunc" title="c/numeric/math/trunc"> <span class="t-lines"><span>trunc</span><span>truncf</span><span>truncl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> rounds to nearest integer not greater in magnitude than the given value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="round" title="c/numeric/math/round"> <span class="t-lines"><span>round</span><span>roundf</span><span>roundl</span><span>lround</span><span>lroundf</span><span>lroundl</span><span>llround</span><span>llroundf</span><span>llroundl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> rounds to nearest integer, rounding away from zero in halfway cases <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/floor" title="cpp/numeric/math/floor">C++ documentation</a></span> for <code>floor</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/floor" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/floor</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Ffma.html b/devdocs/c/numeric%2Fmath%2Ffma.html new file mode 100644 index 00000000..ce600c3f --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffma.html @@ -0,0 +1,94 @@ + <h1 id="firstHeading" class="firstHeading">fma, fmaf, fmal</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float fmaf( float x, float y, float z );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double fma( double x, double y, double z );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double fmal( long double x, long double y, long double z );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FP_FAST_FMA /* implementation-defined */</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FP_FAST_FMAF /* implementation-defined */</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FP_FAST_FMAL /* implementation-defined */</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define fma( x, y, z )</pre> +</td> <td> (7) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes <code>(x*y) + z</code> as if to infinite precision and rounded only once to fit the result type.</div> <div class="t-li1"> +<span class="t-li">4-6)</span> If the macro constants <code>FP_FAST_FMA</code>, <code>FP_FAST_FMAF</code>, or <code>FP_FAST_FMAL</code> are defined, the corresponding function <code>fmaf</code>, <code>fma</code>, or <code>fmal</code> evaluates faster (in addition to being more precise) than the expression <code>x*y+z</code> for <code>float</code>, <code>double</code>, and <code>long double</code> arguments, respectively. If defined, these macros evaluate to integer <code>1</code>.</div> <div class="t-li1"> +<span class="t-li">7)</span> Type-generic macro: If any argument has type <code>long double</code>, <code>fmal</code> is called. Otherwise, if any argument has integer type or has type <code>double</code>, <code>fma</code> is called. Otherwise, <code>fmaf</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> x, y, z </td> <td> - </td> <td> floating point values </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If successful, returns the value of <code>(x*y) + z</code> as if calculated to infinite precision and rounded once to fit the result type (or, alternatively, calculated as a single ternary floating-point operation).</p> +<p>If a range error due to overflow occurs, <code><a href="huge_val" title="c/numeric/math/HUGE VAL">±HUGE_VAL</a></code>, <code>±HUGE_VALF</code>, or <code>±HUGE_VALL</code> is returned.</p> +<p>If a range error due to underflow occurs, the correct value (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> If x is zero and y is infinite or if x is infinite and y is zero, and z is not a NaN, then NaN is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised </li> +<li> If x is zero and y is infinite or if x is infinite and y is zero, and z is a NaN, then NaN is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> may be raised </li> +<li> If <code>x*y</code> is an exact infinity and z is an infinity with the opposite sign, NaN is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised </li> +<li> If x or y are NaN, NaN is returned </li> +<li> If z is NaN, and <code>x*y</code> aren't 0*Inf or Inf*0, then NaN is returned (without <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code>). </li> +</ul> <h3 id="Notes"> Notes</h3> <p>This operation is commonly implemented in hardware as <a href="https://en.wikipedia.org/wiki/Multiply%E2%80%93accumulate_operation" class="extiw" title="enwiki:Multiply–accumulate operation">fused multiply-add</a> CPU instruction. If supported by hardware, the appropriate <code>FP_FAST_FMA*</code> macros are expected to be defined, but many implementations make use of the CPU instruction even when the macros are not defined.</p> +<p><a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/fma.html">POSIX specifies</a> that the situation where the value <code>x*y</code> is invalid and z is a NaN is a domain error.</p> +<p>Due to its infinite intermediate precision, <code>fma</code> is a common building block of other correctly-rounded mathematical operations, such as <code><a href="sqrt" title="c/numeric/math/sqrt">sqrt</a></code> or even the division (where not provided by the CPU, e.g. Itanium).</p> +<p>As with all floating-point expressions, the expression <code>(x*y) + z</code> may be compiled as a fused mutiply-add unless the <a href="../../preprocessor/impl" title="c/preprocessor/impl"><code> #pragma</code></a> <code>STDC FP_CONTRACT</code> is off.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> +#include <fenv.h> +#pragma STDC FENV_ACCESS ON +int main(void) +{ + // demo the difference between fma and built-in operators + double in = 0.1; + printf("0.1 double is %.23f (%a)\n", in, in); + printf("0.1*10 is 1.0000000000000000555112 (0x8.0000000000002p-3)," + " or 1.0 if rounded to double\n"); + double expr_result = 0.1 * 10 - 1; + printf("0.1 * 10 - 1 = %g : 1 subtracted after " + "intermediate rounding to 1.0\n", expr_result); + double fma_result = fma(0.1, 10, -1); + printf("fma(0.1, 10, -1) = %g (%a)\n", fma_result, fma_result); + + // fma use in double-double arithmetic + printf("\nin double-double arithmetic, 0.1 * 10 is representable as "); + double high = 0.1 * 10; + double low = fma(0.1, 10, -high); + printf("%g + %g\n\n", high, low); + + //error handling + feclearexcept(FE_ALL_EXCEPT); + printf("fma(+Inf, 10, -Inf) = %f\n", fma(INFINITY, 10, -INFINITY)); + if(fetestexcept(FE_INVALID)) puts(" FE_INVALID raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">0.1 double is 0.10000000000000000555112 (0x1.999999999999ap-4) +0.1*10 is 1.0000000000000000555112 (0x8.0000000000002p-3), or 1.0 if rounded to double +0.1 * 10 - 1 = 0 : 1 subtracted after intermediate rounding to 1.0 +fma(0.1, 10, -1) = 5.55112e-17 (0x1p-54) + +in double-double arithmetic, 0.1 * 10 is representable as 1 + 5.55112e-17 + +fma(+Inf, 10, -Inf) = -nan + FE_INVALID raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.13.1 The fma functions (p: 188-189) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.10.1 The fma functions (p: 386) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.13.1 The fma functions (p: 258) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.10.1 The fma functions (p: 530) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.13.1 The fma functions (p: 239) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.10.1 The fma functions (p: 466) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="remainder" title="c/numeric/math/remainder"> <span class="t-lines"><span>remainder</span><span>remainderf</span><span>remainderl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes signed remainder of the floating-point division operation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="remquo" title="c/numeric/math/remquo"> <span class="t-lines"><span>remquo</span><span>remquof</span><span>remquol</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes signed remainder as well as the three last bits of the division operation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/fma" title="cpp/numeric/math/fma">C++ documentation</a></span> for <code>fma</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/fma" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/fma</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Ffmax.html b/devdocs/c/numeric%2Fmath%2Ffmax.html new file mode 100644 index 00000000..899bbddd --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffmax.html @@ -0,0 +1,56 @@ + <h1 id="firstHeading" class="firstHeading">fmax, fmaxf, fmaxl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float fmaxf( float x, float y );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double fmax( double x, double y );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double fmaxl( long double x, long double y );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define fmax( x, y )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Returns the larger of two floating point arguments, treating NaNs as missing data (between a NaN and a numeric value, the numeric value is chosen).</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If any argument has type <code>long double</code>, <code>fmaxl</code> is called. Otherwise, if any argument has integer type or has type <code>double</code>, <code>fmax</code> is called. Otherwise, <code>fmaxf</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> x, y </td> <td> - </td> <td> floating point values </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If successful, returns the larger of two floating point values. The value returned is exact and does not depend on any rounding modes.</p> +<h3 id="Error_handling"> Error handling</h3> <p>This function is not subject to any of the error conditions specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> If one of the two arguments is NaN, the value of the other argument is returned. </li> +<li> Only if both arguments are NaN is NaN returned. </li> +</ul> <h3 id="Notes"> Notes</h3> <p>This function is not required to be sensitive to the sign of zero, although some implementations additionally enforce that if one argument is +0 and the other is -0, then +0 is returned.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> + +int main(void) +{ + printf("fmax(2,1) = %f\n", fmax(2,1)); + printf("fmax(-Inf,0) = %f\n", fmax(-INFINITY,0)); + printf("fmax(NaN,-1) = %f\n", fmax(NAN,-1)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">fmax(2,1) = 2.000000 +fmax(-Inf,0) = 0.000000 +fmax(NaN,-1) = -1.000000</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.12.2 The fmax functions (p: 188) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 397) </li> +<li> F.10.9.2 The fmax functions (p: 386) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.12.2 The fmax functions (p: 257-258) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.9.2 The fmax functions (p: 530) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.12.2 The fmax functions (p: 238-239) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.9.2 The fmax functions (p: 466) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="isgreater" title="c/numeric/math/isgreater"> <span class="t-lines"><span>isgreater</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the first floating-point argument is greater than the second <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fmin" title="c/numeric/math/fmin"> <span class="t-lines"><span>fmin</span><span>fminf</span><span>fminl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> determines smaller of two floating-point values <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/fmax" title="cpp/numeric/math/fmax">C++ documentation</a></span> for <code>fmax</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/fmax" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/fmax</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Ffmin.html b/devdocs/c/numeric%2Fmath%2Ffmin.html new file mode 100644 index 00000000..bec5d0b4 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffmin.html @@ -0,0 +1,50 @@ + <h1 id="firstHeading" class="firstHeading">fmin, fminf, fminl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float fminf( float x, float y );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double fmin( double x, double y );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double fminl( long double x, long double y );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define fmin( x, y )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Returns the smaller of two floating point arguments, treating NaNs as missing data (between a NaN and a numeric value, the numeric value is chosen).</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If any argument has type <code>long double</code>, <code>fminl</code> is called. Otherwise, if any argument has integer type or has type <code>double</code>, <code>fmin</code> is called. Otherwise, <code>fminf</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> x, y </td> <td> - </td> <td> floating point values </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If successful, returns the smaller of two floating point values. The value returned is exact and does not depend on any rounding modes.</p> +<h3 id="Error_handling"> Error handling</h3> <p>This function is not subject to any of the error conditions specified in <a href="math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> If one of the two arguments is NaN, the value of the other argument is returned </li> +<li> Only if both arguments are NaN, NaN is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p>This function is not required to be sensitive to the sign of zero, although some implementations additionally enforce that if one argument is +0 and the other is -0, then -0 is returned.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> + +int main(void) +{ + printf("fmin(2,1) = %f\n", fmin(2,1)); + printf("fmin(-Inf,0) = %f\n", fmin(-INFINITY,0)); + printf("fmin(NaN,-1) = %f\n", fmin(NAN,-1)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">fmin(2,1) = 1.000000 +fmin(-Inf,0) = -inf +fmin(NaN,-1) = -1.000000</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.12.3 The fmin functions (p: 258) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.9.3 The fmin functions (p: 530) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.12.3 The fmin functions (p: 239) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.9.3 The fmin functions (p: 466) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="isless" title="c/numeric/math/isless"> <span class="t-lines"><span>isless</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the first floating-point argument is less than the second <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fmax" title="c/numeric/math/fmax"> <span class="t-lines"><span>fmax</span><span>fmaxf</span><span>fmaxl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> determines larger of two floating-point values <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/fmin" title="cpp/numeric/math/fmin">C++ documentation</a></span> for <code>fmin</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/fmin" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/fmin</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Ffmod.html b/devdocs/c/numeric%2Fmath%2Ffmod.html new file mode 100644 index 00000000..e43577a0 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffmod.html @@ -0,0 +1,95 @@ + <h1 id="firstHeading" class="firstHeading">fmod, fmodf, fmodl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float fmodf( float x, float y );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double fmod( double x, double y );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double fmodl( long double x, long double y );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define fmod( x, y )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the floating-point remainder of the division operation <code>x/y</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If any argument has type <code>long double</code>, <code>fmodl</code> is called. Otherwise, if any argument has integer type or has type <code>double</code>, <code>fmod</code> is called. Otherwise, <code>fmodf</code> is called.</div> <p>The floating-point remainder of the division operation <code>x/y</code> calculated by this function is exactly the value <code>x - n*y</code>, where <code>n</code> is <code>x/y</code> with its fractional part truncated.</p> +<p>The returned value has the same sign as <code>x</code> and is less or equal to <code>y</code> in magnitude.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> x, y </td> <td> - </td> <td> floating point values </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If successful, returns the floating-point remainder of the division <code>x/y</code> as defined above.</p> +<p>If a domain error occurs, an implementation-defined value is returned (NaN where supported).</p> +<p>If a range error occurs due to underflow, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a>.</p> +<p>Domain error may occur if <code>y</code> is zero.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> If <code>x</code> is ±0 and <code>y</code> is not zero, ±0 is returned </li> +<li> If <code>x</code> is ±∞ and <code>y</code> is not NaN, NaN is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised </li> +<li> If <code>y</code> is ±0 and <code>x</code> is not NaN, NaN is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised </li> +<li> If <code>y</code> is ±∞ and <code>x</code> is finite, <code>x</code> is returned. </li> +<li> If either argument is NaN, NaN is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/fmod.html">POSIX requires</a> that a domain error occurs if <code>x</code> is infinite or <code>y</code> is zero.</p> +<p><code>fmod</code>, but not <code><a href="remainder" title="c/numeric/math/remainder">remainder</a></code> is useful for doing silent wrapping of floating-point types to unsigned integer types: <code><span class="br0">(</span><span class="nu16">0.0</span> <span class="sy1"><=</span> <span class="br0">(</span>y <span class="sy1">=</span> fmod<span class="br0">(</span><a href="http://en.cppreference.com/w/c/numeric/math/rint"><span class="kw692">rint</span></a><span class="br0">(</span>x<span class="br0">)</span>, <span class="nu16">65536.0</span> <span class="br0">)</span><span class="br0">)</span> <span class="sy4">?</span> y <span class="sy4">:</span> <span class="nu16">65536.0</span> <span class="sy2">+</span> y<span class="br0">)</span></code> is in the range <code>[-0.0 .. 65535.0]</code>, which corresponds to <code>unsigned short</code>, but <code><a href="http://en.cppreference.com/w/c/numeric/math/remainder"><span class="kw647">remainder</span></a><span class="br0">(</span><a href="http://en.cppreference.com/w/c/numeric/math/rint"><span class="kw692">rint</span></a><span class="br0">(</span>x<span class="br0">)</span>, <span class="nu16">65536.0</span><span class="br0">)</span></code> is in the range <code>[-32767.0, +32768.0]</code>, which is outside of the range of <code>signed short</code>.</p> +<p>The <code>double</code> version of <code>fmod</code> behaves as if implemented as follows:</p> +<div class="c source-c"><pre data-language="c">double fmod(double x, double y) +{ +#pragma STDC FENV_ACCESS ON + double result = remainder(fabs(x), (y = fabs(y))); + if (signbit(result)) result += y; + return copysign(result, x); +}</pre></div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <fenv.h> + +// #pragma STDC FENV_ACCESS ON +int main(void) +{ + printf("fmod(+5.1, +3.0) = %.1f\n", fmod(5.1,3)); + printf("fmod(-5.1, +3.0) = %.1f\n", fmod(-5.1,3)); + printf("fmod(+5.1, -3.0) = %.1f\n", fmod(5.1,-3)); + printf("fmod(-5.1, -3.0) = %.1f\n", fmod(-5.1,-3)); + + // special values + printf("fmod(+0.0, 1.0) = %.1f\n", fmod(0, 1)); + printf("fmod(-0.0, 1.0) = %.1f\n", fmod(-0.0, 1)); + printf("fmod(+5.1, Inf) = %.1f\n", fmod(5.1, INFINITY)); + + // error handling + feclearexcept(FE_ALL_EXCEPT); + printf("fmod(+5.1, 0) = %.1f\n", fmod(5.1, 0)); + if(fetestexcept(FE_INVALID)) puts(" FE_INVALID raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">fmod(+5.1, +3.0) = 2.1 +fmod(-5.1, +3.0) = -2.1 +fmod(+5.1, -3.0) = 2.1 +fmod(-5.1, -3.0) = -2.1 +fmod(+0.0, 1.0) = 0.0 +fmod(-0.0, 1.0) = -0.0 +fmod(+5.1, Inf) = 5.1 +fmod(+5.1, 0) = nan + FE_INVALID raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.10.1 The fmod functions (p: 185) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 274-275) </li> +<li> F.10.7.1 The fmod functions (p: 385) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.10.1 The fmod functions (p: 254) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.7.1 The fmod functions (p: 528) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.10.1 The fmod functions (p: 235) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.7.1 The fmod functions (p: 465) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.6.4 The fmod function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="div" title="c/numeric/math/div"> <span class="t-lines"><span>div</span><span>ldiv</span><span>lldiv</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes quotient and remainder of integer division <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="remainder" title="c/numeric/math/remainder"> <span class="t-lines"><span>remainder</span><span>remainderf</span><span>remainderl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes signed remainder of the floating-point division operation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="remquo" title="c/numeric/math/remquo"> <span class="t-lines"><span>remquo</span><span>remquof</span><span>remquol</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes signed remainder as well as the three last bits of the division operation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/fmod" title="cpp/numeric/math/fmod">C++ documentation</a></span> for <code>fmod</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/fmod" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/fmod</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Ffp_categories.html b/devdocs/c/numeric%2Fmath%2Ffp_categories.html new file mode 100644 index 00000000..520ed9eb --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffp_categories.html @@ -0,0 +1,54 @@ + <h1 id="firstHeading" class="firstHeading">FP_NORMAL, FP_SUBNORMAL, FP_ZERO, FP_INFINITE, FP_NAN</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FP_NORMAL /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FP_SUBNORMAL /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FP_ZERO /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FP_INFINITE /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FP_NAN /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>The <code>FP_NORMAL</code>, <code>FP_SUBNORMAL</code>, <code>FP_ZERO</code>, <code>FP_INFINITE</code>, <code>FP_NAN</code> macros each represent a distinct category of floating-point numbers. They all expand to an integer constant expression.</p> +<table class="t-dsc-begin"> <tr class="t-dsc-hitem"> <th> Constant </th> <th> Explanation </th> +</tr> <tr class="t-dsc"> <td> <code>FP_NORMAL</code> </td> <td> indicates that the value is <i>normal</i>, i.e. not an infinity, subnormal, not-a-number or zero </td> +</tr> <tr class="t-dsc"> <td> <code>FP_SUBNORMAL</code> </td> <td> indicates that the value is <a href="https://en.wikipedia.org/wiki/Subnormal_number" class="extiw" title="enwiki:Subnormal number"><i>subnormal</i></a> </td> +</tr> <tr class="t-dsc"> <td> <code>FP_ZERO</code> </td> <td> indicates that the value is positive or negative zero </td> +</tr> <tr class="t-dsc"> <td> <code>FP_INFINITE</code> </td> <td> indicates that the value is not representable by the underlying type (positive or negative infinity) </td> +</tr> <tr class="t-dsc"> <td> <code>FP_NAN</code> </td> <td> indicates that the value is not-a-number (NaN) </td> +</tr> </table> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> + +const char *show_classification(double x) { + switch(fpclassify(x)) { + case FP_INFINITE: return "Inf"; + case FP_NAN: return "NaN"; + case FP_NORMAL: return "normal"; + case FP_SUBNORMAL: return "subnormal"; + case FP_ZERO: return "zero"; + default: return "unknown"; + } +} +int main(void) +{ + printf("1.0/0.0 is %s\n", show_classification(1/0.0)); + printf("0.0/0.0 is %s\n", show_classification(0.0/0.0)); + printf("DBL_MIN/2 is %s\n", show_classification(DBL_MIN/2)); + printf("-0.0 is %s\n", show_classification(-0.0)); + printf(" 1.0 is %s\n", show_classification(1.0)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">1.0/0.0 is Inf +0.0/0.0 is NaN +DBL_MIN/2 is subnormal +-0.0 is zero + 1.0 is normal</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.12/6 FP_NORMAL, ... (p: 169-170) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.12/6 FP_NORMAL, ... (p: 232) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.12/6 FP_NORMAL, ... (p: 213) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fpclassify" title="c/numeric/math/fpclassify"> <span class="t-lines"><span>fpclassify</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> classifies the given floating-point value <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/FP_categories" title="cpp/numeric/math/FP categories">C++ documentation</a></span> for <code>FP_categories</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/FP_categories" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/FP_categories</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Ffpclassify.html b/devdocs/c/numeric%2Fmath%2Ffpclassify.html new file mode 100644 index 00000000..0014938b --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffpclassify.html @@ -0,0 +1,52 @@ + <h1 id="firstHeading" class="firstHeading">fpclassify</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define fpclassify(arg) /* implementation defined */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Categorizes floating point value <code>arg</code> into the following categories: zero, subnormal, normal, infinite, NAN, or implementation-defined category. The macro returns an integral value.</p> +<p><code><a href="../../types/limits/flt_eval_method" title="c/types/limits/FLT EVAL METHOD">FLT_EVAL_METHOD</a></code> is ignored: even if the argument is evaluated with more range and precision than its type, it is first converted to its semantic type, and the classification is based on that: a normal long double value might become subnormal when converted to double and zero when converted to float.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>One of <code><a href="fp_categories" title="c/numeric/math/FP categories">FP_INFINITE</a></code>, <code><a href="fp_categories" title="c/numeric/math/FP categories">FP_NAN</a></code>, <code><a href="fp_categories" title="c/numeric/math/FP categories">FP_NORMAL</a></code>, <code><a href="fp_categories" title="c/numeric/math/FP categories">FP_SUBNORMAL</a></code>, <code><a href="fp_categories" title="c/numeric/math/FP categories">FP_ZERO</a></code> or implementation-defined type, specifying the category of <code>arg</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> + +const char *show_classification(double x) { + switch(fpclassify(x)) { + case FP_INFINITE: return "Inf"; + case FP_NAN: return "NaN"; + case FP_NORMAL: return "normal"; + case FP_SUBNORMAL: return "subnormal"; + case FP_ZERO: return "zero"; + default: return "unknown"; + } +} +int main(void) +{ + printf("1.0/0.0 is %s\n", show_classification(1/0.0)); + printf("0.0/0.0 is %s\n", show_classification(0.0/0.0)); + printf("DBL_MIN/2 is %s\n", show_classification(DBL_MIN/2)); + printf("-0.0 is %s\n", show_classification(-0.0)); + printf("1.0 is %s\n", show_classification(1.0)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">1.0/0.0 is Inf +0.0/0.0 is NaN +DBL_MIN/2 is subnormal +-0.0 is zero +1.0 is normal</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.12.3.1 The fpclassify macro (p: 235) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.12.3.1 The fpclassify macro (p: 216) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="isfinite" title="c/numeric/math/isfinite"> <span class="t-lines"><span>isfinite</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number has finite value <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="isinf" title="c/numeric/math/isinf"> <span class="t-lines"><span>isinf</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number is infinite <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="isnan" title="c/numeric/math/isnan"> <span class="t-lines"><span>isnan</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number is NaN <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="isnormal" title="c/numeric/math/isnormal"> <span class="t-lines"><span>isnormal</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number is normal <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/fpclassify" title="cpp/numeric/math/fpclassify">C++ documentation</a></span> for <code>fpclassify</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/fpclassify" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/fpclassify</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Ffrexp.html b/devdocs/c/numeric%2Fmath%2Ffrexp.html new file mode 100644 index 00000000..60c85cff --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ffrexp.html @@ -0,0 +1,79 @@ + <h1 id="firstHeading" class="firstHeading">frexp, frexpf, frexpl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float frexpf( float arg, int* exp );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double frexp( double arg, int* exp );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double frexpl( long double arg, int* exp );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define frexp( arg, exp )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Decomposes given floating point value <code>x</code> into a normalized fraction and an integral power of two.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>arg</code> has type <code>long double</code>, <code>frexpl</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>frexp</code> is called. Otherwise, <code>frexpf</code> is called, respectively.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> <tr class="t-par"> <td> exp </td> <td> - </td> <td> pointer to integer value to store the exponent to </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If <code>arg</code> is zero, returns zero and stores zero in <code>*exp</code>.</p> +<p>Otherwise (if <code>arg</code> is not zero), if no errors occur, returns the value <code>x</code> in the range <code>(-1;-0.5], [0.5; 1)</code> and stores an integer value in <code><span class="sy2">*</span><a href="http://en.cppreference.com/w/c/numeric/math/exp"><span class="kw657">exp</span></a></code> such that x×2<sup class="t-su">(*exp)</sup>=arg.</p> +<p>If the value to be stored in <code>*exp</code> is outside the range of <code>int</code>, the behavior is unspecified.</p> +<p>If <code>arg</code> is not a floating-point number, the behavior is unspecified.</p> +<h3 id="Error_handling"> Error handling</h3> <p>This function is not subject to any errors specified in <a href="math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> If <code>arg</code> is ±0, it is returned, unmodified, and <code>0</code> is stored in <code><span class="sy2">*</span><a href="http://en.cppreference.com/w/c/numeric/math/exp"><span class="kw657">exp</span></a></code>. </li> +<li> If <code>arg</code> is ±∞, it is returned, and an unspecified value is stored in <code><span class="sy2">*</span><a href="http://en.cppreference.com/w/c/numeric/math/exp"><span class="kw657">exp</span></a></code>. </li> +<li> If <code>arg</code> is NaN, NaN is returned, and an unspecified value is stored in <code><span class="sy2">*</span><a href="http://en.cppreference.com/w/c/numeric/math/exp"><span class="kw657">exp</span></a></code>. </li> +<li> No floating-point exceptions are raised. </li> +<li> If <code><a href="../../types/limits" title="c/types/limits">FLT_RADIX</a></code> is 2 (or a power of 2), the returned value is exact, <a href="../fenv/fe_round" title="c/numeric/fenv/FE round">the current rounding mode</a> is ignored </li> +</ul> <h3 id="Notes"> Notes</h3> <p>On a binary system (where <code><a href="../../types/limits" title="c/types/limits">FLT_RADIX</a></code> is <code>2</code>), <code>frexp</code> may be implemented as</p> +<div class="c source-c"><pre data-language="c">{ + *exp = (value == 0) ? 0 : (int)(1 + logb(value)); + return scalbn(value, -(*exp)); +}</pre></div> <p>The function <code>frexp</code>, together with its dual, <code><a href="ldexp" title="c/numeric/math/ldexp">ldexp</a></code>, can be used to manipulate the representation of a floating-point number without direct bit manipulations.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> + +int main(void) +{ + double f = 123.45; + printf("Given the number %.2f or %a in hex,\n", f, f); + + double f3; + double f2 = modf(f, &f3); + printf("modf() makes %.0f + %.2f\n", f3, f2); + + int i; + f2 = frexp(f, &i); + printf("frexp() makes %f * 2^%d\n", f2, i); + + i = ilogb(f); + printf("logb()/ilogb() make %f * %d^%d\n", f/scalbn(1.0, i), FLT_RADIX, i); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Given the number 123.45 or 0x1.edccccccccccdp+6 in hex, +modf() makes 123 + 0.45 +frexp() makes 0.964453 * 2^7 +logb()/ilogb() make 1.92891 * 2^6</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.6.4 The frexp functions (p: 243) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.3.4 The frexp functions (p: 521) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.6.4 The frexp functions (p: 224) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.3.4 The frexp functions (p: 458) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.4.2 The frexp function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="ldexp" title="c/numeric/math/ldexp"> <span class="t-lines"><span>ldexp</span><span>ldexpf</span><span>ldexpl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> multiplies a number by <code>2</code> raised to a power <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="logb" title="c/numeric/math/logb"> <span class="t-lines"><span>logb</span><span>logbf</span><span>logbl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> extracts exponent of the given number <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ilogb" title="c/numeric/math/ilogb"> <span class="t-lines"><span>ilogb</span><span>ilogbf</span><span>ilogbl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> extracts exponent of the given number <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="modf" title="c/numeric/math/modf"> <span class="t-lines"><span>modf</span><span>modff</span><span>modfl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> breaks a number into integer and fractional parts <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/frexp" title="cpp/numeric/math/frexp">C++ documentation</a></span> for <code>frexp</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/frexp" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/frexp</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fhuge_val.html b/devdocs/c/numeric%2Fmath%2Fhuge_val.html new file mode 100644 index 00000000..d95e528b --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fhuge_val.html @@ -0,0 +1,52 @@ + <h1 id="firstHeading" class="firstHeading">HUGE_VALF, HUGE_VAL, HUGE_VALL</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define HUGE_VALF /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define HUGE_VAL /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define HUGE_VALL /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>The <code>HUGE_VALF</code>, <code>HUGE_VAL</code> and <code>HUGE_VALL</code> macros expand to positive floating point constant expressions which compare equal to the values returned by floating-point functions and operators in case of overflow (see <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>).</p> +<table class="t-dsc-begin"> <tr class="t-dsc-hitem"> <th> Constant </th> <th> Explanation </th> +</tr> <tr class="t-dsc"> <td> <code>HUGE_VALF</code> </td> <td> Expands to positive <code>float</code> expression that indicates overflow </td> +</tr> <tr class="t-dsc"> <td> <code>HUGE_VAL</code> </td> <td> Expands to positive <code>double</code> expression that indicates overflow, not necessarily representable as a <code>float</code> </td> +</tr> <tr class="t-dsc"> <td> <code>HUGE_VALL</code> </td> <td> Expands to positive <code>long double</code> expression that indicates overflow, not necessarily representable as a <code>float</code> or <code>double</code> </td> +</tr> </table> <p>On implementations that support floating-point infinities, these macros always expand to the positive infinities of <code>float</code>, <code>double</code>, and <code>long double</code>, respectively.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <math.h> +#include <stdio.h> + +int main(void) +{ + const double result = 1.0 / 0.0; + printf("1.0/0.0 == %f\n", result); + if (result == HUGE_VAL) + puts("1.0/0.0 == HUGE_VAL"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">1.0/0.0 == inf +1.0/0.0 == HUGE_VAL</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.12/3 HUGE_VAL, HUGE_VALF, HUGE_VALL (p: TBD) </li> +<li> F.10/2 HUGE_VAL, HUGE_VALF, HUGE_VALL (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12/3 HUGE_VAL, HUGE_VALF, HUGE_VALL (p: TBD) </li> +<li> F.10/2 HUGE_VAL, HUGE_VALF, HUGE_VALL (p: TBD) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12/3 HUGE_VAL, HUGE_VALF, HUGE_VALL (p: 231) </li> +<li> F.10/2 HUGE_VAL, HUGE_VALF, HUGE_VALL (p: 517) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12/3 HUGE_VAL, HUGE_VALF, HUGE_VALL (p: 212) </li> +<li> F.9/2 HUGE_VAL, HUGE_VALF, HUGE_VALL (p: 454) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5 HUGE_VAL </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="infinity" title="c/numeric/math/INFINITY"> <span class="t-lines"><span>INFINITY</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> evaluates to positive infinity or the value guaranteed to overflow a <code>float</code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/HUGE_VAL" title="cpp/numeric/math/HUGE VAL">C++ documentation</a></span> for <code>HUGE_VAL</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/HUGE_VAL" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/HUGE_VAL</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fhypot.html b/devdocs/c/numeric%2Fmath%2Fhypot.html new file mode 100644 index 00000000..bd94e763 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fhypot.html @@ -0,0 +1,81 @@ + <h1 id="firstHeading" class="firstHeading">hypot, hypotf, hypotl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float hypotf( float x, float y );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double hypot( double x, double y );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double hypotl( long double x, long double y );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define hypot( x, y )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the square root of the sum of the squares of <code>x</code> and <code>y</code>, without undue overflow or underflow at intermediate stages of the computation.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If any argument has type <code>long double</code>, the long double version of the function is called. Otherwise, if any argument has integer type or has type <code>double</code>, the double version of the function is called. Otherwise, the <code>float</code> version of the function is called.</div> <p>The value computed by this function is the length of the hypotenuse of a right-angled triangle with sides of length <code>x</code> and <code>y</code>, or the distance of the point <code>(x,y)</code> from the origin <code>(0,0)</code>, or the magnitude of a complex number <code>x+<i>i</i>y</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> x </td> <td> - </td> <td> floating point value </td> +</tr> <tr class="t-par"> <td> y </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the hypotenuse of a right-angled triangle, \(\scriptsize{\sqrt{x^2+y^2} }\)<span class="t-mrad"><span>√</span><span>x<sup class="t-su">2</sup>+y<sup class="t-su">2</sup></span></span>, is returned.</p> +<p>If a range error due to overflow occurs, <code><a href="huge_val" title="c/numeric/math/HUGE VAL">+HUGE_VAL</a></code>, <code>+HUGE_VALF</code>, or <code>+HUGE_VALL</code> is returned.</p> +<p>If a range error due to underflow occurs, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> <code>hypot(x, y)</code>, <code>hypot(y, x)</code>, and <code>hypot(x, -y)</code> are equivalent </li> +<li> if one of the arguments is ±0, <code>hypot</code> is equivalent to <code><a href="http://en.cppreference.com/w/c/numeric/math/fabs"><span class="kw644">fabs</span></a></code> called with the non-zero argument </li> +<li> if one of the arguments is ±∞, <code>hypot</code> returns +∞ even if the other argument is NaN </li> +<li> otherwise, if any of the arguments is NaN, NaN is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p>Implementations usually guarantee precision of less than 1 ulp (<a href="https://en.wikipedia.org/wiki/Unit_in_the_last_place" class="extiw" title="enwiki:Unit in the last place">units in the last place</a>): <a rel="nofollow" class="external text" href="http://sourceware.org/git/?p=glibc.git;a=blob_plain;f=sysdeps/ieee754/dbl-64/e_hypot.c">GNU</a>, <a rel="nofollow" class="external text" href="http://www.freebsd.org/cgi/cvsweb.cgi/src/lib/msun/src/e_hypot.c">BSD</a>.</p> +<p><code>hypot(x, y)</code> is equivalent to <code><a href="http://en.cppreference.com/w/c/numeric/complex/cabs"><span class="kw765">cabs</span></a><span class="br0">(</span>x <span class="sy2">+</span> I<span class="sy2">*</span>y<span class="br0">)</span></code>.</p> +<p><a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/hypot.html">POSIX specifies</a> that underflow may only occur when both arguments are subnormal and the correct result is also subnormal (this forbids naive implementations).</p> +<p><code>hypot(INFINITY, NAN)</code> returns +∞, but <code><a href="http://en.cppreference.com/w/c/numeric/math/sqrt"><span class="kw665">sqrt</span></a><span class="br0">(</span>INFINITY<span class="sy2">*</span>INFINITY<span class="sy2">+</span>NAN<span class="sy2">*</span>NAN<span class="br0">)</span></code> returns NaN.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <errno.h> +#include <fenv.h> +#include <float.h> + +// #pragma STDC FENV_ACCESS ON +int main(void) +{ + // typical usage + printf("(1,1) cartesian is (%f,%f) polar\n", hypot(1,1), atan2(1,1)); + // special values + printf("hypot(NAN,INFINITY) = %f\n", hypot(NAN,INFINITY)); + // error handling + errno = 0; feclearexcept(FE_ALL_EXCEPT); + printf("hypot(DBL_MAX,DBL_MAX) = %f\n", hypot(DBL_MAX,DBL_MAX)); + if(errno == ERANGE) perror(" errno == ERANGE"); + if(fetestexcept(FE_OVERFLOW)) puts(" FE_OVERFLOW raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">(1,1) cartesian is (1.414214,0.785398) polar +hypot(NAN,INFINITY) = inf +hypot(DBL_MAX,DBL_MAX) = inf + errno == ERANGE: Numerical result out of range + FE_OVERFLOW raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.7.3 The hypot functions (p: 181) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.4.3 The hypot functions (p: 382) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.7.3 The hypot functions (p: 248) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.4.3 The hypot functions (p: 524) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.7.3 The hypot functions (p: 229) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.4.3 The hypot functions (p: 461) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="pow" title="c/numeric/math/pow"> <span class="t-lines"><span>pow</span><span>powf</span><span>powl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes a number raised to the given power (\(\small{x^y}\)x<sup>y</sup>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="sqrt" title="c/numeric/math/sqrt"> <span class="t-lines"><span>sqrt</span><span>sqrtf</span><span>sqrtl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes square root (\(\small{\sqrt{x} }\)<span class="t-mrad"><span>√</span><span>x</span></span>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="cbrt" title="c/numeric/math/cbrt"> <span class="t-lines"><span>cbrt</span><span>cbrtf</span><span>cbrtl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes cube root (\(\small{\sqrt[3]{x} }\)<span class="t-mrad"><span>3</span><span>√</span><span>x</span></span>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../complex/cabs" title="c/numeric/complex/cabs"> <span class="t-lines"><span>cabs</span><span>cabsf</span><span>cabsl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the magnitude of a complex number <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/hypot" title="cpp/numeric/math/hypot">C++ documentation</a></span> for <code>hypot</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/hypot" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/hypot</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Filogb.html b/devdocs/c/numeric%2Fmath%2Filogb.html new file mode 100644 index 00000000..75847df0 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Filogb.html @@ -0,0 +1,91 @@ + <h1 id="firstHeading" class="firstHeading">ilogb, ilogbf, ilogbl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int ilogbf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int ilogb( double arg );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int ilogbl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define ilogb( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FP_ILOGB0 /*implementation-defined*/</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FP_ILOGBNAN /*implementation-defined*/</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Extracts the value of the unbiased exponent from the floating-point argument <code>arg</code>, and returns it as a signed integer value. </div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macros: If <code>arg</code> has type <code>long double</code>, <code>ilogbl</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>ilogb</code> is called. Otherwise, <code>ilogbf</code> is called.</div> <div class="t-li1"> +<span class="t-li">5)</span> Expands to integer constant expression whose value is either <code><a href="../../types/limits" title="c/types/limits">INT_MIN</a></code> or <code><span class="sy2">-</span><a href="http://en.cppreference.com/w/c/types/limits"><span class="kw364">INT_MAX</span></a></code>.</div> <div class="t-li1"> +<span class="t-li">6)</span> Expands to integer constant expression whose value is either <code><a href="../../types/limits" title="c/types/limits">INT_MIN</a></code> or <code><span class="sy2">+</span><a href="http://en.cppreference.com/w/c/types/limits"><span class="kw364">INT_MAX</span></a></code>.</div> <p>Formally, the unbiased exponent is the integral part of log<sub class="t-su t-su-b">r</sub>|arg| as a signed integral value, for non-zero arg, where <code>r</code> is <code><a href="../../types/limits" title="c/types/limits">FLT_RADIX</a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the unbiased exponent of <code>arg</code> is returned as a signed int value.</p> +<p>If <code>arg</code> is zero, <code>FP_ILOGB0</code> is returned.</p> +<p>If <code>arg</code> is infinite, <code><a href="../../types/limits" title="c/types/limits">INT_MAX</a></code> is returned.</p> +<p>If <code>arg</code> is a NaN, <code>FP_ILOGBNAN</code> is returned.</p> +<p>If the correct result is greater than <code><a href="../../types/limits" title="c/types/limits">INT_MAX</a></code> or smaller than <code><a href="../../types/limits" title="c/types/limits">INT_MIN</a></code>, the return value is unspecified and a domain error or range error may occur</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a>.</p> +<p>A domain error or range error may occur if <code>arg</code> is zero, infinite, or NaN.</p> +<p>If the correct result is greater than <code><a href="../../types/limits" title="c/types/limits">INT_MAX</a></code> or smaller than <code><a href="../../types/limits" title="c/types/limits">INT_MIN</a></code>, a domain error or a range error may occur</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> If the correct result is greater than <code><a href="../../types/limits" title="c/types/limits">INT_MAX</a></code> or smaller than <code><a href="../../types/limits" title="c/types/limits">INT_MIN</a></code>, <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised. </li> +<li> If <code>arg</code> is ±0, ±∞, or NaN, <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised. </li> +<li> In all other cases, the result is exact (<code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> is never raised) and <a href="../fenv/fe_round" title="c/numeric/fenv/FE round">the current rounding mode</a> is ignored </li> +</ul> <h3 id="Notes"> Notes</h3> <p>If <code>arg</code> is not zero, infinite, or NaN, the value returned is exactly equivalent to <code><span class="br0">(</span><span class="kw4">int</span><span class="br0">)</span><a href="http://en.cppreference.com/w/c/numeric/math/logb"><span class="kw663">logb</span></a><span class="br0">(</span>arg<span class="br0">)</span></code>.</p> +<p><a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/ilogb.html">POSIX requires</a> that a domain error occurs if <code>arg</code> is zero, infinite, NaN, or if the correct result is outside of the range of <code>int</code>.</p> +<p>POSIX also requires that, on XSI-conformant systems, the value returned when the correct result is greater than <code><a href="../../types/limits" title="c/types/limits">INT_MAX</a></code> is <code><a href="../../types/limits" title="c/types/limits">INT_MAX</a></code> and the value returned when the correct result is less than <code><a href="../../types/limits" title="c/types/limits">INT_MIN</a></code> is <code><a href="../../types/limits" title="c/types/limits">INT_MIN</a></code>.</p> +<p>The correct result can be represented as <code>int</code> on all known implementations. For overflow to occur, <code><a href="../../types/limits" title="c/types/limits">INT_MAX</a></code> must be less than <code><a href="http://en.cppreference.com/w/c/types/limits"><span class="kw397">LDBL_MAX_EXP</span></a><span class="sy2">*</span>log2<span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/limits"><span class="kw372">FLT_RADIX</span></a><span class="br0">)</span></code> or <code><a href="../../types/limits" title="c/types/limits">INT_MIN</a></code> must be greater than <code>LDBL_MIN_EXP<span class="sy2">-</span><a href="http://en.cppreference.com/w/c/types/limits"><span class="kw388">LDBL_MANT_DIG</span></a><span class="br0">)</span><span class="sy2">*</span>log2<span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/limits"><span class="kw372">FLT_RADIX</span></a><span class="br0">)</span></code>.</p> +<p>The value of the exponent returned by <code>ilogb</code> is always 1 less than the exponent retuned by <code><a href="frexp" title="c/numeric/math/frexp">frexp</a></code> because of the different normalization requirements: for the exponent <code>e</code> returned by <code>ilogb</code>, |arg*r<sup class="t-su">-e</sup>| is between 1 and <code>r</code> (typically between <code>1</code> and <code>2</code>), but for the exponent <code>e</code> returned by <code><a href="frexp" title="c/numeric/math/frexp">frexp</a></code>, |arg*2<sup class="t-su">-e</sup>| is between <code>0.5</code> and <code>1</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> +#include <fenv.h> + +#pragma STDC FENV_ACCESS ON +int main(void) +{ + double f = 123.45; + printf("Given the number %.2f or %a in hex,\n", f, f); + + double f3; + double f2 = modf(f, &f3); + printf("modf() makes %.0f + %.2f\n", f3, f2); + + int i; + f2 = frexp(f, &i); + printf("frexp() makes %f * 2^%d\n", f2, i); + + i = ilogb(f); + printf("logb()/ilogb() make %f * %d^%d\n", f/scalbn(1.0, i), FLT_RADIX, i); + + // error handling + feclearexcept(FE_ALL_EXCEPT); + printf("ilogb(0) = %d\n", ilogb(0)); + if(fetestexcept(FE_INVALID)) puts(" FE_INVALID raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Given the number 123.45 or 0x1.edccccccccccdp+6 in hex, +modf() makes 123 + 0.45 +frexp() makes 0.964453 * 2^7 +logb()/ilogb() make 1.92891 * 2^6 +ilogb(0) = -2147483648 + FE_INVALID raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12/8 Mathematics <math.h> (p: 232) </li> +<li> 7.12.6.5 The ilogb functions (p: 244) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.3.5 The ilogb functions (p: 521) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12/8 Mathematics <math.h> (p: 213) </li> +<li> 7.12.6.5 The ilogb functions (p: 224-225) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.3.5 The ilogb functions (p: 458) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="frexp" title="c/numeric/math/frexp"> <span class="t-lines"><span>frexp</span><span>frexpf</span><span>frexpl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> breaks a number into significand and a power of <code>2</code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="logb" title="c/numeric/math/logb"> <span class="t-lines"><span>logb</span><span>logbf</span><span>logbl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> extracts exponent of the given number <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="scalbn" title="c/numeric/math/scalbn"> <span class="t-lines"><span>scalbn</span><span>scalbnf</span><span>scalbnl</span><span>scalbln</span><span>scalblnf</span><span>scalblnl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes efficiently a number times <code><a href="../../types/limits" title="c/types/limits">FLT_RADIX</a></code> raised to a power <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/ilogb" title="cpp/numeric/math/ilogb">C++ documentation</a></span> for <code>ilogb</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/ilogb" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/ilogb</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Finfinity.html b/devdocs/c/numeric%2Fmath%2Finfinity.html new file mode 100644 index 00000000..e9559f1f --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Finfinity.html @@ -0,0 +1,33 @@ + <h1 id="firstHeading" class="firstHeading">INFINITY</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define INFINITY /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>If the implementation supports floating-point infinities, the macro <code>INFINITY</code> expands to constant expression of type <code>float</code> which evaluates to positive or unsigned infinity.</p> +<p>If the implementation does not support floating-point infinities, the macro <code>INFINITY</code> expands to a positive value that is guaranteed to overflow a <code>float</code> at compile time, and the use of this macro generates a compiler warning.</p> +<p>The style used to print an infinity is implementation defined.</p> +<h3 id="Example"> Example</h3> <p>Show style used to print an infinity and IEEE format.</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <stdint.h> +#include <inttypes.h> +#include <string.h> + +int main(void) +{ + double f = INFINITY; + uint64_t fn; memcpy(&fn, &f, sizeof f); + printf("INFINITY: %f %" PRIx64 "\n", f, fn); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">INFINITY: inf 7ff0000000000000</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.12/4 INFINITY (p: 231-232) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.12/4 INFINITY (p: 212-213) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="isinf" title="c/numeric/math/isinf"> <span class="t-lines"><span>isinf</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number is infinite <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="huge_val" title="c/numeric/math/HUGE VAL"> <span class="t-lines"><span>HUGE_VALF</span><span>HUGE_VAL</span><span>HUGE_VALL</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> indicates value too big to be representable (infinity) by <code>float</code>, <code>double</code> and <code>long double</code> respectively <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/INFINITY" title="cpp/numeric/math/INFINITY">C++ documentation</a></span> for <code>INFINITY</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/INFINITY" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/INFINITY</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fisfinite.html b/devdocs/c/numeric%2Fmath%2Fisfinite.html new file mode 100644 index 00000000..f700b213 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fisfinite.html @@ -0,0 +1,44 @@ + <h1 id="firstHeading" class="firstHeading">isfinite</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define isfinite(arg) /* implementation defined */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Determines if the given floating point number <code>arg</code> has finite value i.e. it is normal, subnormal or zero, but not infinite or NaN. The macro returns an integral value.</p> +<p><code><a href="../../types/limits/flt_eval_method" title="c/types/limits/FLT EVAL METHOD">FLT_EVAL_METHOD</a></code> is ignored: even if the argument is evaluated with more range and precision than its type, it is first converted to its semantic type, and the classification is based on that.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Nonzero integral value if <code>arg</code> has finite value, <code>0</code> otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> + +int main(void) +{ + printf("isfinite(NAN) = %d\n", isfinite(NAN)); + printf("isfinite(INFINITY) = %d\n", isfinite(INFINITY)); + printf("isfinite(0.0) = %d\n", isfinite(0.0)); + printf("isfinite(DBL_MIN/2.0) = %d\n", isfinite(DBL_MIN/2.0)); + printf("isfinite(1.0) = %d\n", isfinite(1.0)); + printf("isfinite(exp(800)) = %d\n", isfinite(exp(800))); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">isfinite(NAN) = 0 +isfinite(INFINITY) = 0 +isfinite(0.0) = 1 +isfinite(DBL_MIN/2.0) = 1 +isfinite(1.0) = 1 +isfinite(exp(800)) = 0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.12.3.2 The isfinite macro (p: 236) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.12.3.2 The isfinite macro (p: 216-217) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fpclassify" title="c/numeric/math/fpclassify"> <span class="t-lines"><span>fpclassify</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> classifies the given floating-point value <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="isinf" title="c/numeric/math/isinf"> <span class="t-lines"><span>isinf</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number is infinite <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="isnan" title="c/numeric/math/isnan"> <span class="t-lines"><span>isnan</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number is NaN <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="isnormal" title="c/numeric/math/isnormal"> <span class="t-lines"><span>isnormal</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number is normal <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/isfinite" title="cpp/numeric/math/isfinite">C++ documentation</a></span> for <code>isfinite</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/isfinite" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/isfinite</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fisgreater.html b/devdocs/c/numeric%2Fmath%2Fisgreater.html new file mode 100644 index 00000000..51bca156 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fisgreater.html @@ -0,0 +1,44 @@ + <h1 id="firstHeading" class="firstHeading">isgreater</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define isgreater(x, y) /* implementation defined */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Determines if the floating point number <code>x</code> is greater than the floating-point number (<code>y</code>), without setting floating-point exceptions.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> x </td> <td> - </td> <td> floating point value </td> +</tr> <tr class="t-par"> <td> y </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Nonzero integral value if <code>x > y</code>, <code>0</code> otherwise.</p> +<h3 id="Notes"> Notes</h3> <p>The built-in <code>operator></code> for floating-point numbers may set <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> if one or both of the arguments is NaN. This function is a "quiet" version of <code>operator></code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> + +int main(void) +{ + printf("isgreater(2.0,1.0) = %d\n", isgreater(2.0,1.0)); + printf("isgreater(1.0,2.0) = %d\n", isgreater(1.0,2.0)); + printf("isgreater(INFINITY,1.0) = %d\n", isgreater(INFINITY,1.0)); + printf("isgreater(1.0,NAN) = %d\n", isgreater(1.0,NAN)); + + return 0; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">isgreater(2.0,1.0) = 1 +isgreater(1.0,2.0) = 0 +isgreater(INFINITY,1.0) = 1 +isgreater(1.0,NAN) = 0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.14.1 The isgreater macro (p: 189) </li> +<li> F.10.11 Comparison macros (p: 386-387) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.14.1 The isgreater macro (p: 259) </li> +<li> F.10.11 Comparison macros (p: 531) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.12.14.1 The isgreater macro (p: 240) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="isless" title="c/numeric/math/isless"> <span class="t-lines"><span>isless</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the first floating-point argument is less than the second <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/isgreater" title="cpp/numeric/math/isgreater">C++ documentation</a></span> for <code>isgreater</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/isgreater" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/isgreater</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fisgreaterequal.html b/devdocs/c/numeric%2Fmath%2Fisgreaterequal.html new file mode 100644 index 00000000..d9c44c9c --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fisgreaterequal.html @@ -0,0 +1,41 @@ + <h1 id="firstHeading" class="firstHeading">isgreaterequal</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define isgreaterequal(x, y) /* implementation defined */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Determines if the floating point number <code>x</code> is greater than or equal to the floating-point number <code>y</code>, without setting floating-point exceptions.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> x </td> <td> - </td> <td> floating point value </td> +</tr> <tr class="t-par"> <td> y </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Nonzero integral value if <code>x >= y</code>, <code>0</code> otherwise.</p> +<h3 id="Notes"> Notes</h3> <p>The built-in <code>operator>=</code> for floating-point numbers may raise <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> if one or both of the arguments is NaN. This function is a "quiet" version of <code>operator>=</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> + +int main(void) +{ + printf("isgreaterequal(2.0,1.0) = %d\n", isgreaterequal(2.0,1.0)); + printf("isgreaterequal(1.0,2.0) = %d\n", isgreaterequal(1.0,2.0)); + printf("isgreaterequal(1.0,1.0) = %d\n", isgreaterequal(1.0,1.0)); + printf("isgreaterequal(INFINITY,1.0) = %d\n", isgreaterequal(INFINITY,1.0)); + printf("isgreaterequal(1.0,NAN) = %d\n", isgreaterequal(1.0,NAN)); + + return 0; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">isgreaterequal(2.0,1.0) = 1 +isgreaterequal(1.0,2.0) = 0 +isgreaterequal(1.0,1.0) = 1 +isgreaterequal(INFINITY,1.0) = 1 +isgreaterequal(1.0,NAN) = 0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.14.2 The isgreaterequal macro (p: 259-260) </li> +<li> F.10.11 Comparison macros (p: 531) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.12.14.2 The isgreaterequal macro (p: 240-241) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="islessequal" title="c/numeric/math/islessequal"> <span class="t-lines"><span>islessequal</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the first floating-point argument is less or equal than the second <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/isgreaterequal" title="cpp/numeric/math/isgreaterequal">C++ documentation</a></span> for <code>isgreaterequal</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/isgreaterequal" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/isgreaterequal</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fisinf.html b/devdocs/c/numeric%2Fmath%2Fisinf.html new file mode 100644 index 00000000..57713b0e --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fisinf.html @@ -0,0 +1,46 @@ + <h1 id="firstHeading" class="firstHeading">isinf</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define isinf(arg) /* implementation defined */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Determines if the given floating-point number <code>arg</code> is positive or negative infinity. The macro returns an integral value.</p> +<p><code><a href="../../types/limits/flt_eval_method" title="c/types/limits/FLT EVAL METHOD">FLT_EVAL_METHOD</a></code> is ignored: even if the argument is evaluated with more range and precision than its type, it is first converted to its semantic type, and the classification is based on that.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating-point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Nonzero integral value if <code>arg</code> has an infinite value, <code>0</code> otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> + +int main(void) +{ + printf("isinf(NAN) = %d\n", isinf(NAN)); + printf("isinf(INFINITY) = %d\n", isinf(INFINITY)); + printf("isinf(0.0) = %d\n", isinf(0.0)); + printf("isinf(DBL_MIN/2.0) = %d\n", isinf(DBL_MIN/2.0)); + printf("isinf(1.0) = %d\n", isinf(1.0)); + printf("isinf(exp(800)) = %d\n", isinf(exp(800))); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">isinf(NAN) = 0 +isinf(INFINITY) = 1 +isinf(0.0) = 0 +isinf(DBL_MIN/2.0) = 0 +isinf(1.0) = 0 +isinf(exp(800)) = 1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.12.3.3 The isinf macro (p: 172) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.12.3.3 The isinf macro (p: 236) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.12.3.3 The isinf macro (p: 217) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fpclassify" title="c/numeric/math/fpclassify"> <span class="t-lines"><span>fpclassify</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> classifies the given floating-point value <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="isfinite" title="c/numeric/math/isfinite"> <span class="t-lines"><span>isfinite</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number has finite value <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="isnan" title="c/numeric/math/isnan"> <span class="t-lines"><span>isnan</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number is NaN <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="isnormal" title="c/numeric/math/isnormal"> <span class="t-lines"><span>isnormal</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number is normal <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/isinf" title="cpp/numeric/math/isinf">C++ documentation</a></span> for <code>isinf</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/isinf" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/isinf</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fisless.html b/devdocs/c/numeric%2Fmath%2Fisless.html new file mode 100644 index 00000000..8da4a04d --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fisless.html @@ -0,0 +1,39 @@ + <h1 id="firstHeading" class="firstHeading">isless</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define isless(x, y) /* implementation defined */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Determines if the floating point number <code>x</code> is less than the floating-point number <code>y</code>, without setting floating-point exceptions.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> x </td> <td> - </td> <td> floating point value </td> +</tr> <tr class="t-par"> <td> y </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Nonzero integral value if <code>x < y</code>, <code>0</code> otherwise.</p> +<h3 id="Notes"> Notes</h3> <p>The built-in <code>operator<</code> for floating-point numbers may raise <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> if one or both of the arguments is NaN. This function is a "quiet" version of <code>operator<</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> + +int main(void) +{ + printf("isless(2.0,1.0) = %d\n", isless(2.0,1.0)); + printf("isless(1.0,2.0) = %d\n", isless(1.0,2.0)); + printf("isless(INFINITY,1.0) = %d\n", isless(INFINITY,1.0)); + printf("isless(1.0,NAN) = %d\n", isless(1.0,NAN)); + + return 0; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">isless(2.0,1.0) = 0 +isless(1.0,2.0) = 1 +isless(INFINITY,1.0) = 0 +isless(1.0,NAN) = 0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.14.3 The isless macro (p: 260) </li> +<li> F.10.11 Comparison macros (p: 531) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.12.14.3 The isless macro (p: 241) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="isgreater" title="c/numeric/math/isgreater"> <span class="t-lines"><span>isgreater</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the first floating-point argument is greater than the second <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/isless" title="cpp/numeric/math/isless">C++ documentation</a></span> for <code>isless</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/isless" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/isless</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fislessequal.html b/devdocs/c/numeric%2Fmath%2Fislessequal.html new file mode 100644 index 00000000..588f3473 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fislessequal.html @@ -0,0 +1,41 @@ + <h1 id="firstHeading" class="firstHeading">islessequal</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define islessequal(x, y) /* implementation defined */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Determines if the floating point number <code>x</code> is less than or equal to the floating-point number <code>y</code>, without setting floating-point exceptions.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> x </td> <td> - </td> <td> floating point value </td> +</tr> <tr class="t-par"> <td> y </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Nonzero integral value if <code>x <= y</code>, <code>0</code> otherwise.</p> +<h3 id="Notes"> Notes</h3> <p>The built-in <code>operator<=</code> for floating-point numbers may raise <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> if one or both of the arguments is NaN. This function is a "quiet" version of <code>operator<=</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> + +int main(void) +{ + printf("islessequal(2.0,1.0) = %d\n", islessequal(2.0,1.0)); + printf("islessequal(1.0,2.0) = %d\n", islessequal(1.0,2.0)); + printf("islessequal(1.0,1.0) = %d\n", islessequal(1.0,1.0)); + printf("islessequal(INFINITY,1.0) = %d\n", islessequal(INFINITY,1.0)); + printf("islessequal(1.0,NAN) = %d\n", islessequal(1.0,NAN)); + + return 0; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">islessequal(2.0,1.0) = 0 +islessequal(1.0,2.0) = 1 +islessequal(1.0,1.0) = 1 +islessequal(INFINITY,1.0) = 0 +islessequal(1.0,NAN) = 0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.14.4 The islessequal macro (p: 260) </li> +<li> F.10.11 Comparison macros (p: 531) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.12.14.4 The islessequal macro (p: 241) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="isgreaterequal" title="c/numeric/math/isgreaterequal"> <span class="t-lines"><span>isgreaterequal</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the first floating-point argument is greater or equal than the second <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/islessequal" title="cpp/numeric/math/islessequal">C++ documentation</a></span> for <code>islessequal</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/islessequal" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/islessequal</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fislessgreater.html b/devdocs/c/numeric%2Fmath%2Fislessgreater.html new file mode 100644 index 00000000..a508962c --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fislessgreater.html @@ -0,0 +1,43 @@ + <h1 id="firstHeading" class="firstHeading">islessgreater</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define islessgreater(x, y) /* implementation defined */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Determines if the floating point number <code>x</code> is less than or greater than the floating-point number <code>y</code>, without setting floating-point exceptions.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> x </td> <td> - </td> <td> floating point value </td> +</tr> <tr class="t-par"> <td> y </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Nonzero integral value if <code>x < y || x > y</code>, <code>0</code> otherwise.</p> +<h3 id="Notes"> Notes</h3> <p>The built-in <code>operator<</code> and <code>operator></code> for floating-point numbers may raise <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> if one or both of the arguments is NaN. This function is a "quiet" version of the expression <code>x < y || x > y</code>. The macro does not evaluate x and y twice.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> + +int main(void) +{ + printf("islessgreater(2.0,1.0) = %d\n", islessgreater(2.0,1.0)); + printf("islessgreater(1.0,2.0) = %d\n", islessgreater(1.0,2.0)); + printf("islessgreater(1.0,1.0) = %d\n", islessgreater(1.0,1.0)); + printf("islessgreater(INFINITY,1.0) = %d\n", islessgreater(INFINITY,1.0)); + printf("islessgreater(1.0,NAN) = %d\n", islessgreater(1.0,NAN)); + + return 0; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">islessgreater(2.0,1.0) = 1 +islessgreater(1.0,2.0) = 1 +islessgreater(1.0,1.0) = 0 +islessgreater(INFINITY,1.0) = 1 +islessgreater(1.0,NAN) = 0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.14.5 The islessgreater macro (p: 261) </li> +<li> F.10.11 Comparison macros (p: 531) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.12.14.5 The islessgreater macro (p: 241-242) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="isless" title="c/numeric/math/isless"> <span class="t-lines"><span>isless</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the first floating-point argument is less than the second <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="isgreater" title="c/numeric/math/isgreater"> <span class="t-lines"><span>isgreater</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the first floating-point argument is greater than the second <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/islessgreater" title="cpp/numeric/math/islessgreater">C++ documentation</a></span> for <code>islessgreater</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/islessgreater" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/islessgreater</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fisnan.html b/devdocs/c/numeric%2Fmath%2Fisnan.html new file mode 100644 index 00000000..f9b432de --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fisnan.html @@ -0,0 +1,51 @@ + <h1 id="firstHeading" class="firstHeading">isnan</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define isnan(arg) /* implementation defined */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Determines if the given floating point number <code>arg</code> is a not-a-number (NaN) value. The macro returns an integral value.</p> +<p><code><a href="../../types/limits/flt_eval_method" title="c/types/limits/FLT EVAL METHOD">FLT_EVAL_METHOD</a></code> is ignored: even if the argument is evaluated with more range and precision than its type, it is first converted to its semantic type, and the classification is based on that (this matters if the evaluation type supports NaNs, while the semantic type does not).</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Nonzero integral value if <code>arg</code> is a NaN, <code>0</code> otherwise.</p> +<h3 id="Notes"> Notes</h3> <p>There are many different NaN values with different sign bits and payloads, see <code><a href="nan" title="c/numeric/math/nan">nan</a></code>.</p> +<p>NaN values never compare equal to themselves or to other NaN values. Copying a NaN may change its bit pattern.</p> +<p>Another way to test if a floating-point value is NaN is to compare it with itself: <code>bool is_nan(double x) { return x != x; }</code></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> + +int main(void) +{ + printf("isnan(NAN) = %d\n", isnan(NAN)); + printf("isnan(INFINITY) = %d\n", isnan(INFINITY)); + printf("isnan(0.0) = %d\n", isnan(0.0)); + printf("isnan(DBL_MIN/2.0) = %d\n", isnan(DBL_MIN/2.0)); + printf("isnan(0.0 / 0.0) = %d\n", isnan(0.0/0.0)); + printf("isnan(Inf - Inf) = %d\n", isnan(INFINITY - INFINITY)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">isnan(NAN) = 1 +isnan(INFINITY) = 0 +isnan(0.0) = 0 +isnan(DBL_MIN/2.0) = 0 +isnan(0.0 / 0.0) = 1 +isnan(Inf - Inf) = 1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.12.3.4 The isnan macro (p: 236-237) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.12.3.4 The isnan macro (p: 217) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="nan" title="c/numeric/math/nan"> <span class="t-lines"><span>nan</span><span>nanf</span><span>nanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> returns a NaN (not-a-number) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fpclassify" title="c/numeric/math/fpclassify"> <span class="t-lines"><span>fpclassify</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> classifies the given floating-point value <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="isfinite" title="c/numeric/math/isfinite"> <span class="t-lines"><span>isfinite</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number has finite value <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="isinf" title="c/numeric/math/isinf"> <span class="t-lines"><span>isinf</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number is infinite <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="isnormal" title="c/numeric/math/isnormal"> <span class="t-lines"><span>isnormal</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number is normal <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="isunordered" title="c/numeric/math/isunordered"> <span class="t-lines"><span>isunordered</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if two floating-point values are unordered <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/isnan" title="cpp/numeric/math/isnan">C++ documentation</a></span> for <code>isnan</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/isnan" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/isnan</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fisnormal.html b/devdocs/c/numeric%2Fmath%2Fisnormal.html new file mode 100644 index 00000000..0a2a19cd --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fisnormal.html @@ -0,0 +1,42 @@ + <h1 id="firstHeading" class="firstHeading">isnormal</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define isnormal(arg) /* implementation defined */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Determines if the given floating point number <code>arg</code> is normal, i.e. is neither zero, subnormal, infinite, nor <code>NaN</code>. The macro returns an integral value.</p> +<p><code><a href="../../types/limits/flt_eval_method" title="c/types/limits/FLT EVAL METHOD">FLT_EVAL_METHOD</a></code> is ignored: even if the argument is evaluated with more range and precision than its type, it is first converted to its semantic type, and the classification is based on that.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Nonzero integral value if <code>arg</code> is normal, <code>0</code> otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> + +int main(void) +{ + printf("isnormal(NAN) = %d\n", isnormal(NAN)); + printf("isnormal(INFINITY) = %d\n", isnormal(INFINITY)); + printf("isnormal(0.0) = %d\n", isnormal(0.0)); + printf("isnormal(DBL_MIN/2.0) = %d\n", isnormal(DBL_MIN/2.0)); + printf("isnormal(1.0) = %d\n", isnormal(1.0)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">isnormal(NAN) = 0 +isnormal(INFINITY) = 0 +isnormal(0.0) = 0 +isnormal(DBL_MIN/2.0) = 0 +isnormal(1.0) = 1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.12.3.5 The isnormal macro (p: 237) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.12.3.5 The isnormal macro (p: 217-218) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fpclassify" title="c/numeric/math/fpclassify"> <span class="t-lines"><span>fpclassify</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> classifies the given floating-point value <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="isfinite" title="c/numeric/math/isfinite"> <span class="t-lines"><span>isfinite</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number has finite value <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="isinf" title="c/numeric/math/isinf"> <span class="t-lines"><span>isinf</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number is infinite <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="isnan" title="c/numeric/math/isnan"> <span class="t-lines"><span>isnan</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number is NaN <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/isnormal" title="cpp/numeric/math/isnormal">C++ documentation</a></span> for <code>isnormal</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/isnormal" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/isnormal</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fisunordered.html b/devdocs/c/numeric%2Fmath%2Fisunordered.html new file mode 100644 index 00000000..5341387f --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fisunordered.html @@ -0,0 +1,40 @@ + <h1 id="firstHeading" class="firstHeading">isunordered</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define isunordered(x, y) /* implementation defined */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Determines if the floating point numbers <code>x</code> and <code>y</code> are unordered, that is, one or both are NaN and thus cannot be meaningfully compared with each other.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> x </td> <td> - </td> <td> floating point value </td> +</tr> <tr class="t-par"> <td> y </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Nonzero integral value if either <code>x</code> or <code>y</code> is NaN, <code>0</code> otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> + +int main(void) +{ + printf("isunordered(NAN,1.0) = %d\n", isunordered(NAN,1.0)); + printf("isunordered(1.0,NAN) = %d\n", isunordered(1.0,NAN)); + printf("isunordered(NAN,NAN) = %d\n", isunordered(NAN,NAN)); + printf("isunordered(1.0,0.0) = %d\n", isunordered(1.0,0.0)); + + return 0; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">isunordered(NAN,1.0) = 1 +isunordered(1.0,NAN) = 1 +isunordered(NAN,NAN) = 1 +isunordered(1.0,0.0) = 0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.14.6 The isunordered macro (p: 261) </li> +<li> F.10.11 Comparison macros (p: 531) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.12.14.6 The isunordered macro (p: 242) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fpclassify" title="c/numeric/math/fpclassify"> <span class="t-lines"><span>fpclassify</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> classifies the given floating-point value <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="isnan" title="c/numeric/math/isnan"> <span class="t-lines"><span>isnan</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number is NaN <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/isunordered" title="cpp/numeric/math/isunordered">C++ documentation</a></span> for <code>isunordered</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/isunordered" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/isunordered</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fldexp.html b/devdocs/c/numeric%2Fmath%2Fldexp.html new file mode 100644 index 00000000..b2e09059 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fldexp.html @@ -0,0 +1,79 @@ + <h1 id="firstHeading" class="firstHeading">ldexp, ldexpf, ldexpl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float ldexpf( float arg, int exp );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double ldexp( double arg, int exp );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double ldexpl( long double arg, int exp );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define ldexp( arg, exp )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Multiplies a floating point value <code>arg</code> by the number 2 raised to the <code>exp</code> power.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>arg</code> has type <code>long double</code>, <code>ldexpl</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>ldexp</code> is called. Otherwise, <code>ldexpf</code> is called, respectively.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> <tr class="t-par"> <td> exp </td> <td> - </td> <td> integer value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, <code>arg</code> multiplied by 2 to the power of <code>exp</code> (arg×2<sup class="t-su">exp</sup>) is returned.</p> +<p>If a range error due to overflow occurs, <code><a href="huge_val" title="c/numeric/math/HUGE VAL">±HUGE_VAL</a></code>, <code>±HUGE_VALF</code>, or <code>±HUGE_VALL</code> is returned.</p> +<p>If a range error due to underflow occurs, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> Unless a range error occurs, <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> is never raised (the result is exact) </li> +<li> Unless a range error occurs, the <a href="../fenv/fe_round" title="c/numeric/fenv/FE round">current rounding mode</a> is ignored </li> +<li> If <code>arg</code> is ±0, it is returned, unmodified </li> +<li> If <code>arg</code> is ±∞, it is returned, unmodified </li> +<li> If <code>exp</code> is 0, then <code>arg</code> is returned, unmodified </li> +<li> If <code>arg</code> is NaN, NaN is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p>On binary systems (where <code><a href="../../types/limits" title="c/types/limits">FLT_RADIX</a></code> is <code>2</code>), <code>ldexp</code> is equivalent to <code><a href="scalbn" title="c/numeric/math/scalbn">scalbn</a></code>.</p> +<p>The function <code>ldexp</code> ("load exponent"), together with its dual, <code><a href="frexp" title="c/numeric/math/frexp">frexp</a></code>, can be used to manipulate the representation of a floating-point number without direct bit manipulations.</p> +<p>On many implementations, <code>ldexp</code> is less efficient than multiplication or division by a power of two using arithmetic operators.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> +#include <errno.h> +#include <fenv.h> +#pragma STDC FENV_ACCESS ON +int main(void) +{ + printf("ldexp(7, -4) = %f\n", ldexp(7, -4)); + printf("ldexp(1, -1074) = %g (minimum positive subnormal double)\n", + ldexp(1, -1074)); + printf("ldexp(nextafter(1,0), 1024) = %g (largest finite double)\n", + ldexp(nextafter(1,0), 1024)); + // special values + printf("ldexp(-0, 10) = %f\n", ldexp(-0.0, 10)); + printf("ldexp(-Inf, -1) = %f\n", ldexp(-INFINITY, -1)); + //error handling + errno = 0; feclearexcept(FE_ALL_EXCEPT); + printf("ldexp(1, 1024) = %f\n", ldexp(1, 1024)); + if(errno == ERANGE) perror(" errno == ERANGE"); + if(fetestexcept(FE_OVERFLOW)) puts(" FE_OVERFLOW raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">ldexp(7, -4) = 0.437500 +ldexp(1, -1074) = 4.94066e-324 (minimum positive subnormal double) +ldexp(nextafter(1,0), 1024) = 1.79769e+308 (largest finite double) +ldexp(-0, 10) = -0.000000 +ldexp(-Inf, -1) = -inf +ldexp(1, 1024) = inf + errno == ERANGE: Numerical result out of range + FE_OVERFLOW raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.6.6 The ldexp functions (p: 244) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.3.6 The ldexp functions (p: 522) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.6.6 The ldexp functions (p: 225) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.3.6 The ldexp functions (p: 459) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.4.3 The ldexp function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="frexp" title="c/numeric/math/frexp"> <span class="t-lines"><span>frexp</span><span>frexpf</span><span>frexpl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> breaks a number into significand and a power of <code>2</code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="scalbn" title="c/numeric/math/scalbn"> <span class="t-lines"><span>scalbn</span><span>scalbnf</span><span>scalbnl</span><span>scalbln</span><span>scalblnf</span><span>scalblnl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes efficiently a number times <code><a href="../../types/limits" title="c/types/limits">FLT_RADIX</a></code> raised to a power <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/ldexp" title="cpp/numeric/math/ldexp">C++ documentation</a></span> for <code>ldexp</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/ldexp" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/ldexp</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Flgamma.html b/devdocs/c/numeric%2Fmath%2Flgamma.html new file mode 100644 index 00000000..5dbfcbd3 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Flgamma.html @@ -0,0 +1,85 @@ + <h1 id="firstHeading" class="firstHeading">lgamma, lgammaf, lgammal</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float lgammaf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double lgamma( double arg );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double lgammal( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define lgamma( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the natural logarithm of the absolute value of the <a href="https://en.wikipedia.org/wiki/Gamma_function" class="extiw" title="enwiki:Gamma function">gamma function</a> of <code>arg</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>arg</code> has type <code>long double</code>, <code>lgammal</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>lgamma</code> is called. Otherwise, <code>lgammaf</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the value of the logarithm of the gamma function of <code>arg</code>, that is \(\log_{e}|{\int_0^\infty t^{arg-1} e^{-t} \mathsf{d}t}|\)log<sub class="t-su t-su-b">e</sub>|∫<sub class="t-su t-su-b">∞0</sub><i>t</i><sup class="t-su">arg-1</sup> <i>e</i><sup>-t</sup> d<i>t</i>|, is returned.</p> +<p>If a pole error occurs, <code><a href="huge_val" title="c/numeric/math/HUGE VAL">+HUGE_VAL</a></code>, <code>+HUGE_VALF</code>, or <code>+HUGE_VALL</code> is returned.</p> +<p>If a range error due to overflow occurs, <code><a href="huge_val" title="c/numeric/math/HUGE VAL">±HUGE_VAL</a></code>, <code>±HUGE_VALF</code>, or <code>±HUGE_VALL</code> is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If <code>arg</code> is zero or is an integer less than zero, a pole error may occur.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> If the argument is 1, +0 is returned. </li> +<li> If the argument is 2, +0 is returned. </li> +<li> If the argument is ±0, +∞ is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_DIVBYZERO</a></code> is raised. </li> +<li> If the argument is a negative integer, +∞ is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_DIVBYZERO</a></code> is raised. </li> +<li> If the argument is ±∞, +∞ is returned. </li> +<li> If the argument is NaN, NaN is returned. </li> +</ul> <h3 id="Notes"> Notes</h3> <p>If <code>arg</code> is a natural number, <code>lgamma(arg)</code> is the logarithm of the factorial of <code>arg - 1</code>.</p> +<p>The <a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/lgamma.html">POSIX version of <code>lgamma</code></a> is not thread-safe: each execution of the function stores the sign of the gamma function of <code>arg</code> in the static external variable <code>signgam</code>. Some implementations provide <code>lgamma_r</code>, which takes a pointer to user-provided storage for singgam as the second parameter, and is thread-safe.</p> +<p>There is a non-standard function named <code>gamma</code> in various implementations, but its definition is inconsistent. For example, glibc and 4.2BSD version of <code>gamma</code> executes <code>lgamma</code>, but 4.4BSD version of <code>gamma</code> executes <code>tgamma</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> +#include <errno.h> +#include <fenv.h> +// #pragma STDC FENV_ACCESS ON + +int main(void) +{ + printf("lgamma(10) = %f, log(9!) = %f\n", lgamma(10), log(2*3*4*5*6*7*8*9)); + const double pi = acos(-1); + printf("lgamma(0.5) = %f, log(sqrt(pi)) = %f\n", log(sqrt(pi)), lgamma(0.5)); + // special values + printf("lgamma(1) = %f\n", lgamma(1)); + printf("lgamma(+Inf) = %f\n", lgamma(INFINITY)); + + // error handling + errno = 0; feclearexcept(FE_ALL_EXCEPT); + printf("lgamma(0) = %f\n", lgamma(0)); + if (errno == ERANGE) + perror(" errno == ERANGE"); + if (fetestexcept(FE_DIVBYZERO)) + puts(" FE_DIVBYZERO raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">lgamma(10) = 12.801827, log(9!) = 12.801827 +lgamma(0.5) = 0.572365, log(sqrt(pi)) = 0.572365 +lgamma(1) = 0.000000 +lgamma(+Inf) = inf +lgamma(0) = inf + errno == ERANGE: Numerical result out of range + FE_DIVBYZERO raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.8.3 The lgamma functions (p: 182) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.5.3 The lgamma functions (p: 383) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.8.3 The lgamma functions (p: 250) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.5.3 The lgamma functions (p: 525) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.8.3 The lgamma functions (p: 231) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.5.3 The lgamma functions (p: 462) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="tgamma" title="c/numeric/math/tgamma"> <span class="t-lines"><span>tgamma</span><span>tgammaf</span><span>tgammal</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes gamma function <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/lgamma" title="cpp/numeric/math/lgamma">C++ documentation</a></span> for <code>lgamma</code> </td> +</tr> </table> <h3 id="External_links"> External links</h3> <table> <tr> <td> +<a rel="nofollow" class="external text" href="https://mathworld.wolfram.com/LogGammaFunction.html">Weisstein, Eric W. "Log Gamma Function."</a> From MathWorld — A Wolfram Web Resource. </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/lgamma" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/lgamma</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Flog.html b/devdocs/c/numeric%2Fmath%2Flog.html new file mode 100644 index 00000000..297dca2b --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Flog.html @@ -0,0 +1,84 @@ + <h1 id="firstHeading" class="firstHeading">log, logf, logl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float logf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double log( double arg );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double logl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define log( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the natural (base <i>e</i>) logarithm of <code>arg</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>arg</code> has type <code>long double</code>, <code>logl</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>log</code> is called. Otherwise, <code>logf</code> is called. If <code>arg</code> is complex or imaginary, then the macro invokes the corresponding complex function (<code><a href="http://en.cppreference.com/w/c/numeric/complex/clog"><span class="kw772">clogf</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/clog"><span class="kw771">clog</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/clog"><span class="kw773">clogl</span></a></code>).</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the natural (base-<i>e</i>) logarithm of <code>arg</code> (ln(arg) or log<sub class="t-su t-su-b">e</sub>(arg)) is returned.</p> +<p>If a domain error occurs, an implementation-defined value is returned (NaN where supported).</p> +<p>If a pole error occurs, <code><a href="huge_val" title="c/numeric/math/HUGE VAL">-HUGE_VAL</a></code>, <code>-HUGE_VALF</code>, or <code>-HUGE_VALL</code> is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>Domain error occurs if <code>arg</code> is less than zero.</p> +<p>Pole error may occur if <code>arg</code> is zero.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> If the argument is ±0, -∞ is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_DIVBYZERO</a></code> is raised. </li> +<li> If the argument is 1, +0 is returned </li> +<li> If the argument is negative, NaN is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised. </li> +<li> If the argument is +∞, +∞ is returned </li> +<li> If the argument is NaN, NaN is returned </li> +</ul> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> +#include <errno.h> +#include <fenv.h> +// #pragma STDC FENV_ACCESS ON +int main(void) +{ + printf("log(1) = %f\n", log(1)); + printf("base-5 logarithm of 125 = %f\n", log(125)/log(5)); + // special values + printf("log(1) = %f\n", log(1)); + printf("log(+Inf) = %f\n", log(INFINITY)); + //error handling + errno = 0; feclearexcept(FE_ALL_EXCEPT); + printf("log(0) = %f\n", log(0)); + if(errno == ERANGE) perror(" errno == ERANGE"); + if(fetestexcept(FE_DIVBYZERO)) puts(" FE_DIVBYZERO raised"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">log(1) = 0.000000 +base-5 logarithm of 125 = 3.000000 +log(1) = 0.000000 +log(+Inf) = inf +log(0) = -inf + errno == ERANGE: Numerical result out of range + FE_DIVBYZERO raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.6.7 The log functions (p: 178-179) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.3.7 The log functions (p: 380) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.6.7 The log functions (p: 244-245) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.3.7 The log functions (p: 522) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.6.7 The log functions (p: 225) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.3.7 The log functions (p: 459) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.4.4 The log function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="log10" title="c/numeric/math/log10"> <span class="t-lines"><span>log10</span><span>log10f</span><span>log10l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes common (base-<i>10</i>) logarithm (\({\small \log_{10}{x} }\)log<sub>10</sub>(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="log2" title="c/numeric/math/log2"> <span class="t-lines"><span>log2</span><span>log2f</span><span>log2l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes base-2 logarithm (\({\small \log_{2}{x} }\)log<sub>2</sub>(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="log1p" title="c/numeric/math/log1p"> <span class="t-lines"><span>log1p</span><span>log1pf</span><span>log1pl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes natural (base-<i>e</i>) logarithm of 1 plus the given number (\({\small \ln{(1+x)} }\)ln(1+x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="exp" title="c/numeric/math/exp"> <span class="t-lines"><span>exp</span><span>expf</span><span>expl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes <i>e</i> raised to the given power (\({\small e^x}\)e<sup>x</sup>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../complex/clog" title="c/numeric/complex/clog"> <span class="t-lines"><span>clog</span><span>clogf</span><span>clogl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex natural logarithm <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/log" title="cpp/numeric/math/log">C++ documentation</a></span> for <code>log</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/log" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/log</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Flog10.html b/devdocs/c/numeric%2Fmath%2Flog10.html new file mode 100644 index 00000000..5f9bfc00 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Flog10.html @@ -0,0 +1,83 @@ + <h1 id="firstHeading" class="firstHeading">log10, log10f, log10l</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float log10f( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double log10( double arg );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double log10l( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define log10( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the common (base-<i>10</i>) logarithm of <code>arg</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>arg</code> has type <code>long double</code>, <code>log10l</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>log10</code> is called. Otherwise, <code>log10f</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the common (base-<i>10</i>) logarithm of <code>arg</code> (log<sub class="t-su t-su-b">10</sub>(arg) or lg(arg)) is returned.</p> +<p>If a domain error occurs, an implementation-defined value is returned (NaN where supported).</p> +<p>If a pole error occurs, <code><a href="huge_val" title="c/numeric/math/HUGE VAL">-HUGE_VAL</a></code>, <code>-HUGE_VALF</code>, or <code>-HUGE_VALL</code> is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>Domain error occurs if <code>arg</code> is less than zero.</p> +<p>Pole error may occur if <code>arg</code> is zero.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> If the argument is ±0, -∞ is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_DIVBYZERO</a></code> is raised. </li> +<li> If the argument is 1, +0 is returned </li> +<li> If the argument is negative, NaN is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised. </li> +<li> If the argument is +∞, +∞ is returned </li> +<li> If the argument is NaN, NaN is returned </li> +</ul> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> +#include <errno.h> +#include <fenv.h> + +// #pragma STDC FENV_ACCESS ON +int main(void) +{ + printf("log10(1000) = %f\n", log10(1000)); + printf("log10(0.001) = %f\n", log10(0.001)); + printf("base-5 logarithm of 125 = %f\n", log10(125)/log10(5)); + // special values + printf("log10(1) = %f\n", log10(1)); + printf("log10(+Inf) = %f\n", log10(INFINITY)); + //error handling + errno = 0; feclearexcept(FE_ALL_EXCEPT); + printf("log10(0) = %f\n", log10(0)); + if(errno == ERANGE) perror(" errno == ERANGE"); + if(fetestexcept(FE_DIVBYZERO)) puts(" FE_DIVBYZERO raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">log10(1000) = 3.000000 +log10(0.001) = -3.000000 +base-5 logarithm of 125 = 3.000000 +log10(1) = 0.000000 +log10(+Inf) = inf +log10(0) = -inf + errno == ERANGE: Numerical result out of range + FE_DIVBYZERO raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.6.8 The log10 functions (p: 179) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.3.8 The log10 functions (p: 380) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.6.8 The log10 functions (p: 245) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.3.8 The log10 functions (p: 522) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.6.8 The log10 functions (p: 225-226) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.3.8 The log10 functions (p: 459) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.4.5 The log10 function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="log" title="c/numeric/math/log"> <span class="t-lines"><span>log</span><span>logf</span><span>logl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes natural (base-<i>e</i>) logarithm (\({\small \ln{x} }\)ln(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="log2" title="c/numeric/math/log2"> <span class="t-lines"><span>log2</span><span>log2f</span><span>log2l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes base-2 logarithm (\({\small \log_{2}{x} }\)log<sub>2</sub>(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="log1p" title="c/numeric/math/log1p"> <span class="t-lines"><span>log1p</span><span>log1pf</span><span>log1pl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes natural (base-<i>e</i>) logarithm of 1 plus the given number (\({\small \ln{(1+x)} }\)ln(1+x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/log10" title="cpp/numeric/math/log10">C++ documentation</a></span> for <code>log10</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/log10" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/log10</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Flog1p.html b/devdocs/c/numeric%2Fmath%2Flog1p.html new file mode 100644 index 00000000..792b8a08 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Flog1p.html @@ -0,0 +1,82 @@ + <h1 id="firstHeading" class="firstHeading">log1p, log1pf, log1pl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float log1pf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double log1p( double arg );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double log1pl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define log1p( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the natural (base <code>e</code>) logarithm of <code>1+arg</code>. This function is more precise than the expression <code><a href="http://en.cppreference.com/w/c/numeric/math/log"><span class="kw660">log</span></a><span class="br0">(</span><span class="nu0">1</span><span class="sy2">+</span>arg<span class="br0">)</span></code> if <code>arg</code> is close to zero.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>arg</code> has type <code>long double</code>, <code>log1pl</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>log1p</code> is called. Otherwise, <code>log1pf</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur ln(1+arg) is returned.</p> +<p>If a domain error occurs, an implementation-defined value is returned (NaN where supported).</p> +<p>If a pole error occurs, <code>-HUGE_VAL</code>, <code>-HUGE_VALF</code>, or <code>-HUGE_VALL</code> is returned.</p> +<p>If a range error occurs due to underflow, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a>.</p> +<p>Domain error occurs if <code>arg</code> is less than -1.</p> +<p>Pole error may occur if <code>arg</code> is -1.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> If the argument is ±0, it is returned unmodified </li> +<li> If the argument is -1, -∞ is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_DIVBYZERO</a></code> is raised. </li> +<li> If the argument is less than -1, NaN is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised. </li> +<li> If the argument is +∞, +∞ is returned </li> +<li> If the argument is NaN, NaN is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p>The functions <code><a href="expm1" title="c/numeric/math/expm1">expm1</a></code> and <code>log1p</code> are useful for financial calculations, for example, when calculating small daily interest rates: (1+x)<sup class="t-su">n</sup>-1 can be expressed as <code><a href="http://en.cppreference.com/w/c/numeric/math/expm1"><span class="kw659">expm1</span></a><span class="br0">(</span>n <span class="sy2">*</span> log1p<span class="br0">(</span>x<span class="br0">)</span><span class="br0">)</span></code>. These functions also simplify writing accurate inverse hyperbolic functions.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> +#include <errno.h> +#include <fenv.h> +#pragma STDC FENV_ACCESS ON +int main(void) +{ + printf("log1p(0) = %f\n", log1p(0)); + printf("Interest earned in 2 days on $100, compounded daily at 1%%\n" + " on a 30/360 calendar = %f\n", + 100*expm1(2*log1p(0.01/360))); + printf("log(1+1e-16) = %g, but log1p(1e-16) = %g\n", + log(1+1e-16), log1p(1e-16)); + // special values + printf("log1p(-0) = %f\n", log1p(-0.0)); + printf("log1p(+Inf) = %f\n", log1p(INFINITY)); + //error handling + errno = 0; feclearexcept(FE_ALL_EXCEPT); + printf("log1p(-1) = %f\n", log1p(-1)); + if(errno == ERANGE) perror(" errno == ERANGE"); + if(fetestexcept(FE_DIVBYZERO)) puts(" FE_DIVBYZERO raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">log1p(0) = 0.000000 +Interest earned in 2 days on $100, compounded daily at 1% + on a 30/360 calendar = 0.005556 +log(1+1e-16) = 0, but log1p(1e-16) = 1e-16 +log1p(-0) = -0.000000 +log1p(+Inf) = Inf +log1p(-1) = -Inf + errno == ERANGE: Result too large + FE_DIVBYZERO raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.6.9 The log1p functions (p: 245) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.3.9 The log1p functions (p: 522) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.6.9 The log1p functions (p: 226) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.3.9 The log1p functions (p: 459) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="log" title="c/numeric/math/log"> <span class="t-lines"><span>log</span><span>logf</span><span>logl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes natural (base-<i>e</i>) logarithm (\({\small \ln{x} }\)ln(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="log10" title="c/numeric/math/log10"> <span class="t-lines"><span>log10</span><span>log10f</span><span>log10l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes common (base-<i>10</i>) logarithm (\({\small \log_{10}{x} }\)log<sub>10</sub>(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="log2" title="c/numeric/math/log2"> <span class="t-lines"><span>log2</span><span>log2f</span><span>log2l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes base-2 logarithm (\({\small \log_{2}{x} }\)log<sub>2</sub>(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="expm1" title="c/numeric/math/expm1"> <span class="t-lines"><span>expm1</span><span>expm1f</span><span>expm1l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes <i>e</i> raised to the given power, minus one (\({\small e^x-1}\)e<sup>x</sup>-1) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/log1p" title="cpp/numeric/math/log1p">C++ documentation</a></span> for <code>log1p</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/log1p" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/log1p</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Flog2.html b/devdocs/c/numeric%2Fmath%2Flog2.html new file mode 100644 index 00000000..14c569b3 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Flog2.html @@ -0,0 +1,85 @@ + <h1 id="firstHeading" class="firstHeading">log2, log2f, log2l</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float log2f( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double log2( double arg );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double log2l( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define log2( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the base <code>2</code> logarithm of <code>arg</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>arg</code> has type <code>long double</code>, <code>log2l</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>log2</code> is called. Otherwise, <code>log2f</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the base-<i>2</i> logarithm of <code>arg</code> (log<sub class="t-su t-su-b">2</sub>(arg) or lb(arg)) is returned.</p> +<p>If a domain error occurs, an implementation-defined value is returned (NaN where supported).</p> +<p>If a pole error occurs, <code><a href="huge_val" title="c/numeric/math/HUGE VAL">-HUGE_VAL</a></code>, <code>-HUGE_VALF</code>, or <code>-HUGE_VALL</code> is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>Domain error occurs if <code>arg</code> is less than zero.</p> +<p>Pole error may occur if <code>arg</code> is zero.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> If the argument is ±0, -∞ is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_DIVBYZERO</a></code> is raised. </li> +<li> If the argument is 1, +0 is returned </li> +<li> If the argument is negative, NaN is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised. </li> +<li> If the argument is +∞, +∞ is returned </li> +<li> If the argument is NaN, NaN is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p>For integer <code>arg</code>, the binary logarithm can be interpreted as the zero-based index of the most significant 1 bit in the input.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> +#include <errno.h> +#include <fenv.h> +// #pragma STDC FENV_ACCESS ON +int main(void) +{ + printf("log2(65536) = %f\n", log2(65536)); + printf("log2(0.125) = %f\n", log2(0.125)); + printf("log2(0x020f) = %f (highest set bit is in position 9)\n", log2(0x020f)); + printf("base-5 logarithm of 125 = %f\n", log2(125)/log2(5)); + // special values + printf("log2(1) = %f\n", log2(1)); + printf("log2(+Inf) = %f\n", log2(INFINITY)); + //error handling + errno = 0; feclearexcept(FE_ALL_EXCEPT); + printf("log2(0) = %f\n", log2(0)); + if(errno == ERANGE) perror(" errno == ERANGE"); + if(fetestexcept(FE_DIVBYZERO)) puts(" FE_DIVBYZERO raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">log2(65536) = 16.000000 +log2(0.125) = -3.000000 +log2(0x020f) = 9.041659 (highest set bit is in position 9) +base-5 logarithm of 125 = 3.000000 +log2(1) = 0.000000 +log2(+Inf) = inf +log2(0) = -inf + errno == ERANGE: Numerical result out of range + FE_DIVBYZERO raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.6.10 The log2 functions (p: 179) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.3.10 The log2 functions (p: 381) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.6.10 The log2 functions (p: 246) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.3.10 The log2 functions (p: 522) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.6.10 The log2 functions (p: 226) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.3.10 The log2 functions (p: 459) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="log" title="c/numeric/math/log"> <span class="t-lines"><span>log</span><span>logf</span><span>logl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes natural (base-<i>e</i>) logarithm (\({\small \ln{x} }\)ln(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="log10" title="c/numeric/math/log10"> <span class="t-lines"><span>log10</span><span>log10f</span><span>log10l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes common (base-<i>10</i>) logarithm (\({\small \log_{10}{x} }\)log<sub>10</sub>(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="log1p" title="c/numeric/math/log1p"> <span class="t-lines"><span>log1p</span><span>log1pf</span><span>log1pl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes natural (base-<i>e</i>) logarithm of 1 plus the given number (\({\small \ln{(1+x)} }\)ln(1+x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="exp2" title="c/numeric/math/exp2"> <span class="t-lines"><span>exp2</span><span>exp2f</span><span>exp2l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes <i>2</i> raised to the given power (\({\small 2^x}\)2<sup>x</sup>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/log2" title="cpp/numeric/math/log2">C++ documentation</a></span> for <code>log2</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/log2" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/log2</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Flogb.html b/devdocs/c/numeric%2Fmath%2Flogb.html new file mode 100644 index 00000000..79b5b473 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Flogb.html @@ -0,0 +1,88 @@ + <h1 id="firstHeading" class="firstHeading">logb, logbf, logbl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float logbf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double logb( double arg );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double logbl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define logb( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Extracts the value of the unbiased radix-independent exponent from the floating-point argument <code>arg</code>, and returns it as a floating-point value. </div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macros: If <code>arg</code> has type <code>long double</code>, <code>logbl</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>logb</code> is called. Otherwise, <code>logbf</code> is called.</div> <p>Formally, the unbiased exponent is the signed integral part of log<sub class="t-su t-su-b">r</sub>|arg| (returned by this function as a floating-point value), for non-zero arg, where <code>r</code> is <code><a href="../../types/limits" title="c/types/limits">FLT_RADIX</a></code>. If <code>arg</code> is subnormal, it is treated as though it was normalized.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the unbiased exponent of <code>arg</code> is returned as a signed floating-point value.</p> +<p>If a domain error occurs, an implementation-defined value is returned</p> +<p>If a pole error occurs, <code><a href="huge_val" title="c/numeric/math/HUGE VAL">-HUGE_VAL</a></code>, <code>-HUGE_VALF</code>, or <code>-HUGE_VALL</code> is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>Domain or range error may occur if <code>arg</code> is zero.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> If <code>arg</code> is ±0, -∞ is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_DIVBYZERO</a></code> is raised. </li> +<li> If <code>arg</code> is ±∞, +∞ is returned </li> +<li> If <code>arg</code> is NaN, NaN is returned. </li> +<li> In all other cases, the result is exact (<code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> is never raised) and <a href="../fenv/fe_round" title="c/numeric/fenv/FE round">the current rounding mode</a> is ignored </li> +</ul> <h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/logb.html">POSIX requires</a> that a pole error occurs if <code>arg</code> is ±0.</p> +<p>The value of the exponent returned by <code>logb</code> is always 1 less than the exponent retuned by <code><a href="frexp" title="c/numeric/math/frexp">frexp</a></code> because of the different normalization requirements: for the exponent <code>e</code> returned by <code>logb</code>, |arg*r<sup class="t-su">-e</sup>| is between 1 and <code>r</code> (typically between <code>1</code> and <code>2</code>), but for the exponent <code>e</code> returned by <code><a href="frexp" title="c/numeric/math/frexp">frexp</a></code>, |arg*2<sup class="t-su">-e</sup>| is between <code>0.5</code> and <code>1</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>Compares different floating-point decomposition functions.</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> +#include <fenv.h> + +// #pragma STDC FENV_ACCESS ON +int main(void) +{ + double f = 123.45; + printf("Given the number %.2f or %a in hex,\n", f, f); + + double f3; + double f2 = modf(f, &f3); + printf("modf() makes %.0f + %.2f\n", f3, f2); + + int i; + f2 = frexp(f, &i); + printf("frexp() makes %f * 2^%d\n", f2, i); + + i = logb(f); + printf("logb()/logb() make %f * %d^%d\n", f/scalbn(1.0, i), FLT_RADIX, i); + + // error handling + feclearexcept(FE_ALL_EXCEPT); + printf("logb(0) = %f\n", logb(0)); + if(fetestexcept(FE_DIVBYZERO)) puts(" FE_DIVBYZERO raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Given the number 123.45 or 0x1.edccccccccccdp+6 in hex, +modf() makes 123 + 0.45 +frexp() makes 0.964453 * 2^7 +logb()/logb() make 1.928906 * 2^6 +logb(0) = -Inf + FE_DIVBYZERO raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.6.11 The logb functions (p: 179-180) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.3.11 The logb functions (p: 381) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.6.11 The logb functions (p: 246) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.3.11 The logb functions (p: 522) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.6.11 The logb functions (p: 227) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.3.11 The logb functions (p: 459) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="frexp" title="c/numeric/math/frexp"> <span class="t-lines"><span>frexp</span><span>frexpf</span><span>frexpl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> breaks a number into significand and a power of <code>2</code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ilogb" title="c/numeric/math/ilogb"> <span class="t-lines"><span>ilogb</span><span>ilogbf</span><span>ilogbl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> extracts exponent of the given number <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="scalbn" title="c/numeric/math/scalbn"> <span class="t-lines"><span>scalbn</span><span>scalbnf</span><span>scalbnl</span><span>scalbln</span><span>scalblnf</span><span>scalblnl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes efficiently a number times <code><a href="../../types/limits" title="c/types/limits">FLT_RADIX</a></code> raised to a power <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/logb" title="cpp/numeric/math/logb">C++ documentation</a></span> for <code>logb</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/logb" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/logb</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fmath_errhandling.html b/devdocs/c/numeric%2Fmath%2Fmath_errhandling.html new file mode 100644 index 00000000..49d3048d --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fmath_errhandling.html @@ -0,0 +1,81 @@ + <h1 id="firstHeading" class="firstHeading">MATH_ERRNO, MATH_ERREXCEPT, math_errhandling</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define MATH_ERRNO 1</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define MATH_ERREXCEPT 2</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define math_errhandling /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>The macro constant <code>math_errhandling</code> expands to an expression of type <code>int</code> that is either equal to <code>MATH_ERRNO</code>, or equal to <code>MATH_ERREXCEPT</code>, or equal to their bitwise OR (<code>MATH_ERRNO | MATH_ERREXCEPT</code>).</p> +<p>The value of <code>math_errhandling</code> indicates the type of error handling that is performed by the floating-point operators and <a href="../math" title="c/numeric/math">functions</a>:</p> +<table class="t-dsc-begin"> <tr class="t-dsc-hitem"> <th> Constant </th> <th> Explanation </th> +</tr> <tr class="t-dsc"> <td> <code>MATH_ERREXCEPT</code> </td> <td> indicates that floating-point exceptions are used: at least <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_DIVBYZERO</a></code>, <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code>, and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_OVERFLOW</a></code> are defined in <code><fenv.h></code>. </td> +</tr> <tr class="t-dsc"> <td> <code>MATH_ERRNO</code> </td> <td> indicates that floating-point operations use the variable <code><a href="../../error/errno" title="c/error/errno">errno</a></code> to report errors. </td> +</tr> </table> <p>If the implementation supports IEEE floating-point arithmetic (IEC 60559), <code>math_errhandling & MATH_ERREXCEPT</code> is required to be non-zero.</p> +<p>The following floating-point error conditions are recognized:</p> +<table class="wikitable"> <tr> <th>Condition</th> <th>Explanation</th> <th>errno</th> <th>floating-point exception</th> <th>Example </th> +</tr> <tr> <td>Domain error </td> <td>the argument is outside the range in which the operation is mathematically defined (the description of <a href="../math" title="c/numeric/math">each function</a> lists the required domain errors) </td> <td> +<code><a href="../../error/errno_macros" title="c/error/errno macros">EDOM</a></code> </td> <td> +<code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> </td> <td> +<code><a href="http://en.cppreference.com/w/c/numeric/math/acos"><span class="kw673">acos</span></a><span class="br0">(</span><span class="nu0">2</span><span class="br0">)</span></code> </td> +</tr> <tr> <td>Pole error </td> <td>the mathematical result of the function is exactly infinite or undefined </td> <td> +<code><a href="../../error/errno_macros" title="c/error/errno macros">ERANGE</a></code> </td> <td> +<code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_DIVBYZERO</a></code> </td> <td> +<code><a href="http://en.cppreference.com/w/c/numeric/math/log"><span class="kw660">log</span></a><span class="br0">(</span><span class="nu16">0.0</span><span class="br0">)</span></code>, <code>1.0/0.0</code> </td> +</tr> <tr> <td>Range error due to overflow </td> <td>the mathematical result is finite, but becomes infinite after rounding, or becomes the largest representable finite value after rounding down </td> <td> +<code><a href="../../error/errno_macros" title="c/error/errno macros">ERANGE</a></code> </td> <td> +<code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_OVERFLOW</a></code> </td> <td> +<code><a href="http://en.cppreference.com/w/c/numeric/math/pow"><span class="kw668">pow</span></a><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/limits"><span class="kw378">DBL_MAX</span></a>,<span class="nu0">2</span><span class="br0">)</span></code> </td> +</tr> <tr> <td>Range error due to underflow </td> <td>the result is non-zero, but becomes zero after rounding, or becomes subnormal with a loss of precision </td> <td> +<code><a href="../../error/errno_macros" title="c/error/errno macros">ERANGE</a></code> or unchanged (implementation-defined) </td> <td> +<code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_UNDERFLOW</a></code> or nothing (implementation-defined) </td> <td> +<code>DBL_TRUE_MIN/2</code> </td> +</tr> <tr> <td>Inexact result </td> <td>the result has to be rounded to fit in the destination type </td> <td>unchanged </td> <td> +<code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> or nothing (unspecified) </td> <td> +<code><a href="http://en.cppreference.com/w/c/numeric/math/sqrt"><span class="kw665">sqrt</span></a><span class="br0">(</span><span class="nu0">2</span><span class="br0">)</span></code>, <code>1.0/10.0</code> </td> +</tr> +</table> <h3 id="Notes"> Notes</h3> <p>Whether <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> is raised by the mathematical library functions is unspecified in general, but may be explicitly specified in the description of the function (e.g. <code><a href="rint" title="c/numeric/math/rint">rint</a></code> vs <code><a href="nearbyint" title="c/numeric/math/nearbyint">nearbyint</a></code>).</p> +<p>Before C99, floating-point exceptions were not specified, <code><a href="http://en.cppreference.com/w/c/error/errno_macros"><span class="kw426">EDOM</span></a></code> was required for any domain error, <code><a href="http://en.cppreference.com/w/c/error/errno_macros"><span class="kw478">ERANGE</span></a></code> was required for overflows and implementation-defined for underflows.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <fenv.h> +#include <math.h> +#include <errno.h> +#pragma STDC FENV_ACCESS ON +int main(void) +{ + printf("MATH_ERRNO is %s\n", math_errhandling & MATH_ERRNO ? "set" : "not set"); + printf("MATH_ERREXCEPT is %s\n", + math_errhandling & MATH_ERREXCEPT ? "set" : "not set"); + feclearexcept(FE_ALL_EXCEPT); + errno = 0; + printf("log(0) = %f\n", log(0)); + if(errno == ERANGE) + perror("errno == ERANGE"); + if(fetestexcept(FE_DIVBYZERO)) + puts("FE_DIVBYZERO (pole error) reported"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">MATH_ERRNO is set +MATH_ERREXCEPT is set +log(0) = -inf +errno = ERANGE: Numerical result out of range +FE_DIVBYZERO (pole error) reported</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12/9 MATH_ERRNO, MATH_ERREXCEPT, math_errhandling (p: 170) </li> +<li> F.10/4 MATH_ERREXCEPT, math_errhandling (p: 377) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12/9 MATH_ERRNO, MATH_ERREXCEPT, math_errhandling (p: 233) </li> +<li> F.10/4 MATH_ERREXCEPT, math_errhandling (p: 517) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12/9 MATH_ERRNO, MATH_ERREXCEPT, math_errhandling (p: 214) </li> +<li> F.9/4 MATH_ERREXCEPT, math_errhandling> (p: 454) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions"> <span class="t-lines"><span>FE_ALL_EXCEPT</span><span>FE_DIVBYZERO</span><span>FE_INEXACT</span><span>FE_INVALID</span><span>FE_OVERFLOW</span><span>FE_UNDERFLOW</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> floating-point exceptions <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../../error/errno" title="c/error/errno"> <span class="t-lines"><span>errno</span></span></a></div> </td> <td> macro which expands to POSIX-compatible thread-local error number variable<br><span class="t-mark">(macro variable)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/math_errhandling" title="cpp/numeric/math/math errhandling">C++ documentation</a></span> for <code>math_errhandling</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/math_errhandling" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/math_errhandling</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fmodf.html b/devdocs/c/numeric%2Fmath%2Fmodf.html new file mode 100644 index 00000000..7ee360cd --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fmodf.html @@ -0,0 +1,78 @@ + <h1 id="firstHeading" class="firstHeading">modf, modff, modfl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float modff( float arg, float* iptr );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double modf( double arg, double* iptr );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double modfl( long double arg, long double* iptr );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Decomposes given floating point value <code>arg</code> into integral and fractional parts, each having the same type and sign as <code>arg</code>. The integral part (in floating-point format) is stored in the object pointed to by <code>iptr</code>.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> <tr class="t-par"> <td> iptr </td> <td> - </td> <td> pointer to floating point value to store the integral part to </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, returns the fractional part of <code>x</code> with the same sign as <code>x</code>. The integral part is put into the value pointed to by <code>iptr</code>.</p> +<p>The sum of the returned value and the value stored in <code>*iptr</code> gives <code>arg</code> (allowing for rounding).</p> +<h3 id="Error_handling"> Error handling</h3> <p>This function is not subject to any errors specified in <a href="math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> If <code>arg</code> is ±0, ±0 is returned, and ±0 is stored in <code>*iptr</code>. </li> +<li> If <code>arg</code> is ±∞, ±0 is returned, and ±∞ is stored in <code>*iptr</code>. </li> +<li> If <code>arg</code> is NaN, NaN is returned, and NaN is stored in <code>*iptr</code>. </li> +<li> The returned value is exact, <a href="../fenv/fe_round" title="c/numeric/fenv/FE round">the current rounding mode</a> is ignored </li> +</ul> <h3 id="Notes"> Notes</h3> <p>This function behaves as if implemented as follows:</p> +<div class="c source-c"><pre data-language="c">double modf(double value, double *iptr) +{ +#pragma STDC FENV_ACCESS ON + int save_round = fegetround(); + fesetround(FE_TOWARDZERO); + *iptr = std::nearbyint(value); + fesetround(save_round); + return copysign(isinf(value) ? 0.0 : value - (*iptr), value); +}</pre></div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> + +int main(void) +{ + double f = 123.45; + printf("Given the number %.2f or %a in hex,\n", f, f); + + double f3; + double f2 = modf(f, &f3); + printf("modf() makes %.2f + %.2f\n", f3, f2); + + int i; + f2 = frexp(f, &i); + printf("frexp() makes %f * 2^%d\n", f2, i); + + i = ilogb(f); + printf("logb()/ilogb() make %f * %d^%d\n", f/scalbn(1.0, i), FLT_RADIX, i); + + // special values + f2 = modf(-0.0, &f3); + printf("modf(-0) makes %.2f + %.2f\n", f3, f2); + f2 = modf(-INFINITY, &f3); + printf("modf(-Inf) makes %.2f + %.2f\n", f3, f2); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Given the number 123.45 or 0x1.edccccccccccdp+6 in hex, +modf() makes 123.00 + 0.45 +frexp() makes 0.964453 * 2^7 +logb()/ilogb() make 1.92891 * 2^6 +modf(-0) makes -0.00 + -0.00 +modf(-Inf) makes -INF + -0.00</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.6.12 The modf functions (p: 246-247) </li> +<li> F.10.3.12 The modf functions (p: 523) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.6.12 The modf functions (p: 227) </li> +<li> F.9.3.12 The modf functions (p: 460) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.4.6 The modf function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="trunc" title="c/numeric/math/trunc"> <span class="t-lines"><span>trunc</span><span>truncf</span><span>truncl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> rounds to nearest integer not greater in magnitude than the given value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/modf" title="cpp/numeric/math/modf">C++ documentation</a></span> for <code>modf</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/modf" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/modf</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fnan.html b/devdocs/c/numeric%2Fmath%2Fnan.html new file mode 100644 index 00000000..b8bdd8b4 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fnan.html @@ -0,0 +1,74 @@ + <h1 id="firstHeading" class="firstHeading">nan, nanf, nanl, nand32, nand64, nand128</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float nanf( const char* arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double nan( const char* arg );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double nanl( const char* arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal32 nand32( const char* arg );</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal64 nand64( const char* arg );</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal128 nand128( const char* arg );</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <p>Converts the implementation-defined character string <code>arg</code> into the corresponding quiet NaN value, as if by calling the appropriate parsing function <code><i>strtoX</i></code>, as follows:</p> +<ul> +<li> The call <code>nan("n-char-sequence")</code>, where <span class="t-spar">n-char-sequence</span> is a sequence of digits, Latin letters, and underscores, is equivalent to the call <code><span class="coMULTI">/*strtoX*/</span><span class="br0">(</span><span class="st0">"NAN(n-char-sequence)"</span>, <span class="br0">(</span><span class="kw4">char</span><span class="sy2">**</span><span class="br0">)</span><a href="http://en.cppreference.com/w/c/types/NULL"><span class="kw103">NULL</span></a><span class="br0">)</span><span class="sy4">;</span></code>. </li> +<li> The call <code>nan("")</code> is equivalent to the call <code><span class="coMULTI">/*strtoX*/</span><span class="br0">(</span><span class="st0">"NAN()"</span>, <span class="br0">(</span><span class="kw4">char</span><span class="sy2">**</span><span class="br0">)</span><a href="http://en.cppreference.com/w/c/types/NULL"><span class="kw103">NULL</span></a><span class="br0">)</span><span class="sy4">;</span></code>. </li> +<li> The call <code>nan("string")</code>, where <code>string</code> is neither an <span class="t-spar">n-char-sequence</span> nor an empty string, is equivalent to the call <code><span class="coMULTI">/*strtoX*/</span><span class="br0">(</span><span class="st0">"NAN"</span>, <span class="br0">(</span><span class="kw4">char</span><span class="sy2">**</span><span class="br0">)</span><a href="http://en.cppreference.com/w/c/types/NULL"><span class="kw103">NULL</span></a><span class="br0">)</span><span class="sy4">;</span></code>. </li> +</ul> <div class="t-li1"> +<span class="t-li">1)</span> The parsing function is <code><a href="../../string/byte/strtof" title="c/string/byte/strtof">strtof</a></code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> The parsing function is <code><a href="../../string/byte/strtof" title="c/string/byte/strtof">strtod</a></code>.</div> <div class="t-li1"> +<span class="t-li">3)</span> The parsing function is <code><a href="../../string/byte/strtof" title="c/string/byte/strtof">strtold</a></code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> The parsing function is <code>strtod32</code>.</div> <div class="t-li1"> +<span class="t-li">5)</span> The parsing function is <code>strtod64</code>.</div> <div class="t-li1"> +<span class="t-li">6)</span> The parsing function is <code>strtod128</code>.</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>The functions returning decimal floating point values are declared if and only the implementation predefines <code>__STDC_IEC_60559_DFP__</code> (i.e. the implementation supports decimal floating point numbers).</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> narrow character string identifying the contents of a NaN </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The quiet NaN value that corresponds to the identifying string <code>arg</code> or zero if the implementation does not support quiet NaNs.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559), it also supports quiet NaNs.</p> +<h3 id="Error_handling"> Error handling</h3> <p>This function is not subject to any of the error conditions specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <stdint.h> +#include <inttypes.h> +#include <string.h> + +int main(void) +{ + double f1 = nan("1"); + uint64_t f1n; memcpy(&f1n, &f1, sizeof f1); + printf("nan(\"1\") = %f (%" PRIx64 ")\n", f1, f1n); + + double f2 = nan("2"); + uint64_t f2n; memcpy(&f2n, &f2, sizeof f2); + printf("nan(\"2\") = %f (%" PRIx64 ")\n", f2, f2n); + + double f3 = nan("0xF"); + uint64_t f3n; memcpy(&f3n, &f3, sizeof f3); + printf("nan(\"0xF\") = %f (%" PRIx64 ")\n", f3, f3n); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">nan("1") = nan (7ff8000000000001) +nan("2") = nan (7ff8000000000002) +nan("0xF") = nan (7ff800000000000f)</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.11.2 The nan functions (p: 186-187) </li> +<li> F.10.8.2 The nan functions (p: 386) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.11.2 The nan functions (p: 256) </li> +<li> F.10.8.2 The nan functions (p: 529) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.11.2 The nan functions (p: 237) </li> +<li> F.9.8.2 The fabs functions (p: 465) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="isnan" title="c/numeric/math/isnan"> <span class="t-lines"><span>isnan</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number is NaN <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="nan" title="c/numeric/math/NAN"> <span class="t-lines"><span>NAN</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> evaluates to a quiet NaN of type <code>float</code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/nan" title="cpp/numeric/math/nan">C++ documentation</a></span> for <code>nanf, nan, nanl</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/nan" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/nan</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fnearbyint.html b/devdocs/c/numeric%2Fmath%2Fnearbyint.html new file mode 100644 index 00000000..4f551258 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fnearbyint.html @@ -0,0 +1,78 @@ + <h1 id="firstHeading" class="firstHeading">nearbyint, nearbyintf, nearbyintl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float nearbyintf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double nearbyint( double arg );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double nearbyintl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define nearbyint( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Rounds the floating-point argument <code>arg</code> to an integer value in floating-point format, using the <a href="../fenv/fe_round" title="c/numeric/fenv/FE round">current rounding mode</a>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>arg</code> has type <code>long double</code>, <code>nearbyintl</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>nearbyint</code> is called. Otherwise, <code>nearbyintf</code> is called, respectively.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The nearest integer value to <code>arg</code>, according to the <a href="../fenv/fe_round" title="c/numeric/fenv/FE round">current rounding mode</a>, is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>This function is not subject to any of the errors specified in <a href="math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> is never raised </li> +<li> If <code>arg</code> is ±∞, it is returned, unmodified </li> +<li> If <code>arg</code> is ±0, it is returned, unmodified </li> +<li> If <code>arg</code> is NaN, NaN is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p>The only difference between <code>nearbyint</code> and <code><a href="rint" title="c/numeric/math/rint">rint</a></code> is that <code>nearbyint</code> never raises <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code>.</p> +<p>The largest representable floating-point values are exact integers in all standard floating-point formats, so <code>nearbyint</code> never overflows on its own; however the result may overflow any integer type (including <code><a href="../../types/integer" title="c/types/integer">intmax_t</a></code>), when stored in an integer variable.</p> +<p>If the current rounding mode is <code><a href="../fenv/fe_round" title="c/numeric/fenv/FE round">FE_TONEAREST</a></code>, this function rounds to even in halfway cases (like <code><a href="rint" title="c/numeric/math/rint">rint</a></code>, but unlike <code><a href="round" title="c/numeric/math/round">round</a></code>).</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <fenv.h> + +int main(void) +{ +#pragma STDC FENV_ACCESS ON + fesetround(FE_TONEAREST); + printf("rounding to nearest:\nnearbyint(+2.3) = %+.1f ", nearbyint(2.3)); + printf("nearbyint(+2.5) = %+.1f ", nearbyint(2.5)); + printf("nearbyint(+3.5) = %+.1f\n", nearbyint(3.5)); + printf("nearbyint(-2.3) = %+.1f ", nearbyint(-2.3)); + printf("nearbyint(-2.5) = %+.1f ", nearbyint(-2.5)); + printf("nearbyint(-3.5) = %+.1f\n", nearbyint(-3.5)); + + fesetround(FE_DOWNWARD); + printf("rounding down: \nnearbyint(+2.3) = %+.1f ", nearbyint(2.3)); + printf("nearbyint(+2.5) = %+.1f ", nearbyint(2.5)); + printf("nearbyint(+3.5) = %+.1f\n", nearbyint(3.5)); + printf("nearbyint(-2.3) = %+.1f ", nearbyint(-2.3)); + printf("nearbyint(-2.5) = %+.1f ", nearbyint(-2.5)); + printf("nearbyint(-3.5) = %+.1f\n", nearbyint(-3.5)); + + printf("nearbyint(-0.0) = %+.1f\n", nearbyint(-0.0)); + printf("nearbyint(-Inf) = %+.1f\n", nearbyint(-INFINITY)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">rounding to nearest: +nearbyint(+2.3) = +2.0 nearbyint(+2.5) = +2.0 nearbyint(+3.5) = +4.0 +nearbyint(-2.3) = -2.0 nearbyint(-2.5) = -2.0 nearbyint(-3.5) = -4.0 +rounding down: +nearbyint(+2.3) = +2.0 nearbyint(+2.5) = +2.0 nearbyint(+3.5) = +3.0 +nearbyint(-2.3) = -3.0 nearbyint(-2.5) = -3.0 nearbyint(-3.5) = -4.0 +nearbyint(-0.0) = -0.0 +nearbyint(-Inf) = -inf</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.9.3 The nearbyint functions (p: 251-252) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.6.3 The nearbyint functions (p: 526) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.9.3 The nearbyint functions (p: 232) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.6.3 The nearbyint functions (p: 463) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="rint" title="c/numeric/math/rint"> <span class="t-lines"><span>rint</span><span>rintf</span><span>rintl</span><span>lrint</span><span>lrintf</span><span>lrintl</span><span>llrint</span><span>llrintf</span><span>llrintl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> rounds to an integer using current rounding mode with <br> exception if the result differs <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="round" title="c/numeric/math/round"> <span class="t-lines"><span>round</span><span>roundf</span><span>roundl</span><span>lround</span><span>lroundf</span><span>lroundl</span><span>llround</span><span>llroundf</span><span>llroundl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> rounds to nearest integer, rounding away from zero in halfway cases <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../fenv/feround" title="c/numeric/fenv/feround"> <span class="t-lines"><span>fegetround</span><span>fesetround</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> gets or sets rounding direction <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/nearbyint" title="cpp/numeric/math/nearbyint">C++ documentation</a></span> for <code>nearbyint</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/nearbyint" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/nearbyint</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fnextafter.html b/devdocs/c/numeric%2Fmath%2Fnextafter.html new file mode 100644 index 00000000..ad038edc --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fnextafter.html @@ -0,0 +1,109 @@ + <h1 id="firstHeading" class="firstHeading">nextafter, nextafterf, nextafterl, nexttoward, nexttowardf, nexttowardl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float nextafterf( float from, float to );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double nextafter( double from, double to );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double nextafterl( long double from, long double to );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float nexttowardf( float from, long double to );</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double nexttoward( double from, long double to );</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double nexttowardl( long double from, long double to );</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define nextafter(from, to)</pre> +</td> <td> (7) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define nexttoward(from, to)</pre> +</td> <td> (8) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> First, converts both arguments to the type of the function, then returns the next representable value of <code>from</code> in the direction of <code>to</code>. If <code>from</code> equals to <code>to</code>, <code>to</code> is returned.</div> <div class="t-li1"> +<span class="t-li">4-6)</span> First, converts the first argument to the type of the function, then returns the next representable value of <code>from</code> in the direction of <code>to</code>. If <code>from</code> equals to <code>to</code>, <code>to</code> is returned, converted from <code>long double</code> to the return type of the function without loss of range or precision.</div> <div class="t-li1"> +<span class="t-li">7)</span> Type-generic macro: If any argument has type <code>long double</code>, <code>nextafterl</code> is called. Otherwise, if any argument has integer type or has type <code>double</code>, <code>nextafter</code> is called. Otherwise, <code>nextafterf</code> is called.</div> <div class="t-li1"> +<span class="t-li">8)</span> Type-generic macro: If the argument <code>from</code> has type <code>long double</code>, <code>nexttowardl</code> is called. Otherwise, if <code>from</code> has integer type or the type <code>double</code>, <code>nexttoward</code> is called. Otherwise, <code>nexttowardf</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> from, to </td> <td> - </td> <td> floating point values </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the next representable value of <code>from</code> in the direction of <code>to</code>. is returned. If <code>from</code> equals <code>to</code>, then <code>to</code> is returned, converted to the type of the function.</p> +<p>If a range error due to overflow occurs, <code><a href="huge_val" title="c/numeric/math/HUGE VAL">±HUGE_VAL</a></code>, <code>±HUGE_VALF</code>, or <code>±HUGE_VALL</code> is returned (with the same sign as <code>from</code>).</p> +<p>If a range error occurs due to underflow, the correct result is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> if <code>from</code> is finite, but the expected result is an infinity, raises <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_OVERFLOW</a></code> </li> +<li> if <code>from</code> does not equal <code>to</code> and the result is subnormal or zero, raises <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_UNDERFLOW</a></code> </li> +<li> in any case, the returned value is independent of the current rounding mode </li> +<li> if either <code>from</code> or <code>to</code> is NaN, NaN is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/nextafter.html">POSIX specifies</a> that the overflow and the underflow conditions are range errors (<code><a href="../../error/errno" title="c/error/errno">errno</a></code> may be set).</p> +<p>IEC 60559 recommends that <code>from</code> is returned whenever <code>from == to</code>. These functions return <code>to</code> instead, which makes the behavior around zero consistent: <code>nextafter(-0.0, +0.0)</code> returns <code>+0.0</code> and <code>nextafter(+0.0, -0.0)</code> returns <code>-0.0</code>.</p> +<p><code>nextafter</code> is typically implemented by manipulation of IEEE representation (<a rel="nofollow" class="external text" href="https://github.com/bminor/glibc/blob/master/math/s_nextafter.c">glibc</a> <a rel="nofollow" class="external text" href="https://github.com/ifduyue/musl/blob/master/src/math/nextafter.c">musl</a>).</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <math.h> +#include <stdio.h> +#include <float.h> +#include <fenv.h> + +int main(void) +{ + float from1 = 0, to1 = nextafterf(from1, 1); + printf("The next representable float after %.2f is %.20g (%a)\n", from1, to1, to1); + + float from2 = 1, to2 = nextafterf(from2, 2); + printf("The next representable float after %.2f is %.20f (%a)\n", from2, to2, to2); + + double from3 = nextafter(0.1, 0), to3 = 0.1; + printf("The number 0.1 lies between two valid doubles:\n" + " %.56f (%a)\nand %.55f (%a)\n", from3, from3, to3, to3); + + // difference between nextafter and nexttoward: + long double dir = nextafterl(from1, 1); // first subnormal long double + float x = nextafterf(from1, dir); // first converts dir to float, giving 0 + printf("Using nextafter, next float after %.2f (%a) is %.20g (%a)\n", + from1, from1, x, x); + x = nexttowardf(from1, dir); + printf("Using nexttoward, next float after %.2f (%a) is %.20g (%a)\n", + from1, from1, x, x); + + // special values + { + #pragma STDC FENV_ACCESS ON + feclearexcept(FE_ALL_EXCEPT); + double from4 = DBL_MAX, to4 = nextafter(from4, INFINITY); + printf("The next representable double after %.2g (%a) is %.23f (%a)\n", + from4, from4, to4, to4); + if(fetestexcept(FE_OVERFLOW)) puts(" raised FE_OVERFLOW"); + if(fetestexcept(FE_INEXACT)) puts(" raised FE_INEXACT"); + } // end FENV_ACCESS block + + float from5 = 0.0, to5 = nextafter(from5, -0.0); + printf("nextafter(+0.0, -0.0) gives %.2g (%a)\n", to5, to5); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">The next representable float after 0.00 is 1.4012984643248170709e-45 (0x1p-149) +The next representable float after 1.00 is 1.00000011920928955078 (0x1.000002p+0) +The number 0.1 lies between two valid doubles: + 0.09999999999999999167332731531132594682276248931884765625 (0x1.9999999999999p-4) +and 0.1000000000000000055511151231257827021181583404541015625 (0x1.999999999999ap-4) +Using nextafter, next float after 0.00 (0x0p+0) is 0 (0x0p+0) +Using nexttoward, next float after 0.00 (0x0p+0) is 1.4012984643248170709e-45 (0x1p-149) +The next representable double after 1.8e+308 (0x1.fffffffffffffp+1023) is inf (inf) + raised FE_OVERFLOW + raised FE_INEXACT +nextafter(+0.0, -0.0) gives -0 (-0x0p+0)</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.11.3 The nextafter functions (p: 187) </li> +<li> 7.12.11.4 The nexttoward functions (p: 187) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.8.3 The nextafter functions (p: 386) </li> +<li> F.10.8.4 The nexttoward functions (p: 386) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.11.3 The nextafter functions (p: 256) </li> +<li> 7.12.11.4 The nexttoward functions (p: 257) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.8.3 The nextafter functions (p: 529) </li> +<li> F.10.8.4 The nexttoward functions (p: 529) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.11.3 The nextafter functions (p: 237) </li> +<li> 7.12.11.4 The nexttoward functions (p: 238) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.8.3 The nextafter functions (p: 466) </li> +<li> F.9.8.4 The nexttoward functions (p: 466) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/nextafter" title="cpp/numeric/math/nextafter">C++ documentation</a></span> for <code>nextafter</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/nextafter" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/nextafter</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fpow.html b/devdocs/c/numeric%2Fmath%2Fpow.html new file mode 100644 index 00000000..c0edd34b --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fpow.html @@ -0,0 +1,122 @@ + <h1 id="firstHeading" class="firstHeading">pow, powf, powl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float powf( float base, float exponent );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double pow( double base, double exponent );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double powl( long double base, long double exponent );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define pow( base, exponent )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the value of <code>base</code> raised to the power <code>exponent</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If any argument has type <code>long double</code>, <code>powl</code> is called. Otherwise, if any argument has integer type or has type <code>double</code>, <code>pow</code> is called. Otherwise, <code>powf</code> is called. If at least one argument is complex or imaginary, then the macro invokes the corresponding complex function (<code><a href="http://en.cppreference.com/w/c/numeric/complex/cpow"><span class="kw775">cpowf</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/cpow"><span class="kw774">cpow</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/cpow"><span class="kw776">cpowl</span></a></code>).</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> base </td> <td> - </td> <td> base as floating point value </td> +</tr> <tr class="t-par"> <td> exponent </td> <td> - </td> <td> exponent as floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, <code>base</code> raised to the power of <code>exponent</code> (base<sup class="t-su">exponent</sup>) is returned.</p> +<p>If a domain error occurs, an implementation-defined value is returned (NaN where supported).</p> +<p>If a pole error or a range error due to overflow occurs, <code><a href="huge_val" title="c/numeric/math/HUGE VAL">±HUGE_VAL</a></code>, <code>±HUGE_VALF</code>, or <code>±HUGE_VALL</code> is returned.</p> +<p>If a range error occurs due to underflow, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If <code>base</code> is finite and negative and <code>exponent</code> is finite and non-integer, a domain error occurs and a range error may occur.</p> +<p>If <code>base</code> is zero and <code>exponent</code> is zero, a domain error may occur.</p> +<p>If <code>base</code> is zero and <code>exponent</code> is negative, a domain error or a pole error may occur.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> <code>pow(+0, exponent)</code>, where <code>exponent</code> is a negative odd integer, returns <code>+∞</code> and raises <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_DIVBYZERO</a></code> </li> +<li> <code>pow(-0, exponent)</code>, where <code>exponent</code> is a negative odd integer, returns <code>-∞</code> and raises <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_DIVBYZERO</a></code> </li> +<li> <code>pow(±0, exponent)</code>, where <code>exponent</code> is negative, finite, and is an even integer or a non-integer, returns +∞ and raises <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_DIVBYZERO</a></code> </li> +<li> <code>pow(±0, -∞)</code> returns +∞ <span class="t-rev-inl t-until-c23"><span>and may raise <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_DIVBYZERO</a></code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span> </li> +<li> <code>pow(+0, exponent)</code>, where <code>exponent</code> is a positive odd integer, returns +0 </li> +<li> <code>pow(-0, exponent)</code>, where <code>exponent</code> is a positive odd integer, returns -0 </li> +<li> <code>pow(±0, exponent)</code>, where <code>exponent</code> is positive non-integer or a positive even integer, returns +0 </li> +<li> <code>pow(-1, ±∞)</code> returns <code>1</code> </li> +<li> <code>pow(+1, exponent)</code> returns <code>1</code> for any <code>exponent</code>, even when <code>exponent</code> is <code>NaN</code> </li> +<li> <code>pow(base, ±0)</code> returns <code>1</code> for any <code>base</code>, even when <code>base</code> is <code>NaN</code> </li> +<li> <code>pow(base, exponent)</code> returns <code>NaN</code> and raises <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> if <code>base</code> is finite and negative and <code>exponent</code> is finite and non-integer. </li> +<li> <code>pow(base, -∞)</code> returns +∞ for any <code>|base|<1</code> </li> +<li> <code>pow(base, -∞)</code> returns +0 for any <code>|base|>1</code> </li> +<li> <code>pow(base, +∞)</code> returns +0 for any <code>|base|<1</code> </li> +<li> <code>pow(base, +∞)</code> returns +∞ for any <code>|base|>1</code> </li> +<li> <code>pow(-∞, exponent)</code> returns -0 if <code>exponent</code> is a negative odd integer </li> +<li> <code>pow(-∞, exponent)</code> returns +0 if <code>exponent</code> is a negative non-integer or negative even integer </li> +<li> <code>pow(-∞, exponent)</code> returns -∞ if <code>exponent</code> is a positive odd integer </li> +<li> <code>pow(-∞, exponent)</code> returns +∞ if <code>exponent</code> is a positive non-integer or positive even integer </li> +<li> <code>pow(+∞, exponent)</code> returns +0 for any negative <code>exponent</code> </li> +<li> <code>pow(+∞, exponent)</code> returns +∞ for any positive <code>exponent</code> </li> +<li> except where specified above, if any argument is NaN, NaN is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p>Although <code>pow</code> cannot be used to obtain a root of a negative number, <code><a href="cbrt" title="c/numeric/math/cbrt">cbrt</a></code> is provided for the common case where <code>exponent</code> is 1/3.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <errno.h> +#include <fenv.h> + +#pragma STDC FENV_ACCESS ON +int main(void) +{ + // typical usage + printf("pow(2, 10) = %f\n", pow(2,10)); + printf("pow(2, 0.5) = %f\n", pow(2,0.5)); + printf("pow(-2, -3) = %f\n", pow(-2,-3)); + // special values + printf("pow(-1, NAN) = %f\n", pow(-1,NAN)); + printf("pow(+1, NAN) = %f\n", pow(+1,NAN)); + printf("pow(INFINITY, 2) = %f\n", pow(INFINITY, 2)); + printf("pow(INFINITY, -1) = %f\n", pow(INFINITY, -1)); + // error handling + errno = 0; feclearexcept(FE_ALL_EXCEPT); + printf("pow(-1, 1/3) = %f\n", pow(-1, 1.0/3)); + if(errno == EDOM) perror(" errno == EDOM"); + if(fetestexcept(FE_INVALID)) puts(" FE_INVALID raised"); + + feclearexcept(FE_ALL_EXCEPT); + printf("pow(-0, -3) = %f\n", pow(-0.0, -3)); + if(fetestexcept(FE_DIVBYZERO)) puts(" FE_DIVBYZERO raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">pow(2, 10) = 1024.000000 +pow(2, 0.5) = 1.414214 +pow(-2, -3) = -0.125000 +pow(-1, NAN) = nan +pow(+1, NAN) = 1.000000 +pow(INFINITY, 2) = inf +pow(INFINITY, -1) = 0.000000 +pow(-1, 1/3) = -nan + errno == EDOM: Numerical argument out of domain + FE_INVALID raised +pow(-0, -3) = -inf + FE_DIVBYZERO raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.12.7.5 The pow functions </li> +<li> 7.27 Type-generic math <tgmath.h> </li> +<li> F.10.4.5 The pow functions (p: 524-525) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.7.4 The pow functions (p: 248-249) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.4.4 The pow functions (p: 524-525) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.7.4 The pow functions (p: 248-249) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.4.4 The pow functions (p: 524-525) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.7.4 The pow functions (p: 229) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.4.4 The pow functions (p: 461) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.5.1 The pow function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="sqrt" title="c/numeric/math/sqrt"> <span class="t-lines"><span>sqrt</span><span>sqrtf</span><span>sqrtl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes square root (\(\small{\sqrt{x} }\)<span class="t-mrad"><span>√</span><span>x</span></span>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="cbrt" title="c/numeric/math/cbrt"> <span class="t-lines"><span>cbrt</span><span>cbrtf</span><span>cbrtl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes cube root (\(\small{\sqrt[3]{x} }\)<span class="t-mrad"><span>3</span><span>√</span><span>x</span></span>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="hypot" title="c/numeric/math/hypot"> <span class="t-lines"><span>hypot</span><span>hypotf</span><span>hypotl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes square root of the sum of the squares of two given numbers (\(\scriptsize{\sqrt{x^2+y^2} }\)<span class="t-mrad"><span>√</span><span>x<sup class="t-su">2</sup>+y<sup class="t-su">2</sup></span></span>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../complex/cpow" title="c/numeric/complex/cpow"> <span class="t-lines"><span>cpow</span><span>cpowf</span><span>cpowl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex power function <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/pow" title="cpp/numeric/math/pow">C++ documentation</a></span> for <code>pow</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/pow" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/pow</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fremainder.html b/devdocs/c/numeric%2Fmath%2Fremainder.html new file mode 100644 index 00000000..1abb2995 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fremainder.html @@ -0,0 +1,87 @@ + <h1 id="firstHeading" class="firstHeading">remainder, remainderf, remainderl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float remainderf( float x, float y );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double remainder( double x, double y );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double remainderl( long double x, long double y );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define remainder( x, y )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the IEEE remainder of the floating point division operation <code>x/y</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If any argument has type <code>long double</code>, <code>remainderl</code> is called. Otherwise, if any argument has integer type or has type <code>double</code>, <code>remainder</code> is called. Otherwise, <code>remainderf</code> is called.</div> <p>The IEEE floating-point remainder of the division operation <code>x/y</code> calculated by this function is exactly the value <code>x - n*y</code>, where the value <code>n</code> is the integral value nearest the exact value <code>x/y</code>. When |n-x/y| = ½, the value <code>n</code> is chosen to be even.</p> +<p>In contrast to <code><a href="fmod" title="c/numeric/math/fmod">fmod()</a></code>, the returned value is not guaranteed to have the same sign as <code>x</code>.</p> +<p>If the returned value is <code>0</code>, it will have the same sign as <code>x</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> x, y </td> <td> - </td> <td> floating point values </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If successful, returns the IEEE floating-point remainder of the division <code>x/y</code> as defined above.</p> +<p>If a domain error occurs, an implementation-defined value is returned (NaN where supported).</p> +<p>If a range error occurs due to underflow, the correct result is returned.</p> +<p>If <code>y</code> is zero, but the domain error does not occur, zero is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>Domain error may occur if <code>y</code> is zero.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> The current <a href="../fenv/fe_round" title="c/numeric/fenv/FE round">rounding mode</a> has no effect. </li> +<li> <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> is never raised, the result is always exact. </li> +<li> If <code>x</code> is ±∞ and <code>y</code> is not NaN, NaN is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised. </li> +<li> If <code>y</code> is ±0 and <code>x</code> is not NaN, NaN is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised. </li> +<li> If either argument is NaN, NaN is returned. </li> +</ul> <h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/remainder.html">POSIX requires</a> that a domain error occurs if <code>x</code> is infinite or <code>y</code> is zero.</p> +<p><code><a href="fmod" title="c/numeric/math/fmod">fmod</a></code>, but not <code>remainder</code> is useful for doing silent wrapping of floating-point types to unsigned integer types: <code><span class="br0">(</span><span class="nu16">0.0</span> <span class="sy1"><=</span> <span class="br0">(</span>y <span class="sy1">=</span> <a href="http://en.cppreference.com/w/c/numeric/math/fmod"><span class="kw647">fmod</span></a><span class="br0">(</span><a href="http://en.cppreference.com/w/c/numeric/math/rint"><span class="kw692">rint</span></a><span class="br0">(</span>x<span class="br0">)</span>, <span class="nu16">65536.0</span><span class="br0">)</span><span class="br0">)</span> <span class="sy4">?</span> y <span class="sy4">:</span> <span class="nu16">65536.0</span> <span class="sy2">+</span> y<span class="br0">)</span></code> is in the range <code>[-0.0 .. 65535.0]</code>, which corresponds to <code>unsigned short</code>, but <code>remainder<span class="br0">(</span><a href="http://en.cppreference.com/w/c/numeric/math/rint"><span class="kw692">rint</span></a><span class="br0">(</span>x<span class="br0">)</span>, <span class="nu16">65536.0</span><span class="br0">)</span></code> is in the range <code>[-32767.0, +32768.0]</code>, which is outside of the range of <code>signed short</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <fenv.h> + +#pragma STDC FENV_ACCESS ON +int main(void) +{ + printf("remainder(+5.1, +3.0) = %.1f\n", remainder(5.1,3)); + printf("remainder(-5.1, +3.0) = %.1f\n", remainder(-5.1,3)); + printf("remainder(+5.1, -3.0) = %.1f\n", remainder(5.1,-3)); + printf("remainder(-5.1, -3.0) = %.1f\n", remainder(-5.1,-3)); + + // special values + printf("remainder(-0.0, 1.0) = %.1f\n", remainder(-0.0, 1)); + printf("remainder(+5.1, Inf) = %.1f\n", remainder(5.1, INFINITY)); + + // error handling + feclearexcept(FE_ALL_EXCEPT); + printf("remainder(+5.1, 0) = %.1f\n", remainder(5.1, 0)); + if(fetestexcept(FE_INVALID)) puts(" FE_INVALID raised"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">remainder(+5.1, +3.0) = -0.9 +remainder(-5.1, +3.0) = 0.9 +remainder(+5.1, -3.0) = -0.9 +remainder(-5.1, -3.0) = 0.9 +remainder(+0.0, 1.0) = 0.0 +remainder(-0.0, 1.0) = -0.0 +remainder(+5.1, Inf) = 5.1 +remainder(+5.1, 0) = -nan + FE_INVALID raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.10.2 The remainder functions (p: 185-186) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.7.2 The remainder functions (p: 385) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.10.2 The remainder functions (p: 254-255) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.7.2 The remainder functions (p: 529) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.10.2 The remainder functions (p: 235) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.7.2 The remainder functions (p: 465) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="div" title="c/numeric/math/div"> <span class="t-lines"><span>div</span><span>ldiv</span><span>lldiv</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes quotient and remainder of integer division <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fmod" title="c/numeric/math/fmod"> <span class="t-lines"><span>fmod</span><span>fmodf</span><span>fmodl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes remainder of the floating-point division operation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="remquo" title="c/numeric/math/remquo"> <span class="t-lines"><span>remquo</span><span>remquof</span><span>remquol</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes signed remainder as well as the three last bits of the division operation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/remainder" title="cpp/numeric/math/remainder">C++ documentation</a></span> for <code>remainder</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/remainder" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/remainder</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fremquo.html b/devdocs/c/numeric%2Fmath%2Fremquo.html new file mode 100644 index 00000000..aef01c0a --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fremquo.html @@ -0,0 +1,99 @@ + <h1 id="firstHeading" class="firstHeading">remquo, remquof, remquol</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float remquof( float x, float y, int *quo );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double remquo( double x, double y, int *quo );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double remquol( long double x, long double y, int *quo );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define remquo( x, y, quo )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the floating-point remainder of the division operation <code>x/y</code> as the <code><a href="remainder" title="c/numeric/math/remainder">remainder()</a></code> function does. Additionally, the sign and at least the three of the last bits of <code>x/y</code> will be stored in <code>quo</code>, sufficient to determine the octant of the result within a period.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If any non-pointer argument has type <code>long double</code>, <code>remquol</code> is called. Otherwise, if any non-pointer argument has integer type or has type <code>double</code>, <code>remquo</code> is called. Otherwise, <code>remquof</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> x, y </td> <td> - </td> <td> floating point values </td> +</tr> <tr class="t-par"> <td> quo </td> <td> - </td> <td> pointer to an integer value to store the sign and some bits of <code>x/y</code> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If successful, returns the floating-point remainder of the division <code>x/y</code> as defined in <code><a href="remainder" title="c/numeric/math/remainder">remainder</a></code>, and stores, in <code>*quo</code>, the sign and at least three of the least significant bits of <code>x/y</code> (formally, stores a value whose sign is the sign of <code>x/y</code> and whose magnitude is congruent modulo 2<sup class="t-su">n</sup> to the magnitude of the integral quotient of <code>x/y</code>, where n is an implementation-defined integer greater than or equal to 3).</p> +<p>If <code>y</code> is zero, the value stored in <code>*quo</code> is unspecified.</p> +<p>If a domain error occurs, an implementation-defined value is returned (NaN where supported).</p> +<p>If a range error occurs due to underflow, the correct result is returned if subnormals are supported.</p> +<p>If <code>y</code> is zero, but the domain error does not occur, zero is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>Domain error may occur if <code>y</code> is zero.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> The current <a href="../fenv/fe_round" title="c/numeric/fenv/FE round">rounding mode</a> has no effect. </li> +<li> <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> is never raised </li> +<li> If <code>x</code> is ±∞ and <code>y</code> is not NaN, NaN is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised </li> +<li> If <code>y</code> is ±0 and <code>x</code> is not NaN, NaN is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised </li> +<li> If either <code>x</code> or <code>y</code> is NaN, NaN is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/remquo.html">POSIX requires</a> that a domain error occurs if <code>x</code> is infinite or <code>y</code> is zero.</p> +<p>This function is useful when implementing periodic functions with the period exactly representable as a floating-point value: when calculating sin(πx) for a very large <code>x</code>, calling <code><a href="sin" title="c/numeric/math/sin">sin</a></code> directly may result in a large error, but if the function argument is first reduced with <code>remquo</code>, the low-order bits of the quotient may be used to determine the sign and the octant of the result within the period, while the remainder may be used to calculate the value with high precision.</p> +<p>On some platforms this operation is supported by hardware (and, for example, on Intel CPU, <code>FPREM1</code> leaves exactly 3 bits of precision in the quotient)</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <fenv.h> +#ifndef __GNUC__ +#pragma STDC FENV_ACCESS ON +#endif +double cos_pi_x_naive(double x) +{ + const double pi = acos(-1); + return cos(pi * x); +} +// the period is 2, values are (0;0.5) positive, (0.5;1.5) negative, (1.5,2) positive +double cos_pi_x_smart(double x) +{ + const double pi = acos(-1); + int extremum; + double rem = remquo(x, 1, &extremum); + extremum = (unsigned)extremum % 2; // keep 1 bit to determine nearest extremum + return extremum ? -cos(pi * rem) : cos(pi * rem); +} +int main(void) +{ + printf("cos(pi * 0.25) = %f\n", cos_pi_x_naive(0.25)); + printf("cos(pi * 1.25) = %f\n", cos_pi_x_naive(1.25)); + printf("cos(pi * 1000000000000.25) = %f\n", cos_pi_x_naive(1000000000000.25)); + printf("cos(pi * 1000000000001.25) = %f\n", cos_pi_x_naive(1000000000001.25)); + printf("cos(pi * 1000000000000.25) = %f\n", cos_pi_x_smart(1000000000000.25)); + printf("cos(pi * 1000000000001.25) = %f\n", cos_pi_x_smart(1000000000001.25)); + // error handling + feclearexcept(FE_ALL_EXCEPT); + int quo; + printf("remquo(+Inf, 1) = %.1f\n", remquo(INFINITY, 1, &quo)); + if(fetestexcept(FE_INVALID)) puts(" FE_INVALID raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">cos(pi * 0.25) = 0.707107 +cos(pi * 1.25) = -0.707107 +cos(pi * 1000000000000.25) = 0.707123 +cos(pi * 1000000000001.25) = -0.707117 +cos(pi * 1000000000000.25) = 0.707107 +cos(pi * 1000000000001.25) = -0.707107 +remquo(+Inf, 1) = -nan + FE_INVALID raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.10.3 The remquo functions (p: 186) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.7.3 The remquo functions (p: 385) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.10.3 The remquo functions (p: 255) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.7.3 The remquo functions (p: 529) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.10.3 The remquo functions (p: 236) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.7.3 The remquo functions (p: 465) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="div" title="c/numeric/math/div"> <span class="t-lines"><span>div</span><span>ldiv</span><span>lldiv</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes quotient and remainder of integer division <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fmod" title="c/numeric/math/fmod"> <span class="t-lines"><span>fmod</span><span>fmodf</span><span>fmodl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes remainder of the floating-point division operation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="remainder" title="c/numeric/math/remainder"> <span class="t-lines"><span>remainder</span><span>remainderf</span><span>remainderl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes signed remainder of the floating-point division operation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/remquo" title="cpp/numeric/math/remquo">C++ documentation</a></span> for <code>remquo</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/remquo" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/remquo</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Frint.html b/devdocs/c/numeric%2Fmath%2Frint.html new file mode 100644 index 00000000..cd195c3e --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Frint.html @@ -0,0 +1,134 @@ + <h1 id="firstHeading" class="firstHeading">rint, rintf, rintl, lrint, lrintf, lrintl, llrint, llrintf, llrintl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float rintf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double rint( double arg );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double rintl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define rint( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long lrintf( float arg );</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long lrint( double arg );</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long lrintl( long double arg );</pre> +</td> <td> (7) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define lrint( arg )</pre> +</td> <td> (8) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long long llrintf( float arg );</pre> +</td> <td> (9) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long long llrint( double arg );</pre> +</td> <td> (10) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long long llrintl( long double arg );</pre> +</td> <td> (11) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define llrint( arg )</pre> +</td> <td> (12) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Rounds the floating-point argument <code>arg</code> to an integer value in floating-point format, using the current rounding mode.</div> <div class="t-li1"> +<span class="t-li">5-7, 9-11)</span> Rounds the floating-point argument <code>arg</code> to an integer value in integer format, using the current rounding mode.</div> <div class="t-li1"> +<span class="t-li">4,8,12)</span> Type-generic macros: If <code>arg</code> has type <code>long double</code>, <code>rintl</code>, <code>lrintl</code>, <code>llrintl</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>rint</code>, <code>lrint</code>, <code>llrint</code> is called. Otherwise, <code>rintf</code>, <code>lrintf</code>, <code>llrintf</code> is called, respectively.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the nearest integer value to <code>arg</code>, according to the <a href="../fenv/fe_round" title="c/numeric/fenv/FE round">current rounding mode</a>, is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the result of <code>lrint</code> or <code>llrint</code> is outside the range representable by the return type, a domain error or a range error may occur.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559), For the <code>rint</code> function:</p> +<ul> +<li> If <code>arg</code> is ±∞, it is returned, unmodified </li> +<li> If <code>arg</code> is ±0, it is returned, unmodified </li> +<li> If <code>arg</code> is NaN, NaN is returned </li> +</ul> For <code>lrint</code> and <code>llrint</code> functions: <ul> +<li> If <code>arg</code> is ±∞, <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised and an implementation-defined value is returned </li> +<li> If the result of the rounding is outside the range of the return type, <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised and an implementation-defined value is returned </li> +<li> If <code>arg</code> is NaN, <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised and an implementation-defined value is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/lrint.html">POSIX specifies</a> that all cases where <code>lrint</code> or <code>llrint</code> raise <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> are domain errors.</p> +<p>As specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>, <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> may be (but isn't required to be on non-IEEE floating-point platforms) raised by <code>rint</code> when rounding a non-integer finite value.</p> +<p>The only difference between <code>rint</code> and <code><a href="nearbyint" title="c/numeric/math/nearbyint">nearbyint</a></code> is that <code><a href="nearbyint" title="c/numeric/math/nearbyint">nearbyint</a></code> never raises <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code>.</p> +<p>The largest representable floating-point values are exact integers in all standard floating-point formats, so <code>rint</code> never overflows on its own; however the result may overflow any integer type (including <code><a href="../../types/integer" title="c/types/integer">intmax_t</a></code>), when stored in an integer variable.</p> +<p>If the current rounding mode is...</p> +<ul> +<li> <code><a href="../fenv/fe_round" title="c/numeric/fenv/FE round">FE_DOWNWARD</a></code>, then <code>rint</code> is equivalent to <code><a href="floor" title="c/numeric/math/floor">floor</a></code>. </li> +<li> <code><a href="../fenv/fe_round" title="c/numeric/fenv/FE round">FE_UPWARD</a></code>, then <code>rint</code> is equivalent to <code><a href="ceil" title="c/numeric/math/ceil">ceil</a></code>. </li> +<li> <code><a href="../fenv/fe_round" title="c/numeric/fenv/FE round">FE_TOWARDZERO</a></code>, then <code>rint</code> is equivalent to <code><a href="trunc" title="c/numeric/math/trunc">trunc</a></code> </li> +<li> <code><a href="../fenv/fe_round" title="c/numeric/fenv/FE round">FE_TONEAREST</a></code>, then <code>rint</code> differs from <code><a href="round" title="c/numeric/math/round">round</a></code> in that halfway cases are rounded to even rather than away from zero. </li> +</ul> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <fenv.h> +#include <limits.h> + +int main(void) +{ +#pragma STDC FENV_ACCESS ON + fesetround(FE_TONEAREST); + printf("rounding to nearest (halfway cases to even):\n" + "rint(+2.3) = %+.1f ", rint(2.3)); + printf("rint(+2.5) = %+.1f ", rint(2.5)); + printf("rint(+3.5) = %+.1f\n", rint(3.5)); + printf("rint(-2.3) = %+.1f ", rint(-2.3)); + printf("rint(-2.5) = %+.1f ", rint(-2.5)); + printf("rint(-3.5) = %+.1f\n", rint(-3.5)); + + fesetround(FE_DOWNWARD); + printf("rounding down: \nrint(+2.3) = %+.1f ", rint(2.3)); + printf("rint(+2.5) = %+.1f ", rint(2.5)); + printf("rint(+3.5) = %+.1f\n", rint(3.5)); + printf("rint(-2.3) = %+.1f ", rint(-2.3)); + printf("rint(-2.5) = %+.1f ", rint(-2.5)); + printf("rint(-3.5) = %+.1f\n", rint(-3.5)); + printf("rounding down with lrint: \nlrint(+2.3) = %ld ", lrint(2.3)); + printf("lrint(+2.5) = %ld ", lrint(2.5)); + printf("lrint(+3.5) = %ld\n", lrint(3.5)); + printf("lrint(-2.3) = %ld ", lrint(-2.3)); + printf("lrint(-2.5) = %ld ", lrint(-2.5)); + printf("lrint(-3.5) = %ld\n", lrint(-3.5)); + + printf("lrint(-0.0) = %ld\n", lrint(-0.0)); + printf("lrint(-Inf) = %ld\n", lrint(-INFINITY)); // FE_INVALID raised + + // error handling + feclearexcept(FE_ALL_EXCEPT); + printf("rint(1.1) = %.1f\n", rint(1.1)); + if(fetestexcept(FE_INEXACT)) puts(" FE_INEXACT was raised"); + + feclearexcept(FE_ALL_EXCEPT); + printf("lrint(LONG_MIN-2048.0) = %ld\n", lrint(LONG_MIN-2048.0)); + if(fetestexcept(FE_INVALID)) puts(" FE_INVALID was raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">rounding to nearest (halfway cases to even): +rint(+2.3) = +2.0 rint(+2.5) = +2.0 rint(+3.5) = +4.0 +rint(-2.3) = -2.0 rint(-2.5) = -2.0 rint(-3.5) = -4.0 +rounding down: +rint(+2.3) = +2.0 rint(+2.5) = +2.0 rint(+3.5) = +3.0 +rint(-2.3) = -3.0 rint(-2.5) = -3.0 rint(-3.5) = -4.0 +rounding down with lrint: +lrint(+2.3) = 2 lrint(+2.5) = 2 lrint(+3.5) = 3 +lrint(-2.3) = -3 lrint(-2.5) = -3 lrint(-3.5) = -4 +lrint(-0.0) = 0 +lrint(-Inf) = -9223372036854775808 +rint(1.1) = 1.0 + FE_INEXACT was raised +lrint(LONG_MIN-2048.0) = -9223372036854775808 + FE_INVALID was raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.9.4 The rint functions (p: 184) </li> +<li> 7.12.9.5 The lrint and llrint functions (p: 184) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.6.4 The rint functions (p: 384) </li> +<li> F.10.6.5 The lrint and llrint functions (p: 384) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.9.4 The rint functions (p: 252) </li> +<li> 7.12.9.5 The lrint and llrint functions (p: 252) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.6.4 The rint functions (p: 527) </li> +<li> F.10.6.5 The lrint and llrint functions (p: 527) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.9.4 The rint functions (p: 232-233) </li> +<li> 7.12.9.5 The lrint and llrint functions (p: 233) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.6.4 The rint functions (p: 463) </li> +<li> F.9.6.5 The lrint and llrint functions (p: 463) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="trunc" title="c/numeric/math/trunc"> <span class="t-lines"><span>trunc</span><span>truncf</span><span>truncl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> rounds to nearest integer not greater in magnitude than the given value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="nearbyint" title="c/numeric/math/nearbyint"> <span class="t-lines"><span>nearbyint</span><span>nearbyintf</span><span>nearbyintl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> rounds to an integer using current rounding mode <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../fenv/feround" title="c/numeric/fenv/feround"> <span class="t-lines"><span>fegetround</span><span>fesetround</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> gets or sets rounding direction <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/rint" title="cpp/numeric/math/rint">C++ documentation</a></span> for <code>rint</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/rint" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/rint</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fround.html b/devdocs/c/numeric%2Fmath%2Fround.html new file mode 100644 index 00000000..119c6750 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fround.html @@ -0,0 +1,124 @@ + <h1 id="firstHeading" class="firstHeading">round, roundf, roundl, lround, lroundf, lroundl, llround, llroundf, llroundl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float roundf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double round( double arg );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double roundl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define round( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long lroundf( float arg );</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long lround( double arg );</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long lroundl( long double arg );</pre> +</td> <td> (7) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define lround( arg )</pre> +</td> <td> (8) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long long llroundf( float arg );</pre> +</td> <td> (9) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long long llround( double arg );</pre> +</td> <td> (10) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long long llroundl( long double arg );</pre> +</td> <td> (11) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define llround( arg )</pre> +</td> <td> (12) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the nearest integer value to <code>arg</code> (in floating-point format), rounding halfway cases away from zero, regardless of the current rounding mode.</div> <div class="t-li1"> +<span class="t-li">5-7, 9-11)</span> Computes the nearest integer value to <code>arg</code> (in integer format), rounding halfway cases away from zero, regardless of the current rounding mode.</div> <div class="t-li1"> +<span class="t-li">4,8,12)</span> Type-generic macros: If <code>arg</code> has type <code>long double</code>, <code>roundl</code>, <code>lroundl</code>, <code>llroundl</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>round</code>, <code>lround</code>, <code>llround</code> is called. Otherwise, <code>roundf</code>, <code>lroundf</code>, <code>llroundf</code> is called, respectively.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the nearest integer value to <code>arg</code>, rounding halfway cases away from zero, is returned.</p> +<div class="t-plot"> <div class="t-plot-left">Return value</div> <div class="t-plot-image-left"><img alt="math-round away zero.svg" src="data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9Im5vIj8+CjwhRE9DVFlQRSBzdmcgUFVCTElDICItLy9XM0MvL0RURCBTVkcgMS4xLy9FTiIgImh0dHA6Ly93d3cudzMub3JnL0dyYXBoaWNzL1NWRy8xLjEvRFREL3N2ZzExLmR0ZCI+CjwhLS0gQ3JlYXRlZCB3aXRoIG1hdHBsb3RsaWIgKGh0dHA6Ly9tYXRwbG90bGliLnNvdXJjZWZvcmdlLm5ldC8pIC0tPgo8c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIGhlaWdodD0iMjAwcHgiIHZlcnNpb249IjEuMSIgdmlld0JveD0iMCAwIDIwMCAyMDAiIHdpZHRoPSIyMDBweCI+CiA8ZGVmcz4KICA8c3R5bGUgdHlwZT0idGV4dC9jc3MiPgoqe3N0cm9rZS1saW5lY2FwOnNxdWFyZTtzdHJva2UtbGluZWpvaW46cm91bmQ7fQogIDwvc3R5bGU+CiA8L2RlZnM+CiA8ZyBpZD0iZmlndXJlXzEiPgogIDxnIGlkPSJwYXRjaF8xIj4KICAgPHBhdGggZD0iIE0wIDIwMCBMMjAwIDIwMCBMMjAwIDAgTDAgMCB6ICIgc3R5bGU9ImZpbGw6I2ZmZmZmZjsiLz4KICA8L2c+CiAgPGcgaWQ9ImF4ZXNfMSI+CiAgIDxnIGlkPSJwYXRjaF8yIj4KICAgIDxwYXRoIGQ9IiBNMjUgMTc3LjUgTDE4MCAxNzcuNSBMMTgwIDIyLjUgTDI1IDIyLjUgeiAiIHN0eWxlPSJmaWxsOiNmZmZmZmY7Ii8+CiAgIDwvZz4KICAgPGcgaWQ9Im1hdHBsb3RsaWIuYXhpc18xIj4KICAgIDxnIGlkPSJ4dGlja18xIj4KICAgICA8ZyBpZD0ibGluZTJkXzEiPgogICAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTM2LjA3MTQgMTc3LjUgTDM2LjA3MTQgMjIuNSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDtzdHJva2UtZGFzaGFycmF5OjEuMDAwMDAwLDMuMDAwMDAwO3N0cm9rZS1kYXNob2Zmc2V0OjAuMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMiI+CiAgICAgIDxkZWZzPgogICAgICAgPHBhdGggZD0iIE0wIDAgTDAgLTQiIGlkPSJtMDAxMmRkNGVlZiIgc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICAgPC9kZWZzPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjM2LjA3MTQyODU3MTQiIHhsaW5rOmhyZWY9IiNtMDAxMmRkNGVlZiIgeT0iMTc3LjUiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzMiPgogICAgICA8ZGVmcz4KICAgICAgIDxwYXRoIGQ9IiBNMCAwIEwwIDQiIGlkPSJtNDc2MzQ0OTY5YyIgc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICAgPC9kZWZzPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjM2LjA3MTQyODU3MTQiIHhsaW5rOmhyZWY9IiNtNDc2MzQ0OTY5YyIgeT0iMjIuNSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzEiPgogICAgICA8IS0tIOKIkjMgLS0+CiAgICAgIDxkZWZzPgogICAgICAgPHBhdGggZD0iIE00MC41NzgxIDM5LjMxMjUgUTQ3LjY1NjIgMzcuNzk2OSA1MS42MjUgMzMgUTU1LjYwOTQgMjguMjE4OCA1NS42MDk0IDIxLjE4NzUgUTU1LjYwOTQgMTAuNDA2MiA0OC4xODc1IDQuNDg0MzggUTQwLjc2NTYgLTEuNDIxODggMjcuMDkzOCAtMS40MjE4OCBRMjIuNTE1NiAtMS40MjE4OCAxNy42NTYyIC0wLjUxNTYyNSBRMTIuNzk2OSAwLjM5MDYyNSA3LjYyNSAyLjIwMzEyIEw3LjYyNSAxMS43MTg4IFExMS43MTg4IDkuMzI4MTIgMTYuNTkzOCA4LjEwOTM4IFEyMS40ODQ0IDYuODkwNjIgMjYuODEyNSA2Ljg5MDYyIFEzNi4wNzgxIDYuODkwNjIgNDAuOTM3NSAxMC41NDY5IFE0NS43OTY5IDE0LjIwMzEgNDUuNzk2OSAyMS4xODc1IFE0NS43OTY5IDI3LjY0MDYgNDEuMjgxMiAzMS4yNjU2IFEzNi43NjU2IDM0LjkwNjIgMjguNzE4OCAzNC45MDYyIEwyMC4yMTg4IDM0LjkwNjIgTDIwLjIxODggNDMuMDE1NiBMMjkuMTA5NCA0My4wMTU2IFEzNi4zNzUgNDMuMDE1NiA0MC4yMzQ0IDQ1LjkyMTkgUTQ0LjA5MzggNDguODI4MSA0NC4wOTM4IDU0LjI5NjkgUTQ0LjA5MzggNTkuOTA2MiA0MC4xMDk0IDYyLjkwNjIgUTM2LjE0MDYgNjUuOTIxOSAyOC43MTg4IDY1LjkyMTkgUTI0LjY1NjIgNjUuOTIxOSAyMC4wMTU2IDY1LjAzMTIgUTE1LjM3NSA2NC4xNTYyIDkuODEyNSA2Mi4zMTI1IEw5LjgxMjUgNzEuMDkzOCBRMTUuNDM3NSA3Mi42NTYyIDIwLjM0MzggNzMuNDM3NSBRMjUuMjUgNzQuMjE4OCAyOS41OTM4IDc0LjIxODggUTQwLjgyODEgNzQuMjE4OCA0Ny4zNTk0IDY5LjEwOTQgUTUzLjkwNjIgNjQuMDE1NiA1My45MDYyIDU1LjMyODEgUTUzLjkwNjIgNDkuMjY1NiA1MC40Mzc1IDQ1LjA5MzggUTQ2Ljk2ODggNDAuOTIxOSA0MC41NzgxIDM5LjMxMjUiIGlkPSJEZWphVnVTYW5zLTMzIi8+CiAgICAgICA8cGF0aCBkPSIgTTEwLjU5MzggMzUuNSBMNzMuMTg3NSAzNS41IEw3My4xODc1IDI3LjIwMzEgTDEwLjU5MzggMjcuMjAzMSB6ICIgaWQ9IkRlamFWdVNhbnMtMjIxMiIvPgogICAgICA8L2RlZnM+CiAgICAgIDxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDMwLjI3NDg2NjA3MTQgMTkxLjY3OTY4NzUpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0yMjEyIi8+CiAgICAgICA8dXNlIHg9IjgzLjc4OTA2MjUiIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTMzIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICA8L2c+CiAgICA8ZyBpZD0ieHRpY2tfMiI+CiAgICAgPGcgaWQ9ImxpbmUyZF80Ij4KICAgICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE01OC4yMTQzIDE3Ny41IEw1OC4yMTQzIDIyLjUiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWRhc2hhcnJheToxLjAwMDAwMCwzLjAwMDAwMDtzdHJva2UtZGFzaG9mZnNldDowLjA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzUiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjU4LjIxNDI4NTcxNDMiIHhsaW5rOmhyZWY9IiNtMDAxMmRkNGVlZiIgeT0iMTc3LjUiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzYiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjU4LjIxNDI4NTcxNDMiIHhsaW5rOmhyZWY9IiNtNDc2MzQ0OTY5YyIgeT0iMjIuNSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzIiPgogICAgICA8IS0tIOKIkjIgLS0+CiAgICAgIDxkZWZzPgogICAgICAgPHBhdGggZD0iIE0xOS4xODc1IDguMjk2ODggTDUzLjYwOTQgOC4yOTY4OCBMNTMuNjA5NCAwIEw3LjMyODEyIDAgTDcuMzI4MTIgOC4yOTY4OCBRMTIuOTM3NSAxNC4xMDk0IDIyLjYyNSAyMy44OTA2IFEzMi4zMjgxIDMzLjY4NzUgMzQuODEyNSAzNi41MzEyIFEzOS41NDY5IDQxLjg0MzggNDEuNDIxOSA0NS41MzEyIFE0My4zMTI1IDQ5LjIxODggNDMuMzEyNSA1Mi43ODEyIFE0My4zMTI1IDU4LjU5MzggMzkuMjM0NCA2Mi4yNSBRMzUuMTU2MiA2NS45MjE5IDI4LjYwOTQgNjUuOTIxOSBRMjMuOTY4OCA2NS45MjE5IDE4LjgxMjUgNjQuMzEyNSBRMTMuNjcxOSA2Mi43MDMxIDcuODEyNSA1OS40MjE5IEw3LjgxMjUgNjkuMzkwNiBRMTMuNzY1NiA3MS43ODEyIDE4LjkzNzUgNzMgUTI0LjEyNSA3NC4yMTg4IDI4LjQyMTkgNzQuMjE4OCBRMzkuNzUgNzQuMjE4OCA0Ni40ODQ0IDY4LjU0NjkgUTUzLjIxODggNjIuODkwNiA1My4yMTg4IDUzLjQyMTkgUTUzLjIxODggNDguOTIxOSA1MS41MzEyIDQ0Ljg5MDYgUTQ5Ljg1OTQgNDAuODc1IDQ1LjQwNjIgMzUuNDA2MiBRNDQuMTg3NSAzMy45ODQ0IDM3LjY0MDYgMjcuMjE4OCBRMzEuMTA5NCAyMC40NTMxIDE5LjE4NzUgOC4yOTY4OCIgaWQ9IkRlamFWdVNhbnMtMzIiLz4KICAgICAgPC9kZWZzPgogICAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSg1Mi41MDc3MjMyMTQzIDE5MS42Nzk2ODc1KXNjYWxlKDAuMDkgLTAuMDkpIj4KICAgICAgIDx1c2UgeGxpbms6aHJlZj0iI0RlamFWdVNhbnMtMjIxMiIvPgogICAgICAgPHVzZSB4PSI4My43ODkwNjI1IiB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMiIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICAgPGcgaWQ9Inh0aWNrXzMiPgogICAgIDxnIGlkPSJsaW5lMmRfNyI+CiAgICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNODAuMzU3MSAxNzcuNSBMODAuMzU3MSAyMi41IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF84Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSI4MC4zNTcxNDI4NTcxIiB4bGluazpocmVmPSIjbTAwMTJkZDRlZWYiIHk9IjE3Ny41Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF85Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSI4MC4zNTcxNDI4NTcxIiB4bGluazpocmVmPSIjbTQ3NjM0NDk2OWMiIHk9IjIyLjUiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0idGV4dF8zIj4KICAgICAgPCEtLSDiiJIxIC0tPgogICAgICA8ZGVmcz4KICAgICAgIDxwYXRoIGQ9IiBNMTIuNDA2MiA4LjI5Njg4IEwyOC41MTU2IDguMjk2ODggTDI4LjUxNTYgNjMuOTIxOSBMMTAuOTg0NCA2MC40MDYyIEwxMC45ODQ0IDY5LjM5MDYgTDI4LjQyMTkgNzIuOTA2MiBMMzguMjgxMiA3Mi45MDYyIEwzOC4yODEyIDguMjk2ODggTDU0LjM5MDYgOC4yOTY4OCBMNTQuMzkwNiAwIEwxMi40MDYyIDAgeiAiIGlkPSJEZWphVnVTYW5zLTMxIi8+CiAgICAgIDwvZGVmcz4KICAgICAgPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNzQuNjE1NDI0MTA3MSAxOTEuNTYxNTYyNSlzY2FsZSgwLjA5IC0wLjA5KSI+CiAgICAgICA8dXNlIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTIyMTIiLz4KICAgICAgIDx1c2UgeD0iODMuNzg5MDYyNSIgeGxpbms6aHJlZj0iI0RlamFWdVNhbnMtMzEiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgIDwvZz4KICAgIDxnIGlkPSJ4dGlja180Ij4KICAgICA8ZyBpZD0ibGluZTJkXzEwIj4KICAgICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0xMDIuNSAxNzcuNSBMMTAyLjUgMjIuNSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDtzdHJva2UtZGFzaGFycmF5OjEuMDAwMDAwLDMuMDAwMDAwO3N0cm9rZS1kYXNob2Zmc2V0OjAuMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMTEiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjEwMi41IiB4bGluazpocmVmPSIjbTAwMTJkZDRlZWYiIHk9IjE3Ny41Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8xMiI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTAyLjUiIHhsaW5rOmhyZWY9IiNtNDc2MzQ0OTY5YyIgeT0iMjIuNSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzQiPgogICAgICA8IS0tIDAgLS0+CiAgICAgIDxkZWZzPgogICAgICAgPHBhdGggZD0iIE0zMS43ODEyIDY2LjQwNjIgUTI0LjE3MTkgNjYuNDA2MiAyMC4zMjgxIDU4LjkwNjIgUTE2LjUgNTEuNDIxOSAxNi41IDM2LjM3NSBRMTYuNSAyMS4zOTA2IDIwLjMyODEgMTMuODkwNiBRMjQuMTcxOSA2LjM5MDYyIDMxLjc4MTIgNi4zOTA2MiBRMzkuNDUzMSA2LjM5MDYyIDQzLjI4MTIgMTMuODkwNiBRNDcuMTI1IDIxLjM5MDYgNDcuMTI1IDM2LjM3NSBRNDcuMTI1IDUxLjQyMTkgNDMuMjgxMiA1OC45MDYyIFEzOS40NTMxIDY2LjQwNjIgMzEuNzgxMiA2Ni40MDYyIE0zMS43ODEyIDc0LjIxODggUTQ0LjA0NjkgNzQuMjE4OCA1MC41MTU2IDY0LjUxNTYgUTU2Ljk4NDQgNTQuODI4MSA1Ni45ODQ0IDM2LjM3NSBRNTYuOTg0NCAxNy45Njg4IDUwLjUxNTYgOC4yNjU2MiBRNDQuMDQ2OSAtMS40MjE4OCAzMS43ODEyIC0xLjQyMTg4IFExOS41MzEyIC0xLjQyMTg4IDEzLjA2MjUgOC4yNjU2MiBRNi41OTM3NSAxNy45Njg4IDYuNTkzNzUgMzYuMzc1IFE2LjU5Mzc1IDU0LjgyODEgMTMuMDYyNSA2NC41MTU2IFExOS41MzEyIDc0LjIxODggMzEuNzgxMiA3NC4yMTg4IiBpZD0iRGVqYVZ1U2Fucy0zMCIvPgogICAgICA8L2RlZnM+CiAgICAgIDxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDEwMC4yMzI0MjE4NzUgMTkxLjY3OTY4NzUpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMCIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICAgPGcgaWQ9Inh0aWNrXzUiPgogICAgIDxnIGlkPSJsaW5lMmRfMTMiPgogICAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTEyNC42NDMgMTc3LjUgTDEyNC42NDMgMjIuNSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDtzdHJva2UtZGFzaGFycmF5OjEuMDAwMDAwLDMuMDAwMDAwO3N0cm9rZS1kYXNob2Zmc2V0OjAuMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMTQiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjEyNC42NDI4NTcxNDMiIHhsaW5rOmhyZWY9IiNtMDAxMmRkNGVlZiIgeT0iMTc3LjUiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzE1Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxMjQuNjQyODU3MTQzIiB4bGluazpocmVmPSIjbTQ3NjM0NDk2OWMiIHk9IjIyLjUiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0idGV4dF81Ij4KICAgICAgPCEtLSAxIC0tPgogICAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMjIuNjg5NTc1ODkzIDE5MS41NjE1NjI1KXNjYWxlKDAuMDkgLTAuMDkpIj4KICAgICAgIDx1c2UgeGxpbms6aHJlZj0iI0RlamFWdVNhbnMtMzEiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgIDwvZz4KICAgIDxnIGlkPSJ4dGlja182Ij4KICAgICA8ZyBpZD0ibGluZTJkXzE2Ij4KICAgICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0xNDYuNzg2IDE3Ny41IEwxNDYuNzg2IDIyLjUiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWRhc2hhcnJheToxLjAwMDAwMCwzLjAwMDAwMDtzdHJva2UtZGFzaG9mZnNldDowLjA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzE3Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxNDYuNzg1NzE0Mjg2IiB4bGluazpocmVmPSIjbTAwMTJkZDRlZWYiIHk9IjE3Ny41Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8xOCI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTQ2Ljc4NTcxNDI4NiIgeGxpbms6aHJlZj0iI200NzYzNDQ5NjljIiB5PSIyMi41Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9InRleHRfNiI+CiAgICAgIDwhLS0gMiAtLT4KICAgICAgPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMTQ0LjcwMzA1ODAzNiAxOTEuNjc5Njg3NSlzY2FsZSgwLjA5IC0wLjA5KSI+CiAgICAgICA8dXNlIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTMyIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICA8L2c+CiAgICA8ZyBpZD0ieHRpY2tfNyI+CiAgICAgPGcgaWQ9ImxpbmUyZF8xOSI+CiAgICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMTY4LjkyOSAxNzcuNSBMMTY4LjkyOSAyMi41IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8yMCI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTY4LjkyODU3MTQyOSIgeGxpbms6aHJlZj0iI20wMDEyZGQ0ZWVmIiB5PSIxNzcuNSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMjEiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjE2OC45Mjg1NzE0MjkiIHhsaW5rOmhyZWY9IiNtNDc2MzQ0OTY5YyIgeT0iMjIuNSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzciPgogICAgICA8IS0tIDMgLS0+CiAgICAgIDxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDE2Ni43NjkyNzQ1NTQgMTkxLjY3OTY4NzUpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMyIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICA8L2c+CiAgIDxnIGlkPSJtYXRwbG90bGliLmF4aXNfMiI+CiAgICA8ZyBpZD0ieXRpY2tfMSI+CiAgICAgPGcgaWQ9ImxpbmUyZF8yMiI+CiAgICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMjUgMTY2LjQyOSBMMTgwIDE2Ni40MjkiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWRhc2hhcnJheToxLjAwMDAwMCwzLjAwMDAwMDtzdHJva2UtZGFzaG9mZnNldDowLjA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzIzIj4KICAgICAgPGRlZnM+CiAgICAgICA8cGF0aCBkPSIgTTAgMCBMNCAwIiBpZD0ibWU4YTg1ZjdiZjYiIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICAgIDwvZGVmcz4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIyNS4wIiB4bGluazpocmVmPSIjbWU4YTg1ZjdiZjYiIHk9IjE2Ni40Mjg1NzE0MjkiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzI0Ij4KICAgICAgPGRlZnM+CiAgICAgICA8cGF0aCBkPSIgTTAgMCBMLTQgMCIgaWQ9Im0xYTMyMDA1ZGVhIiBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgICA8L2RlZnM+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTgwLjAiIHhsaW5rOmhyZWY9IiNtMWEzMjAwNWRlYSIgeT0iMTY2LjQyODU3MTQyOSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzgiPgogICAgICA8IS0tIOKIkjMgLS0+CiAgICAgIDxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDUuOTA2ODc1IDE2OS43MDQ0MzA4MDQpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0yMjEyIi8+CiAgICAgICA8dXNlIHg9IjgzLjc4OTA2MjUiIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTMzIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICA8L2c+CiAgICA8ZyBpZD0ieXRpY2tfMiI+CiAgICAgPGcgaWQ9ImxpbmUyZF8yNSI+CiAgICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMjUgMTQ0LjI4NiBMMTgwIDE0NC4yODYiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWRhc2hhcnJheToxLjAwMDAwMCwzLjAwMDAwMDtzdHJva2UtZGFzaG9mZnNldDowLjA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzI2Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIyNS4wIiB4bGluazpocmVmPSIjbWU4YTg1ZjdiZjYiIHk9IjE0NC4yODU3MTQyODYiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzI3Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxODAuMCIgeGxpbms6aHJlZj0iI20xYTMyMDA1ZGVhIiB5PSIxNDQuMjg1NzE0Mjg2Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9InRleHRfOSI+CiAgICAgIDwhLS0g4oiSMiAtLT4KICAgICAgPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNi4wODY4NzUgMTQ3LjYyNTU1ODAzNilzY2FsZSgwLjA5IC0wLjA5KSI+CiAgICAgICA8dXNlIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTIyMTIiLz4KICAgICAgIDx1c2UgeD0iODMuNzg5MDYyNSIgeGxpbms6aHJlZj0iI0RlamFWdVNhbnMtMzIiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgIDwvZz4KICAgIDxnIGlkPSJ5dGlja18zIj4KICAgICA8ZyBpZD0ibGluZTJkXzI4Ij4KICAgICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0yNSAxMjIuMTQzIEwxODAgMTIyLjE0MyIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDtzdHJva2UtZGFzaGFycmF5OjEuMDAwMDAwLDMuMDAwMDAwO3N0cm9rZS1kYXNob2Zmc2V0OjAuMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMjkiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjI1LjAiIHhsaW5rOmhyZWY9IiNtZThhODVmN2JmNiIgeT0iMTIyLjE0Mjg1NzE0MyIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMzAiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjE4MC4wIiB4bGluazpocmVmPSIjbTFhMzIwMDVkZWEiIHk9IjEyMi4xNDI4NTcxNDMiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0idGV4dF8xMCI+CiAgICAgIDwhLS0g4oiSMSAtLT4KICAgICAgPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNi4wMTY1NjI1IDEyNS40MjM2MzgzOTMpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0yMjEyIi8+CiAgICAgICA8dXNlIHg9IjgzLjc4OTA2MjUiIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTMxIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICA8L2c+CiAgICA8ZyBpZD0ieXRpY2tfNCI+CiAgICAgPGcgaWQ9ImxpbmUyZF8zMSI+CiAgICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMjUgMTAwIEwxODAgMTAwIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8zMiI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMjUuMCIgeGxpbms6aHJlZj0iI21lOGE4NWY3YmY2IiB5PSIxMDAuMCIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMzMiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjE4MC4wIiB4bGluazpocmVmPSIjbTFhMzIwMDVkZWEiIHk9IjEwMC4wIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9InRleHRfMTEiPgogICAgICA8IS0tIDAgLS0+CiAgICAgIDxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDEyLjk2NDg0Mzc1IDEwMy4yNzU4NTkzNzUpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMCIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICAgPGcgaWQ9Inl0aWNrXzUiPgogICAgIDxnIGlkPSJsaW5lMmRfMzQiPgogICAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTI1IDc3Ljg1NzEgTDE4MCA3Ny44NTcxIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8zNSI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMjUuMCIgeGxpbms6aHJlZj0iI21lOGE4NWY3YmY2IiB5PSI3Ny44NTcxNDI4NTcxIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8zNiI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTgwLjAiIHhsaW5rOmhyZWY9IiNtMWEzMjAwNWRlYSIgeT0iNzcuODU3MTQyODU3MSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzEyIj4KICAgICAgPCEtLSAxIC0tPgogICAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMy41OTM0Mzc1IDgxLjEzNzkyNDEwNzEpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICAgPGcgaWQ9Inl0aWNrXzYiPgogICAgIDxnIGlkPSJsaW5lMmRfMzciPgogICAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTI1IDU1LjcxNDMgTDE4MCA1NS43MTQzIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8zOCI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMjUuMCIgeGxpbms6aHJlZj0iI21lOGE4NWY3YmY2IiB5PSI1NS43MTQyODU3MTQzIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8zOSI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTgwLjAiIHhsaW5rOmhyZWY9IiNtMWEzMjAwNWRlYSIgeT0iNTUuNzE0Mjg1NzE0MyIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzEzIj4KICAgICAgPCEtLSAyIC0tPgogICAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMy4zMzQ2ODc1IDU5LjA1NDEyOTQ2NDMpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMiIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICAgPGcgaWQ9Inl0aWNrXzciPgogICAgIDxnIGlkPSJsaW5lMmRfNDAiPgogICAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTI1IDMzLjU3MTQgTDE4MCAzMy41NzE0IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF80MSI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMjUuMCIgeGxpbms6aHJlZj0iI21lOGE4NWY3YmY2IiB5PSIzMy41NzE0Mjg1NzE0Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF80MiI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTgwLjAiIHhsaW5rOmhyZWY9IiNtMWEzMjAwNWRlYSIgeT0iMzMuNTcxNDI4NTcxNCIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzE0Ij4KICAgICAgPCEtLSAzIC0tPgogICAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMy4xODE0MDYyNSAzNi44NDcyODc5NDY0KXNjYWxlKDAuMDkgLTAuMDkpIj4KICAgICAgIDx1c2UgeGxpbms6aHJlZj0iI0RlamFWdVNhbnMtMzMiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgIDwvZz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzQzIj4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMjUgMTY2LjQyOSBMNDcuMTQyOSAxNjYuNDI5IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMGZmO3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF80NCI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTQ3LjE0MjkgMTQ0LjI4NiBMNjkuMjg1NyAxNDQuMjg2IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMGZmO3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF80NSI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTY5LjI4NTcgMTIyLjE0MyBMOTEuNDI4NiAxMjIuMTQzIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMGZmO3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF80NiI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTkxLjQyODYgMTAwIEwxMTMuNTcxIDEwMCIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDBmZjtzdHJva2Utd2lkdGg6MC41OyIvPgogICA8L2c+CiAgIDxnIGlkPSJsaW5lMmRfNDciPgogICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0xMTMuNTcxIDc3Ljg1NzEgTDEzNS43MTQgNzcuODU3MSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDBmZjtzdHJva2Utd2lkdGg6MC41OyIvPgogICA8L2c+CiAgIDxnIGlkPSJsaW5lMmRfNDgiPgogICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0xMzUuNzE0IDU1LjcxNDMgTDE1Ny44NTcgNTUuNzE0MyIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDBmZjtzdHJva2Utd2lkdGg6MC41OyIvPgogICA8L2c+CiAgIDxnIGlkPSJsaW5lMmRfNDkiPgogICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0xNTcuODU3IDMzLjU3MTQgTDE4MCAzMy41NzE0IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMGZmO3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF81MCI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTI1IDE2Ni40MjkiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwZmY7Ii8+CiAgICA8ZGVmcz4KICAgICA8cGF0aCBkPSIgTTAgMy43NSBDMC45OTQ1MTIgMy43NSAxLjk0ODQyIDMuMzU0ODggMi42NTE2NSAyLjY1MTY1IEMzLjM1NDg4IDEuOTQ4NDIgMy43NSAwLjk5NDUxMiAzLjc1IDAgQzMuNzUgLTAuOTk0NTEyIDMuMzU0ODggLTEuOTQ4NDIgMi42NTE2NSAtMi42NTE2NSBDMS45NDg0MiAtMy4zNTQ4OCAwLjk5NDUxMiAtMy43NSAwIC0zLjc1IEMtMC45OTQ1MTIgLTMuNzUgLTEuOTQ4NDIgLTMuMzU0ODggLTIuNjUxNjUgLTIuNjUxNjUgQy0zLjM1NDg4IC0xLjk0ODQyIC0zLjc1IC0wLjk5NDUxMiAtMy43NSAwIEMtMy43NSAwLjk5NDUxMiAtMy4zNTQ4OCAxLjk0ODQyIC0yLjY1MTY1IDIuNjUxNjUgQy0xLjk0ODQyIDMuMzU0ODggLTAuOTk0NTEyIDMuNzUgMCAzLjc1IHogIiBpZD0ibWUyNzgwNjQyZTIiIHN0eWxlPSJzdHJva2U6IzAwMDBmZjtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICA8L2RlZnM+CiAgICA8ZyBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIj4KICAgICA8dXNlIHN0eWxlPSJmaWxsOiNmZmZmZmY7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMjUuMCIgeGxpbms6aHJlZj0iI21lMjc4MDY0MmUyIiB5PSIxNjYuNDI4NTcxNDI5Ii8+CiAgICA8L2c+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF81MSI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTQ3LjE0MjkgMTY2LjQyOSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwODAwMDsiLz4KICAgIDxkZWZzPgogICAgIDxwYXRoIGQ9IiBNMCAzLjc1IEMwLjk5NDUxMiAzLjc1IDEuOTQ4NDIgMy4zNTQ4OCAyLjY1MTY1IDIuNjUxNjUgQzMuMzU0ODggMS45NDg0MiAzLjc1IDAuOTk0NTEyIDMuNzUgMCBDMy43NSAtMC45OTQ1MTIgMy4zNTQ4OCAtMS45NDg0MiAyLjY1MTY1IC0yLjY1MTY1IEMxLjk0ODQyIC0zLjM1NDg4IDAuOTk0NTEyIC0zLjc1IDAgLTMuNzUgQy0wLjk5NDUxMiAtMy43NSAtMS45NDg0MiAtMy4zNTQ4OCAtMi42NTE2NSAtMi42NTE2NSBDLTMuMzU0ODggLTEuOTQ4NDIgLTMuNzUgLTAuOTk0NTEyIC0zLjc1IDAgQy0zLjc1IDAuOTk0NTEyIC0zLjM1NDg4IDEuOTQ4NDIgLTIuNjUxNjUgMi42NTE2NSBDLTEuOTQ4NDIgMy4zNTQ4OCAtMC45OTQ1MTIgMy43NSAwIDMuNzUgeiAiIGlkPSJtZTUzYjdiYjZkMiIgc3R5bGU9InN0cm9rZTojMDAwMGZmO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgIDwvZGVmcz4KICAgIDxnIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiPgogICAgIDx1c2Ugc3R5bGU9ImZpbGw6IzAwMDBmZjtzdHJva2U6IzAwMDBmZjtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSI0Ny4xNDI4NTcxNDI5IiB4bGluazpocmVmPSIjbWU1M2I3YmI2ZDIiIHk9IjE2Ni40Mjg1NzE0MjkiLz4KICAgIDwvZz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzUyIj4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNNDcuMTQyOSAxNDQuMjg2IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojZmYwMDAwOyIvPgogICAgPGcgY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSI+CiAgICAgPHVzZSBzdHlsZT0iZmlsbDojZmZmZmZmO3N0cm9rZTojMDAwMGZmO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjQ3LjE0Mjg1NzE0MjkiIHhsaW5rOmhyZWY9IiNtZTI3ODA2NDJlMiIgeT0iMTQ0LjI4NTcxNDI4NiIvPgogICAgPC9nPgogICA8L2c+CiAgIDxnIGlkPSJsaW5lMmRfNTMiPgogICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE02OS4yODU3IDE0NC4yODYiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMGJmYmY7Ii8+CiAgICA8ZyBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIj4KICAgICA8dXNlIHN0eWxlPSJmaWxsOiMwMDAwZmY7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iNjkuMjg1NzE0Mjg1NyIgeGxpbms6aHJlZj0iI21lNTNiN2JiNmQyIiB5PSIxNDQuMjg1NzE0Mjg2Ii8+CiAgICA8L2c+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF81NCI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTY5LjI4NTcgMTIyLjE0MyIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6I2JmMDBiZjsiLz4KICAgIDxnIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiPgogICAgIDx1c2Ugc3R5bGU9ImZpbGw6I2ZmZmZmZjtzdHJva2U6IzAwMDBmZjtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSI2OS4yODU3MTQyODU3IiB4bGluazpocmVmPSIjbWUyNzgwNjQyZTIiIHk9IjEyMi4xNDI4NTcxNDMiLz4KICAgIDwvZz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzU1Ij4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNOTEuNDI4NiAxMjIuMTQzIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojYmZiZjAwOyIvPgogICAgPGcgY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSI+CiAgICAgPHVzZSBzdHlsZT0iZmlsbDojMDAwMGZmO3N0cm9rZTojMDAwMGZmO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjkxLjQyODU3MTQyODYiIHhsaW5rOmhyZWY9IiNtZTUzYjdiYjZkMiIgeT0iMTIyLjE0Mjg1NzE0MyIvPgogICAgPC9nPgogICA8L2c+CiAgIDxnIGlkPSJsaW5lMmRfNTYiPgogICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE05MS40Mjg2IDEwMCIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDsiLz4KICAgIDxnIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiPgogICAgIDx1c2Ugc3R5bGU9ImZpbGw6I2ZmZmZmZjtzdHJva2U6IzAwMDBmZjtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSI5MS40Mjg1NzE0Mjg2IiB4bGluazpocmVmPSIjbWUyNzgwNjQyZTIiIHk9IjEwMC4wIi8+CiAgICA8L2c+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF81NyI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTExMy41NzEgMTAwIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMGZmOyIvPgogICAgPGcgY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSI+CiAgICAgPHVzZSBzdHlsZT0iZmlsbDojZmZmZmZmO3N0cm9rZTojMDAwMGZmO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjExMy41NzE0Mjg1NzEiIHhsaW5rOmhyZWY9IiNtZTI3ODA2NDJlMiIgeT0iMTAwLjAiLz4KICAgIDwvZz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzU4Ij4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMTEzLjU3MSA3Ny44NTcxIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDA4MDAwOyIvPgogICAgPGcgY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSI+CiAgICAgPHVzZSBzdHlsZT0iZmlsbDojMDAwMGZmO3N0cm9rZTojMDAwMGZmO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjExMy41NzE0Mjg1NzEiIHhsaW5rOmhyZWY9IiNtZTUzYjdiYjZkMiIgeT0iNzcuODU3MTQyODU3MSIvPgogICAgPC9nPgogICA8L2c+CiAgIDxnIGlkPSJsaW5lMmRfNTkiPgogICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0xMzUuNzE0IDc3Ljg1NzEiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiNmZjAwMDA7Ii8+CiAgICA8ZyBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIj4KICAgICA8dXNlIHN0eWxlPSJmaWxsOiNmZmZmZmY7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTM1LjcxNDI4NTcxNCIgeGxpbms6aHJlZj0iI21lMjc4MDY0MmUyIiB5PSI3Ny44NTcxNDI4NTcxIi8+CiAgICA8L2c+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF82MCI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTEzNS43MTQgNTUuNzE0MyIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwYmZiZjsiLz4KICAgIDxnIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiPgogICAgIDx1c2Ugc3R5bGU9ImZpbGw6IzAwMDBmZjtzdHJva2U6IzAwMDBmZjtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxMzUuNzE0Mjg1NzE0IiB4bGluazpocmVmPSIjbWU1M2I3YmI2ZDIiIHk9IjU1LjcxNDI4NTcxNDMiLz4KICAgIDwvZz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzYxIj4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMTU3Ljg1NyA1NS43MTQzIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojYmYwMGJmOyIvPgogICAgPGcgY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSI+CiAgICAgPHVzZSBzdHlsZT0iZmlsbDojZmZmZmZmO3N0cm9rZTojMDAwMGZmO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjE1Ny44NTcxNDI4NTciIHhsaW5rOmhyZWY9IiNtZTI3ODA2NDJlMiIgeT0iNTUuNzE0Mjg1NzE0MyIvPgogICAgPC9nPgogICA8L2c+CiAgIDxnIGlkPSJsaW5lMmRfNjIiPgogICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0xNTcuODU3IDMzLjU3MTQiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiNiZmJmMDA7Ii8+CiAgICA8ZyBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIj4KICAgICA8dXNlIHN0eWxlPSJmaWxsOiMwMDAwZmY7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTU3Ljg1NzE0Mjg1NyIgeGxpbms6aHJlZj0iI21lNTNiN2JiNmQyIiB5PSIzMy41NzE0Mjg1NzE0Ii8+CiAgICA8L2c+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF82MyI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTE4MCAzMy41NzE0IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwOyIvPgogICAgPGcgY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSI+CiAgICAgPHVzZSBzdHlsZT0iZmlsbDojZmZmZmZmO3N0cm9rZTojMDAwMGZmO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjE4MC4wIiB4bGluazpocmVmPSIjbWUyNzgwNjQyZTIiIHk9IjMzLjU3MTQyODU3MTQiLz4KICAgIDwvZz4KICAgPC9nPgogICA8ZyBpZD0icGF0Y2hfMyI+CiAgICA8cGF0aCBkPSIgTTI1IDIyLjUgTDE4MCAyMi41IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwOyIvPgogICA8L2c+CiAgIDxnIGlkPSJwYXRjaF80Ij4KICAgIDxwYXRoIGQ9IiBNMTgwIDE3Ny41IEwxODAgMjIuNSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDsiLz4KICAgPC9nPgogICA8ZyBpZD0icGF0Y2hfNSI+CiAgICA8cGF0aCBkPSIgTTI1IDE3Ny41IEwxODAgMTc3LjUiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwMDA7Ii8+CiAgIDwvZz4KICAgPGcgaWQ9InBhdGNoXzYiPgogICAgPHBhdGggZD0iIE0yNSAxNzcuNSBMMjUgMjIuNSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDsiLz4KICAgPC9nPgogIDwvZz4KIDwvZz4KIDxkZWZzPgogIDxjbGlwUGF0aCBpZD0icDQwZmVjMTE1M2YiPgogICA8cmVjdCBoZWlnaHQ9IjE1NS4wIiB3aWR0aD0iMTU1LjAiIHg9IjI1LjAiIHk9IjIyLjUiLz4KICA8L2NsaXBQYXRoPgogPC9kZWZzPgo8L3N2Zz4K" width="200" height="200"></div> <div class="t-plot-bottom">Argument</div> </div> <p>If a domain error occurs, an implementation-defined value is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a>.</p> +<p>If the result of <code>lround</code> or <code>llround</code> is outside the range representable by the return type, a domain error or a range error may occur.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559), For the <code>round</code>, <code>roundf</code>, and <code>roundl</code> function:</p> +<ul> +<li> The current <a href="../fenv/fe_round" title="c/numeric/fenv/FE round">rounding mode</a> has no effect. </li> +<li> If <code>arg</code> is ±∞, it is returned, unmodified </li> +<li> If <code>arg</code> is ±0, it is returned, unmodified </li> +<li> If <code>arg</code> is NaN, NaN is returned </li> +</ul> For <code>lround</code> and <code>llround</code> families of functions: <ul> +<li> <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> is never raised </li> +<li> The current <a href="../fenv/fe_round" title="c/numeric/fenv/FE round">rounding mode</a> has no effect. </li> +<li> If <code>arg</code> is ±∞, <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised and an implementation-defined value is returned </li> +<li> If the result of the rounding is outside the range of the return type, <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised and an implementation-defined value is returned </li> +<li> If <code>arg</code> is NaN, <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised and an implementation-defined value is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p><code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> may be (but isn't required to be) raised by <code>round</code> when rounding a non-integer finite value.</p> +<p>The largest representable floating-point values are exact integers in all standard floating-point formats, so <code>round</code> never overflows on its own; however the result may overflow any integer type (including <code><a href="../../types/integer" title="c/types/integer">intmax_t</a></code>), when stored in an integer variable.</p> +<p><a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/lround.html">POSIX specifies</a> that all cases where <code>lround</code> or <code>llround</code> raise <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> are domain errors.</p> +<p>The <code>double</code> version of <code>round</code> behaves as if implemented as follows:</p> +<div class="c source-c"><pre data-language="c">#include <math.h> +double round(double x) +{ + return signbit(x) ? ceil(x - 0.5) : floor(x + 0.5); +}</pre></div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <fenv.h> +#include <limits.h> + +// #pragma STDC FENV_ACCESS ON + +int main(void) +{ + // round + printf("round(+2.3) = %+.1f ", round(2.3)); + printf("round(+2.5) = %+.1f ", round(2.5)); + printf("round(+2.7) = %+.1f\n", round(2.7)); + printf("round(-2.3) = %+.1f ", round(-2.3)); + printf("round(-2.5) = %+.1f ", round(-2.5)); + printf("round(-2.7) = %+.1f\n", round(-2.7)); + + printf("round(-0.0) = %+.1f\n", round(-0.0)); + printf("round(-Inf) = %+f\n", round(-INFINITY)); + + // lround + printf("lround(+2.3) = %ld ", lround(2.3)); + printf("lround(+2.5) = %ld ", lround(2.5)); + printf("lround(+2.7) = %ld\n", lround(2.7)); + printf("lround(-2.3) = %ld ", lround(-2.3)); + printf("lround(-2.5) = %ld ", lround(-2.5)); + printf("lround(-2.7) = %ld\n", lround(-2.7)); + + printf("lround(-0.0) = %ld\n", lround(-0.0)); + printf("lround(-Inf) = %ld\n", lround(-INFINITY)); // FE_INVALID raised + + // error handling + feclearexcept(FE_ALL_EXCEPT); + printf("lround(LONG_MAX+1.5) = %ld\n", lround(LONG_MAX+1.5)); + if(fetestexcept(FE_INVALID)) puts(" FE_INVALID was raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">round(+2.3) = +2.0 round(+2.5) = +3.0 round(+2.7) = +3.0 +round(-2.3) = -2.0 round(-2.5) = -3.0 round(-2.7) = -3.0 +round(-0.0) = -0.0 +round(-Inf) = -inf +lround(+2.3) = 2 lround(+2.5) = 3 lround(+2.7) = 3 +lround(-2.3) = -2 lround(-2.5) = -3 lround(-2.7) = -3 +lround(-0.0) = 0 +lround(-Inf) = -9223372036854775808 +lround(LONG_MAX+1.5) = -9223372036854775808 + FE_INVALID was raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.9.6 The round functions (p: 184) </li> +<li> 7.12.9.7 The lround and llround functions (p: 184-185) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.6.6 The round functions (p: 384) </li> +<li> F.10.6.7 The lround and llround functions (p: 385) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.9.6 The round functions (p: 253) </li> +<li> 7.12.9.7 The lround and llround functions (p: 253) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.6.6 The round functions (p: 527) </li> +<li> F.10.6.7 The lround and llround functions (p: 528) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.9.6 The round functions (p: 233) </li> +<li> 7.12.9.7 The lround and llround functions (p: 234) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.6.6 The round functions (p: 464) </li> +<li> F.9.6.7 The lround and llround functions (p: 464) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="floor" title="c/numeric/math/floor"> <span class="t-lines"><span>floor</span><span>floorf</span><span>floorl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes largest integer not greater than the given value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ceil" title="c/numeric/math/ceil"> <span class="t-lines"><span>ceil</span><span>ceilf</span><span>ceill</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes smallest integer not less than the given value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="trunc" title="c/numeric/math/trunc"> <span class="t-lines"><span>trunc</span><span>truncf</span><span>truncl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> rounds to nearest integer not greater in magnitude than the given value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/round" title="cpp/numeric/math/round">C++ documentation</a></span> for <code>round</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/round" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/round</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Froundeven.html b/devdocs/c/numeric%2Fmath%2Froundeven.html new file mode 100644 index 00000000..418b93ae --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Froundeven.html @@ -0,0 +1,57 @@ + <h1 id="firstHeading" class="firstHeading">roundeven, roundevenf, roundevenl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">float roundevenf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">double roundeven( double arg );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">long double roundevenl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">#define roundeven( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the nearest integer value to <code>arg</code> (in floating-point format), rounding halfway cases to nearest even integer, regardless of the current rounding mode.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>arg</code> has type <code>long double</code>, <code>roundevenl</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>roundeven</code> is called. Otherwise, <code>roundevenf</code> is called, respectively.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the nearest integer value to <code>arg</code>, rounding halfway cases to nearest even integer, is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>This function is not subject to any of the errors specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> is never raised </li> +<li> If <code>arg</code> is ±∞, it is returned, unmodified </li> +<li> If <code>arg</code> is ±0, it is returned, unmodified </li> +<li> If <code>arg</code> is NaN, NaN is returned </li> +</ul> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <math.h> +#include <stdio.h> +int main(void) +{ + printf("roundeven(+2.4) = %+.1f\n", roundeven(2.4)); + printf("roundeven(-2.4) = %+.1f\n", roundeven(-2.4)); + printf("roundeven(+2.5) = %+.1f\n", roundeven(2.5)); + printf("roundeven(-2.5) = %+.1f\n", roundeven(-2.5)); + printf("roundeven(+2.6) = %+.1f\n", roundeven(2.6)); + printf("roundeven(-2.6) = %+.1f\n", roundeven(-2.6)); + printf("roundeven(+3.5) = %+.1f\n", roundeven(3.5)); + printf("roundeven(-3.5) = %+.1f\n", roundeven(-3.5)); + printf("roundeven(-0.0) = %+.1f\n", roundeven(-0.0)); + printf("roundeven(-Inf) = %+f\n", roundeven(-INFINITY)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">roundeven(+2.4) = +2.0 +roundeven(-2.4) = -2.0 +roundeven(+2.5) = +2.0 +roundeven(-2.5) = -2.0 +roundeven(+2.6) = +3.0 +roundeven(-2.6) = -3.0 +roundeven(+3.5) = +4.0 +roundeven(-3.5) = -4.0 +roundeven(-0.0) = -0.0 +roundeven(-Inf) = -inf</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.12.9.8 The roundeven functions (p: 265-266) </li> +<li> 7.27 Type-generic math <tgmath.h> (p: 386-390) </li> +<li> F.10.6.8 The roundeven functions (p: 532) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="rint" title="c/numeric/math/rint"> <span class="t-lines"><span>rint</span><span>rintf</span><span>rintl</span><span>lrint</span><span>lrintf</span><span>lrintl</span><span>llrint</span><span>llrintf</span><span>llrintl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> rounds to an integer using current rounding mode with <br> exception if the result differs <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="round" title="c/numeric/math/round"> <span class="t-lines"><span>round</span><span>roundf</span><span>roundl</span><span>lround</span><span>lroundf</span><span>lroundl</span><span>llround</span><span>llroundf</span><span>llroundl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> rounds to nearest integer, rounding away from zero in halfway cases <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/roundeven" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/roundeven</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fscalbn.html b/devdocs/c/numeric%2Fmath%2Fscalbn.html new file mode 100644 index 00000000..0a6b35c7 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fscalbn.html @@ -0,0 +1,99 @@ + <h1 id="firstHeading" class="firstHeading">scalbn, scalbnf, scalbnl, scalbln, scalblnf, scalblnl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float scalbnf( float arg, int exp );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double scalbn( double arg, int exp );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double scalbnl( long double arg, int exp );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define scalbn( arg, exp )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float scalblnf( float arg, long exp );</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double scalbln( double arg, long exp );</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double scalblnl( long double arg, long exp );</pre> +</td> <td> (7) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define scalbln( arg, exp )</pre> +</td> <td> (8) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3,5-7)</span> Multiplies a floating point value <code>arg</code> by <code><a href="../../types/limits" title="c/types/limits">FLT_RADIX</a></code> raised to power <code><a href="http://en.cppreference.com/w/c/numeric/math/exp"><span class="kw657">exp</span></a></code>.</div> <div class="t-li1"> +<span class="t-li">4,8)</span> Type-generic macros: If <code>arg</code> has type <code>long double</code>, <code>scalbnl</code> or <code>scalblnl</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>scalbn</code> or <code>scalbln</code> is called. Otherwise, <code>scalbnf</code> or <code>scalblnf</code> is called, respectively.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> <tr class="t-par"> <td> exp </td> <td> - </td> <td> integer value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, <code>arg</code> multiplied by <code><a href="../../types/limits" title="c/types/limits">FLT_RADIX</a></code> to the power of <code><a href="http://en.cppreference.com/w/c/numeric/math/exp"><span class="kw657">exp</span></a></code> (arg×FLT_RADIX<sup class="t-su">exp</sup>) is returned.</p> +<p>If a range error due to overflow occurs, <code><a href="huge_val" title="c/numeric/math/HUGE VAL">±HUGE_VAL</a></code>, <code>±HUGE_VALF</code>, or <code>±HUGE_VALL</code> is returned.</p> +<p>If a range error due to underflow occurs, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> Unless a range error occurs, <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> is never raised (the result is exact). </li> +<li> Unless a range error occurs, the <a href="../fenv/fe_round" title="c/numeric/fenv/FE round">current rounding mode</a> is ignored. </li> +<li> If <code>arg</code> is ±0, it is returned, unmodified. </li> +<li> If <code>arg</code> is ±∞, it is returned, unmodified. </li> +<li> If <code><a href="http://en.cppreference.com/w/c/numeric/math/exp"><span class="kw657">exp</span></a></code> is 0, then <code>arg</code> is returned, unmodified. </li> +<li> If <code>arg</code> is NaN, NaN is returned. </li> +</ul> <h3 id="Notes"> Notes</h3> <p>On binary systems (where <code><a href="../../types/limits" title="c/types/limits">FLT_RADIX</a></code> is <code>2</code>), <code>scalbn</code> is equivalent to <code><a href="ldexp" title="c/numeric/math/ldexp">ldexp</a></code>.</p> +<p>Although <code>scalbn</code> and <code>scalbln</code> are specified to perform the operation efficiently, on many implementations they are less efficient than multiplication or division by a power of two using arithmetic operators.</p> +<p>The <code>scalbln</code> function is provided because the factor required to scale from the smallest positive floating-point value to the largest finite one may be greater than <code>32767</code>, the standard-guaranteed <code><a href="../../types/limits" title="c/types/limits">INT_MAX</a></code>. In particular, for the 80-bit <code>long double</code>, the factor is <code>32828</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <errno.h> +#include <fenv.h> +#include <float.h> +#include <math.h> +#include <stdio.h> + +// #pragma STDC FENV_ACCESS ON + +int main(void) +{ + printf("scalbn(7, -4) = %f\n", scalbn(7, -4)); + printf("scalbn(1, -1074) = %g (minimum positive subnormal double)\n", + scalbn(1, -1074)); + printf("scalbn(nextafter(1,0), 1024) = %g (largest finite double)\n", + scalbn(nextafter(1,0), 1024)); + + // special values + printf("scalbn(-0, 10) = %f\n", scalbn(-0.0, 10)); + printf("scalbn(-Inf, -1) = %f\n", scalbn(-INFINITY, -1)); + + // error handling + errno = 0; feclearexcept(FE_ALL_EXCEPT); + printf("scalbn(1, 1024) = %f\n", scalbn(1, 1024)); + if (errno == ERANGE) + perror(" errno == ERANGE"); + if (fetestexcept(FE_OVERFLOW)) + puts(" FE_OVERFLOW raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">scalbn(7, -4) = 0.437500 +scalbn(1, -1074) = 4.94066e-324 (minimum positive subnormal double) +scalbn(nextafter(1,0), 1024) = 1.79769e+308 (largest finite double) +scalbn(-0, 10) = -0.000000 +scalbn(-Inf, -1) = -inf +scalbn(1, 1024) = inf + errno == ERANGE: Numerical result out of range + FE_OVERFLOW raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.12.6.13 The scalbn functions (p: TBD) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: TBD) </li> +<li> F.10.3.13 The scalbn functions (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.6.13 The scalbn functions (p: TBD) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: TBD) </li> +<li> F.10.3.13 The scalbn functions (p: TBD) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.6.13 The scalbn functions (p: 247) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.3.13 The scalbn functions (p: 523) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.6.13 The scalbn functions (p: 228) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.3.13 The scalbn functions (p: 460) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="frexp" title="c/numeric/math/frexp"> <span class="t-lines"><span>frexp</span><span>frexpf</span><span>frexpl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> breaks a number into significand and a power of <code>2</code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ldexp" title="c/numeric/math/ldexp"> <span class="t-lines"><span>ldexp</span><span>ldexpf</span><span>ldexpl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> multiplies a number by <code>2</code> raised to a power <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/scalbn" title="cpp/numeric/math/scalbn">C++ documentation</a></span> for <code>scalbn</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/scalbn" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/scalbn</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fsignbit.html b/devdocs/c/numeric%2Fmath%2Fsignbit.html new file mode 100644 index 00000000..dc7e42da --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fsignbit.html @@ -0,0 +1,35 @@ + <h1 id="firstHeading" class="firstHeading">signbit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define signbit( arg ) /* implementation defined */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Determines if the given floating point number <code>arg</code> is negative. The macro returns an integral value.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Nonzero integral value if <code>arg</code> is negative, <code>0</code> otherwise.</p> +<h3 id="Notes"> Notes</h3> <p>This macro detects the sign bit of zeroes, infinities, and NaNs. Along with <code><a href="copysign" title="c/numeric/math/copysign">copysign</a></code>, this macro is one of the only two portable ways to examine the sign of a NaN.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <math.h> +#include <stdio.h> + +int main(void) +{ + printf("signbit(+0.0) = %d\n", signbit(+0.0)); + printf("signbit(-0.0) = %d\n", signbit(-0.0)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">signbit(+0.0) = 0 +signbit(-0.0) = 128</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.12.3.6 The signbit macro (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.12.3.6 The signbit macro (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.12.3.6 The signbit macro (p: 237) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.12.3.6 The signbit macro (p: 218) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fabs" title="c/numeric/math/fabs"> <span class="t-lines"><span>fabs</span><span>fabsf</span><span>fabsl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes absolute value of a floating-point value (\(\small{|x|}\)|x|) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="copysign" title="c/numeric/math/copysign"> <span class="t-lines"><span>copysign</span><span>copysignf</span><span>copysignl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> produces a value with the magnitude of a given value and the sign of another given value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/signbit" title="cpp/numeric/math/signbit">C++ documentation</a></span> for <code>signbit</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/signbit" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/signbit</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fsin.html b/devdocs/c/numeric%2Fmath%2Fsin.html new file mode 100644 index 00000000..18a0ebb1 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fsin.html @@ -0,0 +1,104 @@ + <h1 id="firstHeading" class="firstHeading">sin, sinf, sinl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float sinf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double sin( double arg );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double sinl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal32 sind32( _Decimal32 arg );</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal64 sind64( _Decimal64 arg );</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal128 sind128( _Decimal128 arg );</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define sin( arg )</pre> +</td> <td> (7) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the sine of <code>arg</code> (measured in radians).</div> <div class="t-li1"> +<span class="t-li">7)</span> Type-generic macro: If the argument has type <code>long double</code>, <span class="t-v">(3)</span> (<code>sinl</code>) is called. Otherwise, if the argument has integer type or the type <code>double</code>, <span class="t-v">(2)</span> (<code>sin</code>) is called. Otherwise, <span class="t-v">(1)</span> (<code>sinf</code>) is called. If the argument is complex, then the macro invokes the corresponding complex function (<code><a href="../complex/csin" title="c/numeric/complex/csin">csinl</a></code>, <code><a href="../complex/csin" title="c/numeric/complex/csin">csin</a></code>, <code><a href="../complex/csin" title="c/numeric/complex/csin">csinf</a></code>).</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>The functions <span class="t-v">(4-6)</span> are declared if and only if the implementation predefines <code>__STDC_IEC_60559_DFP__</code> (i.e. the implementation supports decimal floating-point numbers).</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating-point value representing an angle in radians </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the sine of <code>arg</code> (sin(arg)) in the range [-1 ; +1], is returned.</p> +<table class="t-rev-begin"> <tr class="t-rev t-until-c99"> +<td> <p>The result may have little or no significance if the magnitude of <code>arg</code> is large.</p> +</td> <td><span class="t-mark-rev t-until-c99">(until C99)</span></td> +</tr> </table> <p>If a domain error occurs, an implementation-defined value is returned (NaN where supported).</p> +<p>If a range error occurs due to underflow, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559):</p> +<ul> +<li> if the argument is ±0, it is returned unmodified; </li> +<li> if the argument is ±∞, NaN is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised; </li> +<li> if the argument is NaN, NaN is returned. </li> +</ul> <h3 id="Notes"> Notes</h3> <p>The case where the argument is infinite is not specified to be a domain error in C, but it is defined as a <a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/sin.html">domain error in POSIX</a>.</p> +<p>POSIX also specifies that in case of underflow, <code>arg</code> is returned unmodified, and if that is not supported, an implementation-defined value no greater than <code><a href="../../types/limits" title="c/types/limits">DBL_MIN</a></code>, <code><a href="../../types/limits" title="c/types/limits">FLT_MIN</a></code>, and <code><a href="../../types/limits" title="c/types/limits">LDBL_MIN</a></code> is returned.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <errno.h> +#include <fenv.h> +#include <math.h> +#include <stdio.h> + +#ifndef __GNUC__ +#pragma STDC FENV_ACCESS ON +#endif + +int main(void) +{ + const double pi = acos(-1); + + // typical usage + printf("sin(pi/6) = %f\n", sin(pi / 6)); + printf("sin(pi/2) = %f\n", sin(pi / 2)); + printf("sin(-3*pi/4) = %f\n", sin(-3 * pi / 4)); + + // special values + printf("sin(+0) = %f\n", sin(0.0)); + printf("sin(-0) = %f\n", sin(-0.0)); + + // error handling + feclearexcept(FE_ALL_EXCEPT); + printf("sin(INFINITY) = %f\n", sin(INFINITY)); + if (fetestexcept(FE_INVALID)) + puts(" FE_INVALID raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">sin(pi/6) = 0.500000 +sin(pi/2) = 1.000000 +sin(-3*pi/4) = -0.707107 +sin(+0) = 0.000000 +sin(-0) = -0.000000 +sin(INFINITY) = -nan + FE_INVALID raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.12.4.6 The sin functions (p: TBD) </li> +<li> 7.27 Type-generic math <tgmath.h> (p: TBD) </li> +<li> F.10.1.6 The sin functions (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.4.6 The sin functions (p: 175) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.1.6 The sin functions (p: 378) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.4.6 The sin functions (p: 239-240) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.1.6 The sin functions (p: 519) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.4.6 The sin functions (p: 220) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.1.6 The sin functions (p: 456) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.2.6 The sin function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="cos" title="c/numeric/math/cos"> <span class="t-lines"><span>cos</span><span>cosf</span><span>cosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes cosine (\({\small\cos{x} }\)cos(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="tan" title="c/numeric/math/tan"> <span class="t-lines"><span>tan</span><span>tanf</span><span>tanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes tangent (\({\small\tan{x} }\)tan(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="asin" title="c/numeric/math/asin"> <span class="t-lines"><span>asin</span><span>asinf</span><span>asinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc sine (\({\small\arcsin{x} }\)arcsin(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../complex/csin" title="c/numeric/complex/csin"> <span class="t-lines"><span>csin</span><span>csinf</span><span>csinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex sine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/sin" title="cpp/numeric/math/sin">C++ documentation</a></span> for <code>sin</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/sin" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/sin</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fsinh.html b/devdocs/c/numeric%2Fmath%2Fsinh.html new file mode 100644 index 00000000..bedcb5d3 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fsinh.html @@ -0,0 +1,77 @@ + <h1 id="firstHeading" class="firstHeading">sinh, sinhf, sinhl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float sinhf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double sinh( double arg );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double sinhl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define sinh( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes hyperbolic sine of <code>arg</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If the argument has type <code>long double</code>, <code>sinhl</code> is called. Otherwise, if the argument has integer type or the type <code>double</code>, <code>sinh</code> is called. Otherwise, <code>sinhf</code> is called. If the argument is complex, then the macro invokes the corresponding complex function (<code><a href="http://en.cppreference.com/w/c/numeric/complex/csinh"><span class="kw811">csinhf</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/csinh"><span class="kw810">csinh</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/csinh"><span class="kw812">csinhl</span></a></code>).</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value representing a hyperbolic angle </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> If no errors occur, the hyperbolic sine of <code>arg</code> (sinh(arg), or <span><span>earg-e-arg</span><span>/</span><span>2</span></span>) is returned. <p>If a range error due to overflow occurs, <code><a href="huge_val" title="c/numeric/math/HUGE VAL">±HUGE_VAL</a></code>, <code>±HUGE_VALF</code>, or <code>±HUGE_VALL</code> is returned.</p> +<p>If a range error occurs due to underflow, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> if the argument is ±0 or ±∞, it is returned unmodified </li> +<li> if the argument is NaN, NaN is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/sinh.html">POSIX specifies</a> that in case of underflow, <code>arg</code> is returned unmodified, and if that is not supported, an implementation-defined value no greater than <code><a href="../../types/limits" title="c/types/limits">DBL_MIN</a></code>, <code><a href="../../types/limits" title="c/types/limits">FLT_MIN</a></code>, and <code><a href="../../types/limits" title="c/types/limits">LDBL_MIN</a></code> is returned.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <errno.h> +#include <fenv.h> + +// #pragma STDC FENV_ACCESS ON +int main(void) +{ + printf("sinh(1) = %f\nsinh(-1)=%f\n", sinh(1), sinh(-1)); + printf("log(sinh(1) + cosh(1))=%f\n", log(sinh(1)+cosh(1))); + // special values + printf("sinh(+0) = %f\nsinh(-0)=%f\n", sinh(0.0), sinh(-0.0)); + // error handling + errno=0; feclearexcept(FE_ALL_EXCEPT); + printf("sinh(710.5) = %f\n", sinh(710.5)); + if(errno == ERANGE) perror(" errno == ERANGE"); + if(fetestexcept(FE_OVERFLOW)) puts(" FE_OVERFLOW raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">sinh(1) = 1.175201 +sinh(-1)=-1.175201 +log(sinh(1) + cosh(1))=1.000000 +sinh(+0) = 0.000000 +sinh(-0)=-0.000000 +sinh(710.5) = inf + errno == ERANGE: Numerical result out of range + FE_OVERFLOW raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.5.5 The sinh functions (p: 176) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.2.5 The sinh functions (p: 379) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.5.5 The sinh functions (p: 241-242) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.2.5 The sinh functions (p: 520) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.5.5 The sinh functions (p: 222) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.2.5 The sinh functions (p: 457) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.3.2 The sinh function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="cosh" title="c/numeric/math/cosh"> <span class="t-lines"><span>cosh</span><span>coshf</span><span>coshl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes hyperbolic cosine (\({\small\cosh{x} }\)cosh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="tanh" title="c/numeric/math/tanh"> <span class="t-lines"><span>tanh</span><span>tanhf</span><span>tanhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes hyperbolic tangent (\({\small\tanh{x} }\)tanh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="asinh" title="c/numeric/math/asinh"> <span class="t-lines"><span>asinh</span><span>asinhf</span><span>asinhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes inverse hyperbolic sine (\({\small\operatorname{arsinh}{x} }\)arsinh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../complex/csinh" title="c/numeric/complex/csinh"> <span class="t-lines"><span>csinh</span><span>csinhf</span><span>csinhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex hyperbolic sine <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/sinh" title="cpp/numeric/math/sinh">C++ documentation</a></span> for <code>sinh</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/sinh" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/sinh</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fsinpi.html b/devdocs/c/numeric%2Fmath%2Fsinpi.html new file mode 100644 index 00000000..c6d70ab9 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fsinpi.html @@ -0,0 +1,77 @@ + <h1 id="firstHeading" class="firstHeading">sinpi, sinpif, sinpil, sinpid32, sinpid64, sinpid128</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">float sinpif( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">double sinpi( double arg );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">long double sinpil( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal32 sinpid32( _Decimal32 arg );</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal64 sinpid64( _Decimal64 arg );</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal128 sinpid128( _Decimal128 arg );</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">#define sinpi( arg )</pre> +</td> <td> (7) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-6)</span> Computes the sine of <code>π·arg</code> measured in radians, thus regarding <code>arg</code> as a measurement in half-revolutions.</div> <div class="t-li1"> +<span class="t-li">7)</span> Type-generic macro: calls the correct function based on the type of <code>arg</code>. If the argument has integer type, <span class="t-v">(2)</span> is called.</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>The functions <span class="t-v">(4-6)</span> are declared if and only if the implementation predefines <code>__STDC_IEC_60559_DFP__</code> (i.e. the implementation supports decimal floating-point numbers).</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating-point value whose product with <code>π</code> represents an angle in radians </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the sine of <code>π·arg</code> (sin(π×arg)) in the range [-1, +1], is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559):</p> +<ul> +<li> if the argument is ±0, it is returned unmodified; </li> +<li> if the argument is ±∞, NaN is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised; </li> +<li> if the argument is NaN, NaN is returned. </li> +</ul> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <errno.h> +#include <fenv.h> +#include <math.h> +#include <stdio.h> + +#ifndef __GNUC__ +#pragma STDC FENV_ACCESS ON +#endif + +#if __STDC_VERSION__ < 202311L +// A naive implementation of a subset of sinpi family +double sinpi(double arg) +{ + return sin(arg * (double)3.1415926535897932384626433); +} +#endif + +int main(void) +{ + const double pi = acos(-1); + + // typical usage + printf("sinpi(1) = %f, sin(pi) = %f\n", sinpi(1), sin(pi)); + printf("sinpi(0.5) = %f, sin(pi/2) = %f\n", sinpi(0.5), sin(pi / 2)); + printf("sinpi(-0.75) = %f, sin(-3*pi/4) = %f\n", sinpi(-0.75), sin(-3 * pi / 4)); + + // special values + printf("sinpi(+0) = %f\n", sinpi(0.0)); + printf("sinpi(-0) = %f\n", sinpi(-0.0)); + + // error handling + feclearexcept(FE_ALL_EXCEPT); + printf("sinpi(INFINITY) = %f\n", sinpi(INFINITY)); + if (fetestexcept(FE_INVALID)) + puts(" FE_INVALID raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">sinpi(1) = 0.000000, sin(pi) = 0.000000 +sinpi(0.5) = 1.000000, sin(pi/2) = 1.000000 +sinpi(-0.75) = -0.707107, sin(-3*pi/4) = -0.707107 +sinpi(+0) = 0.000000 +sinpi(-0) = -0.000000 +sinpi(INFINITY) = -nan + FE_INVALID raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.12.4.13 The sinpi functions (p: 247-248) </li> +<li> 7.27 Type generic math <tgmath.h> (p: 387) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="sin" title="c/numeric/math/sin"> <span class="t-lines"><span>sin</span><span>sinf</span><span>sinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes sine (\({\small\sin{x} }\)sin(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/sinpi" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/sinpi</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Fsqrt.html b/devdocs/c/numeric%2Fmath%2Fsqrt.html new file mode 100644 index 00000000..460db07c --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Fsqrt.html @@ -0,0 +1,76 @@ + <h1 id="firstHeading" class="firstHeading">sqrt, sqrtf, sqrtl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float sqrtf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double sqrt( double arg );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double sqrtl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define sqrt( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes square root of <code>arg</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>arg</code> has type <code>long double</code>, <code>sqrtl</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>sqrt</code> is called. Otherwise, <code>sqrtf</code> is called. If <code>arg</code> is complex or imaginary, then the macro invokes the corresponding complex function (<code><a href="http://en.cppreference.com/w/c/numeric/complex/csqrt"><span class="kw778">csqrtf</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/csqrt"><span class="kw777">csqrt</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/csqrt"><span class="kw779">csqrtl</span></a></code>).</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, square root of <code>arg</code> (\({\small \sqrt{arg} }\)<span class="t-mrad"><span>√</span><span>arg</span></span>), is returned.</p> +<p>If a domain error occurs, an implementation-defined value is returned (NaN where supported).</p> +<p>If a range error occurs due to underflow, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>Domain error occurs if <code>arg</code> is less than zero.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> If the argument is less than -0, <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised and NaN is returned. </li> +<li> If the argument is +∞ or ±0, it is returned, unmodified. </li> +<li> If the argument is NaN, NaN is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p><code>sqrt</code> is required by the IEEE standard to be correctly rounded from the infinitely precise result. In particular, the exact result is produced if it can be represented in the floating-point type. The only other operations which require this are the <a href="../../language/operator_arithmetic" title="c/language/operator arithmetic">arithmetic operators</a> and the function <code><a href="fma" title="c/numeric/math/fma">fma</a></code>. Other functions, including <code><a href="pow" title="c/numeric/math/pow">pow</a></code>, are not so constrained.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <errno.h> +#include <fenv.h> + +#pragma STDC FENV_ACCESS ON + +int main(void) +{ + // normal use + printf("sqrt(100) = %f\n", sqrt(100)); + printf("sqrt(2) = %f\n", sqrt(2)); + printf("golden ratio = %f\n", (1+sqrt(5))/2); + // special values + printf("sqrt(-0) = %f\n", sqrt(-0.0)); + // error handling + errno = 0; feclearexcept(FE_ALL_EXCEPT); + printf("sqrt(-1.0) = %f\n", sqrt(-1)); + if(errno == EDOM) perror(" errno == EDOM"); + if(fetestexcept(FE_INVALID)) puts(" FE_INVALID was raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">sqrt(100) = 10.000000 +sqrt(2) = 1.414214 +golden ratio = 1.618034 +sqrt(-0) = -0.000000 +sqrt(-1.0) = -nan + errno = EDOM: Numerical argument out of domain + FE_INVALID was raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.7.5 The sqrt functions (p: 249) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.4.5 The sqrt functions (p: 525) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.7.5 The sqrt functions (p: 229-230) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.4.5 The sqrt functions (p: 462) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.5.2 The sqrt function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="pow" title="c/numeric/math/pow"> <span class="t-lines"><span>pow</span><span>powf</span><span>powl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes a number raised to the given power (\(\small{x^y}\)x<sup>y</sup>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="cbrt" title="c/numeric/math/cbrt"> <span class="t-lines"><span>cbrt</span><span>cbrtf</span><span>cbrtl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes cube root (\(\small{\sqrt[3]{x} }\)<span class="t-mrad"><span>3</span><span>√</span><span>x</span></span>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="hypot" title="c/numeric/math/hypot"> <span class="t-lines"><span>hypot</span><span>hypotf</span><span>hypotl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes square root of the sum of the squares of two given numbers (\(\scriptsize{\sqrt{x^2+y^2} }\)<span class="t-mrad"><span>√</span><span>x<sup class="t-su">2</sup>+y<sup class="t-su">2</sup></span></span>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../complex/csqrt" title="c/numeric/complex/csqrt"> <span class="t-lines"><span>csqrt</span><span>csqrtf</span><span>csqrtl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex square root <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/sqrt" title="cpp/numeric/math/sqrt">C++ documentation</a></span> for <code>sqrt</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/sqrt" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/sqrt</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Ftan.html b/devdocs/c/numeric%2Fmath%2Ftan.html new file mode 100644 index 00000000..74007697 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ftan.html @@ -0,0 +1,106 @@ + <h1 id="firstHeading" class="firstHeading">tan, tanf, tanl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float tanf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double tan( double arg );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double tanl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal32 tand32( _Decimal32 arg );</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal64 tand64( _Decimal64 arg );</pre> +</td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">_Decimal128 tand128( _Decimal128 arg );</pre> +</td> <td> (6) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define tan( arg )</pre> +</td> <td> (7) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-6)</span> Computes the tangent of <code>arg</code> (measured in radians).</div> <div class="t-li1"> +<span class="t-li">7)</span> Type-generic macro: If the argument has type <code>long double</code>, <span class="t-v">(3)</span> (<code>tanl</code>) is called. Otherwise, if the argument has integer type or the type <code>double</code>, <span class="t-v">(2)</span> (<code>tan</code>) is called. Otherwise, <span class="t-v">(1)</span> (<code>tanf</code>) is called. If the argument is complex, then the macro invokes the corresponding complex function (<code><a href="../complex/ctan" title="c/numeric/complex/ctan">ctanf</a></code>, <code><a href="../complex/ctan" title="c/numeric/complex/ctan">ctan</a></code>, <code><a href="../complex/ctan" title="c/numeric/complex/ctan">ctanl</a></code>).</div> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>The functions <span class="t-v">(4-6)</span> are declared if and only if the implementation predefines <code>__STDC_IEC_60559_DFP__</code> (i.e. the implementation supports decimal floating-point numbers).</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating-point value representing angle in radians </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the tangent of <code>arg</code> (tan(arg)) is returned.</p> +<table class="t-rev-begin"> <tr class="t-rev t-until-c99"> +<td> <p>The result may have little or no significance if the magnitude of <code>arg</code> is large.</p> +</td> <td><span class="t-mark-rev t-until-c99">(until C99)</span></td> +</tr> </table> <p>If a domain error occurs, an implementation-defined value is returned (NaN where supported).</p> +<p>If a range error occurs due to underflow, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559):</p> +<ul> +<li> if the argument is ±0, it is returned unmodified; </li> +<li> if the argument is ±∞, NaN is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised; </li> +<li> if the argument is NaN, NaN is returned. </li> +</ul> <h3 id="Notes"> Notes</h3> <p>The case where the argument is infinite is not specified to be a domain error in C, but it is defined as a <a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/tan.html">domain error in POSIX</a>.</p> +<p>The function has mathematical poles at π(1/2 + n); however no common floating-point representation is able to represent <code>π/2</code> exactly, thus there is no value of the argument for which a pole error occurs.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <errno.h> +#include <fenv.h> +#include <math.h> +#include <stdio.h> + +#ifndef __GNUC__ +#pragma STDC FENV_ACCESS ON +#endif + +int main(void) +{ + const double pi = acos(-1); + + // typical usage + printf("tan(pi*1/4) = %+f\n", tan(pi * 1 / 4)); // 45 deg + printf("tan(pi*3/4) = %+f\n", tan(pi * 3 / 4)); // 135 deg + printf("tan(pi*5/4) = %+f\n", tan(pi * 5 / 4)); // -135 deg + printf("tan(pi*7/4) = %+f\n", tan(pi * 7 / 4)); // -45 deg + + // special values + printf("tan(+0) = %f\n", tan(0.0)); + printf("tan(-0) = %f\n", tan(-0.0)); + + // error handling + feclearexcept(FE_ALL_EXCEPT); + printf("tan(INFINITY) = %f\n", tan(INFINITY)); + if (fetestexcept(FE_INVALID)) + puts(" FE_INVALID raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">tan(pi*1/4) = +1.000000 +tan(pi*3/4) = -1.000000 +tan(pi*5/4) = +1.000000 +tan(pi*7/4) = -1.000000 +tan(+0) = 0.000000 +tan(-0) = -0.000000 +tan(INFINITY) = -nan + FE_INVALID raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.12.4.7 The tan functions (p: TBD) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: TBD) </li> +<li> F.10.1.7 The tan functions (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.12.4.7 The tan functions (p: 175) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li> +<li> F.10.1.7 The tan functions (p: 378) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.4.7 The tan functions (p: 240) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.1.7 The tan functions (p: 519) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.4.7 The tan functions (p: 220) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.1.7 The tan functions (p: 457) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.2.7 The tan function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="sin" title="c/numeric/math/sin"> <span class="t-lines"><span>sin</span><span>sinf</span><span>sinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes sine (\({\small\sin{x} }\)sin(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="cos" title="c/numeric/math/cos"> <span class="t-lines"><span>cos</span><span>cosf</span><span>cosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes cosine (\({\small\cos{x} }\)cos(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atan" title="c/numeric/math/atan"> <span class="t-lines"><span>atan</span><span>atanf</span><span>atanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc tangent (\({\small\arctan{x} }\)arctan(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../complex/ctan" title="c/numeric/complex/ctan"> <span class="t-lines"><span>ctan</span><span>ctanf</span><span>ctanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex tangent <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/tan" title="cpp/numeric/math/tan">C++ documentation</a></span> for <code>tan</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/tan" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/tan</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Ftanh.html b/devdocs/c/numeric%2Fmath%2Ftanh.html new file mode 100644 index 00000000..15b20f0b --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ftanh.html @@ -0,0 +1,60 @@ + <h1 id="firstHeading" class="firstHeading">tanh, tanhf, tanhl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float tanhf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">double tanh( double arg );</pre> +</td> <td> (2) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double tanhl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define tanh( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the hyperbolic tangent of <code>arg</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If the argument has type <code>long double</code>, <code>tanhl</code> is called. Otherwise, if the argument has integer type or the type <code>double</code>, <code>tanh</code> is called. Otherwise, <code>tanhf</code> is called. If the argument is complex, then the macro invokes the corresponding complex function (<code><a href="http://en.cppreference.com/w/c/numeric/complex/ctanh"><span class="kw814">ctanhf</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/ctanh"><span class="kw813">ctanh</span></a></code>, <code><a href="http://en.cppreference.com/w/c/numeric/complex/ctanh"><span class="kw815">ctanhl</span></a></code>).</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value representing a hyperbolic angle </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> If no errors occur, the hyperbolic tangent of <code>arg</code> (tanh(arg), or <span><span>earg-e-arg</span><span>/</span><span>earg+e-arg</span></span>) is returned. <p>If a range error occurs due to underflow, the correct result (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> if the argument is ±0, ±0 is returned </li> +<li> If the argument is ±∞, ±1 is returned </li> +<li> if the argument is NaN, NaN is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/tanh.html">POSIX specifies</a> that in case of underflow, <code>arg</code> is returned unmodified, and if that is not supported, an implementation-defined value no greater than DBL_MIN, FLT_MIN, and LDBL_MIN is returned.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> + +int main(void) +{ + printf("tanh(1) = %f\ntanh(-1) = %f\n", tanh(1), tanh(-1)); + printf("tanh(0.1)*sinh(0.2)-cosh(0.2) = %f\n", tanh(0.1) * sinh(0.2) - cosh(0.2)); + // special values + printf("tanh(+0) = %f\ntanh(-0) = %f\n", tanh(0.0), tanh(-0.0)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">tanh(1) = 0.761594 +tanh(-1) = -0.761594 +tanh(0.1)*sinh(0.2)-cosh(0.2) = -1.000000 +tanh(+0) = 0.000000 +tanh(-0) = -0.000000</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.5.6 The tanh functions (p: 242) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.2.6 The tanh functions (p: 520) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.5.6 The tanh functions (p: 222-223) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.2.6 The tanh functions (p: 457) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.5.3.3 The tanh function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="sinh" title="c/numeric/math/sinh"> <span class="t-lines"><span>sinh</span><span>sinhf</span><span>sinhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes hyperbolic sine (\({\small\sinh{x} }\)sinh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="cosh" title="c/numeric/math/cosh"> <span class="t-lines"><span>cosh</span><span>coshf</span><span>coshl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes hyperbolic cosine (\({\small\cosh{x} }\)cosh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atanh" title="c/numeric/math/atanh"> <span class="t-lines"><span>atanh</span><span>atanhf</span><span>atanhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes inverse hyperbolic tangent (\({\small\operatorname{artanh}{x} }\)artanh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../complex/ctanh" title="c/numeric/complex/ctanh"> <span class="t-lines"><span>ctanh</span><span>ctanhf</span><span>ctanhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes the complex hyperbolic tangent <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/tanh" title="cpp/numeric/math/tanh">C++ documentation</a></span> for <code>tanh</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/tanh" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/tanh</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Ftgamma.html b/devdocs/c/numeric%2Fmath%2Ftgamma.html new file mode 100644 index 00000000..5b7fec6f --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ftgamma.html @@ -0,0 +1,83 @@ + <h1 id="firstHeading" class="firstHeading">tgamma, tgammaf, tgammal</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float tgammaf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double tgamma( double arg );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double tgammal( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define tgamma( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the <a href="https://en.wikipedia.org/wiki/Gamma_function" class="extiw" title="enwiki:Gamma function">gamma function</a> of <code>arg</code>.</div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>arg</code> has type <code>long double</code>, <code>tgammal</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>tgamma</code> is called. Otherwise, <code>tgammaf</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the value of the gamma function of <code>arg</code>, that is \(\Gamma(\mathtt{arg}) = \displaystyle\int_0^\infty\!\! t^{\mathtt{arg}-1} e^{-t}\, dt\)∫<sub class="t-su t-su-b">∞0</sub><i>t</i><sup class="t-su">arg-1</sup> <i>e</i><sup>-t</sup> d<i>t</i>, is returned.</p> +<p>If a domain error occurs, an implementation-defined value (NaN where supported) is returned.</p> +<p>If a pole error occurs, <code><a href="huge_val" title="c/numeric/math/HUGE VAL">±HUGE_VAL</a></code>, <code>±HUGE_VALF</code>, or <code>±HUGE_VALL</code> is returned.</p> +<p>If a range error due to overflow occurs, <code><a href="huge_val" title="c/numeric/math/HUGE VAL">±HUGE_VAL</a></code>, <code>±HUGE_VALF</code>, or <code>±HUGE_VALL</code> is returned.</p> +<p>If a range error due to underflow occurs, the correct value (after rounding) is returned.</p> +<h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling"><code>math_errhandling</code></a>.</p> +<p>If <code>arg</code> is zero or is an integer less than zero, a pole error or a domain error may occur.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559):</p> +<ul> +<li> If the argument is ±0, ±∞ is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_DIVBYZERO</a></code> is raised. </li> +<li> If the argument is a negative integer, NaN is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised. </li> +<li> If the argument is -∞, NaN is returned and <code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INVALID</a></code> is raised. </li> +<li> If the argument is +∞, +∞ is returned. </li> +<li> If the argument is NaN, NaN is returned. </li> +</ul> <h3 id="Notes"> Notes</h3> <p>If <code>arg</code> is a natural number, <code>tgamma(arg)</code> is the factorial of <code>arg - 1</code>. Many implementations calculate the exact integer-domain factorial if the argument is a sufficiently small integer.</p> +<p>For IEEE-compatible type <code>double</code>, overflow happens if <code><span class="nu0">0</span> <span class="sy1"><</span> x <span class="sy1"><</span> <span class="nu0">1</span><span class="sy2">/</span><a href="http://en.cppreference.com/w/c/types/limits"><span class="kw378">DBL_MAX</span></a></code> or if <code>x > 171.7</code>.</p> +<p><a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/tgamma.html">POSIX requires</a> that a pole error occurs if the argument is zero, but a domain error occurs when the argument is a negative integer. It also specifies that in future, domain errors may be replaced by pole errors for negative integer arguments (in which case the return value in those cases would change from NaN to ±∞).</p> +<p>There is a non-standard function named <code>gamma</code> in various implementations, but its definition is inconsistent. For example, glibc and 4.2BSD version of <code>gamma</code> executes <code>lgamma</code>, but 4.4BSD version of <code>gamma</code> executes <code>tgamma</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <math.h> +#include <float.h> +#include <errno.h> +#include <fenv.h> +// #pragma STDC FENV_ACCESS ON + +int main(void) +{ + printf("tgamma(10) = %f, 9!=%f\n", tgamma(10), 2 * 3 * 4 * 5 * 6 * 7 * 8 * 9.0); + printf("tgamma(0.5) = %f, sqrt(pi) = %f\n", tgamma(0.5), sqrt(acos(-1))); + + // special values + printf("tgamma(+Inf) = %f\n", tgamma(INFINITY)); + + // error handling + errno = 0; feclearexcept(FE_ALL_EXCEPT); + printf("tgamma(-1) = %f\n", tgamma(-1)); + if (errno == ERANGE) + perror(" errno == ERANGE"); + else + if (errno == EDOM) perror(" errno == EDOM"); + if (fetestexcept(FE_DIVBYZERO)) + puts(" FE_DIVBYZERO raised"); + else if (fetestexcept(FE_INVALID)) + puts(" FE_INVALID raised"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">tgamma(10) = 362880.000000, 9!=362880.000000 +tgamma(0.5) = 1.772454, sqrt(pi) = 1.772454 +tgamma(+Inf) = inf +tgamma(-1) = nan + errno == EDOM: Numerical argument out of domain + FE_INVALID raised</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.8.4 The tgamma functions (p: 250) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.5.4 The tgamma functions (p: 525) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.8.4 The tgamma functions (p: 231) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.5.4 The tgamma functions (p: 462) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="lgamma" title="c/numeric/math/lgamma"> <span class="t-lines"><span>lgamma</span><span>lgammaf</span><span>lgammal</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes natural (base-<i>e</i>) logarithm of the gamma function <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/tgamma" title="cpp/numeric/math/tgamma">C++ documentation</a></span> for <code>tgamma</code> </td> +</tr> </table> <h3 id="External_links"> External links</h3> <table> <tr> <td> +<a rel="nofollow" class="external text" href="https://mathworld.wolfram.com/GammaFunction.html">Weisstein, Eric W. "Gamma Function."</a> From MathWorld — A Wolfram Web Resource. </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/tgamma" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/tgamma</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath%2Ftrunc.html b/devdocs/c/numeric%2Fmath%2Ftrunc.html new file mode 100644 index 00000000..a86f0ec6 --- /dev/null +++ b/devdocs/c/numeric%2Fmath%2Ftrunc.html @@ -0,0 +1,57 @@ + <h1 id="firstHeading" class="firstHeading">trunc, truncf, truncl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><math.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float truncf( float arg );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double trunc( double arg );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double truncl( long double arg );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><tgmath.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define trunc( arg )</pre> +</td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1-3)</span> Computes the nearest integer not greater in magnitude than <code>arg</code>. </div> <div class="t-li1"> +<span class="t-li">4)</span> Type-generic macro: If <code>arg</code> has type <code>long double</code>, <code>truncl</code> is called. Otherwise, if <code>arg</code> has integer type or the type <code>double</code>, <code>trunc</code> is called. Otherwise, <code>truncf</code> is called.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> arg </td> <td> - </td> <td> floating point value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If no errors occur, the nearest integer value not greater in magnitude than <code>arg</code> (in other words, <code>arg</code> rounded towards zero), is returned.</p> +<div class="t-plot"> <div class="t-plot-left">Return value</div> <div class="t-plot-image-left"><img alt="math-trunc.svg" src="data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9Im5vIj8+CjwhRE9DVFlQRSBzdmcgUFVCTElDICItLy9XM0MvL0RURCBTVkcgMS4xLy9FTiIgImh0dHA6Ly93d3cudzMub3JnL0dyYXBoaWNzL1NWRy8xLjEvRFREL3N2ZzExLmR0ZCI+CjwhLS0gQ3JlYXRlZCB3aXRoIG1hdHBsb3RsaWIgKGh0dHA6Ly9tYXRwbG90bGliLnNvdXJjZWZvcmdlLm5ldC8pIC0tPgo8c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIGhlaWdodD0iMjAwcHgiIHZlcnNpb249IjEuMSIgdmlld0JveD0iMCAwIDIwMCAyMDAiIHdpZHRoPSIyMDBweCI+CiA8ZGVmcz4KICA8c3R5bGUgdHlwZT0idGV4dC9jc3MiPgoqe3N0cm9rZS1saW5lY2FwOnNxdWFyZTtzdHJva2UtbGluZWpvaW46cm91bmQ7fQogIDwvc3R5bGU+CiA8L2RlZnM+CiA8ZyBpZD0iZmlndXJlXzEiPgogIDxnIGlkPSJwYXRjaF8xIj4KICAgPHBhdGggZD0iIE0wIDIwMCBMMjAwIDIwMCBMMjAwIDAgTDAgMCB6ICIgc3R5bGU9ImZpbGw6I2ZmZmZmZjsiLz4KICA8L2c+CiAgPGcgaWQ9ImF4ZXNfMSI+CiAgIDxnIGlkPSJwYXRjaF8yIj4KICAgIDxwYXRoIGQ9IiBNMjUgMTc3LjUgTDE4MCAxNzcuNSBMMTgwIDIyLjUgTDI1IDIyLjUgeiAiIHN0eWxlPSJmaWxsOiNmZmZmZmY7Ii8+CiAgIDwvZz4KICAgPGcgaWQ9Im1hdHBsb3RsaWIuYXhpc18xIj4KICAgIDxnIGlkPSJ4dGlja18xIj4KICAgICA8ZyBpZD0ibGluZTJkXzEiPgogICAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTM2LjA3MTQgMTc3LjUgTDM2LjA3MTQgMjIuNSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDtzdHJva2UtZGFzaGFycmF5OjEuMDAwMDAwLDMuMDAwMDAwO3N0cm9rZS1kYXNob2Zmc2V0OjAuMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMiI+CiAgICAgIDxkZWZzPgogICAgICAgPHBhdGggZD0iIE0wIDAgTDAgLTQiIGlkPSJtMDAxMmRkNGVlZiIgc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICAgPC9kZWZzPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjM2LjA3MTQyODU3MTQiIHhsaW5rOmhyZWY9IiNtMDAxMmRkNGVlZiIgeT0iMTc3LjUiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzMiPgogICAgICA8ZGVmcz4KICAgICAgIDxwYXRoIGQ9IiBNMCAwIEwwIDQiIGlkPSJtNDc2MzQ0OTY5YyIgc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICAgPC9kZWZzPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjM2LjA3MTQyODU3MTQiIHhsaW5rOmhyZWY9IiNtNDc2MzQ0OTY5YyIgeT0iMjIuNSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzEiPgogICAgICA8IS0tIOKIkjMgLS0+CiAgICAgIDxkZWZzPgogICAgICAgPHBhdGggZD0iIE00MC41NzgxIDM5LjMxMjUgUTQ3LjY1NjIgMzcuNzk2OSA1MS42MjUgMzMgUTU1LjYwOTQgMjguMjE4OCA1NS42MDk0IDIxLjE4NzUgUTU1LjYwOTQgMTAuNDA2MiA0OC4xODc1IDQuNDg0MzggUTQwLjc2NTYgLTEuNDIxODggMjcuMDkzOCAtMS40MjE4OCBRMjIuNTE1NiAtMS40MjE4OCAxNy42NTYyIC0wLjUxNTYyNSBRMTIuNzk2OSAwLjM5MDYyNSA3LjYyNSAyLjIwMzEyIEw3LjYyNSAxMS43MTg4IFExMS43MTg4IDkuMzI4MTIgMTYuNTkzOCA4LjEwOTM4IFEyMS40ODQ0IDYuODkwNjIgMjYuODEyNSA2Ljg5MDYyIFEzNi4wNzgxIDYuODkwNjIgNDAuOTM3NSAxMC41NDY5IFE0NS43OTY5IDE0LjIwMzEgNDUuNzk2OSAyMS4xODc1IFE0NS43OTY5IDI3LjY0MDYgNDEuMjgxMiAzMS4yNjU2IFEzNi43NjU2IDM0LjkwNjIgMjguNzE4OCAzNC45MDYyIEwyMC4yMTg4IDM0LjkwNjIgTDIwLjIxODggNDMuMDE1NiBMMjkuMTA5NCA0My4wMTU2IFEzNi4zNzUgNDMuMDE1NiA0MC4yMzQ0IDQ1LjkyMTkgUTQ0LjA5MzggNDguODI4MSA0NC4wOTM4IDU0LjI5NjkgUTQ0LjA5MzggNTkuOTA2MiA0MC4xMDk0IDYyLjkwNjIgUTM2LjE0MDYgNjUuOTIxOSAyOC43MTg4IDY1LjkyMTkgUTI0LjY1NjIgNjUuOTIxOSAyMC4wMTU2IDY1LjAzMTIgUTE1LjM3NSA2NC4xNTYyIDkuODEyNSA2Mi4zMTI1IEw5LjgxMjUgNzEuMDkzOCBRMTUuNDM3NSA3Mi42NTYyIDIwLjM0MzggNzMuNDM3NSBRMjUuMjUgNzQuMjE4OCAyOS41OTM4IDc0LjIxODggUTQwLjgyODEgNzQuMjE4OCA0Ny4zNTk0IDY5LjEwOTQgUTUzLjkwNjIgNjQuMDE1NiA1My45MDYyIDU1LjMyODEgUTUzLjkwNjIgNDkuMjY1NiA1MC40Mzc1IDQ1LjA5MzggUTQ2Ljk2ODggNDAuOTIxOSA0MC41NzgxIDM5LjMxMjUiIGlkPSJEZWphVnVTYW5zLTMzIi8+CiAgICAgICA8cGF0aCBkPSIgTTEwLjU5MzggMzUuNSBMNzMuMTg3NSAzNS41IEw3My4xODc1IDI3LjIwMzEgTDEwLjU5MzggMjcuMjAzMSB6ICIgaWQ9IkRlamFWdVNhbnMtMjIxMiIvPgogICAgICA8L2RlZnM+CiAgICAgIDxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDMwLjI3NDg2NjA3MTQgMTkxLjY3OTY4NzUpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0yMjEyIi8+CiAgICAgICA8dXNlIHg9IjgzLjc4OTA2MjUiIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTMzIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICA8L2c+CiAgICA8ZyBpZD0ieHRpY2tfMiI+CiAgICAgPGcgaWQ9ImxpbmUyZF80Ij4KICAgICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE01OC4yMTQzIDE3Ny41IEw1OC4yMTQzIDIyLjUiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWRhc2hhcnJheToxLjAwMDAwMCwzLjAwMDAwMDtzdHJva2UtZGFzaG9mZnNldDowLjA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzUiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjU4LjIxNDI4NTcxNDMiIHhsaW5rOmhyZWY9IiNtMDAxMmRkNGVlZiIgeT0iMTc3LjUiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzYiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjU4LjIxNDI4NTcxNDMiIHhsaW5rOmhyZWY9IiNtNDc2MzQ0OTY5YyIgeT0iMjIuNSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzIiPgogICAgICA8IS0tIOKIkjIgLS0+CiAgICAgIDxkZWZzPgogICAgICAgPHBhdGggZD0iIE0xOS4xODc1IDguMjk2ODggTDUzLjYwOTQgOC4yOTY4OCBMNTMuNjA5NCAwIEw3LjMyODEyIDAgTDcuMzI4MTIgOC4yOTY4OCBRMTIuOTM3NSAxNC4xMDk0IDIyLjYyNSAyMy44OTA2IFEzMi4zMjgxIDMzLjY4NzUgMzQuODEyNSAzNi41MzEyIFEzOS41NDY5IDQxLjg0MzggNDEuNDIxOSA0NS41MzEyIFE0My4zMTI1IDQ5LjIxODggNDMuMzEyNSA1Mi43ODEyIFE0My4zMTI1IDU4LjU5MzggMzkuMjM0NCA2Mi4yNSBRMzUuMTU2MiA2NS45MjE5IDI4LjYwOTQgNjUuOTIxOSBRMjMuOTY4OCA2NS45MjE5IDE4LjgxMjUgNjQuMzEyNSBRMTMuNjcxOSA2Mi43MDMxIDcuODEyNSA1OS40MjE5IEw3LjgxMjUgNjkuMzkwNiBRMTMuNzY1NiA3MS43ODEyIDE4LjkzNzUgNzMgUTI0LjEyNSA3NC4yMTg4IDI4LjQyMTkgNzQuMjE4OCBRMzkuNzUgNzQuMjE4OCA0Ni40ODQ0IDY4LjU0NjkgUTUzLjIxODggNjIuODkwNiA1My4yMTg4IDUzLjQyMTkgUTUzLjIxODggNDguOTIxOSA1MS41MzEyIDQ0Ljg5MDYgUTQ5Ljg1OTQgNDAuODc1IDQ1LjQwNjIgMzUuNDA2MiBRNDQuMTg3NSAzMy45ODQ0IDM3LjY0MDYgMjcuMjE4OCBRMzEuMTA5NCAyMC40NTMxIDE5LjE4NzUgOC4yOTY4OCIgaWQ9IkRlamFWdVNhbnMtMzIiLz4KICAgICAgPC9kZWZzPgogICAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSg1Mi41MDc3MjMyMTQzIDE5MS42Nzk2ODc1KXNjYWxlKDAuMDkgLTAuMDkpIj4KICAgICAgIDx1c2UgeGxpbms6aHJlZj0iI0RlamFWdVNhbnMtMjIxMiIvPgogICAgICAgPHVzZSB4PSI4My43ODkwNjI1IiB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMiIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICAgPGcgaWQ9Inh0aWNrXzMiPgogICAgIDxnIGlkPSJsaW5lMmRfNyI+CiAgICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNODAuMzU3MSAxNzcuNSBMODAuMzU3MSAyMi41IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF84Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSI4MC4zNTcxNDI4NTcxIiB4bGluazpocmVmPSIjbTAwMTJkZDRlZWYiIHk9IjE3Ny41Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF85Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSI4MC4zNTcxNDI4NTcxIiB4bGluazpocmVmPSIjbTQ3NjM0NDk2OWMiIHk9IjIyLjUiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0idGV4dF8zIj4KICAgICAgPCEtLSDiiJIxIC0tPgogICAgICA8ZGVmcz4KICAgICAgIDxwYXRoIGQ9IiBNMTIuNDA2MiA4LjI5Njg4IEwyOC41MTU2IDguMjk2ODggTDI4LjUxNTYgNjMuOTIxOSBMMTAuOTg0NCA2MC40MDYyIEwxMC45ODQ0IDY5LjM5MDYgTDI4LjQyMTkgNzIuOTA2MiBMMzguMjgxMiA3Mi45MDYyIEwzOC4yODEyIDguMjk2ODggTDU0LjM5MDYgOC4yOTY4OCBMNTQuMzkwNiAwIEwxMi40MDYyIDAgeiAiIGlkPSJEZWphVnVTYW5zLTMxIi8+CiAgICAgIDwvZGVmcz4KICAgICAgPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNzQuNjE1NDI0MTA3MSAxOTEuNTYxNTYyNSlzY2FsZSgwLjA5IC0wLjA5KSI+CiAgICAgICA8dXNlIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTIyMTIiLz4KICAgICAgIDx1c2UgeD0iODMuNzg5MDYyNSIgeGxpbms6aHJlZj0iI0RlamFWdVNhbnMtMzEiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgIDwvZz4KICAgIDxnIGlkPSJ4dGlja180Ij4KICAgICA8ZyBpZD0ibGluZTJkXzEwIj4KICAgICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0xMDIuNSAxNzcuNSBMMTAyLjUgMjIuNSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDtzdHJva2UtZGFzaGFycmF5OjEuMDAwMDAwLDMuMDAwMDAwO3N0cm9rZS1kYXNob2Zmc2V0OjAuMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMTEiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjEwMi41IiB4bGluazpocmVmPSIjbTAwMTJkZDRlZWYiIHk9IjE3Ny41Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8xMiI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTAyLjUiIHhsaW5rOmhyZWY9IiNtNDc2MzQ0OTY5YyIgeT0iMjIuNSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzQiPgogICAgICA8IS0tIDAgLS0+CiAgICAgIDxkZWZzPgogICAgICAgPHBhdGggZD0iIE0zMS43ODEyIDY2LjQwNjIgUTI0LjE3MTkgNjYuNDA2MiAyMC4zMjgxIDU4LjkwNjIgUTE2LjUgNTEuNDIxOSAxNi41IDM2LjM3NSBRMTYuNSAyMS4zOTA2IDIwLjMyODEgMTMuODkwNiBRMjQuMTcxOSA2LjM5MDYyIDMxLjc4MTIgNi4zOTA2MiBRMzkuNDUzMSA2LjM5MDYyIDQzLjI4MTIgMTMuODkwNiBRNDcuMTI1IDIxLjM5MDYgNDcuMTI1IDM2LjM3NSBRNDcuMTI1IDUxLjQyMTkgNDMuMjgxMiA1OC45MDYyIFEzOS40NTMxIDY2LjQwNjIgMzEuNzgxMiA2Ni40MDYyIE0zMS43ODEyIDc0LjIxODggUTQ0LjA0NjkgNzQuMjE4OCA1MC41MTU2IDY0LjUxNTYgUTU2Ljk4NDQgNTQuODI4MSA1Ni45ODQ0IDM2LjM3NSBRNTYuOTg0NCAxNy45Njg4IDUwLjUxNTYgOC4yNjU2MiBRNDQuMDQ2OSAtMS40MjE4OCAzMS43ODEyIC0xLjQyMTg4IFExOS41MzEyIC0xLjQyMTg4IDEzLjA2MjUgOC4yNjU2MiBRNi41OTM3NSAxNy45Njg4IDYuNTkzNzUgMzYuMzc1IFE2LjU5Mzc1IDU0LjgyODEgMTMuMDYyNSA2NC41MTU2IFExOS41MzEyIDc0LjIxODggMzEuNzgxMiA3NC4yMTg4IiBpZD0iRGVqYVZ1U2Fucy0zMCIvPgogICAgICA8L2RlZnM+CiAgICAgIDxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDEwMC4yMzI0MjE4NzUgMTkxLjY3OTY4NzUpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMCIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICAgPGcgaWQ9Inh0aWNrXzUiPgogICAgIDxnIGlkPSJsaW5lMmRfMTMiPgogICAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTEyNC42NDMgMTc3LjUgTDEyNC42NDMgMjIuNSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDtzdHJva2UtZGFzaGFycmF5OjEuMDAwMDAwLDMuMDAwMDAwO3N0cm9rZS1kYXNob2Zmc2V0OjAuMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMTQiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjEyNC42NDI4NTcxNDMiIHhsaW5rOmhyZWY9IiNtMDAxMmRkNGVlZiIgeT0iMTc3LjUiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzE1Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxMjQuNjQyODU3MTQzIiB4bGluazpocmVmPSIjbTQ3NjM0NDk2OWMiIHk9IjIyLjUiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0idGV4dF81Ij4KICAgICAgPCEtLSAxIC0tPgogICAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMjIuNjg5NTc1ODkzIDE5MS41NjE1NjI1KXNjYWxlKDAuMDkgLTAuMDkpIj4KICAgICAgIDx1c2UgeGxpbms6aHJlZj0iI0RlamFWdVNhbnMtMzEiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgIDwvZz4KICAgIDxnIGlkPSJ4dGlja182Ij4KICAgICA8ZyBpZD0ibGluZTJkXzE2Ij4KICAgICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0xNDYuNzg2IDE3Ny41IEwxNDYuNzg2IDIyLjUiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWRhc2hhcnJheToxLjAwMDAwMCwzLjAwMDAwMDtzdHJva2UtZGFzaG9mZnNldDowLjA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzE3Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxNDYuNzg1NzE0Mjg2IiB4bGluazpocmVmPSIjbTAwMTJkZDRlZWYiIHk9IjE3Ny41Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8xOCI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTQ2Ljc4NTcxNDI4NiIgeGxpbms6aHJlZj0iI200NzYzNDQ5NjljIiB5PSIyMi41Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9InRleHRfNiI+CiAgICAgIDwhLS0gMiAtLT4KICAgICAgPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMTQ0LjcwMzA1ODAzNiAxOTEuNjc5Njg3NSlzY2FsZSgwLjA5IC0wLjA5KSI+CiAgICAgICA8dXNlIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTMyIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICA8L2c+CiAgICA8ZyBpZD0ieHRpY2tfNyI+CiAgICAgPGcgaWQ9ImxpbmUyZF8xOSI+CiAgICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMTY4LjkyOSAxNzcuNSBMMTY4LjkyOSAyMi41IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8yMCI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTY4LjkyODU3MTQyOSIgeGxpbms6aHJlZj0iI20wMDEyZGQ0ZWVmIiB5PSIxNzcuNSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMjEiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjE2OC45Mjg1NzE0MjkiIHhsaW5rOmhyZWY9IiNtNDc2MzQ0OTY5YyIgeT0iMjIuNSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzciPgogICAgICA8IS0tIDMgLS0+CiAgICAgIDxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDE2Ni43NjkyNzQ1NTQgMTkxLjY3OTY4NzUpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMyIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICA8L2c+CiAgIDxnIGlkPSJtYXRwbG90bGliLmF4aXNfMiI+CiAgICA8ZyBpZD0ieXRpY2tfMSI+CiAgICAgPGcgaWQ9ImxpbmUyZF8yMiI+CiAgICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMjUgMTY2LjQyOSBMMTgwIDE2Ni40MjkiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWRhc2hhcnJheToxLjAwMDAwMCwzLjAwMDAwMDtzdHJva2UtZGFzaG9mZnNldDowLjA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzIzIj4KICAgICAgPGRlZnM+CiAgICAgICA8cGF0aCBkPSIgTTAgMCBMNCAwIiBpZD0ibWU4YTg1ZjdiZjYiIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICAgIDwvZGVmcz4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIyNS4wIiB4bGluazpocmVmPSIjbWU4YTg1ZjdiZjYiIHk9IjE2Ni40Mjg1NzE0MjkiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzI0Ij4KICAgICAgPGRlZnM+CiAgICAgICA8cGF0aCBkPSIgTTAgMCBMLTQgMCIgaWQ9Im0xYTMyMDA1ZGVhIiBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgICA8L2RlZnM+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTgwLjAiIHhsaW5rOmhyZWY9IiNtMWEzMjAwNWRlYSIgeT0iMTY2LjQyODU3MTQyOSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzgiPgogICAgICA8IS0tIOKIkjMgLS0+CiAgICAgIDxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDUuOTA2ODc1IDE2OS43MDQ0MzA4MDQpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0yMjEyIi8+CiAgICAgICA8dXNlIHg9IjgzLjc4OTA2MjUiIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTMzIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICA8L2c+CiAgICA8ZyBpZD0ieXRpY2tfMiI+CiAgICAgPGcgaWQ9ImxpbmUyZF8yNSI+CiAgICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMjUgMTQ0LjI4NiBMMTgwIDE0NC4yODYiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWRhc2hhcnJheToxLjAwMDAwMCwzLjAwMDAwMDtzdHJva2UtZGFzaG9mZnNldDowLjA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzI2Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIyNS4wIiB4bGluazpocmVmPSIjbWU4YTg1ZjdiZjYiIHk9IjE0NC4yODU3MTQyODYiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0ibGluZTJkXzI3Ij4KICAgICAgPGc+CiAgICAgICA8dXNlIHN0eWxlPSJzdHJva2U6IzAwMDAwMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxODAuMCIgeGxpbms6aHJlZj0iI20xYTMyMDA1ZGVhIiB5PSIxNDQuMjg1NzE0Mjg2Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9InRleHRfOSI+CiAgICAgIDwhLS0g4oiSMiAtLT4KICAgICAgPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNi4wODY4NzUgMTQ3LjYyNTU1ODAzNilzY2FsZSgwLjA5IC0wLjA5KSI+CiAgICAgICA8dXNlIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTIyMTIiLz4KICAgICAgIDx1c2UgeD0iODMuNzg5MDYyNSIgeGxpbms6aHJlZj0iI0RlamFWdVNhbnMtMzIiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgIDwvZz4KICAgIDxnIGlkPSJ5dGlja18zIj4KICAgICA8ZyBpZD0ibGluZTJkXzI4Ij4KICAgICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0yNSAxMjIuMTQzIEwxODAgMTIyLjE0MyIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDtzdHJva2UtZGFzaGFycmF5OjEuMDAwMDAwLDMuMDAwMDAwO3N0cm9rZS1kYXNob2Zmc2V0OjAuMDtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMjkiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjI1LjAiIHhsaW5rOmhyZWY9IiNtZThhODVmN2JmNiIgeT0iMTIyLjE0Mjg1NzE0MyIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMzAiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjE4MC4wIiB4bGluazpocmVmPSIjbTFhMzIwMDVkZWEiIHk9IjEyMi4xNDI4NTcxNDMiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgICA8ZyBpZD0idGV4dF8xMCI+CiAgICAgIDwhLS0g4oiSMSAtLT4KICAgICAgPGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNi4wMTY1NjI1IDEyNS40MjM2MzgzOTMpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0yMjEyIi8+CiAgICAgICA8dXNlIHg9IjgzLjc4OTA2MjUiIHhsaW5rOmhyZWY9IiNEZWphVnVTYW5zLTMxIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICA8L2c+CiAgICA8ZyBpZD0ieXRpY2tfNCI+CiAgICAgPGcgaWQ9ImxpbmUyZF8zMSI+CiAgICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMjUgMTAwIEwxODAgMTAwIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8zMiI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMjUuMCIgeGxpbms6aHJlZj0iI21lOGE4NWY3YmY2IiB5PSIxMDAuMCIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJsaW5lMmRfMzMiPgogICAgICA8Zz4KICAgICAgIDx1c2Ugc3R5bGU9InN0cm9rZTojMDAwMDAwO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjE4MC4wIiB4bGluazpocmVmPSIjbTFhMzIwMDVkZWEiIHk9IjEwMC4wIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9InRleHRfMTEiPgogICAgICA8IS0tIDAgLS0+CiAgICAgIDxnIHRyYW5zZm9ybT0idHJhbnNsYXRlKDEyLjk2NDg0Mzc1IDEwMy4yNzU4NTkzNzUpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMCIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICAgPGcgaWQ9Inl0aWNrXzUiPgogICAgIDxnIGlkPSJsaW5lMmRfMzQiPgogICAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTI1IDc3Ljg1NzEgTDE4MCA3Ny44NTcxIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8zNSI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMjUuMCIgeGxpbms6aHJlZj0iI21lOGE4NWY3YmY2IiB5PSI3Ny44NTcxNDI4NTcxIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8zNiI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTgwLjAiIHhsaW5rOmhyZWY9IiNtMWEzMjAwNWRlYSIgeT0iNzcuODU3MTQyODU3MSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzEyIj4KICAgICAgPCEtLSAxIC0tPgogICAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMy41OTM0Mzc1IDgxLjEzNzkyNDEwNzEpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMSIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICAgPGcgaWQ9Inl0aWNrXzYiPgogICAgIDxnIGlkPSJsaW5lMmRfMzciPgogICAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTI1IDU1LjcxNDMgTDE4MCA1NS43MTQzIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8zOCI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMjUuMCIgeGxpbms6aHJlZj0iI21lOGE4NWY3YmY2IiB5PSI1NS43MTQyODU3MTQzIi8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF8zOSI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTgwLjAiIHhsaW5rOmhyZWY9IiNtMWEzMjAwNWRlYSIgeT0iNTUuNzE0Mjg1NzE0MyIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzEzIj4KICAgICAgPCEtLSAyIC0tPgogICAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMy4zMzQ2ODc1IDU5LjA1NDEyOTQ2NDMpc2NhbGUoMC4wOSAtMC4wOSkiPgogICAgICAgPHVzZSB4bGluazpocmVmPSIjRGVqYVZ1U2Fucy0zMiIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgPC9nPgogICAgPGcgaWQ9Inl0aWNrXzciPgogICAgIDxnIGlkPSJsaW5lMmRfNDAiPgogICAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTI1IDMzLjU3MTQgTDE4MCAzMy41NzE0IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS1kYXNoYXJyYXk6MS4wMDAwMDAsMy4wMDAwMDA7c3Ryb2tlLWRhc2hvZmZzZXQ6MC4wO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF80MSI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMjUuMCIgeGxpbms6aHJlZj0iI21lOGE4NWY3YmY2IiB5PSIzMy41NzE0Mjg1NzE0Ii8+CiAgICAgIDwvZz4KICAgICA8L2c+CiAgICAgPGcgaWQ9ImxpbmUyZF80MiI+CiAgICAgIDxnPgogICAgICAgPHVzZSBzdHlsZT0ic3Ryb2tlOiMwMDAwMDA7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTgwLjAiIHhsaW5rOmhyZWY9IiNtMWEzMjAwNWRlYSIgeT0iMzMuNTcxNDI4NTcxNCIvPgogICAgICA8L2c+CiAgICAgPC9nPgogICAgIDxnIGlkPSJ0ZXh0XzE0Ij4KICAgICAgPCEtLSAzIC0tPgogICAgICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMy4xODE0MDYyNSAzNi44NDcyODc5NDY0KXNjYWxlKDAuMDkgLTAuMDkpIj4KICAgICAgIDx1c2UgeGxpbms6aHJlZj0iI0RlamFWdVNhbnMtMzMiLz4KICAgICAgPC9nPgogICAgIDwvZz4KICAgIDwvZz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzQzIj4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMjQuNTU3MSAxNjYuNDI5IEwzNi4wNzE0IDE2Ni40MjkiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzQ0Ij4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMzYuMDcxNCAxNDQuMjg2IEw1OC4yMTQzIDE0NC4yODYiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzQ1Ij4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNNTguMjE0MyAxMjIuMTQzIEw4MC4zNTcxIDEyMi4xNDMiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzQ2Ij4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNODAuMzU3MSAxMDAgTDEyNC42NDMgMTAwIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMGZmO3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF80NyI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTEyNC42NDMgNzcuODU3MSBMMTQ2Ljc4NiA3Ny44NTcxIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMGZmO3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF80OCI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTE0Ni43ODYgNTUuNzE0MyBMMTY4LjkyOSA1NS43MTQzIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMGZmO3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF80OSI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTE2OC45MjkgMzMuNTcxNCBMMTgwIDMzLjU3MTQiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLXdpZHRoOjAuNTsiLz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzUwIj4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMzYuMDcxNCAxNjYuNDI5IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMGZmOyIvPgogICAgPGRlZnM+CiAgICAgPHBhdGggZD0iIE0wIDMuNzUgQzAuOTk0NTEyIDMuNzUgMS45NDg0MiAzLjM1NDg4IDIuNjUxNjUgMi42NTE2NSBDMy4zNTQ4OCAxLjk0ODQyIDMuNzUgMC45OTQ1MTIgMy43NSAwIEMzLjc1IC0wLjk5NDUxMiAzLjM1NDg4IC0xLjk0ODQyIDIuNjUxNjUgLTIuNjUxNjUgQzEuOTQ4NDIgLTMuMzU0ODggMC45OTQ1MTIgLTMuNzUgMCAtMy43NSBDLTAuOTk0NTEyIC0zLjc1IC0xLjk0ODQyIC0zLjM1NDg4IC0yLjY1MTY1IC0yLjY1MTY1IEMtMy4zNTQ4OCAtMS45NDg0MiAtMy43NSAtMC45OTQ1MTIgLTMuNzUgMCBDLTMuNzUgMC45OTQ1MTIgLTMuMzU0ODggMS45NDg0MiAtMi42NTE2NSAyLjY1MTY1IEMtMS45NDg0MiAzLjM1NDg4IC0wLjk5NDUxMiAzLjc1IDAgMy43NSB6ICIgaWQ9Im1lNTNiN2JiNmQyIiBzdHlsZT0ic3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIvPgogICAgPC9kZWZzPgogICAgPGcgY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSI+CiAgICAgPHVzZSBzdHlsZT0iZmlsbDojMDAwMGZmO3N0cm9rZTojMDAwMGZmO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjM2LjA3MTQyODU3MTQiIHhsaW5rOmhyZWY9IiNtZTUzYjdiYjZkMiIgeT0iMTY2LjQyODU3MTQyOSIvPgogICAgPC9nPgogICA8L2c+CiAgIDxnIGlkPSJsaW5lMmRfNTEiPgogICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0zNi4wNzE0IDE0NC4yODYiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDgwMDA7Ii8+CiAgICA8ZGVmcz4KICAgICA8cGF0aCBkPSIgTTAgMy43NSBDMC45OTQ1MTIgMy43NSAxLjk0ODQyIDMuMzU0ODggMi42NTE2NSAyLjY1MTY1IEMzLjM1NDg4IDEuOTQ4NDIgMy43NSAwLjk5NDUxMiAzLjc1IDAgQzMuNzUgLTAuOTk0NTEyIDMuMzU0ODggLTEuOTQ4NDIgMi42NTE2NSAtMi42NTE2NSBDMS45NDg0MiAtMy4zNTQ4OCAwLjk5NDUxMiAtMy43NSAwIC0zLjc1IEMtMC45OTQ1MTIgLTMuNzUgLTEuOTQ4NDIgLTMuMzU0ODggLTIuNjUxNjUgLTIuNjUxNjUgQy0zLjM1NDg4IC0xLjk0ODQyIC0zLjc1IC0wLjk5NDUxMiAtMy43NSAwIEMtMy43NSAwLjk5NDUxMiAtMy4zNTQ4OCAxLjk0ODQyIC0yLjY1MTY1IDIuNjUxNjUgQy0xLjk0ODQyIDMuMzU0ODggLTAuOTk0NTEyIDMuNzUgMCAzLjc1IHogIiBpZD0ibWUyNzgwNjQyZTIiIHN0eWxlPSJzdHJva2U6IzAwMDBmZjtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7Ii8+CiAgICA8L2RlZnM+CiAgICA8ZyBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIj4KICAgICA8dXNlIHN0eWxlPSJmaWxsOiNmZmZmZmY7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMzYuMDcxNDI4NTcxNCIgeGxpbms6aHJlZj0iI21lMjc4MDY0MmUyIiB5PSIxNDQuMjg1NzE0Mjg2Ii8+CiAgICA8L2c+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF81MiI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTU4LjIxNDMgMTQ0LjI4NiIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6I2ZmMDAwMDsiLz4KICAgIDxnIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiPgogICAgIDx1c2Ugc3R5bGU9ImZpbGw6IzAwMDBmZjtzdHJva2U6IzAwMDBmZjtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSI1OC4yMTQyODU3MTQzIiB4bGluazpocmVmPSIjbWU1M2I3YmI2ZDIiIHk9IjE0NC4yODU3MTQyODYiLz4KICAgIDwvZz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzUzIj4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNNTguMjE0MyAxMjIuMTQzIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDBiZmJmOyIvPgogICAgPGcgY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSI+CiAgICAgPHVzZSBzdHlsZT0iZmlsbDojZmZmZmZmO3N0cm9rZTojMDAwMGZmO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjU4LjIxNDI4NTcxNDMiIHhsaW5rOmhyZWY9IiNtZTI3ODA2NDJlMiIgeT0iMTIyLjE0Mjg1NzE0MyIvPgogICAgPC9nPgogICA8L2c+CiAgIDxnIGlkPSJsaW5lMmRfNTQiPgogICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE04MC4zNTcxIDEyMi4xNDMiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiNiZjAwYmY7Ii8+CiAgICA8ZyBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIj4KICAgICA8dXNlIHN0eWxlPSJmaWxsOiMwMDAwZmY7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iODAuMzU3MTQyODU3MSIgeGxpbms6aHJlZj0iI21lNTNiN2JiNmQyIiB5PSIxMjIuMTQyODU3MTQzIi8+CiAgICA8L2c+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF81NSI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTgwLjM1NzEgMTAwIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojYmZiZjAwOyIvPgogICAgPGcgY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSI+CiAgICAgPHVzZSBzdHlsZT0iZmlsbDojZmZmZmZmO3N0cm9rZTojMDAwMGZmO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjgwLjM1NzE0Mjg1NzEiIHhsaW5rOmhyZWY9IiNtZTI3ODA2NDJlMiIgeT0iMTAwLjAiLz4KICAgIDwvZz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzU2Ij4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMTI0LjY0MyAxMDAiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwMDA7Ii8+CiAgICA8ZyBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIj4KICAgICA8dXNlIHN0eWxlPSJmaWxsOiNmZmZmZmY7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTI0LjY0Mjg1NzE0MyIgeGxpbms6aHJlZj0iI21lMjc4MDY0MmUyIiB5PSIxMDAuMCIvPgogICAgPC9nPgogICA8L2c+CiAgIDxnIGlkPSJsaW5lMmRfNTciPgogICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0xMjQuNjQzIDc3Ljg1NzEiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwZmY7Ii8+CiAgICA8ZyBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIj4KICAgICA8dXNlIHN0eWxlPSJmaWxsOiMwMDAwZmY7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTI0LjY0Mjg1NzE0MyIgeGxpbms6aHJlZj0iI21lNTNiN2JiNmQyIiB5PSI3Ny44NTcxNDI4NTcxIi8+CiAgICA8L2c+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF81OCI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTE0Ni43ODYgNzcuODU3MSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwODAwMDsiLz4KICAgIDxnIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiPgogICAgIDx1c2Ugc3R5bGU9ImZpbGw6I2ZmZmZmZjtzdHJva2U6IzAwMDBmZjtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxNDYuNzg1NzE0Mjg2IiB4bGluazpocmVmPSIjbWUyNzgwNjQyZTIiIHk9Ijc3Ljg1NzE0Mjg1NzEiLz4KICAgIDwvZz4KICAgPC9nPgogICA8ZyBpZD0ibGluZTJkXzU5Ij4KICAgIDxwYXRoIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiIGQ9IiBNMTQ2Ljc4NiA1NS43MTQzIiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojZmYwMDAwOyIvPgogICAgPGcgY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSI+CiAgICAgPHVzZSBzdHlsZT0iZmlsbDojMDAwMGZmO3N0cm9rZTojMDAwMGZmO3N0cm9rZS1saW5lY2FwOmJ1dHQ7c3Ryb2tlLXdpZHRoOjAuNTsiIHg9IjE0Ni43ODU3MTQyODYiIHhsaW5rOmhyZWY9IiNtZTUzYjdiYjZkMiIgeT0iNTUuNzE0Mjg1NzE0MyIvPgogICAgPC9nPgogICA8L2c+CiAgIDxnIGlkPSJsaW5lMmRfNjAiPgogICAgPHBhdGggY2xpcC1wYXRoPSJ1cmwoI3A0MGZlYzExNTNmKSIgZD0iIE0xNjguOTI5IDU1LjcxNDMiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMGJmYmY7Ii8+CiAgICA8ZyBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIj4KICAgICA8dXNlIHN0eWxlPSJmaWxsOiNmZmZmZmY7c3Ryb2tlOiMwMDAwZmY7c3Ryb2tlLWxpbmVjYXA6YnV0dDtzdHJva2Utd2lkdGg6MC41OyIgeD0iMTY4LjkyODU3MTQyOSIgeGxpbms6aHJlZj0iI21lMjc4MDY0MmUyIiB5PSI1NS43MTQyODU3MTQzIi8+CiAgICA8L2c+CiAgIDwvZz4KICAgPGcgaWQ9ImxpbmUyZF82MSI+CiAgICA8cGF0aCBjbGlwLXBhdGg9InVybCgjcDQwZmVjMTE1M2YpIiBkPSIgTTE2OC45MjkgMzMuNTcxNCIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6I2JmMDBiZjsiLz4KICAgIDxnIGNsaXAtcGF0aD0idXJsKCNwNDBmZWMxMTUzZikiPgogICAgIDx1c2Ugc3R5bGU9ImZpbGw6IzAwMDBmZjtzdHJva2U6IzAwMDBmZjtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS13aWR0aDowLjU7IiB4PSIxNjguOTI4NTcxNDI5IiB4bGluazpocmVmPSIjbWU1M2I3YmI2ZDIiIHk9IjMzLjU3MTQyODU3MTQiLz4KICAgIDwvZz4KICAgPC9nPgogICA8ZyBpZD0icGF0Y2hfMyI+CiAgICA8cGF0aCBkPSIgTTI1IDIyLjUgTDE4MCAyMi41IiBzdHlsZT0iZmlsbDpub25lO3N0cm9rZTojMDAwMDAwOyIvPgogICA8L2c+CiAgIDxnIGlkPSJwYXRjaF80Ij4KICAgIDxwYXRoIGQ9IiBNMTgwIDE3Ny41IEwxODAgMjIuNSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDsiLz4KICAgPC9nPgogICA8ZyBpZD0icGF0Y2hfNSI+CiAgICA8cGF0aCBkPSIgTTI1IDE3Ny41IEwxODAgMTc3LjUiIHN0eWxlPSJmaWxsOm5vbmU7c3Ryb2tlOiMwMDAwMDA7Ii8+CiAgIDwvZz4KICAgPGcgaWQ9InBhdGNoXzYiPgogICAgPHBhdGggZD0iIE0yNSAxNzcuNSBMMjUgMjIuNSIgc3R5bGU9ImZpbGw6bm9uZTtzdHJva2U6IzAwMDAwMDsiLz4KICAgPC9nPgogIDwvZz4KIDwvZz4KIDxkZWZzPgogIDxjbGlwUGF0aCBpZD0icDQwZmVjMTE1M2YiPgogICA8cmVjdCBoZWlnaHQ9IjE1NS4wIiB3aWR0aD0iMTU1LjAiIHg9IjI1LjAiIHk9IjIyLjUiLz4KICA8L2NsaXBQYXRoPgogPC9kZWZzPgo8L3N2Zz4K" width="200" height="200"></div> <div class="t-plot-bottom">Argument</div> </div> <h3 id="Error_handling"> Error handling</h3> <p>Errors are reported as specified in <a href="math_errhandling" title="c/numeric/math/math errhandling">math_errhandling</a>.</p> +<p>If the implementation supports IEEE floating-point arithmetic (IEC 60559),</p> +<ul> +<li> The current <a href="../fenv/fe_round" title="c/numeric/fenv/FE round">rounding mode</a> has no effect. </li> +<li> If <code>arg</code> is ±∞, it is returned, unmodified </li> +<li> If <code>arg</code> is ±0, it is returned, unmodified </li> +<li> If arg is NaN, NaN is returned </li> +</ul> <h3 id="Notes"> Notes</h3> <p><code><a href="../fenv/fe_exceptions" title="c/numeric/fenv/FE exceptions">FE_INEXACT</a></code> may be (but isn't required to be) raised when truncating a non-integer finite value.</p> +<p>The largest representable floating-point values are exact integers in all standard floating-point formats, so this function never overflows on its own; however the result may overflow any integer type (including <code><a href="../../types/integer" title="c/types/integer">intmax_t</a></code>), when stored in an integer variable.</p> +<p>The implicit conversion from floating-point to integral types also rounds towards zero, but is limited to the values that can be represented by the target type.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <math.h> +#include <stdio.h> +int main(void) +{ + printf("trunc(+2.7) = %+.1f\n", trunc(2.7)); + printf("trunc(-2.7) = %+.1f\n", trunc(-2.7)); + printf("trunc(-0.0) = %+.1f\n", trunc(-0.0)); + printf("trunc(-Inf) = %+f\n", trunc(-INFINITY)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">trunc(+2.7) = +2.0 +trunc(-2.7) = -2.0 +trunc(-0.0) = -0.0 +trunc(-Inf) = -inf</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.12.9.8 The trunc functions (p: 253-254) </li> +<li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li> +<li> F.10.6.8 The trunc functions (p: 528) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.12.9.8 The trunc functions (p: 234) </li> +<li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li> +<li> F.9.6.8 The trunc functions (p: 464) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="floor" title="c/numeric/math/floor"> <span class="t-lines"><span>floor</span><span>floorf</span><span>floorl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes largest integer not greater than the given value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ceil" title="c/numeric/math/ceil"> <span class="t-lines"><span>ceil</span><span>ceilf</span><span>ceill</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes smallest integer not less than the given value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="round" title="c/numeric/math/round"> <span class="t-lines"><span>round</span><span>roundf</span><span>roundl</span><span>lround</span><span>lroundf</span><span>lroundl</span><span>llround</span><span>llroundf</span><span>llroundl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> rounds to nearest integer, rounding away from zero in halfway cases <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math/trunc" title="cpp/numeric/math/trunc">C++ documentation</a></span> for <code>trunc</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math/trunc" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math/trunc</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Fmath.html b/devdocs/c/numeric%2Fmath.html new file mode 100644 index 00000000..aeb71314 --- /dev/null +++ b/devdocs/c/numeric%2Fmath.html @@ -0,0 +1,212 @@ + <h1 id="firstHeading" class="firstHeading">Common mathematical functions</h1> <h3 id="Functions"> Functions</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdlib.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="math/abs" title="c/numeric/math/abs"> <span class="t-lines"><span>abs</span><span>labs</span><span>llabs</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes absolute value of an integral value (\(\small{|x|}\)|x|) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/div" title="c/numeric/math/div"> <span class="t-lines"><span>div</span><span>ldiv</span><span>lldiv</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes quotient and remainder of integer division <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><inttypes.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="math/abs" title="c/numeric/math/abs"> <span class="t-lines"><span>imaxabs</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes absolute value of an integral value (\(\small{|x|}\)|x|) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/div" title="c/numeric/math/div"> <span class="t-lines"><span>imaxdiv</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes quotient and remainder of integer division <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><math.h></code> </th> +</tr> <tr> <td colspan="2"> <h5 id="Basic_operations"> Basic operations </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/fabs" title="c/numeric/math/fabs"> <span class="t-lines"><span>fabs</span><span>fabsf</span><span>fabsl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes absolute value of a floating-point value (\(\small{|x|}\)|x|) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/fmod" title="c/numeric/math/fmod"> <span class="t-lines"><span>fmod</span><span>fmodf</span><span>fmodl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes remainder of the floating-point division operation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/remainder" title="c/numeric/math/remainder"> <span class="t-lines"><span>remainder</span><span>remainderf</span><span>remainderl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes signed remainder of the floating-point division operation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/remquo" title="c/numeric/math/remquo"> <span class="t-lines"><span>remquo</span><span>remquof</span><span>remquol</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes signed remainder as well as the three last bits of the division operation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/fma" title="c/numeric/math/fma"> <span class="t-lines"><span>fma</span><span>fmaf</span><span>fmal</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes fused multiply-add operation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/fmax" title="c/numeric/math/fmax"> <span class="t-lines"><span>fmax</span><span>fmaxf</span><span>fmaxl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> determines larger of two floating-point values <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/fmin" title="c/numeric/math/fmin"> <span class="t-lines"><span>fmin</span><span>fminf</span><span>fminl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> determines smaller of two floating-point values <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/fdim" title="c/numeric/math/fdim"> <span class="t-lines"><span>fdim</span><span>fdimf</span><span>fdiml</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> determines positive difference of two floating-point values (\({\small\max{(0, x-y)} }\)max(0, x-y)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/nan" title="c/numeric/math/nan"> <span class="t-lines"><span>nan</span><span>nanf</span><span>nanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> returns a NaN (not-a-number) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Exponential_functions"> Exponential functions </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/exp" title="c/numeric/math/exp"> <span class="t-lines"><span>exp</span><span>expf</span><span>expl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes <i>e</i> raised to the given power (\({\small e^x}\)e<sup>x</sup>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/exp2" title="c/numeric/math/exp2"> <span class="t-lines"><span>exp2</span><span>exp2f</span><span>exp2l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes <i>2</i> raised to the given power (\({\small 2^x}\)2<sup>x</sup>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/expm1" title="c/numeric/math/expm1"> <span class="t-lines"><span>expm1</span><span>expm1f</span><span>expm1l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes <i>e</i> raised to the given power, minus one (\({\small e^x-1}\)e<sup>x</sup>-1) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/log" title="c/numeric/math/log"> <span class="t-lines"><span>log</span><span>logf</span><span>logl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes natural (base-<i>e</i>) logarithm (\({\small \ln{x} }\)ln(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/log10" title="c/numeric/math/log10"> <span class="t-lines"><span>log10</span><span>log10f</span><span>log10l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes common (base-<i>10</i>) logarithm (\({\small \log_{10}{x} }\)log<sub>10</sub>(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/log2" title="c/numeric/math/log2"> <span class="t-lines"><span>log2</span><span>log2f</span><span>log2l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes base-2 logarithm (\({\small \log_{2}{x} }\)log<sub>2</sub>(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/log1p" title="c/numeric/math/log1p"> <span class="t-lines"><span>log1p</span><span>log1pf</span><span>log1pl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes natural (base-<i>e</i>) logarithm of 1 plus the given number (\({\small \ln{(1+x)} }\)ln(1+x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Power_functions"> Power functions </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/pow" title="c/numeric/math/pow"> <span class="t-lines"><span>pow</span><span>powf</span><span>powl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes a number raised to the given power (\(\small{x^y}\)x<sup>y</sup>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/sqrt" title="c/numeric/math/sqrt"> <span class="t-lines"><span>sqrt</span><span>sqrtf</span><span>sqrtl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes square root (\(\small{\sqrt{x} }\)<span class="t-mrad"><span>√</span><span>x</span></span>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/cbrt" title="c/numeric/math/cbrt"> <span class="t-lines"><span>cbrt</span><span>cbrtf</span><span>cbrtl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes cube root (\(\small{\sqrt[3]{x} }\)<span class="t-mrad"><span>3</span><span>√</span><span>x</span></span>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/hypot" title="c/numeric/math/hypot"> <span class="t-lines"><span>hypot</span><span>hypotf</span><span>hypotl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes square root of the sum of the squares of two given numbers (\(\scriptsize{\sqrt{x^2+y^2} }\)<span class="t-mrad"><span>√</span><span>x<sup class="t-su">2</sup>+y<sup class="t-su">2</sup></span></span>) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Trigonometric_functions"> Trigonometric functions </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/sin" title="c/numeric/math/sin"> <span class="t-lines"><span>sin</span><span>sinf</span><span>sinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes sine (\({\small\sin{x} }\)sin(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/cos" title="c/numeric/math/cos"> <span class="t-lines"><span>cos</span><span>cosf</span><span>cosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes cosine (\({\small\cos{x} }\)cos(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/tan" title="c/numeric/math/tan"> <span class="t-lines"><span>tan</span><span>tanf</span><span>tanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes tangent (\({\small\tan{x} }\)tan(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/asin" title="c/numeric/math/asin"> <span class="t-lines"><span>asin</span><span>asinf</span><span>asinl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc sine (\({\small\arcsin{x} }\)arcsin(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/acos" title="c/numeric/math/acos"> <span class="t-lines"><span>acos</span><span>acosf</span><span>acosl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc cosine (\({\small\arccos{x} }\)arccos(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/atan" title="c/numeric/math/atan"> <span class="t-lines"><span>atan</span><span>atanf</span><span>atanl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc tangent (\({\small\arctan{x} }\)arctan(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/atan2" title="c/numeric/math/atan2"> <span class="t-lines"><span>atan2</span><span>atan2f</span><span>atan2l</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes arc tangent, using signs to determine quadrants <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Hyperbolic_functions"> Hyperbolic functions </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/sinh" title="c/numeric/math/sinh"> <span class="t-lines"><span>sinh</span><span>sinhf</span><span>sinhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes hyperbolic sine (\({\small\sinh{x} }\)sinh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/cosh" title="c/numeric/math/cosh"> <span class="t-lines"><span>cosh</span><span>coshf</span><span>coshl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes hyperbolic cosine (\({\small\cosh{x} }\)cosh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/tanh" title="c/numeric/math/tanh"> <span class="t-lines"><span>tanh</span><span>tanhf</span><span>tanhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes hyperbolic tangent (\({\small\tanh{x} }\)tanh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/asinh" title="c/numeric/math/asinh"> <span class="t-lines"><span>asinh</span><span>asinhf</span><span>asinhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes inverse hyperbolic sine (\({\small\operatorname{arsinh}{x} }\)arsinh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/acosh" title="c/numeric/math/acosh"> <span class="t-lines"><span>acosh</span><span>acoshf</span><span>acoshl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes inverse hyperbolic cosine (\({\small\operatorname{arcosh}{x} }\)arcosh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/atanh" title="c/numeric/math/atanh"> <span class="t-lines"><span>atanh</span><span>atanhf</span><span>atanhl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes inverse hyperbolic tangent (\({\small\operatorname{artanh}{x} }\)artanh(x)) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Error_and_gamma_functions"> Error and gamma functions </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/erf" title="c/numeric/math/erf"> <span class="t-lines"><span>erf</span><span>erff</span><span>erfl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes error function <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/erfc" title="c/numeric/math/erfc"> <span class="t-lines"><span>erfc</span><span>erfcf</span><span>erfcl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes complementary error function <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/tgamma" title="c/numeric/math/tgamma"> <span class="t-lines"><span>tgamma</span><span>tgammaf</span><span>tgammal</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes gamma function <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/lgamma" title="c/numeric/math/lgamma"> <span class="t-lines"><span>lgamma</span><span>lgammaf</span><span>lgammal</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes natural (base-<i>e</i>) logarithm of the gamma function <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Nearest_integer_floating-point_operations"> Nearest integer floating-point operations </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/ceil" title="c/numeric/math/ceil"> <span class="t-lines"><span>ceil</span><span>ceilf</span><span>ceill</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes smallest integer not less than the given value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/floor" title="c/numeric/math/floor"> <span class="t-lines"><span>floor</span><span>floorf</span><span>floorl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes largest integer not greater than the given value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/trunc" title="c/numeric/math/trunc"> <span class="t-lines"><span>trunc</span><span>truncf</span><span>truncl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> rounds to nearest integer not greater in magnitude than the given value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/round" title="c/numeric/math/round"> <span class="t-lines"><span>round</span><span>roundf</span><span>roundl</span><span>lround</span><span>lroundf</span><span>lroundl</span><span>llround</span><span>llroundf</span><span>llroundl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> rounds to nearest integer, rounding away from zero in halfway cases <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/nearbyint" title="c/numeric/math/nearbyint"> <span class="t-lines"><span>nearbyint</span><span>nearbyintf</span><span>nearbyintl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> rounds to an integer using current rounding mode <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/rint" title="c/numeric/math/rint"> <span class="t-lines"><span>rint</span><span>rintf</span><span>rintl</span><span>lrint</span><span>lrintf</span><span>lrintl</span><span>llrint</span><span>llrintf</span><span>llrintl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> rounds to an integer using current rounding mode with <br> exception if the result differs <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Floating-point_manipulation_functions"> Floating-point manipulation functions </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/frexp" title="c/numeric/math/frexp"> <span class="t-lines"><span>frexp</span><span>frexpf</span><span>frexpl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> breaks a number into significand and a power of <code>2</code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/ldexp" title="c/numeric/math/ldexp"> <span class="t-lines"><span>ldexp</span><span>ldexpf</span><span>ldexpl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> multiplies a number by <code>2</code> raised to a power <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/modf" title="c/numeric/math/modf"> <span class="t-lines"><span>modf</span><span>modff</span><span>modfl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> breaks a number into integer and fractional parts <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/scalbn" title="c/numeric/math/scalbn"> <span class="t-lines"><span>scalbn</span><span>scalbnf</span><span>scalbnl</span><span>scalbln</span><span>scalblnf</span><span>scalblnl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> computes efficiently a number times <code><a href="../types/limits" title="c/types/limits">FLT_RADIX</a></code> raised to a power <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/ilogb" title="c/numeric/math/ilogb"> <span class="t-lines"><span>ilogb</span><span>ilogbf</span><span>ilogbl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> extracts exponent of the given number <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/logb" title="c/numeric/math/logb"> <span class="t-lines"><span>logb</span><span>logbf</span><span>logbl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> extracts exponent of the given number <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/nextafter" title="c/numeric/math/nextafter"> <span class="t-lines"><span>nextafter</span><span>nextafterf</span><span>nextafterl</span><span>nexttoward</span><span>nexttowardf</span><span>nexttowardl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> determines next representable floating-point value towards the given value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/copysign" title="c/numeric/math/copysign"> <span class="t-lines"><span>copysign</span><span>copysignf</span><span>copysignl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> produces a value with the magnitude of a given value and the sign of another given value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Classification_and_comparison"> Classification and comparison </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/fpclassify" title="c/numeric/math/fpclassify"> <span class="t-lines"><span>fpclassify</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> classifies the given floating-point value <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/isfinite" title="c/numeric/math/isfinite"> <span class="t-lines"><span>isfinite</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number has finite value <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/isinf" title="c/numeric/math/isinf"> <span class="t-lines"><span>isinf</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number is infinite <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/isnan" title="c/numeric/math/isnan"> <span class="t-lines"><span>isnan</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number is NaN <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/isnormal" title="c/numeric/math/isnormal"> <span class="t-lines"><span>isnormal</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number is normal <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/signbit" title="c/numeric/math/signbit"> <span class="t-lines"><span>signbit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the given number is negative <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/isgreater" title="c/numeric/math/isgreater"> <span class="t-lines"><span>isgreater</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the first floating-point argument is greater than the second <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/isgreaterequal" title="c/numeric/math/isgreaterequal"> <span class="t-lines"><span>isgreaterequal</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the first floating-point argument is greater or equal than the second <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/isless" title="c/numeric/math/isless"> <span class="t-lines"><span>isless</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the first floating-point argument is less than the second <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/islessequal" title="c/numeric/math/islessequal"> <span class="t-lines"><span>islessequal</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the first floating-point argument is less or equal than the second <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/islessgreater" title="c/numeric/math/islessgreater"> <span class="t-lines"><span>islessgreater</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if the first floating-point argument is less or greater than the second <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/isunordered" title="c/numeric/math/isunordered"> <span class="t-lines"><span>isunordered</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if two floating-point values are unordered <br> <span class="t-mark">(function macro)</span> </td> +</tr> </table> <h3 id="Types"> Types</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdlib.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="math/div" title="c/numeric/math/div"> <span class="t-lines"><span>div_t</span></span></a></div> </td> <td> structure type, return of the <code><a href="http://en.cppreference.com/w/c/numeric/math/div"><span class="kw645">div</span></a></code> function <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/div" title="c/numeric/math/div"> <span class="t-lines"><span>ldiv_t</span></span></a></div> </td> <td> structure type, return of the <code><a href="http://en.cppreference.com/w/c/numeric/math/div"><span class="kw646">ldiv</span></a></code> function <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/div" title="c/numeric/math/div"> <span class="t-lines"><span>lldiv_t</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> structure type, return of the <code>lldiv</code> function <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><inttypes.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="math/div" title="c/numeric/math/div"> <span class="t-lines"><span>imaxdiv_t</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> structure type, return of the <code>imaxdiv</code> function <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><math.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="math/float_t" title="c/numeric/math/float t"> <span class="t-lines"><span>float_t</span><span>double_t</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> most efficient floating-point type at least as wide as <code>float</code> or <code>double</code> <br> <span class="t-mark">(typedef)</span> </td> +</tr> </table> <h3 id="Macro_constants"> Macro constants</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><math.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="math/huge_val" title="c/numeric/math/HUGE VAL"> <span class="t-lines"><span>HUGE_VALF</span><span>HUGE_VAL</span><span>HUGE_VALL</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> indicates value too big to be representable (infinity) by <code>float</code>, <code>double</code> and <code>long double</code> respectively <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/infinity" title="c/numeric/math/INFINITY"> <span class="t-lines"><span>INFINITY</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> evaluates to positive infinity or the value guaranteed to overflow a <code>float</code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/nan" title="c/numeric/math/NAN"> <span class="t-lines"><span>NAN</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> evaluates to a quiet NaN of type <code>float</code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/fma" title="c/numeric/math/fma"> <span class="t-lines"><span>FP_FAST_FMAF</span><span>FP_FAST_FMA</span><span>FP_FAST_FMAL</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> indicates that the fma function generally executes about as fast as, or faster than, a multiply and an add of double operands <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/ilogb" title="c/numeric/math/ilogb"> <span class="t-lines"><span>FP_ILOGB0</span><span>FP_ILOGBNAN</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> evaluates to ilogb(x) if x is zero or NaN, respectively <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/math_errhandling" title="c/numeric/math/math errhandling"> <span class="t-lines"><span>math_errhandling</span><span>MATH_ERRNO</span><span>MATH_ERREXCEPT</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> defines the error handling mechanism used by the common mathematical functions <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Classification"> Classification </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="math/fp_categories" title="c/numeric/math/FP categories"> <span class="t-lines"><span>FP_NORMAL</span><span>FP_SUBNORMAL</span><span>FP_ZERO</span><span>FP_INFINITE</span><span>FP_NAN</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> indicates a floating-point category <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.8 Format conversion of integer types <inttypes.h> (p: 158-160) </li> +<li> 7.12 Mathematics <math.h> (p: 169-190) </li> +<li> 7.22 General utilities <stdlib.h> (p: 248-262) </li> +<li> 7.31.5 Format conversion of integer types <inttypes.h> (p: 332) </li> +<li> 7.31.12 General utilities <stdlib.h> (p: 333) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.8 Format conversion of integer types <inttypes.h> (p: 217-220) </li> +<li> 7.12 Mathematics <math.h> (p: 231-261) </li> +<li> 7.22 General utilities <stdlib.h> (p: 340-360) </li> +<li> 7.31.5 Format conversion of integer types <inttypes.h> (p: 455) </li> +<li> 7.31.12 General utilities <stdlib.h> (p: 456) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.8 Format conversion of integer types <inttypes.h> (p: 198-201) </li> +<li> 7.12 Mathematics <math.h> (p: 212-242) </li> +<li> 7.20 General utilities <stdlib.h> (p: 306-324) </li> +<li> 7.26.4 Format conversion of integer types <inttypes.h> (p: 401) </li> +<li> 7.26.10 General utilities <stdlib.h> (p: 402) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 4.5 MATHEMATICS <math.h> </li> +<li> 4.10 GENERAL UTILITIES <stdlib.h> </li> +<li> 4.13.4 Mathematics <math.h> </li> +<li> 7.13.7 General utilities <stdlib.h> </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/math" title="cpp/numeric/math">C++ documentation</a></span> for <span class=""><span>Common mathematical functions</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/math" class="_attribution-link">https://en.cppreference.com/w/c/numeric/math</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Frandom%2Frand.html b/devdocs/c/numeric%2Frandom%2Frand.html new file mode 100644 index 00000000..cd6aaf4c --- /dev/null +++ b/devdocs/c/numeric%2Frandom%2Frand.html @@ -0,0 +1,46 @@ + <h1 id="firstHeading" class="firstHeading">rand</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int rand();</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Returns a pseudo-random integer value between <code>0</code> and <code><a href="rand_max" title="c/numeric/random/RAND MAX">RAND_MAX</a></code> (<code>0</code> and <code>RAND_MAX</code> included).</p> +<p><code><a href="srand" title="c/numeric/random/srand">srand()</a></code> seeds the pseudo-random number generator used by <code>rand()</code>. If <code>rand()</code> is used before any calls to <code>srand()</code>, <code>rand()</code> behaves as if it was seeded with <code><a href="http://en.cppreference.com/w/c/numeric/random/srand"><span class="kw740">srand</span></a><span class="br0">(</span><span class="nu0">1</span><span class="br0">)</span></code>. Each time <code>rand()</code> is seeded with <code>srand()</code>, it must produce the same sequence of values.</p> +<p><code>rand()</code> is not guaranteed to be thread-safe.</p> +<h3 id="Parameters"> Parameters</h3> <p>(none)</p> +<h3 id="Return_value"> Return value</h3> <p>Pseudo-random integer value between <code>0</code> and <code><a href="rand_max" title="c/numeric/random/RAND MAX">RAND_MAX</a></code>, inclusive.</p> +<h3 id="Notes"> Notes</h3> <p>There are no guarantees as to the quality of the random sequence produced. In the past, some implementations of <code>rand()</code> have had serious shortcomings in the randomness, distribution and period of the sequence produced (in one well-known example, the low-order bit simply alternated between <code>1</code> and <code>0</code> between calls). <code>rand()</code> is not recommended for serious random-number generation needs, like cryptography.</p> +<p>POSIX requires that the period of the pseudo-random number generator used by <code>rand</code> be at least 2<sup class="t-su">32</sup>.</p> +<p>POSIX offered a thread-safe version of rand called <code>rand_r</code>, which is obsolete in favor of the <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/drand48.html"><code>drand48</code></a> family of functions.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> +#include <time.h> + +int main(void) +{ + srand(time(NULL)); // use current time as seed for random generator + int random_variable = rand(); + printf("Random value on [0,%d]: %d\n", RAND_MAX, random_variable); + + // roll a 6-sided die 20 times + for (int n=0; n != 20; ++n) { + int x = 7; + while(x > 6) + x = 1 + rand()/((RAND_MAX + 1u)/6); // Note: 1+rand()%6 is biased + printf("%d ", x); + } +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Random value on [0,2147483647]: 448749574 +3 1 3 1 4 2 2 1 3 6 4 4 3 1 6 2 3 2 6 1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22.2.1 The rand function (p: 252) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.2.1 The rand function (p: 346) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.2.1 The rand function (p: 312) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.2.1 The rand function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="srand" title="c/numeric/random/srand"> <span class="t-lines"><span>srand</span></span></a></div> </td> <td> seeds pseudo-random number generator <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="rand_max" title="c/numeric/random/RAND MAX"> <span class="t-lines"><span>RAND_MAX</span></span></a></div> </td> <td> maximum possible value generated by <code>rand()</code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/random/rand" title="cpp/numeric/random/rand">C++ documentation</a></span> for <code>rand</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/random/rand" class="_attribution-link">https://en.cppreference.com/w/c/numeric/random/rand</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Frandom%2Frand_max.html b/devdocs/c/numeric%2Frandom%2Frand_max.html new file mode 100644 index 00000000..3e146e2f --- /dev/null +++ b/devdocs/c/numeric%2Frandom%2Frand_max.html @@ -0,0 +1,34 @@ + <h1 id="firstHeading" class="firstHeading">RAND_MAX</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define RAND_MAX /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Expands to an integer constant expression equal to the maximum value returned by the function <code><a href="rand" title="c/numeric/random/rand">rand()</a></code>. This value is implementation dependent. It's guaranteed that this value is at least <code>32767</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <limits.h> +#include <stdio.h> +#include <stdlib.h> +#include <time.h> + +int main(void) +{ + srand(time(NULL)); // use current time as seed for random generator + printf("RAND_MAX: %i\n", RAND_MAX); + printf("INT_MAX: %i\n", INT_MAX); + printf("Random value on [0,1]: %f\n", (double)rand() / RAND_MAX); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">RAND_MAX: 2147483647 +INT_MAX: 2147483647 +Random value on [0,1]: 0.362509</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22/3 General utilities <stdlib.h> (p: 248) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22/3 General utilities <stdlib.h> (p: 340) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20/3 General utilities <stdlib.h> (p: 306) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10 GENERAL UTILITIES <stdlib.h> </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="rand" title="c/numeric/random/rand"> <span class="t-lines"><span>rand</span></span></a></div> </td> <td> generates a pseudo-random number <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="srand" title="c/numeric/random/srand"> <span class="t-lines"><span>srand</span></span></a></div> </td> <td> seeds pseudo-random number generator <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/random/RAND_MAX" title="cpp/numeric/random/RAND MAX">C++ documentation</a></span> for <code>RAND_MAX</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/random/RAND_MAX" class="_attribution-link">https://en.cppreference.com/w/c/numeric/random/RAND_MAX</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Frandom%2Fsrand.html b/devdocs/c/numeric%2Frandom%2Fsrand.html new file mode 100644 index 00000000..b51663b0 --- /dev/null +++ b/devdocs/c/numeric%2Frandom%2Fsrand.html @@ -0,0 +1,38 @@ + <h1 id="firstHeading" class="firstHeading">srand</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">void srand( unsigned seed );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Seeds the pseudo-random number generator used by <code><a href="rand" title="c/numeric/random/rand">rand()</a></code> with the value <code>seed</code>.</p> +<p>If <code>rand()</code> is used before any calls to <code>srand()</code>, <code>rand()</code> behaves as if it was seeded with <code>srand(1)</code>.</p> +<p>Each time <code>rand()</code> is seeded with the same <code>seed</code>, it must produce the same sequence of values.</p> +<p><code>srand()</code> is not guaranteed to be thread-safe.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> seed </td> <td> - </td> <td> the seed value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="Notes"> Notes</h3> <p>Generally speaking, the pseudo-random number generator should only be seeded once, before any calls to <code>rand()</code>, and the start of the program. It should not be repeatedly seeded, or reseeded every time you wish to generate a new batch of pseudo-random numbers.</p> +<p>Standard practice is to use the result of a call to <code><a href="http://en.cppreference.com/w/c/chrono/time"><span class="kw513">time</span></a><span class="br0">(</span><span class="nu0">0</span><span class="br0">)</span></code> as the seed. However, <code>time()</code> returns a <code><a href="../../chrono/time_t" title="c/chrono/time t">time_t</a></code> value, and <code>time_t</code> is not guaranteed to be an integral type. In practice, though, every major implementation defines <code>time_t</code> to be an integral type, and this is also what POSIX requires.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> +#include <time.h> + +int main(void) +{ + srand(time(NULL)); //use current time as seed for random generator + int random_variable = rand(); + printf("Random value on [0,%d]: %d\n", RAND_MAX, random_variable); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Random value on [0 2147483647]: 1373858591</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22.2.2 The srand function (p: 252-253) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.2.2 The srand function (p: 346-347) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.2.2 The srand function (p: 312-313) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.2.2 The srand function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="rand" title="c/numeric/random/rand"> <span class="t-lines"><span>rand</span></span></a></div> </td> <td> generates a pseudo-random number <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="rand_max" title="c/numeric/random/RAND MAX"> <span class="t-lines"><span>RAND_MAX</span></span></a></div> </td> <td> maximum possible value generated by <code><a href="http://en.cppreference.com/w/c/numeric/random/rand"><span class="kw740">rand</span></a><span class="br0">(</span><span class="br0">)</span></code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/random/srand" title="cpp/numeric/random/srand">C++ documentation</a></span> for <code>srand</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/random/srand" class="_attribution-link">https://en.cppreference.com/w/c/numeric/random/srand</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Frandom.html b/devdocs/c/numeric%2Frandom.html new file mode 100644 index 00000000..93b1fb6a --- /dev/null +++ b/devdocs/c/numeric%2Frandom.html @@ -0,0 +1,20 @@ + <h1 id="firstHeading" class="firstHeading">Pseudo-random number generation</h1> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdlib.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="random/rand" title="c/numeric/random/rand"> <span class="t-lines"><span>rand</span></span></a></div> </td> <td> generates a pseudo-random number <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="random/srand" title="c/numeric/random/srand"> <span class="t-lines"><span>srand</span></span></a></div> </td> <td> seeds pseudo-random number generator <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="random/rand_max" title="c/numeric/random/RAND MAX"> <span class="t-lines"><span>RAND_MAX</span></span></a></div> </td> <td> maximum possible value generated by <code><a href="http://en.cppreference.com/w/c/numeric/random/rand"><span class="kw741">rand</span></a><span class="br0">(</span><span class="br0">)</span></code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22.2 Pseudo-random sequence generation functions (p: 252-253) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.2 Pseudo-random sequence generation functions (p: 346-347) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.2 Pseudo-random sequence generation functions (p: 312-313) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.2 Pseudo-random sequence generation functions </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric/random" title="cpp/numeric/random">C++ documentation</a></span> for <span class=""><span>Pseudo-random number generation</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/random" class="_attribution-link">https://en.cppreference.com/w/c/numeric/random</a> + </p> +</div> diff --git a/devdocs/c/numeric%2Ftgmath.html b/devdocs/c/numeric%2Ftgmath.html new file mode 100644 index 00000000..2e53991e --- /dev/null +++ b/devdocs/c/numeric%2Ftgmath.html @@ -0,0 +1,138 @@ + <h1 id="firstHeading" class="firstHeading">Type-generic math</h1> <p>The header <code><tgmath.h></code> includes the headers <code><math.h></code> and <code><complex.h></code> and defines several type-generic macros that determine which real or, when applicable, complex function to call based on the types of the arguments.</p> +<p>For each macro, the parameters whose corresponding real type in the unsuffixed math.h function is <code>double</code> are known as <i>generic parameters</i> (for example, both parameters of <code><a href="math/pow" title="c/numeric/math/pow">pow</a></code> are generic parameters, but only the first parameter of <code><a href="math/scalbn" title="c/numeric/math/scalbn">scalbn</a></code> is a generic parameter).</p> +<p>When a <code><tgmath.h></code> macro is used the types of the arguments passed to the generic parameters determine which function is selected by the macro as described below. If the types of the arguments are not <a href="../language/type#Compatible_types" title="c/language/type">compatible</a> with the parameter types of the selected function, the behavior is undefined (e.g. if a complex argument is passed into a real-only <code><tgmath.h></code>'s macro: <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a> fc<span class="sy4">;</span> <a href="http://en.cppreference.com/w/c/numeric/math/ceil"><span class="kw686">ceil</span></a><span class="br0">(</span>fc<span class="br0">)</span><span class="sy4">;</span></code> or <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a> dc<span class="sy4">;</span> <span class="kw4">double</span> d<span class="sy4">;</span> <a href="http://en.cppreference.com/w/c/numeric/math/fmax"><span class="kw651">fmax</span></a><span class="br0">(</span>dc, d<span class="br0">)</span><span class="sy4">;</span></code> are examples of undefined behavior).</p> +<p>Note: type-generic macros were implemented in implementation-defined manner in C99, but C11 keyword <a href="../keyword/_generic" title="c/keyword/ Generic"><code>_Generic</code></a> makes it possible to implement these macros in portable manner.</p> +<h3 id="Complex.2Freal_type-generic_macros"> Complex/real type-generic macros</h3> <p>For all functions that have both real and complex counterparts, a type-generic macro <code>XXX</code> exists, which calls either of:</p> +<ul> +<li> real function: </li> +<ul> +<li> <code>float</code> variant <code>XXXf</code> </li> +<li> <code>double</code> variant <code>XXX</code> </li> +<li> <code>long double</code> variant <code>XXXl</code> </li> +</ul> +<li> complex function: </li> +<ul> +<li> <code>float</code> variant <code>cXXXf</code> </li> +<li> <code>double</code> variant <code>cXXX</code> </li> +<li> <code>long double</code> variant <code>cXXXl</code> </li> +</ul> +</ul> <p>An exception to the above rule is the <code>fabs</code> macro (see the table below).</p> +<p>The function to call is determined as follows:</p> +<ul> +<li> If any of the arguments for the generic parameters is imaginary, the behavior is specified on each function reference page individually (in particular, <code>sin</code>, <code>cos</code>, <code>tag</code>, <code>cosh</code>, <code>sinh</code>, <code>tanh</code>, <code>asin</code>, <code>atan</code>, <code>asinh</code>, and <code>atanh</code> call <i>real</i> functions, the return types of <code>sin</code>, <code>tan</code>, <code>sinh</code>, <code>tanh</code>, <code>asin</code>, <code>atan</code>, <code>asinh</code>, and <code>atanh</code> are imaginary, and the return types of <code>cos</code> and <code>cosh</code> are real). </li> +<li> If any of the arguments for the generic parameters is complex, then the complex function is called, otherwise the real function is called. </li> +<li> If any of the arguments for the generic parameters is <code>long double</code>, then the <code>long double</code> variant is called. Otherwise, if any of the parameters is <code>double</code> or integer, then the <code>double</code> variant is called. Otherwise, <code>float</code> variant is called. </li> +</ul> <p>The type-generic macros are as follows:</p> +<table class="wikitable"> <tr> <th> Type-generic macro </th> <th colspan="3"> Real function <br> variants </th> <th colspan="3"> Complex function <br> variants </th> +</tr> <tr> <th> </th> <th> <div><code>float</code></div> </th> <th> <div><code>double</code></div> </th> <th> <div><code>long double</code></div> </th> <th> <div><code>float</code></div> </th> <th> <div><code>double</code></div> </th> <th> <div><code>long double</code></div> </th> +</tr> <tr> <th> fabs </th> <td> <a href="math/fabs" title="c/numeric/math/fabs"><code>fabsf</code></a> </td> <td> <a href="math/fabs" title="c/numeric/math/fabs"><code>fabs</code></a> </td> <td> <a href="math/fabs" title="c/numeric/math/fabs"><code>fabsl</code></a> </td> <td> <a href="complex/cabs" title="c/numeric/complex/cabs"><code>cabsf</code></a> </td> <td> <a href="complex/cabs" title="c/numeric/complex/cabs"><code>cabs</code></a> </td> <td> <a href="complex/cabs" title="c/numeric/complex/cabs"><code>cabsl</code></a> </td> +</tr> <tr> <th> exp </th> <td> <a href="math/exp" title="c/numeric/math/exp"><code>expf</code></a> </td> <td> <a href="math/exp" title="c/numeric/math/exp"><code>exp</code></a> </td> <td> <a href="math/exp" title="c/numeric/math/exp"><code>expl</code></a> </td> <td> <a href="complex/cexp" title="c/numeric/complex/cexp"><code>cexpf</code></a> </td> <td> <a href="complex/cexp" title="c/numeric/complex/cexp"><code>cexp</code></a> </td> <td> <a href="complex/cexp" title="c/numeric/complex/cexp"><code>cexpl</code></a> </td> +</tr> <tr> <th> log </th> <td> <a href="math/log" title="c/numeric/math/log"><code>logf</code></a> </td> <td> <a href="math/log" title="c/numeric/math/log"><code>log</code></a> </td> <td> <a href="math/log" title="c/numeric/math/log"><code>logl</code></a> </td> <td> <a href="complex/clog" title="c/numeric/complex/clog"><code>clogf</code></a> </td> <td> <a href="complex/clog" title="c/numeric/complex/clog"><code>clog</code></a> </td> <td> <a href="complex/clog" title="c/numeric/complex/clog"><code>clogl</code></a> </td> +</tr> <tr> <th> pow </th> <td> <a href="math/pow" title="c/numeric/math/pow"><code>powf</code></a> </td> <td> <a href="math/pow" title="c/numeric/math/pow"><code>pow</code></a> </td> <td> <a href="math/pow" title="c/numeric/math/pow"><code>powl</code></a> </td> <td> <a href="complex/cpow" title="c/numeric/complex/cpow"><code>cpowf</code></a> </td> <td> <a href="complex/cpow" title="c/numeric/complex/cpow"><code>cpow</code></a> </td> <td> <a href="complex/cpow" title="c/numeric/complex/cpow"><code>cpowl</code></a> </td> +</tr> <tr> <th> sqrt </th> <td> <a href="math/sqrt" title="c/numeric/math/sqrt"><code>sqrtf</code></a> </td> <td> <a href="math/sqrt" title="c/numeric/math/sqrt"><code>sqrt</code></a> </td> <td> <a href="math/sqrt" title="c/numeric/math/sqrt"><code>sqrtl</code></a> </td> <td> <a href="complex/csqrt" title="c/numeric/complex/csqrt"><code>csqrtf</code></a> </td> <td> <a href="complex/csqrt" title="c/numeric/complex/csqrt"><code>csqrt</code></a> </td> <td> <a href="complex/csqrt" title="c/numeric/complex/csqrt"><code>csqrtl</code></a> </td> +</tr> <tr> <th> sin </th> <td> <a href="math/sin" title="c/numeric/math/sin"><code>sinf</code></a> </td> <td> <a href="math/sin" title="c/numeric/math/sin"><code>sin</code></a> </td> <td> <a href="math/sin" title="c/numeric/math/sin"><code>sinl</code></a> </td> <td> <a href="complex/csin" title="c/numeric/complex/csin"><code>csinf</code></a> </td> <td> <a href="complex/csin" title="c/numeric/complex/csin"><code>csin</code></a> </td> <td> <a href="complex/csin" title="c/numeric/complex/csin"><code>csinl</code></a> </td> +</tr> <tr> <th> cos </th> <td> <a href="math/cos" title="c/numeric/math/cos"><code>cosf</code></a> </td> <td> <a href="math/cos" title="c/numeric/math/cos"><code>cos</code></a> </td> <td> <a href="math/cos" title="c/numeric/math/cos"><code>cosl</code></a> </td> <td> <a href="complex/ccos" title="c/numeric/complex/ccos"><code>ccosf</code></a> </td> <td> <a href="complex/ccos" title="c/numeric/complex/ccos"><code>ccos</code></a> </td> <td> <a href="complex/ccos" title="c/numeric/complex/ccos"><code>ccosl</code></a> </td> +</tr> <tr> <th> tan </th> <td> <a href="math/tan" title="c/numeric/math/tan"><code>tanf</code></a> </td> <td> <a href="math/tan" title="c/numeric/math/tan"><code>tan</code></a> </td> <td> <a href="math/tan" title="c/numeric/math/tan"><code>tanl</code></a> </td> <td> <a href="complex/ctan" title="c/numeric/complex/ctan"><code>ctanf</code></a> </td> <td> <a href="complex/ctan" title="c/numeric/complex/ctan"><code>ctan</code></a> </td> <td> <a href="complex/ctan" title="c/numeric/complex/ctan"><code>ctanl</code></a> </td> +</tr> <tr> <th> asin </th> <td> <a href="math/asin" title="c/numeric/math/asin"><code>asinf</code></a> </td> <td> <a href="math/asin" title="c/numeric/math/asin"><code>asin</code></a> </td> <td> <a href="math/asin" title="c/numeric/math/asin"><code>asinl</code></a> </td> <td> <a href="complex/casin" title="c/numeric/complex/casin"><code>casinf</code></a> </td> <td> <a href="complex/casin" title="c/numeric/complex/casin"><code>casin</code></a> </td> <td> <a href="complex/casin" title="c/numeric/complex/casin"><code>casinl</code></a> </td> +</tr> <tr> <th> acos </th> <td> <a href="math/acos" title="c/numeric/math/acos"><code>acosf</code></a> </td> <td> <a href="math/acos" title="c/numeric/math/acos"><code>acos</code></a> </td> <td> <a href="math/acos" title="c/numeric/math/acos"><code>acosl</code></a> </td> <td> <a href="complex/cacos" title="c/numeric/complex/cacos"><code>cacosf</code></a> </td> <td> <a href="complex/cacos" title="c/numeric/complex/cacos"><code>cacos</code></a> </td> <td> <a href="complex/cacos" title="c/numeric/complex/cacos"><code>cacosl</code></a> </td> +</tr> <tr> <th> atan </th> <td> <a href="math/atan" title="c/numeric/math/atan"><code>atanf</code></a> </td> <td> <a href="math/atan" title="c/numeric/math/atan"><code>atan</code></a> </td> <td> <a href="math/atan" title="c/numeric/math/atan"><code>atanl</code></a> </td> <td> <a href="complex/catan" title="c/numeric/complex/catan"><code>catanf</code></a> </td> <td> <a href="complex/catan" title="c/numeric/complex/catan"><code>catan</code></a> </td> <td> <a href="complex/catan" title="c/numeric/complex/catan"><code>catanl</code></a> </td> +</tr> <tr> <th> sinh </th> <td> <a href="math/sinh" title="c/numeric/math/sinh"><code>sinhf</code></a> </td> <td> <a href="math/sinh" title="c/numeric/math/sinh"><code>sinh</code></a> </td> <td> <a href="math/sinh" title="c/numeric/math/sinh"><code>sinhl</code></a> </td> <td> <a href="complex/csinh" title="c/numeric/complex/csinh"><code>csinhf</code></a> </td> <td> <a href="complex/csinh" title="c/numeric/complex/csinh"><code>csinh</code></a> </td> <td> <a href="complex/csinh" title="c/numeric/complex/csinh"><code>csinhl</code></a> </td> +</tr> <tr> <th> cosh </th> <td> <a href="math/cosh" title="c/numeric/math/cosh"><code>coshf</code></a> </td> <td> <a href="math/cosh" title="c/numeric/math/cosh"><code>cosh</code></a> </td> <td> <a href="math/cosh" title="c/numeric/math/cosh"><code>coshl</code></a> </td> <td> <a href="complex/ccosh" title="c/numeric/complex/ccosh"><code>ccoshf</code></a> </td> <td> <a href="complex/ccosh" title="c/numeric/complex/ccosh"><code>ccosh</code></a> </td> <td> <a href="complex/ccosh" title="c/numeric/complex/ccosh"><code>ccoshl</code></a> </td> +</tr> <tr> <th> tanh </th> <td> <a href="math/tanh" title="c/numeric/math/tanh"><code>tanhf</code></a> </td> <td> <a href="math/tanh" title="c/numeric/math/tanh"><code>tanh</code></a> </td> <td> <a href="math/tanh" title="c/numeric/math/tanh"><code>tanhl</code></a> </td> <td> <a href="complex/ctanh" title="c/numeric/complex/ctanh"><code>ctanhf</code></a> </td> <td> <a href="complex/ctanh" title="c/numeric/complex/ctanh"><code>ctanh</code></a> </td> <td> <a href="complex/ctanh" title="c/numeric/complex/ctanh"><code>ctanhl</code></a> </td> +</tr> <tr> <th> asinh </th> <td> <a href="math/asinh" title="c/numeric/math/asinh"><code>asinhf</code></a> </td> <td> <a href="math/asinh" title="c/numeric/math/asinh"><code>asinh</code></a> </td> <td> <a href="math/asinh" title="c/numeric/math/asinh"><code>asinhl</code></a> </td> <td> <a href="complex/casinh" title="c/numeric/complex/casinh"><code>casinhf</code></a> </td> <td> <a href="complex/casinh" title="c/numeric/complex/casinh"><code>casinh</code></a> </td> <td> <a href="complex/casinh" title="c/numeric/complex/casinh"><code>casinhl</code></a> </td> +</tr> <tr> <th> acosh </th> <td> <a href="math/acosh" title="c/numeric/math/acosh"><code>acoshf</code></a> </td> <td> <a href="math/acosh" title="c/numeric/math/acosh"><code>acosh</code></a> </td> <td> <a href="math/acosh" title="c/numeric/math/acosh"><code>acoshl</code></a> </td> <td> <a href="complex/cacosh" title="c/numeric/complex/cacosh"><code>cacoshf</code></a> </td> <td> <a href="complex/cacosh" title="c/numeric/complex/cacosh"><code>cacosh</code></a> </td> <td> <a href="complex/cacosh" title="c/numeric/complex/cacosh"><code>cacoshl</code></a> </td> +</tr> <tr> <th> atanh </th> <td> <a href="math/atanh" title="c/numeric/math/atanh"><code>atanhf</code></a> </td> <td> <a href="math/atanh" title="c/numeric/math/atanh"><code>atanh</code></a> </td> <td> <a href="math/atanh" title="c/numeric/math/atanh"><code>atanhl</code></a> </td> <td> <a href="complex/catanh" title="c/numeric/complex/catanh"><code>catanhf</code></a> </td> <td> <a href="complex/catanh" title="c/numeric/complex/catanh"><code>catanh</code></a> </td> <td> <a href="complex/catanh" title="c/numeric/complex/catanh"><code>catanhl</code></a> </td> +</tr> +</table> <h3 id="Real-only_functions"> Real-only functions</h3> <p>For all functions that do not have complex counterparts, with the exception of <code>modf</code>, a type-generic macro <code>XXX</code> exists, which calls either of the variants of a real function:</p> +<ul> +<li> <code>float</code> variant <code>XXXf</code> </li> +<li> <code>double</code> variant <code>XXX</code> </li> +<li> <code>long double</code> variant <code>XXXl</code> </li> +</ul> <p>The function to call is determined as follows:</p> +<ul><li> If any of the arguments for the generic parameters is <code>long double</code>, then the <code>long double</code> variant is called. Otherwise, if any of the arguments for the generic parameters is <code>double</code>, then the <code>double</code> variant is called. Otherwise, <code>float</code> variant is called. </li></ul> <table class="wikitable"> <tr> <th> Type-generic macro </th> <th colspan="3"> Real function <br> variants </th> +</tr> <tr> <th> </th> <th> <div><code>float</code></div> </th> <th> <div><code>double</code></div> </th> <th> <div><code>long double</code></div> </th> +</tr> <tr> <th> atan2 </th> <td> <a href="math/atan2" title="c/numeric/math/atan2"><code>atan2f</code></a> </td> <td> <a href="math/atan2" title="c/numeric/math/atan2"><code>atan2</code></a> </td> <td> <a href="math/atan2" title="c/numeric/math/atan2"><code>atan2l</code></a> </td> +</tr> <tr> <th> cbrt </th> <td> <a href="math/cbrt" title="c/numeric/math/cbrt"><code>cbrtf</code></a> </td> <td> <a href="math/cbrt" title="c/numeric/math/cbrt"><code>cbrt</code></a> </td> <td> <a href="math/cbrt" title="c/numeric/math/cbrt"><code>cbrtl</code></a> </td> +</tr> <tr> <th> ceil </th> <td> <a href="math/ceil" title="c/numeric/math/ceil"><code>ceilf</code></a> </td> <td> <a href="math/ceil" title="c/numeric/math/ceil"><code>ceil</code></a> </td> <td> <a href="math/ceil" title="c/numeric/math/ceil"><code>ceill</code></a> </td> +</tr> <tr> <th> copysign </th> <td> <a href="math/copysign" title="c/numeric/math/copysign"><code>copysignf</code></a> </td> <td> <a href="math/copysign" title="c/numeric/math/copysign"><code>copysign</code></a> </td> <td> <a href="math/copysign" title="c/numeric/math/copysign"><code>copysignl</code></a> </td> +</tr> <tr> <th> erf </th> <td> <a href="math/erf" title="c/numeric/math/erf"><code>erff</code></a> </td> <td> <a href="math/erf" title="c/numeric/math/erf"><code>erf</code></a> </td> <td> <a href="math/erf" title="c/numeric/math/erf"><code>erfl</code></a> </td> +</tr> <tr> <th> erfc </th> <td> <a href="math/erfc" title="c/numeric/math/erfc"><code>erfcf</code></a> </td> <td> <a href="math/erfc" title="c/numeric/math/erfc"><code>erfc</code></a> </td> <td> <a href="math/erfc" title="c/numeric/math/erfc"><code>erfcl</code></a> </td> +</tr> <tr> <th> exp2 </th> <td> <a href="math/exp2" title="c/numeric/math/exp2"><code>exp2f</code></a> </td> <td> <a href="math/exp2" title="c/numeric/math/exp2"><code>exp2</code></a> </td> <td> <a href="math/exp2" title="c/numeric/math/exp2"><code>exp2l</code></a> </td> +</tr> <tr> <th> expm1 </th> <td> <a href="math/expm1" title="c/numeric/math/expm1"><code>expm1f</code></a> </td> <td> <a href="math/expm1" title="c/numeric/math/expm1"><code>expm1</code></a> </td> <td> <a href="math/expm1" title="c/numeric/math/expm1"><code>expm1l</code></a> </td> +</tr> <tr> <th> fdim </th> <td> <a href="math/fdim" title="c/numeric/math/fdim"><code>fdimf</code></a> </td> <td> <a href="math/fdim" title="c/numeric/math/fdim"><code>fdim</code></a> </td> <td> <a href="math/fdim" title="c/numeric/math/fdim"><code>fdiml</code></a> </td> +</tr> <tr> <th> floor </th> <td> <a href="math/floor" title="c/numeric/math/floor"><code>floorf</code></a> </td> <td> <a href="math/floor" title="c/numeric/math/floor"><code>floor</code></a> </td> <td> <a href="math/floor" title="c/numeric/math/floor"><code>floorl</code></a> </td> +</tr> <tr> <th> fma </th> <td> <a href="math/fma" title="c/numeric/math/fma"><code>fmaf</code></a> </td> <td> <a href="math/fma" title="c/numeric/math/fma"><code>fma</code></a> </td> <td> <a href="math/fma" title="c/numeric/math/fma"><code>fmal</code></a> </td> +</tr> <tr> <th> fmax </th> <td> <a href="math/fmax" title="c/numeric/math/fmax"><code>fmaxf</code></a> </td> <td> <a href="math/fmax" title="c/numeric/math/fmax"><code>fmax</code></a> </td> <td> <a href="math/fmax" title="c/numeric/math/fmax"><code>fmaxl</code></a> </td> +</tr> <tr> <th> fmin </th> <td> <a href="math/fmin" title="c/numeric/math/fmin"><code>fminf</code></a> </td> <td> <a href="math/fmin" title="c/numeric/math/fmin"><code>fmin</code></a> </td> <td> <a href="math/fmin" title="c/numeric/math/fmin"><code>fminl</code></a> </td> +</tr> <tr> <th> fmod </th> <td> <a href="math/fmod" title="c/numeric/math/fmod"><code>fmodf</code></a> </td> <td> <a href="math/fmod" title="c/numeric/math/fmod"><code>fmod</code></a> </td> <td> <a href="math/fmod" title="c/numeric/math/fmod"><code>fmodl</code></a> </td> +</tr> <tr> <th> frexp </th> <td> <a href="math/frexp" title="c/numeric/math/frexp"><code>frexpf</code></a> </td> <td> <a href="math/frexp" title="c/numeric/math/frexp"><code>frexp</code></a> </td> <td> <a href="math/frexp" title="c/numeric/math/frexp"><code>frexpl</code></a> </td> +</tr> <tr> <th> hypot </th> <td> <a href="math/hypot" title="c/numeric/math/hypot"><code>hypotf</code></a> </td> <td> <a href="math/hypot" title="c/numeric/math/hypot"><code>hypot</code></a> </td> <td> <a href="math/hypot" title="c/numeric/math/hypot"><code>hypotl</code></a> </td> +</tr> <tr> <th> ilogb </th> <td> <a href="math/ilogb" title="c/numeric/math/ilogb"><code>ilogbf</code></a> </td> <td> <a href="math/ilogb" title="c/numeric/math/ilogb"><code>ilogb</code></a> </td> <td> <a href="math/ilogb" title="c/numeric/math/ilogb"><code>ilogbl</code></a> </td> +</tr> <tr> <th> ldexp </th> <td> <a href="math/ldexp" title="c/numeric/math/ldexp"><code>ldexpf</code></a> </td> <td> <a href="math/ldexp" title="c/numeric/math/ldexp"><code>ldexp</code></a> </td> <td> <a href="math/ldexp" title="c/numeric/math/ldexp"><code>ldexpl</code></a> </td> +</tr> <tr> <th> lgamma </th> <td> <a href="math/lgamma" title="c/numeric/math/lgamma"><code>lgammaf</code></a> </td> <td> <a href="math/lgamma" title="c/numeric/math/lgamma"><code>lgamma</code></a> </td> <td> <a href="math/lgamma" title="c/numeric/math/lgamma"><code>lgammal</code></a> </td> +</tr> <tr> <th> llrint </th> <td> <a href="math/rint" title="c/numeric/math/rint"><code>llrintf</code></a> </td> <td> <a href="math/rint" title="c/numeric/math/rint"><code>llrint</code></a> </td> <td> <a href="math/rint" title="c/numeric/math/rint"><code>llrintl</code></a> </td> +</tr> <tr> <th> llround </th> <td> <a href="math/round" title="c/numeric/math/round"><code>llroundf</code></a> </td> <td> <a href="math/round" title="c/numeric/math/round"><code>llround</code></a> </td> <td> <a href="math/round" title="c/numeric/math/round"><code>llroundl</code></a> </td> +</tr> <tr> <th> log10 </th> <td> <a href="math/log10" title="c/numeric/math/log10"><code>log10f</code></a> </td> <td> <a href="math/log10" title="c/numeric/math/log10"><code>log10</code></a> </td> <td> <a href="math/log10" title="c/numeric/math/log10"><code>log10l</code></a> </td> +</tr> <tr> <th> log1p </th> <td> <a href="math/log1p" title="c/numeric/math/log1p"><code>log1pf</code></a> </td> <td> <a href="math/log1p" title="c/numeric/math/log1p"><code>log1p</code></a> </td> <td> <a href="math/log1p" title="c/numeric/math/log1p"><code>log1pl</code></a> </td> +</tr> <tr> <th> log2 </th> <td> <a href="math/log2" title="c/numeric/math/log2"><code>log2f</code></a> </td> <td> <a href="math/log2" title="c/numeric/math/log2"><code>log2</code></a> </td> <td> <a href="math/log2" title="c/numeric/math/log2"><code>log2l</code></a> </td> +</tr> <tr> <th> logb </th> <td> <a href="math/logb" title="c/numeric/math/logb"><code>logbf</code></a> </td> <td> <a href="math/logb" title="c/numeric/math/logb"><code>logb</code></a> </td> <td> <a href="math/logb" title="c/numeric/math/logb"><code>logbl</code></a> </td> +</tr> <tr> <th> lrint </th> <td> <a href="math/rint" title="c/numeric/math/rint"><code>lrintf</code></a> </td> <td> <a href="math/rint" title="c/numeric/math/rint"><code>lrint</code></a> </td> <td> <a href="math/rint" title="c/numeric/math/rint"><code>lrintl</code></a> </td> +</tr> <tr> <th> lround </th> <td> <a href="math/round" title="c/numeric/math/round"><code>lroundf</code></a> </td> <td> <a href="math/round" title="c/numeric/math/round"><code>lround</code></a> </td> <td> <a href="math/round" title="c/numeric/math/round"><code>lroundl</code></a> </td> +</tr> <tr> <th> nearbyint </th> <td> <a href="math/nearbyint" title="c/numeric/math/nearbyint"><code>nearbyintf</code></a> </td> <td> <a href="math/nearbyint" title="c/numeric/math/nearbyint"><code>nearbyint</code></a> </td> <td> <a href="math/nearbyint" title="c/numeric/math/nearbyint"><code>nearbyintl</code></a> </td> +</tr> <tr> <th> nextafter </th> <td> <a href="math/nextafter" title="c/numeric/math/nextafter"><code>nextafterf</code></a> </td> <td> <a href="math/nextafter" title="c/numeric/math/nextafter"><code>nextafter</code></a> </td> <td> <a href="math/nextafter" title="c/numeric/math/nextafter"><code>nextafterl</code></a> </td> +</tr> <tr> <th> nexttoward </th> <td> <a href="math/nextafter" title="c/numeric/math/nextafter"><code>nexttowardf</code></a> </td> <td> <a href="math/nextafter" title="c/numeric/math/nextafter"><code>nexttoward</code></a> </td> <td> <a href="math/nextafter" title="c/numeric/math/nextafter"><code>nexttowardl</code></a> </td> +</tr> <tr> <th> remainder </th> <td> <a href="math/remainder" title="c/numeric/math/remainder"><code>remainderf</code></a> </td> <td> <a href="math/remainder" title="c/numeric/math/remainder"><code>remainder</code></a> </td> <td> <a href="math/remainder" title="c/numeric/math/remainder"><code>remainderl</code></a> </td> +</tr> <tr> <th> remquo </th> <td> <a href="math/remquo" title="c/numeric/math/remquo"><code>remquof</code></a> </td> <td> <a href="math/remquo" title="c/numeric/math/remquo"><code>remquo</code></a> </td> <td> <a href="math/remquo" title="c/numeric/math/remquo"><code>remquol</code></a> </td> +</tr> <tr> <th> rint </th> <td> <a href="math/rint" title="c/numeric/math/rint"><code>rintf</code></a> </td> <td> <a href="math/rint" title="c/numeric/math/rint"><code>rint</code></a> </td> <td> <a href="math/rint" title="c/numeric/math/rint"><code>rintl</code></a> </td> +</tr> <tr> <th> round </th> <td> <a href="math/round" title="c/numeric/math/round"><code>roundf</code></a> </td> <td> <a href="math/round" title="c/numeric/math/round"><code>round</code></a> </td> <td> <a href="math/round" title="c/numeric/math/round"><code>roundl</code></a> </td> +</tr> <tr> <th> scalbln </th> <td> <a href="math/scalbn" title="c/numeric/math/scalbn"><code>scalblnf</code></a> </td> <td> <a href="math/scalbn" title="c/numeric/math/scalbn"><code>scalbln</code></a> </td> <td> <a href="math/scalbn" title="c/numeric/math/scalbn"><code>scalblnl</code></a> </td> +</tr> <tr> <th> scalbn </th> <td> <a href="math/scalbn" title="c/numeric/math/scalbn"><code>scalbnf</code></a> </td> <td> <a href="math/scalbn" title="c/numeric/math/scalbn"><code>scalbn</code></a> </td> <td> <a href="math/scalbn" title="c/numeric/math/scalbn"><code>scalbnl</code></a> </td> +</tr> <tr> <th> tgamma </th> <td> <a href="math/tgamma" title="c/numeric/math/tgamma"><code>tgammaf</code></a> </td> <td> <a href="math/tgamma" title="c/numeric/math/tgamma"><code>tgamma</code></a> </td> <td> <a href="math/tgamma" title="c/numeric/math/tgamma"><code>tgammal</code></a> </td> +</tr> <tr> <th> trunc </th> <td> <a href="math/trunc" title="c/numeric/math/trunc"><code>truncf</code></a> </td> <td> <a href="math/trunc" title="c/numeric/math/trunc"><code>trunc</code></a> </td> <td> <a href="math/trunc" title="c/numeric/math/trunc"><code>truncl</code></a> </td> +</tr> +</table> <h3 id="Complex-only_functions"> Complex-only functions</h3> <p>For all complex number functions that do not have real counterparts, a type-generic macro <code>cXXX</code> exists, which calls either of the variants of a complex function:</p> +<ul> +<li> <code><span class="kw4">float</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code> variant <code>cXXXf</code> </li> +<li> <code><span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code> variant <code>cXXX</code> </li> +<li> <code><span class="kw4">long</span> <span class="kw4">double</span> <a href="http://en.cppreference.com/w/c/numeric/complex/complex"><span class="kw743">complex</span></a></code> variant <code>cXXXl</code> </li> +</ul> <p>The function to call is determined as follows:</p> +<ul><li> If any of the arguments for the generic parameters is real, complex, or imaginary, then the appropriate complex function is called. </li></ul> <table class="wikitable"> <tr> <th> Type-generic macro </th> <th colspan="3"> Complex function <br> variants </th> +</tr> <tr> <th> </th> <th> <div><code>float</code></div> </th> <th> <div><code>double</code></div> </th> <th> <div><code>long double</code></div> </th> +</tr> <tr> <th> carg </th> <td> <a href="complex/carg" title="c/numeric/complex/carg"><code>cargf</code></a> </td> <td> <a href="complex/carg" title="c/numeric/complex/carg"><code>carg</code></a> </td> <td> <a href="complex/carg" title="c/numeric/complex/carg"><code>cargl</code></a> </td> +</tr> <tr> <th> conj </th> <td> <a href="complex/conj" title="c/numeric/complex/conj"><code>conjf</code></a> </td> <td> <a href="complex/conj" title="c/numeric/complex/conj"><code>conj</code></a> </td> <td> <a href="complex/conj" title="c/numeric/complex/conj"><code>conjl</code></a> </td> +</tr> <tr> <th> creal </th> <td> <a href="complex/creal" title="c/numeric/complex/creal"><code>crealf</code></a> </td> <td> <a href="complex/creal" title="c/numeric/complex/creal"><code>creal</code></a> </td> <td> <a href="complex/creal" title="c/numeric/complex/creal"><code>creall</code></a> </td> +</tr> <tr> <th> cimag </th> <td> <a href="complex/cimag" title="c/numeric/complex/cimag"><code>cimagf</code></a> </td> <td> <a href="complex/cimag" title="c/numeric/complex/cimag"><code>cimag</code></a> </td> <td> <a href="complex/cimag" title="c/numeric/complex/cimag"><code>cimagl</code></a> </td> +</tr> <tr> <th> cproj </th> <td> <a href="complex/cproj" title="c/numeric/complex/cproj"><code>cprojf</code></a> </td> <td> <a href="complex/cproj" title="c/numeric/complex/cproj"><code>cproj</code></a> </td> <td> <a href="complex/cproj" title="c/numeric/complex/cproj"><code>cprojl</code></a> </td> +</tr> +</table> <h3 id="Example"> Example </h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <tgmath.h> + +int main(void) +{ + int i = 2; + printf("sqrt(2) = %f\n", sqrt(i)); // argument type is int, calls sqrt + + float f = 0.5; + printf("sin(0.5f) = %f\n", sin(f)); // argument type is float, calls sinf + + float complex dc = 1 + 0.5*I; + float complex z = sqrt(dc); // argument type is float complex, calls csqrtf + printf("sqrt(1 + 0.5i) = %f+%fi\n", + creal(z), // argument type is float complex, calls crealf + cimag(z)); // argument type is float complex, calls cimagf +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">sqrt(2) = 1.414214 +sin(0.5f) = 0.479426 +sqrt(1 + 0.5i) = 1.029086+0.242934i</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.25 Type-generic math <tgmath.h> (p: 272-273) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.25 Type-generic math <tgmath.h> (p: 373-375) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.22 Type-generic math <tgmath.h> (p: 335-337) </li></ul> +</ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric/tgmath" class="_attribution-link">https://en.cppreference.com/w/c/numeric/tgmath</a> + </p> +</div> diff --git a/devdocs/c/numeric.html b/devdocs/c/numeric.html new file mode 100644 index 00000000..82bd12e9 --- /dev/null +++ b/devdocs/c/numeric.html @@ -0,0 +1,31 @@ + <h1 id="firstHeading" class="firstHeading">Numerics</h1> <p>The C numerics library includes common mathematical functions and types, as well as support for random number generation.</p> +<h3 id="Common_mathematical_functions"> <a href="numeric/math" title="c/numeric/math"> Common mathematical functions</a> +</h3> <p>The header <code>math.h</code> provides <a href="numeric/math" title="c/numeric/math">standard C library mathematical functions</a> such as <code><a href="numeric/math/fabs" title="c/numeric/math/fabs">fabs</a></code>, <code><a href="numeric/math/sqrt" title="c/numeric/math/sqrt">sqrt</a></code>, and <code><a href="numeric/math/sin" title="c/numeric/math/sin">sin</a></code>.</p> +<h3 id="Floating-point_environment"> <a href="numeric/fenv" title="c/numeric/fenv"> Floating-point environment</a> +</h3> <p>The header <code>fenv.h</code> defines <a href="numeric/fenv" title="c/numeric/fenv">flags and functions related to exceptional floating-point state</a>, such as overflow and division by zero.</p> +<h3 id="Pseudo-random_number_generation"> <a href="numeric/random" title="c/numeric/random"> Pseudo-random number generation</a> +</h3> <p>The header <code>stdlib.h</code> also includes C-style random number generation via <code><a href="numeric/random/srand" title="c/numeric/random/srand">srand</a></code> and <code><a href="numeric/random/rand" title="c/numeric/random/rand">rand</a></code>.</p> +<h3 id="Complex_number_arithmetic"> <a href="numeric/complex" title="c/numeric/complex"> Complex number arithmetic</a> +</h3> <p>The header <code>complex.h</code> provides types and functions about <a href="numeric/complex" title="c/numeric/complex">complex numbers</a>.</p> +<h3 id="Type-generic_math"> <a href="numeric/tgmath" title="c/numeric/tgmath"> Type-generic math</a> +</h3> <p>The header <code>tgmath.h</code> provides some macros for a function which names XXX:</p> +<ul> +<li> real function: </li> +<ul> +<li> <code>float</code> variant <code>XXXf</code> </li> +<li> <code>double</code> variant <code>XXX</code> </li> +<li> <code>long double</code> variant <code>XXXl</code> </li> +</ul> +<li> complex function: </li> +<ul> +<li> <code>float</code> variant <code>cXXXf</code> </li> +<li> <code>double</code> variant <code>cXXX</code> </li> +<li> <code>long double</code> variant <code>cXXXl</code> </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/numeric" title="cpp/numeric">C++ documentation</a></span> for <span class=""><span>Numerics library</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/numeric" class="_attribution-link">https://en.cppreference.com/w/c/numeric</a> + </p> +</div> diff --git a/devdocs/c/preprocessor%2Fconditional.html b/devdocs/c/preprocessor%2Fconditional.html new file mode 100644 index 00000000..2b4496f2 --- /dev/null +++ b/devdocs/c/preprocessor%2Fconditional.html @@ -0,0 +1,89 @@ + <h1 id="firstHeading" class="firstHeading">Conditional inclusion</h1> <p>The preprocessor supports conditional compilation of parts of source file. This behavior is controlled by <code>#if</code>, <code>#else</code>, <code>#elif</code>, <code>#ifdef</code>, <code>#ifndef</code><span class="t-rev-inl t-since-c23"><span>, <code>#elifdef</code>, <code>#elifndef</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, and <code>#endif</code> directives.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>#if</code> <span class="t-spar">expression</span> </td> <td class="t-sdsc-nopad"> </td> <td> </td> +</tr> <tr class="t-sdsc"> <td> <code>#ifdef</code> <span class="t-spar">identifier</span> </td> <td class="t-sdsc-nopad"> </td> <td> </td> +</tr> <tr class="t-sdsc"> <td> <code>#ifndef</code> <span class="t-spar">identifier</span> </td> <td class="t-sdsc-nopad"> </td> <td> </td> +</tr> <tr class="t-sdsc"> <td> <code>#elif</code> <span class="t-spar">expression</span> </td> <td class="t-sdsc-nopad"> </td> <td> </td> +</tr> <tr class="t-sdsc"> <td> <code>#elifdef</code> <span class="t-spar">identifier</span> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>#elifndef</code> <span class="t-spar">identifier</span> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>#else</code> </td> <td class="t-sdsc-nopad"> </td> <td> </td> +</tr> <tr class="t-sdsc"> <td> <code>#endif</code> </td> <td class="t-sdsc-nopad"> </td> <td> </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <p>The conditional preprocessing block starts with <code>#if</code>, <code>#ifdef</code> or <code>#ifndef</code> directive, then optionally includes any number of <code>#elif</code><span class="t-rev-inl t-since-c23"><span>, <code>#elifdef</code>, or <code>#elifndef</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> directives, then optionally includes at most one <code>#else</code> directive and is terminated with <code>#endif</code> directive. Any inner conditional preprocessing blocks are processed separately.</p> +<p>Each of <code>#if</code>, <code>#ifdef</code>, <code>#ifndef</code>, <code>#elif</code><span class="t-rev-inl t-since-c23"><span>, <code>#elifdef</code>, <code>#elifndef</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, and <code>#else</code> directives control code block until first <code>#elif</code><span class="t-rev-inl t-since-c23"><span>, <code>#elifdef</code>, <code>#elifndef</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, <code>#else</code>, <code>#endif</code> directive not belonging to any inner conditional preprocessing blocks.</p> +<p><code>#if</code>, <code>#ifdef</code> and <code>#ifndef</code> directives test the specified condition (see below) and if it evaluates to true, compiles the controlled code block. In that case subsequent <code>#else</code><span class="t-rev-inl t-since-c23"><span>, <code>#elifdef</code>, <code>#elifndef</code>,</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> and <code>#elif</code> directives are ignored. Otherwise, if the specified condition evaluates false, the controlled code block is skipped and the subsequent <code>#else</code><span class="t-rev-inl t-since-c23"><span>, <code>#elifdef</code>, <code>#elifndef</code>,</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> or <code>#elif</code> directive (if any) is processed. If the subsequent directive is <code>#else</code>, the code block controlled by the <code>#else</code> directive is unconditionally compiled. Otherwise, the <code>#elif</code><span class="t-rev-inl t-since-c23"><span>, <code>#elifdef</code>, or <code>#elifndef</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> directive acts as if it was <code>#if</code> directive: checks for condition, compiles or skips the controlled code block based on the result, and in the latter case processes subsequent <code>#elif</code><span class="t-rev-inl t-since-c23"><span>, <code>#elifdef</code>, <code>#elifndef</code>,</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> and <code>#else</code> directives. The conditional preprocessing block is terminated by <code>#endif</code> directive.</p> +<h3 id="Conditional_evaluation"> Conditional evaluation</h3> <h4 id=".23if.2C_.23elif"> <span class="co2">#if, #elif</span> +</h4> <p>The <span class="t-spar">expression</span> is a constant expression, using only <a href="../language/expressions#Constants_and_literals" title="c/language/expressions">constants</a> and identifiers, defined using <a href="replace" title="c/preprocessor/replace"><code> #define</code></a> directive. Any identifier, which is not literal, non defined using <a href="replace" title="c/preprocessor/replace"><code> #define</code></a> directive, evaluates to <code>0</code> <span class="t-rev-inl t-since-c23"><span>except <code>true</code> which evaluates to <code>1</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>.</p> +<p>The expression may contain unary operators in form <code>defined</code> <span class="t-spar">identifier</span> or <code>defined (</code><span class="t-spar">identifier</span><code>)</code> which return <code>1</code> if the <span class="t-spar">identifier</span> was defined using <a href="replace" title="c/preprocessor/replace"><code> #define</code></a> directive and <code>0</code> otherwise. <span class="t-rev-inl t-since-c23"><span>In this context, <code>__has_include</code>, <code>__has_embed</code> and <code>__has_c_attribute</code> are treated as if they were the name of defined macros.</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> If the <span class="t-spar">expression</span> evaluates to nonzero value, the controlled code block is included and skipped otherwise. If any used identifier is not a constant, it is replaced with <code>0</code>.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>In context of a preprocessor directive, a <code>__has_c_attribute</code> expression detects whether a given attribute token is supported and its supported version. See <a href="../language/attributes#Attribute_testing" title="c/language/attributes">Attribute testing</a>.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <p>Note: Until <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/dr_412.htm">DR 412</a>, <code>#if <i>cond1</i></code> ... <code>#elif <i>cond2</i></code> is different from <code>#if <i>cond1</i></code> ... <code>#else</code> followed by <code>#if <i>cond3</i></code> because if <code><i>cond1</i></code> is true, the second <code>#if</code> is skipped and <code><i>cond3</i></code> does not need to be well-formed, while <code>#elif</code>'s <code><i>cond2</i></code> must be a valid expression. As of <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/dr_412.htm">DR 412</a>, <code>#elif</code> that leads the skipped code block is also skipped.</p> +<h4 id="Combined_directives"> Combined directives</h4> <p>Checks if the identifier was <a href="replace" title="c/preprocessor/replace">defined as a macro name</a>.</p> +<p><code>#ifdef</code> <span class="t-spar">identifier</span> is essentially equivalent to <code>#if defined</code> <span class="t-spar">identifier</span>.</p> +<p><code>#ifndef</code> <span class="t-spar">identifier</span> is essentially equivalent to <code>#if !defined</code> <span class="t-spar">identifier</span>.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p><code>#elifdef</code> <span class="t-spar">identifier</span> is essentially equivalent to <code>#elif defined</code> <span class="t-spar">identifier</span>.</p> +<p><code>#elifndef</code> <span class="t-spar">identifier</span> is essentially equivalent to <code>#elif !defined</code> <span class="t-spar">identifier</span>.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>While <code>#elifdef</code> and <code>#elifndef</code> directives target C23, implementations may backport them to the older language modes as conforming extensions.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#define ABCD 2 +#include <stdio.h> + +int main(void) +{ + +#ifdef ABCD + printf("1: yes\n"); +#else + printf("1: no\n"); +#endif + +#ifndef ABCD + printf("2: no1\n"); +#elif ABCD == 2 + printf("2: yes\n"); +#else + printf("2: no2\n"); +#endif + +#if !defined(DCBA) && (ABCD < 2 * 4 - 3) + printf("3: yes\n"); +#endif + +// C23 directives #elifdef/#elifndef +#ifdef CPU + printf("4: no1\n"); +#elifdef GPU + printf("4: no2\n"); +#elifndef RAM + printf("4: yes\n"); // selected in C23 mode, may be selected in pre-C23 mode +#else + printf("4: no3\n"); // may be selected in pre-C23 mode +#endif +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">1: yes +2: yes +3: yes +4: yes</pre></div> </div> <h3 id="Defect_reports"> Defect reports</h3> <p>The following behavior-changing defect reports were applied retroactively to previously published C standards.</p> +<table class="dsctable"> <tr> <th>DR </th> <th>Applied to </th> <th>Behavior as published </th> <th>Correct behavior </th> +</tr> <tr> <td> +<a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_412">DR 412</a> </td> <td>C89 </td> <td>failed <code>#elif</code>'s expression was required to be valid </td> <td>failed <code>#elif</code> is skipped </td> +</tr> +</table> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 6.10.1 Conditional inclusion (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.10.1 Conditional inclusion (p: 118-119) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.10.1 Conditional inclusion (p: 162-164) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.10.1 Conditional inclusion (p: 147-149) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.8.1 Conditional inclusion </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/preprocessor/conditional" title="cpp/preprocessor/conditional">C++ documentation</a></span> for <span class=""><span>Conditional inclusion</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/preprocessor/conditional" class="_attribution-link">https://en.cppreference.com/w/c/preprocessor/conditional</a> + </p> +</div> diff --git a/devdocs/c/preprocessor%2Fembed.html b/devdocs/c/preprocessor%2Fembed.html new file mode 100644 index 00000000..62c39019 --- /dev/null +++ b/devdocs/c/preprocessor%2Fembed.html @@ -0,0 +1,112 @@ + <h1 id="firstHeading" class="firstHeading">Binary resource inclusion <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <p><span class="co2">#embed</span> is a preprocessor directive to include (binary) resources in the build, where a resource is defined as a source of data accessible from the translation environment.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>#embed <</code> <span class="t-spar">h-char-sequence</span> <code>></code> <span class="t-spar">embed-parameter-sequence</span> <span class="t-mark">(optional)</span> <span class="t-spar">new-line</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>#embed "</code> <span class="t-spar">q-char-sequence</span> <code>"</code> <span class="t-spar">embed-parameter-sequence</span> <span class="t-mark">(optional)</span> <span class="t-spar">new-line</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>#embed</code> <span class="t-spar">pp-tokens</span> <span class="t-spar">new-line</span> </td> <td> (3) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>__has_embed</code> <code>(</code> <code>"</code> <span class="t-spar">q-char-sequence</span> <code>"</code> <span class="t-spar">embed-parameter-sequence</span> <span class="t-mark">(optional)</span> <code>)</code><br><code>__has_embed</code> <code>(</code> <code><</code> <span class="t-spar">h-char-sequence</span> <code>></code> <span class="t-spar">embed-parameter-sequence</span> <span class="t-mark">(optional)</span> <code>)</code> </td> <td> (4) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>__has_embed</code> <code>(</code> <span class="t-spar">string-literal</span> <span class="t-spar">pp-balanced-token-sequence</span> <span class="t-mark">(optional)</span> <code>)</code><br><code>__has_embed</code> <code>(</code> <code><</code> <span class="t-spar">h-pp-tokens</span> <code>></code> <span class="t-spar">pp-balanced-token-sequence</span> <span class="t-mark">(optional)</span> <code>)</code> </td> <td> (5) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> Searches for a resource identified uniquely by <span class="t-spar">h-char-sequence</span> and replaces the directive by a comma separated list of integers corresponding to the data of the resource.</div> <div class="t-li1"> +<span class="t-li">2)</span> Searches for a resource identified by <span class="t-spar">q-char-sequence</span> and replaces the directive by a list of integers corresponding to the data of the resource. It may fallback to <span class="t-v">(1)</span>.</div> <div class="t-li1"> +<span class="t-li">3)</span> If neither <span class="t-v">(1)</span> nor <span class="t-v">(2)</span> is matched, <span class="t-spar">pp-tokens</span> will undergo macro replacement. The directive after replacement will be tried to match with <span class="t-v">(1)</span> or <span class="t-v">(2)</span> again.</div> <div class="t-li1"> +<span class="t-li">4)</span> Checks whether a resource is available for embedding, whether it is empty or not and whether the parameters passed are supported by the implementation.</div> <div class="t-li1"> +<span class="t-li">5)</span> If <span class="t-v">(4)</span> is not matched, <span class="t-spar">h-pp-tokens</span> and <span class="t-spar">pp-balanced-token-sequence</span> will undergo macro replacement. The directive after replacement will be tried to match with <span class="t-v">(4)</span> again.</div> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">new-line</span> </td> <td> - </td> <td> The new-line character </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">h-char-sequence</span> </td> <td> - </td> <td> A sequence of one or more <span class="t-spar">h-char</span>s, where the appearance of any of the following causes undefined behavior: <ul> +<li> the character <code>'</code> </li> +<li> the character <code>"</code> </li> +<li> the character <code>\</code> </li> +<li> the character sequence <code>//</code> </li> +<li> the character sequence <code>/*</code> </li> +</ul> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">h-char</span> </td> <td> - </td> <td> Any member of the <a href="../language/translation_phases#Phase_5" title="c/language/translation phases">source character set</a> except new-line and <code>></code> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">q-char-sequence</span> </td> <td> - </td> <td> A sequence of one or more <span class="t-spar">q-char</span>s, where the appearance of any of the following causes undefined behavior: <ul> +<li> the character <code>'</code> </li> +<li> the character <code>\</code> </li> +<li> the character sequence <code>//</code> </li> +<li> the character sequence <code>/*</code> </li> +</ul> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">q-char</span> </td> <td> - </td> <td> Any member of the <a href="../language/translation_phases#Phase_5" title="c/language/translation phases">source character set</a> except new-line and <code>"</code> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">pp-tokens</span> </td> <td> - </td> <td> A sequence of one or more <a href="../language/translation_phases#Phase_3" title="c/language/translation phases">preprocessing tokens</a> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">string-literal</span> </td> <td> - </td> <td> A <a href="../language/string_literal" title="c/language/string literal">string literal</a> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">h-pp-tokens</span> </td> <td> - </td> <td> A sequence of one or more <a href="../language/translation_phases#Phase_3" title="c/language/translation phases">preprocessing tokens</a> except <code>></code> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">embed-parameter-sequence</span> </td> <td> - </td> <td> A sequence of one or more <span class="t-spar">pp-parameter</span> s. Note that unlike an <span class="t-spar">attribute-list</span>, this sequence is not comma separated. </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">pp-parameter</span> </td> <td> - </td> <td> An <span class="t-spar">attribute-token</span> (see: <a href="../language/attributes" title="c/language/attributes">attributes</a>) but comprised of preprocessing tokens instead of tokens. </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">pp-balanced-token-sequence</span> </td> <td> - </td> <td> A <span class="t-spar">balanced-token-sequence</span> (see: <a href="../language/attributes" title="c/language/attributes">attributes</a>) but comprised of preprocessing tokens instead of tokens </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <div class="t-li1"> +<span class="t-li">1)</span> Searches for the resource identified by <span class="t-spar">h-char-sequence</span> in implementation-defined manner.</div> <div class="t-li1"> +<span class="t-li">2)</span> Searches for the resource identified by <span class="t-spar">q-char-sequence</span> in implementation-defined manner. For <span class="t-v">(1,2)</span>, the implementations typically use a mechanism similar to, but distinct from, the implementation-defined search paths used for <a href="include" title="c/preprocessor/include">source file inclusion</a>. The construct <code>__has_embed(__FILE__ ...</code> appears in one of the examples in the standard, suggesting, in case <span class="t-v">(2)</span> at least, that the directory where the current file resides is expected to be searched.</div> <div class="t-li1"> +<span class="t-li">3)</span> The preprocessing tokens after <code>embed</code> in the directive are processed just as in normal text (i.e., each identifier currently defined as a macro name is replaced by its replacement list of preprocessing tokens). The directive resulting after all replacements shall match one of the two previous forms. The method by which a sequence of preprocessing tokens between <code><</code> and <code>></code> preprocessing token pair or a pair of <code>"</code> characters is combined into a single header name preprocessing token is implementation-defined.</div> <div class="t-li1"> +<span class="t-li">4)</span> The resource identified by <span class="t-spar">h-char-sequence</span> or <span class="t-spar">q-char-sequence</span> is searched for as if that preprocessing token sequence were the <span class="t-spar">pp-tokens</span> in syntax <span class="t-v">(3)</span>, except that no further macro expansion is performed. If such a directive would not satisfy the syntactic requirements of an <span class="co2">#embed</span> directive, the program is ill-formed. The <code>__has__embed</code> expression evaluates to <code>__STDC_EMBED_FOUND__</code> if the search for the resource succeeds, the resource is non empty and all the parameters are supported, to <code>__STDC_EMBED_EMPTY__</code> if the resource is empty and all the parameters are supported, and to <code>__STDC_EMBED_NOT_FOUND__</code> if the search fails or one of the parameters passed is not supported by the implementation.</div> <div class="t-li1"> +<span class="t-li">5)</span> This form is considered only if syntax <span class="t-v">(4)</span> does not match, in which case the preprocessing tokens are processed just as in normal text.</div> <p>In the case the resource is not found or one of the parameters is not supported by the implementation, the program is ill-formed.</p> +<p><code>__has_embed</code> can be expanded in the expression of <a href="conditional" title="c/preprocessor/conditional"><code> #if</code></a> and <a href="conditional" title="c/preprocessor/conditional"><code> #elif</code></a>. It is treated as a defined macro by <a href="conditional" title="c/preprocessor/conditional"><code> #ifdef</code></a>, <a href="conditional" title="c/preprocessor/conditional"><code> #ifndef</code></a>, <a href="conditional" title="c/preprocessor/conditional"><code> #elifdef</code></a>, <a href="conditional" title="c/preprocessor/conditional"><code> #elifndef</code></a> and <a href="conditional" title="c/preprocessor/conditional"><code>defined</code></a> but cannot be used anywhere else.</p> +<p>A resource has an <i>implementation resource width</i> which is the implementation-defined size in bits of the located resource. Its <i>resource width</i> is the implementation resource width unless modified by a <code>limit</code> parameter. If the resource width is 0, the resource is considered empty. The <i>embed element width</i> is equal to <code><a href="../types/limits" title="c/types/limits">CHAR_BIT</a></code> unless modified by an implementation defined parameter. The resource width must be divisible by the embed element width.</p> +<p>The expansion of a #embed directive is a token sequence formed from the list of integer <a href="../language/constant_expression" title="c/language/constant expression">constant expressions</a> described below. The group of tokens for each integer constant expression in the list is separated in the token sequence from the group of tokens for the previous integer constant expression in the list by a comma. The sequence neither begins nor ends in a comma. If the list of integer constant expressions is empty, the token sequence is empty. The directive is replaced by its expansion and, with the presence of certain embed parameters, additional or replacement token sequences.</p> +<p>The values of the integer constant expressions in the expanded sequence are determined by an implementation-defined mapping of the resource’s data. Each integer constant expression’s value is in the range <code>[</code>0<code>, </code>2<sup>embed element width</sup><code>)</code>. If:</p> +<ol> +<li> The list of integer constant expressions is used to initialize an array of a type compatible with <code>unsigned char</code>, or compatible with <code>char</code> if <code>char</code> cannot hold negative values, and </li> +<li> The embed element width is equal to <code><a href="../types/limits" title="c/types/limits">CHAR_BIT</a></code>, </li> +</ol> <p>then the contents of the initialized elements of the array are as-if the resource’s binary data is <code><a href="../io/fread" title="c/io/fread">fread</a></code> into the array at translation time.</p> +<p>Implementations are encouraged to take into account translation-time bit and byte orders as well as execution-time bit and byte orders to more appropriately represent the resource’s binary data from the directive. This maximizes the chance that, if the resource referenced at translation time through the <span class="co2">#embed</span> directive is the same one accessed through execution-time means, the data that is e.g. <code><a href="../io/fread" title="c/io/fread">fread</a></code> or similar into contiguous storage will compare bit-for-bit equal to an array of character type initialized from an <span class="co2">#embed</span> directive’s expanded contents.</p> +<h3 id="Parameters"> Parameters</h3> <p>The standard defines the parameters <code>limit</code>, <code>prefix</code>, <code>suffix</code> and <code>if_empty</code>. Any other parameter that appears in the directive must be implementation-defined, or the program is ill-formed. Implementation-defined embed parameters may change the semantics of the directive.</p> +<h4 id="limit"> limit</h4> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>limit(</code> <span class="t-spar">constant-expression</span> <code>)</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>__limit__(</code> <span class="t-spar">constant-expression</span> <code>)</code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>The <code>limit</code> embed parameter can appear at most once in the embed parameter sequence. It must have an argument, which must be an integer (preprocessor) <a href="../language/constant_expression" title="c/language/constant expression">constant expression</a> that evaluates to a non negative number and does not contain the token <code>defined</code>. The resource width is set to the minimum of the integer constant expression multiplied by the embed element width and the implementation resource width.</p> +<h4 id="suffix"> suffix</h4> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>suffix(</code> <span class="t-spar">pp-balanced-token-sequence</span> <span class="t-mark">(optional)</span> <code>)</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>__suffix__(</code> <span class="t-spar">pp-balanced-token-sequence</span> <span class="t-mark">(optional)</span> <code>)</code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>The <code>suffix</code> embed parameter can appear at most once in the embed parameter sequence. It must have a (possibly empty) preprocessor argument clause. If the resource is non empty, the contents of the parameter clause are placed immediately after the expansion of the directive. Otherwise, it has no effect.</p> +<h4 id="prefix"> prefix</h4> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>prefix(</code> <span class="t-spar">pp-balanced-token-sequence</span> <span class="t-mark">(optional)</span> <code>)</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>__prefix__(</code> <span class="t-spar">pp-balanced-token-sequence</span> <span class="t-mark">(optional)</span> <code>)</code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>The <code>prefix</code> embed parameter can appear at most once in the embed parameter sequence. It must have a (possibly empty) preprocessor argument clause. If the resource is non empty, the contents of the parameter clause are placed immediately before the expansion of the directive. Otherwise, it has no effect.</p> +<h4 id="if_empty"> if_empty</h4> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>if_empty(</code> <span class="t-spar">pp-balanced-token-sequence</span> <span class="t-mark">(optional)</span> <code>)</code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>__if_empty__(</code> <span class="t-spar">pp-balanced-token-sequence</span> <span class="t-mark">(optional)</span> <code>)</code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>The <code>if_empty</code> embed parameter can appear at most once in the embed parameter sequence. It must have a (possibly empty) preprocessor argument clause. If the resource is empty, the contents of the parameter clause replace the directive. Otherwise, it has no effect.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdint.h> +#include <stdio.h> + +const uint8_t image_data[] = { +#embed "image.png" +}; + +const char message[] = { +#embed "message.txt" if_empty('M', 'i', 's', 's', 'i', 'n', 'g', '\n') +,'\0' // null terminator +}; + +void dump(const uint8_t arr[], size_t size) +{ + for (size_t i = 0; i != size; ++i) + printf("%02X%c", arr[i], (i + 1) % 16 ? ' ' : '\n'); + puts(""); +} + +int main() +{ + puts("image_data[]:"); + dump(image_data, sizeof image_data); + puts("message[]:"); + dump((const uint8_t*)message, sizeof message); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">image_data[]: +89 50 4E 47 0D 0A 1A 0A 00 00 00 0D 49 48 44 52 +00 00 00 01 00 00 00 01 01 03 00 00 00 25 DB 56 +... +message[]: +4D 69 73 73 69 6E 67 0A 00</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 6.4.7 Header names (p: 69) </li> +<li> 6.10.1 Conditional inclusion (p: 165-169) </li> +<li> 6.10.2 Binary resource inclusion (p: 170-177) </li> +</ul> +</ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/preprocessor/embed" class="_attribution-link">https://en.cppreference.com/w/c/preprocessor/embed</a> + </p> +</div> diff --git a/devdocs/c/preprocessor%2Ferror.html b/devdocs/c/preprocessor%2Ferror.html new file mode 100644 index 00000000..decd26b2 --- /dev/null +++ b/devdocs/c/preprocessor%2Ferror.html @@ -0,0 +1,37 @@ + <h1 id="firstHeading" class="firstHeading">Diagnostic directives</h1> <p>Shows the given error message and renders the program ill-formed<span class="t-rev-inl t-since-c23"><span>, or given warning message without affect the validity of the program</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>#error</code> <span class="t-spar">diagnostic-message</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>#warning</code> <span class="t-spar">diagnostic-message</span> </td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <div class="t-li1"> +<span class="t-li">1)</span> After encountering the <code>#error</code> directive, an implementation displays the message <span class="t-spar">diagnostic-message</span> and renders the program ill-formed (the compilation stops).</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that the validity of the program is not affected and the compilation continues. </div> <p><span class="t-spar">diagnostic-message</span> can consist of several words not necessarily in quotes.</p> +<h3 id="Notes"> Notes</h3> <p>Before its standardization in C23, <code>#warning</code> has been provided by many compilers in all modes as a conforming extension.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#if __STDC__ != 1 +# error "Not a standard compliant compiler" +#endif + +#if __STDC_VERSION__ >= 202311L +# warning "Using #warning as a standard feature" +#endif + +#include <stdio.h> +int main (void) +{ + printf("The compiler used conforms to the ISO C Standard !!"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">The compiler used conforms to the ISO C Standard !!</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.10.5 Error directive (p: 126-127) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.10.5 Error directive (p: 174) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.10.5 Error directive (p: 159) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.8.5 Error directive </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/preprocessor/error" title="cpp/preprocessor/error">C++ documentation</a></span> for <span class=""><span>Diagnostic directives</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/preprocessor/error" class="_attribution-link">https://en.cppreference.com/w/c/preprocessor/error</a> + </p> +</div> diff --git a/devdocs/c/preprocessor%2Fimpl.html b/devdocs/c/preprocessor%2Fimpl.html new file mode 100644 index 00000000..3ef1cf4a --- /dev/null +++ b/devdocs/c/preprocessor%2Fimpl.html @@ -0,0 +1,82 @@ + <h1 id="firstHeading" class="firstHeading">Implementation defined behavior control</h1> <p>Implementation defined behavior is controlled by <code>#pragma</code> directive.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>#pragma</code> <span class="t-spar">pragma_params</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>_Pragma</code> <code>(</code> <span class="t-spar">string-literal</span> <code>)</code> </td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> Behaves in an implementation-defined manner (unless <span class="t-spar">pragma_params</span> is one of the standard pragmas shown below).</div> <div class="t-li1"> +<span class="t-li">2)</span> Removes the encoding prefix (if any), the outer quotes, and leading/trailing whitespace from <span class="t-spar">string-literal</span>, replaces each <code>\"</code> with <code>"</code> and each <code>\\</code> with <code>\</code>, then tokenizes the result (as in <a href="../language/translation_phases" title="c/language/translation phases">translation stage 3</a>), and then uses the result as if the input to <code>#pragma</code> in <span class="t-v">(1)</span>.</div> <h3 id="Explanation"> Explanation</h3> <p>The pragma directive controls implementation-specific behavior of the compiler, such as disabling compiler warnings or changing alignment requirements. Any pragma that is not recognized is ignored.</p> +<h3 id="Standard_pragmas"> Standard pragmas</h3> <p>The following three pragmas are defined by the language standard:</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>#pragma STDC FENV_ACCESS </code><span class="t-spar">arg</span> </td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>#pragma STDC FP_CONTRACT </code><span class="t-spar">arg</span> </td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>#pragma STDC CX_LIMITED_RANGE </code><span class="t-spar">arg</span> </td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> +</tr> +</table> <p>where <span class="t-spar">arg</span> is either <code>ON</code> or <code>OFF</code> or <code>DEFAULT</code>.</p> +<div class="t-li1"> +<span class="t-li">1)</span> If set to <code>ON</code>, informs the compiler that the program will access or modify <a href="../numeric/fenv" title="c/numeric/fenv">floating-point environment</a>, which means that optimizations that could subvert flag tests and mode changes (e.g., global common subexpression elimination, code motion, and constant folding) are prohibited. The default value is implementation-defined, usually <code>OFF</code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Allows <i>contracting</i> of floating-point expressions, that is optimizations that omit rounding errors and floating-point exceptions that would be observed if the expression was evaluated exactly as written. For example, allows the implementation of <code>(x * y) + z</code> with a single fused multiply-add CPU instruction. The default value is implementation-defined, usually <code>ON</code>.</div> <div class="t-li1"> +<span class="t-li">3)</span> Informs the compiler that multiplication, division, and absolute value of complex numbers may use simplified mathematical formulas (x+iy)×(u+iv) = (xu-yv)+i(yu+xv), (x+iy)/(u+iv) = [(xu+yv)+i(yu-xv)]/(u<sup class="t-su">2</sup>+v<sup class="t-su">2</sup>), and |x+iy| = <span class="t-mrad"><span>√</span><span>x<sup class="t-su">2</sup>+y<sup class="t-su">2</sup></span></span>, despite the possibility of intermediate overflow. In other words, the programmer guarantees that the range of the values that will be passed to those function is limited. The default value is <code>OFF</code> +</div> <p>Note: compilers that do not support these pragmas may provide equivalent compile-time options, such as gcc's <code>-fcx-limited-range</code> and <code>-ffp-contract</code>.</p> +<h3 id="Non-standard_pragmas"> Non-standard pragmas</h3> <h4 id=".23pragma_once"> <span class="co2">#pragma once</span> +</h4> <p><code>#pragma once</code> is a non-standard pragma that is supported by the <a href="https://en.wikipedia.org/wiki/Pragma_once#Portability" class="extiw" title="enwiki:Pragma once">vast majority of modern compilers</a>. If it appears in a header file, it indicates that it is only to be parsed once, even if it is (directly or indirectly) included multiple times in the same source file.</p> +<p>Standard approach to preventing multiple inclusion of the same header is by using <a href="https://en.wikipedia.org/wiki/Include_guard" class="extiw" title="enwiki:Include guard">include guards</a>:</p> +<div class="c source-c"><pre data-language="c">#ifndef LIBRARY_FILENAME_H +#define LIBRARY_FILENAME_H +// contents of the header +#endif /* LIBRARY_FILENAME_H */</pre></div> <p>So that all but the first inclusion of the header in any translation unit are excluded from compilation. All modern compilers record the fact that a header file uses an include guard and do not re-parse the file if it is encountered again, as long as the guard is still defined (see e.g. <a rel="nofollow" class="external text" href="https://gcc.gnu.org/onlinedocs/cpp/Once-Only-Headers.html">gcc</a>).</p> +<p>With <code>#pragma once</code>, the same header appears as</p> +<div class="c source-c"><pre data-language="c">#pragma once +// contents of the header</pre></div> <p>Unlike header guards, this pragma makes it impossible to erroneously use the same macro name in more than one file. On the other hand, since with <code>#pragma once</code> files are excluded based on their filesystem-level identity, this can't protect against including a header twice if it exists in more than one location in a project.</p> +<h4 id=".23pragma_pack"> <span class="co2">#pragma pack</span> +</h4> <p>This family of pragmas control the maximum alignment for subsequently defined structure and union members.</p> +<table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>#pragma pack(<span class="t-spar">arg</span>) </code> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>#pragma pack() </code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>#pragma pack(push) </code> </td> <td> (3) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>#pragma pack(push, <span class="t-spar">arg</span>) </code> </td> <td> (4) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>#pragma pack(pop) </code> </td> <td> (5) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <p>where <span class="t-spar">arg</span> is a small power of two and specifies the new alignment in bytes.</p> +<div class="t-li1"> +<span class="t-li">1)</span> Sets the current alignment to value <span class="t-spar">arg</span>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Sets the current alignment to the default value (specified by a command-line option).</div> <div class="t-li1"> +<span class="t-li">3)</span> Pushes the value of the current alignment on an internal stack.</div> <div class="t-li1"> +<span class="t-li">4)</span> Pushes the value of the current alignment on the internal stack and then sets the current alignment to value <span class="t-spar">arg</span>.</div> <div class="t-li1"> +<span class="t-li">5)</span> Pops the top entry from the internal stack and then sets (restores) the current alignment to that value.</div> <p><code>#pragma pack</code> may decrease the alignment of a structure, however, it cannot make a structure overaligned.</p> +<p>See also specific details for <a rel="nofollow" class="external text" href="https://gcc.gnu.org/onlinedocs/gcc/Structure-Layout-Pragmas.html">GCC</a> and <a rel="nofollow" class="external text" href="https://docs.microsoft.com/en-us/cpp/preprocessor/pack">MSVC</a>.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.10.6 Pragma directive (p: 127) </li> +<li> 6.10.9 Pragma operator (p: 129) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.10.6 Pragma directive (p: 174) </li> +<li> 6.10.9 Pragma operator (p: 178) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 6.10.6 Pragma directive (p: 159) </li> +<li> 6.10.9 Pragma operator (p: 161-162) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.8.6 Pragma directive </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/preprocessor/impl" title="cpp/preprocessor/impl">C++ documentation</a></span> for <span class=""><span>Implementation defined behavior control</span></span> </td> +</tr> </table> <h3 id="External_links"> External links</h3> <table> <tr style="vertical-align:top;"> <td>1. </td> <td> +<a rel="nofollow" class="external text" href="https://docs.microsoft.com/en-us/cpp/preprocessor/pragma-directives-and-the-pragma-keyword?view=vs-2019">C++ pragmas in Visual Studio 2019</a> </td> +</tr> <tr style="vertical-align:top;"> <td>2. </td> <td> +<a rel="nofollow" class="external text" href="https://gcc.gnu.org/onlinedocs/gcc/Pragmas.html">Pragmas</a> accepted by GCC </td> +</tr> <tr style="vertical-align:top;"> <td>3. </td> <td> +<a rel="nofollow" class="external text" href="https://www.ibm.com/support/knowledgecenter/en/SSGH3R_16.1.0/com.ibm.xlcpp161.aix.doc/compiler_ref/pragma_descriptions.html">Individual pragma descriptions</a> and <a rel="nofollow" class="external text" href="https://www.ibm.com/support/knowledgecenter/en/SSGH3R_16.1.0/com.ibm.xlcpp161.aix.doc/language_ref/std_pragmas.html">Standard pragmas</a> in IBM AIX XL C 16.1 </td> +</tr> <tr style="vertical-align:top;"> <td>4. </td> <td> +<a rel="nofollow" class="external text" href="http://download.oracle.com/docs/cd/E19422-01/819-3690/Pragmas_App.html#73499">Appendix B. Pragmas</a> in Sun Studio 11 C++ User's Guide </td> +</tr> <tr style="vertical-align:top;"> <td>5. </td> <td> +<a rel="nofollow" class="external text" href="https://software.intel.com/content/www/us/en/develop/documentation/cpp-compiler-developer-guide-and-reference/top/compiler-reference/pragmas.html">Intel C++ compiler pragmas</a> </td> +</tr> <tr style="vertical-align:top;"> <td>6. </td> <td> +<a rel="nofollow" class="external text" href="http://h21007.www2.hp.com/portal/download/files/unprot/aCxx/Online_Help/pragmas.htm">HP aCC compiler pragmas</a> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/preprocessor/impl" class="_attribution-link">https://en.cppreference.com/w/c/preprocessor/impl</a> + </p> +</div> diff --git a/devdocs/c/preprocessor%2Finclude.html b/devdocs/c/preprocessor%2Finclude.html new file mode 100644 index 00000000..b4bf7c7b --- /dev/null +++ b/devdocs/c/preprocessor%2Finclude.html @@ -0,0 +1,72 @@ + <h1 id="firstHeading" class="firstHeading">Source file inclusion</h1> <p>Includes another source file into the current source file at the line immediately after the directive.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>#include <</code> <span class="t-spar">h-char-sequence</span> <code>></code> <span class="t-spar">new-line</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>#include "</code> <span class="t-spar">q-char-sequence</span> <code>"</code> <span class="t-spar">new-line</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>#include</code> <span class="t-spar">pp-tokens</span> <span class="t-spar">new-line</span> </td> <td> (3) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>__has_include</code> <code>(</code> <code>"</code> <span class="t-spar">q-char-sequence</span> <code>"</code> <code>)</code><br><code>__has_include</code> <code>(</code> <code><</code> <span class="t-spar">h-char-sequence</span> <code>></code> <code>)</code> </td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>__has_include</code> <code>(</code> <span class="t-spar">string-literal</span> <code>)</code><br><code>__has_include</code> <code>(</code> <code><</code> <span class="t-spar">h-pp-tokens</span> <code>></code> <code>)</code> </td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> Searches for a header identified uniquely by <span class="t-spar">h-char-sequence</span> and replaces the directive by the entire contents of the header.</div> <div class="t-li1"> +<span class="t-li">2)</span> Searches for a source file identified by <span class="t-spar">q-char-sequence</span> and replaces the directive by the entire contents of the source file. It may fallback to <span class="t-v">(1)</span> and treat <span class="t-spar">q-char-sequence</span> as a header identifier.</div> <div class="t-li1"> +<span class="t-li">3)</span> If neither <span class="t-v">(1)</span> nor <span class="t-v">(2)</span> is matched, <span class="t-spar">pp-tokens</span> will undergo macro replacement. The directive after replacement will be tried to match with <span class="t-v">(1)</span> or <span class="t-v">(2)</span> again.</div> <div class="t-li1"> +<span class="t-li">4)</span> Checks whether a header or source file is available for inclusion.</div> <div class="t-li1"> +<span class="t-li">5)</span> If <span class="t-v">(4)</span> is not matched, <span class="t-spar">h-pp-tokens</span> will undergo macro replacement. The directive after replacement will be tried to match with <span class="t-v">(4)</span> again.</div> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">new-line</span> </td> <td> - </td> <td> The new-line character </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">h-char-sequence</span> </td> <td> - </td> <td> A sequence of one or more <span class="t-spar">h-char</span>s, where the appearance of any of the following causes undefined behavior: <ul> +<li> the character <code>'</code> </li> +<li> the character <code>"</code> </li> +<li> the character <code>\</code> </li> +<li> the character sequence <code>//</code> </li> +<li> the character sequence <code>/*</code> </li> +</ul> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">h-char</span> </td> <td> - </td> <td> Any member of the <a href="../language/translation_phases#Phase_5" title="c/language/translation phases">source character set</a> except new-line and <code>></code> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">q-char-sequence</span> </td> <td> - </td> <td> A sequence of one or more <span class="t-spar">q-char</span>s, where the appearance of any of the following causes undefined behavior: <ul> +<li> the character <code>'</code> </li> +<li> the character <code>\</code> </li> +<li> the character sequence <code>//</code> </li> +<li> the character sequence <code>/*</code> </li> +</ul> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">q-char</span> </td> <td> - </td> <td> Any member of the <a href="../language/translation_phases#Phase_5" title="c/language/translation phases">source character set</a> except new-line and <code>"</code> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">pp-tokens</span> </td> <td> - </td> <td> A sequence of one or more <a href="../language/translation_phases#Phase_3" title="c/language/translation phases">preprocessing tokens</a> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">string-literal</span> </td> <td> - </td> <td> A <a href="../language/string_literal" title="c/language/string literal">string literal</a> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">h-pp-tokens</span> </td> <td> - </td> <td> A sequence of one or more <a href="../language/translation_phases#Phase_3" title="c/language/translation phases">preprocessing tokens</a> except <code>></code> </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <div class="t-li1"> +<span class="t-li">1)</span> Searches for the file identified by <span class="t-spar">h-char-sequence</span> in implementation-defined manner. The intent of this syntax is to search for the files under control of the implementation. Typical implementations search only standard include directories. The standard C library is implicitly included in these standard include directories. The standard include directories usually can be controlled by the user through compiler options.</div> <div class="t-li1"> +<span class="t-li">2)</span> Searches for the file identified by <span class="t-spar">q-char-sequence</span> in implementation-defined manner. The intent of this syntax is to search for the files that are not controlled by the implementation. Typical implementations first search the directory where the current file resides and, only if the file is not found, search the standard include directories as with <span class="t-v">(1)</span>.</div> <div class="t-li1"> +<span class="t-li">3)</span> The preprocessing tokens after <code>include</code> in the directive are processed just as in normal text (i.e., each identifier currently defined as a macro name is replaced by its replacement list of preprocessing tokens). The directive resulting after all replacements shall match one of the two previous forms. The method by which a sequence of preprocessing tokens between <code><</code> and <code>></code> preprocessing token pair or a pair of <code>"</code> characters is combined into a single header name preprocessing token is implementation-defined.</div> <div class="t-li1"> +<span class="t-li">4)</span> The header or source file identified by <span class="t-spar">h-char-sequence</span> or <span class="t-spar">q-char-sequence</span> is searched for as if that preprocessing token sequence were the <span class="t-spar">pp-tokens</span> in syntax <span class="t-v">(3)</span>, except that no further macro expansion is performed. If such a directive would not satisfy the syntactic requirements of an <span class="co2">#include</span> directive, the program is ill-formed. The <code>__has_include</code> expression evaluates to <code>1</code> if the search for the source file succeeds, and to <code>0</code> if the search fails.</div> <div class="t-li1"> +<span class="t-li">5)</span> This form is considered only if syntax <span class="t-v">(4)</span> does not match, in which case the preprocessing tokens are processed just as in normal text.</div> <p>In the case the file is not found, the program is ill-formed.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p><code>__has_include</code> can be expanded in the expression of <a href="conditional" title="c/preprocessor/conditional"><code> #if</code></a> and <a href="conditional" title="c/preprocessor/conditional"><code> #elif</code></a>. It is treated as a defined macro by <a href="conditional" title="c/preprocessor/conditional"><code> #ifdef</code></a>, <a href="conditional" title="c/preprocessor/conditional"><code> #ifndef</code></a>, <a href="conditional" title="c/preprocessor/conditional"><code> #elifdef</code></a>, <a href="conditional" title="c/preprocessor/conditional"><code> #elifndef</code></a> and <a href="conditional" title="c/preprocessor/conditional"><code>defined</code></a> but cannot be used anywhere else.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>Typical implementations search only standard include directories for syntax (1). The standard C library is implicitly included in these standard include directories. The standard include directories usually can be controlled by the user through compiler options.</p> +<p>The intent of syntax <span class="t-v">(2)</span> is to search for the files that are not controlled by the implementation. Typical implementations first search the directory where the current file resides then falls back to <span class="t-v">(1)</span>.</p> +<p>When a file is included, it is processed by <a href="../language/translation_phases" title="c/language/translation phases">translation phases</a> 1-4, which may include, recursively, expansion of the nested <code>#include</code> directives, up to an implementation-defined nesting limit. To avoid repeated inclusion of the same file and endless recursion when a file includes itself, perhaps transitively, <i>header guards</i> are commonly used: the entire header is wrapped in</p> +<div class="c source-c"><pre data-language="c">#ifndef FOO_H_INCLUDED /* any name uniquely mapped to file name */ +#define FOO_H_INCLUDED +// contents of the file are here +#endif</pre></div> <p>Many compilers also implement the non-standard <a href="impl" title="c/preprocessor/impl"><code>pragma</code></a> <code>#pragma once</code> with similar effects: it disables processing of a file if the same file (where file identity is determined in OS-specific way) has already been included.</p> +<p>A <code>__has_include</code> result of <code>1</code> only means that a header or source file with the specified name exists. It does not mean that the header or source file, when included, would not cause an error or would contain anything useful.</p> +<h3 id="Example"> Example</h3> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 6.4.7 Header names (p: 69) </li> +<li> 6.10.1 Conditional inclusion (p: 165-169) </li> +<li> 6.10.2 Source file inclusion (p: 169-170) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.10.2 Source file inclusion (p: 119-120) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.10.2 Source file inclusion (p: 164-166) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.10.2 Source file inclusion (p: 149-151) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.8.2 Source file inclusion </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <a href="../index" title="c/header">A list of C Standard Library header files</a> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/preprocessor/include" title="cpp/preprocessor/include">C++ documentation</a></span> for <span class=""><span>Source file inclusion</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/preprocessor/include" class="_attribution-link">https://en.cppreference.com/w/c/preprocessor/include</a> + </p> +</div> diff --git a/devdocs/c/preprocessor%2Fline.html b/devdocs/c/preprocessor%2Fline.html new file mode 100644 index 00000000..92993911 --- /dev/null +++ b/devdocs/c/preprocessor%2Fline.html @@ -0,0 +1,37 @@ + <h1 id="firstHeading" class="firstHeading">Filename and line information</h1> <p>Changes the current line number and file name in the preprocessor.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>#line</code> <span class="t-spar">lineno</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>#line</code> <span class="t-spar">lineno</span> <code>"</code><span class="t-spar">filename</span><code>"</code> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <div class="t-li1"> +<span class="t-li">1)</span> Changes the current preprocessor line number to <span class="t-spar">lineno</span>. Occurrences of the macro <code>__LINE__</code> beyond this point will expand to <span class="t-spar">lineno</span> plus the number of actual source code lines encountered since.</div> <div class="t-li1"> +<span class="t-li">2)</span> Also changes the current preprocessor file name to <span class="t-spar">filename</span>. Occurrences of the macro <code>__FILE__</code> beyond this point will produce <span class="t-spar">filename</span>.</div> <p>Any preprocessing tokens (macro constants or expressions) are permitted as arguments to <code>#line</code> as long as they expand to a valid decimal integer optionally following a valid character string.</p> +<p><span class="t-spar">lineno</span> must be a sequence of at least one decimal digit (the program is ill-formed, otherwise) and is always interpreted as decimal (even if it starts with <code>0</code>).</p> +<p>If <span class="t-spar">lineno</span> is <code>0</code> or greater than <span class="t-rev-inl t-until-c99"><span><code>32767</code></span><span><span class="t-mark-rev t-until-c99">(until C99)</span></span></span><span class="t-rev-inl t-since-c99"><span><code>2147483647</code></span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>, the behavior is undefined.</p> +<h3 id="Notes"> Notes</h3> <p>This directive is used by some automatic code generation tools which produce C source files from a file written in another language. In that case, <code>#line</code> directives may be inserted in the generated C file referencing line numbers and the file name of the original (human-editable) source file.</p> +<p>The line number following the directive <code>#line __LINE__</code> is unspecified (there are two possible values that <code>__LINE__</code> can expand to in this case: number of endlines seen so far, or number of endlines seen so far plus the endline that ends the <code>#line</code> directive). This is the result of <a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2257.htm#dr_464">DR 464</a>, which applies retroactively.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <assert.h> +#define FNAME "test.c" +int main(void) +{ +#line 777 FNAME + assert(2+2 == 5); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">test: test.c:777: int main(): Assertion `2+2 == 5' failed.</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.10.4 Line control (p: 126) </li> +<li> J.1 Unspecified behavior </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.10.4 Line control (p: 173) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.10.4 Line control (p: 158) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.8.4 Line control </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/preprocessor/line" title="cpp/preprocessor/line">C++ documentation</a></span> for <span class=""><span>Filename and line information</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/preprocessor/line" class="_attribution-link">https://en.cppreference.com/w/c/preprocessor/line</a> + </p> +</div> diff --git a/devdocs/c/preprocessor%2Freplace.html b/devdocs/c/preprocessor%2Freplace.html new file mode 100644 index 00000000..19c051cf --- /dev/null +++ b/devdocs/c/preprocessor%2Freplace.html @@ -0,0 +1,160 @@ + <h1 id="firstHeading" class="firstHeading">Replacing text macros</h1> <p>The preprocessor supports text macro replacement and function-like text macro replacement.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>#define</code> <span class="t-spar">identifier</span> <span class="t-spar">replacement-list</span> <span class="t-mark">(optional)</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>#define</code> <span class="t-spar">identifier</span> <code>(</code> <span class="t-spar">parameters</span> <code>)</code> <span class="t-spar">replacement-list</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>#define</code> <span class="t-spar">identifier</span> <code>(</code> <span class="t-spar">parameters</span><code>, ... )</code> <span class="t-spar">replacement-list</span> </td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>#define</code> <span class="t-spar">identifier</span> <code>( ... )</code> <span class="t-spar">replacement-list</span> </td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>#undef</code> <span class="t-spar">identifier</span> </td> <td> (5) </td> <td class="t-sdsc-nopad"> </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <h4 id=".23define_directives"> <span class="co2">#define</span> directives</h4> <p>The <code>#define</code> directives define the <span class="t-spar">identifier</span> as a macro, that is they instruct the compiler to replace all successive occurrences of <span class="t-spar">identifier</span> with <span class="t-spar">replacement-list</span>, which can be optionally additionally processed. If the identifier is already defined as any type of macro, the program is ill-formed unless the definitions are identical.</p> +<h5 id="Object-like_macros"> Object-like macros</h5> <p>Object-like macros replace every occurrence of a defined <span class="t-spar">identifier</span> with <span class="t-spar">replacement-list</span>. Version (1) of the <code>#define</code> directive behaves exactly like that.</p> +<h5 id="Function-like_macros"> Function-like macros</h5> <p>Function-like macros replace each occurrence of a defined <span class="t-spar">identifier</span> with <span class="t-spar">replacement-list</span>, additionally taking a number of arguments, which then replace corresponding occurrences of any of the <span class="t-spar">parameters</span> in the <span class="t-spar">replacement-list</span>.</p> +<p>The syntax of a function-like macro invocation is similar to the syntax of a function call: each instance of the macro name followed by a ( as the next preprocessing token introduces the sequence of tokens that is replaced by the replacement-list. The sequence is terminated by the matching ) token, skipping intervening matched pairs of left and right parentheses.</p> +<p>The number of arguments must be the same as the number of arguments in the macro definition (<span class="t-spar">parameters</span>) or the program is ill-formed. If the identifier is not in functional-notation, i.e. does not have parentheses after itself, it is not replaced at all.</p> +<p>Version (2) of the <code>#define</code> directive defines a simple function-like macro.</p> +<p>Version (3) of the <code>#define</code> directive defines a function-like macro with variable number of arguments. The additional arguments can be accessed using <code>__VA_ARGS__</code> identifier, which is then replaced with arguments, supplied with the identifier to be replaced.</p> +<p>Version (4) of the <code>#define</code> directive defines a function-like macro with variable number of arguments, but no regular arguments. The arguments can be accessed only with <code>__VA_ARGS__</code> identifier, which is then replaced with arguments, supplied with identifier to be replaced.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>For versions (3,4), <span class="t-spar">replacement-list</span> may contain the token sequence <code>__VA_OPT__ (</code> <span class="t-spar">content</span> <code>)</code>, which is replaced by <span class="t-spar">content</span> if <code>__VA_ARGS__</code> is non-empty, and expands to nothing otherwise.</p> +<div class="c source-c"><pre data-language="c">#define F(...) f(0 __VA_OPT__(,) __VA_ARGS__) +F(a, b, c) // replaced by f(0, a, b, c) +F() // replaced by f(0) + +#define G(X, ...) f(0, X __VA_OPT__(,) __VA_ARGS__) +G(a, b, c) // replaced by f(0, a, b, c) +G(a, ) // replaced by f(0, a) +G(a) // replaced by f(0, a) + +#define SDEF(sname, ...) S sname __VA_OPT__(= { __VA_ARGS__ }) +SDEF(foo); // replaced by S foo; +SDEF(bar, 1, 2); // replaced by S bar = { 1, 2 };</pre></div> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <p><br> Note: if an argument of a function-like macro includes commas that are not protected by matched pairs of left and right parentheses (such as <code>macro(array[x = y, x + 1])</code> or <code><a href="http://en.cppreference.com/w/c/atomic/atomic_store"><span class="kw937">atomic_store</span></a> <span class="br0">(</span>p, <span class="br0">(</span><span class="kw1">struct</span> S<span class="br0">)</span><span class="br0">{</span> a, b <span class="br0">}</span><span class="br0">)</span><span class="sy4">;</span></code>), the comma is interpreted as macro argument separator, causing a compilation failure due to argument count mismatch.</p> +<h4 id=".23_and_.23.23_operators"> <span class="co2">#</span> and <span class="co2">##</span> operators</h4> <p>In function-like macros, a <code>#</code> operator before an identifier in the <span class="t-spar">replacement-list</span> runs the identifier through parameter replacement and encloses the result in quotes, effectively creating a string literal. In addition, the preprocessor adds backslashes to escape the quotes surrounding embedded string literals, if any, and doubles the backslashes within the string as necessary. All leading and trailing whitespace is removed, and any sequence of whitespace in the middle of the text (but not inside embedded string literals) is collapsed to a single space. This operation is called "stringification". If the result of stringification is not a valid string literal, the behavior is undefined.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>When <code>#</code> appears before <code>__VA_ARGS__</code>, the entire expanded <code>__VA_ARGS__</code> is enclosed in quotes:</p> +<div class="c source-c"><pre data-language="c">#define showlist(...) puts(#__VA_ARGS__) +showlist(); // expands to puts("") +showlist(1, "x", int); // expands to puts("1, \"x\", int")</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <p>A <code>##</code> operator between any two successive identifiers in the <span class="t-spar">replacement-list</span> runs parameter replacement on the two identifiers and then concatenates the result. This operation is called "concatenation" or "token pasting". Only tokens that form a valid token together may be pasted: identifiers that form a longer identifier, digits that form a number, or operators <code>+</code> and <code>=</code> that form a <code>+=</code>. A comment cannot be created by pasting <code>/</code> and <code>*</code> because comments are removed from text before macro substitution is considered. If the result of concatenation is not a valid token, the behavior is undefined.</p> +<p>Note: Some compilers offer an extension that allows <code>##</code> to appear after a comma and before <code>__VA_ARGS__</code>, in which case the <code>##</code> does nothing when <code>__VA_ARGS__</code> is non-empty, but removes the comma when <code>__VA_ARGS__</code> is empty: this makes it possible to define macros such as <code><a href="http://en.cppreference.com/w/c/io/fprintf"><span class="kw852">fprintf</span></a> <span class="br0">(</span><a href="http://en.cppreference.com/w/c/io/std_streams"><span class="kw888">stderr</span></a>, format, <span class="co2">##__VA_ARGS__)</span></code>.</p> +<p>The order of evaluation of <code>#</code> and <code>##</code> operators is unspecified.</p> +<h4 id=".23undef_directive"> <span class="co2">#undef</span> directive</h4> <p>The <code>#undef</code> directive undefines the <span class="t-spar">identifier</span>, that is it cancels the previous definition of the <span class="t-spar">identifier</span> by <code>#define</code> directive. If the identifier does not have an associated macro, the directive is ignored.</p> +<h3 id="Predefined_macros"> Predefined macros</h3> <p>The following macro names are predefined in any translation unit:</p> +<table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC__</span></span></div> </td> <td> expands to the integer constant <code>1</code>. This macro is intended to indicate a conforming implementation <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_VERSION__</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> expands to an integer constant of type <code>long</code> whose value increases with each version of the C standard: <ul> +<li> <code>199409L</code> <span class="t-mark-rev t-since-c95">(C95)</span> </li> +<li> <code>199901L</code> <span class="t-mark-rev t-since-c99">(C99)</span> </li> +<li> <code>201112L</code> <span class="t-mark-rev t-since-c11">(C11)</span> </li> +<li> <code>201710L</code> <span class="t-mark-rev t-since-c17">(C17)</span> </li> +<li> <code>202311L</code> <span class="t-mark-rev t-since-c23">(C23)</span> <br> <span class="t-mark">(macro constant)</span> </li> +</ul> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_HOSTED__</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> expands to the integer constant <code>1</code> if the implementation is hosted (runs under an OS), <code>0</code> if freestanding (runs without an OS) <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__FILE__</span></span></div> </td> <td> expands to the name of the current file, as a character string literal, can be changed by the <a href="line" title="c/preprocessor/line">#line</a> directive <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__LINE__</span></span></div> </td> <td> expands to the source file line number, an integer constant, can be changed by the <a href="line" title="c/preprocessor/line">#line</a> directive <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__DATE__</span></span></div> </td> <td> expands to the date of translation, a character string literal of the form "Mmm dd yyyy". The name of the month is as if generated by <code><a href="../chrono/asctime" title="c/chrono/asctime">asctime</a></code> and the first character of "dd" is a space if the day of the month is less than 10 <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__TIME__</span></span></div> </td> <td> expands to the time of translation, a character string literal of the form "hh:mm:ss", as in the time generated by <code><a href="http://en.cppreference.com/w/c/chrono/asctime"><span class="kw515">asctime</span></a><span class="br0">(</span><span class="br0">)</span></code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_UTF_16__</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> expands to <code>1</code> to indicate that <code>char16_t</code> use UTF-16 encoding <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_UTF_32__</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> expands to <code>1</code> to indicate that <code>char32_t</code> use UTF-32 encoding <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_EMBED_NOT_FOUND__</span><span>__STDC_EMBED_FOUND__</span><span>__STDC_EMBED_EMPTY__</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> expand to <code>0</code>, <code>1</code>, and <code>2</code>, respectively <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> <p>The following additional macro names may be predefined by an implementation:</p> +<table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_ISO_10646__</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> expands to an integer constant of the form <code>yyyymmL</code>, if <code>wchar_t</code> uses Unicode; the date indicates the latest revision of Unicode supported <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_IEC_559__</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> expands to <code>1</code> if IEC 60559 is supported <span class="t-rev-inl t-since-c23"><span><span class="t-mark">(deprecated)</span></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_IEC_559_COMPLEX__</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> expands to <code>1</code> if IEC 60559 complex arithmetic is supported <span class="t-rev-inl t-since-c23"><span><span class="t-mark">(deprecated)</span></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_UTF_16__</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> expands to <code>1</code> if <code>char16_t</code> use UTF-16 encoding <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_UTF_32__</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> expands to <code>1</code> if <code>char32_t</code> use UTF-32 encoding <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_MB_MIGHT_NEQ_WC__</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> expands to <code>1</code> if <code>'x' == L'x'</code> might be false for a member of the basic character set, such as on EBCDIC-based systems that use Unicode for <code>wchar_t</code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_ANALYZABLE__</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> expands to <code>1</code> if <a href="../language/analyzability" title="c/language/analyzability">analyzability</a> is supported <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_LIB_EXT1__</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> expands to an integer constant <code>201112L</code> if <a href="../error" title="c/error">bounds-checking interfaces</a> are supported <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_NO_ATOMICS__</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> expands to <code>1</code> if <a href="../language/atomic" title="c/language/atomic">atomic</a> types and <a href="../thread#Atomic_operations" title="c/thread">atomic operations library</a> are not supported <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_NO_COMPLEX__</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> expands to <code>1</code> if <a href="../language/arithmetic_types#Complex_floating_types" title="c/language/arithmetic types">complex types</a> and <a href="../numeric/complex" title="c/numeric/complex">complex math library</a> are not supported <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_NO_THREADS__</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> expands to <code>1</code> if <a href="../thread" title="c/thread">multithreading</a> is not supported <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_NO_VLA__</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> expands to <code>1</code> if <a href="../language/array#Variable-length_arrays" title="c/language/array">variable-length arrays</a> <span class="t-rev-inl t-until-c23"><span>and variably-modified types</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span>of automatic storage duration</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> are not supported <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_IEC_60559_BFP__</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> expands to <code>202311L</code> if IEC 60559 binary floating-point arithmetic is supported <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_IEC_60559_DFP__</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> expands to <code>202311L</code> if IEC 60559 decimal floating-point arithmetic is supported <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_IEC_60559_COMPLEX__</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> expands to <code>202311L</code> if IEC 60559 complex arithmetic is supported <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_IEC_60559_TYPES__</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> expands to <code>202311L</code> if IEC 60559 interchange and extended types are supported <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> <p>The values of these macros (except for <code>__FILE__</code> and <code>__LINE__</code>) remain constant throughout the translation unit. Attempts to redefine or undefine these macros result in undefined behavior.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>The predefined variable <code>__func__</code> (see <a href="../language/function_definition#func" title="c/language/function definition">function definition</a> for details) is not a preprocessor macro, even though it is sometimes used together with <code>__FILE__</code> and <code>__LINE__</code>, e.g. by <code><a href="../error/assert" title="c/error/assert">assert</a></code>.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> + +// make function factory and use it +#define FUNCTION(name, a) int fun_##name(int x) { return (a) * x; } + +FUNCTION(quadruple, 4) +FUNCTION(double, 2) + +#undef FUNCTION +#define FUNCTION 34 +#define OUTPUT(a) puts( #a ) + +int main(void) +{ + printf("quadruple(13): %d\n", fun_quadruple(13) ); + printf("double(21): %d\n", fun_double(21) ); + printf("%d\n", FUNCTION); + OUTPUT(billion); // note the lack of quotes +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">quadruple(13): 52 +double(21): 42 +34 +billion</pre></div> </div> <h3 id="Defect_reports"> Defect reports</h3> <p>The following behavior-changing defect reports were applied retroactively to previously published C standards.</p> +<table class="dsctable"> <tr> <th>DR </th> <th>Applied to </th> <th>Behavior as published </th> <th>Correct behavior </th> +</tr> <tr> <td> +<a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/dr_321.htm">DR 321</a> </td> <td>C99 </td> <td>it was unclear if <code>L'x' == 'x'</code> always holds<br>among the basic character set </td> <td> +<code>__STDC_MB_MIGHT_NEQ_WC__</code> added for the purpose </td> +</tr> +</table> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 6.10.4 Macro replacement (p: 187-184) </li> +<li> 6.10.9 Predefined macro names (p: 186-188) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.10.3 Macro replacement (p: 121-126) </li> +<li> 6.10.8 Predefined macro names (p: 127-129) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.10.3 Macro replacement (p: 166-173) </li> +<li> 6.10.8 Predefined macro names (p: 175-176) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 6.10.3 Macro replacement (p: 151-158) </li> +<li> 6.10.8 Predefined macro names (p: 160-161) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 3.8.3 Macro replacement </li> +<li> 3.8.8 Predefined macro names </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/preprocessor/replace" title="cpp/preprocessor/replace">C++ documentation</a></span> for <span class=""><span>Replacing text macros</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/preprocessor/replace" class="_attribution-link">https://en.cppreference.com/w/c/preprocessor/replace</a> + </p> +</div> diff --git a/devdocs/c/preprocessor.html b/devdocs/c/preprocessor.html new file mode 100644 index 00000000..1300711b --- /dev/null +++ b/devdocs/c/preprocessor.html @@ -0,0 +1,36 @@ + <h1 id="firstHeading" class="firstHeading">Preprocessor</h1> <p>The preprocessor is executed at <a href="language/translation_phases" title="c/language/translation phases">translation phase 4</a>, before the compilation. The result of preprocessing is a single file which is then passed to the actual compiler.</p> +<h3 id="Directives"> Directives</h3> <p>The preprocessing directives control the behavior of the preprocessor. Each directive occupies one line and has the following format:</p> +<ul> +<li> <code>#</code> character </li> +<li> preprocessing instruction (one of <code>define</code>, <code>undef</code>, <code>include</code>, <code>if</code>, <code>ifdef</code>, <code>ifndef</code>, <code>else</code>, <code>elif</code><span class="t-rev-inl t-since-c23"><span>, <code>elifdef</code>, <code>elifndef</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, <code>endif</code>, <code>line</code><span class="t-rev-inl t-since-c23"><span>, <code>embed</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, <code>error</code><span class="t-rev-inl t-since-c23"><span>, <code>warning</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, <code>pragma</code>) <sup id="cite_ref-1" class="reference"><a href="#cite_note-1">[1]</a></sup> </li> +<li> arguments (depends on the instruction) </li> +<li> line break </li> +</ul> <p>The null directive (<code>#</code> followed by a line break) is allowed and has no effect.</p> +<h3 id="Capabilities"> Capabilities</h3> <p>The preprocessor has the source file translation capabilities:</p> +<ul> +<li> <b><a href="preprocessor/conditional" title="c/preprocessor/conditional"> conditionally</a></b> compile of parts of source file (controlled by directive <code>#if</code>, <code>#ifdef</code>, <code>#ifndef</code>, <code>#else</code>, <code>#elif</code><span class="t-rev-inl t-since-c23"><span>, <code>#elifdef</code>, <code>#elifndef</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> and <code>#endif</code>). </li> +<li> <b><a href="preprocessor/replace" title="c/preprocessor/replace"> replace</a></b> text macros while possibly concatenating or quoting identifiers (controlled by directives <code>#define</code> and <code>#undef</code>, and operators <code>#</code> and <code>##</code>) </li> +<li> <b><a href="preprocessor/include" title="c/preprocessor/include">include</a></b> other files (controlled by directive <code>#include</code> <span class="t-rev-inl t-since-c23"><span>and checked with <code>__has_include</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>) </li> +<li> cause an <b><a href="preprocessor/error" title="c/preprocessor/error">error</a></b> <span class="t-rev-inl t-since-c23"><span>or <b><a href="preprocessor/error" title="c/preprocessor/error">warning</a></b></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> (controlled by directive <code>#error</code><span class="t-rev-inl t-since-c23"><span> or <code>#warning</code> respectively</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>) </li> +</ul> <p>The following aspects of the preprocessor can be controlled:</p> +<ul> +<li> <b><a href="preprocessor/impl" title="c/preprocessor/impl"> implementation defined</a></b> behavior (controlled by directive <code>#pragma</code><span class="t-rev-inl t-since-c99"><span> and operator <code>_Pragma</code></span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>) </li> +<li> <b><a href="preprocessor/line" title="c/preprocessor/line"> file name and line information</a></b> available to the preprocessor (controlled by directives <code>#line</code>) </li> +</ul> <h3 id="Footnotes"> Footnotes</h3> <ol class="references"> <li id="cite_note-1"> <span class="reference-text">These are the directives defined by the standard. The standard does not define behavior for other directives: they might be ignored, have some useful meaning, or make the program ill-formed. Even if otherwise ignored, they are removed from the source code when the preprocessor is done. <span class="t-rev-inl t-until-c23"><span>A common non-standard extension is the directive <code>#warning</code> which emits a user-defined message during compilation.</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span></span> </li> </ol> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.10 Preprocessing directives (p: 117-129) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.10 Preprocessing directives (p: 160-178) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.10 Preprocessing directives (p: 145-162) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.8 PREPROCESSING DIRECTIVES </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="preprocessor/replace#Predefined_macros" title="c/preprocessor/replace">C documentation</a></span> for <span class=""><span>Predefined Macro Symbols</span></span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="symbol_index/macro" title="c/symbol index/macro">C documentation</a></span> for <span class=""><span>Macro Symbol Index</span></span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/preprocessor" title="cpp/preprocessor">C++ documentation</a></span> for <span class=""><span>Preprocessor</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/preprocessor" class="_attribution-link">https://en.cppreference.com/w/c/preprocessor</a> + </p> +</div> diff --git a/devdocs/c/program%2F_exit.html b/devdocs/c/program%2F_exit.html new file mode 100644 index 00000000..4fc7cd21 --- /dev/null +++ b/devdocs/c/program%2F_exit.html @@ -0,0 +1,48 @@ + <h1 id="firstHeading" class="firstHeading">_Exit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99 t-until-c11"> <td><pre data-language="c">void _Exit( int exit_code );</pre></td> <td class="t-dcl-nopad"> </td> <td> +<span class="t-mark-rev t-since-c99">(since C99)</span> <br><span class="t-mark-rev t-until-c11">(until C11)</span> +</td> </tr> <tr class="t-dcl t-since-c11 t-until-c23"> <td> <pre data-language="c">_Noreturn void _Exit( int exit_code );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> <br><span class="t-mark-rev t-until-c23">(until C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">[[noreturn]] void _Exit( int exit_code );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <p>Causes normal program termination to occur without completely cleaning the resources.</p> +<p>Functions passed to <code><a href="at_quick_exit" title="c/program/at quick exit">at_quick_exit()</a></code> or <code><a href="atexit" title="c/program/atexit">atexit()</a></code> are not called. Whether open streams with unwritten buffered data are flushed, open streams are closed, or temporary files are removed is implementation-defined.</p> +<p>If <code>exit_code</code> is <code>0</code> or <code><a href="exit_status" title="c/program/EXIT status">EXIT_SUCCESS</a></code>, an implementation-defined status indicating successful termination is returned to the host environment. If <code>exit_code</code> is <code><a href="exit_status" title="c/program/EXIT status">EXIT_FAILURE</a></code>, an implementation-defined status, indicating <i>unsuccessful</i> termination, is returned. In other cases an implementation-defined status value is returned.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> exit_code </td> <td> - </td> <td> exit status of the program </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdlib.h> +#include <stdio.h> + +/* _Exit does not call functions registered with atexit. */ +void f1(void) +{ + puts("pushed first"); +} + +void f2(void) +{ + puts("pushed second"); +} + +int main(void) +{ + printf("Enter main()\n"); + atexit(f1); + atexit(f2); + fflush(stdout); /* _Exit may not flush unwritten buffered data */ + _Exit(0); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Enter main()</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22.4.5 The _Exit function (p: 256) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.4.5 The _Exit function (p: 352) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.4.4 The _Exit function (p: 316) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="abort" title="c/program/abort"> <span class="t-lines"><span>abort</span></span></a></div> </td> <td> causes abnormal program termination (without cleaning up) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="exit" title="c/program/exit"> <span class="t-lines"><span>exit</span></span></a></div> </td> <td> causes normal program termination with cleaning up <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/program/_Exit" title="cpp/utility/program/ Exit">C++ documentation</a></span> for <code>_Exit</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/program/_Exit" class="_attribution-link">https://en.cppreference.com/w/c/program/_Exit</a> + </p> +</div> diff --git a/devdocs/c/program%2Fabort.html b/devdocs/c/program%2Fabort.html new file mode 100644 index 00000000..8755f11c --- /dev/null +++ b/devdocs/c/program%2Fabort.html @@ -0,0 +1,45 @@ + <h1 id="firstHeading" class="firstHeading">abort</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-until-c11"> <td><pre data-language="c">void abort(void);</pre></td> <td class="t-dcl-nopad"> </td> <td><span class="t-mark-rev t-until-c11">(until C11)</span></td> </tr> <tr class="t-dcl t-since-c11 t-until-c23"> <td> <pre data-language="c">_Noreturn void abort(void);</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> <br><span class="t-mark-rev t-until-c23">(until C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">[[noreturn]] void abort(void);</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <p>Causes abnormal program termination unless <code><a href="sig_types" title="c/program/SIG types">SIGABRT</a></code> is being caught by a signal handler passed to signal and the handler does not return.</p> +<p>Functions passed to <code><a href="atexit" title="c/program/atexit">atexit()</a></code> are not called. Whether open resources such as files are closed is implementation defined. An implementation defined status is returned to the host environment that indicates unsuccessful execution.</p> +<h3 id="Parameters"> Parameters</h3> <p>(none)</p> +<h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="Notes"> Notes</h3> <p>POSIX <a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/abort.html">specifies</a> that the <code>abort()</code> function overrides blocking or ignoring the <code>SIGABRT</code> signal.</p> +<p>Some compiler intrinsics, e.g. <a rel="nofollow" class="external text" href="https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html"><code>__builtin_trap</code></a> (gcc, clang, and icc) or <a rel="nofollow" class="external text" href="https://learn.microsoft.com/en-us/cpp/intrinsics/fastfail"><code>__fastfail</code></a>/<a rel="nofollow" class="external text" href="https://learn.microsoft.com/en-us/cpp/intrinsics/debugbreak"><code>__debugbreak</code></a> (msvc), can be used to terminate the program as fast as possible.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + FILE *fp = fopen("data.txt","r"); + if (fp == NULL) + { + fprintf(stderr, "error opening file data.txt in function main()\n"); + abort(); + } + + /* Normal processing continues here. */ + fclose(fp); + printf("Normal Return\n"); + return 0; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">error opening file data.txt in function main()</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22.4.1 The abort function (p: 255) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.4.1 The abort function (p: 350) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.4.1 The abort function (p: 315) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.4.1 The abort function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="exit" title="c/program/exit"> <span class="t-lines"><span>exit</span></span></a></div> </td> <td> causes normal program termination with cleaning up <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atexit" title="c/program/atexit"> <span class="t-lines"><span>atexit</span></span></a></div> </td> <td> registers a function to be called on <code><a href="exit" title="c/program/exit">exit()</a></code> invocation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="quick_exit" title="c/program/quick exit"> <span class="t-lines"><span>quick_exit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> causes normal program termination without completely cleaning up <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/program/abort" title="cpp/utility/program/abort">C++ documentation</a></span> for <code>abort</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/program/abort" class="_attribution-link">https://en.cppreference.com/w/c/program/abort</a> + </p> +</div> diff --git a/devdocs/c/program%2Fat_quick_exit.html b/devdocs/c/program%2Fat_quick_exit.html new file mode 100644 index 00000000..fd003acf --- /dev/null +++ b/devdocs/c/program%2Fat_quick_exit.html @@ -0,0 +1,45 @@ + <h1 id="firstHeading" class="firstHeading">at_quick_exit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int at_quick_exit( void (*func)(void) );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Registers the function pointed to by <code>func</code> to be called on quick program termination (via <code><a href="quick_exit" title="c/program/quick exit">quick_exit</a></code>).</p> +<p>Calling the function from several threads does not induce a data race. The implementation is guaranteed to support the registration of at least 32 functions. The exact limit is implementation-defined.</p> +<p>The registered functions will not be called on <a href="exit" title="c/program/exit">normal program termination</a>. If a function need to be called in that case, <code><a href="atexit" title="c/program/atexit">atexit</a></code> must be used.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> func </td> <td> - </td> <td> pointer to a function to be called on quick program termination </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>0</code> if the registration succeeds, nonzero value otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdlib.h> +#include <stdio.h> + +void f1(void) +{ + puts("pushed first"); + fflush(stdout); +} + +void f2(void) +{ + puts("pushed second"); +} + +int main(void) +{ + at_quick_exit(f1); + at_quick_exit(f2); + quick_exit(0); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">pushed second +pushed first</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22.4.3 The at_quick_exit function (p: 255) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.4.3 The at_quick_exit function (p: 351) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="abort" title="c/program/abort"> <span class="t-lines"><span>abort</span></span></a></div> </td> <td> causes abnormal program termination (without cleaning up) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="exit" title="c/program/exit"> <span class="t-lines"><span>exit</span></span></a></div> </td> <td> causes normal program termination with cleaning up <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atexit" title="c/program/atexit"> <span class="t-lines"><span>atexit</span></span></a></div> </td> <td> registers a function to be called on <code><a href="exit" title="c/program/exit">exit()</a></code> invocation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="quick_exit" title="c/program/quick exit"> <span class="t-lines"><span>quick_exit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> causes normal program termination without completely cleaning up <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/program/at_quick_exit" title="cpp/utility/program/at quick exit">C++ documentation</a></span> for <code>at_quick_exit</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/program/at_quick_exit" class="_attribution-link">https://en.cppreference.com/w/c/program/at_quick_exit</a> + </p> +</div> diff --git a/devdocs/c/program%2Fatexit.html b/devdocs/c/program%2Fatexit.html new file mode 100644 index 00000000..c9cebb8e --- /dev/null +++ b/devdocs/c/program%2Fatexit.html @@ -0,0 +1,50 @@ + <h1 id="firstHeading" class="firstHeading">atexit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int atexit( void (*func)(void) );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Registers the function pointed to by <code>func</code> to be called on normal program termination (via <code><a href="exit" title="c/program/exit">exit()</a></code> or returning from <code>main()</code>). The functions will be called in reverse order they were registered, i.e. the function registered last will be executed first.</p> +<p>The same function may be registered more than once.</p> +<p><code>atexit</code> is thread-safe: calling the function from several threads does not induce a data race.</p> +<p>The implementation is guaranteed to support the registration of at least <code>32</code> functions. The exact limit is implementation-defined.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> func </td> <td> - </td> <td> pointer to a function to be called on normal program termination </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>0</code> if the registration succeeds, nonzero value otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdlib.h> +#include <stdio.h> + +void f1(void) +{ + puts("f1"); +} + +void f2(void) +{ + puts("f2"); +} + +int main(void) +{ + if ( ! atexit(f1) && ! atexit(f2) && ! atexit(f2) ) + return EXIT_SUCCESS ; + + // atexit registration failed + return EXIT_FAILURE ; + +} // <- if registration was successful calls f2, f2, f1</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">f2 +f2 +f1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22.4.2 The atexit function (p: 255) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.4.2 The atexit function (p: 350) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.4.2 The atexit function (p: 315) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 7.10.4.2 The atexit function (p: 156) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="at_quick_exit" title="c/program/at quick exit"> <span class="t-lines"><span>at_quick_exit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> registers a function to be called on <a href="quick_exit" title="c/program/quick exit"><code>quick_exit</code></a> invocation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/program/atexit" title="cpp/utility/program/atexit">C++ documentation</a></span> for <code>atexit</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/program/atexit" class="_attribution-link">https://en.cppreference.com/w/c/program/atexit</a> + </p> +</div> diff --git a/devdocs/c/program%2Fexit.html b/devdocs/c/program%2Fexit.html new file mode 100644 index 00000000..a7ae5e4f --- /dev/null +++ b/devdocs/c/program%2Fexit.html @@ -0,0 +1,51 @@ + <h1 id="firstHeading" class="firstHeading">exit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-until-c11"> <td><pre data-language="c">void exit( int exit_code );</pre></td> <td class="t-dcl-nopad"> </td> <td><span class="t-mark-rev t-until-c11">(until C11)</span></td> </tr> <tr class="t-dcl t-since-c11 t-until-c23"> <td> <pre data-language="c">_Noreturn void exit( int exit_code );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> <br><span class="t-mark-rev t-until-c23">(until C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">[[noreturn]] void exit( int exit_code );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <p>Causes normal program termination to occur.</p> +<p>Several cleanup steps are performed:</p> +<ul> +<li> functions passed to <code><a href="atexit" title="c/program/atexit">atexit</a></code> are called, in reverse order of registration </li> +<li> all C streams are flushed and closed </li> +<li> files created by <code><a href="../io/tmpfile" title="c/io/tmpfile">tmpfile</a></code> are removed </li> +<li> control is returned to the host environment. If <code>exit_code</code> is zero or <code><a href="exit_status" title="c/program/EXIT status">EXIT_SUCCESS</a></code>, an implementation-defined status indicating successful termination is returned. If <code>exit_code</code> is <code><a href="exit_status" title="c/program/EXIT status">EXIT_FAILURE</a></code>, an implementation-defined status indicating unsuccessful termination is returned. In other cases implementation-defined status value is returned. </li> +</ul> <h3 id="Notes"> Notes</h3> <p>The functions registered with <code><a href="at_quick_exit" title="c/program/at quick exit">at_quick_exit</a></code> are not called.</p> +<p>The behavior is undefined if a program calls <code>exit</code> more than once, or if it calls <code>exit</code> and <code><a href="quick_exit" title="c/program/quick exit">quick_exit</a></code></p> +<p>The behavior is undefined if during a call to a function registered with <code><a href="atexit" title="c/program/atexit">atexit</a></code>, the function exits with <code><a href="longjmp" title="c/program/longjmp">longjmp</a></code>.</p> +<p>Returning from the <a href="../language/main_function" title="c/language/main function">the main function</a>, either by a <code>return</code> statement or by reaching the end of the function, executes <code>exit()</code>, passing the argument of the return statement (or <code>0</code> if implicit return was used) as <code>exit_code</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> exit_code </td> <td> - </td> <td> exit status of the program </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + FILE *fp = fopen("data.txt","r"); + if (fp == NULL) + { + fprintf(stderr, "error opening file data.txt in function main()\n"); + exit( EXIT_FAILURE ); + } + fclose(fp); + printf("Normal Return\n"); + return EXIT_SUCCESS ; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">error opening file data.txt in function main()</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22.4.4 The exit function (p: 256) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.4.4 The exit function (p: 351-352) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.4.3 The exit function (p: 315-316) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.4.3 The exit function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="abort" title="c/program/abort"> <span class="t-lines"><span>abort</span></span></a></div> </td> <td> causes abnormal program termination (without cleaning up) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atexit" title="c/program/atexit"> <span class="t-lines"><span>atexit</span></span></a></div> </td> <td> registers a function to be called on <code>exit()</code> invocation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="quick_exit" title="c/program/quick exit"> <span class="t-lines"><span>quick_exit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> causes normal program termination without completely cleaning up <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/program/exit" title="cpp/utility/program/exit">C++ documentation</a></span> for <code>exit</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/program/exit" class="_attribution-link">https://en.cppreference.com/w/c/program/exit</a> + </p> +</div> diff --git a/devdocs/c/program%2Fexit_status.html b/devdocs/c/program%2Fexit_status.html new file mode 100644 index 00000000..89cd2252 --- /dev/null +++ b/devdocs/c/program%2Fexit_status.html @@ -0,0 +1,41 @@ + <h1 id="firstHeading" class="firstHeading">EXIT_SUCCESS, EXIT_FAILURE</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define EXIT_SUCCESS /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define EXIT_FAILURE /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>The <code>EXIT_SUCCESS</code> and <code>EXIT_FAILURE</code> macros expand into integral expressions that can be used as arguments to the <code><a href="exit" title="c/program/exit">exit</a></code> function (and, therefore, as the values to return from the <a href="../language/main_function" title="c/language/main function">main function</a>), and indicate program execution status.</p> +<table class="t-dsc-begin"> <tr class="t-dsc-hitem"> <th> Constant </th> <th> Explanation </th> +</tr> <tr class="t-dsc"> <td> <code>EXIT_SUCCESS</code> </td> <td> successful execution of a program </td> +</tr> <tr class="t-dsc"> <td> <code>EXIT_FAILURE</code> </td> <td> unsuccessful execution of a program </td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>Both <code>EXIT_SUCCESS</code> and the value zero indicate successful program execution status (see <code><a href="exit" title="c/program/exit">exit</a></code>), although it is not required that <code>EXIT_SUCCESS</code> equals zero.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + FILE *fp = fopen("data.txt","r"); + if (fp == NULL) + { + fprintf(stderr, "fopen() failed in file %s at line # %d", __FILE__,__LINE__); + exit(EXIT_FAILURE); + } + + /* Normal processing continues here. */ + fclose(fp); + printf("Normal Return\n"); + + return EXIT_SUCCESS; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">fopen() failed in file main.cpp at line # 9</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22/3 General utilities <stdlib.h> (p: 248) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22/3 General utilities <stdlib.h> (p: 340) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20/3 General utilities <stdlib.h> (p: 306) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10 General utilities <stdlib.h> </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/program/EXIT_status" title="cpp/utility/program/EXIT status">C++ documentation</a></span> for <code>EXIT_SUCCESS, EXIT_FAILURE</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/program/EXIT_status" class="_attribution-link">https://en.cppreference.com/w/c/program/EXIT_status</a> + </p> +</div> diff --git a/devdocs/c/program%2Fgetenv.html b/devdocs/c/program%2Fgetenv.html new file mode 100644 index 00000000..912fe7b3 --- /dev/null +++ b/devdocs/c/program%2Fgetenv.html @@ -0,0 +1,62 @@ + <h1 id="firstHeading" class="firstHeading">getenv, getenv_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">char *getenv( const char *name );</pre> +</td> <td> (1) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t getenv_s( size_t *restrict len, char *restrict value, + rsize_t valuesz, const char *restrict name );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Searches for an environmental variable with name <code>name</code> in the host-specified environment list and returns a pointer to the string that is associated with the matched environment variable. The set of environmental variables and methods of altering it are implementation-defined.</div> <div class="t-li1"> + This function is not required to be thread-safe. Another call to <code>getenv</code>, as well as a call to the POSIX functions <a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/setenv.html"><code>setenv()</code></a>, <a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/unsetenv.html"><code>unsetenv()</code></a>, and <a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/putenv.html"><code>putenv()</code></a> may invalidate the pointer returned by a previous call or modify the string obtained from a previous call.</div> <div class="t-li1"> + Modifying the string returned by <code>getenv</code> invokes undefined behavior.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that the values of the environment variable is written to the user-provided buffer <code>value</code> (unless null) and the number of bytes written is stored in the user-provided location <code>*len</code> (unless null). If the environment variable is not set in the environment, zero is written to <code>*len</code> (unless null) and <code>'\0'</code> is written to <code>value[0]</code> (unless null). In addition, the following errors are detected at runtime and call the currently installed <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> <code>name</code> is a null pointer </li> +<li> <code>valuesz</code> is greater than <code>RSIZE_MAX</code> </li> +<li> <code>value</code> is a null pointer and <code>valuesz</code> is not zero </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>getenv_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../program" title="c/program"><code><stdlib.h></code></a>.</dd> +</dl> +</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> name </td> <td> - </td> <td> null-terminated character string identifying the name of the environmental variable to look for </td> +</tr> <tr class="t-par"> <td> len </td> <td> - </td> <td> pointer to a user-provided location where <code>getenv_s</code> will store the length of the environment variable </td> +</tr> <tr class="t-par"> <td> value </td> <td> - </td> <td> pointer to a user-provided character array where <code>getenv_s</code> will store the contents of the environment variable </td> +</tr> <tr class="t-par"> <td> valuesz </td> <td> - </td> <td> maximum number of characters that <code>getenv_s</code> is allowed to write to <code>dest</code> (size of the buffer) </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> character string identifying the value of the environmental variable or null pointer if such variable is not found.</div> <div class="t-li1"> +<span class="t-li">2)</span> zero if the environment variable was found, non-zero if it was not found or if a runtime constraint violation occurred. On any error, writes zero to <code>*len</code> (unless <code>len</code> is a null pointer).</div> <h3 id="Notes"> Notes</h3> <p>On POSIX systems, the <a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08">environment variables</a> are also accessible through the global variable <code>environ</code>, declared as <code>extern char **environ;</code> in <code><unistd.h></code>, and through the optional third argument, <code>envp</code>, of <a href="../language/main_function" title="c/language/main function">the main function</a>.</p> +<p>The call to <code>getenv_s</code> with a null pointer for <code>value</code> and zero for <code>valuesz</code> is used to determine the size of the buffer required to hold the entire result.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + const char *name = "PATH"; + const char *env_p = getenv(name); + if (env_p) + printf("Your %s is %s\n", name, env_p); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Your PATH is /home/gamer/.local/bin:/usr/local/bin:/usr/bin:/bin:/usr/share/games</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.22.4.6 The getenv function (p: TBD) </li> +<li> K.3.6.2.1 The getenv_s function (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.22.4.6 The getenv function (p: 256-257) </li> +<li> K.3.6.2.1 The getenv_s function (p: 440-441) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.22.4.6 The getenv function (p: 352-353) </li> +<li> K.3.6.2.1 The getenv_s function (p: 606-607) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.4.5 The getenv function (p: 317) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.4.4 The getenv function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/program/getenv" title="cpp/utility/program/getenv">C++ documentation</a></span> for <code>getenv</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/program/getenv" class="_attribution-link">https://en.cppreference.com/w/c/program/getenv</a> + </p> +</div> diff --git a/devdocs/c/program%2Fjmp_buf.html b/devdocs/c/program%2Fjmp_buf.html new file mode 100644 index 00000000..2ebd106e --- /dev/null +++ b/devdocs/c/program%2Fjmp_buf.html @@ -0,0 +1,20 @@ + <h1 id="firstHeading" class="firstHeading">jmp_buf</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><setjmp.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">typedef /* unspecified */ jmp_buf;</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>The <code>jmp_buf</code> type is an array type suitable for storing information to restore a calling environment. The stored information is sufficient to restore execution at the correct block of the program and invocation of that block. The state of floating-point status flags, or open files, or any other data is not stored in an object of type <code>jmp_buf</code>.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.13/2 Nonlocal jumps <setjmp.h> (p: 191) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.13/2 Nonlocal jumps <setjmp.h> (p: 262) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.13/2 Nonlocal jumps <setjmp.h> (p: 243) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.6 NON-LOCAL JUMPS <setjmp.h> </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="setjmp" title="c/program/setjmp"> <span class="t-lines"><span>setjmp</span></span></a></div> </td> <td> saves the context <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="longjmp" title="c/program/longjmp"> <span class="t-lines"><span>longjmp</span></span></a></div> </td> <td> jumps to specified location <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/program/jmp_buf" title="cpp/utility/program/jmp buf">C++ documentation</a></span> for <code>jmp_buf</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/program/jmp_buf" class="_attribution-link">https://en.cppreference.com/w/c/program/jmp_buf</a> + </p> +</div> diff --git a/devdocs/c/program%2Flongjmp.html b/devdocs/c/program%2Flongjmp.html new file mode 100644 index 00000000..2ccde1dd --- /dev/null +++ b/devdocs/c/program%2Flongjmp.html @@ -0,0 +1,64 @@ + <h1 id="firstHeading" class="firstHeading">longjmp</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><setjmp.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-until-c11"> <td> <pre data-language="c">void longjmp( jmp_buf env, int status );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-until-c11">(until C11)</span> </td> </tr> <tr class="t-dcl t-since-c11 t-until-c23"> <td> <pre data-language="c">_Noreturn void longjmp( jmp_buf env, int status );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> <br><span class="t-mark-rev t-until-c23">(until C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">[[noreturn]] void longjmp( jmp_buf env, int status );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <p>Loads the execution context <code>env</code> saved by a previous call to <code><a href="setjmp" title="c/program/setjmp">setjmp</a></code>. This function does not return. Control is transferred to the call site of the macro <code><a href="setjmp" title="c/program/setjmp">setjmp</a></code> that set up <code>env</code>. That <code><a href="setjmp" title="c/program/setjmp">setjmp</a></code> then returns the value, passed as the <code>status</code>.</p> +<p>If the function that called <code><a href="setjmp" title="c/program/setjmp">setjmp</a></code> has exited (whether by return or by a different <code>longjmp</code> higher up the stack), the behavior is undefined. In other words, only long jumps up the call stack are allowed.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <p>Jumping across threads (if the function that called <code>setjmp</code> was executed by another thread) is also undefined behavior.</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>If when <code><a href="setjmp" title="c/program/setjmp">setjmp</a></code> was called, a <a href="../language/array" title="c/language/array">VLA</a> or another <a href="../language/declarations" title="c/language/declarations">variably-modified type</a> variable was in scope and control left that scope, <code>longjmp</code> to that <code>setjmp</code> invokes undefined behavior even if control remained within the function.</p> +<p>On the way up the stack, <code>longjmp</code> does not deallocate any VLAs, memory leaks may occur if their lifetimes are terminated in this way:</p> +<div class="c source-c"><pre data-language="c">void g(int n) +{ + int a[n]; // a may remain allocated + h(n); // does not return +} +void h(int n) +{ + int b[n]; // b may remain allocated + longjmp(buf, 2); // might cause a memory leak for h's b and g's a +}</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> env </td> <td> - </td> <td> variable referring to the execution state of the program saved by <code><a href="setjmp" title="c/program/setjmp">setjmp</a></code> </td> +</tr> <tr class="t-par"> <td> status </td> <td> - </td> <td> the value to return from <code><a href="setjmp" title="c/program/setjmp">setjmp</a></code>. If it is equal to <code>0</code>, <code>1</code> is used instead </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="Notes"> Notes</h3> <p><code>longjmp</code> is intended for handling unexpected error conditions where the function cannot return meaningfully. This is similar to exception handling in other programming languages.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <setjmp.h> +#include <stdnoreturn.h> + +jmp_buf my_jump_buffer; + +noreturn void foo(int status) +{ + printf("foo(%d) called\n", status); + longjmp(my_jump_buffer, status + 1); // will return status+1 out of setjmp +} + +int main(void) +{ + volatile int count = 0; // modified local vars in setjmp scope must be volatile + if (setjmp(my_jump_buffer) != 5) // compare against constant in an if + foo(++count); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">foo(1) called +foo(2) called +foo(3) called +foo(4) called</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.13.2.1 The longjmp macro (p: 191-192) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.13.2.1 The longjmp macro (p: 263-264) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.13.2.1 The longjmp macro (p: 244-245) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.6.2.1 The longjmp function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="setjmp" title="c/program/setjmp"> <span class="t-lines"><span>setjmp</span></span></a></div> </td> <td> saves the context <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/program/longjmp" title="cpp/utility/program/longjmp">C++ documentation</a></span> for <code>longjmp</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/program/longjmp" class="_attribution-link">https://en.cppreference.com/w/c/program/longjmp</a> + </p> +</div> diff --git a/devdocs/c/program%2Fquick_exit.html b/devdocs/c/program%2Fquick_exit.html new file mode 100644 index 00000000..2527ca17 --- /dev/null +++ b/devdocs/c/program%2Fquick_exit.html @@ -0,0 +1,52 @@ + <h1 id="firstHeading" class="firstHeading">quick_exit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11 t-until-c23"> <td><pre data-language="c">_Noreturn void quick_exit( int exit_code );</pre></td> <td class="t-dcl-nopad"> </td> <td> +<span class="t-mark-rev t-since-c11">(since C11)</span> <br><span class="t-mark-rev t-until-c23">(until C23)</span> +</td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">[[noreturn]] void quick_exit( int exit_code );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <p>Causes normal program termination to occur without completely cleaning the resources.</p> +<p>Functions passed to <code><a href="at_quick_exit" title="c/program/at quick exit">at_quick_exit</a></code> are called in reverse order of their registration. After calling the registered functions, calls <code><a href="http://en.cppreference.com/w/c/program/_Exit"><span class="kw489">_Exit</span></a><span class="br0">(</span>exit_code<span class="br0">)</span></code>.</p> +<p>Functions passed to <code><a href="atexit" title="c/program/atexit">atexit</a></code> or signal handlers passed to <code><a href="signal" title="c/program/signal">signal</a></code> are not called.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> exit_code </td> <td> - </td> <td> exit status of the program </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdlib.h> +#include <stdio.h> + +void f1(void) +{ + puts("pushed first"); + fflush(stdout); +} + +void f2(void) +{ + puts("pushed second"); +} + +void f3(void) +{ + puts("won't be called"); +} + +int main(void) +{ + at_quick_exit(f1); + at_quick_exit(f2); + atexit(f3); + quick_exit(0); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">pushed second +pushed first</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22.4.7 The quick_exit function (p: 257) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.4.7 The quick_exit function (p: 353) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="abort" title="c/program/abort"> <span class="t-lines"><span>abort</span></span></a></div> </td> <td> causes abnormal program termination (without cleaning up) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atexit" title="c/program/atexit"> <span class="t-lines"><span>atexit</span></span></a></div> </td> <td> registers a function to be called on <code><a href="exit" title="c/program/exit">exit()</a></code> invocation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="at_quick_exit" title="c/program/at quick exit"> <span class="t-lines"><span>at_quick_exit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> registers a function to be called on <strong class="selflink"><code>quick_exit</code></strong> invocation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/program/quick_exit" title="cpp/utility/program/quick exit">C++ documentation</a></span> for <code>quick_exit</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/program/quick_exit" class="_attribution-link">https://en.cppreference.com/w/c/program/quick_exit</a> + </p> +</div> diff --git a/devdocs/c/program%2Fraise.html b/devdocs/c/program%2Fraise.html new file mode 100644 index 00000000..5aa1e9e2 --- /dev/null +++ b/devdocs/c/program%2Fraise.html @@ -0,0 +1,43 @@ + <h1 id="firstHeading" class="firstHeading">raise</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><signal.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int raise( int sig );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Sends signal sig to the program. The signal handler, specified using <code><a href="signal" title="c/program/signal">signal()</a></code>, is invoked.</p> +<p>If the user-defined signal handling strategy is not set using <code><a href="signal" title="c/program/signal">signal()</a></code> yet, it is implementation-defined whether the signal will be ignored or default handler will be invoked.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> sig </td> <td> - </td> <td> the signal to be sent. It can be an implementation-defined value or one of the following values: <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="sig_types" title="c/program/SIG types"> <span class="t-lines"><span>SIGABRT</span><span>SIGFPE</span><span>SIGILL</span><span>SIGINT</span><span>SIGSEGV</span><span>SIGTERM</span></span></a></div> </td> <td> defines signal types <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>0</code> upon success, non-zero value on failure.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <signal.h> +#include <stdio.h> + +void signal_handler(int signal) +{ + printf("Received signal %d\n", signal); +} + +int main(void) +{ + // Install a signal handler. + signal(SIGTERM, signal_handler); + + printf("Sending signal %d\n", SIGTERM); + raise(SIGTERM); + printf("Exit main()\n"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Sending signal 15 +Received signal 15 +Exit main()</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.14.2.1 The raise function (p: 194-195) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.14.2.1 The raise function (p: 267) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.14.2.1 The raise function (p: 248) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.7.2.1 The raise function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="signal" title="c/program/signal"> <span class="t-lines"><span>signal</span></span></a></div> </td> <td> sets a signal handler for particular signal <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/program/raise" title="cpp/utility/program/raise">C++ documentation</a></span> for <code>raise</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/program/raise" class="_attribution-link">https://en.cppreference.com/w/c/program/raise</a> + </p> +</div> diff --git a/devdocs/c/program%2Fsetjmp.html b/devdocs/c/program%2Fsetjmp.html new file mode 100644 index 00000000..b0fedd15 --- /dev/null +++ b/devdocs/c/program%2Fsetjmp.html @@ -0,0 +1,56 @@ + <h1 id="firstHeading" class="firstHeading">setjmp</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><setjmp.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define setjmp(env) /* implementation-defined */</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Saves the current execution context into a variable <code>env</code> of type <code><a href="jmp_buf" title="c/program/jmp buf">jmp_buf</a></code>. This variable can later be used to restore the current execution context by <code><a href="longjmp" title="c/program/longjmp">longjmp</a></code> function. That is, when a call to <code><a href="longjmp" title="c/program/longjmp">longjmp</a></code> function is made, the execution continues at the particular call site that constructed the <code><a href="jmp_buf" title="c/program/jmp buf">jmp_buf</a></code> variable passed to <code><a href="longjmp" title="c/program/longjmp">longjmp</a></code>. In that case <code>setjmp</code> returns the value passed to <code><a href="longjmp" title="c/program/longjmp">longjmp</a></code>.</p> +<p>The invocation of <code>setjmp</code> must appear only in one of the following contexts:</p> +<ol> +<li> The entire controlling expression of <a href="../language/if" title="c/language/if"><code>if</code></a>, <a href="../language/switch" title="c/language/switch"><code>switch</code></a>, <a href="../language/while" title="c/language/while"><code>while</code></a>, <a href="../language/do" title="c/language/do"><code>do-while</code></a>, <a href="../language/for" title="c/language/for"><code>for</code></a>.<div class="c source-c"><pre data-language="c">switch(setjmp(env)) { // ...</pre></div> </li> +<li> One operand of a relational or equality operator with the other operand an integer constant expression, with the resulting expression being the entire controlling expression of <a href="../language/if" title="c/language/if"><code>if</code></a>, <a href="../language/switch" title="c/language/switch"><code>switch</code></a>, <a href="../language/while" title="c/language/while"><code>while</code></a>, <a href="../language/do" title="c/language/do"><code>do-while</code></a>, <a href="../language/for" title="c/language/for"><code>for</code></a>.<div class="c source-c"><pre data-language="c">if(setjmp(env) > 10) { // ...</pre></div> </li> +<li> The operand of a unary ! operator with the resulting expression being the entire controlling expression of <a href="../language/if" title="c/language/if"><code>if</code></a>, <a href="../language/switch" title="c/language/switch"><code>switch</code></a>, <a href="../language/while" title="c/language/while"><code>while</code></a>, <a href="../language/do" title="c/language/do"><code>do-while</code></a>, <a href="../language/for" title="c/language/for"><code>for</code></a>.<div class="c source-c"><pre data-language="c">while(!setjmp(env)) { // ...</pre></div> </li> +<li> The entire expression of an <a href="../language/statements#Expression_statements" title="c/language/statements">expression statement</a> (possibly cast to <code>void</code>).<div class="c source-c"><pre data-language="c">setjmp(env);</pre></div> </li> +</ol> <p>If <code>setjmp</code> appears in any other context, the behavior is undefined.</p> +<p>Upon return to the scope of <code>setjmp</code>:</p> +<ul> +<li> all accessible objects, floating-point status flags, and other components of the abstract machine have the same values as they had when <code><a href="longjmp" title="c/program/longjmp">longjmp</a></code> was executed, </li> +<li> except for the non-<a href="../language/volatile" title="c/language/volatile"><code>volatile</code></a> local variables in the function containing the invocation of <code>setjmp</code>, whose values are indeterminate if they have been changed since the <code>setjmp</code> invocation. </li> +</ul> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> env </td> <td> - </td> <td> variable to save the execution state of the program to. </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>0</code> if the macro was called by the original code and the execution context was saved to <code>env</code>.</p> +<p>Non-zero value if a non-local jump was just performed. The return value is the same as passed to <code><a href="longjmp" title="c/program/longjmp">longjmp</a></code>.</p> +<h3 id="Notes"> Notes</h3> <p>Above requirements forbid using return value of <code>setjmp</code> in data flow (e.g. to initialize or assign an object with it). The return value can only be either used in control flow or discarded.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <setjmp.h> +#include <stdnoreturn.h> + +jmp_buf my_jump_buffer; + +noreturn void foo(int status) +{ + printf("foo(%d) called\n", status); + longjmp(my_jump_buffer, status + 1); // will return status+1 out of setjmp +} + +int main(void) +{ + volatile int count = 0; // modified local vars in setjmp scope must be volatile + if (setjmp(my_jump_buffer) != 5) // compare against constant in an if + foo(++count); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">foo(1) called +foo(2) called +foo(3) called +foo(4) called</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.13.1.1 The setjmp macro (p: 191) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.13.1.1 The setjmp macro (p: 262-263) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.13.1.1 The setjmp macro (p: 243-244) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.6.1 The setjmp macro </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="longjmp" title="c/program/longjmp"> <span class="t-lines"><span>longjmp</span></span></a></div> </td> <td> jumps to specified location <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/program/setjmp" title="cpp/utility/program/setjmp">C++ documentation</a></span> for <code>setjmp</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/program/setjmp" class="_attribution-link">https://en.cppreference.com/w/c/program/setjmp</a> + </p> +</div> diff --git a/devdocs/c/program%2Fsig_atomic_t.html b/devdocs/c/program%2Fsig_atomic_t.html new file mode 100644 index 00000000..f791b620 --- /dev/null +++ b/devdocs/c/program%2Fsig_atomic_t.html @@ -0,0 +1,41 @@ + <h1 id="firstHeading" class="firstHeading">sig_atomic_t</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><signal.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">typedef /* unspecified */ sig_atomic_t;</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>An integer type which can be accessed as an atomic entity even in the presence of asynchronous interrupts made by signals.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <signal.h> +#include <stdio.h> + +volatile sig_atomic_t gSignalStatus = 0; + +void signal_handler(int status) +{ + gSignalStatus = status; +} + +int main(void) +{ + /* Install a signal handler. */ + signal(SIGINT, signal_handler); + + printf("SignalValue: %d\n", gSignalStatus); + printf("Sending signal: %d\n", SIGINT); + raise(SIGINT); + printf("SignalValue: %d\n", gSignalStatus); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">SignalValue: 0 +Sending signal: 2 +SignalValue: 2</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.14/2 Signal handling <signal.h> (p: 194-195) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.14/2 Signal handling <signal.h> (p: 265) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.14/2 Signal handling <signal.h> (p: 246) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.7 SIGNAL HANDLING <signal.h> </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="signal" title="c/program/signal"> <span class="t-lines"><span>signal</span></span></a></div> </td> <td> sets a signal handler for particular signal <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/program/sig_atomic_t" title="cpp/utility/program/sig atomic t">C++ documentation</a></span> for <code>sig_atomic_t</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/program/sig_atomic_t" class="_attribution-link">https://en.cppreference.com/w/c/program/sig_atomic_t</a> + </p> +</div> diff --git a/devdocs/c/program%2Fsig_err.html b/devdocs/c/program%2Fsig_err.html new file mode 100644 index 00000000..5e2118d6 --- /dev/null +++ b/devdocs/c/program%2Fsig_err.html @@ -0,0 +1,49 @@ + <h1 id="firstHeading" class="firstHeading">SIG_ERR</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><signal.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define SIG_ERR /* implementation defined */</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>A value of type <code>void (*)(int)</code>. When returned by <code><a href="signal" title="c/program/signal">signal</a></code>, indicates that an error has occurred.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> +#include <signal.h> + +void signal_handler(int sig) +{ + printf("Received signal: %d\n", sig); +} + +int main(void) +{ + /* Install a signal handler. */ + if (signal(SIGTERM, signal_handler) == SIG_ERR) + { + printf("Error while installing a signal handler.\n"); + exit(EXIT_FAILURE); + } + + printf("Sending signal: %d\n", SIGTERM); + if (raise(SIGTERM) != 0) + { + printf("Error while raising the SIGTERM signal.\n"); + exit(EXIT_FAILURE); + } + + printf("Exit main()\n"); + return EXIT_SUCCESS; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Sending signal: 15 +Received signal: 15 +Exit main()</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.14/3 Signal handling <signal.h> (p: 194) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.14/3 Signal handling <signal.h> (p: 265) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.14/3 Signal handling <signal.h> (p: 246) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.7 SIGNAL HANDLING <signal.h> </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="signal" title="c/program/signal"> <span class="t-lines"><span>signal</span></span></a></div> </td> <td> sets a signal handler for particular signal <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/program/SIG_ERR" title="cpp/utility/program/SIG ERR">C++ documentation</a></span> for <code>SIG_ERR</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/program/SIG_ERR" class="_attribution-link">https://en.cppreference.com/w/c/program/SIG_ERR</a> + </p> +</div> diff --git a/devdocs/c/program%2Fsig_strategies.html b/devdocs/c/program%2Fsig_strategies.html new file mode 100644 index 00000000..f4a8f245 --- /dev/null +++ b/devdocs/c/program%2Fsig_strategies.html @@ -0,0 +1,41 @@ + <h1 id="firstHeading" class="firstHeading">SIG_DFL, SIG_IGN</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><signal.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define SIG_DFL /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define SIG_IGN /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>The <code>SIG_DFL</code> and <code>SIG_IGN</code> macros expand into integral expressions that are not equal to an address of any function. The macros define signal handling strategies for <code><a href="http://en.cppreference.com/w/c/program/signal"><span class="kw497">signal</span></a><span class="br0">(</span><span class="br0">)</span></code> function.</p> +<table class="t-dsc-begin"> <tr class="t-dsc-hitem"> <th> Constant </th> <th> Explanation </th> +</tr> <tr class="t-dsc"> <td> <code>SIG_DFL</code> </td> <td> default signal handling </td> +</tr> <tr class="t-dsc"> <td> <code>SIG_IGN</code> </td> <td> signal is ignored </td> +</tr> </table> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <signal.h> +#include <stdio.h> + +int main(void) +{ + /* using the default signal handler */ + raise(SIGTERM); + printf("Exit main()\n"); /* never reached */ +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">(none)</pre></div> </div> <h3 id="Example_2"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <signal.h> +#include <stdio.h> + +int main(void) +{ + /* ignoring the signal */ + signal(SIGTERM, SIG_IGN); + raise(SIGTERM); + printf("Exit main()\n"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Exit main()</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.14/3 Signal handling <signal.h> (p: 193) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.14/3 Signal handling <signal.h> (p: 265) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.14/3 Signal handling <signal.h> (p: 246) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.7 SIGNAL HANDLING <signal.h> </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/program/SIG_strategies" title="cpp/utility/program/SIG strategies">C++ documentation</a></span> for <code>SIG_DFL, SIG_IGN</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/program/SIG_strategies" class="_attribution-link">https://en.cppreference.com/w/c/program/SIG_strategies</a> + </p> +</div> diff --git a/devdocs/c/program%2Fsig_types.html b/devdocs/c/program%2Fsig_types.html new file mode 100644 index 00000000..12f7b29f --- /dev/null +++ b/devdocs/c/program%2Fsig_types.html @@ -0,0 +1,32 @@ + <h1 id="firstHeading" class="firstHeading">SIGTERM, SIGSEGV, SIGINT, SIGILL, SIGABRT, SIGFPE</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><signal.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define SIGTERM /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define SIGSEGV /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define SIGINT /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define SIGILL /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define SIGABRT /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define SIGFPE /*implementation defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Each of the above macro constants expands to an integer constant expression with distinct values, which represent different signals sent to the program.</p> +<table class="t-dsc-begin"> <tr class="t-dsc-hitem"> <th> Constant </th> <th> Explanation </th> +</tr> <tr class="t-dsc"> <td> <code>SIGTERM</code> </td> <td> termination request, sent to the program </td> +</tr> <tr class="t-dsc"> <td> <code>SIGSEGV</code> </td> <td> invalid memory access (segmentation fault) </td> +</tr> <tr class="t-dsc"> <td> <code>SIGINT</code> </td> <td> external interrupt, usually initiated by the user </td> +</tr> <tr class="t-dsc"> <td> <code>SIGILL</code> </td> <td> invalid program image, such as invalid instruction </td> +</tr> <tr class="t-dsc"> <td> <code>SIGABRT</code> </td> <td> abnormal termination condition, as is e.g. initiated by <code><a href="abort" title="c/program/abort">abort()</a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>SIGFPE</code> </td> <td> erroneous arithmetic operation such as divide by zero </td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.14/3 Signal handling <signal.h> (p: 193) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.14/3 Signal handling <signal.h> (p: 265) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.14/3 Signal handling <signal.h> (p: 246) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.7 SIGNAL HANDLING <signal.h> </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="signal" title="c/program/signal"> <span class="t-lines"><span>signal</span></span></a></div> </td> <td> sets a signal handler for particular signal <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="raise" title="c/program/raise"> <span class="t-lines"><span>raise</span></span></a></div> </td> <td> runs the signal handler for particular signal <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/program/SIG_types" title="cpp/utility/program/SIG types">C++ documentation</a></span> for <span class=""><span>signal types</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/program/SIG_types" class="_attribution-link">https://en.cppreference.com/w/c/program/SIG_types</a> + </p> +</div> diff --git a/devdocs/c/program%2Fsignal.html b/devdocs/c/program%2Fsignal.html new file mode 100644 index 00000000..4dfb42f4 --- /dev/null +++ b/devdocs/c/program%2Fsignal.html @@ -0,0 +1,78 @@ + <h1 id="firstHeading" class="firstHeading">signal</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><signal.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">void (*signal( int sig, void (*handler) (int))) (int);</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Sets the error handler for signal <code>sig</code>. The signal handler can be set so that default handling will occur, signal is ignored, or a user-defined function is called.</p> +<p>When signal handler is set to a function and a signal occurs, it is implementation defined whether <code>signal<span class="br0">(</span>sig, <a href="http://en.cppreference.com/w/c/program/SIG_strategies"><span class="kw499">SIG_DFL</span></a><span class="br0">)</span></code> will be executed immediately before the start of signal handler. Also, the implementation can prevent some implementation-defined set of signals from occurring while the signal handler runs.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> sig </td> <td> - </td> <td> the signal to set the signal handler to. It can be an implementation-defined value or one of the following values: <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="sig_types" title="c/program/SIG types"> <span class="t-lines"><span>SIGABRT</span><span>SIGFPE</span><span>SIGILL</span><span>SIGINT</span><span>SIGSEGV</span><span>SIGTERM</span></span></a></div> </td> <td> defines signal types <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> </td> +</tr> <tr class="t-par"> <td> handler </td> <td> - </td> <td> the signal handler. This must be one of the following: <ul> +<li> +<code><a href="sig_strategies" title="c/program/SIG strategies">SIG_DFL</a></code> macro. The signal handler is set to default signal handler. </li> +<li> +<code><a href="sig_strategies" title="c/program/SIG strategies">SIG_IGN</a></code> macro. The signal is ignored. </li> +<li>pointer to a function. The signature of the function must be equivalent to the following: </li> +</ul> <table class="t-dcl-begin"> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">void fun(int sig);</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Previous signal handler on success or <code><a href="sig_err" title="c/program/SIG ERR">SIG_ERR</a></code> on failure (setting a signal handler can be disabled on some implementations).</p> +<h3 id="Signal_handler"> Signal handler</h3> <p>The following limitations are imposed on the user-defined function that is installed as a signal handler.</p> +<p>If the user defined function returns when handling <code><a href="sig_types" title="c/program/SIG types">SIGFPE</a></code>, <code><a href="sig_types" title="c/program/SIG types">SIGILL</a></code> or <code><a href="sig_types" title="c/program/SIG types">SIGSEGV</a></code>, the behavior is undefined.</p> +<p>If the signal handler is called as a result of <code><a href="abort" title="c/program/abort">abort</a></code> or <code><a href="raise" title="c/program/raise">raise</a></code>, the behavior is undefined if the signal handler calls <code><a href="raise" title="c/program/raise">raise</a></code>.</p> +<p>If the signal handler is called NOT as a result of <code><a href="abort" title="c/program/abort">abort</a></code> or <code><a href="raise" title="c/program/raise">raise</a></code> (in other words, the signal handler is <i>asynchronous</i>), the behavior is undefined if</p> +<ul> +<li> the signal handler calls any function within the standard library, except </li> +<ul> +<li> <code><a href="abort" title="c/program/abort">abort</a></code> </li> +<li> <code><a href="_exit" title="c/program/ Exit">_Exit</a></code> </li> +<li> <code><a href="quick_exit" title="c/program/quick exit">quick_exit</a></code> </li> +<li> <code>signal</code> with the first argument being the number of the signal currently handled (async handler can re-register itself, but not other signals). </li> +<li> atomic functions from <a href="../thread#Atomic_operations" title="c/thread"><code><stdatomic.h></code></a> if the atomic arguments are lock-free </li> +<li> <code><a href="../atomic/atomic_is_lock_free" title="c/atomic/atomic is lock free">atomic_is_lock_free</a></code> (with any kind of atomic arguments) </li> +</ul> +<li> the signal handler refers to any object with static <span class="t-rev-inl t-since-c11"><span>or thread-local</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> <a href="../language/storage_duration" title="c/language/storage duration">storage duration</a> <span class="t-rev-inl t-since-c11"><span>that is not a lock-free <a href="../language/atomic" title="c/language/atomic">atomic</a></span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> other than by assigning to a static <code><span class="kw4">volatile</span> <a href="http://en.cppreference.com/w/c/program/sig_atomic_t"><span class="kw498">sig_atomic_t</span></a></code>. </li> +</ul> <p>On entry to the signal handler, the state of the floating-point environment and the values of all objects is unspecified, except for</p> +<ul> +<li> objects of type <code><span class="kw4">volatile</span> <a href="http://en.cppreference.com/w/c/program/sig_atomic_t"><span class="kw498">sig_atomic_t</span></a></code> </li> +<li> objects of lock-free atomic types <span class="t-mark-rev t-since-c11">(since C11)</span> </li> +<li> side effects made visible through <code><a href="../atomic/atomic_signal_fence" title="c/atomic/atomic signal fence">atomic_signal_fence</a></code> <span class="t-mark-rev t-since-c11">(since C11)</span> </li> +</ul> <p>On return from a signal handler, the value of any object modified by the signal handler that is not <code><span class="kw4">volatile</span> <a href="http://en.cppreference.com/w/c/program/sig_atomic_t"><span class="kw498">sig_atomic_t</span></a></code> or lock-free atomic<span class="t-mark-rev t-since-c11">(since C11)</span> is undefined.</p> +<p>The behavior is undefined if <code>signal</code> is used in a multithreaded program. It is not required to be thread-safe.</p> +<h3 id="Notes"> Notes</h3> <p>POSIX requires that <code>signal</code> is thread-safe, and <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_04">specifies a list of async-signal-safe library functions</a> that may be called from any signal handler.</p> +<p>Besides <code>abort</code> and <code>raise</code>, POSIX specifies that <code>kill</code>, <code>pthread_kill</code>, and <code>sigqueue</code> generate synchronous signals.</p> +<p>POSIX recommends <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/sigaction.html"><code>sigaction</code></a> instead of <code>signal</code>, due to its underspecified behavior and significant implementation variations, regarding signal delivery while a signal handler is executed.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <signal.h> +#include <stdio.h> + +volatile sig_atomic_t gSignalStatus; + +void signal_handler(int signal) +{ + gSignalStatus = signal; +} + +int main(void) +{ + signal(SIGINT, signal_handler); + + printf("SignalValue: %d\n", gSignalStatus); + printf("Sending signal: %d\n", SIGINT); + raise(SIGINT); + printf("SignalValue: %d\n", gSignalStatus); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">SignalValue: 0 +Sending signal: 2 +SignalValue: 2</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.14.1.1 The signal function (p: 193-194) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.14.1.1 The signal function (p: 266-267) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.14.1.1 The signal function (p: 247-248) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.7.1.1 The signal function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="raise" title="c/program/raise"> <span class="t-lines"><span>raise</span></span></a></div> </td> <td> runs the signal handler for particular signal <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/program/signal" title="cpp/utility/program/signal">C++ documentation</a></span> for <code>signal</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/program/signal" class="_attribution-link">https://en.cppreference.com/w/c/program/signal</a> + </p> +</div> diff --git a/devdocs/c/program%2Fsystem.html b/devdocs/c/program%2Fsystem.html new file mode 100644 index 00000000..40e60354 --- /dev/null +++ b/devdocs/c/program%2Fsystem.html @@ -0,0 +1,33 @@ + <h1 id="firstHeading" class="firstHeading">system</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int system( const char *command );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Calls the host environment's command processor with the parameter <code>command</code>. Returns an implementation-defined value (usually the value that the invoked program returns).</p> +<p>If command is a null pointer, checks if the host environment has a command processor and returns a nonzero value if and only if the command processor exists.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> command </td> <td> - </td> <td> character string identifying the command to be run in the command processor. If a null pointer is given, command processor is checked for existence </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Implementation-defined value. If <code>command</code> is a null pointer, returns a nonzero value if and only if the command processor exists.</p> +<h3 id="Notes"> Notes</h3> <p>On POSIX systems, the return value can be decomposed using <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/wait.html"><code>WEXITSTATUS</code> and <code>WSTOPSIG</code></a>.</p> +<p>The related POSIX function <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/popen.html">popen</a> makes the output generated by <code>command</code> available to the caller.</p> +<h3 id="Example"> Example</h3> <p>In this example there is a system call of the unix command <b>date +%A</b> and a system call to (possibly installed) <b>gcc</b> compiler with command-line argument (<i>--version</i>):</p> +<div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdlib.h> + +int main(void) { + system("date +%A"); + system("gcc --version"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Wednesday +gcc (GCC) 11.2.0 +...</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22.4.8 The system function (p: 257) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.4.8 The system function (p: 353-354) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.4.6 The system function (p: 317) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.4.5 The system function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/program/system" title="cpp/utility/program/system">C++ documentation</a></span> for <code>system</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/program/system" class="_attribution-link">https://en.cppreference.com/w/c/program/system</a> + </p> +</div> diff --git a/devdocs/c/program%2Funreachable.html b/devdocs/c/program%2Funreachable.html new file mode 100644 index 00000000..09e33e03 --- /dev/null +++ b/devdocs/c/program%2Funreachable.html @@ -0,0 +1,79 @@ + <h1 id="firstHeading" class="firstHeading">unreachable</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stddef.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">#define unreachable() /* see below */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <p>The function-like macro <code>unreachable</code> expands to a <code>void</code> expression. Executing <code>unreachable()</code> results in <a href="../language/behavior" title="c/language/behavior">undefined behavior</a>.</p> +<p>An implementation may use this to optimize impossible code branches away (typically, in optimized builds) or to trap them to prevent further execution (typically, in debug builds).</p> +<h3 id="Possible_implementation"> Possible implementation</h3> <table class="eq-fun-cpp-table"> <tr> <td> <div class="c source-c"><pre data-language="c">// Uses compiler specific extensions if possible. +#ifdef __GNUC__ // GCC, Clang, ICC + +#define unreachable() (__builtin_unreachable()) + +#elifdef _MSC_VER // MSVC + +#define unreachable() (__assume(false)) + +#else +// Even if no extension is used, undefined behavior is still raised by +// the empty function body and the noreturn attribute. + +// The external definition of unreachable_impl must be emitted in a separated TU +// due to the rule for inline functions in C. + +[[noreturn]] inline void unreachable_impl() {} +#define unreachable() (unreachable_impl()) + +#endif</pre></div> </td> +</tr> +</table> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <assert.h> +#include <stddef.h> +#include <stdint.h> +#include <stdlib.h> + +struct Color { uint8_t r, g, b, a; }; +struct ColorSpan { struct Color* data; size_t size; }; + +// Assume that only restricted set of texture caps is supported. +struct ColorSpan allocate_texture(size_t xy) +{ + switch (xy) + { + case 128: [[fallthrough]]; + case 256: [[fallthrough]]; + case 512: + { + /* ... */ + struct ColorSpan result = { + .data = malloc(xy * xy * sizeof(struct Color)), + .size = xy * xy + }; + if (!result.data) + result.size = 0; + return result; + } + default: + unreachable(); + } +} + +int main(void) +{ + struct ColorSpan tex = allocate_texture(128); // OK + assert(tex.size == 128 * 128); + + struct ColorSpan badtex = allocate_texture(32); // Undefined behavior + + free(badtex.data); + free(tex.data); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Segmentation fault</pre></div> </div> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/unreachable" title="cpp/utility/unreachable">C++ documentation</a></span> for <code>unreachable</code> </td> +</tr> </table> <h3 id="External_Links"> External Links</h3> <table> <tr style="vertical-align:top;"> <td>1. </td> <td> +<a rel="nofollow" class="external text" href="https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html#index-_005f_005fbuiltin_005funreachable">GCC docs: <code>__builtin_unreachable</code></a> </td> +</tr> <tr style="vertical-align:top;"> <td>2. </td> <td> +<a rel="nofollow" class="external text" href="https://clang.llvm.org/docs/LanguageExtensions.html#builtin-unreachable">Clang docs: <code>__builtin_unreachable</code></a> </td> +</tr> <tr style="vertical-align:top;"> <td>3. </td> <td> +<a rel="nofollow" class="external text" href="https://docs.microsoft.com/en-us/cpp/intrinsics/assume">MSVC docs: <code>__assume</code></a> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/program/unreachable" class="_attribution-link">https://en.cppreference.com/w/c/program/unreachable</a> + </p> +</div> diff --git a/devdocs/c/program.html b/devdocs/c/program.html new file mode 100644 index 00000000..95464568 --- /dev/null +++ b/devdocs/c/program.html @@ -0,0 +1,73 @@ + <h1 id="firstHeading" class="firstHeading">Program support utilities</h1> <h3 id="Program_termination"> Program termination</h3> <p>The following functions manage program termination and resources cleanup.</p> +<table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdlib.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="program/abort" title="c/program/abort"> <span class="t-lines"><span>abort</span></span></a></div> </td> <td> causes abnormal program termination (without cleaning up) <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="program/exit" title="c/program/exit"> <span class="t-lines"><span>exit</span></span></a></div> </td> <td> causes normal program termination with cleaning up <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="program/quick_exit" title="c/program/quick exit"> <span class="t-lines"><span>quick_exit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> causes normal program termination without completely cleaning up <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="program/_exit" title="c/program/ Exit"> <span class="t-lines"><span>_Exit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> causes normal program termination without cleaning up <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="program/atexit" title="c/program/atexit"> <span class="t-lines"><span>atexit</span></span></a></div> </td> <td> registers a function to be called on <code><a href="program/exit" title="c/program/exit">exit()</a></code> invocation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="program/at_quick_exit" title="c/program/at quick exit"> <span class="t-lines"><span>at_quick_exit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> registers a function to be called on <a href="program/quick_exit" title="c/program/quick exit"><code>quick_exit</code></a> invocation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="program/exit_status" title="c/program/EXIT status"> <span class="t-lines"><span>EXIT_SUCCESS</span><span>EXIT_FAILURE</span></span></a></div> </td> <td> indicates program execution execution status <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> <h3 id="Unreachable_control_flow"> Unreachable control flow</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stddef.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="program/unreachable" title="c/program/unreachable"> <span class="t-lines"><span>unreachable</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> marks unreachable point of execution <br> <span class="t-mark">(function macro)</span> </td> +</tr> </table> <h3 id="Communicating_with_the_environment"> Communicating with the environment</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdlib.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="program/system" title="c/program/system"> <span class="t-lines"><span>system</span></span></a></div> </td> <td> calls the host environment's command processor <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="program/getenv" title="c/program/getenv"> <span class="t-lines"><span>getenv</span><span>getenv_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> access to the list of environment variables <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <h3 id="Signals"> Signals</h3> <p>Several functions and macro constants for signal management are provided.</p> +<table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><signal.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="program/signal" title="c/program/signal"> <span class="t-lines"><span>signal</span></span></a></div> </td> <td> sets a signal handler for particular signal <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="program/raise" title="c/program/raise"> <span class="t-lines"><span>raise</span></span></a></div> </td> <td> runs the signal handler for particular signal <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="program/sig_atomic_t" title="c/program/sig atomic t"> <span class="t-lines"><span>sig_atomic_t</span></span></a></div> </td> <td> the integer type that can be accessed as an atomic entity from an asynchronous signal handler <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="program/sig_strategies" title="c/program/SIG strategies"> <span class="t-lines"><span>SIG_DFL</span><span>SIG_IGN</span></span></a></div> </td> <td> defines signal handling strategies <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="program/sig_err" title="c/program/SIG ERR"> <span class="t-lines"><span>SIG_ERR</span></span></a></div> </td> <td> error was encountered <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Signal_types"> Signal types </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="program/sig_types" title="c/program/SIG types"> <span class="t-lines"><span>SIGABRT</span><span>SIGFPE</span><span>SIGILL</span><span>SIGINT</span><span>SIGSEGV</span><span>SIGTERM</span></span></a></div> </td> <td> defines signal types <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> <h3 id="Non-local_jumps"> Non-local jumps</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><setjmp.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="program/setjmp" title="c/program/setjmp"> <span class="t-lines"><span>setjmp</span></span></a></div> </td> <td> saves the context <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="program/longjmp" title="c/program/longjmp"> <span class="t-lines"><span>longjmp</span></span></a></div> </td> <td> jumps to specified location <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Types"> Types </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="program/jmp_buf" title="c/program/jmp buf"> <span class="t-lines"><span>jmp_buf</span></span></a></div> </td> <td> execution context type <br> <span class="t-mark">(typedef)</span> </td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.13 Nonlocal jumps <setjmp.h> (p: 191-192) </li> +<li> 7.14 Signal handling <signal.h> (p: 193-195) </li> +<li> 7.22 General utilities <stdlib.h> (p: 248-262) </li> +<li> 7.31.7 Signal handling <signal.h> (p: 332) </li> +<li> 7.31.12 General utilities <stdlib.h> (p: 333) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.13 Nonlocal jumps <setjmp.h> (p: 262-264) </li> +<li> 7.14 Signal handling <signal.h> (p: 265-267) </li> +<li> 7.22 General utilities <stdlib.h> (p: 340-360) </li> +<li> 7.31.7 Signal handling <signal.h> (p: 455) </li> +<li> 7.31.12 General utilities <stdlib.h> (p: 456) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.13 Nonlocal jumps <setjmp.h> (p: 243-245) </li> +<li> 7.14 Signal handling <signal.h> (p: 246-248) </li> +<li> 7.20 General utilities <stdlib.h> (p: 306-324) </li> +<li> 7.26.6 Signal handling <signal.h> (p: 401) </li> +<li> 7.26.10 General utilities <stdlib.h> (p: 402) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 4.6 NON-LOCAL JUMPS <setjmp.h> </li> +<li> 4.7 SIGNAL HANDLING <signal.h> </li> +<li> 4.10 GENERAL UTILITIES <stdlib.h> </li> +<li> 4.13.5 Signal handling <signal.h> </li> +<li> 7.13.7 General utilities <stdlib.h> </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/program" title="cpp/utility/program">C++ documentation</a></span> for <span class=""><span>Program support utilities</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/program" class="_attribution-link">https://en.cppreference.com/w/c/program</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fatof.html b/devdocs/c/string%2Fbyte%2Fatof.html new file mode 100644 index 00000000..54760677 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fatof.html @@ -0,0 +1,73 @@ + <h1 id="firstHeading" class="firstHeading">atof</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">double atof( const char* str );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Interprets a floating-point value in a byte string pointed to by <code>str</code>.</p> +<p>Function discards any whitespace characters (as determined by <code><a href="isspace" title="c/string/byte/isspace">isspace</a></code>) until first non-whitespace character is found. Then it takes as many characters as possible to form a valid floating-point representation and converts them to a floating-point value. The valid floating-point value can be one of the following:</p> +<ul> +<li>decimal floating-point expression. It consists of the following parts: </li> +<ul> +<li> <span class="t-mark">(optional)</span> plus or minus sign </li> +<li> nonempty sequence of decimal digits optionally containing decimal-point character (as determined by the current C <a href="../../locale/setlocale" title="c/locale/setlocale">locale</a>) (defines significand) </li> +<li> <span class="t-mark">(optional)</span> <code>e</code> or <code>E</code> followed with optional minus or plus sign and nonempty sequence of decimal digits (defines exponent to base 10) </li> +</ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <ul> +<li>hexadecimal floating-point expression. It consists of the following parts: </li> +<ul> +<li> <span class="t-mark">(optional)</span> plus or minus sign </li> +<li> <code>0x</code> or <code>0X</code> </li> +<li> nonempty sequence of hexadecimal digits optionally containing a decimal-point character (as determined by the current C <a href="../../locale/setlocale" title="c/locale/setlocale">locale</a>) (defines significand) </li> +<li> <span class="t-mark">(optional)</span> <code>p</code> or <code>P</code> followed with optional minus or plus sign and nonempty sequence of decimal digits (defines exponent to base 2) </li> +</ul> +<li> infinity expression. It consists of the following parts: </li> +<ul> +<li> <span class="t-mark">(optional)</span> plus or minus sign </li> +<li> <code>INF</code> or <code>INFINITY</code> ignoring case </li> +</ul> +<li> not-a-number expression. It consists of the following parts: </li> +<ul> +<li> <span class="t-mark">(optional)</span> plus or minus sign </li> +<li> <code>NAN</code> or <code>NAN(</code><i>char_sequence</i><code>)</code> ignoring case of the <code>NAN</code> part. <i>char_sequence</i> can only contain digits, Latin letters, and underscores. The result is a quiet NaN floating-point value. </li> +</ul> +</ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <ul><li> any other expression that may be accepted by the currently installed C <a href="../../locale/setlocale" title="c/locale/setlocale">locale</a> </li></ul> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> pointer to the null-terminated byte string to be interpreted </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>double</code> value corresponding to the contents of <code>str</code> on success. If the converted value falls out of range of the return type, the return value is undefined. If no conversion can be performed, <code>0.0</code> is returned.</p> +<h3 id="Notes"> Notes</h3> <p>The name stands for "ASCII to float".</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdlib.h> +#include <stdio.h> + +int main(void) +{ + printf("%g\n", atof(" -0.0000000123junk")); + printf("%g\n", atof("0.012")); + printf("%g\n", atof("15e16")); + printf("%g\n", atof("-0x1afp-2")); + printf("%g\n", atof("inF")); + printf("%g\n", atof("Nan")); + printf("%g\n", atof("1.0e+309")); // UB: out of range of double + printf("%g\n", atof("0.0")); + printf("%g\n", atof("junk")); // no conversion can be performed +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">-1.23e-08 +0.012 +1.5e+17 +-107.75 +inf +nan +inf +0 +0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.1.1 The atof function (p: 341) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.1.1 The atof function (p: 307) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.1.1 The atof function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="strtof" title="c/string/byte/strtof"> <span class="t-lines"><span>strtof</span><span>strtod</span><span>strtold</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a byte string to a floating point value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/atof" title="cpp/string/byte/atof">C++ documentation</a></span> for <code>atof</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/atof" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/atof</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fatoi.html b/devdocs/c/string%2Fbyte%2Fatoi.html new file mode 100644 index 00000000..b4a114d3 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fatoi.html @@ -0,0 +1,60 @@ + <h1 id="firstHeading" class="firstHeading">atoi, atol, atoll</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int atoi( const char *str );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">long atol( const char *str );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long long atoll( const char *str );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Interprets an integer value in a byte string pointed to by <code>str</code>. The implied radix is always 10.</p> +<p>Discards any whitespace characters until the first non-whitespace character is found, then takes as many characters as possible to form a valid integer number representation and converts them to an integer value. The valid integer value consists of the following parts:</p> +<ul> +<li> <span class="t-mark">(optional)</span> plus or minus sign </li> +<li> numeric digits </li> +</ul> <p>If the value of the result cannot be represented, i.e. the converted value falls out of range of the corresponding return type, the behavior is undefined.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> pointer to the null-terminated byte string to be interpreted </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Integer value corresponding to the contents of <code>str</code> on success.</p> +<p>If no conversion can be performed, <code>0</code> is returned.</p> +<h3 id="Notes"> Notes</h3> <p>The name stands for "ASCII to integer".</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + printf("%i\n", atoi(" -123junk")); + printf("%i\n", atoi(" +321dust")); + printf("%i\n", atoi("0")); + printf("%i\n", atoi("0042")); // treated as a decimal number with leading zeros + printf("%i\n", atoi("0x2A")); // only leading zero is converted discarding "x2A" + printf("%i\n", atoi("junk")); // no conversion can be performed + printf("%i\n", atoi("2147483648")); // UB: out of range of int +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">-123 +321 +0 +42 +0 +0 +-2147483648</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22.1.2 The atoi, atol, and atoll functions (p: 249) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.1.2 The atoi, atol, and atoll functions (p: 341) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.1.2 The atoi, atol, and atoll functions (p: 307) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 4.10.1.2 The atoi function </li> +<li> 4.10.1.3 The atol function </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="strtol" title="c/string/byte/strtol"> <span class="t-lines"><span>strtol</span><span>strtoll</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a byte string to an integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strtoul" title="c/string/byte/strtoul"> <span class="t-lines"><span>strtoul</span><span> strtoull</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a byte string to an unsigned integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../wide/wcstol" title="c/string/wide/wcstol"> <span class="t-lines"><span>wcstol</span><span>wcstoll</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a wide string to an integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../wide/wcstoul" title="c/string/wide/wcstoul"> <span class="t-lines"><span>wcstoul</span><span>wcstoull</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a wide string to an unsigned integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/atoi" title="cpp/string/byte/atoi">C++ documentation</a></span> for <code>atoi, atol, atoll</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/atoi" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/atoi</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fisalnum.html b/devdocs/c/string%2Fbyte%2Fisalnum.html new file mode 100644 index 00000000..98f04421 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fisalnum.html @@ -0,0 +1,124 @@ + <h1 id="firstHeading" class="firstHeading">isalnum</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><ctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int isalnum( int ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Checks if the given character is an alphanumeric character as classified by the current C locale. In the default locale, the following characters are alphanumeric:</p> +<ul> +<li> digits (<code>0123456789</code>) </li> +<li> uppercase letters (<code>ABCDEFGHIJKLMNOPQRSTUVWXYZ</code>) </li> +<li> lowercase letters (<code>abcdefghijklmnopqrstuvwxyz</code>) </li> +</ul> <p>The behavior is undefined if the value of <code>ch</code> is not representable as <code>unsigned char</code> and is not equal to <code><a href="http://en.cppreference.com/w/c/io"><span class="kw888">EOF</span></a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> character to classify </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the character is an alphanumeric character, <code>0</code> otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>Demonstrates the use of <code>isalnum</code> with different locales (OS-specific).</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <ctype.h> +#include <locale.h> + +int main(void) +{ + unsigned char c = '\xdf'; // German letter ß in ISO-8859-1 + + printf("isalnum('\\xdf') in default C locale returned %d\n", !!isalnum(c)); + + if(setlocale(LC_CTYPE, "de_DE.iso88591")) + printf("isalnum('\\xdf') in ISO-8859-1 locale returned %d\n", !!isalnum(c)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">isalnum('\xdf') in default C locale returned 0 +isalnum('\xdf') in ISO-8859-1 locale returned 1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.4.1.1 The isalnum function (p: 145) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.4.1.1 The isalnum function (p: 200) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.4.1.1 The isalnum function (p: 181) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.3.1.1 The isalnum function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../wide/iswalnum" title="c/string/wide/iswalnum"> <span class="t-lines"><span>iswalnum</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is alphanumeric <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/isalnum" title="cpp/string/byte/isalnum">C++ documentation</a></span> for <code>isalnum</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="../wide/iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="../wide/iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="../wide/iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="../wide/iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="../wide/iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="../wide/iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><strong class="selflink"><code>isalnum</code></strong> <br> <a href="../wide/iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="../wide/iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="../wide/iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="../wide/iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="../wide/iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="../wide/iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/isalnum" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/isalnum</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fisalpha.html b/devdocs/c/string%2Fbyte%2Fisalpha.html new file mode 100644 index 00000000..3e6a7c4c --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fisalpha.html @@ -0,0 +1,121 @@ + <h1 id="firstHeading" class="firstHeading">isalpha</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><ctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int isalpha( int ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Checks if the given character is an alphabetic character, i.e. either an uppercase letter (<code>ABCDEFGHIJKLMNOPQRSTUVWXYZ</code>), or a lowercase letter (<code>abcdefghijklmnopqrstuvwxyz</code>).</p> +<p>In locales other than <code>"C"</code>, an alphabetic character is a character for which <code><a href="isupper" title="c/string/byte/isupper">isupper()</a></code> or <code><a href="islower" title="c/string/byte/islower">islower()</a></code> returns <code>true</code> or any other character considered alphabetic by the locale. In any case, <code><a href="iscntrl" title="c/string/byte/iscntrl">iscntrl()</a></code>, <code><a href="isdigit" title="c/string/byte/isdigit">isdigit()</a></code>, <code><a href="ispunct" title="c/string/byte/ispunct">ispunct()</a></code> and <code><a href="isspace" title="c/string/byte/isspace">isspace()</a></code> will return <code>false</code> for this character.</p> +<p>The behavior is undefined if the value of <code>ch</code> is not representable as <code>unsigned char</code> and is not equal to <code><a href="http://en.cppreference.com/w/c/io"><span class="kw888">EOF</span></a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> character to classify </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the character is an alphabetic character, zero otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>Demonstrates the use of <code>isalpha</code> with different locales (OS-specific).</p> +<div class="c source-c"><pre data-language="c">#include <ctype.h> +#include <stdio.h> +#include <locale.h> + +int main(void) +{ + unsigned char c = '\xdf'; // German letter ß in ISO-8859-1 + + printf("isalpha('\\xdf') in default C locale returned %d\n", !!isalpha(c)); + + setlocale(LC_CTYPE, "de_DE.iso88591"); + printf("isalpha('\\xdf') in ISO-8859-1 locale returned %d\n", !!isalpha(c)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">isalpha('\xdf') in default C locale returned 0 +isalpha('\xdf') in ISO-8859-1 locale returned 1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.4.1.2 The isalpha function (p: 145) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.4.1.2 The isalpha function (p: 200-201) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.4.1.2 The isalpha function (p: 181-182) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.3.1.2 The isalpha function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../wide/iswalpha" title="c/string/wide/iswalpha"> <span class="t-lines"><span>iswalpha</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is alphabetic <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/isalpha" title="cpp/string/byte/isalpha">C++ documentation</a></span> for <code>isalpha</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="../wide/iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="../wide/iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="../wide/iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="../wide/iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="../wide/iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="../wide/iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="../wide/iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><strong class="selflink"><code>isalpha</code></strong> <br> <a href="../wide/iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="../wide/iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="../wide/iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="../wide/iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="../wide/iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/isalpha" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/isalpha</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fisblank.html b/devdocs/c/string%2Fbyte%2Fisblank.html new file mode 100644 index 00000000..76e4d54e --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fisblank.html @@ -0,0 +1,112 @@ + <h1 id="firstHeading" class="firstHeading">isblank</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><ctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int isblank( int ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Checks if the given character is a blank character in the current C locale. In the default C locale, only space (<code>0x20</code>) and horizontal tab (<code>0x09</code>) are classified as blank.</p> +<p>The behavior is undefined if the value of <code>ch</code> is not representable as <code>unsigned char</code> and is not equal to <code><a href="http://en.cppreference.com/w/c/io"><span class="kw888">EOF</span></a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> character to classify </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the character is a blank character, zero otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <ctype.h> +#include <limits.h> + +int main(void) +{ + for (int ndx=0; ndx<=UCHAR_MAX; ndx++) + if (isblank(ndx)) printf("0x%02x\n", ndx); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">0x09 +0x20</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.4.1.3 The isblank function (p: 145) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.4.1.3 The isblank function (p: 201) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.4.1.3 The isblank function (p: 182) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../wide/iswblank" title="c/string/wide/iswblank"> <span class="t-lines"><span>iswblank</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if a wide character is a blank character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/isblank" title="cpp/string/byte/isblank">C++ documentation</a></span> for <code>isblank</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="../wide/iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="../wide/iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="../wide/iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><strong class="selflink"><code>isblank</code></strong><br> <a href="../wide/iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="../wide/iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="../wide/iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="../wide/iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="../wide/iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="../wide/iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="../wide/iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="../wide/iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="../wide/iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/isblank" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/isblank</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fiscntrl.html b/devdocs/c/string%2Fbyte%2Fiscntrl.html new file mode 100644 index 00000000..54078772 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fiscntrl.html @@ -0,0 +1,118 @@ + <h1 id="firstHeading" class="firstHeading">iscntrl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><ctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int iscntrl( int ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Checks if the given character is a control character, i.e. codes <code>0x00-0x1F</code> and <code>0x7F</code>.</p> +<p>The behavior is undefined if the value of <code>ch</code> is not representable as <code>unsigned char</code> and is not equal to <code><a href="http://en.cppreference.com/w/c/io"><span class="kw888">EOF</span></a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> character to classify </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the character is a control character, zero otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <ctype.h> +#include <locale.h> + +int main(void) +{ + unsigned char c = '\x94'; // the control code CCH in ISO-8859-1 + printf("In the default C locale, \\x94 is %sa control character\n", + iscntrl(c) ? "" : "not " ); + setlocale(LC_ALL, "en_GB.iso88591"); + printf("In ISO-8859-1 locale, \\x94 is %sa control character\n", + iscntrl(c) ? "" : "not " ); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">In the default C locale, \x94 is not a control character +In ISO-8859-1 locale, \x94 is a control character</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.4.1.4 The iscntrl function (p: 146) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.4.1.4 The iscntrl function (p: 201) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.4.1.4 The iscntrl function (p: 182) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.3.1.3 The iscntrl function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../wide/iswcntrl" title="c/string/wide/iswcntrl"> <span class="t-lines"><span>iswcntrl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is a control character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/iscntrl" title="cpp/string/byte/iscntrl">C++ documentation</a></span> for <code>iscntrl</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><strong class="selflink"><code>iscntrl</code></strong><br> <a href="../wide/iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="../wide/iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="../wide/iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="../wide/iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="../wide/iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="../wide/iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="../wide/iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="../wide/iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="../wide/iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="../wide/iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="../wide/iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="../wide/iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/iscntrl" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/iscntrl</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fisdigit.html b/devdocs/c/string%2Fbyte%2Fisdigit.html new file mode 100644 index 00000000..b3c3ec37 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fisdigit.html @@ -0,0 +1,115 @@ + <h1 id="firstHeading" class="firstHeading">isdigit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><ctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int isdigit( int ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Checks if the given character is a numeric character (<code>0123456789</code>).</p> +<p>The behavior is undefined if the value of <code>ch</code> is not representable as <code>unsigned char</code> and is not equal to <code><a href="http://en.cppreference.com/w/c/io"><span class="kw888">EOF</span></a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> character to classify </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the character is a numeric character, zero otherwise.</p> +<h3 id="Notes"> Notes</h3> <p><code>isdigit</code> and <code>isxdigit</code> are the only standard narrow character classification functions that are not affected by the currently installed C locale, although some implementations (e.g. Microsoft in 1252 codepage) may classify additional single-byte characters as digits.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <ctype.h> +#include <limits.h> + +int main(void) +{ + for (int ndx=0; ndx<=UCHAR_MAX; ndx++) + if (isdigit(ndx)) printf("%c", ndx); + printf("\n"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">0123456789</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.4.1.5 The isdigit function (p: 146) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.4.1.5 The isdigit function (p: 201) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.4.1.5 The isdigit function (p: 182) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.3.1.4 The isdigit function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../wide/iswdigit" title="c/string/wide/iswdigit"> <span class="t-lines"><span>iswdigit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is a digit <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/isdigit" title="cpp/string/byte/isdigit">C++ documentation</a></span> for <code>isdigit</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="../wide/iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="../wide/iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="../wide/iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="../wide/iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="../wide/iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="../wide/iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="../wide/iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="../wide/iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="../wide/iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="../wide/iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><strong class="selflink"><code>isdigit</code></strong><br> <a href="../wide/iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="../wide/iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/isdigit" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/isdigit</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fisgraph.html b/devdocs/c/string%2Fbyte%2Fisgraph.html new file mode 100644 index 00000000..b6a983b4 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fisgraph.html @@ -0,0 +1,118 @@ + <h1 id="firstHeading" class="firstHeading">isgraph</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><ctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int isgraph( int ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Checks if the given character has a graphical representation, i.e. it is either a number (<code>0123456789</code>), an uppercase letter (<code>ABCDEFGHIJKLMNOPQRSTUVWXYZ</code>), a lowercase letter (<code>abcdefghijklmnopqrstuvwxyz</code>), or a punctuation character (<code>!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~</code>), or any graphical character specific to the current C locale.</p> +<p>The behavior is undefined if the value of <code>ch</code> is not representable as <code>unsigned char</code> and is not equal to <code><a href="http://en.cppreference.com/w/c/io"><span class="kw888">EOF</span></a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> character to classify </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the character has a graphical representation character, zero otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <ctype.h> +#include <locale.h> + +int main(void) +{ + unsigned char c = '\xb6'; // the character ¶ in ISO-8859-1 + printf("In the default C locale, \\xb6 is %sgraphical\n", + isgraph(c) ? "" : "not " ); + setlocale(LC_ALL, "en_GB.iso88591"); + printf("In ISO-8859-1 locale, \\xb6 is %sgraphical\n", + isgraph(c) ? "" : "not " ); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">In the default C locale, \xb6 is not graphical +In ISO-8859-1 locale, \xb6 is graphical</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.4.1.6 The isgraph function (p: 146) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.4.1.6 The isgraph function (p: 201-202) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.4.1.6 The isgraph function (p: 182-183) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.3.1.5 The isgraph function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../wide/iswgraph" title="c/string/wide/iswgraph"> <span class="t-lines"><span>iswgraph</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is a graphical character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/isgraph" title="cpp/string/byte/isgraph">C++ documentation</a></span> for <code>isgraph</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="../wide/iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="../wide/iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="../wide/iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="../wide/iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><strong class="selflink"><code>isgraph</code></strong><br> <a href="../wide/iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="../wide/iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="../wide/iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="../wide/iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="../wide/iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="../wide/iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="../wide/iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="../wide/iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/isgraph" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/isgraph</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fislower.html b/devdocs/c/string%2Fbyte%2Fislower.html new file mode 100644 index 00000000..1d68c8db --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fislower.html @@ -0,0 +1,119 @@ + <h1 id="firstHeading" class="firstHeading">islower</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><ctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int islower( int ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Checks if the given character is classified as a lowercase character according to the current C locale. In the default "C" locale, <code>islower</code> returns true only for the lowercase letters (<code>abcdefghijklmnopqrstuvwxyz</code>).</p> +<p>If <code>islower</code> returns <code>true</code>, it is guaranteed that <code><a href="iscntrl" title="c/string/byte/iscntrl">iscntrl</a></code>, <code><a href="isdigit" title="c/string/byte/isdigit">isdigit</a></code>, <code><a href="ispunct" title="c/string/byte/ispunct">ispunct</a></code>, and <code><a href="isspace" title="c/string/byte/isspace">isspace</a></code> return <code>false</code> for the same character in the same C locale.</p> +<p>The behavior is undefined if the value of <code>ch</code> is not representable as <code>unsigned char</code> and is not equal to <code><a href="http://en.cppreference.com/w/c/io"><span class="kw888">EOF</span></a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> character to classify </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the character is a lowercase letter, zero otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <ctype.h> +#include <locale.h> + +int main(void) +{ + unsigned char c = '\xe5'; // letter å in ISO-8859-1 + printf("In the default C locale, \\xe5 is %slowercase\n", + islower(c) ? "" : "not " ); + setlocale(LC_ALL, "en_GB.iso88591"); + printf("In ISO-8859-1 locale, \\xe5 is %slowercase\n", + islower(c) ? "" : "not " ); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">In the default C locale, \xe5 is not lowercase +In ISO-8859-1 locale, \xe5 is lowercase</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.4.1.7 The islower function (p: 146) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.4.1.7 The islower function (p: 202) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.4.1.7 The islower function (p: 183) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.3.1.6 The islower function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../wide/iswlower" title="c/string/wide/iswlower"> <span class="t-lines"><span>iswlower</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is an lowercase character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/islower" title="cpp/string/byte/islower">C++ documentation</a></span> for <code>islower</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="../wide/iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="../wide/iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="../wide/iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="../wide/iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="../wide/iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="../wide/iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="../wide/iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="../wide/iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="../wide/iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><strong class="selflink"><code>islower</code></strong><br> <a href="../wide/iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="../wide/iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="../wide/iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/islower" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/islower</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fisprint.html b/devdocs/c/string%2Fbyte%2Fisprint.html new file mode 100644 index 00000000..9a1efa2b --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fisprint.html @@ -0,0 +1,116 @@ + <h1 id="firstHeading" class="firstHeading">isprint</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><ctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int isprint( int ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Checks if the given character can be printed, i.e. it is either a number (<code>0123456789</code>), an uppercase letter (<code>ABCDEFGHIJKLMNOPQRSTUVWXYZ</code>), a lowercase letter (<code>abcdefghijklmnopqrstuvwxyz</code>), a punctuation character(<code>!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~</code>), or space, or any character classified as printable by the current C locale.</p> +<p>The behavior is undefined if the value of <code>ch</code> is not representable as <code>unsigned char</code> and is not equal to <code><a href="http://en.cppreference.com/w/c/io"><span class="kw888">EOF</span></a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> character to classify </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the character can be printed, zero otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <ctype.h> +#include <locale.h> + +int main(void) +{ + unsigned char c = '\xa0'; // the non-breaking space in ISO-8859-1 + printf("In the default C locale, \\xa0 is %sprintable\n", isprint(c)?"":"not "); + setlocale(LC_ALL, "en_GB.iso88591"); + printf("In ISO-8859-1 locale, \\xa0 is %sprintable\n", isprint(c)?"":"not "); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">In the default C locale, \xa0 is not printable +In ISO-8859-1 locale, \xa0 is printable</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.4.1.8 The isprint function (p: 146) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.4.1.8 The isprint function (p: 202) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.4.1.8 The isprint function (p: 183) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.3.1.7 The isprint function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../wide/iswprint" title="c/string/wide/iswprint"> <span class="t-lines"><span>iswprint</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is a printing character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/isprint" title="cpp/string/byte/isprint">C++ documentation</a></span> for <code>isprint</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="../wide/iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><strong class="selflink"><code>isprint</code></strong><br> <a href="../wide/iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="../wide/iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="../wide/iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="../wide/iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="../wide/iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="../wide/iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="../wide/iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="../wide/iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="../wide/iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="../wide/iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="../wide/iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/isprint" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/isprint</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fispunct.html b/devdocs/c/string%2Fbyte%2Fispunct.html new file mode 100644 index 00000000..c9986542 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fispunct.html @@ -0,0 +1,118 @@ + <h1 id="firstHeading" class="firstHeading">ispunct</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><ctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int ispunct( int ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Checks if the given character is a punctuation character in the current C locale. The default C locale classifies the characters <code>!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~</code> as punctuation.</p> +<p>The behavior is undefined if the value of <code>ch</code> is not representable as <code>unsigned char</code> and is not equal to <code><a href="http://en.cppreference.com/w/c/io"><span class="kw888">EOF</span></a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> character to classify </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the character is a punctuation character, zero otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <ctype.h> +#include <locale.h> + +int main(void) +{ + unsigned char c = '\xd7'; // the character × (multiplication sign) in ISO-8859-1 + printf("In the default C locale, \\xd7 is %spunctuation\n", + ispunct(c) ? "" : "not " ); + setlocale(LC_ALL, "en_GB.iso88591"); + printf("In ISO-8859-1 locale, \\xd7 is %spunctuation\n", + ispunct(c) ? "" : "not " ); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">In the default C locale, \xd7 is not punctuation +In ISO-8859-1 locale, \xd7 is punctuation</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.4.1.9 The ispunct function (p: 146) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.4.1.9 The ispunct function (p: 202) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.4.1.9 The ispunct function (p: 183) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.3.1.8 The ispunct function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../wide/iswpunct" title="c/string/wide/iswpunct"> <span class="t-lines"><span>iswpunct</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is a punctuation character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/ispunct" title="cpp/string/byte/ispunct">C++ documentation</a></span> for <code>ispunct</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="../wide/iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="../wide/iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="../wide/iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="../wide/iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="../wide/iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><strong class="selflink"><code>ispunct</code></strong> <br> <a href="../wide/iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="../wide/iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="../wide/iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="../wide/iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="../wide/iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="../wide/iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="../wide/iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/ispunct" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/ispunct</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fisspace.html b/devdocs/c/string%2Fbyte%2Fisspace.html new file mode 100644 index 00000000..4e44c6b0 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fisspace.html @@ -0,0 +1,127 @@ + <h1 id="firstHeading" class="firstHeading">isspace</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><ctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int isspace( int ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Checks if the given character is either</p> +<ul> +<li> A standard white-space character: </li> +<ul> +<li> Space (<span class="nu12">0x20</span>, <code>' '</code>), </li> +<li> Form feed (<span class="nu12">0x0c</span>, <code>'\f'</code>), </li> +<li> Line feed (<span class="nu12">0x0a</span>, <code>'\n'</code>), </li> +<li> Carriage return (<span class="nu12">0x0d</span>, <code>'\r'</code>), </li> +<li> Horizontal tab (<span class="nu12">0x09</span>, <code>'\t'</code>), </li> +<li> Vertical tab (<span class="nu12">0x0b</span>, <code>'\v'</code>), </li> +</ul> +<li> Or a locale-specific white-space character. </li> +</ul> <p>The behavior is undefined if the value of <code>ch</code> is not representable as <code>unsigned char</code> and is not equal to <code><a href="../../io" title="c/io">EOF</a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> character to classify </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the character is a whitespace character, zero otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <ctype.h> +#include <limits.h> +#include <stdio.h> + +int main(void) +{ + for (int ndx = 0; ndx <= UCHAR_MAX; ndx++) + if (isspace(ndx)) + printf("0x%02x ", ndx); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">0x09 0x0a 0x0b 0x0c 0x0d 0x20</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.4.1.10 The isspace function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.4.1.10 The isspace function (p: 147) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.4.1.10 The isspace function (p: 202-203) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.4.1.10 The isspace function (p: 183-184) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.3.1.9 The isspace function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../wide/iswspace" title="c/string/wide/iswspace"> <span class="t-lines"><span>iswspace</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is a space character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/isspace" title="cpp/string/byte/isspace">C++ documentation</a></span> for <code>isspace</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="../wide/iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="../wide/iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><strong class="selflink"><code>isspace</code></strong><br> <a href="../wide/iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="../wide/iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="../wide/iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="../wide/iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="../wide/iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="../wide/iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="../wide/iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="../wide/iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="../wide/iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="../wide/iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/isspace" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/isspace</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fisupper.html b/devdocs/c/string%2Fbyte%2Fisupper.html new file mode 100644 index 00000000..52479559 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fisupper.html @@ -0,0 +1,119 @@ + <h1 id="firstHeading" class="firstHeading">isupper</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><ctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int isupper( int ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Checks if the given character is an uppercase character according to the current C locale. In the default "C" locale, <code>isupper</code> returns true only for the uppercase letters (<code>ABCDEFGHIJKLMNOPQRSTUVWXYZ</code>).</p> +<p>If <code>isupper</code> returns <code>true</code>, it is guaranteed that <code><a href="iscntrl" title="c/string/byte/iscntrl">iscntrl</a></code>, <code><a href="isdigit" title="c/string/byte/isdigit">isdigit</a></code>, <code><a href="ispunct" title="c/string/byte/ispunct">ispunct</a></code>, and <code><a href="isspace" title="c/string/byte/isspace">isspace</a></code> return <code>false</code> for the same character in the same C locale.</p> +<p>The behavior is undefined if the value of <code>ch</code> is not representable as <code>unsigned char</code> and is not equal to <code><a href="http://en.cppreference.com/w/c/io"><span class="kw888">EOF</span></a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> character to classify </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the character is an uppercase letter, zero otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <ctype.h> +#include <locale.h> + +int main(void) +{ + unsigned char c = '\xc6'; // letter Æ in ISO-8859-1 + printf("In the default C locale, \\xc6 is %suppercase\n", + isupper(c) ? "" : "not " ); + setlocale(LC_ALL, "en_GB.iso88591"); + printf("In ISO-8859-1 locale, \\xc6 is %suppercase\n", + isupper(c) ? "" : "not " ); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">In the default C locale, \xc6 is not uppercase +In ISO-8859-1 locale, \xc6 is uppercase</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.4.1.11 The isupper function (p: 147) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.4.1.11 The isupper function (p: 203) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.4.1.11 The isupper function (p: 184) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.3.1.10 The isupper function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../wide/iswupper" title="c/string/wide/iswupper"> <span class="t-lines"><span>iswupper</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is an uppercase character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/isupper" title="cpp/string/byte/isupper">C++ documentation</a></span> for <code>isupper</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="../wide/iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="../wide/iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="../wide/iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="../wide/iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="../wide/iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="../wide/iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="../wide/iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="../wide/iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><strong class="selflink"><code>isupper</code></strong><br> <a href="../wide/iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="../wide/iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="../wide/iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="../wide/iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/isupper" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/isupper</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fisxdigit.html b/devdocs/c/string%2Fbyte%2Fisxdigit.html new file mode 100644 index 00000000..86d2cfd9 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fisxdigit.html @@ -0,0 +1,116 @@ + <h1 id="firstHeading" class="firstHeading">isxdigit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><ctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int isxdigit( int ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Checks if the given character is a hexadecimal numeric character (<span class="nu19">0123456789</span>abcdefABCDEF) or is classified as a hexadecimal character.</p> +<p>The behavior is undefined if the value of <code>ch</code> is not representable as <code>unsigned char</code> and is not equal to <code><a href="http://en.cppreference.com/w/c/io"><span class="kw888">EOF</span></a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> character to classify </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the character is an hexadecimal numeric character, zero otherwise.</p> +<h3 id="Notes"> Notes</h3> <p><code>isdigit</code> and <code>isxdigit</code> are the only standard narrow character classification functions that are not affected by the currently installed C locale, although some implementations (e.g. Microsoft in 1252 codepage) may classify additional single-byte characters as digits.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <ctype.h> +#include <limits.h> +#include <stdio.h> + +int main(void) +{ + for (int ndx = 0; UCHAR_MAX >= ndx; ++ndx) + if (isxdigit(ndx)) + printf("%c", ndx); + printf("\n"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">0123456789ABCDEFabcdef</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.4.1.12 The isxdigit function (p: 147) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.4.1.12 The isxdigit function (p: 203) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.4.1.12 The isxdigit function (p: 184) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.3.1.11 The isxdigit function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../wide/iswxdigit" title="c/string/wide/iswxdigit"> <span class="t-lines"><span>iswxdigit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is a hexadecimal character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/isxdigit" title="cpp/string/byte/isxdigit">C++ documentation</a></span> for <code>isxdigit</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="../wide/iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="../wide/iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="../wide/iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="../wide/iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="../wide/iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="../wide/iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="../wide/iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="../wide/iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="../wide/iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="../wide/iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="../wide/iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><strong class="selflink"><code>isxdigit</code></strong><br> <a href="../wide/iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/isxdigit" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/isxdigit</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fmemccpy.html b/devdocs/c/string%2Fbyte%2Fmemccpy.html new file mode 100644 index 00000000..a487a5ec --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fmemccpy.html @@ -0,0 +1,106 @@ + <h1 id="firstHeading" class="firstHeading">memccpy</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">void* memccpy( void* restrict dest, const void* restrict src, int c, size_t count );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <p>Copies bytes from the object pointed to by <code>src</code> to the object pointed to by <code>dest</code>, stopping after <i>any</i> of the next two conditions are satisfied:</p> +<ul> +<li> <code>count</code> bytes are copied </li> +<li> the byte <code>(unsigned char)c</code> is found (and copied). </li> +</ul> <p>The <code>src</code> and <code>dest</code> objects are interpreted as arrays of <code>unsigned char</code>.</p> +<p>The behavior is undefined if <i>any</i> condition is met:</p> +<ul> +<li> access occurs beyond the end of the <code>dest</code> array; </li> +<li> the objects overlap (which is a violation of the <a href="../../language/restrict" title="c/language/restrict"><code>restrict</code></a> contract) </li> +<li> either <code>dest</code> or <code>src</code> is an invalid or null pointer </li> +</ul> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the object to copy to </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the object to copy from </td> +</tr> <tr class="t-par"> <td> c </td> <td> - </td> <td> terminating byte, converted to <code>unsigned char</code> at first </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> number of bytes to copy </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If the byte <code>(unsigned char)c</code> was found, <code>memccpy</code> returns a pointer to the next byte in <code>dest</code> after <code>(unsigned char)c</code>. Otherwise it returns a null pointer.</p> +<h3 id="Notes"> Notes</h3> <p>The function is identical to the <a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/memccpy.html">POSIX <code>memccpy</code></a>.</p> +<p><code>memccpy(dest, src, 0, count)</code> behaves similar to <code><a href="http://en.cppreference.com/w/c/string/byte/strncpy"><span class="kw554">strncpy</span></a><span class="br0">(</span>dest, src, count<span class="br0">)</span></code>, except that the former returns a pointer to the <i>end</i> of the buffer written, and does not zero-pad the destination array. Thus, <code>memccpy</code> is useful for efficiently concatenating multiple strings.</p> +<div class="c source-c"><pre data-language="c">char bigString[1000]; +char* end = bigString + sizeof bigString; + +char* p = memccpy(bigString, "John, ", '\0', sizeof bigString - 1); +if (p) + p = memccpy(p - 1, "Paul, ", '\0', end - p); +if (p) + p = memccpy(p - 1, "George, ", '\0', end - p); +if (p) + p = memccpy(p - 1, "Joel ", '\0', end - p); +if (!p) + end[-1] = '\0'; + +puts(bigString); // John, Paul, George, Joel</pre></div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <ctype.h> +#include <stdio.h> +#include <string.h> + +int main(void) +{ + const char src[] = "Stars: Altair, Sun, Vega."; + const char terminal[] = {':', ' ', ',', '.', '!'}; + char dest[sizeof src]; + const char alt = '@'; + + for (size_t i = 0; i != sizeof terminal; ++i) + { + void* to = memccpy(dest, src, terminal[i], sizeof dest); + + printf("Terminal '%c' (%s):\t\"", terminal[i], to ? "found" : "absent"); + + // if `terminal` character was not found - print the whole `dest` + to = to ? to : dest + sizeof dest; + + for (char* from = dest; from != to; ++from) + putchar(isprint(*from) ? *from : alt); + + puts("\""); + } + + + puts("\n" "Separate star names from distances (ly):"); + const char *star_distance[] = { + "Arcturus : 37", "Vega : 25", "Capella : 43", "Rigel : 860", "Procyon : 11" + }; + char names_only[64]; + char *first = names_only; + char *last = names_only + sizeof names_only; + + for (size_t t = 0; t != (sizeof star_distance) / (sizeof star_distance[0]); ++t) + { + if (first) + first = memccpy(first, star_distance[t], ' ', last - first); + else + break; + } + + if (first) + { + *first = '\0'; + puts(names_only); + } + else + puts("Buffer is too small."); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Terminal ':' (found): "Stars:" +Terminal ' ' (found): "Stars: " +Terminal ',' (found): "Stars: Altair," +Terminal '.' (found): "Stars: Altair, Sun, Vega." +Terminal '!' (absent): "Stars: Altair, Sun, Vega.@" + +Separate star names from distances (ly): +Arcturus Vega Capella Rigel Procyon</pre></div> </div> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="memcpy" title="c/string/byte/memcpy"> <span class="t-lines"><span>memcpy</span><span>memcpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies one buffer to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../wide/wmemcpy" title="c/string/wide/wmemcpy"> <span class="t-lines"><span>wmemcpy</span><span>wmemcpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies a certain amount of wide characters between two non-overlapping arrays <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="memmove" title="c/string/byte/memmove"> <span class="t-lines"><span>memmove</span><span>memmove_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> moves one buffer to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strcpy" title="c/string/byte/strcpy"> <span class="t-lines"><span>strcpy</span><span>strcpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies one string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strcat" title="c/string/byte/strcat"> <span class="t-lines"><span>strcat</span><span>strcat_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> concatenates two strings <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/memccpy" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/memccpy</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fmemchr.html b/devdocs/c/string%2Fbyte%2Fmemchr.html new file mode 100644 index 00000000..79724ecd --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fmemchr.html @@ -0,0 +1,51 @@ + <h1 id="firstHeading" class="firstHeading">memchr</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">void *memchr( const void *ptr, int ch, size_t count );</pre> +</td> <td> (1) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">/*QVoid*/ *memchr( /*QVoid*/ *ptr, int ch, size_t count );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Finds the first occurrence of <code>(unsigned char)ch</code> in the initial <code>count</code> bytes (each interpreted as <code>unsigned char</code>) of the object pointed to by <code>ptr</code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Type-generic function equivalent to <span class="t-v">(1)</span>. Let <code>T</code> be an unqualified object type (including <code>void</code>). <ul> +<li> If <code>ptr</code> is of type <code>const T*</code>, the return type is <code>const void*</code>. </li> +<li> Otherwise, if <code>ptr</code> is of type <code>T*</code>, the return type is <code>void*</code>. </li> +<li> Otherwise, the behavior is undefined. </li> +</ul> If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if <code>(memchr)</code> or a function pointer is used), the actual function declaration <span class="t-v">(1)</span> becomes visible.</div> <p>The behavior is undefined if access occurs beyond the end of the array searched. The behavior is undefined if <code>ptr</code> is a null pointer.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c11"> +<td> <p>This function behaves as if it reads the bytes sequentially and stops as soon as a matching bytes is found: if the array pointed to by <code>ptr</code> is smaller than <code>count</code>, but the match is found within the array, the behavior is well-defined.</p> +</td> <td><span class="t-mark-rev t-since-c11">(since C11)</span></td> +</tr> </table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ptr </td> <td> - </td> <td> pointer to the object to be examined </td> +</tr> <tr class="t-par"> <td> ch </td> <td> - </td> <td> bytes to search for </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> max number of bytes to examine </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Pointer to the location of the byte, or a null pointer if no such byte is found.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <string.h> + +int main(void) +{ + const char str[] = "ABCDEFG"; + const int chars[] = {'D', 'd'}; + for (size_t i = 0; i < sizeof chars / (sizeof chars[0]); ++i) + { + const int c = chars[i]; + const char *ps = memchr(str, c, strlen(str)); + ps ? printf ("character '%c'(%i) found: %s\n", c, c, ps) + : printf ("character '%c'(%i) not found\n", c, c); + } + return 0; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">character 'D'(68) found: DEFG +character 'd'(100) not found</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.24.5.1 The memchr function (p: 267-268) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.24.5.1 The memchr function (p: 367) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.5.1 The memchr function (p: 330) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.5.1 The memchr function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="strchr" title="c/string/byte/strchr"> <span class="t-lines"><span>strchr</span></span></a></div> </td> <td> finds the first occurrence of a character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/memchr" title="cpp/string/byte/memchr">C++ documentation</a></span> for <code>memchr</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/memchr" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/memchr</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fmemcmp.html b/devdocs/c/string%2Fbyte%2Fmemcmp.html new file mode 100644 index 00000000..4d8d372f --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fmemcmp.html @@ -0,0 +1,57 @@ + <h1 id="firstHeading" class="firstHeading">memcmp</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int memcmp( const void* lhs, const void* rhs, size_t count );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Compares the first <code>count</code> bytes of the objects pointed to by <code>lhs</code> and <code>rhs</code>. The comparison is done lexicographically.</p> +<p>The sign of the result is the sign of the difference between the values of the first pair of bytes (both interpreted as <code>unsigned char</code>) that differ in the objects being compared.</p> +<p>The behavior is undefined if access occurs beyond the end of either object pointed to by <code>lhs</code> and <code>rhs</code>. The behavior is undefined if either <code>lhs</code> or <code>rhs</code> is a null pointer.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> lhs, rhs </td> <td> - </td> <td> pointers to the objects to compare </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> number of bytes to examine </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Negative value if <code>lhs</code> appears before <code>rhs</code> in lexicographical order.</p> +<p>Zero if <code>lhs</code> and <code>rhs</code> compare equal, or if count is zero.</p> +<p>Positive value if <code>lhs</code> appears after <code>rhs</code> in lexicographical order.</p> +<h3 id="Notes"> Notes</h3> <p>This function reads <a href="../../language/object" title="c/language/object">object representations</a>, not the object values, and is typically meaningful for byte arrays only: structs may have padding bytes whose values are indeterminate, the values of any bytes beyond the last stored member in a union are indeterminate, and a type may have two or more representations for the same value (different encodings for +0 and -0 or for +0.0 and –0.0, indeterminate padding bits within the type).</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <string.h> + +void demo(const char* lhs, const char* rhs, size_t sz) +{ + for(size_t n = 0; n < sz; ++n) + putchar(lhs[n]); + + int rc = memcmp(lhs, rhs, sz); + const char *rel = rc < 0 ? " precedes " : rc > 0 ? " follows " : " compares equal "; + fputs(rel, stdout); + + for(size_t n = 0; n < sz; ++n) + putchar(rhs[n]); + puts(" in lexicographical order"); +} + +int main(void) +{ + char a1[] = {'a','b','c'}; + char a2[sizeof a1] = {'a','b','d'}; + + demo(a1, a2, sizeof a1); + demo(a2, a1, sizeof a1); + demo(a1, a1, sizeof a1); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">abc precedes abd in lexicographical order +abd follows abc in lexicographical order +abc compares equal to abc in lexicographical order</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.24.4.1 The memcmp function (p: 266) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.24.4.1 The memcmp function (p: 365) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.4.1 The memcmp function (p: 328) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.4.1 The memcmp function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="strcmp" title="c/string/byte/strcmp"> <span class="t-lines"><span>strcmp</span></span></a></div> </td> <td> compares two strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strncmp" title="c/string/byte/strncmp"> <span class="t-lines"><span>strncmp</span></span></a></div> </td> <td> compares a certain amount of characters of two strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/memcmp" title="cpp/string/byte/memcmp">C++ documentation</a></span> for <code>memcmp</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/memcmp" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/memcmp</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fmemcpy.html b/devdocs/c/string%2Fbyte%2Fmemcpy.html new file mode 100644 index 00000000..d2483fba --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fmemcpy.html @@ -0,0 +1,94 @@ + <h1 id="firstHeading" class="firstHeading">memcpy, memcpy_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">void* memcpy( void *dest, const void *src, size_t count );</pre> +</td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">void* memcpy( void *restrict dest, const void *restrict src, size_t count );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t memcpy_s( void *restrict dest, rsize_t destsz, + const void *restrict src, rsize_t count );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Copies <code>count</code> characters from the object pointed to by <code>src</code> to the object pointed to by <code>dest</code>. Both objects are interpreted as arrays of <code>unsigned char</code>.</div> <div class="t-li1"> + The behavior is undefined if access occurs beyond the end of the <code>dest</code> array. If the objects overlap<span class="t-rev-inl t-since-c99"><span> (which is a violation of the <a href="../../language/restrict" title="c/language/restrict"><code>restrict</code></a> contract)</span><span><span class="t-mark-rev t-since-c99">(since C99)</span></span></span>, the behavior is undefined. The behavior is undefined if either <code>dest</code> or <code>src</code> is an invalid or null pointer.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that the following errors are detected at runtime and cause the entire destination range <code>[dest, dest+destsz)</code> to be zeroed out (if both <code>dest</code> and <code>destsz</code> are valid), as well as call the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <ul> +<li> <code>dest</code> or <code>src</code> is a null pointer </li> +<li> <code>destsz</code> or <code>count</code> is greater than <code>RSIZE_MAX</code> </li> +<li> <code>count</code> is greater than <code>destsz</code> (buffer overflow would occur) </li> +<li> the source and the destination objects overlap</li> +</ul> +</div> <div class="t-li1"> + The behavior is undefined if the size of the character array pointed to by <code>dest</code> < <code>count</code> <= <code>destsz</code>; in other words, an erroneous value of <code>destsz</code> does not expose the impending buffer overflow. As with all bounds-checked functions, <code>memcpy_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../byte" title="c/string/byte"><code><string.h></code></a>.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the object to copy to </td> +</tr> <tr class="t-par"> <td> destsz </td> <td> - </td> <td> max number of bytes to modify in the destination (typically the size of the destination object) </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the object to copy from </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> number of bytes to copy </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> Returns a copy of <code>dest</code> +</div> <div class="t-li1"> +<span class="t-li">2)</span> Returns zero on success and non-zero value on error. Also on error, if <code>dest</code> is not a null pointer and <code>destsz</code> is valid, writes <code>destsz</code> zero bytes in to the destination array.</div> <h3 id="Notes"> Notes</h3> <p><code>memcpy</code> may be used to set the <a href="../../language/object#Effective_type" title="c/language/object">effective type</a> of an object obtained by an allocation function.</p> +<p><code>memcpy</code> is the fastest library routine for memory-to-memory copy. It is usually more efficient than <code><a href="strcpy" title="c/string/byte/strcpy">strcpy</a></code>, which must scan the data it copies or <code><a href="memmove" title="c/string/byte/memmove">memmove</a></code>, which must take precautions to handle overlapping inputs.</p> +<p>Several C compilers transform suitable memory-copying loops to <code>memcpy</code> calls.</p> +<p>Where <a href="../../language/object#Strict_aliasing" title="c/language/object">strict aliasing</a> prohibits examining the same memory as values of two different types, <code>memcpy</code> may be used to convert the values.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#define __STDC_WANT_LIB_EXT1__ 1 +#include <stdio.h> +#include <stdint.h> +#include <inttypes.h> +#include <string.h> +#include <stdlib.h> + +int main(void) +{ + // simple usage + char source[] = "once upon a midnight dreary...", dest[4]; + memcpy(dest, source, sizeof dest); + for(size_t n = 0; n < sizeof dest; ++n) + putchar(dest[n]); + + // setting effective type of allocated memory to be int + int *p = malloc(3*sizeof(int)); // allocated memory has no effective type + int arr[3] = {1,2,3}; + memcpy(p,arr,3*sizeof(int)); // allocated memory now has an effective type + + // reinterpreting data + double d = 0.1; +// int64_t n = *(int64_t*)(&d); // strict aliasing violation + int64_t n; + memcpy(&n, &d, sizeof d); // OK + printf("\n%a is %" PRIx64 " as an int64_t\n", d, n); + +#ifdef __STDC_LIB_EXT1__ + set_constraint_handler_s(ignore_handler_s); + char src[] = "aaaaaaaaaa"; + char dst[] = "xyxyxyxyxy"; + int r = memcpy_s(dst,sizeof dst,src,5); + printf("dst = \"%s\", r = %d\n", dst,r); + r = memcpy_s(dst,5,src,10); // count is greater than destsz + printf("dst = \""); + for(size_t ndx=0; ndx<sizeof dst; ++ndx) { + char c = dst[ndx]; + c ? printf("%c", c) : printf("\\0"); + } + printf("\", r = %d\n", r); +#endif +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">once +0x1.999999999999ap-4 is 3fb999999999999a as an int64_t +dst = "aaaaayxyxy", r = 0 +dst = "\0\0\0\0\0yxyxy", r = 22</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.24.2.1 The memcpy function (p: 362) </li> +<li> K.3.7.1.1 The memcpy_s function (p: 614) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.2.1 The memcpy function (p: 325) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.2.1 The memcpy function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="memccpy" title="c/string/byte/memccpy"> <span class="t-lines"><span>memccpy</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> copies one buffer to another, stopping after the specified delimiter <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="memmove" title="c/string/byte/memmove"> <span class="t-lines"><span>memmove</span><span>memmove_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> moves one buffer to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../wide/wmemcpy" title="c/string/wide/wmemcpy"> <span class="t-lines"><span>wmemcpy</span><span>wmemcpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies a certain amount of wide characters between two non-overlapping arrays <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/memcpy" title="cpp/string/byte/memcpy">C++ documentation</a></span> for <code>memcpy</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/memcpy" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/memcpy</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fmemmove.html b/devdocs/c/string%2Fbyte%2Fmemmove.html new file mode 100644 index 00000000..2fbb10a9 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fmemmove.html @@ -0,0 +1,93 @@ + <h1 id="firstHeading" class="firstHeading">memmove, memmove_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">void* memmove( void* dest, const void* src, size_t count );</pre> +</td> <td> (1) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t memmove_s(void *dest, rsize_t destsz, const void *src, rsize_t count);</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Copies <code>count</code> characters from the object pointed to by <code>src</code> to the object pointed to by <code>dest</code>. Both objects are interpreted as arrays of <code>unsigned char</code>. The objects may overlap: copying takes place as if the characters were copied to a temporary character array and then the characters were copied from the array to <code>dest</code>.</div> <div class="t-li1"> + The behavior is undefined if access occurs beyond the end of the dest array. The behavior is undefined if either <code>dest</code> or <code>src</code> is an invalid or null pointer.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except when detecting the following errors at runtime, it zeroes out the entire destination range <code>[dest, dest+destsz)</code> (if both <code>dest</code> and <code>destsz</code> are valid) and calls the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <ul> +<li> <code>dest</code> or <code>src</code> is a null pointer </li> +<li> <code>destsz</code> or <code>count</code> is greater than <code>RSIZE_MAX</code> </li> +<li> <code>count</code> is greater than <code>destsz</code> (buffer overflow would occur)</li> +</ul> +</div> <div class="t-li1"> + The behavior is undefined if the size of the character array pointed to by <code>dest</code> < <code>count</code> <= <code>destsz</code>; in other words, an erroneous value of <code>destsz</code> does not expose the impending buffer overflow. As with all bounds-checked functions, <code>memmove_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../byte" title="c/string/byte"><code><string.h></code></a>.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the object to copy to </td> +</tr> <tr class="t-par"> <td> destsz </td> <td> - </td> <td> max number of bytes to modify in the destination (typically the size of the destination object) </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the object to copy from </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> number of bytes to copy </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> Returns a copy of <code>dest</code> +</div> <div class="t-li1"> +<span class="t-li">2)</span> Returns zero on success and non-zero value on error. Also on error, if <code>dest</code> is not a null pointer and <code>destsz</code> is valid, writes <code>destsz</code> zero bytes in to the destination array.</div> <h3 id="Notes"> Notes</h3> <p><code>memmove</code> may be used to set the <a href="../../language/object#Effective_type" title="c/language/object">effective type</a> of an object obtained by an allocation function.</p> +<p>Despite being specified "as if" a temporary buffer is used, actual implementations of this function do not incur the overhead or double copying or extra memory. A common approach (glibc and bsd libc) is to copy bytes forwards from the beginning of the buffer if the destination starts before the source, and backwards from the end otherwise, with a fall back to the more efficient <code><a href="memcpy" title="c/string/byte/memcpy">memcpy</a></code> when there is no overlap at all.</p> +<p>Where <a href="../../language/object#Strict_aliasing" title="c/language/object">strict aliasing</a> prohibits examining the same memory as values of two different types, <code>memmove</code> may be used to convert the values.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#define __STDC_WANT_LIB_EXT1__ 1 +#include <stdio.h> +#include <stdint.h> +#include <inttypes.h> +#include <string.h> +#include <stdlib.h> + +int main(void) +{ + char str[] = "1234567890"; + puts(str); + memmove(str+4, str+3, 3); // copy from [4,5,6] to [5,6,7] + puts(str); + + // setting effective type of allocated memory to be int + int *p = malloc(3*sizeof(int)); // allocated memory has no effective type + int arr[3] = {1,2,3}; + memmove(p,arr,3*sizeof(int)); // allocated memory now has an effective type + + // reinterpreting data + double d = 0.1; +// int64_t n = *(int64_t*)(&d); // strict aliasing violation + int64_t n; + memmove(&n, &d, sizeof d); // OK + printf("%a is %" PRIx64 " as an int64_t\n", d, n); + +#ifdef __STDC_LIB_EXT1__ + set_constraint_handler_s(ignore_handler_s); + char src[] = "aaaaaaaaaa"; + char dst[] = "xyxyxyxyxy"; + int r = memmove_s(dst,sizeof dst,src,5); + printf("dst = \"%s\", r = %d\n", dst,r); + r = memmove_s(dst,5,src,10); // count is greater than destsz + printf("dst = \""); + for(size_t ndx=0; ndx<sizeof dst; ++ndx) { + char c = dst[ndx]; + c ? printf("%c", c) : printf("\\0"); + } + printf("\", r = %d\n", r); +#endif +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">1234567890 +1234456890 +0x1.999999999999ap-4 is 3fb999999999999a as an int64_t +dst = "aaaaayxyxy", r = 0 +dst = "\0\0\0\0\0yxyxy", r = 22</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.24.2.2 The memmove function (p: 264) </li> +<li> K.3.7.1.2 The memmove_s function (p: 446) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.24.2.2 The memmove function (p: 363) </li> +<li> K.3.7.1.2 The memmove_s function (p: 615) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.2.2 The memmove function (p: 326) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.2.2 The memmove function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="memcpy" title="c/string/byte/memcpy"> <span class="t-lines"><span>memcpy</span><span>memcpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies one buffer to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../wide/wmemmove" title="c/string/wide/wmemmove"> <span class="t-lines"><span>wmemmove</span><span>wmemmove_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies a certain amount of wide characters between two, possibly overlapping, arrays <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/memmove" title="cpp/string/byte/memmove">C++ documentation</a></span> for <code>memmove</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/memmove" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/memmove</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fmemset.html b/devdocs/c/string%2Fbyte%2Fmemset.html new file mode 100644 index 00000000..cf822c20 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fmemset.html @@ -0,0 +1,73 @@ + <h1 id="firstHeading" class="firstHeading">memset, memset_explicit, memset_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">void *memset( void *dest, int ch, size_t count );</pre> +</td> <td> (1) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">void *memset_explicit( void *dest, int ch, size_t count );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t memset_s( void *dest, rsize_t destsz, int ch, rsize_t count );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Copies the value <code>(unsigned char)ch</code> into each of the first <code>count</code> characters of the object pointed to by <code>dest</code>.</div> <div class="t-li1"> + The behavior is undefined if access occurs beyond the end of the dest array. The behavior is undefined if <code>dest</code> is a null pointer.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that is safe for sensitive information.</div> <div class="t-li1"> +<span class="t-li">3)</span> Same as <span class="t-v">(1)</span>, except that the following errors are detected at runtime and call the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function after storing <code>ch</code> in every location of the destination range <code>[dest, dest+destsz)</code> if <code>dest</code> and <code>destsz</code> are themselves valid: <ul> +<li> <code>dest</code> is a null pointer </li> +<li> <code>destsz</code> or <code>count</code> is greater than <code>RSIZE_MAX</code> </li> +<li> <code>count</code> is greater than <code>destsz</code> (buffer overflow would occur)</li> +</ul> +</div> <div class="t-li1"> + The behavior is undefined if the size of the character array pointed to by <code>dest</code> < <code>count</code> <= <code>destsz</code>; in other words, an erroneous value of <code>destsz</code> does not expose the impending buffer overflow. As with all bounds-checked functions, <code>memset_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../byte" title="c/string/byte"><code><string.h></code></a>.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the object to fill </td> +</tr> <tr class="t-par"> <td> ch </td> <td> - </td> <td> fill byte </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> number of bytes to fill </td> +</tr> <tr class="t-par"> <td> destsz </td> <td> - </td> <td> size of the destination array </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1,2)</span> A copy of <code>dest</code> +</div> <div class="t-li1"> +<span class="t-li">3)</span> zero on success, non-zero on error. Also on error, if <code>dest</code> is not a null pointer and <code>destsz</code> is valid, writes <code>destsz</code> fill bytes <code>ch</code> to the destination array.</div> <h3 id="Notes"> Notes</h3> <p><code>memset</code> may be optimized away (under the <a href="../../language/as_if" title="c/language/as if">as-if</a> rules) if the object modified by this function is not accessed again for the rest of its lifetime (e.g., <a rel="nofollow" class="external text" href="https://gcc.gnu.org/bugzilla/show_bug.cgi?id=8537">gcc bug 8537</a>). For that reason, this function cannot be used to scrub memory (e.g., to fill an array that stored a password with zeroes).</p> +<p>This optimization is prohibited for <code>memset_explicit</code> and <code>memset_s</code>: they are guaranteed to perform the memory write.</p> +<p>Third-party solutions for that include FreeBSD <a rel="nofollow" class="external text" href="https://www.freebsd.org/cgi/man.cgi?query=explicit_bzero"><code>explicit_bzero</code></a> or Microsoft <a rel="nofollow" class="external text" href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa366877.aspx"><code>SecureZeroMemory</code></a>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#define __STDC_WANT_LIB_EXT1__ 1 +#include <stdio.h> +#include <string.h> +#include <stdlib.h> + +int main(void) +{ + char str[] = "ghghghghghghghghghghgh"; + puts(str); + memset(str,'a',5); + puts(str); + +#ifdef __STDC_LIB_EXT1__ + set_constraint_handler_s(ignore_handler_s); + int r = memset_s(str, sizeof str, 'b', 5); + printf("str = \"%s\", r = %d\n", str, r); + r = memset_s(str, 5, 'c', 10); // count is greater than destsz + printf("str = \"%s\", r = %d\n", str, r); +#endif +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">ghghghghghghghghghghgh +aaaaahghghghghghghghgh +str = "bbbbbhghghghghghghghgh", r = 0 +str = "ccccchghghghghghghghgh", r = 22</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.24.6.1 The memset function (p: 270) </li> +<li> K.3.7.4.1 The memset_s function (p: 451) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.24.6.1 The memset function (p: 371) </li> +<li> K.3.7.4.1 The memset_s function (p: 621-622) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.6.1 The memset function (p: 333) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.6.1 The memset function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="memcpy" title="c/string/byte/memcpy"> <span class="t-lines"><span>memcpy</span><span>memcpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies one buffer to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../wide/wmemset" title="c/string/wide/wmemset"> <span class="t-lines"><span>wmemset</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> copies the given wide character to every position in a wide character array <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/memset" title="cpp/string/byte/memset">C++ documentation</a></span> for <code>memset</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/memset" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/memset</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrcat.html b/devdocs/c/string%2Fbyte%2Fstrcat.html new file mode 100644 index 00000000..08ce3a04 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrcat.html @@ -0,0 +1,76 @@ + <h1 id="firstHeading" class="firstHeading">strcat, strcat_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">char *strcat( char *dest, const char *src );</pre> +</td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">char *strcat( char *restrict dest, const char *restrict src );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t strcat_s(char *restrict dest, rsize_t destsz, const char *restrict src);</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Appends a copy of the null-terminated byte string pointed to by <code>src</code> to the end of the null-terminated byte string pointed to by <code>dest</code>. The character <code>src[0]</code> replaces the null terminator at the end of <code>dest</code>. The resulting byte string is null-terminated.</div> <div class="t-li1"> + The behavior is undefined if the destination array is not large enough for the contents of both <code>src</code> and <code>dest</code> and the terminating null character. The behavior is undefined if the strings overlap. The behavior is undefined if either <code>dest</code> or <code>src</code> is not a pointer to a null-terminated byte string.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that it may clobber the rest of the destination array (from the last character written to <code>destsz</code>) with unspecified values and that the following errors are detected at runtime and call the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <ul> +<li> <code>src</code> or <code>dest</code> is a null pointer </li> +<li> <code>destsz</code> is zero or greater than <code>RSIZE_MAX</code> </li> +<li> there is no null terminator in the first <code>destsz</code> bytes of <code>dest</code> </li> +<li> truncation would occur (the available space at the end of <code>dest</code> would not fit every character, including the null terminator, of <code>src</code>) </li> +<li> overlap would occur between the source and the destination strings</li> +</ul> +</div> <div class="t-li1"> + The behavior is undefined if the size of the character array pointed to by <code>dest</code> < <code><a href="http://en.cppreference.com/w/c/string/byte/strlen"><span class="kw557">strlen</span></a><span class="br0">(</span>dest<span class="br0">)</span><span class="sy2">+</span><a href="http://en.cppreference.com/w/c/string/byte/strlen"><span class="kw557">strlen</span></a><span class="br0">(</span>src<span class="br0">)</span><span class="sy2">+</span><span class="nu0">1</span></code> <= <code>destsz</code>; in other words, an erroneous value of <code>destsz</code> does not expose the impending buffer overflow. As with all bounds-checked functions, <code>strcat_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../byte" title="c/string/byte"><code><string.h></code></a>.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the null-terminated byte string to append to </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the null-terminated byte string to copy from </td> +</tr> <tr class="t-par"> <td> destsz </td> <td> - </td> <td> maximum number of characters to write, typically the size of the destination buffer </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> returns a copy of <code>dest</code> +</div> <div class="t-li1"> +<span class="t-li">2)</span> returns zero on success, returns non-zero on error. Also, on error, writes zero to <code>dest[0]</code> (unless <code>dest</code> is a null pointer or <code>destsz</code> is zero or greater than <code>RSIZE_MAX</code>).</div> <h3 id="Notes"> Notes</h3> <p>Because <code>strcat</code> needs to seek to the end of <code>dest</code> on each call, it is inefficient to concatenate many strings into one using <code>strcat</code>.</p> +<p><code>strcat_s</code> is allowed to clobber the destination array from the last character written up to <code>destsz</code> in order to improve efficiency: it may copy in multibyte blocks and then check for null bytes.</p> +<p>The function <code>strcat_s</code> is similar to the <a rel="nofollow" class="external text" href="https://www.freebsd.org/cgi/man.cgi?query=strlcat&sektion=3">BSD function <code>strlcat</code></a>, except that</p> +<ul> +<li> <code>strlcat</code> truncates the source string to fit in the destination </li> +<li> <code>strlcat</code> does not perform all the runtime checks that <code>strcat_s</code> does </li> +<li> <code>strlcat</code> does not make failures obvious by setting the destination to a null string or calling a handler if the call fails. </li> +</ul> <p>Although <code>strcat_s</code> prohibits truncation due to potential security risks, it's possible to truncate a string using bounds-checked <code><a href="strncat" title="c/string/byte/strncat">strncat_s</a></code> instead.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#define __STDC_WANT_LIB_EXT1__ 1 +#include <string.h> +#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + char str[50] = "Hello "; + char str2[50] = "World!"; + strcat(str, str2); + strcat(str, " ..."); + strcat(str, " Goodbye World!"); + puts(str); + +#ifdef __STDC_LIB_EXT1__ + set_constraint_handler_s(ignore_handler_s); + int r = strcat_s(str, sizeof str, " ... "); + printf("str = \"%s\", r = %d\n", str, r); + r = strcat_s(str, sizeof str, " and this is too much"); + printf("str = \"%s\", r = %d\n", str, r); +#endif +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Hello World! ... Goodbye World! +str = "Hello World! ... Goodbye World! ... ", r = 0 +str = "", r = 22</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.24.3.1 The strcat function (p: 364) </li> +<li> K.3.7.2.1 The strcat_s function (p: 617-618) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.3.1 The strcat function (p: 327) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.3.1 The strcat function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="strncat" title="c/string/byte/strncat"> <span class="t-lines"><span>strncat</span><span>strncat_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> concatenates a certain amount of characters of two strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strcpy" title="c/string/byte/strcpy"> <span class="t-lines"><span>strcpy</span><span>strcpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies one string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="memccpy" title="c/string/byte/memccpy"> <span class="t-lines"><span>memccpy</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> copies one buffer to another, stopping after the specified delimiter <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/strcat" title="cpp/string/byte/strcat">C++ documentation</a></span> for <code>strcat</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strcat" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strcat</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrchr.html b/devdocs/c/string%2Fbyte%2Fstrchr.html new file mode 100644 index 00000000..39e66671 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrchr.html @@ -0,0 +1,45 @@ + <h1 id="firstHeading" class="firstHeading">strchr</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">char *strchr( const char *str, int ch );</pre> +</td> <td> (1) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">/*QChar*/ *strchr( /*QChar*/ *str, int ch );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Finds the first occurrence of <code>ch</code> (after conversion to <code>char</code> as if by <code>(char)ch</code>) in the null-terminated byte string pointed to by <code>str</code> (each character interpreted as <code>unsigned char</code>). The terminating null character is considered to be a part of the string and can be found when searching for <code>'\0'</code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Type-generic function equivalent to <span class="t-v">(1)</span>. Let <code>T</code> be an unqualified character object type. <ul> +<li> If <code>str</code> is of type <code>const T*</code>, the return type is <code>const char*</code>. </li> +<li> Otherwise, if <code>str</code> is of type <code>T*</code>, the return type is <code>char*</code>. </li> +<li> Otherwise, the behavior is undefined. </li> +</ul> If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if <code>(strchr)</code> or a function pointer is used), the actual function declaration <span class="t-v">(1)</span> becomes visible.</div> <p>The behavior is undefined if <code>str</code> is not a pointer to a null-terminated byte string.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> pointer to the null-terminated byte string to be analyzed </td> +</tr> <tr class="t-par"> <td> ch </td> <td> - </td> <td> character to search for </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Pointer to the found character in <code>str</code>, or null pointer if no such character is found.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <string.h> + +int main(void) +{ + const char *str = "Try not. Do, or do not. There is no try."; + char target = 'T'; + const char *result = str; + + while((result = strchr(result, target)) != NULL) { + printf("Found '%c' starting at '%s'\n", target, result); + ++result; // Increment result, otherwise we'll find target at the same location + } +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Found 'T' starting at 'Try not. Do, or do not. There is no try.' +Found 'T' starting at 'There is no try.'</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.24.5.2 The strchr function (p: 367-368) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.5.2 The strchr function (p: 330) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.5.2 The strchr function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="memchr" title="c/string/byte/memchr"> <span class="t-lines"><span>memchr</span></span></a></div> </td> <td> searches an array for the first occurrence of a character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strrchr" title="c/string/byte/strrchr"> <span class="t-lines"><span>strrchr</span></span></a></div> </td> <td> finds the last occurrence of a character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strpbrk" title="c/string/byte/strpbrk"> <span class="t-lines"><span>strpbrk</span></span></a></div> </td> <td> finds the first location of any character in one string, in another string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/strchr" title="cpp/string/byte/strchr">C++ documentation</a></span> for <code>strchr</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strchr" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strchr</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrcmp.html b/devdocs/c/string%2Fbyte%2Fstrcmp.html new file mode 100644 index 00000000..40219714 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrcmp.html @@ -0,0 +1,50 @@ + <h1 id="firstHeading" class="firstHeading">strcmp</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int strcmp( const char *lhs, const char *rhs );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Compares two null-terminated byte strings lexicographically.</p> +<p>The sign of the result is the sign of the difference between the values of the first pair of characters (both interpreted as <code>unsigned char</code>) that differ in the strings being compared.</p> +<p>The behavior is undefined if <code>lhs</code> or <code>rhs</code> are not pointers to null-terminated byte strings.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> lhs, rhs </td> <td> - </td> <td> pointers to the null-terminated byte strings to compare </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Negative value if <code>lhs</code> appears before <code>rhs</code> in lexicographical order.</p> +<p>Zero if <code>lhs</code> and <code>rhs</code> compare equal.</p> +<p>Positive value if <code>lhs</code> appears after <code>rhs</code> in lexicographical order.</p> +<h3 id="Notes"> Notes</h3> <p>This function is not locale-sensitive, unlike <code><a href="strcoll" title="c/string/byte/strcoll">strcoll</a></code> and <code><a href="strxfrm" title="c/string/byte/strxfrm">strxfrm</a></code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <string.h> +#include <stdio.h> + +void demo(const char* lhs, const char* rhs) +{ + int rc = strcmp(lhs, rhs); + const char *rel = rc < 0 ? "precedes" : rc > 0 ? "follows" : "equals"; + printf("[%s] %s [%s]\n", lhs, rel, rhs); +} + +int main(void) +{ + const char* string = "Hello World!"; + demo(string, "Hello!"); + demo(string, "Hello"); + demo(string, "Hello there"); + demo("Hello, everybody!" + 12, "Hello, somebody!" + 11); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">[Hello World!] precedes [Hello!] +[Hello World!] follows [Hello] +[Hello World!] precedes [Hello there] +[body!] equals [body!]</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.24.4.2 The strcmp function (p: 365-366) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.4.2 The strcmp function (p: 328-329) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.4.2 The strcmp function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="strncmp" title="c/string/byte/strncmp"> <span class="t-lines"><span>strncmp</span></span></a></div> </td> <td> compares a certain amount of characters of two strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../wide/wcscmp" title="c/string/wide/wcscmp"> <span class="t-lines"><span>wcscmp</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> compares two wide strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="memcmp" title="c/string/byte/memcmp"> <span class="t-lines"><span>memcmp</span></span></a></div> </td> <td> compares two buffers <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strcoll" title="c/string/byte/strcoll"> <span class="t-lines"><span>strcoll</span></span></a></div> </td> <td> compares two strings in accordance to the current locale <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/strcmp" title="cpp/string/byte/strcmp">C++ documentation</a></span> for <code>strcmp</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strcmp" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strcmp</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrcoll.html b/devdocs/c/string%2Fbyte%2Fstrcoll.html new file mode 100644 index 00000000..8c19e000 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrcoll.html @@ -0,0 +1,60 @@ + <h1 id="firstHeading" class="firstHeading">strcoll</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int strcoll( const char* lhs, const char* rhs );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Compares two null-terminated byte strings according to the current locale as defined by the <code><a href="../../locale/lc_categories" title="c/locale/LC categories">LC_COLLATE</a></code> category.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> lhs, rhs </td> <td> - </td> <td> pointers to the null-terminated byte strings to compare </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <ul> +<li> Negative value if <code>lhs</code> is <i>less than</i> (precedes) <code>rhs</code>. </li> +<li> <code>0</code> if <code>lhs</code> is <i>equal to</i> <code>rhs</code>. </li> +<li> Positive value if <code>lhs</code> is <i>greater than</i> (follows) <code>rhs</code>. </li> +</ul> <h3 id="Notes"> Notes</h3> <p>Collation order is the dictionary order: the position of the letter in the national alphabet (its <i>equivalence class</i>) has higher priority than its case or variant. Within an equivalence class, lowercase characters collate before their uppercase equivalents and locale-specific order may apply to the characters with diacritics. In some locales, groups of characters compare as single <i>collation units</i>. For example, <code>"ch"</code> in Czech follows <code>"h"</code> and precedes <code>"i"</code>, and <code>"dzs"</code> in Hungarian follows <code>"dz"</code> and precedes <code>"g"</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <string.h> + +int main(void) +{ + setlocale(LC_COLLATE, "cs_CZ.utf8"); + // Alternatively, ISO-8859-2 (a.k.a. Latin-2) + // may also work on some OS: + // setlocale(LC_COLLATE, "cs_CZ.iso88592"); + + const char* s1 = "hrnec"; + const char* s2 = "chrt"; + + printf("In the Czech locale: "); + if (strcoll(s1, s2) < 0) + printf("%s before %s\n", s1, s2); + else + printf("%s before %s\n", s2, s1); + + printf("In lexicographical comparison: "); + if (strcmp(s1, s2) < 0) + printf("%s before %s\n", s1, s2); + else + printf("%s before %s\n", s2, s1); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">In the Czech locale: hrnec before chrt +In lexicographical comparison: chrt before hrnec</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.24.4.3 The strcoll function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.24.4.3 The strcoll function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.24.4.3 The strcoll function (p: 366) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.4.3 The strcoll function (p: 329) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.4.3 The strcoll function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../wide/wcscoll" title="c/string/wide/wcscoll"> <span class="t-lines"><span>wcscoll</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> compares two wide strings in accordance to the current locale <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strxfrm" title="c/string/byte/strxfrm"> <span class="t-lines"><span>strxfrm</span></span></a></div> </td> <td> transform a string so that strcmp would produce the same result as strcoll <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../wide/wcsxfrm" title="c/string/wide/wcsxfrm"> <span class="t-lines"><span>wcsxfrm</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> transform a wide string so that wcscmp would produce the same result as wcscoll <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strcmp" title="c/string/byte/strcmp"> <span class="t-lines"><span>strcmp</span></span></a></div> </td> <td> compares two strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/strcoll" title="cpp/string/byte/strcoll">C++ documentation</a></span> for <code>strcoll</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strcoll" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strcoll</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrcpy.html b/devdocs/c/string%2Fbyte%2Fstrcpy.html new file mode 100644 index 00000000..723ef82b --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrcpy.html @@ -0,0 +1,82 @@ + <h1 id="firstHeading" class="firstHeading">strcpy, strcpy_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">char *strcpy( char *dest, const char *src );</pre> +</td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">char *strcpy( char *restrict dest, const char *restrict src );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t strcpy_s( char *restrict dest, rsize_t destsz, const char *restrict src );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Copies the null-terminated byte string pointed to by <code>src</code>, including the null terminator, to the character array whose first element is pointed to by <code>dest</code>.</div> <div class="t-li1"> + The behavior is undefined if the <code>dest</code> array is not large enough. The behavior is undefined if the strings overlap. The behavior is undefined if either <code>dest</code> is not a pointer to a character array or <code>src</code> is not a pointer to a null-terminated byte string.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that it may clobber the rest of the destination array with unspecified values and that the following errors are detected at runtime and call the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <ul> +<li> <code>src</code> or <code>dest</code> is a null pointer </li> +<li> <code>destsz</code> is zero or greater than <code>RSIZE_MAX</code> </li> +<li> <code>destsz</code> is less or equal <code>strnlen_s(src, destsz)</code>; in other words, truncation would occur </li> +<li> overlap would occur between the source and the destination strings</li> +</ul> +</div> <div class="t-li1"> + The behavior is undefined if the size of the character array pointed to by <code>dest</code> <= <code>strnlen_s(src, destsz)</code> < <code>destsz</code>; in other words, an erroneous value of <code>destsz</code> does not expose the impending buffer overflow. As with all bounds-checked functions, <code>strcpy_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../byte" title="c/string/byte"><code><string.h></code></a>.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the character array to write to </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the null-terminated byte string to copy from </td> +</tr> <tr class="t-par"> <td> destsz </td> <td> - </td> <td> maximum number of characters to write, typically the size of the destination buffer </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> returns a copy of <code>dest</code> +</div> <div class="t-li1"> +<span class="t-li">2)</span> returns zero on success, returns non-zero on error. Also, on error, writes zero to <code>dest[0]</code> (unless <code>dest</code> is a null pointer or <code>destsz</code> is zero or greater than <code>RSIZE_MAX</code>).</div> <h3 id="Notes"> Notes</h3> <p><code>strcpy_s</code> is allowed to clobber the destination array from the last character written up to <code>destsz</code> in order to improve efficiency: it may copy in multibyte blocks and then check for null bytes.</p> +<p>The function <code>strcpy_s</code> is similar to the BSD function <code>strlcpy</code>, except that</p> +<ul> +<li> <code>strlcpy</code> truncates the source string to fit in the destination (which is a security risk) </li> +<li> <code>strlcpy</code> does not perform all the runtime checks that <code>strcpy_s</code> does </li> +<li> <code>strlcpy</code> does not make failures obvious by setting the destination to a null string or calling a handler if the call fails. </li> +</ul> <p>Although <code>strcpy_s</code> prohibits truncation due to potential security risks, it's possible to truncate a string using bounds-checked <code><a href="strncpy" title="c/string/byte/strncpy">strncpy_s</a></code> instead.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#define __STDC_WANT_LIB_EXT1__ 1 +#include <string.h> +#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + const char *src = "Take the test."; +// src[0] = 'M' ; // this would be undefined behavior + char dst[strlen(src) + 1]; // +1 to accommodate for the null terminator + strcpy(dst, src); + dst[0] = 'M'; // OK + printf("src = %s\ndst = %s\n", src, dst); + +#ifdef __STDC_LIB_EXT1__ + set_constraint_handler_s(ignore_handler_s); + int r = strcpy_s(dst, sizeof dst, src); + printf("dst = \"%s\", r = %d\n", dst, r); + r = strcpy_s(dst, sizeof dst, "Take even more tests."); + printf("dst = \"%s\", r = %d\n", dst, r); +#endif +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">src = Take the test. +dst = Make the test. +dst = "Take the test.", r = 0 +dst = "", r = 22</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.24.2.3 The strcpy function (p: 264-265) </li> +<li> K.3.7.1.3 The strcpy_s function (p: 447) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.24.2.3 The strcpy function (p: 363) </li> +<li> K.3.7.1.3 The strcpy_s function (p: 615-616) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.2.3 The strcpy function (p: 326) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.2.3 The strcpy function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="strncpy" title="c/string/byte/strncpy"> <span class="t-lines"><span>strncpy</span><span>strncpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies a certain amount of characters from one string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="memcpy" title="c/string/byte/memcpy"> <span class="t-lines"><span>memcpy</span><span>memcpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies one buffer to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../wide/wcscpy" title="c/string/wide/wcscpy"> <span class="t-lines"><span>wcscpy</span><span>wcscpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies one wide string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="https://en.cppreference.com/w/c/experimental/dynamic/strdup" title="c/experimental/dynamic/strdup"> <span class="t-lines"><span>strdup</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-dynamic-tr t-mark-ts">(dynamic memory TR)</span></span></span></div> </td> <td> allocate a copy of a string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/strcpy" title="cpp/string/byte/strcpy">C++ documentation</a></span> for <code>strcpy</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strcpy" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strcpy</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrcspn.html b/devdocs/c/string%2Fbyte%2Fstrcspn.html new file mode 100644 index 00000000..43666174 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrcspn.html @@ -0,0 +1,39 @@ + <h1 id="firstHeading" class="firstHeading">strcspn</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">size_t strcspn( const char *dest, const char *src );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Returns the length of the maximum initial segment of the null-terminated byte string pointed to by <code>dest</code>, that consists of only the characters <i>not</i> found in the null-terminated byte string pointed to by <code>src</code>.</p> +<p>The behavior is undefined if either <code>dest</code> or <code>src</code> is not a pointer to a null-terminated byte string.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the null-terminated byte string to be analyzed </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the null-terminated byte string that contains the characters to search for </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The length of the maximum initial segment that contains only characters not found in the null-terminated byte string pointed to by <code>src</code></p> +<h3 id="Notes"> Notes</h3> <p>The function name stands for "complementary span" because the function searches for characters not found in <code>src</code>, that is the complement of <code>src</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <string.h> +#include <stdio.h> + +int main(void) +{ + const char *string = "abcde312$#@"; + const char *invalid = "*$#"; + + size_t valid_len = strcspn(string, invalid); + if(valid_len != strlen(string)) + printf("'%s' contains invalid chars starting at position %zu\n", + string, valid_len); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">'abcde312$#@' contains invalid chars starting at position 8</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.24.5.3 The strcspn function (p: 368) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.5.3 The strcspn function (p: 331) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.5.3 The strcspn function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="strspn" title="c/string/byte/strspn"> <span class="t-lines"><span>strspn</span></span></a></div> </td> <td> returns the length of the maximum initial segment that consists <br> of only the characters found in another byte string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../wide/wcscspn" title="c/string/wide/wcscspn"> <span class="t-lines"><span>wcscspn</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> returns the length of the maximum initial segment that consists <br> of only the wide chars <i>not</i> found in another wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strpbrk" title="c/string/byte/strpbrk"> <span class="t-lines"><span>strpbrk</span></span></a></div> </td> <td> finds the first location of any character in one string, in another string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/strcspn" title="cpp/string/byte/strcspn">C++ documentation</a></span> for <code>strcspn</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strcspn" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strcspn</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrdup.html b/devdocs/c/string%2Fbyte%2Fstrdup.html new file mode 100644 index 00000000..9b2114c8 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrdup.html @@ -0,0 +1,30 @@ + <h1 id="firstHeading" class="firstHeading">strdup</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">char *strdup( const char *src );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <p>Returns a pointer to a null-terminated byte string, which is a duplicate of the string pointed to by <code>src</code>. The space for the new string is obtained as if the <code><a href="../../memory/malloc" title="c/memory/malloc">malloc</a></code> was invoked. The returned pointer must be passed to <code><a href="../../memory/free" title="c/memory/free">free</a></code> to avoid a memory leak.</p> +<p>If an error occurs, a null pointer is returned and <code><a href="../../error/errno" title="c/error/errno">errno</a></code> might be set.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the null-terminated byte string to duplicate </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>A pointer to the newly allocated string, or a null pointer if an error occurred.</p> +<h3 id="Notes"> Notes</h3> <p>The function is identical to the <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/strdup.html">POSIX strdup</a>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <string.h> +#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + const char *s1 = "Duplicate me!"; + char *s2 = strdup(s1); + printf("s2 = \"%s\"\n", s2); + free(s2); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">s2 = "Duplicate me!"</pre></div> </div> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="strndup" title="c/string/byte/strndup"> <span class="t-lines"><span>strndup</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> allocates a copy of a string of specified size <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strcpy" title="c/string/byte/strcpy"> <span class="t-lines"><span>strcpy</span><span>strcpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies one string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../../memory/malloc" title="c/memory/malloc"> <span class="t-lines"><span>malloc</span></span></a></div> </td> <td> allocates memory <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../../memory/free" title="c/memory/free"> <span class="t-lines"><span>free</span></span></a></div> </td> <td> deallocates previously allocated memory <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strdup" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strdup</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrerror.html b/devdocs/c/string%2Fbyte%2Fstrerror.html new file mode 100644 index 00000000..ffa63b45 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrerror.html @@ -0,0 +1,67 @@ + <h1 id="firstHeading" class="firstHeading">strerror, strerror_s, strerrorlen_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">char* strerror( int errnum );</pre> +</td> <td> (1) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t strerror_s( char *buf, rsize_t bufsz, errno_t errnum );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">size_t strerrorlen_s( errno_t errnum );</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Returns a pointer to the textual description of the system error code <code>errnum</code>, identical to the description that would be printed by <code><a href="../../io/perror" title="c/io/perror">perror()</a></code>.</div> <div class="t-li1"> + <code>errnum</code> is usually acquired from the <code>errno</code> variable, however the function accepts any value of type <code>int</code>. The contents of the string are locale-specific.</div> <div class="t-li1"> + The returned string must not be modified by the program, but may be overwritten by a subsequent call to the <code>strerror</code> function. <code>strerror</code> is not required to be thread-safe. Implementations may be returning different pointers to static read-only string literals or may be returning the same pointer over and over, pointing at a static buffer in which strerror places the string.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that the message is copied into user-provided storage <code>buf</code>. No more than <code>bufsz-1</code> bytes are written, the buffer is always null-terminated. If the message had to be truncated to fit the buffer and <code>bufsz</code> is greater than 3, then only <code>bufsz-4</code> bytes are written, and the characters <code>"..."</code> are appended before the null terminator. In addition, the following errors are detected at runtime and call the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <ul> +<li> <code>buf</code> is a null pointer </li> +<li> <code>bufsz</code> is zero or greater than <code>RSIZE_MAX</code> +</li> +</ul> +</div> <div class="t-li1"> + The behavior is undefined if writing to <code>buf</code> occurs past the end of the array, which can happen when the size of the buffer pointed to by <code>buf</code> is less than the number of characters in the error message which in turn is less than <code>bufsz</code>.</div> <div class="t-li1"> +<span class="t-li">3)</span> Computes the length of the untruncated locale-specific error message that <code>strerror_s</code> would write if it were called with <code>errnum</code>. The length does not include the null terminator. As with all bounds-checked functions, <code>strerror_s</code> and <code>strerrorlen_s</code> are only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../byte" title="c/string/byte"><code><string.h></code></a>.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> errnum </td> <td> - </td> <td> integral value referring to an error code </td> +</tr> <tr class="t-par"> <td> buf </td> <td> - </td> <td> pointer to a user-provided buffer </td> +</tr> <tr class="t-par"> <td> bufsz </td> <td> - </td> <td> size of the user-provided buffer </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> Pointer to a null-terminated byte string corresponding to the <code><a href="../../error/errno" title="c/error/errno">errno</a></code> error code <code>errnum</code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Zero if the entire message was successfully stored in <code>buf</code>, non-zero otherwise.</div> <div class="t-li1"> +<span class="t-li">3)</span> Length (not including the null terminator) of the message that <code>strerror_s</code> would return</div> <h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/strerror.html">POSIX</a> allows subsequent calls to <code>strerror</code> to invalidate the pointer value returned by an earlier call. It also specifies that it is the <a href="../../locale/lc_categories" title="c/locale/LC categories"><code>LC_MESSAGES</code></a> locale facet that controls the contents of these messages.</p> +<p><code>strerror_s</code> is the only bounds-checked function that allows truncation, because providing as much information as possible about a failure was deemed to be more desirable. POSIX also defines <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/strerror.html"><code>strerror_r</code></a> for similar purposes.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#define __STDC_WANT_LIB_EXT1__ 1 +#include <stdio.h> +#include <errno.h> +#include <string.h> +#include <locale.h> + +int main(void) +{ + FILE *fp = fopen(tmpnam((char[L_tmpnam]){0}), "r"); + if(fp==NULL) { + printf("File opening error: %s\n", strerror(errno)); + setlocale(LC_MESSAGES, "de_DE.utf8"); + printf("Now in German: %s\n", strerror(errno)); +#ifdef __STDC_LIB_EXT1__ + setlocale(LC_ALL, "ja_JP.utf8"); // printf needs CTYPE for multibyte output + size_t errmsglen = strerrorlen_s(errno) + 1; + char errmsg[errmsglen]; + strerror_s(errmsg, errmsglen, errno); + printf("Now in Japanese: %s\n", errmsg); +#endif + } +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">File opening error: No such file or directory +Now in German: Datei oder Verzeichnis nicht gefunden +Now in Japanese: そのようなファイル、又はディレクトリはありません</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.24.6.2 The strerror function (p: 371) </li> +<li> K.3.7.4.2 The strerror_s function (p: 622) </li> +<li> K.3.7.4.3 The strerrorlen_s function (p: 623) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.6.2 The strerror function (p: 334) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.6.2 The strerror function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../../io/perror" title="c/io/perror"> <span class="t-lines"><span>perror</span></span></a></div> </td> <td> displays a character string corresponding of the current error to <code><a href="../../io/std_streams" title="c/io/std streams">stderr</a></code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../../error/errno" title="c/error/errno"> <span class="t-lines"><span>errno</span></span></a></div> </td> <td> macro which expands to POSIX-compatible thread-local error number variable<br><span class="t-mark">(macro variable)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/strerror" title="cpp/string/byte/strerror">C++ documentation</a></span> for <code>strerror</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strerror" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strerror</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrfromf.html b/devdocs/c/string%2Fbyte%2Fstrfromf.html new file mode 100644 index 00000000..ce768ba4 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrfromf.html @@ -0,0 +1,24 @@ + <h1 id="firstHeading" class="firstHeading">strfromf, strfromd, strfromld</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">int strfromf( char *restrict s, size_t n, const char *restrict format, float fp );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">int strfromd( char *restrict s, size_t n, const char *restrict format, double fp );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">int strfroml( char *restrict s, size_t n, const char *restrict format, long double fp );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <p>Converts a floating-point value to a byte string.</p> +<p>The functions are equivalent to <code><a href="http://en.cppreference.com/w/c/io/fprintf"><span class="kw854">snprintf</span></a><span class="br0">(</span>s, n, format, fp<span class="br0">)</span></code>, except that the format string shall only contain the character <span class="sy2">%</span>, an optional precision that does not contain an asterisk <span class="sy2">*</span>, and one of the conversion specifiers <code>a</code>, <code>A</code>, <code>e</code>, <code>E</code>, <code>f</code>, <code>F</code>, <code>g</code>, or <code>G</code>, which applies to the type <code>double</code>, <code>float</code>, or <code>long double</code>) indicated by the function suffix (rather than by a length modifier). Use of these functions with any other format string results in undefined behavior.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> s </td> <td> - </td> <td> pointer to a character string to write to </td> +</tr> <tr class="t-par"> <td> n </td> <td> - </td> <td> up to n - 1 characters may be written, plus the null terminator </td> +</tr> <tr class="t-par"> <td> format </td> <td> - </td> <td> pointer to a null-terminated byte string specifying how to interpret the data </td> +</tr> <tr class="t-par"> <td> fp </td> <td> - </td> <td> floating-point value to convert </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The number of characters that would have been written had <code>n</code> been sufficiently large, not counting the terminating null character. Thus, the null-terminated output has been completely written if and only if the returned value is both nonnegative and less than <code>n</code>.</p> +<h3 id="Example"> Example</h3> <h3 id="Reference"> Reference</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.24.1.3 The strfromd, strfromf, and strfroml functions </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../../io/fprintf" title="c/io/fprintf"> <span class="t-lines"><span>printf</span><span>fprintf</span><span>sprintf</span><span>snprintf</span><span>printf_s</span><span>fprintf_s</span><span>sprintf_s</span><span>snprintf_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> prints formatted output to <code><a href="../../io/std_streams" title="c/io/std streams">stdout</a></code>, a file stream or a buffer <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strtof" title="c/string/byte/strtof"> <span class="t-lines"><span>strtof</span><span>strtod</span><span>strtold</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a byte string to a floating point value <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strfromf" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strfromf</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrlen.html b/devdocs/c/string%2Fbyte%2Fstrlen.html new file mode 100644 index 00000000..e8a60fbc --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrlen.html @@ -0,0 +1,49 @@ + <h1 id="firstHeading" class="firstHeading">strlen, strnlen_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">size_t strlen( const char *str );</pre> +</td> <td> (1) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">size_t strnlen_s( const char *str, size_t strsz );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Returns the length of the given null-terminated byte string, that is, the number of characters in a character array whose first element is pointed to by <code>str</code> up to and not including the first null character.</div> <div class="t-li1"> + The behavior is undefined if <code>str</code> is not a pointer to a null-terminated byte string.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that the function returns zero if <code>str</code> is a null pointer and returns <code>strsz</code> if the null character was not found in the first <code>strsz</code> bytes of <code>str</code>.</div> <div class="t-li1"> + The behavior is undefined if both <code>str</code> points to a character array which lacks the null character and the size of that character array < <code>strsz</code>; in other words, an erroneous value of <code>strsz</code> does not expose the impending buffer overflow. As with all bounds-checked functions, <code>strnlen_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../byte" title="c/string/byte"><code><string.h></code></a>.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> pointer to the null-terminated byte string to be examined </td> +</tr> <tr class="t-par"> <td> strsz </td> <td> - </td> <td> maximum number of characters to examine </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> The length of the null-terminated byte string <code>str</code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> The length of the null-terminated byte string <code>str</code> on success, zero if <code>str</code> is a null pointer, <code>strsz</code> if the null character was not found.</div> <h3 id="Notes"> Notes</h3> <p><code>strnlen_s</code> and <code>wcsnlen_s</code> are the only <a href="../../error" title="c/error">bounds-checked functions</a> that do not invoke the runtime constraints handler. They are pure utility functions used to provide limited support for non-null terminated strings.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#define __STDC_WANT_LIB_EXT1__ 1 +#include <string.h> +#include <stdio.h> + +int main(void) +{ + const char str[] = "How many characters does this string contain?"; + + printf("without null character: %zu\n", strlen(str)); + printf("with null character: %zu\n", sizeof str); + +#ifdef __STDC_LIB_EXT1__ + printf("without null character: %zu\n", strnlen_s(str, sizeof str)); +#endif +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">without null character: 45 +with null character: 46 +without null character: 45</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.24.6.3 The strlen function (p: 372) </li> +<li> K.3.7.4.4 The strnlen_s function (p: 623) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.6.3 The strlen function (p: 334) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.6.3 The strlen function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../wide/wcslen" title="c/string/wide/wcslen"> <span class="t-lines"><span>wcslen</span><span>wcsnlen_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> returns the length of a wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../multibyte/mblen" title="c/string/multibyte/mblen"> <span class="t-lines"><span>mblen</span></span></a></div> </td> <td> returns the number of bytes in the next multibyte character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/strlen" title="cpp/string/byte/strlen">C++ documentation</a></span> for <code>strlen</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strlen" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strlen</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrncat.html b/devdocs/c/string%2Fbyte%2Fstrncat.html new file mode 100644 index 00000000..282db51e --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrncat.html @@ -0,0 +1,93 @@ + <h1 id="firstHeading" class="firstHeading">strncat, strncat_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">char *strncat( char *dest, const char *src, size_t count );</pre> +</td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">char *strncat( char *restrict dest, const char *restrict src, size_t count );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t strncat_s( char *restrict dest, rsize_t destsz, + const char *restrict src, rsize_t count );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Appends at most <code>count</code> characters from the character array pointed to by <code>src</code>, stopping if the null character is found, to the end of the null-terminated byte string pointed to by <code>dest</code>. The character <code>src[0]</code> replaces the null terminator at the end of <code>dest</code>. The terminating null character is always appended in the end (so the maximum number of bytes the function may write is <code>count+1</code>).</div> <div class="t-li1"> + The behavior is undefined if the destination array does not have enough space for the contents of both <code>dest</code> and the first <code>count</code> characters of <code>src</code>, plus the terminating null character. The behavior is undefined if the source and destination objects overlap. The behavior is undefined if either <code>dest</code> is not a pointer to a null-terminated byte string or <code>src</code> is not a pointer to a character array,</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that this function may clobber the remainder of the destination array (from the last byte written to <code>destsz</code>) and that the following errors are detected at runtime and call the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <ul> +<li> <code>src</code> or <code>dest</code> is a null pointer </li> +<li> <code>destsz</code> or <code>count</code> is zero or greater than <code>RSIZE_MAX</code> </li> +<li> there is no null character in the first <code>destsz</code> bytes of <code>dest</code> </li> +<li> truncation would occur: <code>count</code> or the length of <code>src</code>, whichever is less, exceeds the space available between the null terminator of <code>dest</code> and <code>destsz</code>. </li> +<li> overlap would occur between the source and the destination strings</li> +</ul> +</div> <div class="t-li1"> + The behavior is undefined if the size of the character array pointed to by <code>dest</code> < <code>strnlen(dest,destsz)+strnlen(src,count)+1</code> < <code>destsz</code>; in other words, an erroneous value of <code>destsz</code> does not expose the impending buffer overflow. The behavior is undefined if the size of the character array pointed to by <code>src</code> < <code>strnlen(src,count)</code> < <code>destsz</code>; in other words, an erroneous value of <code>count</code> does not expose the impending buffer overflow. As with all bounds-checked functions, <code>strncat_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../byte" title="c/string/byte"><code><string.h></code></a>.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the null-terminated byte string to append to </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the character array to copy from </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> maximum number of characters to copy </td> +</tr> <tr class="t-par"> <td> destsz </td> <td> - </td> <td> the size of the destination buffer </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> returns a copy of <code>dest</code> +</div> <div class="t-li1"> +<span class="t-li">2)</span> returns zero on success, returns non-zero on error. Also, on error, writes zero to <code>dest[0]</code> (unless <code>dest</code> is a null pointer or <code>destsz</code> is zero or greater than <code>RSIZE_MAX</code>).</div> <h3 id="Notes"> Notes</h3> <p>Because <code>strncat</code> needs to seek to the end of <code>dest</code> on each call, it is inefficient to concatenate many strings into one using <code>strncat</code>.</p> +<p>Although truncation to fit the destination buffer is a security risk and therefore a runtime constraints violation for <code>strncat_s</code>, it is possible to get the truncating behavior by specifying <code>count</code> equal to the size of the destination array minus one: it will copy the first <code>count</code> bytes and append the null terminator as always: <code>strncat_s(dst, sizeof dst, src, (sizeof dst)-strnlen_s(dst, sizeof dst)-1);</code></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#define __STDC_WANT_LIB_EXT1__ 1 +#include <string.h> +#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + char str[50] = "Hello "; + char str2[50] = "World!"; + strcat(str, str2); + strncat(str, " Goodbye World!", 3); + puts(str); + +#ifdef __STDC_LIB_EXT1__ + set_constraint_handler_s(ignore_handler_s); + char s1[100] = "good"; + char s5[1000] = "bye"; + int r1 = strncat_s(s1, 100, s5, 1000); // r1 is 0, s1 holds "goodbye\0" + printf("s1 = %s, r1 = %d\n", s1, r1); + char s2[6] = "hello"; + int r2 = strncat_s(s2, 6, "", 1); // r2 is 0, s2 holds "hello\0" + printf("s2 = %s, r2 = %d\n", s2, r2); + char s3[6] = "hello"; + int r3 = strncat_s(s3, 6, "X", 2); // r3 is non-zero, s3 holds "\0" + printf("s3 = %s, r3 = %d\n", s3, r3); + // the strncat_s truncation idiom: + char s4[7] = "abc"; + int r4 = strncat_s(s4, 7, "defghijklmn", 3); // r4 is 0, s4 holds "abcdef\0" + printf("s4 = %s, r4 = %d\n", s4, r4); +#endif +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Hello World! Go +s1 = goodbye, r1 = 0 +s2 = hello, r2 = 0 +s3 = , r3 = 22 +s4 = abcdef, r4 = 0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.26.3.2 The strncat function (p: 379) </li> +<li> K.3.7.2.2 The strncat_s function (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.24.3.2 The strncat function (p: 265-266) </li> +<li> K.3.7.2.2 The strncat_s function (p: 449-450) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.24.3.2 The strncat function (p: 364-365) </li> +<li> K.3.7.2.2 The strncat_s function (p: 618-620) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.3.2 The strncat function (p: 327-328) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.3.2 The strncat function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="strcat" title="c/string/byte/strcat"> <span class="t-lines"><span>strcat</span><span>strcat_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> concatenates two strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strcpy" title="c/string/byte/strcpy"> <span class="t-lines"><span>strcpy</span><span>strcpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies one string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="memccpy" title="c/string/byte/memccpy"> <span class="t-lines"><span>memccpy</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> copies one buffer to another, stopping after the specified delimiter <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/strncat" title="cpp/string/byte/strncat">C++ documentation</a></span> for <code>strncat</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strncat" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strncat</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrncmp.html b/devdocs/c/string%2Fbyte%2Fstrncmp.html new file mode 100644 index 00000000..d2dc2071 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrncmp.html @@ -0,0 +1,58 @@ + <h1 id="firstHeading" class="firstHeading">strncmp</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int strncmp( const char* lhs, const char* rhs, size_t count );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Compares at most <code>count</code> characters of two possibly null-terminated arrays. The comparison is done lexicographically. Characters following the null character are not compared.</p> +<p>The sign of the result is the sign of the difference between the values of the first pair of characters (both interpreted as <code>unsigned char</code>) that differ in the arrays being compared.</p> +<p>The behavior is undefined when access occurs past the end of either array <code>lhs</code> or <code>rhs</code>. The behavior is undefined when either <code>lhs</code> or <code>rhs</code> is the null pointer.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> lhs, rhs </td> <td> - </td> <td> pointers to the possibly null-terminated arrays to compare </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> maximum number of characters to compare </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Negative value if <code>lhs</code> appears before <code>rhs</code> in lexicographical order.</p> +<p>Zero if <code>lhs</code> and <code>rhs</code> compare equal, or if count is zero.</p> +<p>Positive value if <code>lhs</code> appears after <code>rhs</code> in lexicographical order.</p> +<h3 id="Notes"> Notes</h3> <p>This function is not locale-sensitive, unlike <code><a href="strcoll" title="c/string/byte/strcoll">strcoll</a></code> and <code><a href="strxfrm" title="c/string/byte/strxfrm">strxfrm</a></code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <string.h> + +void demo(const char* lhs, const char* rhs, int sz) +{ + const int rc = strncmp(lhs, rhs, sz); + if (rc < 0) + printf("First %d chars of [%s] precede [%s]\n", sz, lhs, rhs); + else if (rc > 0) + printf("First %d chars of [%s] follow [%s]\n", sz, lhs, rhs); + else + printf("First %d chars of [%s] equal [%s]\n", sz, lhs, rhs); +} +int main(void) +{ + const char* string = "Hello World!"; + demo(string, "Hello!", 5); + demo(string, "Hello", 10); + demo(string, "Hello there", 10); + demo("Hello, everybody!" + 12, "Hello, somebody!" + 11, 5); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">First 5 chars of [Hello World!] equal [Hello!] +First 10 chars of [Hello World!] follow [Hello] +First 10 chars of [Hello World!] precede [Hello there] +First 5 chars of [body!] equal [body!]</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.24.4.4 The strncmp function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.24.4.4 The strncmp function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.24.4.4 The strncmp function (p: 366) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.4.4 The strncmp function (p: 329) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.4.4 The strncmp function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="strcmp" title="c/string/byte/strcmp"> <span class="t-lines"><span>strcmp</span></span></a></div> </td> <td> compares two strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../wide/wcsncmp" title="c/string/wide/wcsncmp"> <span class="t-lines"><span>wcsncmp</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> compares a certain amount of characters from two wide strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="memcmp" title="c/string/byte/memcmp"> <span class="t-lines"><span>memcmp</span></span></a></div> </td> <td> compares two buffers <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strcoll" title="c/string/byte/strcoll"> <span class="t-lines"><span>strcoll</span></span></a></div> </td> <td> compares two strings in accordance to the current locale <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/strncmp" title="cpp/string/byte/strncmp">C++ documentation</a></span> for <code>strncmp</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strncmp" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strncmp</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrncpy.html b/devdocs/c/string%2Fbyte%2Fstrncpy.html new file mode 100644 index 00000000..45076374 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrncpy.html @@ -0,0 +1,101 @@ + <h1 id="firstHeading" class="firstHeading">strncpy, strncpy_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">char *strncpy( char *dest, const char *src, size_t count );</pre> +</td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">char *strncpy( char *restrict dest, const char *restrict src, size_t count );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t strncpy_s( char *restrict dest, rsize_t destsz, + const char *restrict src, rsize_t count );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Copies at most <code>count</code> characters of the character array pointed to by <code>src</code> (including the terminating null character, but not any of the characters that follow the null character) to character array pointed to by <code>dest</code>. </div> <div class="t-li1"> + If <code>count</code> is reached before the entire array <code>src</code> was copied, the resulting character array is not null-terminated.</div> <div class="t-li1"> + If, after copying the terminating null character from <code>src</code>, <code>count</code> is not reached, additional null characters are written to <code>dest</code> until the total of <code>count</code> characters have been written.</div> <div class="t-li1"> + The behavior is undefined if the character arrays overlap, if either <code>dest</code> or <code>src</code> is not a pointer to a character array (including if <code>dest</code> or <code>src</code> is a null pointer), if the size of the array pointed to by <code>dest</code> is less than <code>count</code>, or if the size of the array pointed to by <code>src</code> is less than <code>count</code> and it does not contain a null character.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that the function does not continue writing zeroes into the destination array to pad up to <code>count</code>, it stops after writing the terminating null character (if there was no null in the source, it writes one at <code>dest[count]</code> and then stops). Also, the following errors are detected at runtime and call the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <ul> +<li> <code>src</code> or <code>dest</code> is a null pointer </li> +<li> <code>destsz</code> is zero or greater than <code>RSIZE_MAX</code> </li> +<li> <code>count</code> is greater than <code>RSIZE_MAX</code> </li> +<li> <code>count</code> is greater or equal <code>destsz</code>, but <code>destsz</code> is less or equal <code>strnlen_s(src, count)</code>, in other words, truncation would occur </li> +<li> overlap would occur between the source and the destination strings</li> +</ul> +</div> <div class="t-li1"> + The behavior is undefined if the size of the character array pointed to by <code>dest</code> < <code>strnlen_s(src, destsz)</code> <= <code>destsz</code>; in other words, an erroneous value of <code>destsz</code> does not expose the impending buffer overflow. The behavior is undefined if the size of the character array pointed to by <code>src</code> < <code>strnlen_s(src, count)</code> < <code>destsz</code>; in other words, an erroneous value of <code>count</code> does not expose the impending buffer overflow. As with all bounds-checked functions, <code>strncpy_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../byte" title="c/string/byte"><code><string.h></code></a>.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the character array to copy to </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the character array to copy from </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> maximum number of characters to copy </td> +</tr> <tr class="t-par"> <td> destsz </td> <td> - </td> <td> the size of the destination buffer </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> returns a copy of <code>dest</code> +</div> <div class="t-li1"> +<span class="t-li">2)</span> returns zero on success, returns non-zero on error. Also, on error, writes zero to <code>dest[0]</code> (unless <code>dest</code> is a null pointer or <code>destsz</code> is zero or greater than <code>RSIZE_MAX</code>) and may clobber the rest of the destination array with unspecified values.</div> <h3 id="Notes"> Notes</h3> <p>As corrected by the post-C11 DR 468, <code>strncpy_s</code>, unlike <code><a href="strcpy" title="c/string/byte/strcpy">strcpy_s</a></code>, is only allowed to clobber the remainder of the destination array if an error occurs.</p> +<p>Unlike <code>strncpy</code>, <code>strncpy_s</code> does not pad the destination array with zeroes, This is a common source of errors when converting existing code to the bounds-checked version.</p> +<p>Although truncation to fit the destination buffer is a security risk and therefore a runtime constraints violation for <code>strncpy_s</code>, it is possible to get the truncating behavior by specifying <code>count</code> equal to the size of the destination array minus one: it will copy the first <code>count</code> bytes and append the null terminator as always: <code>strncpy_s(dst, sizeof dst, src, (sizeof dst)-1);</code></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#define __STDC_WANT_LIB_EXT1__ 1 +#include <string.h> +#include <stdio.h> +#include <stdlib.h> +#include <errno.h> + +int main(void) +{ + char src[] = "hi"; + char dest[6] = "abcdef"; // no null terminator + strncpy(dest, src, 5); // writes five characters 'h', 'i', '\0', '\0', '\0' to dest + printf("strncpy(dest, src, 5) to a 6-byte dest gives : "); + for (size_t n = 0; n < sizeof dest; ++n) { + char c = dest[n]; + c ? printf("'%c' ", c) : printf("'\\0' "); + } + + printf("\nstrncpy(dest2, src, 2) to a 2-byte dst gives : "); + char dest2[2]; + strncpy(dest2, src, 2); // truncation: writes two characters 'h', 'i', to dest2 + for (size_t n = 0; n < sizeof dest2; ++n) { + char c = dest2[n]; + c ? printf("'%c' ", c) : printf("'\\0' "); + } + printf("\n"); + +#ifdef __STDC_LIB_EXT1__ + set_constraint_handler_s(ignore_handler_s); + char dst1[6], src1[100] = "hello"; + errno_t r1 = strncpy_s(dst1, 6, src1, 100); // writes 0 to r1, 6 characters to dst1 + printf("dst1 = \"%s\", r1 = %d\n", dst1,r1); // 'h','e','l','l','o','\0' to dst1 + + char dst2[5], src2[7] = {'g','o','o','d','b','y','e'}; + errno_t r2 = strncpy_s(dst2, 5, src2, 7); // copy overflows the destination array + printf("dst2 = \"%s\", r2 = %d\n", dst2,r2); // writes nonzero to r2,'\0' to dst2[0] + + char dst3[5]; + errno_t r3 = strncpy_s(dst3, 5, src2, 4); // writes 0 to r3, 5 characters to dst3 + printf("dst3 = \"%s\", r3 = %d\n", dst3,r3); // 'g', 'o', 'o', 'd', '\0' to dst3 +#endif +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">strncpy(dest, src, 5) to a 6-byte dst gives : 'h' 'i' '\0' '\0' '\0' 'f' +strncpy(dest2, src, 2) to a 2-byte dst gives : 'h' 'i' +dst1 = "hello", r1 = 0 +dst2 = "", r2 = 22 +dst3 = "good", r3 = 0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.24.2.4 The strncpy function (p: 265) </li> +<li> K.3.7.1.4 The strncpy_s function (p: 447-448) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.24.2.4 The strncpy function (p: 363-364) </li> +<li> K.3.7.1.4 The strncpy_s function (p: 616-617) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.2.4 The strncpy function (p: 326-327) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.2.4 The strncpy function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="strcpy" title="c/string/byte/strcpy"> <span class="t-lines"><span>strcpy</span><span>strcpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies one string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="memcpy" title="c/string/byte/memcpy"> <span class="t-lines"><span>memcpy</span><span>memcpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies one buffer to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="https://en.cppreference.com/w/c/experimental/dynamic/strndup" title="c/experimental/dynamic/strndup"> <span class="t-lines"><span>strndup</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-dynamic-tr t-mark-ts">(dynamic memory TR)</span></span></span></div> </td> <td> allocate a copy of a string up to specified size <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/strncpy" title="cpp/string/byte/strncpy">C++ documentation</a></span> for <code>strncpy</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strncpy" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strncpy</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrndup.html b/devdocs/c/string%2Fbyte%2Fstrndup.html new file mode 100644 index 00000000..74cb2101 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrndup.html @@ -0,0 +1,46 @@ + <h1 id="firstHeading" class="firstHeading">strndup</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">char *strndup( const char *src, size_t size );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <p>Returns a pointer to a null-terminated byte string, which contains copies of at most <code>size</code> bytes from the string pointed to by <code>src</code>. The space for the new string is obtained as if <code><a href="../../memory/malloc" title="c/memory/malloc">malloc</a></code> was called. If the null terminator is not encountered in the first <code>size</code> bytes, it is appended to the duplicated string.</p> +<p>The returned pointer must be passed to <code><a href="../../memory/free" title="c/memory/free">free</a></code> to avoid a memory leak.</p> +<p>If an error occurs, a null pointer is returned and <code><a href="../../error/errno" title="c/error/errno">errno</a></code> might be set.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the null-terminated byte string to duplicate </td> +</tr> <tr class="t-par"> <td> size </td> <td> - </td> <td> max number of bytes to copy from <code>src</code> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>A pointer to the newly allocated string, or a null pointer if an error occurred.</p> +<h3 id="Notes"> Notes</h3> <p>The function is identical to the <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/strdup.html">POSIX strndup</a> except that it is allowed, but not required to set <code><a href="../../error/errno" title="c/error/errno">errno</a></code> on error.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <string.h> +#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + const size_t n = 3; + + const char *src = "Replica"; + char *dup = strndup(src, n); + printf("strndup(\"%s\", %lu) == \"%s\"\n", src, n, dup); + free(dup); + + src = "Hi"; + dup = strndup(src, n); + printf("strndup(\"%s\", %lu) == \"%s\"\n", src, n, dup); + free(dup); + + const char arr[] = {'A','B','C','D'}; // NB: no trailing '\0' + dup = strndup(arr, n); + printf("strndup({'A','B','C','D'}, %lu) == \"%s\"\n", n, dup); + free(dup); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">strndup("Replica", 3) == "Rep" +strndup("Hi", 3) == "Hi" +strndup({'A','B','C','D'}, 3) == "ABC"</pre></div> </div> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="strdup" title="c/string/byte/strdup"> <span class="t-lines"><span>strdup</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> allocates a copy of a string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strcpy" title="c/string/byte/strcpy"> <span class="t-lines"><span>strcpy</span><span>strcpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies one string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../../memory/malloc" title="c/memory/malloc"> <span class="t-lines"><span>malloc</span></span></a></div> </td> <td> allocates memory <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../../memory/free" title="c/memory/free"> <span class="t-lines"><span>free</span></span></a></div> </td> <td> deallocates previously allocated memory <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strndup" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strndup</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrpbrk.html b/devdocs/c/string%2Fbyte%2Fstrpbrk.html new file mode 100644 index 00000000..7b5f44dc --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrpbrk.html @@ -0,0 +1,49 @@ + <h1 id="firstHeading" class="firstHeading">strpbrk</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">char *strpbrk( const char *dest, const char *breakset );</pre> +</td> <td> (1) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">/*QChar*/ *strpbrk( /*QChar*/ *dest, const char *breakset );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1 )</span> Scans the null-terminated byte string pointed to by <code>dest</code> for any character from the null-terminated byte string pointed to by <code>breakset</code>, and returns a pointer to that character.</div> <div class="t-li1"> +<span class="t-li">2)</span> Type-generic function equivalent to <span class="t-v">(1)</span>. Let <code>T</code> be an unqualified character object type. <ul> +<li> If <code>dest</code> is of type <code>const T*</code>, the return type is <code>const char*</code>. </li> +<li> Otherwise, if <code>dest</code> is of type <code>T*</code>, the return type is <code>char*</code>. </li> +<li> Otherwise, the behavior is undefined. </li> +</ul> If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if <code>(strpbrk)</code> or a function pointer is used), the actual function declaration <span class="t-v">(1)</span> becomes visible.</div> <p>The behavior is undefined if either <code>dest</code> or <code>breakset</code> is not a pointer to a null-terminated byte string.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the null-terminated byte string to be analyzed </td> +</tr> <tr class="t-par"> <td> breakset </td> <td> - </td> <td> pointer to the null-terminated byte string that contains the characters to search for </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Pointer to the first character in <code>dest</code>, that is also in <code>breakset</code>, or null pointer if no such character exists.</p> +<h3 id="Notes"> Notes</h3> <p>The name stands for "string pointer break", because it returns a pointer to the first of the separator ("break") characters.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <string.h> + +int main(void) +{ + const char* str = "hello world, friend of mine!"; + const char* sep = " ,!"; + + unsigned int cnt = 0; + do { + str = strpbrk(str, sep); // find separator + if(str) str += strspn(str, sep); // skip separator + ++cnt; // increment word count + } while(str && *str); + + printf("There are %u words\n", cnt); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">There are 5 words</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.24.5.4 The strpbrk function (p: 368) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.5.4 The strpbrk function (p: 331) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.5.4 The strpbrk function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="strcspn" title="c/string/byte/strcspn"> <span class="t-lines"><span>strcspn</span></span></a></div> </td> <td> returns the length of the maximum initial segment that consists <br> of only the characters not found in another byte string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strchr" title="c/string/byte/strchr"> <span class="t-lines"><span>strchr</span></span></a></div> </td> <td> finds the first occurrence of a character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strtok" title="c/string/byte/strtok"> <span class="t-lines"><span>strtok</span><span>strtok_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> finds the next token in a byte string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/strpbrk" title="cpp/string/byte/strpbrk">C++ documentation</a></span> for <code>strpbrk</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strpbrk" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strpbrk</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrrchr.html b/devdocs/c/string%2Fbyte%2Fstrrchr.html new file mode 100644 index 00000000..62efabfe --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrrchr.html @@ -0,0 +1,39 @@ + <h1 id="firstHeading" class="firstHeading">strrchr</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">char *strrchr( const char *str, int ch );</pre> +</td> <td> (1) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">/*QChar*/ *strrchr( /*QChar*/ *str, int ch );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Finds the last occurrence of <code>ch</code> (after conversion to <code>char</code> as if by <code>(char)ch</code>) in the null-terminated byte string pointed to by <code>str</code> (each character interpreted as <code>unsigned char</code>). The terminating null character is considered to be a part of the string and can be found if searching for <code>'\0'</code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Type-generic function equivalent to <span class="t-v">(1)</span>. Let <code>T</code> be an unqualified character object type. <ul> +<li> If <code>str</code> is of type <code>const T*</code>, the return type is <code>const char*</code>. </li> +<li> Otherwise, if <code>str</code> is of type <code>T*</code>, the return type is <code>char*</code>. </li> +<li> Otherwise, the behavior is undefined. </li> +</ul> If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if <code>(strrchr)</code> or a function pointer is used), the actual function declaration <span class="t-v">(1)</span> becomes visible.</div> <p>The behavior is undefined if <code>str</code> is not a pointer to a null-terminated byte string.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> pointer to the null-terminated byte string to be analyzed </td> +</tr> <tr class="t-par"> <td> ch </td> <td> - </td> <td> character to search for </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Pointer to the found character in <code>str</code>, or null pointer if no such character is found.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <string.h> +#include <stdio.h> + +int main(void) +{ + char szSomeFileName[] = "foo/bar/foobar.txt"; + char *pLastSlash = strrchr(szSomeFileName, '/'); + char *pszBaseName = pLastSlash ? pLastSlash + 1 : szSomeFileName; + printf("Base Name: %s", pszBaseName); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Base Name: foobar.txt</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.24.5.5 The strrchr function (p: 368-369) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.5.5 The strrchr function (p: 331) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.5.5 The strrchr function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="strchr" title="c/string/byte/strchr"> <span class="t-lines"><span>strchr</span></span></a></div> </td> <td> finds the first occurrence of a character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strpbrk" title="c/string/byte/strpbrk"> <span class="t-lines"><span>strpbrk</span></span></a></div> </td> <td> finds the first location of any character in one string, in another string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/strrchr" title="cpp/string/byte/strrchr">C++ documentation</a></span> for <code>strrchr</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strrchr" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strrchr</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrspn.html b/devdocs/c/string%2Fbyte%2Fstrspn.html new file mode 100644 index 00000000..1d11b48e --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrspn.html @@ -0,0 +1,38 @@ + <h1 id="firstHeading" class="firstHeading">strspn</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">size_t strspn( const char *dest, const char *src );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Returns the length of the maximum initial segment (span) of the null-terminated byte string pointed to by <code>dest</code>, that consists of only the characters found in the null-terminated byte string pointed to by <code>src</code>.</p> +<p>The behavior is undefined if either <code>dest</code> or <code>src</code> is not a pointer to a null-terminated byte string.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the null-terminated byte string to be analyzed </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the null-terminated byte string that contains the characters to search for </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The length of the maximum initial segment that contains only characters from the null-terminated byte string pointed to by <code>src</code></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <string.h> +#include <stdio.h> + +int main(void) +{ + const char *string = "abcde312$#@"; + const char *low_alpha = "qwertyuiopasdfghjklzxcvbnm"; + + size_t spnsz = strspn(string, low_alpha); + printf("After skipping initial lowercase letters from '%s'\n" + "The remainder is '%s'\n", string, string+spnsz); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">After skipping initial lowercase letters from 'abcde312$#@' +The remainder is '312$#@'</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.24.5.6 The strspn function (p: 369) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.5.6 The strspn function (p: 332) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.5.6 The strspn function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="strcspn" title="c/string/byte/strcspn"> <span class="t-lines"><span>strcspn</span></span></a></div> </td> <td> returns the length of the maximum initial segment that consists <br> of only the characters not found in another byte string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../wide/wcsspn" title="c/string/wide/wcsspn"> <span class="t-lines"><span>wcsspn</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> returns the length of the maximum initial segment that consists <br> of only the wide characters found in another wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strpbrk" title="c/string/byte/strpbrk"> <span class="t-lines"><span>strpbrk</span></span></a></div> </td> <td> finds the first location of any character in one string, in another string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/strspn" title="cpp/string/byte/strspn">C++ documentation</a></span> for <code>strspn</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strspn" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strspn</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrstr.html b/devdocs/c/string%2Fbyte%2Fstrstr.html new file mode 100644 index 00000000..0d03ea16 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrstr.html @@ -0,0 +1,56 @@ + <h1 id="firstHeading" class="firstHeading">strstr</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">char *strstr( const char *str, const char *substr );</pre> +</td> <td> (1) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">/*QChar*/ *strstr( /*QChar*/ *str, const char *substr );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Finds the first occurrence of the null-terminated byte string pointed to by <code>substr</code> in the null-terminated byte string pointed to by <code>str</code>. The terminating null characters are not compared.</div> <div class="t-li1"> +<span class="t-li">2)</span> Type-generic function equivalent to <span class="t-v">(1)</span>. Let <code>T</code> be an unqualified character object type. <ul> +<li> If <code>str</code> is of type <code>const T*</code>, the return type is <code>const char*</code>. </li> +<li> Otherwise, if <code>str</code> is of type <code>T*</code>, the return type is <code>char*</code>. </li> +<li> Otherwise, the behavior is undefined. </li> +</ul> If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if <code>(strstr)</code> or a function pointer is used), the actual function declaration <span class="t-v">(1)</span> becomes visible.</div> <p>The behavior is undefined if either <code>str</code> or <code>substr</code> is not a pointer to a null-terminated byte string.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> pointer to the null-terminated byte string to examine </td> +</tr> <tr class="t-par"> <td> substr </td> <td> - </td> <td> pointer to the null-terminated byte string to search for </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Pointer to the first character of the found substring in <code>str</code>, or a null pointer if such substring is not found. If <code>substr</code> points to an empty string, <code>str</code> is returned.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <string.h> +#include <stdio.h> + +void find_str(char const *str, char const *substr) +{ + char *pos = strstr(str, substr); + pos ? printf("found the string '%s' in '%s' at position %td\n", + substr, str, pos - str) + : printf("the string '%s' was not found in '%s'\n", + substr, str); +} + +int main(void) +{ + char *str = "one two three"; + find_str(str, "two"); + find_str(str, ""); + find_str(str, "nine"); + find_str(str, "n"); + + return 0; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">found the string 'two' in 'one two three' at position 4 +found the string '' in 'one two three' at position 0 +the string 'nine' was not found in 'one two three' +found the string 'n' in 'one two three' at position 1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.24.5.7 The strstr function (p: 269) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.24.5.7 The strstr function (p: 369) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.5.7 The strstr function (p: 332) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.5.7 The strstr function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="strchr" title="c/string/byte/strchr"> <span class="t-lines"><span>strchr</span></span></a></div> </td> <td> finds the first occurrence of a character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strrchr" title="c/string/byte/strrchr"> <span class="t-lines"><span>strrchr</span></span></a></div> </td> <td> finds the last occurrence of a character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/strstr" title="cpp/string/byte/strstr">C++ documentation</a></span> for <code>strstr</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strstr" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strstr</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrtof.html b/devdocs/c/string%2Fbyte%2Fstrtof.html new file mode 100644 index 00000000..b3be49b7 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrtof.html @@ -0,0 +1,90 @@ + <h1 id="firstHeading" class="firstHeading">strtof, strtod, strtold</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float strtof( const char *restrict str, char **restrict str_end );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-until-c99"> <td><pre data-language="c">double strtod( const char *str, char **str_end );</pre></td> <td class="t-dcl-nopad"> </td> <td><span class="t-mark-rev t-until-c99">(until C99)</span></td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double strtod( const char *restrict str, char **restrict str_end );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double strtold( const char *restrict str, char **restrict str_end );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Interprets a floating-point value in a byte string pointed to by <code>str</code>.</p> +<p>Function discards any whitespace characters (as determined by <code><a href="isspace" title="c/string/byte/isspace">isspace</a></code>) until first non-whitespace character is found. Then it takes as many characters as possible to form a valid floating-point representation and converts them to a floating-point value. The valid floating-point value can be one of the following:</p> +<ul> +<li>decimal floating-point expression. It consists of the following parts: </li> +<ul> +<li> <span class="t-mark">(optional)</span> plus or minus sign </li> +<li> nonempty sequence of decimal digits optionally containing decimal-point character (as determined by the current C <a href="../../locale/setlocale" title="c/locale/setlocale">locale</a>) (defines significand) </li> +<li> <span class="t-mark">(optional)</span> <code>e</code> or <code>E</code> followed with optional minus or plus sign and nonempty sequence of decimal digits (defines exponent to base 10) </li> +</ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <ul> +<li>hexadecimal floating-point expression. It consists of the following parts: </li> +<ul> +<li> <span class="t-mark">(optional)</span> plus or minus sign </li> +<li> <code>0x</code> or <code>0X</code> </li> +<li> nonempty sequence of hexadecimal digits optionally containing a decimal-point character (as determined by the current C <a href="../../locale/setlocale" title="c/locale/setlocale">locale</a>) (defines significand) </li> +<li> <span class="t-mark">(optional)</span> <code>p</code> or <code>P</code> followed with optional minus or plus sign and nonempty sequence of decimal digits (defines exponent to base 2) </li> +</ul> +<li> infinity expression. It consists of the following parts: </li> +<ul> +<li> <span class="t-mark">(optional)</span> plus or minus sign </li> +<li> <code>INF</code> or <code>INFINITY</code> ignoring case </li> +</ul> +<li> not-a-number expression. It consists of the following parts: </li> +<ul> +<li> <span class="t-mark">(optional)</span> plus or minus sign </li> +<li> <code>NAN</code> or <code>NAN(</code><i>char_sequence</i><code>)</code> ignoring case of the <code>NAN</code> part. <i>char_sequence</i> can only contain digits, Latin letters, and underscores. The result is a quiet NaN floating-point value. </li> +</ul> +</ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <ul><li> any other expression that may be accepted by the currently installed C <a href="../../locale/setlocale" title="c/locale/setlocale">locale</a> </li></ul> <p>The functions sets the pointer pointed to by <code>str_end</code> to point to the character past the last character interpreted. If <code>str_end</code> is a null pointer, it is ignored.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> pointer to the null-terminated byte string to be interpreted </td> +</tr> <tr class="t-par"> <td> str_end </td> <td> - </td> <td> pointer to a pointer to character. </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Floating-point value corresponding to the contents of <code>str</code> on success. If the converted value falls out of range of corresponding return type, range error occurs (<code><a href="../../error/errno" title="c/error/errno">errno</a></code> is set to <code><a href="../../error/errno_macros" title="c/error/errno macros">ERANGE</a></code>) and <code><a href="../../numeric/math/huge_val" title="c/numeric/math/HUGE VAL">HUGE_VAL</a></code>, <code><a href="../../numeric/math/huge_val" title="c/numeric/math/HUGE VAL">HUGE_VALF</a></code> or <code><a href="../../numeric/math/huge_val" title="c/numeric/math/HUGE VAL">HUGE_VALL</a></code> is returned. If no conversion can be performed, <code>0</code> is returned.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <errno.h> +#include <stdlib.h> + +int main(void) +{ + // parsing with error handling + const char *p = "111.11 -2.22 Nan nan(2) inF 0X1.BC70A3D70A3D7P+6 1.18973e+4932zzz"; + printf("Parsing '%s':\n", p); + char *end; + for (double f = strtod(p, &end); p != end; f = strtod(p, &end)) + { + printf("'%.*s' -> ", (int)(end-p), p); + p = end; + if (errno == ERANGE){ + printf("range error, got "); + errno = 0; + } + printf("%f\n", f); + } + + // parsing without error handling + printf("\" -0.0000000123junk\" --> %g\n", strtod(" -0.0000000123junk", NULL)); + printf("\"junk\" --> %g\n", strtod("junk", NULL)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Parsing '111.11 -2.22 Nan nan(2) inF 0X1.BC70A3D70A3D7P+6 1.18973e+4932zzz': +'111.11' -> 111.110000 +' -2.22' -> -2.220000 +' Nan' -> nan +' nan(2)' -> nan +' inF' -> inf +' 0X1.BC70A3D70A3D7P+6' -> 111.110000 +' 1.18973e+4932' -> range error, got inf +" -0.0000000123junk" --> -1.23e-08 +"junk" --> 0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22.1.3 The strtod, strtof, and strtold functions (p: 249-251) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.1.3 The strtod, strtof, and strtold functions (p: 342-344) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.1.3 The strtod, strtof, and strtold functions (p: 308-310) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.1.4 The strtod function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="atof" title="c/string/byte/atof"> <span class="t-lines"><span>atof</span></span></a></div> </td> <td> converts a byte string to a floating-point value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../wide/wcstof" title="c/string/wide/wcstof"> <span class="t-lines"><span>wcstof</span><span>wcstod</span><span>wcstold</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a wide string to a floating-point value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/strtof" title="cpp/string/byte/strtof">C++ documentation</a></span> for <code>strtof, strtod, strtold</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strtof" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strtof</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrtoimax.html b/devdocs/c/string%2Fbyte%2Fstrtoimax.html new file mode 100644 index 00000000..2e199efe --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrtoimax.html @@ -0,0 +1,78 @@ + <h1 id="firstHeading" class="firstHeading">strtoimax, strtoumax</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><inttypes.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">intmax_t strtoimax( const char *restrict nptr, + char **restrict endptr, int base );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">uintmax_t strtoumax( const char *restrict nptr, + char **restrict endptr, int base );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Interprets an integer value in a byte string pointed to by <code>nptr</code>.</p> +<p>Discards any whitespace characters (as identified by calling <a href="isspace" title="c/string/byte/isspace"><code>isspace</code></a>) until the first non-whitespace character is found, then takes as many characters as possible to form a valid <i>base-n</i> (where n=<code>base</code>) integer number representation and converts them to an integer value. The valid integer value consists of the following parts:</p> +<ul> +<li> <span class="t-mark">(optional)</span> plus or minus sign </li> +<li> <span class="t-mark">(optional)</span> prefix (<code>0</code>) indicating octal base (applies only when the base is <code>8</code> or <code>0</code>) </li> +<li> <span class="t-mark">(optional)</span> prefix (<code>0x</code> or <code>0X</code>) indicating hexadecimal base (applies only when the base is <code>16</code> or <code>0</code>) </li> +<li> a sequence of digits </li> +</ul> <p>The set of valid values for base is <code>{0,2,3,...,36}.</code> The set of valid digits for base-<code>2</code> integers is <code>{0,1},</code> for base-<code>3</code> integers is <code>{0,1,2},</code> and so on. For bases larger than <code>10</code>, valid digits include alphabetic characters, starting from <code>Aa</code> for base-<code>11</code> integer, to <code>Zz</code> for base-<code>36</code> integer. The case of the characters is ignored.</p> +<p>Additional numeric formats may be accepted by the currently installed C <a href="../../locale/setlocale" title="c/locale/setlocale">locale</a>.</p> +<p>If the value of <code>base</code> is <code>0</code>, the numeric base is auto-detected: if the prefix is <code>0</code>, the base is octal, if the prefix is <code>0x</code> or <code>0X</code>, the base is hexadecimal, otherwise the base is decimal.</p> +<p>If the minus sign was part of the input sequence, the numeric value calculated from the sequence of digits is negated as if by <a href="../../language/operator_arithmetic#Unary_arithmetic" title="c/language/operator arithmetic">unary minus</a> in the result type.</p> +<p>The functions sets the pointer pointed to by <code>endptr</code> to point to the character past the last character interpreted. If <code>endptr</code> is a null pointer, it is ignored.</p> +<p>If the <code>nptr</code> is empty or does not have the expected form, no conversion is performed, and (if <code>endptr</code> is not a null pointer) the value of <code>nptr</code> is stored in the object pointed to by <code>endptr</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> nptr </td> <td> - </td> <td> pointer to the null-terminated byte string to be interpreted </td> +</tr> <tr class="t-par"> <td> endptr </td> <td> - </td> <td> pointer to a pointer to character. </td> +</tr> <tr class="t-par"> <td> base </td> <td> - </td> <td> <i>base</i> of the interpreted integer value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <ul> +<li> If successful, an integer value corresponding to the contents of <code>str</code> is returned. </li> +<li> If the converted value falls out of range of corresponding return type, a range error occurs (setting <code><a href="../../error/errno" title="c/error/errno">errno</a></code> to <code><a href="../../error/errno_macros" title="c/error/errno macros">ERANGE</a></code>) and <code><a href="../../types/integer" title="c/types/integer">INTMAX_MAX</a></code>, <code><a href="../../types/integer" title="c/types/integer">INTMAX_MIN</a></code>, <code><a href="../../types/integer" title="c/types/integer">UINTMAX_MAX</a></code> or <code>0</code> is returned, as appropriate. </li> +<li> If no conversion can be performed, <code>0</code> is returned. </li> +</ul> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <errno.h> +#include <inttypes.h> +#include <stdio.h> +#include <string.h> + +int main(void) +{ + char* endptr; + + printf("%ld\n", strtoimax(" -123junk",&endptr,10)); /* base 10 */ + printf("%ld\n", strtoimax("11111111",&endptr,2)); /* base 2 */ + printf("%ld\n", strtoimax("XyZ",&endptr,36)); /* base 36 */ + printf("%ld\n", strtoimax("010",&endptr,0)); /* octal auto-detection */ + printf("%ld\n", strtoimax("10",&endptr,0)); /* decimal auto-detection */ + printf("%ld\n", strtoimax("0x10",&endptr,0)); /* hexadecimal auto-detection */ + + /* range error */ + /* LONG_MAX+1 --> LONG_MAX */ + errno = 0; + printf("%ld\n", strtoimax("9223372036854775808",&endptr,10)); + printf("%s\n", strerror(errno)); + + return 0; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">-123 +255 +44027 +8 +10 +16 +9223372036854775807 +Numerical result out of range</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.8.2.3 The strtoimax and strtoumax functions (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.8.2.3 The strtoimax and strtoumax functions (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.8.2.3 The strtoimax and strtoumax functions (p: 219) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.8.2.3 The strtoimax and strtoumax functions (p: 200) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../wide/wcstoimax" title="c/string/wide/wcstoimax"> <span class="t-lines"><span>wcstoimax</span><span>wcstoumax</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a wide string to <code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw118">intmax_t</span></a></code> or <code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw132">uintmax_t</span></a></code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strtol" title="c/string/byte/strtol"> <span class="t-lines"><span>strtol</span><span>strtoll</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a byte string to an integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strtoul" title="c/string/byte/strtoul"> <span class="t-lines"><span>strtoul</span><span> strtoull</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a byte string to an unsigned integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/strtoimax" title="cpp/string/byte/strtoimax">C++ documentation</a></span> for <code>strtoimax, strtoumax</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strtoimax" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strtoimax</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrtok.html b/devdocs/c/string%2Fbyte%2Fstrtok.html new file mode 100644 index 00000000..09405556 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrtok.html @@ -0,0 +1,108 @@ + <h1 id="firstHeading" class="firstHeading">strtok, strtok_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-until-c99"> <td><pre data-language="c">char *strtok( char *str, const char *delim );</pre></td> <td><span class="t-mark-rev t-until-c99">(until C99)</span></td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">char *strtok( char *restrict str, const char *restrict delim );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">char *strtok_s(char *restrict str, rsize_t *restrict strmax, + const char *restrict delim, char **restrict ptr);</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Finds the next token in a null-terminated byte string pointed to by <code>str</code>. The separator characters are identified by null-terminated byte string pointed to by <code>delim</code>.</div> <div class="t-li1"> + This function is designed to be called multiple times to obtain successive tokens from the same string.</div> <ul> +<li> If <code>str</code> is not a null pointer, the call is treated as the first call to <code>strtok</code> for this particular string. The function searches for the first character which is <i>not</i> contained in <code>delim</code>. </li> +<li> If no such character was found, there are no tokens in <code>str</code> at all, and the function returns a null pointer. </li> +<li> If such character was found, it is the <i>beginning of the token</i>. The function then searches from that point on for the first character that <i>is</i> contained in <code>delim</code>. </li> +<ul> +<li> If no such character was found, <code>str</code> has only one token, and future calls to <code>strtok</code> will return a null pointer </li> +<li> If such character was found, it is <i>replaced</i> by the null character <code>'\0'</code> and the pointer to the following character is stored in a static location for subsequent invocations. </li> +</ul> +<li> The function then returns the pointer to the beginning of the token </li> +<li> If <code>str</code> is a null pointer, the call is treated as a subsequent call to <code>strtok</code>: the function continues from where it left in previous invocation. The behavior is the same as if the previously stored pointer is passed as <code>str</code>. </li> +</ul> <div class="t-li1"> + The behavior is undefined if either <code>str</code> or <code>delim</code> is not a pointer to a null-terminated byte string.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that on every step, writes the number of characters left to see in <code>str</code> into <code>*strmax</code> and writes the tokenizer's internal state to <code>*ptr</code>. Repeat calls (with null <code>str</code>) must pass <code>strmax</code> and <code>ptr</code> with the values stored by the previous call. Also, the following errors are detected at runtime and call the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function, without storing anything in the object pointed to by <code>ptr</code> <ul> +<li> <code>strmax</code>, <code>delim</code>, or <code>ptr</code> is a null pointer </li> +<li> on a non-initial call (with null <code>str</code>), <code>*ptr</code> is a null pointer </li> +<li> on the first call, <code>*strmax</code> is zero or greater than <code>RSIZE_MAX</code> </li> +<li> search for the end of a token reaches the end of the source string (as measured by the initial value of <code>*strmax</code>) without encountering the null terminator</li> +</ul> +</div> <div class="t-li1"> + The behavior is undefined if both <code>str</code> points to a character array which lacks the null character and <code>strmax</code> points to a value which is greater than the size of that character array. As with all bounds-checked functions, <code>strtok_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../byte" title="c/string/byte"><code><string.h></code></a>.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> pointer to the null-terminated byte string to tokenize </td> +</tr> <tr class="t-par"> <td> delim </td> <td> - </td> <td> pointer to the null-terminated byte string identifying delimiters </td> +</tr> <tr class="t-par"> <td> strmax </td> <td> - </td> <td> pointer to an object which initially holds the size of <code>str</code>: strtok_s stores the number of characters that remain to be examined </td> +</tr> <tr class="t-par"> <td> ptr </td> <td> - </td> <td> pointer to an object of type <code>char*</code>, which is used by strtok_s to store its internal state </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Returns pointer to the beginning of the next token or a null pointer if there are no more tokens.</p> +<h3 id="Note"> Note</h3> <p>This function is destructive: it writes the <code>'\0'</code> characters in the elements of the string <code>str</code>. In particular, a string literal cannot be used as the first argument of <code>strtok</code>.</p> +<p>Each call to <code>strtok</code> modifies a static variable: is not thread safe.</p> +<p>Unlike most other tokenizers, the delimiters in <code>strtok</code> can be different for each subsequent token, and can even depend on the contents of the previous tokens.</p> +<p>The <code>strtok_s</code> function differs from the POSIX <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/strtok.html"><code>strtok_r</code></a> function by guarding against storing outside of the string being tokenized, and by checking runtime constraints. The Microsoft CRT <code>strtok_s</code> signature matches this POSIX <code>strtok_r</code> definition, not the C11 <code>strtok_s</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#define __STDC_WANT_LIB_EXT1__ 1 +#include <string.h> +#include <stdio.h> + +int main(void) +{ + char input[] = "A bird came down the walk"; + printf("Parsing the input string '%s'\n", input); + char *token = strtok(input, " "); + while(token) { + puts(token); + token = strtok(NULL, " "); + } + + printf("Contents of the input string now: '"); + for(size_t n = 0; n < sizeof input; ++n) + input[n] ? putchar(input[n]) : fputs("\\0", stdout); + puts("'"); + +#ifdef __STDC_LIB_EXT1__ + char str[] = "A bird came down the walk"; + rsize_t strmax = sizeof str; + const char *delim = " "; + char *next_token; + printf("Parsing the input string '%s'\n", str); + token = strtok_s(str, &strmax, delim, &next_token); + while(token) { + puts(token); + token = strtok_s(NULL, &strmax, delim, &next_token); + } + + printf("Contents of the input string now: '"); + for(size_t n = 0; n < sizeof str; ++n) + str[n] ? putchar(str[n]) : fputs("\\0", stdout); + puts("'"); +#endif +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Parsing the input string 'A bird came down the walk' +A +bird +came +down +the +walk +Contents of the input string now: 'A\0bird\0came\0down\0the\0walk\0' +Parsing the input string 'A bird came down the walk' +A +bird +came +down +the +walk +Contents of the input string now: 'A\0bird\0came\0down\0the\0walk\0'</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.24.5.8 The strtok function (p: 369-370) </li> +<li> K.3.7.3.1 The strtok_s function (p: 620-621) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.5.8 The strtok function (p: 332-333) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.5.8 The strtok function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="strpbrk" title="c/string/byte/strpbrk"> <span class="t-lines"><span>strpbrk</span></span></a></div> </td> <td> finds the first location of any character in one string, in another string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strcspn" title="c/string/byte/strcspn"> <span class="t-lines"><span>strcspn</span></span></a></div> </td> <td> returns the length of the maximum initial segment that consists <br> of only the characters not found in another byte string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strspn" title="c/string/byte/strspn"> <span class="t-lines"><span>strspn</span></span></a></div> </td> <td> returns the length of the maximum initial segment that consists <br> of only the characters found in another byte string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../wide/wcstok" title="c/string/wide/wcstok"> <span class="t-lines"><span>wcstok</span><span>wcstok_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> finds the next token in a wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/strtok" title="cpp/string/byte/strtok">C++ documentation</a></span> for <code>strtok</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strtok" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strtok</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrtol.html b/devdocs/c/string%2Fbyte%2Fstrtol.html new file mode 100644 index 00000000..5b16e65b --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrtol.html @@ -0,0 +1,105 @@ + <h1 id="firstHeading" class="firstHeading">strtol, strtoll</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-until-c99"> <td><pre data-language="c">long strtol( const char *str, char **str_end, int base );</pre></td> <td class="t-dcl-nopad"> </td> <td><span class="t-mark-rev t-until-c99">(until C99)</span></td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long strtol( const char *restrict str, char **restrict str_end, int base );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long long strtoll( const char *restrict str, char **restrict str_end, int base );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Interprets an integer value in a byte string pointed to by <code>str</code>.</p> +<p>Discards any whitespace characters (as identified by calling <a href="isspace" title="c/string/byte/isspace"><code>isspace</code></a>) until the first non-whitespace character is found, then takes as many characters as possible to form a valid <i>base-n</i> (where n=<code>base</code>) integer number representation and converts them to an integer value. The valid integer value consists of the following parts:</p> +<ul> +<li> <span class="t-mark">(optional)</span> plus or minus sign </li> +<li> <span class="t-mark">(optional)</span> prefix (<code>0</code>) indicating octal base (applies only when the base is <code>8</code> or <code>0</code>) </li> +<li> <span class="t-mark">(optional)</span> prefix (<code>0x</code> or <code>0X</code>) indicating hexadecimal base (applies only when the base is <code>16</code> or <code>0</code>) </li> +<li> a sequence of digits </li> +</ul> <p>The set of valid values for base is <code>{0,2,3,...,36}.</code> The set of valid digits for base-<code>2</code> integers is <code>{0,1},</code> for base-<code>3</code> integers is <code>{0,1,2},</code> and so on. For bases larger than <code>10</code>, valid digits include alphabetic characters, starting from <code>Aa</code> for base-<code>11</code> integer, to <code>Zz</code> for base-<code>36</code> integer. The case of the characters is ignored.</p> +<p>Additional numeric formats may be accepted by the currently installed C <a href="../../locale/setlocale" title="c/locale/setlocale">locale</a>.</p> +<p>If the value of <code>base</code> is <code>0</code>, the numeric base is auto-detected: if the prefix is <code>0</code>, the base is octal, if the prefix is <code>0x</code> or <code>0X</code>, the base is hexadecimal, otherwise the base is decimal.</p> +<p>If the minus sign was part of the input sequence, the numeric value calculated from the sequence of digits is negated as if by <a href="../../language/operator_arithmetic#Unary_arithmetic" title="c/language/operator arithmetic">unary minus</a> in the result type.</p> +<p>The functions set the pointer pointed to by <code>str_end</code> to point to the character past the last numeric character interpreted. If <code>str_end</code> is a null pointer, it is ignored.</p> +<p>If the <code>str</code> is empty or does not have the expected form, no conversion is performed, and (if <code>str_end</code> is not a null pointer) the value of <code>str</code> is stored in the object pointed to by <code>str_end</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> pointer to the null-terminated byte string to be interpreted </td> +</tr> <tr class="t-par"> <td> str_end </td> <td> - </td> <td> pointer to a pointer to character. </td> +</tr> <tr class="t-par"> <td> base </td> <td> - </td> <td> <i>base</i> of the interpreted integer value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <ul> +<li> If successful, an integer value corresponding to the contents of <code>str</code> is returned. </li> +<li> If the converted value falls out of range of corresponding return type, a range error occurs (setting <code><a href="../../error/errno" title="c/error/errno">errno</a></code> to <code><a href="../../error/errno_macros" title="c/error/errno macros">ERANGE</a></code>) and <code><a href="../../types/limits" title="c/types/limits">LONG_MAX</a></code>, <code><a href="../../types/limits" title="c/types/limits">LONG_MIN</a></code>, <code><a href="../../types/limits" title="c/types/limits">LLONG_MAX</a></code> or <code><a href="../../types/limits" title="c/types/limits">LLONG_MIN</a></code> is returned. </li> +<li> If no conversion can be performed, <code>0</code> is returned. </li> +</ul> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <errno.h> +#include <limits.h> +#include <stdbool.h> +#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + // parsing with error handling + const char *p = "10 200000000000000000000000000000 30 -40 junk"; + printf("Parsing '%s':\n", p); + + for (;;) + { + // errno can be set to any non-zero value by a library function call + // regardless of whether there was an error, so it needs to be cleared + // in order to check the error set by strtol + errno = 0; + char *end; + const long i = strtol(p, &end, 10); + if (p == end) + break; + + const bool range_error = errno == ERANGE; + printf("Extracted '%.*s', strtol returned %ld.", (int)(end-p), p, i); + p = end; + + if (range_error) + printf("\n --> Range error occurred."); + + putchar('\n'); + } + + printf("Unextracted leftover: '%s'\n\n", p); + + // parsing without error handling + printf("\"1010\" in binary --> %ld\n", strtol("1010", NULL, 2)); + printf("\"12\" in octal --> %ld\n", strtol("12", NULL, 8)); + printf("\"A\" in hex --> %ld\n", strtol("A", NULL, 16)); + printf("\"junk\" in base-36 --> %ld\n", strtol("junk", NULL, 36)); + printf("\"012\" in auto-detected base --> %ld\n", strtol("012", NULL, 0)); + printf("\"0xA\" in auto-detected base --> %ld\n", strtol("0xA", NULL, 0)); + printf("\"junk\" in auto-detected base --> %ld\n", strtol("junk", NULL, 0)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Parsing '10 200000000000000000000000000000 30 -40 junk': +Extracted '10', strtol returned 10. +Extracted ' 200000000000000000000000000000', strtol returned 9223372036854775807. + --> Range error occurred. +Extracted ' 30', strtol returned 30. +Extracted ' -40', strtol returned -40. +Unextracted leftover: ' junk' + +"1010" in binary --> 10 +"12" in octal --> 10 +"A" in hex --> 10 +"junk" in base-36 --> 926192 +"012" in auto-detected base --> 10 +"0xA" in auto-detected base --> 10 +"junk" in auto-detected base --> 0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22.1.4 The strtol, strtoll, strtoul, and strtoull functions (p: 251-252) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.1.4 The strtol, strtoll, strtoul, and strtoull functions (p: 344-345) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.1.4 The strtol, strtoll, strtoul, and strtoull functions (p: 310-311) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.1.5 The strtol function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="atoi" title="c/string/byte/atoi"> <span class="t-lines"><span>atoi</span><span>atol</span><span>atoll</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a byte string to an integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strtoul" title="c/string/byte/strtoul"> <span class="t-lines"><span>strtoul</span><span> strtoull</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a byte string to an unsigned integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../wide/wcstol" title="c/string/wide/wcstol"> <span class="t-lines"><span>wcstol</span><span>wcstoll</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a wide string to an integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../wide/wcstoul" title="c/string/wide/wcstoul"> <span class="t-lines"><span>wcstoul</span><span>wcstoull</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a wide string to an unsigned integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/strtol" title="cpp/string/byte/strtol">C++ documentation</a></span> for <code>strtol, strtoll</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strtol" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strtol</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrtoul.html b/devdocs/c/string%2Fbyte%2Fstrtoul.html new file mode 100644 index 00000000..e27953c9 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrtoul.html @@ -0,0 +1,75 @@ + <h1 id="firstHeading" class="firstHeading">strtoul, strtoull</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-until-c99"> <td><pre data-language="c">unsigned long strtoul( const char *str, char **str_end, + int base );</pre></td> <td class="t-dcl-nopad"> </td> <td><span class="t-mark-rev t-until-c99">(until C99)</span></td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">unsigned long strtoul( const char *restrict str, char **restrict str_end, + int base );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">unsigned long long strtoull( const char *restrict str, char **restrict str_end, + int base );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Interprets an unsigned integer value in a byte string pointed to by <code>str</code>.</p> +<p>Discards any whitespace characters (as identified by calling <a href="isspace" title="c/string/byte/isspace"><code>isspace</code></a>) until the first non-whitespace character is found, then takes as many characters as possible to form a valid <i>base-n</i> (where n=<code>base</code>) unsigned integer number representation and converts them to an integer value. The valid unsigned integer value consists of the following parts:</p> +<ul> +<li> <span class="t-mark">(optional)</span> plus or minus sign </li> +<li> <span class="t-mark">(optional)</span> prefix (<code>0</code>) indicating octal base (applies only when the base is <code>8</code> or <code>0</code>) </li> +<li> <span class="t-mark">(optional)</span> prefix (<code>0x</code> or <code>0X</code>) indicating hexadecimal base (applies only when the base is <code>16</code> or <code>0</code>) </li> +<li> a sequence of digits </li> +</ul> <p>The set of valid values for base is <code>{0,2,3,...,36}.</code> The set of valid digits for base-<code>2</code> integers is <code>{0,1},</code> for base-<code>3</code> integers is <code>{0,1,2},</code> and so on. For bases larger than <code>10</code>, valid digits include alphabetic characters, starting from <code>Aa</code> for base-<code>11</code> integer, to <code>Zz</code> for base-<code>36</code> integer. The case of the characters is ignored.</p> +<p>Additional numeric formats may be accepted by the currently installed C <a href="../../locale/setlocale" title="c/locale/setlocale">locale</a>.</p> +<p>If the value of <code>base</code> is <code>0</code>, the numeric base is auto-detected: if the prefix is <code>0</code>, the base is octal, if the prefix is <code>0x</code> or <code>0X</code>, the base is hexadecimal, otherwise the base is decimal.</p> +<p>If the minus sign was part of the input sequence, the numeric value calculated from the sequence of digits is negated as if by <a href="../../language/operator_arithmetic#Unary_arithmetic" title="c/language/operator arithmetic">unary minus</a> in the result type, which applies unsigned integer wraparound rules.</p> +<p>The functions sets the pointer pointed to by <code>str_end</code> to point to the character past the last character interpreted. If <code>str_end</code> is a null pointer, it is ignored.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> pointer to the null-terminated byte string to be interpreted </td> +</tr> <tr class="t-par"> <td> str_end </td> <td> - </td> <td> pointer to a pointer to character, might be set to a position past the last character interpreted </td> +</tr> <tr class="t-par"> <td> base </td> <td> - </td> <td> <i>base</i> of the interpreted integer value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Integer value corresponding to the contents of <code>str</code> on success. If the converted value falls out of range of corresponding return type, range error occurs (<code><a href="../../error/errno" title="c/error/errno">errno</a></code> is set to <code>ERANGE</code>) and <code><a href="../../types/limits" title="c/types/limits">ULONG_MAX</a></code> or <code><a href="../../types/limits" title="c/types/limits">ULLONG_MAX</a></code> is returned. If no conversion can be performed, <code>0</code> is returned.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <errno.h> +#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + const char *p = "10 200000000000000000000000000000 30 -40 - 42"; + printf("Parsing '%s':\n", p); + char *end = NULL; + for (unsigned long i = strtoul(p, &end, 10); + p != end; + i = strtoul(p, &end, 10)) + { + printf("'%.*s' -> ", (int)(end - p), p); + p = end; + if (errno == ERANGE) + { + errno = 0; + printf("range error, got "); + } + printf("%lu\n", i); + } + printf("After the loop p points to '%s'\n", p); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Parsing '10 200000000000000000000000000000 30 -40 - 42': +'10' -> 10 +' 200000000000000000000000000000' -> range error, got 18446744073709551615 +' 30' -> 30 +' -40' -> 18446744073709551576 +After the loop p points to ' - 42'</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.24.1.7 The strtol, strtoll, strtoul, and strtoull functions (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22.1.4 The strtol, strtoll, strtoul, and strtoull functions (p: 251-252) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.1.4 The strtol, strtoll, strtoul, and strtoull functions (p: 344-345) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.1.4 The strtol, strtoll, strtoul, and strtoull functions (p: 310-311) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.1.6 The strtoul function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../wide/wcstoul" title="c/string/wide/wcstoul"> <span class="t-lines"><span>wcstoul</span><span>wcstoull</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a wide string to an unsigned integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atoi" title="c/string/byte/atoi"> <span class="t-lines"><span>atoi</span><span>atol</span><span>atoll</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a byte string to an integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strtol" title="c/string/byte/strtol"> <span class="t-lines"><span>strtol</span><span>strtoll</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a byte string to an integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/strtoul" title="cpp/string/byte/strtoul">C++ documentation</a></span> for <code>strtoul</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strtoul" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strtoul</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Fstrxfrm.html b/devdocs/c/string%2Fbyte%2Fstrxfrm.html new file mode 100644 index 00000000..15aa44a8 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Fstrxfrm.html @@ -0,0 +1,65 @@ + <h1 id="firstHeading" class="firstHeading">strxfrm</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">size_t strxfrm( char *dest, const char *src, size_t count );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">size_t strxfrm( char *restrict dest, const char *restrict src, size_t count );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Transforms the null-terminated byte string pointed to by <code>src</code> into the implementation-defined form such that comparing two transformed strings with <code><a href="strcmp" title="c/string/byte/strcmp">strcmp</a></code> gives the same result as comparing the original strings with <code><a href="strcoll" title="c/string/byte/strcoll">strcoll</a></code>, in the current C locale.</p> +<p>The first <code>count</code> characters of the transformed string are written to destination, including the terminating null character, and the length of the full transformed string is returned, excluding the terminating null character.</p> +<p>The behavior is undefined if the <code>dest</code> array is not large enough. The behavior is undefined if <code>dest</code> and <code>src</code> overlap.</p> +<p>If <code>count</code> is <code>0</code>, then <code>dest</code> is allowed to be a null pointer.</p> +<h3 id="Notes"> Notes</h3> <p>The correct length of the buffer that can receive the entire transformed string is <code><span class="nu0">1</span><span class="sy2">+</span>strxfrm<span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/NULL"><span class="kw103">NULL</span></a>, src, <span class="nu0">0</span><span class="br0">)</span></code></p> +<p>This function is used when making multiple locale-dependent comparisons using the same string or set of strings, because it is more efficient to use <code>strxfrm</code> to transform all the strings just once, and subsequently compare the transformed strings with <code><a href="strcmp" title="c/string/byte/strcmp">strcmp</a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the first element of the array where the transformed string will be written </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the first character of a null-terminated byte string to transform </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> maximum number of characters to be written </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The length of the transformed string, not including the terminating null-character.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <string.h> +#include <locale.h> + +int main(void) +{ + setlocale(LC_COLLATE, "cs_CZ.iso88592"); + + const char *in1 = "hrnec"; + char out1[1+strxfrm(NULL, in1, 0)]; + strxfrm(out1, in1, sizeof out1); + + const char *in2 = "chrt"; + char out2[1+strxfrm(NULL, in2, 0)]; + strxfrm(out2, in2, sizeof out2); + + printf("In the Czech locale: "); + if(strcmp(out1, out2) < 0) + printf("%s before %s\n",in1, in2); + else + printf("%s before %s\n",in2, in1); + + printf("In lexicographical comparison: "); + if(strcmp(in1, in2)<0) + printf("%s before %s\n",in1, in2); + else + printf("%s before %s\n",in2, in1); + +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">In the Czech locale: hrnec before chrt +In lexicographical comparison: chrt before hrnec</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.24.4.5 The strxfrm function (p: 267) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.24.4.5 The strxfrm function (p: 366-367) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.21.4.5 The strxfrm function (p: 329-330) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.11.4.5 The strxfrm function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="strcoll" title="c/string/byte/strcoll"> <span class="t-lines"><span>strcoll</span></span></a></div> </td> <td> compares two strings in accordance to the current locale <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../wide/wcscoll" title="c/string/wide/wcscoll"> <span class="t-lines"><span>wcscoll</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> compares two wide strings in accordance to the current locale <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="strcmp" title="c/string/byte/strcmp"> <span class="t-lines"><span>strcmp</span></span></a></div> </td> <td> compares two strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../wide/wcsxfrm" title="c/string/wide/wcsxfrm"> <span class="t-lines"><span>wcsxfrm</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> transform a wide string so that wcscmp would produce the same result as wcscoll <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/strxfrm" title="cpp/string/byte/strxfrm">C++ documentation</a></span> for <code>strxfrm</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/strxfrm" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/strxfrm</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Ftolower.html b/devdocs/c/string%2Fbyte%2Ftolower.html new file mode 100644 index 00000000..5e9a1f90 --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Ftolower.html @@ -0,0 +1,49 @@ + <h1 id="firstHeading" class="firstHeading">tolower</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><ctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int tolower( int ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Converts the given character to lowercase according to the character conversion rules defined by the currently installed C locale.</p> +<p>In the default "C" locale, the following uppercase letters <code>ABCDEFGHIJKLMNOPQRSTUVWXYZ</code> are replaced with respective lowercase letters <code>abcdefghijklmnopqrstuvwxyz</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> character to be converted. If the value of <code>ch</code> is not representable as <code>unsigned char</code> and does not equal <code><a href="http://en.cppreference.com/w/c/io"><span class="kw888">EOF</span></a></code>, the behavior is undefined. </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Lowercase version of <code>ch</code> or unmodified <code>ch</code> if no lowercase version is listed in the current C locale.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <ctype.h> +#include <locale.h> +#include <limits.h> + +int main(void) +{ + /* In the default locale: */ + for (unsigned char u = 0; u < UCHAR_MAX; u++) { + unsigned char l = tolower(u); + if (l != u) printf("%c%c ", u, l); + } + printf("\n\n"); + + unsigned char c = '\xb4'; // the character Ž in ISO-8859-15 + // but ´ (acute accent) in ISO-8859-1 + setlocale(LC_ALL, "en_US.iso88591"); + printf("in iso8859-1, tolower('0x%x') gives 0x%x\n", c, tolower(c)); + setlocale(LC_ALL, "en_US.iso885915"); + printf("in iso8859-15, tolower('0x%x') gives 0x%x\n", c, tolower(c)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Aa Bb Cc Dd Ee Ff Gg Hh Ii Jj Kk Ll Mm Nn Oo Pp Qq Rr Ss Tt Uu Vv Ww Xx Yy Zz + +in iso8859-1, tolower('0xb4') gives 0xb4 +in iso8859-15, tolower('0xb4') gives 0xb8</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.4.2.1 The tolower function (p: 147) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.4.2.1 The tolower function (p: 203) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.4.2.1 The tolower function (p: 184) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.3.2.1 The tolower function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="toupper" title="c/string/byte/toupper"> <span class="t-lines"><span>toupper</span></span></a></div> </td> <td> converts a character to uppercase <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../wide/towlower" title="c/string/wide/towlower"> <span class="t-lines"><span>towlower</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> converts a wide character to lowercase <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/tolower" title="cpp/string/byte/tolower">C++ documentation</a></span> for <code>tolower</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/tolower" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/tolower</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte%2Ftoupper.html b/devdocs/c/string%2Fbyte%2Ftoupper.html new file mode 100644 index 00000000..6e38516f --- /dev/null +++ b/devdocs/c/string%2Fbyte%2Ftoupper.html @@ -0,0 +1,49 @@ + <h1 id="firstHeading" class="firstHeading">toupper</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><ctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int toupper( int ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Converts the given character to uppercase according to the character conversion rules defined by the currently installed C locale.</p> +<p>In the default "C" locale, the following lowercase letters <code>abcdefghijklmnopqrstuvwxyz</code> are replaced with respective uppercase letters <code>ABCDEFGHIJKLMNOPQRSTUVWXYZ</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> character to be converted. If the value of <code>ch</code> is not representable as <code>unsigned char</code> and does not equal <code><a href="http://en.cppreference.com/w/c/io"><span class="kw888">EOF</span></a></code>, the behavior is undefined. </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Uppercase version of <code>ch</code> or unmodified <code>ch</code> if no uppercase version is listed in the current C locale.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <ctype.h> +#include <locale.h> +#include <limits.h> + +int main(void) +{ + /* In the default locale: */ + for (unsigned char l = 0; l < UCHAR_MAX; l++) { + unsigned char u = toupper(l); + if (u != l) printf("%c%c ", l, u); + } + printf("\n\n"); + + unsigned char c = '\xb8'; // the character Ž in ISO-8859-15 + // but ´ (acute accent) in ISO-8859-1 + setlocale(LC_ALL, "en_US.iso88591"); + printf("in iso8859-1, toupper('0x%x') gives 0x%x\n", c, toupper(c)); + setlocale(LC_ALL, "en_US.iso885915"); + printf("in iso8859-15, toupper('0x%x') gives 0x%x\n", c, toupper(c)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">aA bB cC dD eE fF gG hH iI jJ kK lL mM nN oO pP qQ rR sS tT uU vV wW xX yY zZ + +in iso8859-1, toupper('0xb8') gives 0xb8 +in iso8859-15, toupper('0xb8') gives 0xb4</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.4.2.2 The toupper function (p: 147-148) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.4.2.2 The toupper function (p: 204) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.4.2.2 The toupper function (p: 185) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.3.2.2 The toupper function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="tolower" title="c/string/byte/tolower"> <span class="t-lines"><span>tolower</span></span></a></div> </td> <td> converts a character to lowercase <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../wide/towupper" title="c/string/wide/towupper"> <span class="t-lines"><span>towupper</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> converts a wide character to uppercase <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte/toupper" title="cpp/string/byte/toupper">C++ documentation</a></span> for <code>toupper</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte/toupper" class="_attribution-link">https://en.cppreference.com/w/c/string/byte/toupper</a> + </p> +</div> diff --git a/devdocs/c/string%2Fbyte.html b/devdocs/c/string%2Fbyte.html new file mode 100644 index 00000000..154cff0a --- /dev/null +++ b/devdocs/c/string%2Fbyte.html @@ -0,0 +1,203 @@ + <h1 id="firstHeading" class="firstHeading">Null-terminated byte strings</h1> <p>A null-terminated byte string (NTBS) is a sequence of nonzero bytes followed by a byte with value zero (the terminating null character). Each byte in a byte string encodes one character of some character set. For example, the character array <code>{'\x63','\x61','\x74','\0'}</code> is an NTBS holding the string <code>"cat"</code> in <a href="../language/ascii" title="c/language/ascii">ASCII</a> encoding.</p> +<h3 id="Functions"> Functions</h3> <table class="t-dsc-begin"> <tr> <td colspan="2"> <h5 id="Character_classification"> Character classification </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><ctype.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/isalnum" title="c/string/byte/isalnum"> <span class="t-lines"><span>isalnum</span></span></a></div> </td> <td> checks if a character is alphanumeric <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/isalpha" title="c/string/byte/isalpha"> <span class="t-lines"><span>isalpha</span></span></a></div> </td> <td> checks if a character is alphabetic <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/islower" title="c/string/byte/islower"> <span class="t-lines"><span>islower</span></span></a></div> </td> <td> checks if a character is lowercase <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/isupper" title="c/string/byte/isupper"> <span class="t-lines"><span>isupper</span></span></a></div> </td> <td> checks if a character is an uppercase character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/isdigit" title="c/string/byte/isdigit"> <span class="t-lines"><span>isdigit</span></span></a></div> </td> <td> checks if a character is a digit <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/isxdigit" title="c/string/byte/isxdigit"> <span class="t-lines"><span>isxdigit</span></span></a></div> </td> <td> checks if a character is a hexadecimal character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/iscntrl" title="c/string/byte/iscntrl"> <span class="t-lines"><span>iscntrl</span></span></a></div> </td> <td> checks if a character is a control character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/isgraph" title="c/string/byte/isgraph"> <span class="t-lines"><span>isgraph</span></span></a></div> </td> <td> checks if a character is a graphical character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/isspace" title="c/string/byte/isspace"> <span class="t-lines"><span>isspace</span></span></a></div> </td> <td> checks if a character is a space character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/isblank" title="c/string/byte/isblank"> <span class="t-lines"><span>isblank</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if a character is a blank character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/isprint" title="c/string/byte/isprint"> <span class="t-lines"><span>isprint</span></span></a></div> </td> <td> checks if a character is a printing character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/ispunct" title="c/string/byte/ispunct"> <span class="t-lines"><span>ispunct</span></span></a></div> </td> <td> checks if a character is a punctuation character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Character_manipulation"> Character manipulation </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/tolower" title="c/string/byte/tolower"> <span class="t-lines"><span>tolower</span></span></a></div> </td> <td> converts a character to lowercase <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/toupper" title="c/string/byte/toupper"> <span class="t-lines"><span>toupper</span></span></a></div> </td> <td> converts a character to uppercase <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <p>Note: additional functions whose names begin with either <code>to</code> or <code>is</code>, followed by a lowercase letter, may be added to the header <code>ctype.h</code> in future and should not be defined by programs that include that header.</p> +<table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="byte/iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="wide/iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="wide/iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="wide/iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="wide/iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="wide/iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="wide/iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="wide/iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="wide/iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="wide/iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="wide/iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="wide/iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="wide/iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <table class="t-dsc-begin"> <tr> <td colspan="2"> <h5 id="Conversions_to_and_from_numeric_formats"> Conversions to and from numeric formats </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdlib.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/atof" title="c/string/byte/atof"> <span class="t-lines"><span>atof</span></span></a></div> </td> <td> converts a byte string to a floating-point value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/atoi" title="c/string/byte/atoi"> <span class="t-lines"><span>atoi</span><span>atol</span><span>atoll</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a byte string to an integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strtol" title="c/string/byte/strtol"> <span class="t-lines"><span>strtol</span><span>strtoll</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a byte string to an integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strtoul" title="c/string/byte/strtoul"> <span class="t-lines"><span>strtoul</span><span> strtoull</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a byte string to an unsigned integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strtof" title="c/string/byte/strtof"> <span class="t-lines"><span>strtof</span><span>strtod</span><span>strtold</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a byte string to a floating point value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strfromf" title="c/string/byte/strfromf"> <span class="t-lines"><span>strfromf</span><span>strfromd</span><span>strfromld</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> converts a floating point value to a byte string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><inttypes.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strtoimax" title="c/string/byte/strtoimax"> <span class="t-lines"><span>strtoimax</span><span>strtoumax</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a byte string to <code><a href="../types/integer" title="c/types/integer">intmax_t</a></code> or <code><a href="../types/integer" title="c/types/integer">uintmax_t</a></code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="String_manipulation"> String manipulation </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><string.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strcpy" title="c/string/byte/strcpy"> <span class="t-lines"><span>strcpy</span><span>strcpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies one string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strncpy" title="c/string/byte/strncpy"> <span class="t-lines"><span>strncpy</span><span>strncpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies a certain amount of characters from one string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strcat" title="c/string/byte/strcat"> <span class="t-lines"><span>strcat</span><span>strcat_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> concatenates two strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strncat" title="c/string/byte/strncat"> <span class="t-lines"><span>strncat</span><span>strncat_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> concatenates a certain amount of characters of two strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strxfrm" title="c/string/byte/strxfrm"> <span class="t-lines"><span>strxfrm</span></span></a></div> </td> <td> transform a string so that strcmp would produce the same result as strcoll <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strdup" title="c/string/byte/strdup"> <span class="t-lines"><span>strdup</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> allocates a copy of a string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strndup" title="c/string/byte/strndup"> <span class="t-lines"><span>strndup</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> allocates a copy of a string of specified size <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="String_examination"> String examination </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><string.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strlen" title="c/string/byte/strlen"> <span class="t-lines"><span>strlen</span><span>strnlen_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> returns the length of a given string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strcmp" title="c/string/byte/strcmp"> <span class="t-lines"><span>strcmp</span></span></a></div> </td> <td> compares two strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strncmp" title="c/string/byte/strncmp"> <span class="t-lines"><span>strncmp</span></span></a></div> </td> <td> compares a certain amount of characters of two strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strcoll" title="c/string/byte/strcoll"> <span class="t-lines"><span>strcoll</span></span></a></div> </td> <td> compares two strings in accordance to the current locale <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strchr" title="c/string/byte/strchr"> <span class="t-lines"><span>strchr</span></span></a></div> </td> <td> finds the first occurrence of a character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strrchr" title="c/string/byte/strrchr"> <span class="t-lines"><span>strrchr</span></span></a></div> </td> <td> finds the last occurrence of a character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strspn" title="c/string/byte/strspn"> <span class="t-lines"><span>strspn</span></span></a></div> </td> <td> returns the length of the maximum initial segment that consists <br> of only the characters found in another byte string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strcspn" title="c/string/byte/strcspn"> <span class="t-lines"><span>strcspn</span></span></a></div> </td> <td> returns the length of the maximum initial segment that consists <br> of only the characters not found in another byte string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strpbrk" title="c/string/byte/strpbrk"> <span class="t-lines"><span>strpbrk</span></span></a></div> </td> <td> finds the first location of any character in one string, in another string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strstr" title="c/string/byte/strstr"> <span class="t-lines"><span>strstr</span></span></a></div> </td> <td> finds the first occurrence of a substring of characters <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strtok" title="c/string/byte/strtok"> <span class="t-lines"><span>strtok</span><span>strtok_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> finds the next token in a byte string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Character_array_manipulation"> Character array manipulation </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><string.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/memchr" title="c/string/byte/memchr"> <span class="t-lines"><span>memchr</span></span></a></div> </td> <td> searches an array for the first occurrence of a character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/memcmp" title="c/string/byte/memcmp"> <span class="t-lines"><span>memcmp</span></span></a></div> </td> <td> compares two buffers <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/memset" title="c/string/byte/memset"> <span class="t-lines"><span>memset</span><span>memset_explicit</span><span>memset_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> fills a buffer with a character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/memcpy" title="c/string/byte/memcpy"> <span class="t-lines"><span>memcpy</span><span>memcpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies one buffer to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/memmove" title="c/string/byte/memmove"> <span class="t-lines"><span>memmove</span><span>memmove_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> moves one buffer to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/memccpy" title="c/string/byte/memccpy"> <span class="t-lines"><span>memccpy</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> copies one buffer to another, stopping after the specified delimiter <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Miscellaneous"> Miscellaneous </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><string.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="byte/strerror" title="c/string/byte/strerror"> <span class="t-lines"><span>strerror</span><span>strerror_s</span><span>strerrorlen_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> returns a text version of a given error code <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.4 Character handling <ctype.h> (p: 200-204) </li> +<li> 7.8 Format conversion of integer types <inttypes.h> (p: 217-220) </li> +<li> 7.22 General utilities <stdlib.h> (p: 340-360) </li> +<li> 7.24 String handling <string.h> (p: 362-372) </li> +<li> 7.31.2 Character handling <ctype.h> (p: 455) </li> +<li> 7.31.5 Format conversion of integer types <inttypes.h> (p: 455) </li> +<li> 7.31.12 General utilities <stdlib.h> (p: 456) </li> +<li> 7.31.13 String handling <string.h> (p: 456) </li> +<li> K.3.6 General utilities <stdlib.h> (p: 604-613) </li> +<li> K.3.7 String handling <string.h> (p: 614-623) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.4 Character handling <ctype.h> (p: 181-185) </li> +<li> 7.8 Format conversion of integer types <inttypes.h> (p: 198-201) </li> +<li> 7.20 General utilities <stdlib.h> (p: 306-324) </li> +<li> 7.21 String handling <string.h> (p: 325-334) </li> +<li> 7.26.2 Character handling <ctype.h> (p: 401) </li> +<li> 7.26.4 Format conversion of integer types <inttypes.h> (p: 401) </li> +<li> 7.26.10 General utilities <stdlib.h> (p: 402) </li> +<li> 7.26.11 String handling <string.h> (p: 402) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 4.3 CHARACTER HANDLING <ctype.h> </li> +<li> 4.10 GENERAL UTILITIES <stdlib.h> </li> +<li> 4.11 STRING HANDLING <string.h> </li> +<li> 4.13.2 Character handling <ctype.h> </li> +<li> 4.13.7 General utilities <stdlib.h> </li> +<li> 4.13.8 String handling <string.h> </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/byte" title="cpp/string/byte">C++ documentation</a></span> for <span class=""><span><code>Null</code>-terminated byte strings</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/byte" class="_attribution-link">https://en.cppreference.com/w/c/string/byte</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fbtowc.html b/devdocs/c/string%2Fmultibyte%2Fbtowc.html new file mode 100644 index 00000000..a30db92f --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fbtowc.html @@ -0,0 +1,57 @@ + <h1 id="firstHeading" class="firstHeading">btowc</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">wint_t btowc( int c );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Widens a single-byte character <code>c</code> (reinterpreted as <code>unsigned char</code>) to its wide character equivalent.</p> +<p>Most multibyte character encodings use single-byte codes to represent the characters from the ASCII character set. This function may be used to convert such characters to <code>wchar_t</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> c </td> <td> - </td> <td> single-byte character to widen </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>WEOF</code> if <code>c</code> is <code><a href="../../io" title="c/io">EOF</a></code></p> +<p>wide character representation of <code>c</code> if <code>(unsigned char)c</code> is a valid single-byte character in the initial shift state, <code>WEOF</code> otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <wchar.h> +#include <locale.h> +#include <assert.h> + +void try_widen(unsigned char c) +{ + wint_t w = btowc(c); + if(w != WEOF) + printf("The single-byte character %#x widens to %#x\n", c, w); + else + printf("The single-byte character %#x failed to widen\n", c); +} + +int main(void) +{ + char *loc = setlocale(LC_ALL, "lt_LT.iso88594"); + assert(loc); + printf("In Lithuanian ISO-8859-4 locale:\n"); + try_widen('A'); + try_widen('\xdf'); // German letter ß (U+00df) in ISO-8859-4 + try_widen('\xf9'); // Lithuanian letter ų (U+0173) in ISO-8859-4 + + setlocale(LC_ALL, "lt_LT.utf8"); + printf("In Lithuanian UTF-8 locale:\n"); + try_widen('A'); + try_widen('\xdf'); + try_widen('\xf9'); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">In Lithuanian ISO-8859-4 locale: +The single-byte character 0x41 widens to 0x41 +The single-byte character 0xdf widens to 0xdf +The single-byte character 0xf9 widens to 0x173 +In Lithuanian UTF-8 locale: +The single-byte character 0x41 widens to 0x41 +The single-byte character 0xdf failed to widen +The single-byte character 0xf9 failed to widen</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.6.1.1 The btowc function (p: 441) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.6.1.1 The btowc function (p: 387) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="wctob" title="c/string/multibyte/wctob"> <span class="t-lines"><span>wctob</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> narrows a wide character to a single-byte narrow character, if possible <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/multibyte/btowc" title="cpp/string/multibyte/btowc">C++ documentation</a></span> for <code>btowc</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/btowc" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/btowc</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fc16rtomb.html b/devdocs/c/string%2Fmultibyte%2Fc16rtomb.html new file mode 100644 index 00000000..5f1da1ad --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fc16rtomb.html @@ -0,0 +1,67 @@ + <h1 id="firstHeading" class="firstHeading">c16rtomb</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><uchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">size_t c16rtomb( char* restrict s, char16_t c16, mbstate_t* restrict ps );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Converts a single code point from its variable-length 16-bit wide character representation (typically, UTF-16) to its narrow multibyte character representation.</p> +<p>If <code>s</code> is not a null pointer and <code>c16</code> is the last 16-bit code unit in a valid variable-length encoding of a code point, the function determines the number of bytes necessary to store the multibyte character representation of that code point (including any shift sequences, and taking into account the current multibyte conversion state <code>*ps</code>), and stores the multibyte character representation in the character array whose first element is pointed to by <code>s</code>, updating <code>*ps</code> as necessary. At most <code>MB_CUR_MAX</code> bytes can be written by this function.</p> +<p>If <code>s</code> is a null pointer, the call is equivalent to <code>c16rtomb(buf, u'\0', ps)</code> for some internal buffer <code>buf</code>.</p> +<p>If <code>c16</code> is the null wide character <code>u'\0'</code>, a null byte is stored, preceded by any shift sequence necessary to restore the initial shift state and the conversion state parameter <code>*ps</code> is updated to represent the initial shift state.</p> +<p>If <code>c16</code> is not the final code unit in a 16-bit representation of a wide character, it does not write to the array pointed to by <code>s</code>, only <code>*ps</code> is updated.</p> +<p>If the macro <code>__STDC_UTF_16__</code> is defined, the 16-bit encoding used by this function is UTF-16; otherwise, it is implementation-defined. <span class="t-rev-inl t-since-c23"><span>The macro is always defined and the encoding is always UTF-16.</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> In any case, the multibyte character encoding used by this function is specified by the currently active C locale.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> s </td> <td> - </td> <td> pointer to narrow character array where the multibyte character will be stored </td> +</tr> <tr class="t-par"> <td> c16 </td> <td> - </td> <td> the 16-bit wide character to convert </td> +</tr> <tr class="t-par"> <td> ps </td> <td> - </td> <td> pointer to the conversion state object used when interpreting the multibyte string </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>On success, returns the number of bytes (including any shift sequences) written to the character array whose first element is pointed to by <code>s</code>. This value may be <code>0</code>, e.g. when processing the leading <code>char16_t</code> units in a multi-<code>char16_t</code>-unit sequence (occurs when processing the leading surrogate in a surrogate pair of UTF-16).</p> +<p>On failure (if <code>c16</code> is not a valid 16-bit code unit), returns <code>-1</code>, stores <code><a href="../../error/errno_macros" title="c/error/errno macros">EILSEQ</a></code> in <code><a href="../../error/errno" title="c/error/errno">errno</a></code>, and leaves <code>*ps</code> in unspecified state.</p> +<h3 id="Notes"> Notes</h3> <p>In C11 as published, unlike <code><a href="mbrtoc16" title="c/string/multibyte/mbrtoc16">mbrtoc16</a></code>, which converts variable-width multibyte (such as UTF-8) to variable-width 16-bit (such as UTF-16) encoding, this function can only convert single-unit 16-bit encoding, meaning it cannot convert UTF-16 to UTF-8 despite that being the original intent of this function. This was corrected by the post-C11 defect report <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2059.htm#dr_488">DR488</a>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>Note: this example assumes the fix for the defect report <a rel="nofollow" class="external text" href="https://open-std.org/JTC1/SC22/WG14/www/docs/n2059.htm#dr_488">DR488</a> is applied</p> +<div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <stdlib.h> +#include <uchar.h> + +mbstate_t state; + +int main(void) +{ + setlocale(LC_ALL, "en_US.utf8"); + const char16_t in[] = u"zß水🍌"; // or "z\u00df\u6c34\U0001F34C" + const size_t in_sz = sizeof in / sizeof *in; + + printf("Processing %zu UTF-16 code units: [ ", in_sz); + for (size_t n = 0; n < in_sz; ++n) + printf("%#x ", in[n]); + puts("]"); + + char out[MB_CUR_MAX * in_sz]; + char *p = out; + for (size_t n = 0; n < in_sz; ++n) + { + size_t rc = c16rtomb(p, in[n], &state); + if (rc == (size_t)-1) + break; + p += rc; + } + + size_t out_sz = p - out; + printf("into %zu UTF-8 code units: [ ", out_sz); + for (size_t x = 0; x < out_sz; ++x) + printf("%#x ", +(unsigned char)out[x]); + puts("]"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Processing 6 UTF-16 code units: [ 0x7a 0xdf 0x6c34 0xd83c 0xdf4c 0 ] +into 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0 ]</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.28.1.2 The c16rtomb function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.28.1.2 The c16rtomb function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.28.1.2 The c16rtomb function (p: 399-400) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="mbrtoc16" title="c/string/multibyte/mbrtoc16"> <span class="t-lines"><span>mbrtoc16</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> generates the next 16-bit wide character from a narrow multibyte string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/multibyte/c16rtomb" title="cpp/string/multibyte/c16rtomb">C++ documentation</a></span> for <code>c16rtomb</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/c16rtomb" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/c16rtomb</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fc32rtomb.html b/devdocs/c/string%2Fmultibyte%2Fc32rtomb.html new file mode 100644 index 00000000..c6b285c5 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fc32rtomb.html @@ -0,0 +1,60 @@ + <h1 id="firstHeading" class="firstHeading">c32rtomb</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><uchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">size_t c32rtomb( char* restrict s, char32_t c32, mbstate_t* restrict ps );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Converts a single code point from its variable-length 32-bit wide character representation (but typically, UTF-32) to its narrow multibyte character representation.</p> +<p>If <code>s</code> is not a null pointer, the function determines the number of bytes necessary to store the multibyte character representation of <code>c32</code> (including any shift sequences, and taking into account the current multibyte conversion state <code>*ps</code>), and stores the multibyte character representation in the character array whose first element is pointed to by <code>s</code>, updating <code>*ps</code> as necessary. At most <code>MB_CUR_MAX</code> bytes can be written by this function.</p> +<p>If <code>s</code> is a null pointer, the call is equivalent to <code>c32rtomb(buf, U'\0', ps)</code> for some internal buffer <code>buf</code>.</p> +<p>If <code>c32</code> is the null wide character <code>U'\0'</code>, a null byte is stored, preceded by any shift sequence necessary to restore the initial shift state and the conversion state parameter <code>*ps</code> is updated to represent the initial shift state.</p> +<p>If the macro <code>__STDC_UTF_32__</code> is defined, the 32-bit encoding used by this function is UTF-32; otherwise, it is implementation-defined. <span class="t-rev-inl t-since-c23"><span>The macro is always defined and the encoding is always UTF-32.</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> In any case, the multibyte character encoding used by this function is specified by the currently active C locale.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> s </td> <td> - </td> <td> pointer to narrow character array where the multibyte character will be stored </td> +</tr> <tr class="t-par"> <td> c32 </td> <td> - </td> <td> the 32-bit wide character to convert </td> +</tr> <tr class="t-par"> <td> ps </td> <td> - </td> <td> pointer to the conversion state object used when interpreting the multibyte string </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>On success, returns the number of bytes (including any shift sequences) written to the character array whose first element is pointed to by <code>s</code>. This value may be <code>0</code>, e.g. when processing the leading <code>char32_t</code> units in a multi-<code>char32_t</code>-unit sequence (does not occur in UTF-32).</p> +<p>On failure (if <code>c32</code> is not a valid 32-bit wide character), returns <code>-1</code>, stores <code><a href="../../error/errno_macros" title="c/error/errno macros">EILSEQ</a></code> in <code><a href="../../error/errno" title="c/error/errno">errno</a></code>, and leaves <code>*ps</code> in unspecified state.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <stdlib.h> +#include <uchar.h> + +mbstate_t state; + +int main(void) +{ + setlocale(LC_ALL, "en_US.utf8"); + const char32_t in[] = U"zß水🍌"; // or "z\u00df\u6c34\U0001F34C" + size_t in_sz = sizeof in / sizeof *in; + + printf("Processing %zu UTF-32 code units: [ ", in_sz); + for (size_t n = 0; n < in_sz; ++n) + printf("%#x ", in[n]); + puts("]"); + + char out[MB_CUR_MAX * in_sz]; + char* p = out; + for (size_t n = 0; n < in_sz; ++n) + { + size_t rc = c32rtomb(p, in[n], &state); + if(rc == (size_t)-1) break; + p += rc; + } + + size_t out_sz = p - out; + printf("into %zu UTF-8 code units: [ ", out_sz); + for (size_t x = 0; x < out_sz; ++x) + printf("%#x ", +(unsigned char)out[x]); + puts("]"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Processing 5 UTF-32 code units: [ 0x7a 0xdf 0x6c34 0x1f34c 0 ] +into 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0 ]</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.30.1.6 The c32rtomb function (p: 411) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.28.1.4 The c32rtomb function (p: 401) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="mbrtoc32" title="c/string/multibyte/mbrtoc32"> <span class="t-lines"><span>mbrtoc32</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> generates the next 32-bit wide character from a narrow multibyte string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/multibyte/c32rtomb" title="cpp/string/multibyte/c32rtomb">C++ documentation</a></span> for <code>c32rtomb</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/c32rtomb" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/c32rtomb</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fc8rtomb.html b/devdocs/c/string%2Fmultibyte%2Fc8rtomb.html new file mode 100644 index 00000000..3060f056 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fc8rtomb.html @@ -0,0 +1,23 @@ + <h1 id="firstHeading" class="firstHeading">c8rtomb</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><uchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">size_t c8rtomb( char* restrict s, char8_t c8, mbstate_t* restrict ps );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <p>Converts a single code point from UTF-8 to a narrow multibyte character representation.</p> +<p>If <code>s</code> is not a null pointer and <code>c8</code> is the last code unit in a valid UTF-8 encoding of a code point, the function determines the number of bytes necessary to store the multibyte character representation of that code point (including any shift sequences, and taking into account the current multibyte conversion state <code>*ps</code>), and stores the multibyte character representation in the character array whose first element is pointed to by <code>s</code>, updating <code>*ps</code> as necessary. At most <code>MB_CUR_MAX</code> bytes can be written by this function.</p> +<p>If <code>c8</code> is not the final UTF-8 code unit in a representation of a code point, the function does not write to the array pointed to by <code>s</code>, only <code>*ps</code> is updated.</p> +<p>If <code>s</code> is a null pointer, the call is equivalent to <code>c8rtomb(buf, u8'\0', ps)</code> for some internal buffer <code>buf</code>.</p> +<p>If <code>c8</code> is the null character <code>u8'\0'</code>, a null byte is stored, preceded by any shift sequence necessary to restore the initial shift state and the conversion state parameter <code>*ps</code> is updated to represent the initial shift state.</p> +<p>The multibyte encoding used by this function is specified by the currently active C locale.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> s </td> <td> - </td> <td> pointer to narrow character array where the multibyte character will be stored </td> +</tr> <tr class="t-par"> <td> c8 </td> <td> - </td> <td> the UTF-8 code unit to convert </td> +</tr> <tr class="t-par"> <td> ps </td> <td> - </td> <td> pointer to the conversion state object used when interpreting the multibyte string </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The number of bytes stored in the array object (including any shift sequences). This may be zero when <code>c8</code> is not the final code unit in the UTF-8 representation of a code point.</p> +<p>If <code>c8</code> is invalid (does not contribute to a sequence of <code>char8_t</code> corresponding to a valid multibyte character), the value of the macro <code><a href="../../error/errno_macros" title="c/error/errno macros">EILSEQ</a></code> is stored in <code><a href="../../error/errno" title="c/error/errno">errno</a></code>, <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">1</span></code> is returned, and the conversion state is unspecified.</p> +<h3 id="Notes"> Notes</h3> <p>Calls to <code>c8rtomb</code> with a null pointer argument for <code>s</code> may introduce a data race with other calls to <code>c8rtomb</code> with a null pointer argument for <code>s</code>.</p> +<h3 id="Example"> Example</h3> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="mbrtoc8" title="c/string/multibyte/mbrtoc8"> <span class="t-lines"><span>mbrtoc8</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> converts a narrow multibyte character to UTF-8 encoding <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/multibyte/c8rtomb" title="cpp/string/multibyte/c8rtomb">C++ documentation</a></span> for <code>c8rtomb</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/c8rtomb" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/c8rtomb</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fchar16_t.html b/devdocs/c/string%2Fmultibyte%2Fchar16_t.html new file mode 100644 index 00000000..b31287af --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fchar16_t.html @@ -0,0 +1,35 @@ + <h1 id="firstHeading" class="firstHeading">char16_t</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><uchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">typedef uint_least16_t char16_t;</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p><code>char16_t</code> is an unsigned integer type used for 16-bit wide characters and is the same type as <code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw129">uint_least16_t</span></a></code>.</p> +<h3 id="Notes"> Notes</h3> <p>On any given platform, by the definition of <code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw129">uint_least16_t</span></a></code>, the width of type <code>char16_t</code> can be greater than 16 bits, but the actual values stored in an object of type <code>char16_t</code> will always have a width of 16 bits.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <uchar.h> + +int main(void) +{ + const char16_t wcs[] = u"zß水🍌"; // or "z\u00df\u6c34\U0001f34c" + const size_t wcs_sz = sizeof wcs / sizeof *wcs; + printf("%zu UTF-16 code units: [ ", wcs_sz); + for (size_t n = 0; n < wcs_sz; ++n) + printf("%#x ", wcs[n]); + printf("]\n"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">6 UTF-16 code units: [ 0x7a 0xdf 0x6c34 0xd83c 0xdf4c 0 ]</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.28 Unicode utilities <uchar.h> (p: 292) </li> +<li> 7.20.1.2 Minimum-width integer types (p: 212-213) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.28 Unicode utilities <uchar.h> (p: 398) </li> +<li> 7.20.1.2 Minimum-width integer types (p: 290) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.18.1.2 Minimum-width integer types (p: 256) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/types" title="cpp/language/types">C++ documentation</a></span> for <span class=""><span>Fundamental types</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/char16_t" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/char16_t</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fchar32_t.html b/devdocs/c/string%2Fmultibyte%2Fchar32_t.html new file mode 100644 index 00000000..a6895bb4 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fchar32_t.html @@ -0,0 +1,35 @@ + <h1 id="firstHeading" class="firstHeading">char32_t</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><uchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">typedef uint_least32_t char32_t;</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p><code>char32_t</code> is an unsigned integer type used for 32-bit wide characters and is the same type as <code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw130">uint_least32_t</span></a></code>.</p> +<h3 id="Notes"> Notes</h3> <p>On any given platform, by the definition of <code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw130">uint_least32_t</span></a></code>, the width of type <code>char32_t</code> can be greater than 32 bits, but the actual values stored in an object of type <code>char32_t</code> will always have a width of 32 bits.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <uchar.h> + +int main(void) +{ + const char32_t wc[] = U"zß水🍌"; // or "z\u00df\u6c34\U0001f34c" + const size_t wc_sz = sizeof wc / sizeof *wc; + printf("%zu UTF-32 code units: [ ", wc_sz); + for (size_t n = 0; n < wc_sz; ++n) + printf("%#x ", wc[n]); + printf("]\n"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">5 UTF-32 code units: [ 0x7a 0xdf 0x6c34 0x1f34c 0 ]</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.28 Unicode utilities <uchar.h> (p: 292) </li> +<li> 7.20.1.2 Minimum-width integer types (p: 212-213) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.28 Unicode utilities <uchar.h> (p: 398) </li> +<li> 7.20.1.2 Minimum-width integer types (p: 290) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.18.1.2 Minimum-width integer types (p: 256) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/types" title="cpp/language/types">C++ documentation</a></span> for <span class=""><span>Fundamental types</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/char32_t" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/char32_t</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fchar8_t.html b/devdocs/c/string%2Fmultibyte%2Fchar8_t.html new file mode 100644 index 00000000..56ae4d71 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fchar8_t.html @@ -0,0 +1,24 @@ + <h1 id="firstHeading" class="firstHeading">char8_t</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><uchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">typedef unsigned char char8_t;</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <p><code>char8_t</code> is an unsigned integer type used for UTF-8 and is the same type as <code>unsigned char</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <uchar.h> +#include <stdio.h> + +int main(void) +{ + char8_t str[] = u8"zß水🍌"; // or "z\u00df\u6c34\U0001f34c" + size_t str_sz = sizeof str; // sizeof *str == 1 by definition + printf("%zu UTF-8 code units: [ ", str_sz); + for (size_t n = 0; n < str_sz; ++n) + printf("%02X ", str[n]); + printf("]\n"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">11 UTF-8 code units: [ 7A C3 9F E6 B0 B4 F0 9F 8D 8C 00 ]</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.30 Unicode utilities <uchar.h> (p: 410) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/types" title="cpp/language/types">C++ documentation</a></span> for <code>Fundamental types</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/char8_t" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/char8_t</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fmblen.html b/devdocs/c/string%2Fmultibyte%2Fmblen.html new file mode 100644 index 00000000..46facf2a --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmblen.html @@ -0,0 +1,73 @@ + <h1 id="firstHeading" class="firstHeading">mblen</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">int mblen( const char* s, size_t n );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Determines the size, in bytes, of the multibyte character whose first byte is pointed to by <code>s</code>.</p> +<p>If <code>s</code> is a null pointer, <span class="t-rev-inl t-until-c23"><span>resets the global conversion state and</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span> determined whether shift sequences are used.</p> +<p>This function is equivalent to the call <code><a href="http://en.cppreference.com/w/c/string/multibyte/mbtowc"><span class="kw575">mbtowc</span></a><span class="br0">(</span><span class="br0">(</span><span class="kw4">wchar_t</span><span class="sy2">*</span><span class="br0">)</span><span class="nu0">0</span>, s, n<span class="br0">)</span></code>, except that conversion state of <code><a href="mbtowc" title="c/string/multibyte/mbtowc">mbtowc</a></code> is unaffected.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> s </td> <td> - </td> <td> pointer to the multibyte character </td> +</tr> <tr class="t-par"> <td> n </td> <td> - </td> <td> limit on the number of bytes in s that can be examined </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If <code>s</code> is not a null pointer, returns the number of bytes that are contained in the multibyte character or <code>-1</code> if the first bytes pointed to by <code>s</code> do not form a valid multibyte character or <code>0</code> if <code>s</code> is pointing at the null charcter <code>'\0'</code>.</p> +<p>If <code>s</code> is a null pointer, <span class="t-rev-inl t-until-c23"><span>resets its internal conversion state to represent the initial shift state and</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span> returns <code>0</code> if the current multibyte encoding is not state-dependent (does not use shift sequences) or a non-zero value if the current multibyte encoding is state-dependent (uses shift sequences).</p> +<h3 id="Notes"> Notes</h3> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>Each call to <code>mblen</code> updates the internal global conversion state (a static object of type <code><a href="mbstate_t" title="c/string/multibyte/mbstate t">mbstate_t</a></code>, only known to this function). If the multibyte encoding uses shift states, care must be taken to avoid backtracking or multiple scans. In any case, multiple threads should not call <code>mblen</code> without synchronization: <code><a href="mbrlen" title="c/string/multibyte/mbrlen">mbrlen</a></code> may be used instead.</p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td> <p><code>mblen</code> is not allowed to have an internal state.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> + +// the number of characters in a multibyte string is the sum of mblen()'s +// note: the simpler approach is mbstowcs(NULL, str, sz) +size_t strlen_mb(const char* ptr) +{ + size_t result = 0; + const char* end = ptr + strlen(ptr); + mblen(NULL, 0); // reset the conversion state + while(ptr < end) { + int next = mblen(ptr, end - ptr); + if (next == -1) { + perror("strlen_mb"); + break; + } + ptr += next; + ++result; + } + return result; +} + +void dump_bytes(const char* str) +{ + for (const char* end = str + strlen(str); str != end; ++str) + printf("%02X ", (unsigned char)str[0]); + printf("\n"); +} + +int main(void) +{ + setlocale(LC_ALL, "en_US.utf8"); + const char* str = "z\u00df\u6c34\U0001f34c"; + printf("The string \"%s\" consists of %zu characters, but %zu bytes: ", + str, strlen_mb(str), strlen(str)); + dump_bytes(str); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">The string "zß水🍌" consists of 4 characters, but 10 bytes: 7A C3 9F E6 B0 B4 F0 9F 8D 8C</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22.7.1 The mblen function (p: 260) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.7.1 The mblen function (p: 357) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.7.1 The mblen function (p: 321) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.7.1 The mblen function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="mbtowc" title="c/string/multibyte/mbtowc"> <span class="t-lines"><span>mbtowc</span></span></a></div> </td> <td> converts the next multibyte character to wide character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="mbrlen" title="c/string/multibyte/mbrlen"> <span class="t-lines"><span>mbrlen</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> returns the number of bytes in the next multibyte character, given state <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/multibyte/mblen" title="cpp/string/multibyte/mblen">C++ documentation</a></span> for <code>mblen</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/mblen" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/mblen</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fmbrlen.html b/devdocs/c/string%2Fmultibyte%2Fmbrlen.html new file mode 100644 index 00000000..cf7c2914 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmbrlen.html @@ -0,0 +1,58 @@ + <h1 id="firstHeading" class="firstHeading">mbrlen</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td> <pre data-language="c">size_t mbrlen( const char *s, size_t n, mbstate_t *ps );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">size_t mbrlen( const char *restrict s, size_t n, mbstate_t *restrict ps );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Determines the size, in bytes, of the representation of a multibyte character.</p> +<p>This function is equivalent to the call <code><a href="http://en.cppreference.com/w/c/string/multibyte/mbrtowc"><span class="kw583">mbrtowc</span></a><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/NULL"><span class="kw103">NULL</span></a>, s, n, ps<span class="sy4">?</span>ps<span class="sy4">:</span><span class="sy3">&</span>internal<span class="br0">)</span></code> for some hidden object <code>internal</code> of type <code><a href="mbstate_t" title="c/string/multibyte/mbstate t">mbstate_t</a></code>, except that the expression <code>ps</code> is evaluated only once.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> s </td> <td> - </td> <td> pointer to an element of a multibyte character string </td> +</tr> <tr class="t-par"> <td> n </td> <td> - </td> <td> limit on the number of bytes in s that can be examined </td> +</tr> <tr class="t-par"> <td> ps </td> <td> - </td> <td> pointer to the variable holding the conversion state </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The first of the following that applies:</p> +<ul> +<li> <code>0</code> if the next <code>n</code> or fewer bytes complete the null character or if <code>s</code> is a null pointer. Both cases reset the conversion state. </li> +<li> the number of bytes <code>[1...n]</code> that complete a valid multibyte character </li> +<li> <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">2</span></code> if the next <code>n</code> bytes are part of a possibly valid multibyte character, which is still incomplete after examining all <code>n</code> bytes </li> +<li> <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">1</span></code> if encoding error occurs. The value of <code><a href="../../error/errno" title="c/error/errno">errno</a></code> is <code>EILSEQ</code>; the conversion state is unspecified. </li> +</ul> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <string.h> +#include <stdio.h> +#include <wchar.h> + +int main(void) +{ + // allow mbrlen() to work with UTF-8 multibyte encoding + setlocale(LC_ALL, "en_US.utf8"); + // UTF-8 narrow multibyte encoding + const char* str = u8"水"; + size_t sz = strlen(str); + + mbstate_t mb; + memset(&mb, 0, sizeof mb); + int len1 = mbrlen(str, 1, &mb); + if(len1 == -2) + printf("The first 1 byte of %s is an incomplete multibyte char" + " (mbrlen returns -2)\n", str); + + int len2 = mbrlen(str+1, sz-1, &mb); + printf("The remaining %zu bytes of %s hold %d bytes of the multibyte" + " character\n", sz-1, str, len2); + + printf("Attempting to call mbrlen() in the middle of %s while in initial" + " shift state returns %zd\n", str, mbrlen(str+1, sz-1, &mb)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">The first 1 byte of 水 is an incomplete multibyte char (mbrlen returns -2) +The remaining 2 bytes of 水 hold 2 bytes of the multibyte character +Attempting to call mbrlen() in the middle of 水 while in initial shift state returns -1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.6.3.1 The mbrlen function (p: 442) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.6.3.1 The mbrlen function (p: 388) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="mbrtowc" title="c/string/multibyte/mbrtowc"> <span class="t-lines"><span>mbrtowc</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> converts the next multibyte character to wide character, given state <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="mblen" title="c/string/multibyte/mblen"> <span class="t-lines"><span>mblen</span></span></a></div> </td> <td> returns the number of bytes in the next multibyte character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/multibyte/mbrlen" title="cpp/string/multibyte/mbrlen">C++ documentation</a></span> for <code>mbrlen</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/mbrlen" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/mbrlen</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fmbrtoc16.html b/devdocs/c/string%2Fmultibyte%2Fmbrtoc16.html new file mode 100644 index 00000000..df3061d9 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmbrtoc16.html @@ -0,0 +1,76 @@ + <h1 id="firstHeading" class="firstHeading">mbrtoc16</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><uchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">size_t mbrtoc16( char16_t* restrict pc16, const char* restrict s, + size_t n, mbstate_t* restrict ps );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Converts a single code point from its narrow multibyte character representation to its variable-length 16-bit wide character representation (typically, UTF-16).</p> +<p>If <code>s</code> is not a null pointer, inspects at most <code>n</code> bytes of the multibyte character string, beginning with the byte pointed to by <code>s</code> to determine the number of bytes necessary to complete the next multibyte character (including any shift sequences, and taking into account the current multibyte conversion state <code>*ps</code>). If the function determines that the next multibyte character in <code>s</code> is complete and valid, converts it to the corresponding 16-bit wide character and stores it in <code>*pc16</code> (if <code>pc16</code> is not null).</p> +<p>If the multibyte character in <code>*s</code> corresponds to a multi-char16_t sequence (e.g. a surrogate pair in UTF-16), then after the first call to this function, <code>*ps</code> is updated in such a way that the next call to <code>mbrtoc16</code> will write out the additional <code>char16_t</code>, without considering <code>*s</code>.</p> +<p>If <code>s</code> is a null pointer, the values of <code>n</code> and <code>pc16</code> are ignored and the call is equivalent to <code>mbrtoc16<span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/NULL"><span class="kw103">NULL</span></a>, <span class="st0">""</span>, <span class="nu0">1</span>, ps<span class="br0">)</span></code>.</p> +<p>If the wide character produced is the null character, the conversion state <code>*ps</code> represents the initial shift state.</p> +<p>If the macro <code>__STDC_UTF_16__</code> is defined, the 16-bit encoding used by this function is UTF-16; otherwise, it is implementation-defined. <span class="t-rev-inl t-since-c23"><span>The macro is always defined and the encoding is always UTF-16.</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> In any case, the multibyte character encoding used by this function is specified by the currently active C locale.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> pc16 </td> <td> - </td> <td> pointer to the location where the resulting 16-bit wide character will be written </td> +</tr> <tr class="t-par"> <td> s </td> <td> - </td> <td> pointer to the multibyte character string used as input </td> +</tr> <tr class="t-par"> <td> n </td> <td> - </td> <td> limit on the number of bytes in s that can be examined </td> +</tr> <tr class="t-par"> <td> ps </td> <td> - </td> <td> pointer to the conversion state object used when interpreting the multibyte string </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The first of the following that applies:</p> +<ul> +<li> <code>0</code> if the character converted from <code>s</code> (and stored in <code>*pc16</code> if non-null) was the null character </li> +<li> the number of bytes <code>[1...n]</code> of the multibyte character successfully converted from <code>s</code> </li> +<li> <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">3</span></code> if the next <code>char16_t</code> from a multi-<code>char16_t</code> character (e.g. a surrogate pair) has now been written to <code>*pc16</code>. No bytes are processed from the input in this case. </li> +<li> <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">2</span></code> if the next <code>n</code> bytes constitute an incomplete, but so far valid, multibyte character. Nothing is written to <code>*pc16</code>. </li> +<li> <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">1</span></code> if encoding error occurs. Nothing is written to <code>*pc16</code>, the value <code><a href="../../error/errno_macros" title="c/error/errno macros">EILSEQ</a></code> is stored in <code><a href="../../error/errno" title="c/error/errno">errno</a></code> and the value of <code>*ps</code> is unspecified. </li> +</ul> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <uchar.h> + +mbstate_t state; + +int main(void) +{ + setlocale(LC_ALL, "en_US.utf8"); + const char in[] = u8"zß水🍌"; // or "z\u00df\u6c34\U0001F34C" + const size_t in_sz = sizeof in / sizeof *in; + + printf("Processing %zu UTF-8 code units: [ ", in_sz); + for (size_t n = 0; n < in_sz; ++n) + printf("%#x ", (unsigned char)in[n]); + puts("]"); + + char16_t out[in_sz]; + const char *p_in = in, *end = in + in_sz; + char16_t *p_out = out; + for (size_t rc; (rc = mbrtoc16(p_out, p_in, end - p_in, &state));) + { + if (rc == (size_t)-1) // invalid input + break; + else if(rc == (size_t)-2) // truncated input + break; + else if(rc == (size_t)-3) // UTF-16 high surrogate + p_out += 1; + else + { + p_in += rc; + p_out += 1; + }; + } + + const size_t out_sz = p_out - out + 1; + printf("into %zu UTF-16 code units: [ ", out_sz); + for (size_t x = 0; x < out_sz; ++x) + printf("%#x ", out[x]); + puts("]"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Processing 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0 ] +into 6 UTF-16 code units: [ 0x7a 0xdf 0x6c34 0xd83c 0xdf4c 0 ]</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.30.1.3 The mbrtoc16 function (p: 408-409) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.28.1.1 The mbrtoc16 function (p: 398-399) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="c16rtomb" title="c/string/multibyte/c16rtomb"> <span class="t-lines"><span>c16rtomb</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a 16-bit wide character to narrow multibyte string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/multibyte/mbrtoc16" title="cpp/string/multibyte/mbrtoc16">C++ documentation</a></span> for <code>mbrtoc16</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/mbrtoc16" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/mbrtoc16</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fmbrtoc32.html b/devdocs/c/string%2Fmultibyte%2Fmbrtoc32.html new file mode 100644 index 00000000..f67e7de6 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmbrtoc32.html @@ -0,0 +1,77 @@ + <h1 id="firstHeading" class="firstHeading">mbrtoc32</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><uchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">size_t mbrtoc32( char32_t restrict * pc32, const char * restrict s, + size_t n, mbstate_t * restrict ps );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Converts a single code point from its narrow multibyte character representation to its variable-length 32-bit wide character representation (but typically, UTF-32).</p> +<p>If <code>s</code> is not a null pointer, inspects at most <code>n</code> bytes of the multibyte character string, beginning with the byte pointed to by <code>s</code> to determine the number of bytes necessary to complete the next multibyte character (including any shift sequences, and taking into account the current multibyte conversion state <code>*ps</code>). If the function determines that the next multibyte character in <code>s</code> is complete and valid, converts it to the corresponding 32-bit wide character and stores it in <code>*pc32</code> (if <code>pc32</code> is not null).</p> +<p>If the multibyte character in <code>*s</code> corresponds to a multi-char32_t sequence (not possible with UTF-32), then after the first call to this function, <code>*ps</code> is updated in such a way that the next calls to <code>mbrtoc32</code> will write out the additional char32_t, without considering <code>*s</code>.</p> +<p>If <code>s</code> is a null pointer, the values of <code>n</code> and <code>pc32</code> are ignored and the call is equivalent to <code>mbrtoc32<span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/NULL"><span class="kw103">NULL</span></a>, <span class="st0">""</span>, <span class="nu0">1</span>, ps<span class="br0">)</span></code>.</p> +<p>If the wide character produced is the null character, the conversion state <code>*ps</code> represents the initial shift state.</p> +<p>If the macro <code>__STDC_UTF_32__</code> is defined, the 32-bit encoding used by this function is UTF-32; otherwise, it is implementation-defined. <span class="t-rev-inl t-since-c23"><span>The macro is always defined and the encoding is always UTF-32.</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> In any case, the multibyte character encoding used by this function is specified by the currently active C locale.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> pc32 </td> <td> - </td> <td> pointer to the location where the resulting 32-bit wide character will be written </td> +</tr> <tr class="t-par"> <td> s </td> <td> - </td> <td> pointer to the multibyte character string used as input </td> +</tr> <tr class="t-par"> <td> n </td> <td> - </td> <td> limit on the number of bytes in s that can be examined </td> +</tr> <tr class="t-par"> <td> ps </td> <td> - </td> <td> pointer to the conversion state object used when interpreting the multibyte string </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The first of the following that applies:</p> +<ul> +<li> <code>0</code> if the character converted from <code>s</code> (and stored in <code>*pc32</code> if non-null) was the null character </li> +<li> the number of bytes <code>[1...n]</code> of the multibyte character successfully converted from <code>s</code> </li> +<li> <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">3</span></code> if the next <code>char32_t</code> from a multi-<code>char32_t</code> character has now been written to <code>*pc32</code>. No bytes are processed from the input in this case. </li> +<li> <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">2</span></code> if the next <code>n</code> bytes constitute an incomplete, but so far valid, multibyte character. Nothing is written to <code>*pc32</code>. </li> +<li> <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">1</span></code> if encoding error occurs. Nothing is written to <code>*pc32</code>, the value <code><a href="../../error/errno_macros" title="c/error/errno macros">EILSEQ</a></code> is stored in <code><a href="../../error/errno" title="c/error/errno">errno</a></code> and the value of <code>*ps</code> is unspecified. </li> +</ul> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <locale.h> +#include <string.h> +#include <uchar.h> +#include <assert.h> + +int main(void) +{ + setlocale(LC_ALL, "en_US.utf8"); + char in[] = u8"zß水🍌"; // or "z\u00df\u6c34\U0001F34C" + const size_t in_size = sizeof in / sizeof *in; + + printf("Processing %zu UTF-8 code units: [ ", in_size); + for (size_t i = 0; i < in_size; ++i) + printf("0x%02x ", (unsigned char)in[i]); + + puts("]"); + + char32_t out[in_size]; + char32_t *p_out = out; + char *p_in = in, *end = in + in_size; + mbstate_t state; + memset(&state, 0, sizeof(state)); + size_t rc; + while ((rc = mbrtoc32(p_out, p_in, end - p_in, &state))) + { + assert(rc != (size_t)-3); // no surrogate pairs in UTF-32 + if (rc == (size_t)-1) break; // invalid input + if (rc == (size_t)-2) break; // truncated input + p_in += rc; + ++p_out; + } + + size_t out_size = p_out+1 - out; + printf("into %zu UTF-32 code units: [ ", out_size); + for (size_t i = 0; i < out_size; ++i) + printf("0x%08X ", out[i]); + + puts("]"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Processing 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0x00 ] +into 5 UTF-32 code units: [ 0x0000007A 0x000000DF 0x00006C34 0x0001F34C 0x00000000 ]</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.30.1.5 The mbrtoc32 function (p: 410) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.28.1.3 The mbrtoc32 function (p: 293-294) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.28.1.3 The mbrtoc32 function (p: 400-401) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="c32rtomb" title="c/string/multibyte/c32rtomb"> <span class="t-lines"><span>c32rtomb</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a 32-bit wide character to narrow multibyte string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/multibyte/mbrtoc32" title="cpp/string/multibyte/mbrtoc32">C++ documentation</a></span> for <code>mbrtoc32</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/mbrtoc32" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/mbrtoc32</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fmbrtoc8.html b/devdocs/c/string%2Fmultibyte%2Fmbrtoc8.html new file mode 100644 index 00000000..826b97a4 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmbrtoc8.html @@ -0,0 +1,29 @@ + <h1 id="firstHeading" class="firstHeading">mbrtoc8</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><uchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">size_t mbrtoc8( char8_t * restrict pc8, const char * restrict s, + size_t n, mbstate_t * restrict ps );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <p>Converts a narrow multibyte character to UTF-8 encoding.</p> +<p>If <code>s</code> is not a null pointer, inspects at most <code>n</code> bytes of the multibyte character string, beginning with the byte pointed to by <code>s</code> to determine the number of bytes necessary to complete the next multibyte character (including any shift sequences). If the function determines that the next multibyte character in <code>s</code> is complete and valid, converts it to UTF-8 and stores the first UTF-8 code unit in <code>*pc8</code> (if <code>pc8</code> is not null).</p> +<p>If UTF-8 encoding of the multibyte character in <code>*s</code> consists of more than one UTF-8 code unit, then after the first call to this function, <code>*ps</code> is updated in such a way that the next call to <code>mbrtoc8</code> will write out the additional UTF-8 code units, without considering <code>*s</code>.</p> +<p>If <code>s</code> is a null pointer, the values of <code>n</code> and <code>pc8</code> are ignored and the call is equivalent to <code>mbrtoc8(nullptr, "", 1, ps)</code>.</p> +<p>If UTF-8 code unit produced is <code>u8'\0'</code>, the conversion state <code>*ps</code> represents the initial shift state.</p> +<p>The multibyte encoding used by this function is specified by the currently active C locale.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> pc8 </td> <td> - </td> <td> pointer to the location where the resulting UTF-8 code units will be written </td> +</tr> <tr class="t-par"> <td> s </td> <td> - </td> <td> pointer to the multibyte character string used as input </td> +</tr> <tr class="t-par"> <td> n </td> <td> - </td> <td> limit on the number of bytes in s that can be examined </td> +</tr> <tr class="t-par"> <td> ps </td> <td> - </td> <td> pointer to the conversion state object used when interpreting the multibyte string </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The first of the following that applies:</p> +<ul> +<li> <code>0</code> if the character converted from <code>s</code> (and stored in <code>*pc8</code> if non-null) was the null character </li> +<li> the number of bytes <code>[1...n]</code> of the multibyte character successfully converted from <code>s</code> </li> +<li> <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">3</span></code> if the next UTF-8 code unit from a character whose encoding consists of multiple code units has now been written to <code>*pc8</code>. No bytes are processed from the input in this case. </li> +<li> <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">2</span></code> if the next <code>n</code> bytes constitute an incomplete, but so far valid, multibyte character. Nothing is written to <code>*pc8</code>. </li> +<li> <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">1</span></code> if encoding error occurs. Nothing is written to <code>*pc8</code>, the value <code><a href="../../error/errno_macros" title="c/error/errno macros">EILSEQ</a></code> is stored in <code><a href="../../error/errno" title="c/error/errno">errno</a></code> and the value of <code>*ps</code> is unspecified. </li> +</ul> <h3 id="Example"> Example</h3> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="c8rtomb" title="c/string/multibyte/c8rtomb"> <span class="t-lines"><span>c8rtomb</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> converts UTF-8 string to narrow multibyte encoding <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/multibyte/mbrtoc8" title="cpp/string/multibyte/mbrtoc8">C++ documentation</a></span> for <code>mbrtoc8</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/mbrtoc8" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/mbrtoc8</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fmbrtowc.html b/devdocs/c/string%2Fmultibyte%2Fmbrtowc.html new file mode 100644 index 00000000..9f8d4dea --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmbrtowc.html @@ -0,0 +1,67 @@ + <h1 id="firstHeading" class="firstHeading">mbrtowc</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">size_t mbrtowc( wchar_t* pwc, const char* s, size_t n, mbstate_t* ps );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">size_t mbrtowc( wchar_t *restrict pwc, const char *restrict s, size_t n, + mbstate_t *restrict ps );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Converts a narrow multibyte character to its wide character representation.</p> +<p>If <code>s</code> is not a null pointer, inspects at most <code>n</code> bytes of the multibyte character string, beginning with the byte pointed to by <code>s</code> to determine the number of bytes necessary to complete the next multibyte character (including any shift sequences, and taking into account the current multibyte conversion state <code>*ps</code>). If the function determines that the next multibyte character in <code>s</code> is complete and valid, converts it to the corresponding wide character and stores it in <code>*pwc</code> (if <code>pwc</code> is not null).</p> +<p>If <code>s</code> is a null pointer, the values of <code>n</code> and <code>pwc</code> are ignored and call is equivalent to <code>mbrtowc<span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/NULL"><span class="kw103">NULL</span></a>, <span class="st0">""</span>, <span class="nu0">1</span>, ps<span class="br0">)</span></code>.</p> +<p>If the wide character produced is the null character, the conversion state stored in <code>*ps</code> is the initial shift state.</p> +<p>If the environment macro <code>__STDC_ISO_10646__</code> is defined, the values of type <code>wchar_t</code> are the same as the short identifiers of the characters in the Unicode required set (typically UTF-32 encoding); otherwise, it is implementation-defined. In any case, the multibyte character encoding used by this function is specified by the currently active C locale.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> pwc </td> <td> - </td> <td> pointer to the location where the resulting wide character will be written </td> +</tr> <tr class="t-par"> <td> s </td> <td> - </td> <td> pointer to the multibyte character string used as input </td> +</tr> <tr class="t-par"> <td> n </td> <td> - </td> <td> limit on the number of bytes in s that can be examined </td> +</tr> <tr class="t-par"> <td> ps </td> <td> - </td> <td> pointer to the conversion state used when interpreting the multibyte character string </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The first of the following that applies:</p> +<ul> +<li> <code>0</code> if the character converted from <code>s</code> (and stored in <code>pwc</code> if non-null) was the null character </li> +<li> the number of bytes <code>[1...n]</code> of the multibyte character successfully converted from <code>s</code> </li> +<li> <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">2</span></code> if the next <code>n</code> bytes constitute an incomplete, but so far valid, multibyte character. Nothing is written to <code>*pwc</code>. </li> +<li> <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">1</span></code> if encoding error occurs. Nothing is written to <code>*pwc</code>, the value <code><a href="../../error/errno_macros" title="c/error/errno macros">EILSEQ</a></code> is stored in <code><a href="../../error/errno" title="c/error/errno">errno</a></code> and the value of <code>*ps</code> is left unspecified. </li> +</ul> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <locale.h> +#include <string.h> +#include <wchar.h> + +int main(void) +{ + setlocale(LC_ALL, "en_US.utf8"); + mbstate_t state; + memset(&state, 0, sizeof state); + char in[] = u8"z\u00df\u6c34\U0001F34C"; // or u8"zß水🍌" + size_t in_sz = sizeof in / sizeof *in; + + printf("Processing %zu UTF-8 code units: [ ", in_sz); + for(size_t n = 0; n < in_sz; ++n) printf("%#x ", (unsigned char)in[n]); + puts("]"); + + wchar_t out[in_sz]; + char *p_in = in, *end = in + in_sz; + wchar_t *p_out = out; + int rc; + while((rc = mbrtowc(p_out, p_in, end - p_in, &state)) > 0) + { + p_in += rc; + p_out += 1; + } + + size_t out_sz = p_out - out + 1; + printf("into %zu wchar_t units: [ ", out_sz); + for(size_t x = 0; x < out_sz; ++x) printf("%#x ", out[x]); + puts("]"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Processing 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0 ] +into 5 wchar_t units: [ 0x7a 0xdf 0x6c34 0x1f34c 0 ]</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.6.3.2 The mbrtowc function (p: 443) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.6.3.2 The mbrtowc function (p: 389) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="mbtowc" title="c/string/multibyte/mbtowc"> <span class="t-lines"><span>mbtowc</span></span></a></div> </td> <td> converts the next multibyte character to wide character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcrtomb" title="c/string/multibyte/wcrtomb"> <span class="t-lines"><span>wcrtomb</span><span>wcrtomb_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a wide character to its multibyte representation, given state <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/multibyte/mbrtowc" title="cpp/string/multibyte/mbrtowc">C++ documentation</a></span> for <code>mbrtowc</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/mbrtowc" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/mbrtowc</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fmbsinit.html b/devdocs/c/string%2Fmultibyte%2Fmbsinit.html new file mode 100644 index 00000000..0f1c9207 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmbsinit.html @@ -0,0 +1,50 @@ + <h1 id="firstHeading" class="firstHeading">mbsinit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int mbsinit( const mbstate_t* ps);</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>If <code>ps</code> is not a null pointer, the <code>mbsinit</code> function determines whether the pointed-to <code><a href="mbstate_t" title="c/string/multibyte/mbstate t">mbstate_t</a></code> object describes the initial conversion state.</p> +<h3 id="Notes"> Notes</h3> <p>Although a zero-initialized <code><a href="mbstate_t" title="c/string/multibyte/mbstate t">mbstate_t</a></code> always represents the initial conversion state, there may be other values of <code><a href="mbstate_t" title="c/string/multibyte/mbstate t">mbstate_t</a></code> that also represent the initial conversion state.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ps </td> <td> - </td> <td> pointer to the mbstate_t object to examine </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>0</code> if <code>ps</code> is not a null pointer and does not represent the initial conversion state, nonzero value otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <string.h> +#include <stdio.h> +#include <wchar.h> + +int main(void) +{ + // allow mbrlen() to work with UTF-8 multibyte encoding + setlocale(LC_ALL, "en_US.utf8"); + // UTF-8 narrow multibyte encoding + const char* str = u8"水"; // or u8"\u6c34" or "\xe6\xb0\xb4" + static mbstate_t mb; // zero-initialize + (void)mbrlen(&str[0], 1, &mb); + if (!mbsinit(&mb)) { + printf("After processing the first 1 byte of %s,\n" + "the conversion state is not initial\n\n", str); + } + + (void)mbrlen(&str[1], strlen(str), &mb); + if (mbsinit(&mb)) { + printf("After processing the remaining 2 bytes of %s,\n" + "the conversion state is initial conversion state\n", str); + } +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">After processing the first 1 byte of 水, +the conversion state is not initial + +After processing the remaining 2 bytes of 水, +the conversion state is initial conversion state</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.29.6.2.1 The mbsinit function (p: 322) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.6.2.1 The mbsinit function (p: 441-442) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.6.2.1 The mbsinit function (p: 387-388) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="mbstate_t" title="c/string/multibyte/mbstate t"> <span class="t-lines"><span>mbstate_t</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> conversion state information necessary to iterate multibyte character strings <br> <span class="t-mark">(class)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/multibyte/mbsinit" title="cpp/string/multibyte/mbsinit">C++ documentation</a></span> for <code>mbsinit</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/mbsinit" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/mbsinit</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fmbsrtowcs.html b/devdocs/c/string%2Fmultibyte%2Fmbsrtowcs.html new file mode 100644 index 00000000..8154ac0a --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmbsrtowcs.html @@ -0,0 +1,79 @@ + <h1 id="firstHeading" class="firstHeading">mbsrtowcs, mbsrtowcs_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td><pre data-language="c">size_t mbsrtowcs( wchar_t* dst, const char** src, size_t len, mbstate_t* ps );</pre></td> <td> +<span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> +</td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">size_t mbsrtowcs( wchar_t *restrict dst, const char **restrict src, size_t len, + mbstate_t *restrict ps );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t mbsrtowcs_s( size_t *restrict retval, + wchar_t *restrict dst, rsize_t dstsz, + const char **restrict src, rsize_t len, + mbstate_t *restrict ps );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <span class="t-li">1)</span> Converts a null-terminated multibyte character sequence, which begins in the conversion state described by <code>*ps</code>, from the array whose first element is pointed to by <code>*src</code> to its wide character representation. If <code>dst</code> is not null, converted characters are stored in the successive elements of the wchar_t array pointed to by <code>dst</code>. No more than <code>len</code> wide characters are written to the destination array. Each multibyte character is converted as if by a call to <code><a href="mbrtowc" title="c/string/multibyte/mbrtowc">mbrtowc</a></code>. The conversion stops if: <ul> +<li> The multibyte null character was converted and stored. <code>*src</code> is set to null pointer value and <code>*ps</code> represents the initial shift state. </li> +<li> An invalid multibyte character (according to the current C locale) was encountered. <code>*src</code> is set to point at the beginning of the first unconverted multibyte character. </li> +<li> the next wide character to be stored would exceed <code>len</code>. <code>*src</code> is set to point at the beginning of the first unconverted multibyte character. This condition is not checked if <code>dst</code> is a null pointer.</li> +</ul> <span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that <ul> +<li> the function returns its result as an out-parameter <code>retval</code> </li> +<li> if no null character was written to <code>dst</code> after <code>len</code> wide characters were written, then <code>L'\0'</code> is stored in <code>dst[len]</code>, which means len+1 total wide characters are written </li> +<li> the function clobbers the destination array from the terminating null and until <code>dstsz</code> </li> +<li> If <code>src</code> and <code>dst</code> overlap, the behavior is unspecified. </li> +<li> the following errors are detected at runtime and call the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: </li> +</ul> <dl> +<dd> +<ul> +<li> <code>retval</code>, <code>ps</code>, <code>src</code>, or <code>*src</code> is a null pointer </li> +<li> <code>dstsz</code> or <code>len</code> is greater than <code>RSIZE_MAX/sizeof(wchar_t)</code> (unless <code>dst</code> is null) </li> +<li> <code>dstsz</code> is not zero (unless <code>dst</code> is null) </li> +<li> There is no null character in the first <code>dstsz</code> multibyte characters in the <code>*src</code> array and <code>len</code> is greater than <code>dstsz</code> (unless <code>dst</code> is null) </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>mbsrtowcs_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../wide" title="c/string/wide"><code><wchar.h></code></a>.</dd> +</dl> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dst </td> <td> - </td> <td> pointer to wide character array where the results will be stored </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to pointer to the first element of a null-terminated multibyte string </td> +</tr> <tr class="t-par"> <td> len </td> <td> - </td> <td> number of wide characters available in the array pointed to by dst </td> +</tr> <tr class="t-par"> <td> ps </td> <td> - </td> <td> pointer to the conversion state object </td> +</tr> <tr class="t-par"> <td> dstsz </td> <td> - </td> <td> max number of wide characters that will be written (size of the <code>dst</code> array) </td> +</tr> <tr class="t-par"> <td> retval </td> <td> - </td> <td> pointer to a size_t object where the result will be stored </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> On success, returns the number of wide characters, excluding the terminating <code>L'\0'</code>, written to the character array. If <code>dst</code> is a null pointer, returns the number of wide characters that would have been written given unlimited length. On conversion error (if invalid multibyte character was encountered), returns <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">1</span></code>, stores <code><a href="../../error/errno_macros" title="c/error/errno macros">EILSEQ</a></code> in <code><a href="../../error/errno" title="c/error/errno">errno</a></code>, and leaves <code>*ps</code> in unspecified state.</div> <div class="t-li1"> +<span class="t-li">2)</span> zero on success (in which case the number of wide characters excluding terminating zero that were, or would be written to <code>dst</code>, is stored in <code>*retval</code>), non-sero on error. In case of a runtime constraint violation, stores <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">1</span></code> in <code>*retval</code> (unless <code>retval</code> is null) and sets <code>dst[0]</code> to <code>L'\0'</code> (unless <code>dst</code> is null or <code>dstmax</code> is zero or greater than <code>RSIZE_MAX</code>)</div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <locale.h> +#include <wchar.h> +#include <string.h> + +void print_as_wide(const char* mbstr) +{ + mbstate_t state; + memset(&state, 0, sizeof state); + size_t len = 1 + mbsrtowcs(NULL, &mbstr, 0, &state); + wchar_t wstr[len]; + mbsrtowcs(&wstr[0], &mbstr, len, &state); + wprintf(L"Wide string: %ls \n", wstr); + wprintf(L"The length, including L'\\0': %zu\n", len); +} + +int main(void) +{ + setlocale(LC_ALL, "en_US.utf8"); + print_as_wide(u8"z\u00df\u6c34\U0001f34c"); // u8"zß水🍌" +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Wide string: zß水🍌 +The length, including L'\0': 5</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.29.6.4.1 The mbsrtowcs function (p: 445) </li> +<li> K.3.9.3.2.1 The mbsrtowcs_s function (p: 648-649) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.6.4.1 The mbsrtowcs function (p: 391) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="mbstowcs" title="c/string/multibyte/mbstowcs"> <span class="t-lines"><span>mbstowcs</span><span>mbstowcs_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a narrow multibyte character string to wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="mbrtowc" title="c/string/multibyte/mbrtowc"> <span class="t-lines"><span>mbrtowc</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> converts the next multibyte character to wide character, given state <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcsrtombs" title="c/string/multibyte/wcsrtombs"> <span class="t-lines"><span>wcsrtombs</span><span>wcsrtombs_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a wide string to narrow multibyte character string, given state <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/multibyte/mbsrtowcs" title="cpp/string/multibyte/mbsrtowcs">C++ documentation</a></span> for <code>mbsrtowcs</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/mbsrtowcs" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/mbsrtowcs</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fmbstate_t.html b/devdocs/c/string%2Fmultibyte%2Fmbstate_t.html new file mode 100644 index 00000000..bed230ed --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmbstate_t.html @@ -0,0 +1,18 @@ + <h1 id="firstHeading" class="firstHeading">mbstate_t</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><uchar.h></code> </th> <th> </th> <th><span class="t-mark-rev t-since-c11">(since C11)</span></th> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c95"> <td> <pre data-language="c">struct mbstate_t;</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>The type <code>mbstate_t</code> is a trivial non-array type that can represent any of the conversion states that can occur in an implementation-defined set of supported multibyte character encoding rules. Zero-initialized value of <code>mbstate_t</code> represents the initial conversion state, although other values of <code>mbstate_t</code> may exist that also represent the initial conversion state.</p> +<p>Possible implementation of <code>mbstate_t</code> is a struct type holding an array representing the incomplete multibyte character, an integer counter indicating the number of bytes in the array that have been processed, and a representation of the current shift state.</p> +<p>The following functions should not be called from multiple threads without synchronization with the <code>mbstate_t*</code> argument of a null pointer due to possible data races: <code><a href="mbrlen" title="c/string/multibyte/mbrlen">mbrlen</a></code>, <code><a href="mbrtowc" title="c/string/multibyte/mbrtowc">mbrtowc</a></code>, <code><a href="mbsrtowcs" title="c/string/multibyte/mbsrtowcs">mbsrtowcs</a></code>, <code><a href="mbtowc" title="c/string/multibyte/mbtowc">mbtowc</a></code>, <code><a href="wcrtomb" title="c/string/multibyte/wcrtomb">wcrtomb</a></code>, <code><a href="wcsrtombs" title="c/string/multibyte/wcsrtombs">wcsrtombs</a></code>, <code><a href="wctomb" title="c/string/multibyte/wctomb">wctomb</a></code>.</p> +<h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.1/2 Introduction (p: 402) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.1/2 Introduction (p: 348) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="mbsinit" title="c/string/multibyte/mbsinit"> <span class="t-lines"><span>mbsinit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if the mbstate_t object represents initial shift state <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/multibyte/mbstate_t" title="cpp/string/multibyte/mbstate t">C++ documentation</a></span> for <code>mbstate_t</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/mbstate_t" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/mbstate_t</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fmbstowcs.html b/devdocs/c/string%2Fmultibyte%2Fmbstowcs.html new file mode 100644 index 00000000..80b28999 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmbstowcs.html @@ -0,0 +1,78 @@ + <h1 id="firstHeading" class="firstHeading">mbstowcs, mbstowcs_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">size_t mbstowcs( wchar_t *dst, const char *src, size_t len)</pre> +</td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">size_t mbstowcs( wchar_t *restrict dst, const char *restrict src, size_t len)</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t mbstowcs_s(size_t *restrict retval, wchar_t *restrict dst, + rsize_t dstsz, const char *restrict src, rsize_t len);</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Converts a multibyte character string from the array whose first element is pointed to by <code>src</code> to its wide character representation. Converted characters are stored in the successive elements of the array pointed to by <code>dst</code>. No more than <code>len</code> wide characters are written to the destination array.</div> <div class="t-li1"> + Each character is converted as if by a call to <code><a href="mbtowc" title="c/string/multibyte/mbtowc">mbtowc</a></code>, except that the mbtowc conversion state is unaffected. The conversion stops if:</div> <div class="t-li1"> + * The multibyte null character was converted and stored.</div> <div class="t-li1"> + * An invalid (in the current C locale) multibyte character was encountered.</div> <div class="t-li1"> + * The next wide character to be stored would exceed <code>len</code>.</div> <div class="t-li1"> + If <code>src</code> and <code>dst</code> overlap, the behavior is undefined</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that</div> <div class="t-li1"> + * conversion is as-if by <code><a href="mbrtowc" title="c/string/multibyte/mbrtowc">mbrtowc</a></code>, not <code><a href="mbtowc" title="c/string/multibyte/mbtowc">mbtowc</a></code> +</div> <div class="t-li1"> + * the function returns its result as an out-parameter <code>retval</code> +</div> <div class="t-li1"> + * if no null character was written to <code>dst</code> after <code>len</code> wide characters were written, then <code>L'\0'</code> is stored in <code>dst[len]</code>, which means len+1 total wide characters are written</div> <div class="t-li1"> + * if <code>dst</code> is a null pointer, the number of wide characters that would be produced is stored in <code>*retval</code> +</div> <div class="t-li1"> + * the function clobbers the destination array from the terminating null and until <code>dstsz</code> +</div> <div class="t-li1"> + * If <code>src</code> and <code>dst</code> overlap, the behavior is unspecified.</div> <div class="t-li1"> + * the following errors are detected at runtime and call the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> <code>retval</code> or <code>src</code> is a null pointer </li> +<li> <code>dstsz</code> or <code>len</code> is greater than <code>RSIZE_MAX/sizeof(wchar_t)</code> (unless <code>dst</code> is null) </li> +<li> <code>dstsz</code> is not zero (unless <code>dst</code> is null) </li> +<li> There is no null character in the first <code>dstsz</code> multibyte characters in the <code>src</code> array and <code>len</code> is greater than <code>dstsz</code> (unless <code>dst</code> is null) </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>mbstowcs_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../../program" title="c/program"><code><stdlib.h></code></a>.</dd> +</dl> +</div> <h3 id="Notes"> Notes</h3> <p>In most implementations, <code>mbstowcs</code> updates a global static object of type <code><a href="mbstate_t" title="c/string/multibyte/mbstate t">mbstate_t</a></code> as it processes through the string, and cannot be called simultaneously by two threads, <code><a href="mbsrtowcs" title="c/string/multibyte/mbsrtowcs">mbsrtowcs</a></code> should be used in such cases.</p> +<p>POSIX specifies a common extension: if <code>dst</code> is a null pointer, this function returns the number of wide characters that would be written to <code>dst</code>, if converted. Similar behavior is standard for <code>mbstowcs_s</code> and for <code><a href="mbsrtowcs" title="c/string/multibyte/mbsrtowcs">mbsrtowcs</a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dst </td> <td> - </td> <td> pointer to wide character array where the wide string will be stored </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the first element of a null-terminated multibyte string to convert </td> +</tr> <tr class="t-par"> <td> len </td> <td> - </td> <td> number of wide characters available in the array pointed to by dst </td> +</tr> <tr class="t-par"> <td> dstsz </td> <td> - </td> <td> max number of wide characters that will be written (size of the <code>dst</code> array) </td> +</tr> <tr class="t-par"> <td> retval </td> <td> - </td> <td> pointer to a size_t object where the result will be stored </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> On success, returns the number of wide characters, excluding the terminating <code>L'\0'</code>, written to the destination array. On conversion error (if invalid multibyte character was encountered), returns <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">1</span></code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> zero on success (in which case the number of wide characters excluding terminating zero that were, or would be written to <code>dst</code>, is stored in <code>*retval</code>), non-zero on error. In case of a runtime constraint violation, stores <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">1</span></code> in <code>*retval</code> (unless <code>retval</code> is null) and sets <code>dst[0]</code> to <code>L'\0'</code> (unless <code>dst</code> is null or <code>dstmax</code> is zero or greater than <code>RSIZE_MAX</code>)</div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <locale.h> +#include <stdlib.h> +#include <wchar.h> + +int main(void) +{ + setlocale(LC_ALL, "en_US.utf8"); + const char* mbstr = u8"z\u00df\u6c34\U0001F34C"; // or u8"zß水🍌" + wchar_t wstr[5]; + mbstowcs(wstr, mbstr, 5); + wprintf(L"MB string: %s\n", mbstr); + wprintf(L"Wide string: %ls\n", wstr); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">MB string: zß水🍌 +Wide string: zß水🍌</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.22.8.1 The mbstowcs function (p: 359) </li> +<li> K.3.6.5.1 The mbstowcs_s function (p: 611-612) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.8.1 The mbstowcs function (p: 323) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.8.1 The mbstowcs function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="mbsrtowcs" title="c/string/multibyte/mbsrtowcs"> <span class="t-lines"><span>mbsrtowcs</span><span>mbsrtowcs_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a narrow multibyte character string to wide string, given state <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcstombs" title="c/string/multibyte/wcstombs"> <span class="t-lines"><span>wcstombs</span><span>wcstombs_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a wide string to narrow multibyte character string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/multibyte/mbstowcs" title="cpp/string/multibyte/mbstowcs">C++ documentation</a></span> for <code>mbstowcs</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/mbstowcs" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/mbstowcs</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fmbtowc.html b/devdocs/c/string%2Fmultibyte%2Fmbtowc.html new file mode 100644 index 00000000..7eed6100 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fmbtowc.html @@ -0,0 +1,56 @@ + <h1 id="firstHeading" class="firstHeading">mbtowc</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">int mbtowc( wchar_t *pwc, const char *s, size_t n )</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int mbtowc( wchar_t *restrict pwc, const char *restrict s, size_t n )</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Converts a multibyte character whose first byte is pointed to by <code>s</code> to a wide character, written to <code>*pwc</code> if <code>pwc</code> is not null.</p> +<p>If <code>s</code> is a null pointer, resets the global conversion state and determines whether shift sequences are used.</p> +<h3 id="Notes"> Notes</h3> <p>Each call to <code>mbtowc</code> updates the internal global conversion state (a static object of type <code><a href="mbstate_t" title="c/string/multibyte/mbstate t">mbstate_t</a></code>, known only to this function). If the multibyte encoding uses shift states, care must be taken to avoid backtracking or multiple scans. In any case, multiple threads should not call <code>mbtowc</code> without synchronization: <code><a href="mbrtowc" title="c/string/multibyte/mbrtowc">mbrtowc</a></code> may be used instead.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> pwc </td> <td> - </td> <td> pointer to the wide character for output </td> +</tr> <tr class="t-par"> <td> s </td> <td> - </td> <td> pointer to the multibyte character </td> +</tr> <tr class="t-par"> <td> n </td> <td> - </td> <td> limit on the number of bytes in s that can be examined </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>If <code>s</code> is not a null pointer, returns the number of bytes that are contained in the multibyte character or <code>-1</code> if the first bytes pointed to by <code>s</code> do not form a valid multibyte character or <code>0</code> if <code>s</code> is pointing at the null character <code>'\0'</code>.</p> +<p>If <code>s</code> is a null pointer, resets its internal conversion state to represent the initial shift state and returns <code>0</code> if the current multibyte encoding is not state-dependent (does not use shift sequences) or a non-zero value if the current multibyte encoding is state-dependent (uses shift sequences).</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <wchar.h> + +// print multibyte string to wide-oriented stdout +// equivalent to wprintf(L"%s\n", ptr); +void print_mb(const char* ptr) +{ + mbtowc(NULL, 0, 0); // reset the conversion state + const char* end = ptr + strlen(ptr); + int ret = 0; + for (wchar_t wc; (ret = mbtowc(&wc, ptr, end - ptr)) > 0; ptr += ret) + wprintf(L"%lc", wc); + wprintf(L"\n"); +} + +int main(void) +{ + setlocale(LC_ALL, "en_US.utf8"); + // UTF-8 narrow multibyte encoding + print_mb(u8"z\u00df\u6c34\U0001F34C"); // or u8"zß水🍌" +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">zß水🍌</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.24.7.2 The mbtowc function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.22.7.2 The mbtowc function (p: 260) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.22.7.2 The mbtowc function (p: 358) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.7.2 The mbtowc function (p: 322) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.7.2 The mbtowc function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="mbrtowc" title="c/string/multibyte/mbrtowc"> <span class="t-lines"><span>mbrtowc</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> converts the next multibyte character to wide character, given state <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="mblen" title="c/string/multibyte/mblen"> <span class="t-lines"><span>mblen</span></span></a></div> </td> <td> returns the number of bytes in the next multibyte character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/multibyte/mbtowc" title="cpp/string/multibyte/mbtowc">C++ documentation</a></span> for <code>mbtowc</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/mbtowc" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/mbtowc</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fwcrtomb.html b/devdocs/c/string%2Fmultibyte%2Fwcrtomb.html new file mode 100644 index 00000000..1addcb02 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fwcrtomb.html @@ -0,0 +1,84 @@ + <h1 id="firstHeading" class="firstHeading">wcrtomb, wcrtomb_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-since-c95"> <td> <pre data-language="c">size_t wcrtomb( char *s, wchar_t wc, mbstate_t *ps);</pre> +</td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">size_t wcrtomb( char *restrict s, wchar_t wc, mbstate_t *restrict ps);</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t wcrtomb_s(size_t *restrict retval, char *restrict s, rsize_t ssz, + wchar_t wc, mbstate_t *restrict ps);</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Converts a wide character to its narrow multibyte representation.</p> +<div class="t-li1"> +<span class="t-li">1)</span> If <code>s</code> is not a null pointer, the function determines the number of bytes necessary to store the multibyte character representation of <code>wc</code> (including any shift sequences, and taking into account the current multibyte conversion state <code>*ps</code>), and stores the multibyte character representation in the character array whose first element is pointed to by <code>s</code>, updating <code>*ps</code> as necessary. At most <code>MB_CUR_MAX</code> bytes can be written by this function.</div> <div class="t-li1"> + If <code>s</code> is a null pointer, the call is equivalent to <code>wcrtomb(buf, L'\0', ps)</code> for some internal buffer <code>buf</code>.</div> <div class="t-li1"> + If wc is the null wide character <code>L'\0'</code>, a null byte is stored, preceded by any shift sequence necessary to restore the initial shift state and the conversion state parameter <code>*ps</code> is updated to represent the initial shift state.</div> <div class="t-li1"> + If the environment macro <code>__STDC_ISO_10646__</code> is defined, the values of type <code>wchar_t</code> are the same as the short identifiers of the characters in the Unicode required set (typically UTF-32 encoding); otherwise, it is implementation-defined. In any case, the multibyte character encoding used by this function is specified by the currently active C locale.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that</div> <div class="t-li1"> + if <code>s</code> is a null pointer, the call is equivalent to <code>wcrtomb_s(&retval, buf, sizeof buf, L'\0', ps)</code> with internal variables <code>retval</code> and <code>buf</code> (whose size is greater than <code>MB_CUR_MAX</code>)</div> <div class="t-li1"> + the result is returned in the out-parameter <code>retval</code> +</div> <div class="t-li1"> + the following errors are detected at runtime and call the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> <code>retval</code> or <code>ps</code> is a null pointer. </li> +<li> <code>ssz</code> is zero or greater than <code>RSIZE_MAX</code> (unless <code>s</code> is null) </li> +<li> <code>ssz</code> is less than the number of bytes that would be written (unless <code>s</code> is null) </li> +<li> <code>s</code> is a null pointer but <code>ssz</code> is not zero </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>wcrtomb_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../wide" title="c/string/wide"><code><wchar.h></code></a>.</dd> +</dl> +</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> s </td> <td> - </td> <td> pointer to narrow character array where the multibyte character will be stored </td> +</tr> <tr class="t-par"> <td> wc </td> <td> - </td> <td> the wide character to convert </td> +</tr> <tr class="t-par"> <td> ps </td> <td> - </td> <td> pointer to the conversion state object used when interpreting the multibyte string </td> +</tr> <tr class="t-par"> <td> ssz </td> <td> - </td> <td> max number of bytes to write (the size of the buffer <code>s</code>) </td> +</tr> <tr class="t-par"> <td> retval </td> <td> - </td> <td> pointer to an out-parameter where the result (number of bytes in the multibyte string including any shift sequences) will be stored </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> On success, returns the number of bytes (including any shift sequences) written to the character array whose first element is pointed to by <code>s</code>. </div> <div class="t-li1"> + On failure (if <code>wc</code> is not a valid wide character), returns <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">1</span></code>, stores <code><a href="../../error/errno_macros" title="c/error/errno macros">EILSEQ</a></code> in <code><a href="../../error/errno" title="c/error/errno">errno</a></code>, and leaves <code>*ps</code> in unspecified state.</div> <div class="t-li1"> +<span class="t-li">2)</span> Returns zero on success and non-zero on failure, in which case, <code>s[0]</code> is set to <code>'\0'</code> (unless <code>s</code> is null or <code>ssz</code> is zero or greater than <code>RSIZE_MAX</code>) and <code>*retval</code> is set to <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">1</span></code> (unless <code>retval</code> is null)</div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <locale.h> +#include <string.h> +#include <wchar.h> +#include <stdlib.h> + +int main(void) +{ + setlocale(LC_ALL, "en_US.utf8"); + mbstate_t state; + memset(&state, 0, sizeof state); + wchar_t in[] = L"zß水🍌"; // or "z\u00df\u6c34\U0001F34C" + size_t in_sz = sizeof in / sizeof *in; + + printf("Processing %zu wchar_t units: [ ", in_sz); + for(size_t n = 0; n < in_sz; ++n) printf("%#x ", (unsigned int)in[n]); + puts("]"); + + char out[MB_CUR_MAX * in_sz]; + char *p = out; + for(size_t n = 0; n < in_sz; ++n) { + int rc = wcrtomb(p, in[n], &state); + if(rc == -1) break; + p += rc; + } + + size_t out_sz = p - out; + printf("into %zu UTF-8 code units: [ ", out_sz); + for(size_t x = 0; x < out_sz; ++x) printf("%#x ", +(unsigned char)out[x]); + puts("]"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Processing 5 wchar_t units: [ 0x7a 0xdf 0x6c34 0x1f34c 0 ] +into 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0 ]</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.29.6.3.3 The wcrtomb function (p: 444) </li> +<li> K.3.9.3.1.1 The wcrtomb_s function (p: 647-648) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.6.3.3 The wcrtomb function (p: 390) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="wctomb" title="c/string/multibyte/wctomb"> <span class="t-lines"><span>wctomb</span><span>wctomb_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a wide character to its multibyte representation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="mbrtowc" title="c/string/multibyte/mbrtowc"> <span class="t-lines"><span>mbrtowc</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> converts the next multibyte character to wide character, given state <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/multibyte/wcrtomb" title="cpp/string/multibyte/wcrtomb">C++ documentation</a></span> for <code>wcrtomb</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/wcrtomb" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/wcrtomb</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fwcsrtombs.html b/devdocs/c/string%2Fmultibyte%2Fwcsrtombs.html new file mode 100644 index 00000000..fd435f8a --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fwcsrtombs.html @@ -0,0 +1,83 @@ + <h1 id="firstHeading" class="firstHeading">wcsrtombs, wcsrtombs_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td><pre data-language="c">size_t wcsrtombs( char *dst, const wchar_t **src, size_t len, mbstate_t* ps );</pre></td> <td> +<span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> +</td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">size_t wcsrtombs( char *restrict dst, const wchar_t **restrict src, size_t len, + mbstate_t *restrict ps );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t wcsrtombs_s( size_t *restrict retval, char *restrict dst, rsize_t dstsz, + const wchar_t **restrict src, rsize_t len, + mbstate_t *restrict ps );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <span class="t-li">1)</span> Converts a sequence of wide characters from the array whose first element is pointed to by <code>*src</code> to its narrow multibyte representation that begins in the conversion state described by <code>*ps</code>. If <code>dst</code> is not null, converted characters are stored in the successive elements of the char array pointed to by <code>dst</code>. No more than <code>len</code> bytes are written to the destination array. Each character is converted as if by a call to <code><a href="wcrtomb" title="c/string/multibyte/wcrtomb">wcrtomb</a></code>. The conversion stops if: <ul> +<li> The null character <code>L'\0'</code> was converted and stored. The bytes stored in this case are the unshift sequence (if necessary) followed by <code>'\0'</code>, <code>*src</code> is set to null pointer value and <code>*ps</code> represents the initial shift state. </li> +<li> A <code>wchar_t</code> was found that does not correspond to a valid character in the current C locale. <code>*src</code> is set to point at the first unconverted wide character. </li> +<li> the next multibyte character to be stored would exceed <code>len</code>. <code>*src</code> is set to point at the first unconverted wide character. This condition is not checked if <code>dst</code> is a null pointer.</li> +</ul> <span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that <ul> +<li> the function returns its result as an out-parameter <code>retval</code> </li> +<li> if the conversion stops without writing a null character, the function will store <code>'\0'</code> in the next byte in <code>dst</code>, which may be <code>dst[len]</code> or <code>dst[dstsz]</code>, whichever comes first (meaning up to len+1/dstsz+1 total bytes may be written). In this case, there may be no unshift sequence written before the terminating null. </li> +<li> the function clobbers the destination array from the terminating null and until <code>dstsz</code> </li> +<li> If <code>src</code> and <code>dst</code> overlap, the behavior is unspecified. </li> +<li> the following errors are detected at runtime and call the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: </li> +</ul> <dl> +<dd> +<ul> +<li> <code>retval</code>, <code>ps</code>, <code>src</code>, or <code>*src</code> is a null pointer </li> +<li> <code>dstsz</code> or <code>len</code> is greater than <code>RSIZE_MAX</code> (unless <code>dst</code> is null) </li> +<li> <code>dstsz</code> is not zero (unless <code>dst</code> is null) </li> +<li> <code>len</code> is greater than <code>dstsz</code> and the conversion does not encounter null or encoding error in the <code>src</code> array by the time <code>dstsz</code> is reached (unless <code>dst</code> is null) </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>wcsrtombs_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../wide" title="c/string/wide"><code><wchar.h></code></a>.</dd> +</dl> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dst </td> <td> - </td> <td> pointer to narrow character array where the multibyte characters will be stored </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to pointer to the first element of a null-terminated wide string </td> +</tr> <tr class="t-par"> <td> len </td> <td> - </td> <td> number of bytes available in the array pointed to by dst </td> +</tr> <tr class="t-par"> <td> ps </td> <td> - </td> <td> pointer to the conversion state object </td> +</tr> <tr class="t-par"> <td> dstsz </td> <td> - </td> <td> max number of bytes that will be written (size of the <code>dst</code> array) </td> +</tr> <tr class="t-par"> <td> retval </td> <td> - </td> <td> pointer to a <code><a href="../../types/size_t" title="c/types/size t">size_t</a></code> object where the result will be stored </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> On success, returns the number of bytes (including any shift sequences, but excluding the terminating <code>'\0'</code>) written to the character array whose first element is pointed to by <code>dst</code>. If <code>dst</code> is a null pointer, returns the number of bytes that would have been written. On conversion error (if invalid wide character was encountered), returns <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">1</span></code>, stores <code><a href="../../error/errno_macros" title="c/error/errno macros">EILSEQ</a></code> in <code><a href="../../error/errno" title="c/error/errno">errno</a></code>, and leaves <code>*ps</code> in unspecified state.</div> <div class="t-li1"> +<span class="t-li">2)</span> Returns zero on success (in which case the number of bytes excluding terminating zero that were, or would be written to <code>dst</code>, is stored in <code>*retval</code>), non-zero on error. In case of a runtime constraint violation, stores <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">1</span></code> in <code>*retval</code> (unless <code>retval</code> is null) and sets <code>dst[0]</code> to <code>'\0'</code> (unless <code>dst</code> is null or <code>dstmax</code> is zero or greater than <code>RSIZE_MAX</code>)</div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <locale.h> +#include <string.h> +#include <wchar.h> + +void print_wide(const wchar_t* wstr) +{ + mbstate_t state; + memset(&state, 0, sizeof state); + size_t len = 1 + wcsrtombs(NULL, &wstr, 0, &state); + char mbstr[len]; + wcsrtombs(mbstr, &wstr, len, &state); + printf("Multibyte string: %s\n", mbstr); + printf("Length, including '\\0': %zu\n", len); +} + +int main(void) +{ + setlocale(LC_ALL, "en_US.utf8"); + print_wide(L"z\u00df\u6c34\U0001f34c"); // or L"zß水🍌" +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Multibyte string: zß水🍌 +Length, including '\0': 11</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.29.6.4.2 The wcsrtombs function (p: 324-325) </li> +<li> K.3.9.3.2.2 The wcsrtombs_s function (p: 471-472) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.29.6.4.2 The wcsrtombs function (p: 446) </li> +<li> K.3.9.3.2.2 The wcsrtombs_s function (p: 649-651) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.6.4.2 The wcsrtombs function (p: 392) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="wcstombs" title="c/string/multibyte/wcstombs"> <span class="t-lines"><span>wcstombs</span><span>wcstombs_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a wide string to narrow multibyte character string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcrtomb" title="c/string/multibyte/wcrtomb"> <span class="t-lines"><span>wcrtomb</span><span>wcrtomb_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a wide character to its multibyte representation, given state <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="mbsrtowcs" title="c/string/multibyte/mbsrtowcs"> <span class="t-lines"><span>mbsrtowcs</span><span>mbsrtowcs_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a narrow multibyte character string to wide string, given state <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/multibyte/wcsrtombs" title="cpp/string/multibyte/wcsrtombs">C++ documentation</a></span> for <code>wcsrtombs</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/wcsrtombs" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/wcsrtombs</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fwcstombs.html b/devdocs/c/string%2Fmultibyte%2Fwcstombs.html new file mode 100644 index 00000000..ae8b6652 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fwcstombs.html @@ -0,0 +1,104 @@ + <h1 id="firstHeading" class="firstHeading">wcstombs, wcstombs_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">size_t wcstombs( char *dst, const wchar_t *src, size_t len );</pre> +</td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">size_t wcstombs( char *restrict dst, const wchar_t *restrict src, size_t len );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t wcstombs_s( size_t *restrict retval, char *restrict dst, rsize_t dstsz, + const wchar_t *restrict src, rsize_t len );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Converts a sequence of wide characters from the array whose first element is pointed to by <code>src</code> to its narrow multibyte representation that begins in the initial shift state. Converted characters are stored in the successive elements of the char array pointed to by <code>dst</code>. No more than <code>len</code> bytes are written to the destination array.</div> <div class="t-li1"> + Each character is converted as if by a call to <code><a href="wctomb" title="c/string/multibyte/wctomb">wctomb</a></code>, except that the wctomb's conversion state is unaffected. The conversion stops if:</div> <div class="t-li1"> + * The null character <code>L'\0'</code> was converted and stored. The bytes stored in this case are the unshift sequence (if necessary) followed by <code>'\0'</code>,</div> <div class="t-li1"> + * A <code>wchar_t</code> was found that does not correspond to a valid character in the current C locale.</div> <div class="t-li1"> + * The next multibyte character to be stored would exceed <code>len</code>.</div> <div class="t-li1"> + If <code>src</code> and <code>dst</code> overlap, the behavior is unspecified.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that</div> <div class="t-li1"> + * conversion is as-if by <code><a href="wcrtomb" title="c/string/multibyte/wcrtomb">wcrtomb</a></code>, not <code><a href="wctomb" title="c/string/multibyte/wctomb">wctomb</a></code> +</div> <div class="t-li1"> + * the function returns its result as an out-parameter <code>retval</code> +</div> <div class="t-li1"> + * if the conversion stops without writing a null character, the function will store <code>'\0'</code> in the next byte in <code>dst</code>, which may be <code>dst[len]</code> or <code>dst[dstsz]</code>, whichever comes first (meaning up to len+1/dstsz+1 total bytes may be written). In this case, there may be no unshift sequence written before the terminating null.</div> <div class="t-li1"> + * if <code>dst</code> is a null pointer, the number of bytes that would be produced is stored in <code>*retval</code> +</div> <div class="t-li1"> + * the function clobbers the destination array from the terminating null and until <code>dstsz</code> +</div> <div class="t-li1"> + * If <code>src</code> and <code>dst</code> overlap, the behavior is unspecified.</div> <div class="t-li1"> + * the following errors are detected at runtime and call the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> <code>retval</code> or <code>src</code> is a null pointer </li> +<li> <code>dstsz</code> or <code>len</code> is greater than <code>RSIZE_MAX</code> (unless <code>dst</code> is null) </li> +<li> <code>dstsz</code> is not zero (unless <code>dst</code> is null) </li> +<li> <code>len</code> is greater than <code>dstsz</code> and the conversion does not encounter null or encoding error in the <code>src</code> array by the time <code>dstsz</code> is reached (unless <code>dst</code> is null) </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>wcstombs_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../../program" title="c/program"><code><stdlib.h></code></a>.</dd> +</dl> +</div> <h3 id="Notes"> Notes</h3> <p>In most implementations, <code>wcstombs</code> updates a global static object of type <code><a href="mbstate_t" title="c/string/multibyte/mbstate t">mbstate_t</a></code> as it processes through the string, and cannot be called simultaneously by two threads, <code><a href="wcsrtombs" title="c/string/multibyte/wcsrtombs">wcsrtombs</a></code> or <code>wcstombs_s</code> should be used in such cases.</p> +<p>POSIX specifies a common extension: if <code>dst</code> is a null pointer, this function returns the number of bytes that would be written to <code>dst</code>, if converted. Similar behavior is standard for <code><a href="wcsrtombs" title="c/string/multibyte/wcsrtombs">wcsrtombs</a></code> and <code>wcstombs_s</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dst </td> <td> - </td> <td> pointer to narrow character array where the multibyte character will be stored </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the first element of a null-terminated wide string to convert </td> +</tr> <tr class="t-par"> <td> len </td> <td> - </td> <td> number of bytes available in the array pointed to by dst </td> +</tr> <tr class="t-par"> <td> dstsz </td> <td> - </td> <td> max number of bytes that will be written (size of the <code>dst</code> array) </td> +</tr> <tr class="t-par"> <td> retval </td> <td> - </td> <td> pointer to a size_t object where the result will be stored </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> On success, returns the number of bytes (including any shift sequences, but excluding the terminating <code>'\0'</code>) written to the character array whose first element is pointed to by <code>dst</code>. On conversion error (if invalid wide character was encountered), returns <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">1</span></code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Returns zero on success (in which case the number of bytes excluding terminating zero that were, or would be written to <code>dst</code>, is stored in <code>*retval</code>), non-zero on error. In case of a runtime constraint violation, stores <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">1</span></code> in <code>*retval</code> (unless <code>retval</code> is null) and sets <code>dst[0]</code> to <code>'\0'</code> (unless <code>dst</code> is null or <code>dstmax</code> is zero or greater than <code>RSIZE_MAX</code>)</div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> +#include <locale.h> + +int main(void) +{ + // 4 wide characters + const wchar_t src[] = L"z\u00df\u6c34\U0001f34c"; + // they occupy 10 bytes in UTF-8 + char dst[11]; + + setlocale(LC_ALL, "en_US.utf8"); + printf("wide-character string: '%ls'\n",src); + for (size_t ndx=0; ndx < sizeof src/sizeof src[0]; ++ndx) + printf(" src[%2zu] = %#8x\n", ndx, src[ndx]); + + int rtn_val = wcstombs(dst, src, sizeof dst); + printf("rtn_val = %d\n", rtn_val); + if (rtn_val > 0) + printf("multibyte string: '%s'\n",dst); + for (size_t ndx=0; ndx<sizeof dst; ++ndx) + printf(" dst[%2zu] = %#2x\n", ndx, (unsigned char)dst[ndx]); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">wide-character string: 'zß水🍌' + src[ 0] = 0x7a + src[ 1] = 0xdf + src[ 2] = 0x6c34 + src[ 3] = 0x1f34c + src[ 4] = 0 +rtn_val = 10 +multibyte string: 'zß水🍌' + dst[ 0] = 0x7a + dst[ 1] = 0xc3 + dst[ 2] = 0x9f + dst[ 3] = 0xe6 + dst[ 4] = 0xb0 + dst[ 5] = 0xb4 + dst[ 6] = 0xf0 + dst[ 7] = 0x9f + dst[ 8] = 0x8d + dst[ 9] = 0x8c + dst[10] = 0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.22.8.2 The wcstombs function (p: 360) </li> +<li> K.3.6.5.2 The wcstombs_s function (p: 612-614) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.8.2 The wcstombs function (p: 324) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.8.2 The wcstombs function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="wcsrtombs" title="c/string/multibyte/wcsrtombs"> <span class="t-lines"><span>wcsrtombs</span><span>wcsrtombs_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a wide string to narrow multibyte character string, given state <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="mbstowcs" title="c/string/multibyte/mbstowcs"> <span class="t-lines"><span>mbstowcs</span><span>mbstowcs_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a narrow multibyte character string to wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/multibyte/wcstombs" title="cpp/string/multibyte/wcstombs">C++ documentation</a></span> for <code>wcstombs</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/wcstombs" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/wcstombs</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fwctob.html b/devdocs/c/string%2Fmultibyte%2Fwctob.html new file mode 100644 index 00000000..c942d365 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fwctob.html @@ -0,0 +1,54 @@ + <h1 id="firstHeading" class="firstHeading">wctob</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int wctob( wint_t c );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Narrows a wide character <code>c</code> if its multibyte character equivalent in the initial shift state is a single byte.</p> +<p>This is typically possible for the characters from the ASCII character set, since most multibyte encodings (such as UTF-8) use single bytes to encode those characters.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> c </td> <td> - </td> <td> wide character to narrow </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code><a href="../../io" title="c/io">EOF</a></code> if <code>c</code> does not represent a multibyte character with length <code>1</code> in initial shift state.</p> +<p>otherwise, the single-byte representation of <code>c</code> as <code>unsigned char</code> converted to <code>int</code></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <wchar.h> +#include <stdio.h> +#include <assert.h> + +void try_narrowing(wchar_t c) +{ + int cn = wctob(c); + if(cn != EOF) + printf("%#x narrowed to %#x\n", c, cn); + else + printf("%#x could not be narrowed\n", c); +} + +int main(void) +{ + char* utf_locale_present = setlocale(LC_ALL, "th_TH.utf8"); + assert(utf_locale_present); + puts("In Thai UTF-8 locale:"); + try_narrowing(L'a'); + try_narrowing(L'๛'); + + char* tis_locale_present = setlocale(LC_ALL, "th_TH.tis620"); + assert(tis_locale_present); + puts("In Thai TIS-620 locale:"); + try_narrowing(L'a'); + try_narrowing(L'๛'); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">In Thai UTF-8 locale: +0x61 narrowed to 0x61 +0xe5b could not be narrowed +In Thai TIS-620 locale: +0x61 narrowed to 0x61 +0xe5b narrowed to 0xfb</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.6.1.2 The wctob function (p: 441) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.6.1.2 The wctob function (p: 387) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="btowc" title="c/string/multibyte/btowc"> <span class="t-lines"><span>btowc</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> widens a single-byte narrow character to wide character, if possible <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/multibyte/wctob" title="cpp/string/multibyte/wctob">C++ documentation</a></span> for <code>wctob</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/wctob" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/wctob</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte%2Fwctomb.html b/devdocs/c/string%2Fmultibyte%2Fwctomb.html new file mode 100644 index 00000000..0c17d262 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte%2Fwctomb.html @@ -0,0 +1,82 @@ + <h1 id="firstHeading" class="firstHeading">wctomb, wctomb_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int wctomb( char *s, wchar_t wc );</pre> +</td> <td> (1) </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t wctomb_s( int *restrict status, char *restrict s, rsize_t ssz, wchar_t wc );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Converts a wide character <code>wc</code> to multibyte encoding and stores it (including any shift sequences) in the char array whose first element is pointed to by <code>s</code>. No more than <code>MB_CUR_MAX</code> characters are stored. The conversion is affected by the current locale's LC_CTYPE category. </div> <div class="t-li1"> + If <code>wc</code> is the null character, the null byte is written to <code>s</code>, preceded by any shift sequences necessary to restore the initial shift state.</div> <div class="t-li1"> + If <code>s</code> is a null pointer, this function resets the global conversion state and determines whether shift sequences are used.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that the result is returned in the out-parameter <code>status</code> and the following errors are detected at runtime and call the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> <code>ssz</code> is less than the number of bytes that would be written (unless <code>s</code> is null) </li> +<li> <code>ssz</code> is greater than <code>RSIZE_MAX</code> (unless <code>s</code> is null) </li> +<li> <code>s</code> is a null pointer but <code>ssz</code> is not zero </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>wctomb_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../../program" title="c/program"><code><stdlib.h></code></a>.</dd> +</dl> +</div> <h3 id="Notes"> Notes</h3> <p>Each call to <code>wctomb</code> updates the internal global conversion state (a static object of type <code><a href="mbstate_t" title="c/string/multibyte/mbstate t">mbstate_t</a></code>, known only to this function). If the multibyte encoding uses shift states, this function is not reentrant. In any case, multiple threads should not call <code>wctomb</code> without synchronization: <code><a href="wcrtomb" title="c/string/multibyte/wcrtomb">wcrtomb</a></code> or <code>wctomb_s</code> may be used instead.</p> +<p>Unlike most bounds-checked functions, <code>wctomb_s</code> does not null-terminate its output, because it is designed to be used in loops that process strings character-by-character.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> s </td> <td> - </td> <td> pointer to the character array for output </td> +</tr> <tr class="t-par"> <td> wc </td> <td> - </td> <td> wide character to convert </td> +</tr> <tr class="t-par"> <td> ssz </td> <td> - </td> <td> maximum number of bytes to write to <code>s</code> (size of the array <code>s</code>) </td> +</tr> <tr class="t-par"> <td> status </td> <td> - </td> <td> pointer to an out-parameter where the result (length of the multibyte sequence or the shift sequence status) will be stored </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> If <code>s</code> is not a null pointer, returns the number of bytes that are contained in the multibyte representation of <code>wc</code> or <code>-1</code> if <code>wc</code> is not a valid character.</div> <div class="t-li1"> + If <code>s</code> is a null pointer, resets its internal conversion state to represent the initial shift state and returns <code>0</code> if the current multibyte encoding is not state-dependent (does not use shift sequences) or a non-zero value if the current multibyte encoding is state-dependent (uses shift sequences).</div> <div class="t-li1"> +<span class="t-li">2)</span> zero on success, in which case the multibyte representation of <code>wc</code> is stored in <code>s</code> and its length is stored in <code>*status</code>, or, if <code>s</code> is null, the shift sequence status is stored in <code>status</code>). Non-zero on encoding error or runtime constraint violation, in which case <code><span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a><span class="br0">)</span><span class="sy2">-</span><span class="nu0">1</span></code> is stored in <code>*status</code>. The value stored in <code>*status</code> never exceeds <code>MB_CUR_MAX</code> +</div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> +#include <locale.h> + +void demo(wchar_t wc) +{ + const char* dep = wctomb(NULL, wc) ? "Yes" : "No"; + printf("State-dependent encoding? %s.\n", dep); + + char mb[MB_CUR_MAX]; + int len = wctomb(mb, wc); + printf("wide char '%lc' -> multibyte char [", wc); + for (int idx = 0; idx < len; ++idx) + printf("%s%#2x", idx ? " " : "", (unsigned char)mb[idx]); + printf("]\n"); +} + +int main(void) +{ + setlocale(LC_ALL, "en_US.utf8"); + printf("MB_CUR_MAX = %zu\n", MB_CUR_MAX); + demo(L'A'); + demo(L'\u00df'); + demo(L'\U0001d10b'); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">MB_CUR_MAX = 6 +State-dependent encoding? No. +wide char 'A' -> multibyte char [0x41] +State-dependent encoding? No. +wide char 'ß' -> multibyte char [0xc3 0x9f] +State-dependent encoding? No. +wide char '𝄋' -> multibyte char [0xf0 0x9d 0x84 0x8b]</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.22.7.3 The wctomb function (p: 261) </li> +<li> K.3.6.4.1 The wctomb_s function (p: 443) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.22.7.3 The wctomb function (p: 358-359) </li> +<li> K.3.6.4.1 The wctomb_s function (p: 610-611) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.20.7.3 The wctomb function (p: 322-323) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.10.7.3 The wctomb function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="mbtowc" title="c/string/multibyte/mbtowc"> <span class="t-lines"><span>mbtowc</span></span></a></div> </td> <td> converts the next multibyte character to wide character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcrtomb" title="c/string/multibyte/wcrtomb"> <span class="t-lines"><span>wcrtomb</span><span>wcrtomb_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a wide character to its multibyte representation, given state <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/multibyte/wctomb" title="cpp/string/multibyte/wctomb">C++ documentation</a></span> for <code>wctomb</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte/wctomb" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte/wctomb</a> + </p> +</div> diff --git a/devdocs/c/string%2Fmultibyte.html b/devdocs/c/string%2Fmultibyte.html new file mode 100644 index 00000000..554581e6 --- /dev/null +++ b/devdocs/c/string%2Fmultibyte.html @@ -0,0 +1,90 @@ + <h1 id="firstHeading" class="firstHeading">Null-terminated multibyte strings</h1> <p>A null-terminated multibyte string (NTMBS), or "multibyte string", is a sequence of nonzero bytes followed by a byte with value zero (the terminating null character).</p> +<p>Each character stored in the string may occupy more than one byte. The encoding used to represent characters in a multibyte character string is locale-specific: it may be UTF-8, GB18030, EUC-JP, Shift-JIS, etc. For example, the char array <code>{'\xe4','\xbd','\xa0','\xe5','\xa5','\xbd','\0'</code>} is an NTMBS holding the string <code>"你好"</code> in UTF-8 multibyte encoding: the first three bytes encode the character 你, the next three bytes encode the character 好. The same string encoded in GB18030 is the char array <code>{'\xc4', '\xe3', '\xba', '\xc3', '\0'</code>}, where each of the two characters is encoded as a two-byte sequence.</p> +<p>In some multibyte encodings, any given multibyte character sequence may represent different characters depending on the previous byte sequences, known as "shift sequences". Such encodings are known as state-dependent: knowledge of the current shift state is required to interpret each character. An NTMBS is only valid if it begins and ends in the initial shift state: if a shift sequence was used, the corresponding unshift sequence has to be present before the terminating null character. Examples of such encodings are BOCU-1 and <a rel="nofollow" class="external text" href="http://www.unicode.org/reports/tr6">SCSU</a>.</p> +<p>A multibyte character string is layout-compatible with <a href="byte" title="c/string/byte">null-terminated byte string</a> (NTBS), that is, can be stored, copied, and examined using the same facilities, except for calculating the number of characters. If the correct locale is in effect, I/O functions also handle multibyte strings. Multibyte strings can be converted to and from wide strings using the following locale-dependent conversion functions:</p> +<h3 id="Multibyte.2Fwide_character_conversions"> Multibyte/wide character conversions</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdlib.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/mblen" title="c/string/multibyte/mblen"> <span class="t-lines"><span>mblen</span></span></a></div> </td> <td> returns the number of bytes in the next multibyte character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/mbtowc" title="c/string/multibyte/mbtowc"> <span class="t-lines"><span>mbtowc</span></span></a></div> </td> <td> converts the next multibyte character to wide character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/wctomb" title="c/string/multibyte/wctomb"> <span class="t-lines"><span>wctomb</span><span>wctomb_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a wide character to its multibyte representation <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/mbstowcs" title="c/string/multibyte/mbstowcs"> <span class="t-lines"><span>mbstowcs</span><span>mbstowcs_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a narrow multibyte character string to wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/wcstombs" title="c/string/multibyte/wcstombs"> <span class="t-lines"><span>wcstombs</span><span>wcstombs_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a wide string to narrow multibyte character string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><wchar.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/mbsinit" title="c/string/multibyte/mbsinit"> <span class="t-lines"><span>mbsinit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if the mbstate_t object represents initial shift state <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/btowc" title="c/string/multibyte/btowc"> <span class="t-lines"><span>btowc</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> widens a single-byte narrow character to wide character, if possible <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/wctob" title="c/string/multibyte/wctob"> <span class="t-lines"><span>wctob</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> narrows a wide character to a single-byte narrow character, if possible <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/mbrlen" title="c/string/multibyte/mbrlen"> <span class="t-lines"><span>mbrlen</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> returns the number of bytes in the next multibyte character, given state <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/mbrtowc" title="c/string/multibyte/mbrtowc"> <span class="t-lines"><span>mbrtowc</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> converts the next multibyte character to wide character, given state <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/wcrtomb" title="c/string/multibyte/wcrtomb"> <span class="t-lines"><span>wcrtomb</span><span>wcrtomb_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a wide character to its multibyte representation, given state <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/mbsrtowcs" title="c/string/multibyte/mbsrtowcs"> <span class="t-lines"><span>mbsrtowcs</span><span>mbsrtowcs_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a narrow multibyte character string to wide string, given state <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/wcsrtombs" title="c/string/multibyte/wcsrtombs"> <span class="t-lines"><span>wcsrtombs</span><span>wcsrtombs_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a wide string to narrow multibyte character string, given state <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><uchar.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/mbrtoc8" title="c/string/multibyte/mbrtoc8"> <span class="t-lines"><span>mbrtoc8</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> converts a narrow multibyte character to UTF-8 encoding <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/c8rtomb" title="c/string/multibyte/c8rtomb"> <span class="t-lines"><span>c8rtomb</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> converts UTF-8 string to narrow multibyte encoding <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/mbrtoc16" title="c/string/multibyte/mbrtoc16"> <span class="t-lines"><span>mbrtoc16</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> generates the next 16-bit wide character from a narrow multibyte string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/c16rtomb" title="c/string/multibyte/c16rtomb"> <span class="t-lines"><span>c16rtomb</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a 16-bit wide character to narrow multibyte string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/mbrtoc32" title="c/string/multibyte/mbrtoc32"> <span class="t-lines"><span>mbrtoc32</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> generates the next 32-bit wide character from a narrow multibyte string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/c32rtomb" title="c/string/multibyte/c32rtomb"> <span class="t-lines"><span>c32rtomb</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> converts a 32-bit wide character to narrow multibyte string <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <h3 id="Types"> Types</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><wchar.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/mbstate_t" title="c/string/multibyte/mbstate t"> <span class="t-lines"><span>mbstate_t</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> conversion state information necessary to iterate multibyte character strings <br> <span class="t-mark">(class)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><uchar.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/char8_t" title="c/string/multibyte/char8 t"> <span class="t-lines"><span>char8_t</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> UTF-8 character type, an alias for <code>unsigned char</code> <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/char16_t" title="c/string/multibyte/char16 t"> <span class="t-lines"><span>char16_t</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> 16-bit wide character type <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="multibyte/char32_t" title="c/string/multibyte/char32 t"> <span class="t-lines"><span>char32_t</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> 32-bit wide character type <br> <span class="t-mark">(typedef)</span> </td> +</tr> </table> <h3 id="Macros"> Macros</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><limits.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>MB_LEN_MAX</span></span></div> </td> <td> maximum number of bytes in a multibyte character, for any supported locale <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdlib.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>MB_CUR_MAX</span></span></div> </td> <td> maximum number of bytes in a multibyte character, in the current locale<br><span class="t-mark">(macro variable)</span> </td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.10 Sizes of integer types <limits.h> (p: 222) </li> +<li> 7.22 General utilities <stdlib.h> (p: 340-360) </li> +<li> 7.28 Unicode utilities <uchar.h> (p: 398-401) </li> +<li> 7.29 Extended multibyte and wide character utilities <wchar.h> (p: 402-446) </li> +<li> 7.31.12 General utilities <stdlib.h> (p: 456) </li> +<li> 7.31.16 Extended multibyte and wide character utilities <wchar.h> (p: 456) </li> +<li> K.3.6 General utilities <stdlib.h> (p: 604-614) </li> +<li> K.3.9 Extended multibyte and wide character utilities <wchar.h> (p: 627-651) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.10 Sizes of integer types <limits.h> (p: 203) </li> +<li> 7.20 General utilities <stdlib.h> (p: 306-324) </li> +<li> 7.24 Extended multibyte and wide character utilities <wchar.h> (p: 348-392) </li> +<li> 7.26.10 General utilities <stdlib.h> (p: 402) </li> +<li> 7.26.12 Extended multibyte and wide character utilities <wchar.h> (p: 402) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul> +<li> 4.1.4 Limits <float.h> and <limits.h> </li> +<li> 4.10 GENERAL UTILITIES <stdlib.h> </li> +<li> 4.13.7 General utilities <stdlib.h> </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/multibyte" title="cpp/string/multibyte">C++ documentation</a></span> for <code>Null-terminated multibyte strings</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/multibyte" class="_attribution-link">https://en.cppreference.com/w/c/string/multibyte</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fiswalnum.html b/devdocs/c/string%2Fwide%2Fiswalnum.html new file mode 100644 index 00000000..26a33e71 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswalnum.html @@ -0,0 +1,116 @@ + <h1 id="firstHeading" class="firstHeading">iswalnum</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int iswalnum( wint_t ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Checks if the given wide character is an alphanumeric character, i.e. either a number (<span class="nu19">0123456789</span>), an uppercase letter (<code>ABCDEFGHIJKLMNOPQRSTUVWXYZ</code>), a lowercase letter (<code>abcdefghijklmnopqrstuvwxyz</code>) or any alphanumeric character specific to the current locale.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> wide character </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the wide character is an alphanumeric character, zero otherwise.</p> +<h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="https://www.open-std.org/JTC1/SC35/WG5/docs/30112d10.pdf">ISO 30112</a> specifies which Unicode characters are include in POSIX alnum category.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <locale.h> +#include <wchar.h> +#include <wctype.h> + +int main(void) +{ + wchar_t c = L'\u13ad'; // the Cherokee letter HA ('Ꭽ') + printf("in the default locale, iswalnum(%#x) = %d\n", c, !!iswalnum(c)); + setlocale(LC_ALL, "en_US.utf8"); + printf("in Unicode locale, iswalnum(%#x) = %d\n", c, !!iswalnum(c)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">in the default locale, iswalnum(0x13ad) = 0 +in Unicode locale, iswalnum(0x13ad) = 1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> TBD The iswalnum function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.30.2.1.1 The iswalnum function (p: 327) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.30.2.1.1 The iswalnum function (p: 448) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.25.2.1.1 The iswalnum function (p: 394) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/isalnum" title="c/string/byte/isalnum"> <span class="t-lines"><span>isalnum</span></span></a></div> </td> <td> checks if a character is alphanumeric <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/iswalnum" title="cpp/string/wide/iswalnum">C++ documentation</a></span> for <code>iswalnum</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="../byte/iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <strong class="selflink"><code>iswalnum</code></strong></p> +</th> <th rowspan="2"> <p><a href="../byte/isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/iswalnum" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/iswalnum</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fiswalpha.html b/devdocs/c/string%2Fwide%2Fiswalpha.html new file mode 100644 index 00000000..6bf6e2f0 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswalpha.html @@ -0,0 +1,116 @@ + <h1 id="firstHeading" class="firstHeading">iswalpha</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int iswalpha( wint_t ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Checks if the given wide character is an alphabetic character, i.e. either an uppercase letter (<code>ABCDEFGHIJKLMNOPQRSTUVWXYZ</code>), a lowercase letter (<code>abcdefghijklmnopqrstuvwxyz</code>) or any alphabetic character specific to the current locale.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> wide character </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the wide character is an alphabetic character, zero otherwise.</p> +<h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="https://www.open-std.org/JTC1/SC35/WG5/docs/30112d10.pdf">ISO 30112</a> specifies which Unicode characters are include in POSIX alpha category.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <wchar.h> +#include <wctype.h> + +int main(void) +{ + wchar_t c = L'\u0b83'; // Tamil sign Visarga ('ஃ') + printf("in the default locale, iswalpha(%#x) = %d\n", c, !!iswalpha(c)); + setlocale(LC_ALL, "en_US.utf8"); + printf("in Unicode locale, iswalpha(%#x) = %d\n", c, !!iswalpha(c)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">in the default locale, iswalpha(0xb83) = 0 +in Unicode locale, iswalpha(0xb83) = 1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> TBD The iswalpha function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.30.2.1.2 The iswalpha function (p: 327) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.30.2.1.2 The iswalpha function (p: 448-449) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.25.2.1.2 The iswalpha function (p: 394-395) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/isalpha" title="c/string/byte/isalpha"> <span class="t-lines"><span>isalpha</span></span></a></div> </td> <td> checks if a character is alphabetic <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/iswalpha" title="cpp/string/wide/iswalpha">C++ documentation</a></span> for <code>iswalpha</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="../byte/iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <strong class="selflink"><code>iswalpha</code></strong></p> +</th> <th rowspan="2"> <p><a href="../byte/isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/iswalpha" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/iswalpha</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fiswblank.html b/devdocs/c/string%2Fwide%2Fiswblank.html new file mode 100644 index 00000000..a1531a59 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswblank.html @@ -0,0 +1,117 @@ + <h1 id="firstHeading" class="firstHeading">iswblank</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">int iswblank( wint_t ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Checks if the given wide character is classified as blank character (that is, a whitespace character used to separate words in a sentence) by the current C locale. In the default C locale, only space (<code>0x20</code>) and horizontal tab (<code>0x09</code>) are blank characters.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> wide character </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the wide character is a blank character, zero otherwise.</p> +<h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="https://www.open-std.org/JTC1/SC35/WG5/docs/30112d10.pdf">ISO 30112</a> defines POSIX blank characters as Unicode characters U+0009, U+0020, U+1680, U+180E, U+2000..U+2006, U+2008, U+200A, U+205F, and U+3000.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <wchar.h> +#include <wctype.h> + +int main(void) +{ + wchar_t c = L'\u3000'; // Ideographic space (' ') + printf("In the default locale, iswblank(%#x) = %d\n", c, !!iswblank(c)); + setlocale(LC_ALL, "en_US.utf8"); + printf("In Unicode locale, iswblank(%#x) = %d\n", c, !!iswblank(c)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">In the default locale, iswblank(0x3000) = 0 +In Unicode locale, iswblank(0x3000) = 1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.30.2.1.3 The iswblank function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.30.2.1.3 The iswblank function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.30.2.1.3 The iswblank function (p: 449) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.25.2.1.3 The iswblank function (p: 395) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/isblank" title="c/string/byte/isblank"> <span class="t-lines"><span>isblank</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if a character is a blank character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/iswblank" title="cpp/string/wide/iswblank">C++ documentation</a></span> for <code>iswblank</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="../byte/iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <strong class="selflink"><code>iswblank</code></strong></p> +</th> <th rowspan="2"> <p><a href="../byte/isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/iswblank" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/iswblank</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fiswcntrl.html b/devdocs/c/string%2Fwide%2Fiswcntrl.html new file mode 100644 index 00000000..0b94ae30 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswcntrl.html @@ -0,0 +1,116 @@ + <h1 id="firstHeading" class="firstHeading">iswcntrl</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int iswcntrl( wint_t ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Checks if the given wide character is a control character, i.e. codes <code>0x00-0x1F</code> and <code>0x7F</code> and any control characters specific to the current locale.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> wide character </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the wide character is a control character, zero otherwise.</p> +<h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="https://www.open-std.org/JTC1/SC35/WG5/docs/30112d10.pdf">ISO 30112</a> defines POSIX control characters as Unicode characters U+0000..U+001F, U+007F..U+009F, U+2028, and U+2029 (Unicode classes Cc, Zl, and Zp)</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <wchar.h> +#include <wctype.h> + +int main(void) +{ + wchar_t c = L'\u2028'; // the Unicode character "line separator" + printf("In the default locale, iswcntrl(%#x) = %d\n", c, !!iswcntrl(c)); + setlocale(LC_ALL, "en_US.utf8"); + printf("In Unicode locale, iswcntrl(%#x) = %d\n", c, !!iswcntrl(c)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">In the default locale, iswcntrl(0x2028) = 0 +In Unicode locale, iswcntrl(0x2028) = 1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.30.2.1.4 The iswcntrl function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.30.2.1.4 The iswcntrl function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.30.2.1.4 The iswcntrl function (p: 449) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.25.2.1.4 The iswcntrl function (p: 395) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/iscntrl" title="c/string/byte/iscntrl"> <span class="t-lines"><span>iscntrl</span></span></a></div> </td> <td> checks if a character is a control character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/iswcntrl" title="cpp/string/wide/iswcntrl">C++ documentation</a></span> for <code>iswcntrl</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="../byte/iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <strong class="selflink"><code>iswcntrl</code></strong></p> +</th> <th rowspan="2"> <p><a href="../byte/isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/iswcntrl" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/iswcntrl</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fiswctype.html b/devdocs/c/string%2Fwide%2Fiswctype.html new file mode 100644 index 00000000..36141d09 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswctype.html @@ -0,0 +1,46 @@ + <h1 id="firstHeading" class="firstHeading">iswctype</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int iswctype( wint_t wc, wctype_t desc );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Classifies the wide character <code>wc</code> using the current C locale's <code><a href="../../locale/lc_categories" title="c/locale/LC categories">LC_CTYPE</a></code> category identified by <code>desc</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> wc </td> <td> - </td> <td> the wide character to classify </td> +</tr> <tr class="t-par"> <td> desc </td> <td> - </td> <td> the <code><a href="../../locale/lc_categories" title="c/locale/LC categories">LC_CTYPE</a></code> category, obtained from a call to <code><a href="wctype" title="c/string/wide/wctype">wctype</a></code> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero if the character <code>wc</code> has the property identified by <code>desc</code> in <code><a href="../../locale/lc_categories" title="c/locale/LC categories">LC_CTYPE</a></code> facet of the current C locale, zero otherwise.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <wchar.h> +#include <wctype.h> + +const char* classify(wchar_t wc, const char* cat) +{ + return iswctype(wc, wctype(cat)) ? "true" : "false"; +} + +int main(void) +{ + setlocale(LC_ALL, "ja_JP.UTF-8"); + puts("The character \u6c34 is..."); + const char* cats[] = {"digit", "alpha", "space", "cntrl", "jkanji"}; + for (int n = 0; n < 5; ++n) + printf("%s?\t%s\n", cats[n], classify(L'\u6c34', cats[n])); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">The character 水 is... +digit? false +alpha? true +space? false +cntrl? false +jkanji? true</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.30.2.2.1 The iswctype function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.30.2.2.1 The iswctype function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.30.2.2.1 The iswctype function (p: 451-452) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.25.2.2.1 The iswctype function (p: 397-398) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="wctype" title="c/string/wide/wctype"> <span class="t-lines"><span>wctype</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> looks up a character classification category in the current C locale <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/iswctype" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/iswctype</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fiswdigit.html b/devdocs/c/string%2Fwide%2Fiswdigit.html new file mode 100644 index 00000000..f65568b9 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswdigit.html @@ -0,0 +1,145 @@ + <h1 id="firstHeading" class="firstHeading">iswdigit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int iswdigit( wint_t ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Checks if the given wide character corresponds (if narrowed) to one of the ten decimal digit characters <span class="nu19">0123456789</span>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> wide character </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the wide character is a numeric character, zero otherwise.</p> +<h3 id="Notes"> Notes</h3> <p><code>iswdigit</code> and <code><a href="iswxdigit" title="c/string/wide/iswxdigit">iswxdigit</a></code> are the only standard wide character classification functions that are not affected by the currently installed C locale.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>Some locales offer additional character classes that detect non-ASCII digits</p> +<div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <wchar.h> +#include <wctype.h> + +void test(wchar_t a3, wchar_t u3, wchar_t j3) +{ + printf("\t '%lc' '%lc' '%lc'\n", a3, u3, j3); + printf("iswdigit: %d %d %d\n", + !!iswdigit(a3), + !!iswdigit(u3), + !!iswdigit(j3)); + printf("jdigit: %d %d %d\n", + !!iswctype(a3, wctype("jdigit")), + !!iswctype(u3, wctype("jdigit")), + !!iswctype(j3, wctype("jdigit"))); +} + +int main(void) +{ + wchar_t a3 = L'3'; // the ASCII digit 3 + wchar_t u3 = L'三'; // the CJK numeral 3 + wchar_t j3 = L'３'; // the full-width digit 3 + + setlocale(LC_ALL, "en_US.utf8"); + puts("In American locale:"); + test(a3, u3, j3); + + setlocale(LC_ALL, "ja_JP.utf8"); + puts("\nIn Japanese locale:"); + test(a3, u3, j3); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">In American locale: + '3' '三' '３' +iswdigit: 1 0 0 +jdigit: 0 0 0 + +In Japanese locale: + '3' '三' '３' +iswdigit: 1 0 0 +jdigit: 0 0 1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> TBD 7.30.2.1.5 The iswdigit function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.30.2.1.5 The iswdigit function (p: 327) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.30.2.1.5 The iswdigit function (p: 449) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.25.2.1.5 The iswdigit function (p: 395) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/isdigit" title="c/string/byte/isdigit"> <span class="t-lines"><span>isdigit</span></span></a></div> </td> <td> checks if a character is a digit <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/iswdigit" title="cpp/string/wide/iswdigit">C++ documentation</a></span> for <code>iswdigit</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="../byte/iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <strong class="selflink"><code>iswdigit</code></strong></p> +</th> <th rowspan="2"> <p><a href="../byte/isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/iswdigit" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/iswdigit</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fiswgraph.html b/devdocs/c/string%2Fwide%2Fiswgraph.html new file mode 100644 index 00000000..993fade3 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswgraph.html @@ -0,0 +1,116 @@ + <h1 id="firstHeading" class="firstHeading">iswgraph</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int iswgraph( wint_t ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Checks if the given wide character has a graphical representation, i.e. it is either a number (<code>0123456789</code>), an uppercase letter (<code>ABCDEFGHIJKLMNOPQRSTUVWXYZ</code>), a lowercase letter (<code>abcdefghijklmnopqrstuvwxyz</code>), a punctuation character (<code>!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~</code>) or any graphical character specific to the current C locale.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> wide character </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the wide character has a graphical representation character, zero otherwise.</p> +<h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="https://www.open-std.org/JTC1/SC35/WG5/docs/30112d10.pdf">ISO 30112</a> specifies which Unicode characters are include in POSIX graph category.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <wchar.h> +#include <wctype.h> + +int main(void) +{ + wchar_t c = L'\u2602'; // the Unicode character Umbrella ('☂') + printf("in the default locale, iswgraph(%#x) = %d\n", c, !!iswgraph(c)); + setlocale(LC_ALL, "en_US.utf8"); + printf("in Unicode locale, iswgraph(%#x) = %d\n", c, !!iswgraph(c)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">in the default locale, iswgraph(0x2602) = 0 +in Unicode locale, iswgraph(0x2602) = 1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.30.2.1.6 The iswgraph function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.30.2.1.6 The iswgraph function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.30.2.1.6 The iswgraph function (p: 449-450) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.25.2.1.6 The iswgraph function (p: 395-396) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/isgraph" title="c/string/byte/isgraph"> <span class="t-lines"><span>isgraph</span></span></a></div> </td> <td> checks if a character is a graphical character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/iswgraph" title="cpp/string/wide/iswgraph">C++ documentation</a></span> for <code>iswgraph</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="../byte/iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <strong class="selflink"><code>iswgraph</code></strong></p> +</th> <th rowspan="2"> <p><a href="../byte/ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/iswgraph" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/iswgraph</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fiswlower.html b/devdocs/c/string%2Fwide%2Fiswlower.html new file mode 100644 index 00000000..07d7193f --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswlower.html @@ -0,0 +1,116 @@ + <h1 id="firstHeading" class="firstHeading">iswlower</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int iswlower( wint_t ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Checks if the given wide character is a lowercase letter, i.e. one of <code>abcdefghijklmnopqrstuvwxyz</code> or any lowercase letter specific to the current locale.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> wide character </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the wide character is an lowercase letter, zero otherwise.</p> +<h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="https://www.open-std.org/JTC1/SC35/WG5/docs/30112d10.pdf">ISO 30112</a> specifies which Unicode characters are include in POSIX lower category.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <wchar.h> +#include <wctype.h> + +int main(void) +{ + wchar_t c = L'\u0444'; // Cyrillic small letter ef ('ф') + printf("In the default locale, iswlower(%#x) = %d\n", c, !!iswlower(c)); + setlocale(LC_ALL, "en_US.utf8"); + printf("In Unicode locale, iswlower(%#x) = %d\n", c, !!iswlower(c)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">In the default locale, iswlower(0x444) = 0 +In Unicode locale, iswlower(0x444) = 1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.30.2.1.7 The iswlower function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.30.2.1.7 The iswlower function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.30.2.1.7 The iswlower function (p: 450) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.25.2.1.7 The iswlower function (p: 396) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/islower" title="c/string/byte/islower"> <span class="t-lines"><span>islower</span></span></a></div> </td> <td> checks if a character is lowercase <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/iswlower" title="cpp/string/wide/iswlower">C++ documentation</a></span> for <code>iswlower</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="../byte/iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/islower" title="c/string/byte/islower"><code>islower</code></a><br> <strong class="selflink"><code>iswlower</code></strong></p> +</th> <th rowspan="2"> <p><a href="../byte/isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/iswlower" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/iswlower</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fiswprint.html b/devdocs/c/string%2Fwide%2Fiswprint.html new file mode 100644 index 00000000..0fb25886 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswprint.html @@ -0,0 +1,119 @@ + <h1 id="firstHeading" class="firstHeading">iswprint</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c95"> <td> <pre data-language="c">int iswprint( wint_t ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Checks if the given wide character can be printed, i.e. it is either a number (<code>0123456789</code>), an uppercase letter (<code>ABCDEFGHIJKLMNOPQRSTUVWXYZ</code>), a lowercase letter (<code>abcdefghijklmnopqrstuvwxyz</code>), a punctuation character (<code>!"#$%&'()*+,-./:;<=>?@[\]^_`{!}~</code>), space or any printable character specific to the current C locale.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> wide character </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the wide character can be printed, zero otherwise.</p> +<h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="http://www.open-std.org/JTC1/SC35/WG5/docs/30112d10.pdf">ISO 30112</a> specifies which Unicode characters are included in POSIX print category.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <wchar.h> +#include <wctype.h> + +int main(void) +{ + wchar_t c = L'\u2002'; // Unicode character 'EN SPACE' + printf("in the default locale, iswprint(%#x) = %d\n", c, !!iswprint(c)); + setlocale(LC_ALL, "en_US.utf8"); + printf("in Unicode locale, iswprint(%#x) = %d\n", c, !!iswprint(c)); + wchar_t c2 = L'\x82'; // break permitted + printf("in Unicode locale, iswprint(%#x) = %d\n", c2, !!iswprint(c2)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">in the default locale, iswprint(0x2002) = 0 +in Unicode locale, iswprint(0x2002) = 1 +in Unicode locale, iswprint(0x82) = 0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.30.2.1.8 The iswprint function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.30.2.1.8 The iswprint function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.30.2.1.8 The iswprint function (p: 450) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.25.2.1.8 The iswprint function (p: 396) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/isprint" title="c/string/byte/isprint"> <span class="t-lines"><span>isprint</span></span></a></div> </td> <td> checks if a character is a printing character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/iswprint" title="cpp/string/wide/iswprint">C++ documentation</a></span> for <code>iswprint</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="../byte/iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <strong class="selflink"><code>iswprint</code></strong></p> +</th> <th rowspan="2"> <p><a href="../byte/isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/iswprint" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/iswprint</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fiswpunct.html b/devdocs/c/string%2Fwide%2Fiswpunct.html new file mode 100644 index 00000000..8aa2b1d1 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswpunct.html @@ -0,0 +1,116 @@ + <h1 id="firstHeading" class="firstHeading">iswpunct</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int iswpunct( wint_t ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Checks if the given wide character is a punctuation character, i.e. it is one of <code>!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~</code> or any punctuation character specific to the current locale.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> wide character </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the wide character is a punctuation character, zero otherwise.</p> +<h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="https://www.open-std.org/JTC1/SC35/WG5/docs/30112d10.pdf">ISO 30112</a> specifies which Unicode characters are include in POSIX punct category.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <wchar.h> +#include <wctype.h> +#include <locale.h> + +int main(void) +{ + const wchar_t c = L'\u2051'; // Two asterisks ('⁑') + printf("in the default locale, iswpunct(%#x) = %d\n", c, !!iswpunct(c)); + setlocale(LC_ALL, "en_US.utf8"); + printf("in Unicode locale, iswpunct(%#x) = %d\n", c, !!iswpunct(c)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">in the default locale, iswpunct(0x2051) = 0 +in Unicode locale, iswpunct(0x2051) = 1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.30.2.1.9 The iswpunct function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.30.2.1.9 The iswpunct function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.30.2.1.9 The iswpunct function (p: 450) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.25.2.1.9 The iswpunct function (p: 396) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/ispunct" title="c/string/byte/ispunct"> <span class="t-lines"><span>ispunct</span></span></a></div> </td> <td> checks if a character is a punctuation character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/iswpunct" title="cpp/string/wide/iswpunct">C++ documentation</a></span> for <code>iswpunct</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="../byte/iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <strong class="selflink"><code>iswpunct</code></strong></p> +</th> <th rowspan="2"> <p><a href="../byte/isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/iswpunct" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/iswpunct</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fiswspace.html b/devdocs/c/string%2Fwide%2Fiswspace.html new file mode 100644 index 00000000..8b141acc --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswspace.html @@ -0,0 +1,116 @@ + <h1 id="firstHeading" class="firstHeading">iswspace</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int iswspace( wint_t ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Checks if the given wide character is a whitespace character, i.e. either space (<code>0x20</code>), form feed (<code>0x0c</code>), line feed (<code>0x0a</code>), carriage return (<code>0x0d</code>), horizontal tab (<code>0x09</code>), vertical tab (<code>0x0b</code>) or any whitespace character specific to the current locale.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> wide character </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the wide character is a whitespace character, zero otherwise.</p> +<h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="https://www.open-std.org/JTC1/SC35/WG5/docs/30112d10.pdf">ISO 30112</a> defines POSIX space characters as Unicode characters U+0009..U+000D, U+0020, U+1680, U+180E, U+2000..U+2006, U+2008..U+200A, U+2028, U+2029, U+205F, and U+3000.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <wchar.h> +#include <wctype.h> + +int main(void) +{ + wchar_t c = L'\u2003'; // Unicode character 'EM SPACE' + printf("In the default locale, iswspace(%#x) = %d\n", c, !!iswspace(c)); + setlocale(LC_ALL, "en_US.utf8"); + printf("In Unicode locale, iswspace(%#x) = %d\n", c, !!iswspace(c)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">In the default locale, iswspace(0x2003) = 0 +In Unicode locale, iswspace(0x2003) = 1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.30.2.1.10 The iswspace function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.30.2.1.10 The iswspace function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.30.2.1.10 The iswspace function (p: 450-451) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.25.2.1.10 The iswspace function (p: 396-397) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/isspace" title="c/string/byte/isspace"> <span class="t-lines"><span>isspace</span></span></a></div> </td> <td> checks if a character is a space character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/iswspace" title="cpp/string/wide/iswspace">C++ documentation</a></span> for <code>iswspace</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="../byte/iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <strong class="selflink"><code>iswspace</code></strong></p> +</th> <th rowspan="2"> <p><a href="../byte/isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/iswspace" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/iswspace</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fiswupper.html b/devdocs/c/string%2Fwide%2Fiswupper.html new file mode 100644 index 00000000..206895ca --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswupper.html @@ -0,0 +1,116 @@ + <h1 id="firstHeading" class="firstHeading">iswupper</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int iswupper( wint_t ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Checks if the given wide character is an uppercase letter, i.e. one of <code>ABCDEFGHIJKLMNOPQRSTUVWXYZ</code> or any uppercase letter specific to the current locale.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> wide character </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the wide character is an uppercase letter, zero otherwise.</p> +<h3 id="Notes"> Notes</h3> <p><a rel="nofollow" class="external text" href="https://www.open-std.org/JTC1/SC35/WG5/docs/30112d10.pdf">ISO 30112</a> specifies which Unicode characters are include in POSIX upper category.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <wchar.h> +#include <wctype.h> + +int main(void) +{ + wchar_t c = L'\u053d'; // Armenian capital letter xeh ('Խ') + printf("In the default locale, iswupper(%#x) = %d\n", c, !!iswupper(c)); + setlocale(LC_ALL, "en_US.utf8"); + printf("In Unicode locale, iswupper(%#x) = %d\n", c, !!iswupper(c)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">In the default locale, iswupper(0x53d) = 0 +In Unicode locale, iswupper(0x53d) = 1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.30.2.1.11 The iswupper function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.30.2.1.11 The iswupper function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.30.2.1.11 The iswupper function (p: 451) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.25.2.1.11 The iswupper function (p: 397) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/isupper" title="c/string/byte/isupper"> <span class="t-lines"><span>isupper</span></span></a></div> </td> <td> checks if a character is an uppercase character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/iswupper" title="cpp/string/wide/iswupper">C++ documentation</a></span> for <code>iswupper</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="../byte/iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <strong class="selflink"><code>iswupper</code></strong></p> +</th> <th rowspan="2"> <p><a href="../byte/islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/iswupper" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/iswupper</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fiswxdigit.html b/devdocs/c/string%2Fwide%2Fiswxdigit.html new file mode 100644 index 00000000..4382bde0 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fiswxdigit.html @@ -0,0 +1,145 @@ + <h1 id="firstHeading" class="firstHeading">iswxdigit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int iswxdigit( wint_t ch );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Checks if the given wide character corresponds (if narrowed) to a hexadecimal numeric character, i.e. one of <code>0123456789abcdefABCDEF</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ch </td> <td> - </td> <td> wide character </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if the wide character is a hexadecimal numeric character, zero otherwise.</p> +<h3 id="Notes"> Notes</h3> <p><code><a href="iswdigit" title="c/string/wide/iswdigit">iswdigit</a></code> and <code>iswxdigit</code> are the only standard wide character classification functions that are not affected by the currently installed C locale.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>Some locales offer additional character classes that detect non-ASCII digits</p> +<div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <wchar.h> +#include <wctype.h> + +void test(wchar_t a3, wchar_t u3, wchar_t j3) +{ + printf("\t '%lc' '%lc' '%lc'\n", a3, u3, j3); + printf("iswxdigit: %d %d %d\n", + !!iswxdigit(a3), + !!iswxdigit(u3), + !!iswxdigit(j3)); + printf("jdigit: %d %d %d\n", + !!iswctype(a3, wctype("jdigit")), + !!iswctype(u3, wctype("jdigit")), + !!iswctype(j3, wctype("jdigit"))); +} + +int main(void) +{ + wchar_t a3 = L'9'; // the ASCII digit 9 + wchar_t u3 = L'〩'; // the CJK numeral 9 + wchar_t j3 = L'９'; // the full-width digit 9 + + setlocale(LC_ALL, "en_US.utf8"); + puts("In American locale:"); + test(a3, u3, j3); + + setlocale(LC_ALL, "ja_JP.utf8"); + puts("\nIn Japanese locale:"); + test(a3, u3, j3); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">In American locale: + '9' '〩' '９' +iswxdigit: 1 0 0 +jdigit: 0 0 0 + +In Japanese locale: + '9' '〩' '９' +iswxdigit: 1 0 0 +jdigit: 0 0 1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.30.2.1.12 The iswxdigit function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.30.2.1.12 The iswxdigit function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.30.2.1.12 The iswxdigit function (p: 451) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.25.2.1.12 The iswxdigit function (p: 397) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/isxdigit" title="c/string/byte/isxdigit"> <span class="t-lines"><span>isxdigit</span></span></a></div> </td> <td> checks if a character is a hexadecimal character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/iswxdigit" title="cpp/string/wide/iswxdigit">C++ documentation</a></span> for <code>iswxdigit</code> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="../byte/iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="../byte/isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <strong class="selflink"><code>iswxdigit</code></strong></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/iswxdigit" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/iswxdigit</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Ftowctrans.html b/devdocs/c/string%2Fwide%2Ftowctrans.html new file mode 100644 index 00000000..36a38b2b --- /dev/null +++ b/devdocs/c/string%2Fwide%2Ftowctrans.html @@ -0,0 +1,39 @@ + <h1 id="firstHeading" class="firstHeading">towctrans</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">wint_t towctrans( wint_t wc, wctrans_t desc );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Maps the wide character <code>wc</code> using the current C locale's <code><a href="../../locale/lc_categories" title="c/locale/LC categories">LC_CTYPE</a></code> mapping category identified by <code>desc</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> wc </td> <td> - </td> <td> the wide character to map </td> +</tr> <tr class="t-par"> <td> desc </td> <td> - </td> <td> the <code><a href="../../locale/lc_categories" title="c/locale/LC categories">LC_CTYPE</a></code> mapping, obtained from a call to <code><a href="wctrans" title="c/string/wide/wctrans">wctrans</a></code> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The mapped value of <code>wc</code> using the mapping identified by <code>desc</code> in <code><a href="../../locale/lc_categories" title="c/locale/LC categories">LC_CTYPE</a></code> facet of the current C locale.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <wctype.h> +#include <wchar.h> +#include <stdio.h> + +int main(void) +{ + setlocale(LC_ALL, "ja_JP.UTF-8"); + const wchar_t kana[] = L"ヒラガナ"; + size_t sz = sizeof kana / sizeof *kana; + wchar_t hira[sz]; + for (size_t n = 0; n < sz; ++n) + hira[n] = towctrans(kana[n], wctrans("tojhira")); + printf("katakana characters %ls are %ls in hiragana\n", kana, hira); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">katakana characters ヒラガナ are ひらがな in hiragana</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.30.3.2.1 The towctrans function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.30.3.2.1 The towctrans function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.30.3.2.1 The towctrans function (p: 454) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.25.3.2,1 The towctrans function (p: 400) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="wctrans" title="c/string/wide/wctrans"> <span class="t-lines"><span>wctrans</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> looks up a character mapping category in the current C locale <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/towctrans" title="cpp/string/wide/towctrans">C++ documentation</a></span> for <code>towctrans</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/towctrans" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/towctrans</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Ftowlower.html b/devdocs/c/string%2Fwide%2Ftowlower.html new file mode 100644 index 00000000..0d1bdad4 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Ftowlower.html @@ -0,0 +1,39 @@ + <h1 id="firstHeading" class="firstHeading">towlower</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">wint_t towlower( wint_t wc );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Converts the given wide character to lowercase, if possible.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> wc </td> <td> - </td> <td> wide character to be converted </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Lowercase version of <code>wc</code> or unmodified <code>wc</code> if no lowercase version is listed in the current C locale.</p> +<h3 id="Notes"> Notes</h3> <p>Only 1:1 character mapping can be performed by this function, e.g. the Greek uppercase letter <span class="st0">'Σ'</span> has two lowercase forms, depending on the position in a word: <span class="st0">'σ'</span> and <span class="st0">'ς'</span>. A call to <code>towlower</code> cannot be used to obtain the correct lowercase form in this case.</p> +<p><a rel="nofollow" class="external text" href="http://www.open-std.org/JTC1/SC35/WG5/docs/30112d10.pdf">ISO 30112</a> specifies which pairs of Unicode characters are included in this mapping.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <wchar.h> +#include <wctype.h> + +int main(void) +{ + wchar_t wc = L'\u0190'; // Latin capital open E ('Ɛ') + printf("in the default locale, towlower(%#x) = %#x\n", wc, towlower(wc)); + setlocale(LC_ALL, "en_US.utf8"); + printf("in Unicode locale, towlower(%#x) = %#x\n", wc, towlower(wc)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">in the default locale, towlower(0x190) = 0x190 +in Unicode locale, towlower(0x190) = 0x25b</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.30.3.1.1 The towlower function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.30.3.1.1 The towlower function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.30.3.1.1 The towlower function (p: 453) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.25.3.1.1 The towlower function (p: 399) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="towupper" title="c/string/wide/towupper"> <span class="t-lines"><span>towupper</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> converts a wide character to uppercase <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../byte/tolower" title="c/string/byte/tolower"> <span class="t-lines"><span>tolower</span></span></a></div> </td> <td> converts a character to lowercase <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/towlower" title="cpp/string/wide/towlower">C++ documentation</a></span> for <code>towlower</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/towlower" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/towlower</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Ftowupper.html b/devdocs/c/string%2Fwide%2Ftowupper.html new file mode 100644 index 00000000..4e0cdeb3 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Ftowupper.html @@ -0,0 +1,35 @@ + <h1 id="firstHeading" class="firstHeading">towupper</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">wint_t towupper( wint_t wc );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Converts the given wide character to uppercase, if possible.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> wc </td> <td> - </td> <td> wide character to be converted </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Uppercase version of <code>wc</code> or unmodified <code>wc</code> if no uppercase version is listed in the current C locale.</p> +<h3 id="Notes"> Notes</h3> <p>Only 1:1 character mapping can be performed by this function, e.g. the uppercase form of 'ß' is (with some exceptions) the two-character string "SS", which cannot be obtained by <code>towupper</code>.</p> +<p><a rel="nofollow" class="external text" href="http://www.open-std.org/JTC1/SC35/WG5/docs/30112d10.pdf">ISO 30112</a> specifies which pairs of Unicode characters are included in this mapping.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <wchar.h> +#include <wctype.h> +#include <locale.h> + +int main(void) +{ + wchar_t wc = L'\u017f'; // Latin small letter Long S ('ſ') + printf("in the default locale, towupper(%#x) = %#x\n", wc, towupper(wc)); + setlocale(LC_ALL, "en_US.utf8"); + printf("in Unicode locale, towupper(%#x) = %#x\n", wc, towupper(wc)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">in the default locale, towupper(0x17f) = 0x17f +in Unicode locale, towupper(0x17f) = 0x53</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.30.3.1.2 The towupper function (p: 453) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.25.3.1.2 The towupper function (p: 399) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="towlower" title="c/string/wide/towlower"> <span class="t-lines"><span>towlower</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> converts a wide character to lowercase <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../byte/toupper" title="c/string/byte/toupper"> <span class="t-lines"><span>toupper</span></span></a></div> </td> <td> converts a character to uppercase <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/towupper" title="cpp/string/wide/towupper">C++ documentation</a></span> for <code>towupper</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/towupper" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/towupper</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwcscat.html b/devdocs/c/string%2Fwide%2Fwcscat.html new file mode 100644 index 00000000..038a0a54 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcscat.html @@ -0,0 +1,62 @@ + <h1 id="firstHeading" class="firstHeading">wcscat, wcscat_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td> <pre data-language="c">wchar_t *wcscat( wchar_t *dest, const wchar_t *src );</pre> +</td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">wchar_t *wcscat( wchar_t *restrict dest, const wchar_t *restrict src );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t wcscat_s( wchar_t *restrict dest, rsize_t destsz, + const wchar_t *restrict src );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Appends a copy of the wide string pointed to by <code>src</code> to the end of the wide string pointed to by <code>dest</code>. The wide character <code>src[0]</code> replaces the null terminator at the end of <code>dest</code>. The resulting wide string is null-terminated. The behavior is undefined if the destination array is not large enough for the contents of both <code>str</code> and <code>dest</code> and the terminating null wide character. The behavior is undefined if the strings overlap. </div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that it may clobber the rest of the destination array (from the last character written to <code>destsz</code>) with unspecified values and that the following errors are detected at runtime and call the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> <code>src</code> or <code>dest</code> is a null pointer </li> +<li> <code>destsz</code> is zero or greater than <code>RSIZE_MAX/sizeof(wchar_t)</code> </li> +<li> there is no null terminator in the first <code>destsz</code> wide characters of <code>dest</code> </li> +<li> truncation would occur (the available space at the end of <code>dest</code> would not fit every wide character, including the null terminator, of <code>src</code>) </li> +<li> overlap would occur between the source and the destination strings </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>wcscat_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../wide" title="c/string/wide"><code><wchar.h></code></a>.</dd> +</dl> +</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the null-terminated wide string to append to </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the null-terminated wide string to copy from </td> +</tr> <tr class="t-par"> <td> destsz </td> <td> - </td> <td> maximum number of characters to write, typically the size of the destination buffer </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> returns a copy of <code>dest</code> +</div> <div class="t-li1"> +<span class="t-li">2)</span> returns zero on success, returns non-zero on error. Also, on error, writes <code>L'\0'</code> to <code>dest[0]</code> (unless <code>dest</code> is a null pointer or <code>destsz</code> is zero or greater than <code>RSIZE_MAX/sizeof(wchar_t)</code>).</div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <wchar.h> +#include <stdio.h> +#include <locale.h> + +int main(void) +{ + wchar_t str[50] = L"Земля, прощай."; + wcscat(str, L" "); + wcscat(str, L"В добрый путь."); + setlocale(LC_ALL, "en_US.utf8"); + printf("%ls", str); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Земля, прощай. В добрый путь.</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.29.4.3.1 The wcscat function (p: 315) </li> +<li> K.3.9.2.2.1 The wcscat_s function (p: 466) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.29.4.3.1 The wcscat function (p: 432) </li> +<li> K.3.9.2.2.1 The wcscat_s function (p: 642-643) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.3.1 The wcscat function (p: 378) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="wcsncat" title="c/string/wide/wcsncat"> <span class="t-lines"><span>wcsncat</span><span>wcsncat_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> appends a certain amount of wide characters from one wide string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../byte/strcat" title="c/string/byte/strcat"> <span class="t-lines"><span>strcat</span><span>strcat_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> concatenates two strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcscpy" title="c/string/wide/wcscpy"> <span class="t-lines"><span>wcscpy</span><span>wcscpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies one wide string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wcscat" title="cpp/string/wide/wcscat">C++ documentation</a></span> for <code>wcscat</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wcscat" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wcscat</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwcschr.html b/devdocs/c/string%2Fwide%2Fwcschr.html new file mode 100644 index 00000000..586441d6 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcschr.html @@ -0,0 +1,50 @@ + <h1 id="firstHeading" class="firstHeading">wcschr</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c95"> <td> <pre data-language="c">wchar_t *wcschr( const wchar_t *str, wchar_t ch );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">/*QWchar_t*/ *wcschr( /*QWchar_t*/ *str, wchar_t ch );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Finds the first occurrence of the wide character <code>ch</code> in the wide string pointed to by <code>str</code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Type-generic function equivalent to <span class="t-v">(1)</span>. Let <code>T</code> be an unqualified wide character object type. <ul> +<li> If <code>str</code> is of type <code>const T*</code>, the return type is <code>const wchar_t*</code>. </li> +<li> Otherwise, if <code>str</code> is of type <code>T*</code>, the return type is <code>wchar_t*</code>. </li> +<li> Otherwise, the behavior is undefined. </li> +</ul> If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if <code>(wcschr)</code> or a function pointer is used), the actual function declaration <span class="t-v">(1)</span> becomes visible.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> pointer to the null-terminated wide string to be analyzed </td> +</tr> <tr class="t-par"> <td> ch </td> <td> - </td> <td> wide character to search for </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Pointer to the found character in <code>str</code>, or a null pointer if no such character is found.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <wchar.h> +#include <stdio.h> +#include <locale.h> + +int main(void) +{ + wchar_t arr[] = L"白猫 黒猫 кошки"; + wchar_t *cat = wcschr(arr, L'猫'); + wchar_t *dog = wcschr(arr, L'犬'); + + setlocale(LC_ALL, "en_US.utf8"); + if(cat) + printf("The character 猫 found at position %td\n", cat-arr); + else + puts("The character 猫 not found"); + + if(dog) + printf("The character 犬 found at position %td\n", dog-arr); + else + puts("The character 犬 not found"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">The character 猫 found at position 1 +The character 犬 not found</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.4.5.1 The wcschr function (p: 435) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.5.1 The wcschr function (p: 381) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="wcsrchr" title="c/string/wide/wcsrchr"> <span class="t-lines"><span>wcsrchr</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> finds the last occurrence of a wide character in a wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcspbrk" title="c/string/wide/wcspbrk"> <span class="t-lines"><span>wcspbrk</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> finds the first location of any wide character in one wide string, in another wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wcschr" title="cpp/string/wide/wcschr">C++ documentation</a></span> for <code>wcschr</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wcschr" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wcschr</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwcscmp.html b/devdocs/c/string%2Fwide%2Fwcscmp.html new file mode 100644 index 00000000..297be2b0 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcscmp.html @@ -0,0 +1,55 @@ + <h1 id="firstHeading" class="firstHeading">wcscmp</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int wcscmp( const wchar_t* lhs, const wchar_t* rhs );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Compares two null-terminated wide strings lexicographically.</p> +<p>The sign of the result is the sign of the difference between the values of the first pair of wide characters that differ in the strings being compared.</p> +<p>The behavior is undefined if <code>lhs</code> or <code>rhs</code> are not pointers to null-terminated wide strings.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> lhs, rhs </td> <td> - </td> <td> pointers to the null-terminated wide strings to compare </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Negative value if <code>lhs</code> appears before <code>rhs</code> in lexicographical order.</p> +<p>Zero if <code>lhs</code> and <code>rhs</code> compare equal.</p> +<p>Positive value if <code>lhs</code> appears after <code>rhs</code> in lexicographical order.</p> +<h3 id="Notes"> Notes</h3> <p>This function is not locale-sensitive, unlike <code><a href="wcscoll" title="c/string/wide/wcscoll">wcscoll</a></code>, and the order may not be meaningful when characters from different Unicode blocks are used together or when the order of code units does not match any collation order.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <wchar.h> + +void demo(const wchar_t* lhs, const wchar_t* rhs) +{ + int rc = wcscmp(lhs, rhs); + const char *rel = rc < 0 ? "precedes" : rc > 0 ? "follows" : "equals"; + + setlocale(LC_ALL, "en_US.utf8"); + printf("[%ls] %s [%ls]\n", lhs, rel, rhs); +} + +int main(void) +{ + const wchar_t* string = L"どうもありがとうございます"; + demo(string, L"どうも"); + demo(string, L"助かった"); + demo(string + 9, L"ありがとうございます" + 6); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">[どうもありがとうございます] follows [どうも] +[どうもありがとうございます] precedes [助かった] +[ざいます] equals [ざいます]</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.29.4.4.1 The wcscmp function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.29.4.4.1 The wcscmp function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.4.4.1 The wcscmp function (p: 433) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.4.1 The wcscmp function (p: 379) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="wcsncmp" title="c/string/wide/wcsncmp"> <span class="t-lines"><span>wcsncmp</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> compares a certain amount of characters from two wide strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wmemcmp" title="c/string/wide/wmemcmp"> <span class="t-lines"><span>wmemcmp</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> compares a certain amount of wide characters from two arrays <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../byte/strcmp" title="c/string/byte/strcmp"> <span class="t-lines"><span>strcmp</span></span></a></div> </td> <td> compares two strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcscoll" title="c/string/wide/wcscoll"> <span class="t-lines"><span>wcscoll</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> compares two wide strings in accordance to the current locale <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wcscmp" title="cpp/string/wide/wcscmp">C++ documentation</a></span> for <code>wcscmp</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wcscmp" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wcscmp</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwcscoll.html b/devdocs/c/string%2Fwide%2Fwcscoll.html new file mode 100644 index 00000000..d011acc3 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcscoll.html @@ -0,0 +1,58 @@ + <h1 id="firstHeading" class="firstHeading">wcscoll</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int wcscoll( const wchar_t *lhs, const wchar_t *rhs );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Compares two null-terminated wide strings according to the collation order defined by the <code><a href="../../locale/lc_categories" title="c/locale/LC categories">LC_COLLATE</a></code> category of the currently installed locale.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> lhs, rhs </td> <td> - </td> <td> pointers to the null-terminated wide strings to compare </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Negative value if <code>lhs</code> is <i>less than</i> (precedes) <code>rhs</code>.</p> +<p><code>0</code> if <code>lhs</code> is <i>equal to</i> <code>rhs</code>.</p> +<p>Positive value if <code>lhs</code> is <i>greater than</i> (follows) <code>rhs</code>.</p> +<h3 id="Notes"> Notes</h3> <p>Collation order is the dictionary order: the position of the letter in the national alphabet (its <i>equivalence class</i>) has higher priority than its case or variant. Within an equivalence class, lowercase characters collate before their uppercase equivalents and locale-specific order may apply to the characters with diacritics. In some locales, groups of characters compare as single <i>collation units</i>. For example, <code>"ch"</code> in Czech follows <code>"h"</code> and precedes <code>"i"</code>, and <code>"dzs"</code> in Hungarian follows <code>"dz"</code> and precedes <code>"g"</code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <wchar.h> +#include <locale.h> + +void try_compare(const wchar_t* p1, const wchar_t* p2) +{ + if(wcscoll(p1, p2) < 0) + printf("%ls before %ls\n", p1, p2); + else + printf("%ls before %ls\n", p2, p1); +} + +int main(void) +{ + setlocale(LC_ALL, "en_US.utf8"); + printf("In the American locale: "); + try_compare(L"hrnec", L"chrt"); + + setlocale(LC_COLLATE, "cs_CZ.utf8"); + printf("In the Czech locale: "); + try_compare(L"hrnec", L"chrt"); + + setlocale(LC_COLLATE, "en_US.utf8"); + printf("In the American locale: "); + try_compare(L"år", L"ängel"); + + setlocale(LC_COLLATE, "sv_SE.utf8"); + printf("In the Swedish locale: "); + try_compare(L"år", L"ängel"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">In the American locale: chrt before hrnec +In the Czech locale: hrnec before chrt +In the American locale: ängel before år +In the Swedish locale: år before ängel</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.4.4.2 The wcscoll function (p: 433-434) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.4.2 The wcscoll function (p: 379-380) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/strcoll" title="c/string/byte/strcoll"> <span class="t-lines"><span>strcoll</span></span></a></div> </td> <td> compares two strings in accordance to the current locale <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcsxfrm" title="c/string/wide/wcsxfrm"> <span class="t-lines"><span>wcsxfrm</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> transform a wide string so that wcscmp would produce the same result as wcscoll <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcscmp" title="c/string/wide/wcscmp"> <span class="t-lines"><span>wcscmp</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> compares two wide strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wcscoll" title="cpp/string/wide/wcscoll">C++ documentation</a></span> for <code>wcscoll</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wcscoll" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wcscoll</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwcscpy.html b/devdocs/c/string%2Fwide%2Fwcscpy.html new file mode 100644 index 00000000..0242fb59 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcscpy.html @@ -0,0 +1,70 @@ + <h1 id="firstHeading" class="firstHeading">wcscpy, wcscpy_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td> <pre data-language="c">wchar_t* wcscpy( wchar_t* dest, const wchar_t* src );</pre> +</td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">wchar_t* wcscpy( wchar_t* restrict dest, const wchar_t* restrict src );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t wcscpy_s( wchar_t* restrict dest, rsize_t destsz, + const wchar_t* restrict src );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Copies the wide string pointed to by <code>src</code> (including the terminating null wide character) to wide character array pointed to by <code>dest</code>. The behavior is undefined if the <code>dest</code> array is not large enough. The behavior is undefined if the strings overlap.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that it may clobber the rest of the destination array with unspecified values and that the following errors are detected at runtime and call the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> <code>src</code> or <code>dest</code> is a null pointer </li> +<li> <code>destsz</code> is zero or greater than <code>RSIZE_MAX / sizeof(wchar_t)</code> </li> +<li> <code>destsz</code> is less or equal <code>wcsnlen_s(src, destsz)</code>, in other words, truncation would occur </li> +<li> overlap would occur between the source and the destination strings </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>wcscpy_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../wide" title="c/string/wide"><code><wchar.h></code></a>.</dd> +</dl> +</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the wide character array to copy to </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the null-terminated wide string to copy from </td> +</tr> <tr class="t-par"> <td> destsz </td> <td> - </td> <td> maximum number of characters to write, typically the size of the destination buffer </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> returns a copy of <code>dest</code> +</div> <div class="t-li1"> +<span class="t-li">2)</span> returns zero on success, returns non-zero on error. Also, on error, writes <code>L'\0'</code> to <code>dest[0]</code> (unless <code>dest</code> is a null pointer or <code>destsz</code> is zero or greater than <code>RMAX_SIZE / sizeof(wchar_t)</code>).</div> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <wchar.h> + +int main(void) +{ + wchar_t* src = L"犬 means dog"; +// src[0] = L'狗' ; // this would be undefined behavior + wchar_t dst[wcslen(src) + 1]; // +1 for the null terminator + wcscpy(dst, src); + dst[0] = L'狗'; // OK + + setlocale(LC_ALL, "en_US.utf8"); + printf("src = %ls\ndst = %ls\n", src, dst); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">src = 犬 means dog +dst = 狗 means dog</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.29.4.1.2 The wcscpy function (p: TBD) </li> +<li> K.3.9.2.1.1 The wcscpy_s function (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.29.4.1.2 The wcscpy function (p: TBD) </li> +<li> K.3.9.2.1.1 The wcscpy_s function (p: TBD) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.29.4.1.2 The wcscpy function (p: 430) </li> +<li> K.3.9.2.1.1 The wcscpy_s function (p: 639) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.1.2 The wcscpy function (p: 376) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="wcsncpy" title="c/string/wide/wcsncpy"> <span class="t-lines"><span>wcsncpy</span><span>wcsncpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies a certain amount of wide characters from one string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wmemcpy" title="c/string/wide/wmemcpy"> <span class="t-lines"><span>wmemcpy</span><span>wmemcpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies a certain amount of wide characters between two non-overlapping arrays <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../byte/strcpy" title="c/string/byte/strcpy"> <span class="t-lines"><span>strcpy</span><span>strcpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies one string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wcscpy" title="cpp/string/wide/wcscpy">C++ documentation</a></span> for <code>wcscpy</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wcscpy" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wcscpy</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwcscspn.html b/devdocs/c/string%2Fwide%2Fwcscspn.html new file mode 100644 index 00000000..2cafb850 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcscspn.html @@ -0,0 +1,39 @@ + <h1 id="firstHeading" class="firstHeading">wcscspn</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">size_t wcscspn( const wchar_t* dest, const wchar_t* src );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Returns the length of the maximum initial segment of the wide string pointed to by <code>dest</code>, that consists of only the characters <i>not</i> found in wide string pointed to by <code>src</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the null-terminated wide string to be analyzed </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the null-terminated wide string that contains the characters to search for </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The length of the maximum initial segment that contains only characters not found in the character string pointed to by <code>src</code></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <wchar.h> + +int main(void) +{ + wchar_t dest[] = L"白猫 黑狗 甲虫"; + /* └───┐ */ + const wchar_t *src = L"甲虫,黑狗"; + + const size_t len = wcscspn(dest, src); + dest[len] = L'\0'; /* terminates the segment to print it out */ + + setlocale(LC_ALL, "en_US.utf8"); + wprintf(L"The length of maximum initial segment is %td.\n" + L"The segment is \"%ls\".\n", len, dest); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">The length of maximum initial segment is 3. +The segment is "白猫 ".</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.4.5.2 The wcscspn function (p: 435-436) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.5.2 The wcscspn function (p: 381-382) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="wcsspn" title="c/string/wide/wcsspn"> <span class="t-lines"><span>wcsspn</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> returns the length of the maximum initial segment that consists <br> of only the wide characters found in another wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcspbrk" title="c/string/wide/wcspbrk"> <span class="t-lines"><span>wcspbrk</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> finds the first location of any wide character in one wide string, in another wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wcscspn" title="cpp/string/wide/wcscspn">C++ documentation</a></span> for <code>wcscspn</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wcscspn" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wcscspn</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwcslen.html b/devdocs/c/string%2Fwide%2Fwcslen.html new file mode 100644 index 00000000..efb4dde8 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcslen.html @@ -0,0 +1,38 @@ + <h1 id="firstHeading" class="firstHeading">wcslen, wcsnlen_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c95"> <td> <pre data-language="c">size_t wcslen( const wchar_t *str );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">size_t wcsnlen_s(const wchar_t *str, size_t strsz);</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Returns the length of a wide string, that is the number of non-null wide characters that precede the terminating null wide character.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that the function returns zero if <code>str</code> is a null pointer and returns <code>strsz</code> if the null wide character was not found in the first <code>strsz</code> wide characters of <code>src</code> As with all bounds-checked functions, <code>wcslen_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../../io" title="c/io"><code><stdio.h></code></a>..</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> pointer to the null-terminated wide string to be examined </td> +</tr> <tr class="t-par"> <td> strsz </td> <td> - </td> <td> maximum number of wide characters to examine </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> The length of the null-terminated wide string <code>str</code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> The length of the null-terminated wide string <code>str</code> on success, zero if <code>str</code> is a null pointer, <code>strsz</code> if the null wide character was not found.</div> <h3 id="Notes"> Notes</h3> <p><code>strnlen_s</code> and <code>wcsnlen_s</code> are the only <a href="../../error" title="c/error">bounds-checked functions</a> that do not invoke the runtime constraints handler. They are pure utility functions used to provide limited support for non-null terminated strings.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <wchar.h> +#include <stdio.h> + +int main(void) +{ + wchar_t str[] = L"How many wide characters does this string contain?"; + + printf("without null character: %zu\n", wcslen(str)); + printf("with null character: %zu\n", sizeof str / sizeof *str); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">without null character: 50 +with null character: 51</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.29.4.6.1 The wcslen function (p: 439) </li> +<li> K.3.9.2.4.1 The wcsnlen_s function (p: 646-647) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.6.1 The wcslen function (p: 385) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/strlen" title="c/string/byte/strlen"> <span class="t-lines"><span>strlen</span><span>strnlen_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> returns the length of a given string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wcslen" title="cpp/string/wide/wcslen">C++ documentation</a></span> for <code>wcslen</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wcslen" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wcslen</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwcsncat.html b/devdocs/c/string%2Fwide%2Fwcsncat.html new file mode 100644 index 00000000..17540682 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcsncat.html @@ -0,0 +1,67 @@ + <h1 id="firstHeading" class="firstHeading">wcsncat, wcsncat_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td> <pre data-language="c">wchar_t *wcsncat( wchar_t *dest, const wchar_t *src, size_t count );</pre> +</td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">wchar_t *wcsncat( wchar_t *restrict dest, + const wchar_t *restrict src, size_t count );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t wcsncat_s( wchar_t *restrict dest, rsize_t destsz, + const wchar_t *restrict src, rsize_t count );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Appends at most <code>count</code> wide characters from the wide string pointed to by <code>src</code>, stopping if the null terminator is copied, to the end of the character string pointed to by <code>dest</code>. The wide character <code>src[0]</code> replaces the null terminator at the end of <code>dest</code>. The null terminator is always appended in the end (so the maximum number of wide characters the function may write is <code>count+1</code>).</div> <div class="t-li1"> + The behavior is undefined if the destination array is not large enough for the contents of both <code>str</code> and <code>dest</code> and the terminating null wide character.</div> <div class="t-li1"> + The behavior is undefined if the strings overlap. </div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that this function may clobber the remainder of the destination array (from the last wide character written to <code>destsz</code>) and that the following errors are detected at runtime and call the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> <code>src</code> or <code>dest</code> is a null pointer </li> +<li> <code>destsz</code> or <code>count</code> is zero or greater than <code>RSIZE_MAX/sizeof(wchar_t)</code> </li> +<li> there is no null wide character in the first <code>destsz</code> wide characters of <code>dest</code> </li> +<li> truncation would occur: <code>count</code> or the length of <code>src</code>, whichever is less, exceeds the space available between the null terminator of <code>dest</code> and <code>destsz</code>. </li> +<li> overlap would occur between the source and the destination strings </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>wcsncat_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../wide" title="c/string/wide"><code><wchar.h></code></a>.</dd> +</dl> +</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the null-terminated wide string to append to </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the null-terminated wide string to copy from </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> maximum number of wide characters to copy </td> +</tr> <tr class="t-par"> <td> destsz </td> <td> - </td> <td> the size of the destination buffer </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> returns a copy of <code>dest</code> +</div> <div class="t-li1"> +<span class="t-li">2)</span> returns zero on success, returns non-zero on error. Also, on error, writes <code>L'\0'</code> to <code>dest[0]</code> (unless <code>dest</code> is a null pointer or <code>destsz</code> is zero or greater than <code>RSIZE_MAX/sizeof(wchar_t)</code>).</div> <h3 id="Notes"> Notes</h3> <p>Although truncation to fit the destination buffer is a security risk and therefore a runtime constraints violation for <code>wcsncat_s</code>, it is possible to get the truncating behavior by specifying <code>count</code> equal to the size of the destination array minus one: it will copy the first <code>count</code> wide characters and append the null terminator as always: <code>wcsncat_s(dst, sizeof dst/sizeof *dst, src, (sizeof dst/sizeof *dst)-wcsnlen_s(dst, sizeof dst/sizeof *dst)-1);</code></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <wchar.h> +#include <stdio.h> +#include <locale.h> + +int main(void) +{ + wchar_t str[50] = L"Земля, прощай."; + wcsncat(str, L" ", 1); + wcsncat(str, L"В добрый путь.", 8); // only append the first 8 wide chars + setlocale(LC_ALL, "en_US.utf8"); + printf("%ls", str); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Земля, прощай. В добрый</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.29.4.3.2 The wcsncat function (p: 315) </li> +<li> K.3.9.2.2.2 The wcsncat_s function (p: 466-467) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.29.4.3.2 The wcsncat function (p: 432-433) </li> +<li> K.3.9.2.2.2 The wcsncat_s function (p: 643-644) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.3.2 The wcsncat function (p: 378-379) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="wcscat" title="c/string/wide/wcscat"> <span class="t-lines"><span>wcscat</span><span>wcscat_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> appends a copy of one wide string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../byte/strncat" title="c/string/byte/strncat"> <span class="t-lines"><span>strncat</span><span>strncat_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> concatenates a certain amount of characters of two strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcscpy" title="c/string/wide/wcscpy"> <span class="t-lines"><span>wcscpy</span><span>wcscpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies one wide string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wcsncat" title="cpp/string/wide/wcsncat">C++ documentation</a></span> for <code>wcsncat</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wcsncat" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wcsncat</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwcsncmp.html b/devdocs/c/string%2Fwide%2Fwcsncmp.html new file mode 100644 index 00000000..33c62955 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcsncmp.html @@ -0,0 +1,56 @@ + <h1 id="firstHeading" class="firstHeading">wcsncmp</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int wcsncmp( const wchar_t* lhs, const wchar_t* rhs, size_t count );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Compares at most <code>count</code> wide characters of two null-terminated wide strings. The comparison is done lexicographically.</p> +<p>The sign of the result is the sign of the difference between the values of the first pair of wide characters that differ in the strings being compared.</p> +<p>The behavior is undefined if <code>lhs</code> or <code>rhs</code> are not pointers to null-terminated strings.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> lhs, rhs </td> <td> - </td> <td> pointers to the null-terminated wide strings to compare </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> maximum number of characters to compare </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Negative value if <code>lhs</code> appears before <code>rhs</code> in lexicographical order.</p> +<p>Zero if <code>lhs</code> and <code>rhs</code> compare equal.</p> +<p>Positive value if <code>lhs</code> appears after <code>rhs</code> in lexicographical order.</p> +<h3 id="Notes"> Notes</h3> <p>This function is not locale-sensitive, unlike <code><a href="wcscoll" title="c/string/wide/wcscoll">wcscoll</a></code> and <code><a href="wcsxfrm" title="c/string/wide/wcsxfrm">wcsxfrm</a></code>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <wchar.h> +#include <locale.h> + +void demo(const wchar_t *lhs, const wchar_t *rhs, int sz) +{ + int rc = wcsncmp(lhs, rhs, sz); + if(rc == 0) + printf("First %d characters of [%ls] equal [%ls]\n", sz, lhs, rhs); + else if(rc < 0) + printf("First %d characters of [%ls] precede [%ls]\n", sz, lhs, rhs); + else if(rc > 0) + printf("First %d characters of [%ls] follow [%ls]\n", sz, lhs, rhs); +} + +int main(void) +{ + const wchar_t *str1 = L"안녕하세요"; + const wchar_t *str2 = L"안녕히 가십시오"; + + setlocale(LC_ALL, "en_US.utf8"); + demo(str1, str2, 5); + demo(str2, str1, 8); + demo(str1, str2, 2); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">First 5 characters of [안녕하세요] precede [안녕히 가십시오] +First 8 characters of [안녕히 가십시오] follow [안녕하세요] +First 2 characters of [안녕하세요] equal [안녕히 가십시오]</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.4.4.3 The wcsncmp function (p: 434) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.4.3 The wcsncmp function (p: 380) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="wcscmp" title="c/string/wide/wcscmp"> <span class="t-lines"><span>wcscmp</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> compares two wide strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wmemcmp" title="c/string/wide/wmemcmp"> <span class="t-lines"><span>wmemcmp</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> compares a certain amount of wide characters from two arrays <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcscoll" title="c/string/wide/wcscoll"> <span class="t-lines"><span>wcscoll</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> compares two wide strings in accordance to the current locale <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wcsncmp" title="cpp/string/wide/wcsncmp">C++ documentation</a></span> for <code>wcsncmp</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wcsncmp" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wcsncmp</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwcsncpy.html b/devdocs/c/string%2Fwide%2Fwcsncpy.html new file mode 100644 index 00000000..7cc3efa4 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcsncpy.html @@ -0,0 +1,76 @@ + <h1 id="firstHeading" class="firstHeading">wcsncpy, wcsncpy_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td> <pre data-language="c">wchar_t* wcsncpy( wchar_t* dest, const wchar_t* src, size_t count );</pre> +</td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">wchar_t *wcsncpy( wchar_t *restrict dest, const wchar_t *restrict src, size_t count );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t wcsncpy_s( wchar_t *restrict dest, rsize_t destsz, + const wchar_t *restrict src, rsize_t count);</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Copies at most <code>count</code> characters of the wide string pointed to by <code>src</code> (including the terminating null wide character) to wide character array pointed to by <code>dest</code>. </div> <div class="t-li1"> + If <code>count</code> is reached before the entire string <code>src</code> was copied, the resulting wide character array is not null-terminated.</div> <div class="t-li1"> + If, after copying the terminating null wide character from <code>src</code>, <code>count</code> is not reached, additional null wide characters are written to <code>dest</code> until the total of <code>count</code> characters have been written.</div> <div class="t-li1"> + If the strings overlap, the behavior is undefined.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that the function does not continue writing zeroes into the destination array to pad up to <code>count</code>, it stops after writing the terminating null character (if there was no null in the source, it writes one at <code>dest[count]</code> and then stops). Also, the following errors are detected at runtime and call the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> <code>src</code> or <code>dest</code> is a null pointer </li> +<li> <code>destsz</code> or <code>count</code> is zero or greater than <code>RSIZE_MAX/sizeof(wchar_t)</code> </li> +<li> <code>count</code> is greater or equal <code>destsz</code>, but <code>destsz</code> is less or equal <code>wcsnlen_s(src, count)</code>, in other words, truncation would occur </li> +<li> overlap would occur between the source and the destination strings </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>wcsncpy_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../wide" title="c/string/wide"><code><wchar.h></code></a>.</dd> +</dl> +</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the wide character array to copy to </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the wide string to copy from </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> maximum number of wide characters to copy </td> +</tr> <tr class="t-par"> <td> destsz </td> <td> - </td> <td> the size of the destination buffer </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> returns a copy of <code>dest</code> +</div> <div class="t-li1"> +<span class="t-li">2)</span> returns zero on success, returns non-zero on error. Also, on error, writes <code>L'\0'</code> to <code>dest[0]</code> (unless <code>dest</code> is a null pointer or <code>destsz</code> is zero or greater than <code>RSIZE_MAX/sizeof(wchar_t)</code>) and may clobber the rest of the destination array with unspecified values.</div> <h3 id="Notes"> Notes</h3> <p>In typical usage, <code>count</code> is the number of elements in the destination array.</p> +<p>Although truncation to fit the destination buffer is a security risk and therefore a runtime constraints violation for <code>wcsncpy_s</code>, it is possible to get the truncating behavior by specifying <code>count</code> equal to the size of the destination array minus one: it will copy the first <code>count</code> wide characters and append the null wide terminator as always: <code>wcsncpy_s(dst, sizeof dst / sizeof *dst, src, (sizeof dst / sizeof *dst)-1);</code></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <wchar.h> +#include <locale.h> + +int main(void) +{ + const wchar_t src[] = L"わゐ"; + wchar_t dest[6] = {L'あ', L'い', L'う', L'え', L'お'}; + + wcsncpy(dest, src, 4); // this will copy わゐ and repeat L'\0' two times + + puts("The contents of dest are: "); + setlocale(LC_ALL, "en_US.utf8"); + + const long dest_size = sizeof dest / sizeof *dest; + for(wchar_t* p = dest; p-dest != dest_size; ++p) { + *p ? printf("%lc ", *p) + : printf("\\0 "); + } +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">The contents of dest are: +わ ゐ \0 \0 お \0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.29.4.2.2 The wcsncpy function (p: 314) </li> +<li> K.3.9.2.1.2 The wcsncpy_s function (p: 464) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.29.4.2.2 The wcsncpy function (p: 431) </li> +<li> K.3.9.2.1.2 The wcsncpy_s function (p: 640-641) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.2.2 The wcsncpy function (p: 377) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="wcscpy" title="c/string/wide/wcscpy"> <span class="t-lines"><span>wcscpy</span><span>wcscpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies one wide string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wmemcpy" title="c/string/wide/wmemcpy"> <span class="t-lines"><span>wmemcpy</span><span>wmemcpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies a certain amount of wide characters between two non-overlapping arrays <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../byte/strncpy" title="c/string/byte/strncpy"> <span class="t-lines"><span>strncpy</span><span>strncpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies a certain amount of characters from one string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wcsncpy" title="cpp/string/wide/wcsncpy">C++ documentation</a></span> for <code>wcsncpy</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wcsncpy" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wcsncpy</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwcspbrk.html b/devdocs/c/string%2Fwide%2Fwcspbrk.html new file mode 100644 index 00000000..f6d7a55a --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcspbrk.html @@ -0,0 +1,47 @@ + <h1 id="firstHeading" class="firstHeading">wcspbrk</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c95"> <td> <pre data-language="c">wchar_t *wcspbrk( const wchar_t *dest, const wchar_t *str );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">/*QWchar_t*/ *wcspbrk( /*QWchar_t*/ *dest, const wchar_t *str );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Finds the first character in wide string pointed to by <code>dest</code>, that is also in wide string pointed to by <code>str</code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Type-generic function equivalent to <span class="t-v">(1)</span>. Let <code>T</code> be an unqualified wide character object type. <ul> +<li> If <code>dest</code> is of type <code>const T*</code>, the return type is <code>const wchar_t*</code>. </li> +<li> Otherwise, if <code>dest</code> is of type <code>T*</code>, the return type is <code>wchar_t*</code>. </li> +<li> Otherwise, the behavior is undefined. </li> +</ul> If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if <code>(wcspbrk)</code> or a function pointer is used), the actual function declaration <span class="t-v">(1)</span> becomes visible.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the null-terminated wide string to be analyzed </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the null-terminated wide string that contains the characters to search for </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Pointer to the first character in <code>dest</code>, that is also in <code>str</code>, or a null pointer if no such character exists.</p> +<h3 id="Notes"> Notes</h3> <p>The name stands for "wide character string pointer break", because it returns a pointer to the first of the separator ("break") characters.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <wchar.h> + +int main(void) +{ + const wchar_t* str = L"Hello world, friend of mine!"; + const wchar_t* sep = L" ,!"; + + unsigned int cnt = 0; + do { + str = wcspbrk(str, sep); // find separator + if (str) str += wcsspn(str, sep); // skip separator + ++cnt; // increment word count + } while (str && *str); + + wprintf(L"There are %u words.\n", cnt); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">There are 5 words.</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.4.5.3 The wcspbrk function (p: 436) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.5.3 The wcspbrk function (p: 382) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="wcscspn" title="c/string/wide/wcscspn"> <span class="t-lines"><span>wcscspn</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> returns the length of the maximum initial segment that consists <br> of only the wide chars <i>not</i> found in another wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcschr" title="c/string/wide/wcschr"> <span class="t-lines"><span>wcschr</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> finds the first occurrence of a wide character in a wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../byte/strpbrk" title="c/string/byte/strpbrk"> <span class="t-lines"><span>strpbrk</span></span></a></div> </td> <td> finds the first location of any character in one string, in another string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wcspbrk" title="cpp/string/wide/wcspbrk">C++ documentation</a></span> for <code>wcspbrk</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wcspbrk" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wcspbrk</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwcsrchr.html b/devdocs/c/string%2Fwide%2Fwcsrchr.html new file mode 100644 index 00000000..7cfeb461 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcsrchr.html @@ -0,0 +1,51 @@ + <h1 id="firstHeading" class="firstHeading">wcsrchr</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c95"> <td> <pre data-language="c">wchar_t *wcsrchr( const wchar_t *str, wchar_t ch );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">/*QWchar_t*/ *wcsrchr( /*QWchar_t*/ *str, wchar_t ch );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Finds the last occurrence of the wide character <code>ch</code> in the wide string pointed to by <code>str</code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Type-generic function equivalent to <span class="t-v">(1)</span>. Let <code>T</code> be an unqualified wide character object type. <ul> +<li> If <code>str</code> is of type <code>const T*</code>, the return type is <code>const wchar_t*</code>. </li> +<li> Otherwise, if <code>str</code> is of type <code>T*</code>, the return type is <code>wchar_t*</code>. </li> +<li> Otherwise, the behavior is undefined. </li> +</ul> If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if <code>(wcsrchr)</code> or a function pointer is used), the actual function declaration <span class="t-v">(1)</span> becomes visible.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> pointer to the null-terminated wide string to be analyzed </td> +</tr> <tr class="t-par"> <td> ch </td> <td> - </td> <td> wide character to search for </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Pointer to the found character in <code>str</code>, or a null pointer if no such character is found.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <wchar.h> + +int main(void) +{ + wchar_t arr[] = L"白猫 黒猫 кошки"; + wchar_t *cat = wcsrchr(arr, L'猫'); + wchar_t *dog = wcsrchr(arr, L'犬'); + + setlocale(LC_ALL, "en_US.utf8"); + + cat ? printf("The character 猫 found at position %td\n", cat - arr) + : puts("The character 猫 not found"); + + dog ? printf("The character 犬 found at position %td\n", dog - arr) + : puts("The character 犬 not found"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">The character 猫 found at position 4 +The character 犬 not found</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.31.4.6.4 The wcsrchr function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.29.4.5.4 The wcsrchr function (p: 318) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.4.5.4 The wcsrchr function (p: 436) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.5.4 The wcsrchr function (p: 382) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="wcschr" title="c/string/wide/wcschr"> <span class="t-lines"><span>wcschr</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> finds the first occurrence of a wide character in a wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcspbrk" title="c/string/wide/wcspbrk"> <span class="t-lines"><span>wcspbrk</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> finds the first location of any wide character in one wide string, in another wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wcsrchr" title="cpp/string/wide/wcsrchr">C++ documentation</a></span> for <code>wcsrchr</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wcsrchr" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wcsrchr</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwcsspn.html b/devdocs/c/string%2Fwide%2Fwcsspn.html new file mode 100644 index 00000000..1fc9c8b2 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcsspn.html @@ -0,0 +1,37 @@ + <h1 id="firstHeading" class="firstHeading">wcsspn</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">size_t wcsspn( const wchar_t* dest, const wchar_t* src );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Returns the length of the maximum initial segment of the wide string pointed to by <code>dest</code>, that consists of only the characters found in wide string pointed to by <code>src</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the null-terminated wide string to be analyzed </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the null-terminated wide string that contains the characters to search for </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The length of the maximum initial segment that contains only characters from wide string pointed to by <code>src</code></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <wchar.h> + +int main(void) +{ + wchar_t dest[] = L"白猫 黑狗 甲虫"; + const wchar_t src[] = L" 狗猫 白黑 "; + const size_t len = wcsspn(dest, src); + dest[len] = L'\0'; /* terminates the segment to print it out */ + + setlocale(LC_ALL, "en_US.utf8"); + wprintf(L"The length of maximum initial segment is %td.\n" + L"The segment is \"%ls\".\n", len, dest); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">The length of maximum initial segment is 6. +The segment is "白猫 黑狗 ".</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.4.5.5 The wcsspn function (p: 436) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.5.5 The wcsspn function (p: 382) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="wcscspn" title="c/string/wide/wcscspn"> <span class="t-lines"><span>wcscspn</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> returns the length of the maximum initial segment that consists <br> of only the wide chars <i>not</i> found in another wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcspbrk" title="c/string/wide/wcspbrk"> <span class="t-lines"><span>wcspbrk</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> finds the first location of any wide character in one wide string, in another wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wcsspn" title="cpp/string/wide/wcsspn">C++ documentation</a></span> for <code>wcsspn</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wcsspn" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wcsspn</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwcsstr.html b/devdocs/c/string%2Fwide%2Fwcsstr.html new file mode 100644 index 00000000..d6afb5a4 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcsstr.html @@ -0,0 +1,50 @@ + <h1 id="firstHeading" class="firstHeading">wcsstr</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c95"> <td> <pre data-language="c">wchar_t *wcsstr( const wchar_t *dest, const wchar_t *src );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">/*QWchar_t*/ *wcsstr( /*QWchar_t*/ *dest, const wchar_t *src );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Finds the first occurrence of the wide string <code>src</code> in the wide string pointed to by <code>dest</code>. The terminating null characters are not compared.</div> <div class="t-li1"> +<span class="t-li">2)</span> Type-generic function equivalent to <span class="t-v">(1)</span>. Let <code>T</code> be an unqualified wide character object type. <ul> +<li> If <code>dest</code> is of type <code>const T*</code>, the return type is <code>const wchar_t*</code>. </li> +<li> Otherwise, if <code>dest</code> is of type <code>T*</code>, the return type is <code>wchar_t*</code>. </li> +<li> Otherwise, the behavior is undefined. </li> +</ul> If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if <code>(wcsstr)</code> or a function pointer is used), the actual function declaration <span class="t-v">(1)</span> becomes visible.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the null-terminated wide string to examine </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the null-terminated wide string to search for </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Pointer to the first character of the found substring in <code>dest</code>, or a null pointer if no such substring is found. If <code>src</code> points to an empty string, <code>dest</code> is returned.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <locale.h> +#include <wchar.h> + +int main(void) +{ + setlocale(LC_ALL, "ru_RU.UTF-8"); + + wchar_t str[5][64] = { + L"Строка, где есть подстрока 'но'.", + L"Строка, где такой подстроки нет.", + L"Он здесь.", + L"Здесь он.", + L"Его нет." + }; + + for (size_t i = 0; i < 5; ++i) { + if (wcsstr(str[i], L"но")) { + wprintf(L"%ls\n", str[i]); + } + } +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Строка, где есть подстрока 'но'.</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.4.5.6 The wcsstr function (p: 437) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.5.6 The wcsstr function (p: 383) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="wcschr" title="c/string/wide/wcschr"> <span class="t-lines"><span>wcschr</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> finds the first occurrence of a wide character in a wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcsrchr" title="c/string/wide/wcsrchr"> <span class="t-lines"><span>wcsrchr</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> finds the last occurrence of a wide character in a wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wcsstr" title="cpp/string/wide/wcsstr">C++ documentation</a></span> for <code>wcsstr</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wcsstr" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wcsstr</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwcstof.html b/devdocs/c/string%2Fwide%2Fwcstof.html new file mode 100644 index 00000000..30bf2d82 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcstof.html @@ -0,0 +1,77 @@ + <h1 id="firstHeading" class="firstHeading">wcstof, wcstod, wcstold</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">float wcstof( const wchar_t * restrict str, wchar_t ** restrict str_end );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td><pre data-language="c">double wcstod( const wchar_t * str, wchar_t ** str_end );</pre></td> <td class="t-dcl-nopad"> </td> <td> +<span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> +</td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">double wcstod( const wchar_t * restrict str, wchar_t ** restrict str_end );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long double wcstold( const wchar_t * restrict str, wchar_t ** restrict str_end );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Interprets a floating point value in a wide string pointed to by <code>str</code>.</p> +<p>Function discards any whitespace characters (as determined by <code><a href="iswspace" title="c/string/wide/iswspace">iswspace</a></code>) until first non-whitespace character is found. Then it takes as many characters as possible to form a valid floating-point representation and converts them to a floating-point value. The valid floating-point value can be one of the following:</p> +<ul> +<li>decimal floating-point expression. It consists of the following parts: </li> +<ul> +<li> <span class="t-mark">(optional)</span> plus or minus sign </li> +<li> nonempty sequence of decimal digits optionally containing decimal-point character (as determined by the current C <a href="../../locale/setlocale" title="c/locale/setlocale">locale</a>) (defines significand) </li> +<li> <span class="t-mark">(optional)</span> <code>e</code> or <code>E</code> followed with optional minus or plus sign and nonempty sequence of decimal digits (defines exponent to base 10) </li> +</ul> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <ul> +<li>hexadecimal floating-point expression. It consists of the following parts: </li> +<ul> +<li> <span class="t-mark">(optional)</span> plus or minus sign </li> +<li> <code>0x</code> or <code>0X</code> </li> +<li> nonempty sequence of hexadecimal digits optionally containing a decimal-point character (as determined by the current C <a href="../../locale/setlocale" title="c/locale/setlocale">locale</a>) (defines significand) </li> +<li> <span class="t-mark">(optional)</span> <code>p</code> or <code>P</code> followed with optional minus or plus sign and nonempty sequence of decimal digits (defines exponent to base 2) </li> +</ul> +<li> infinity expression. It consists of the following parts: </li> +<ul> +<li> <span class="t-mark">(optional)</span> plus or minus sign </li> +<li> <code>INF</code> or <code>INFINITY</code> ignoring case </li> +</ul> +<li> not-a-number expression. It consists of the following parts: </li> +<ul> +<li> <span class="t-mark">(optional)</span> plus or minus sign </li> +<li> <code>NAN</code> or <code>NAN(</code><i>char_sequence</i><code>)</code> ignoring case of the <code>NAN</code> part. <i>char_sequence</i> can only contain digits, Latin letters, and underscores. The result is a quiet NaN floating-point value. </li> +</ul> +</ul> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <ul><li> any other expression that may be accepted by the currently installed C <a href="../../locale/setlocale" title="c/locale/setlocale">locale</a> </li></ul> <p>The functions sets the pointer pointed to by <code>str_end</code> to point to the wide character past the last character interpreted. If <code>str_end</code> is a null pointer, it is ignored.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> pointer to the null-terminated wide string to be interpreted </td> +</tr> <tr class="t-par"> <td> str_end </td> <td> - </td> <td> pointer to a pointer to a wide character. </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Floating point value corresponding to the contents of <code>str</code> on success. If the converted value falls out of range of corresponding return type, range error occurs and <code><a href="../../numeric/math/huge_val" title="c/numeric/math/HUGE VAL">HUGE_VAL</a></code>, <code><a href="../../numeric/math/huge_val" title="c/numeric/math/HUGE VAL">HUGE_VALF</a></code> or <code><a href="../../numeric/math/huge_val" title="c/numeric/math/HUGE VAL">HUGE_VALL</a></code> is returned. If no conversion can be performed, <code>0</code> is returned.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <errno.h> +#include <wchar.h> + +int main(void) +{ + const wchar_t *p = L"111.11 -2.22 0X1.BC70A3D70A3D7P+6 1.18973e+4932zzz"; + printf("Parsing L\"%ls\":\n", p); + wchar_t *end; + for (double f = wcstod(p, &end); p != end; f = wcstod(p, &end)) + { + printf("'%.*ls' -> ", (int)(end-p), p); + p = end; + if (errno == ERANGE){ + printf("range error, got "); + errno = 0; + } + printf("%f\n", f); + } +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Parsing L"111.11 -2.22 0X1.BC70A3D70A3D7P+6 1.18973e+4932zzz": +'111.11' -> 111.110000 +' -2.22' -> -2.220000 +' 0X1.BC70A3D70A3D7P+6' -> 111.110000 +' 1.18973e+4932' -> range error, got inf</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.4.1.1 The wcstod, wcstof, and wcstold functions (p: 426-428) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.1.1 The wcstod, wcstof, and wcstold functions (p: 372-374) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/strtof" title="c/string/byte/strtof"> <span class="t-lines"><span>strtof</span><span>strtod</span><span>strtold</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a byte string to a floating point value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wcstof" title="cpp/string/wide/wcstof">C++ documentation</a></span> for <code>wcstof, wcstod, wcstold</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wcstof" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wcstof</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwcstoimax.html b/devdocs/c/string%2Fwide%2Fwcstoimax.html new file mode 100644 index 00000000..f5e07d38 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcstoimax.html @@ -0,0 +1,69 @@ + <h1 id="firstHeading" class="firstHeading">wcstoimax, wcstoumax</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><inttypes.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">intmax_t wcstoimax( const wchar_t *restrict nptr, + wchar_t **restrict endptr, int base );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">uintmax_t wcstoumax( const wchar_t *restrict nptr, + wchar_t **restrict endptr, int base );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Interprets an unsigned integer value in a wide string pointed to by <code>nptr</code>.</p> +<p>Discards any whitespace characters (as identified by calling <a href="iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a>) until the first non-whitespace character is found, then takes as many characters as possible to form a valid <i>base-n</i> (where n=<code>base</code>) unsigned integer number representation and converts them to an integer value. The valid unsigned integer value consists of the following parts:</p> +<ul> +<li> <span class="t-mark">(optional)</span> plus or minus sign </li> +<li> <span class="t-mark">(optional)</span> prefix (<code>0</code>) indicating octal base (applies only when the base is <code>8</code> or <code>0</code>) </li> +<li> <span class="t-mark">(optional)</span> prefix (<code>0x</code> or <code>0X</code>) indicating hexadecimal base (applies only when the base is <code>16</code> or <code>0</code>) </li> +<li> a sequence of digits </li> +</ul> <p>The set of valid values for base is <code>{0,2,3,...,36}.</code> The set of valid digits for base-<code>2</code> integers is <code>{0,1},</code> for base-<code>3</code> integers is <code>{0,1,2},</code> and so on. For bases larger than <code>10</code>, valid digits include alphabetic characters, starting from <code>Aa</code> for base-<code>11</code> integer, to <code>Zz</code> for base-<code>36</code> integer. The case of the characters is ignored.</p> +<p>Additional numeric formats may be accepted by the currently installed C <a href="../../locale/setlocale" title="c/locale/setlocale">locale</a>.</p> +<p>If the value of <code>base</code> is <code>0</code>, the numeric base is auto-detected: if the prefix is <code>0</code>, the base is octal, if the prefix is <code>0x</code> or <code>0X</code>, the base is hexadecimal, otherwise the base is decimal.</p> +<p>If the minus sign was part of the input sequence, the numeric value calculated from the sequence of digits is negated as if by <a href="../../language/operator_arithmetic#Unary_arithmetic" title="c/language/operator arithmetic">unary minus</a> in the result type, which applies unsigned integer wraparound rules.</p> +<p>The functions sets the pointer pointed to by <code>endptr</code> to point to the wide character past the last character interpreted. If <code>endptr</code> is a null pointer, it is ignored.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> nptr </td> <td> - </td> <td> pointer to the null-terminated wide string to be interpreted </td> +</tr> <tr class="t-par"> <td> endptr </td> <td> - </td> <td> pointer to a pointer to a wide character. </td> +</tr> <tr class="t-par"> <td> base </td> <td> - </td> <td> <i>base</i> of the interpreted integer value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Integer value corresponding to the contents of <code>str</code> on success. If the converted value falls out of range of corresponding return type, range error occurs and <code><a href="../../types/integer" title="c/types/integer">INTMAX_MAX</a></code>, <code><a href="../../types/integer" title="c/types/integer">INTMAX_MIN</a></code>, <code><a href="../../types/integer" title="c/types/integer">UINTMAX_MAX</a></code>, or <code>0</code> is returned, as appropriate. If no conversion can be performed, <code>0</code> is returned.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <errno.h> +#include <inttypes.h> +#include <stdio.h> +#include <string.h> +#include <wchar.h> + +int main(void) +{ + wchar_t* endptr; + + wprintf(L"%ld\n", wcstoimax(L" -123junk", &endptr, 10)); /* base 10 */ + wprintf(L"%ld\n", wcstoimax(L"11111111", &endptr, 2)); /* base 2 */ + wprintf(L"%ld\n", wcstoimax(L"XyZ", &endptr, 36)); /* base 36 */ + wprintf(L"%ld\n", wcstoimax(L"010", &endptr, 0)); /* octal auto-detection */ + wprintf(L"%ld\n", wcstoimax(L"10", &endptr, 0)); /* decimal auto-detection */ + wprintf(L"%ld\n", wcstoimax(L"0x10", &endptr, 0)); /* hexadecimal auto-detection */ + + /* range error */ + /* LONG_MAX+1 --> LONG_MAX */ + errno = 0; + wprintf(L"%ld\n", wcstoimax(L"9223372036854775808", &endptr, 10)); + wprintf(L"%s\n", strerror(errno)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">-123 +255 +44027 +8 +10 +16 +9223372036854775807 +Numerical result out of range</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.8.2.4 The wcstoimax and wcstoumax functions (p: 220) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.8.2.4 The wcstoimax and wcstoumax functions (p: 201) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/strtoimax" title="c/string/byte/strtoimax"> <span class="t-lines"><span>strtoimax</span><span>strtoumax</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a byte string to <code><a href="../../types/integer" title="c/types/integer">intmax_t</a></code> or <code><a href="../../types/integer" title="c/types/integer">uintmax_t</a></code> <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcstol" title="c/string/wide/wcstol"> <span class="t-lines"><span>wcstol</span><span>wcstoll</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a wide string to an integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcstoul" title="c/string/wide/wcstoul"> <span class="t-lines"><span>wcstoul</span><span>wcstoull</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a wide string to an unsigned integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wcstoimax" title="cpp/string/wide/wcstoimax">C++ documentation</a></span> for <code>wcstoimax, wcstoumax</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wcstoimax" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wcstoimax</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwcstok.html b/devdocs/c/string%2Fwide%2Fwcstok.html new file mode 100644 index 00000000..fe2e5786 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcstok.html @@ -0,0 +1,80 @@ + <h1 id="firstHeading" class="firstHeading">wcstok, wcstok_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td> <pre data-language="c">wchar_t* wcstok( wchar_t* str, const wchar_t* delim, wchar_t **ptr );</pre> +</td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">wchar_t *wcstok(wchar_t * restrict str, const wchar_t * restrict delim, + wchar_t **restrict ptr);</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">wchar_t *wcstok_s( wchar_t *restrict str, rsize_t *restrict strmax, + const wchar_t *restrict delim, wchar_t **restrict ptr);</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Finds the next token in a null-terminated wide string pointed to by <code>str</code>. The separator characters are identified by null-terminated wide string pointed to by <code>delim</code>.</div> <div class="t-li1"> + This function is designed to be called multiples times to obtain successive tokens from the same string.</div> <ul> +<li> If <code>str <span class="sy3">!</span><span class="sy1">=</span> <a href="http://en.cppreference.com/w/c/types/NULL"><span class="kw103">NULL</span></a></code>, the call is treated as the first call to <code>wcstok</code> for this particular wide string. The function searches for the first wide character which is <i>not</i> contained in <code>delim</code>. </li> +<li> If no such wide character was found, there are no tokens in <code>str</code> at all, and the function returns a null pointer. </li> +<li> If such wide character was found, it is the <i>beginning of the token</i>. The function then searches from that point on for the first wide character that <i>is</i> contained in <code>delim</code>. </li> +<ul> +<li> If no such wide character was found, <code>str</code> has only one token, and future calls to <code>wcstok</code> will return a null pointer </li> +<li> If such wide character was found, it is <i>replaced</i> by the null wide character <code>L'\0'</code> and the parser state (typically a pointer to the following wide character) is stored in the user-provided location <code>*ptr</code>. </li> +</ul> +<li> The function then returns the pointer to the beginning of the token </li> +<li> If <code>str <span class="sy1">==</span> <a href="http://en.cppreference.com/w/c/types/NULL"><span class="kw103">NULL</span></a></code>, the call is treated as a subsequent call to <code>wcstok</code>: the function continues from where it left in the previous invocation with the same <code>*ptr</code>. The behavior is the same as if the pointer to the wide character that follows the last detected token is passed as <code>str</code>. </li> +</ul> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that on every step, writes the number of characters left to see in <code>str</code> into <code>*strmax</code>. Repeat calls (with null <code>str</code>) must pass both <code>strmax</code> and <code>ptr</code> with the values stored by the previous call. Also, the following errors are detected at runtime and call the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function, without storing anything in the object pointed to by <code>ptr</code> <dl> +<dd> +<ul> +<li> <code>strmax</code>, <code>delim</code>, or <code>ptr</code> is a null pointer </li> +<li> on a non-initial call (with null <code>str</code>), <code>*ptr</code> is a null pointer </li> +<li> on the first call, <code>*strmax</code> is zero or greater than <code>RSIZE_MAX/sizeof(wchar_t)</code> </li> +<li> search for the end of a token reaches the end of the source string (as measured by the initial value of <code>*strmax</code>)) without encountering the null terminator </li> +</ul> </dd> +<dd>As all bounds-checked functions, <code>wcstok_s</code> is only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <code>wchar.h</code>.</dd> +</dl> +</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> pointer to the null-terminated wide string to tokenize </td> +</tr> <tr class="t-par"> <td> delim </td> <td> - </td> <td> pointer to the null-terminated wide string identifying delimiters </td> +</tr> <tr class="t-par"> <td> ptr </td> <td> - </td> <td> pointer to an object of type <code>wchar_t*</code>, which is used by both <code>wcstok</code> and <code>wcstok_s</code> to store the internal state of the parser </td> +</tr> <tr class="t-par"> <td> strmax </td> <td> - </td> <td> pointer to an object which initially holds the size of <code>str</code>: wcstok_s stores the number of characters that remain to be examined </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Returns pointer to the beginning of the next token or null pointer if there are no more tokens.</p> +<h3 id="Note"> Note</h3> <p>This function is destructive: it writes the <code>L'\0'</code> characters in the elements of the string <code>str</code>. In particular, a wide string literal cannot be used as the first argument of <code>wcstok</code>.</p> +<p>Unlike <code><a href="../byte/strtok" title="c/string/byte/strtok">strtok</a></code>, <code>wcstok</code> does not update static storage: it stores the parser state in the user-provided location.</p> +<p>Unlike most other tokenizers, the delimiters in <code>wcstok</code> can be different for each subsequent token, and can even depend on the contents of the previous tokens.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <wchar.h> +#include <stdio.h> + +int main(void) +{ + wchar_t input[] = L"A bird came down the walk"; + printf("Parsing the input string '%ls'\n", input); + wchar_t *buffer; + wchar_t *token = wcstok(input, L" ", &buffer); + while(token) { + printf("%ls\n", token); + token = wcstok(NULL, L" ", &buffer); + } + + printf("Contents of the input string now: '"); + for(size_t n = 0; n < sizeof input / sizeof *input; ++n) + input[n] ? printf("%lc", input[n]) : printf("\\0"); + puts("'"); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Parsing the input string 'A bird came down the walk' +A +bird +came +down +the +walk +Contents of the input string now: 'A\0bird\0came\0down\0the\0walk\0'</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.29.4.5.7 The wcstok function (p: 437-438) </li> +<li> K.3.9.2.3.1 The wcstok_s function (p: 645-646) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.5.7 The wcstok function (p: 383-384) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/strtok" title="c/string/byte/strtok"> <span class="t-lines"><span>strtok</span><span>strtok_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> finds the next token in a byte string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wcstok" title="cpp/string/wide/wcstok">C++ documentation</a></span> for <code>wcstok</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wcstok" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wcstok</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwcstol.html b/devdocs/c/string%2Fwide%2Fwcstol.html new file mode 100644 index 00000000..d9da4632 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcstol.html @@ -0,0 +1,65 @@ + <h1 id="firstHeading" class="firstHeading">wcstol, wcstoll</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td><pre data-language="c">long wcstol( const wchar_t * str, wchar_t ** str_end, int base );</pre></td> <td class="t-dcl-nopad"> </td> <td> +<span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> +</td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long wcstol( const wchar_t * restrict str, wchar_t ** restrict str_end, + int base );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">long long wcstoll( const wchar_t * restrict str, wchar_t ** restrict str_end, + int base );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Interprets an integer value in a wide string pointed to by <code>str</code>.</p> +<p>Discards any whitespace characters (as identified by calling <a href="iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a>) until the first non-whitespace character is found, then takes as many characters as possible to form a valid <i>base-n</i> (where n=<code>base</code>) integer number representation and converts them to an integer value. The valid integer value consists of the following parts:</p> +<ul> +<li> <span class="t-mark">(optional)</span> plus or minus sign </li> +<li> <span class="t-mark">(optional)</span> prefix (<code>0</code>) indicating octal base (applies only when the base is <code>8</code> or <code>0</code>) </li> +<li> <span class="t-mark">(optional)</span> prefix (<code>0x</code> or <code>0X</code>) indicating hexadecimal base (applies only when the base is <code>16</code> or <code>0</code>) </li> +<li> a sequence of digits </li> +</ul> <p>The set of valid values for base is <code>{0,2,3,...,36}.</code> The set of valid digits for base-<code>2</code> integers is <code>{0,1},</code> for base-<code>3</code> integers is <code>{0,1,2},</code> and so on. For bases larger than <code>10</code>, valid digits include alphabetic characters, starting from <code>Aa</code> for base-<code>11</code> integer, to <code>Zz</code> for base-<code>36</code> integer. The case of the characters is ignored.</p> +<p>Additional numeric formats may be accepted by the currently installed C <a href="../../locale/setlocale" title="c/locale/setlocale">locale</a>.</p> +<p>If the value of <code>base</code> is <code>0</code>, the numeric base is auto-detected: if the prefix is <code>0</code>, the base is octal, if the prefix is <code>0x</code> or <code>0X</code>, the base is hexadecimal, otherwise the base is decimal.</p> +<p>If the minus sign was part of the input sequence, the numeric value calculated from the sequence of digits is negated as if by <a href="../../language/operator_arithmetic#Unary_arithmetic" title="c/language/operator arithmetic">unary minus</a> in the result type.</p> +<p>The functions sets the pointer pointed to by <code>str_end</code> to point to the wide character past the last character interpreted. If <code>str_end</code> is a null pointer, it is ignored.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> pointer to the null-terminated wide string to be interpreted </td> +</tr> <tr class="t-par"> <td> str_end </td> <td> - </td> <td> pointer to a pointer to wide character </td> +</tr> <tr class="t-par"> <td> base </td> <td> - </td> <td> <i>base</i> of the interpreted integer value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Integer value corresponding to the contents of <code>str</code> on success. If the converted value falls out of range of corresponding return type, range error occurs and <code><a href="../../types/limits" title="c/types/limits">LONG_MAX</a></code>, <code><a href="../../types/limits" title="c/types/limits">LONG_MIN</a></code>, <code><a href="../../types/limits" title="c/types/limits">LLONG_MAX</a></code> or <code><a href="../../types/limits" title="c/types/limits">LLONG_MIN</a></code> is returned. If no conversion can be performed, <code>0</code> is returned.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <errno.h> +#include <wchar.h> + +int main(void) +{ + const wchar_t *p = L"10 200000000000000000000000000000 30 -40"; + printf("Parsing L'%ls':\n", p); + wchar_t *end; + for (long i = wcstol(p, &end, 10); + p != end; + i = wcstol(p, &end, 10)) + { + printf("'%.*ls' -> ", (int)(end-p), p); + p = end; + if (errno == ERANGE){ + printf("range error, got "); + errno = 0; + } + printf("%ld\n", i); + } +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Parsing L'10 200000000000000000000000000000 30 -40': +'10' -> 10 +' 200000000000000000000000000000' -> range error, got 9223372036854775807 +' 30' -> 30 +' -40' -> -40</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.4.1.2 The wcstol, wcstoll, wcstoul, and wcstoull functions (p: 429-430) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.1.2 The wcstol, wcstoll, wcstoul, and wcstoull functions (p: 375-376) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/strtol" title="c/string/byte/strtol"> <span class="t-lines"><span>strtol</span><span>strtoll</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a byte string to an integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcstoul" title="c/string/wide/wcstoul"> <span class="t-lines"><span>wcstoul</span><span>wcstoull</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a wide string to an unsigned integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wcstol" title="cpp/string/wide/wcstol">C++ documentation</a></span> for <code>wcstol, wcstoll</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wcstol" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wcstol</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwcstoul.html b/devdocs/c/string%2Fwide%2Fwcstoul.html new file mode 100644 index 00000000..2740a717 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcstoul.html @@ -0,0 +1,65 @@ + <h1 id="firstHeading" class="firstHeading">wcstoul, wcstoull</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td><pre data-language="c">unsigned long wcstoul( const wchar_t* str, wchar_t** str_end, int base );</pre></td> <td class="t-dcl-nopad"> </td> <td> +<span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> +</td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">unsigned long wcstoul( const wchar_t * restrict str, + wchar_t ** restrict str_end, int base );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">unsigned long long wcstoull( const wchar_t * restrict str, + wchar_t ** restrict str_end, int base );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Interprets an unsigned integer value in a wide string pointed to by <code>str</code>.</p> +<p>Discards any whitespace characters (as identified by calling <a href="iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a>) until the first non-whitespace character is found, then takes as many characters as possible to form a valid <i>base-n</i> (where n=<code>base</code>) unsigned integer number representation and converts them to an integer value. The valid unsigned integer value consists of the following parts:</p> +<ul> +<li> <span class="t-mark">(optional)</span> plus or minus sign </li> +<li> <span class="t-mark">(optional)</span> prefix (<code>0</code>) indicating octal base (applies only when the base is <code>8</code> or <code>0</code>) </li> +<li> <span class="t-mark">(optional)</span> prefix (<code>0x</code> or <code>0X</code>) indicating hexadecimal base (applies only when the base is <code>16</code> or <code>0</code>) </li> +<li> a sequence of digits </li> +</ul> <p>The set of valid values for base is <code>{0,2,3,...,36}.</code> The set of valid digits for base-<code>2</code> integers is <code>{0,1},</code> for base-<code>3</code> integers is <code>{0,1,2},</code> and so on. For bases larger than <code>10</code>, valid digits include alphabetic characters, starting from <code>Aa</code> for base-<code>11</code> integer, to <code>Zz</code> for base-<code>36</code> integer. The case of the characters is ignored.</p> +<p>Additional numeric formats may be accepted by the currently installed C <a href="../../locale/setlocale" title="c/locale/setlocale">locale</a>.</p> +<p>If the value of <code>base</code> is <code>0</code>, the numeric base is auto-detected: if the prefix is <code>0</code>, the base is octal, if the prefix is <code>0x</code> or <code>0X</code>, the base is hexadecimal, otherwise the base is decimal.</p> +<p>If the minus sign was part of the input sequence, the numeric value calculated from the sequence of digits is negated as if by <a href="../../language/operator_arithmetic#Unary_arithmetic" title="c/language/operator arithmetic">unary minus</a> in the result type, which applies unsigned integer wraparound rules.</p> +<p>The functions sets the pointer pointed to by <code>str_end</code> to point to the wide character past the last character interpreted. If <code>str_end</code> is a null pointer, it is ignored.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> pointer to the null-terminated wide string to be interpreted </td> +</tr> <tr class="t-par"> <td> str_end </td> <td> - </td> <td> pointer to a pointer to a wide character. </td> +</tr> <tr class="t-par"> <td> base </td> <td> - </td> <td> <i>base</i> of the interpreted integer value </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Integer value corresponding to the contents of <code>str</code> on success. If the converted value falls out of range of corresponding return type, range error occurs and <code><a href="../../types/limits" title="c/types/limits">ULONG_MAX</a></code> or <code><a href="../../types/limits" title="c/types/limits">ULLONG_MAX</a></code> is returned. If no conversion can be performed, <code>0</code> is returned.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <errno.h> +#include <wchar.h> + +int main(void) +{ + const wchar_t *p = L"10 200000000000000000000000000000 30 40"; + printf("Parsing L'%ls':\n", p); + wchar_t *end; + for (unsigned long i = wcstoul(p, &end, 10); + p != end; + i = wcstoul(p, &end, 10)) + { + printf("'%.*ls' -> ", (int)(end-p), p); + p = end; + if (errno == ERANGE){ + printf("range error, got "); + errno = 0; + } + printf("%lu\n", i); + } +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Parsing '10 200000000000000000000000000000 30 40': +'10' -> 10 +' 200000000000000000000000000000' -> range error, got 18446744073709551615 +' 30' -> 30 +' 40' -> 40</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.4.1.2 The wcstol, wcstoll, wcstoul, and wcstoull functions (p: 429-430) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.1.2 The wcstol, wcstoll, wcstoul, and wcstoull functions (p: 375-376) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/strtoul" title="c/string/byte/strtoul"> <span class="t-lines"><span>strtoul</span><span> strtoull</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a byte string to an unsigned integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcstol" title="c/string/wide/wcstol"> <span class="t-lines"><span>wcstol</span><span>wcstoll</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a wide string to an integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wcstoul" title="cpp/string/wide/wcstoul">C++ documentation</a></span> for <code>wcstoul, wcstoull</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wcstoul" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wcstoul</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwcsxfrm.html b/devdocs/c/string%2Fwide%2Fwcsxfrm.html new file mode 100644 index 00000000..5ed66168 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwcsxfrm.html @@ -0,0 +1,59 @@ + <h1 id="firstHeading" class="firstHeading">wcsxfrm</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">size_t wcsxfrm( wchar_t* dest, const wchar_t* src, size_t count );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> <br><span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">size_t wcsxfrm( wchar_t* restrict dest, const wchar_t* restrict src, size_t count );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Transforms the null-terminated wide string pointed to by <code>src</code> into the implementation-defined form such that comparing two transformed strings with <code><a href="wcscmp" title="c/string/wide/wcscmp">wcscmp</a></code> gives the same result as comparing the original strings with <code><a href="wcscoll" title="c/string/wide/wcscoll">wcscoll</a></code>, in the current C locale.</p> +<p>The first <code>count</code> characters of the transformed string are written to destination, including the terminating null character, and the length of the full transformed string is returned, excluding the terminating null character.</p> +<p>If <code>count</code> is <code>0</code>, then <code>dest</code> is allowed to be a null pointer.</p> +<h3 id="Notes"> Notes</h3> <p>The correct length of the buffer that can receive the entire transformed string is <code><span class="nu0">1</span><span class="sy2">+</span>wcsxfrm<span class="br0">(</span><a href="http://en.cppreference.com/w/c/types/NULL"><span class="kw103">NULL</span></a>, src, <span class="nu0">0</span><span class="br0">)</span></code></p> +<p>This function is used when making multiple locale-dependent comparisons using the same wide string or set of wide strings, because it is more efficient to use <code>wcsxfrm</code> to transform all the strings just once, and subsequently compare the transformed wide strings with <code><a href="wcscmp" title="c/string/wide/wcscmp">wcscmp</a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the first element of a wide null-terminated string to write the transformed string to </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the null-terminated wide character string to transform </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> maximum number of characters to output </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The length of the transformed wide string, not including the terminating null-character.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <wchar.h> +#include <locale.h> + +int main(void) +{ + setlocale(LC_ALL, "sv_SE.utf8"); + + const wchar_t *in1 = L"\u00e5r"; + wchar_t out1[1+wcsxfrm(NULL, in1, 0)]; + wcsxfrm(out1, in1, sizeof out1/sizeof *out1); + + const wchar_t *in2 = L"\u00e4ngel"; + wchar_t out2[1+wcsxfrm(NULL, in2, 0)]; + wcsxfrm(out2, in2, sizeof out2/sizeof *out2); + + printf("In the Swedish locale: "); + if(wcscmp(out1, out2) < 0) + printf("%ls before %ls\n", in1, in2); + else + printf("%ls before %ls\n", in2, in1); + + printf("In lexicographical comparison: "); + if(wcscmp(in1, in2) < 0) + printf("%ls before %ls\n", in1, in2); + else + printf("%ls before %ls\n", in2, in1); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">In the Swedish locale: år before ängel +In lexicographical comparison: ängel before år</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.4.4.4 The wcsxfrm function (p: 434-435) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.4.4 The wcsxfrm function (p: 380-381) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/strcoll" title="c/string/byte/strcoll"> <span class="t-lines"><span>strcoll</span></span></a></div> </td> <td> compares two strings in accordance to the current locale <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcscoll" title="c/string/wide/wcscoll"> <span class="t-lines"><span>wcscoll</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> compares two wide strings in accordance to the current locale <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcscmp" title="c/string/wide/wcscmp"> <span class="t-lines"><span>wcscmp</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> compares two wide strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../byte/strxfrm" title="c/string/byte/strxfrm"> <span class="t-lines"><span>strxfrm</span></span></a></div> </td> <td> transform a string so that strcmp would produce the same result as strcoll <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wcsxfrm" title="cpp/string/wide/wcsxfrm">C++ documentation</a></span> for <code>wcsxfrm</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wcsxfrm" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wcsxfrm</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwctrans.html b/devdocs/c/string%2Fwide%2Fwctrans.html new file mode 100644 index 00000000..16a392f1 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwctrans.html @@ -0,0 +1,27 @@ + <h1 id="firstHeading" class="firstHeading">wctrans</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">wctrans_t wctrans( const char* str );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Constructs a value of type <code>wctrans_t</code> that describes a <code><a href="../../locale/lc_categories" title="c/locale/LC categories">LC_CTYPE</a></code> category of wide character mapping. It may be one of the standard mappings, or a locale-specific mapping, such as <code>"tojhira"</code> or <code>"tojkata"</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> C string holding the name of the desired mapping. <p>The following values of <code>str</code> are supported in all C locales:</p> +<table class="t-dsc-begin"> <tr class="t-dsc-hitem"> <th> Value of <code>str</code> </th> <th> Effect </th> +</tr> <tr class="t-dsc"> <td> <code>"toupper"</code> </td> <td> identifies the mapping used by <code><a href="towupper" title="c/string/wide/towupper">towupper</a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>"tolower"</code> </td> <td> identifies the mapping used by <code><a href="towlower" title="c/string/wide/towlower">towlower</a></code> </td> +</tr> </table> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>wctrans_t</code> object suitable for use with <code><a href="towctrans" title="c/string/wide/towctrans">towctrans</a></code> to map wide characters according to the named mapping of the current C locale or zero if <code>str</code> does not name a mapping supported by the current C locale.</p> +<h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.30.3.2.2 The wctrans function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.30.3.2.2 The wctrans function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.30.3.2.2 The wctrans function (p: 454) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.25.3.2,2 The wctrans function (p: 400) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="towctrans" title="c/string/wide/towctrans"> <span class="t-lines"><span>towctrans</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> performs character mapping according to the specified LC_CTYPE mapping category <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wctrans" title="cpp/string/wide/wctrans">C++ documentation</a></span> for <code>wctrans</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wctrans" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wctrans</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwctype.html b/devdocs/c/string%2Fwide%2Fwctype.html new file mode 100644 index 00000000..a0891b98 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwctype.html @@ -0,0 +1,36 @@ + <h1 id="firstHeading" class="firstHeading">wctype</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wctype.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">wctype_t wctype( const char* str );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Constructs a value of type <code>wctype_t</code> that describes a <code><a href="../../locale/lc_categories" title="c/locale/LC categories">LC_CTYPE</a></code> category of wide character classification. It may be one of the standard classification categories, or a locale-specific category, such as <code>"jkanji"</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> str </td> <td> - </td> <td> C string holding the name of the desired category </td> +</tr> +</table> <p>The following values of <code>str</code> are supported in all C locales:</p> +<table class="t-dsc-begin"> <tr class="t-dsc-hitem"> <th> value of <code>str</code> </th> <th> effect </th> +</tr> <tr class="t-dsc"> <td> <code>"alnum"</code> </td> <td> identifies the category used by <code><a href="iswalnum" title="c/string/wide/iswalnum">iswalnum</a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>"alpha"</code> </td> <td> identifies the category used by <code><a href="iswalpha" title="c/string/wide/iswalpha">iswalpha</a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>"blank"</code> </td> <td> identifies the category used by <code><a href="iswblank" title="c/string/wide/iswblank">iswblank</a></code> <span class="t-mark-rev t-since-c99">(C99)</span> </td> +</tr> <tr class="t-dsc"> <td> <code>"cntrl"</code> </td> <td> identifies the category used by <code><a href="iswcntrl" title="c/string/wide/iswcntrl">iswcntrl</a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>"digit"</code> </td> <td> identifies the category used by <code><a href="iswdigit" title="c/string/wide/iswdigit">iswdigit</a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>"graph"</code> </td> <td> identifies the category used by <code><a href="iswgraph" title="c/string/wide/iswgraph">iswgraph</a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>"lower"</code> </td> <td> identifies the category used by <code><a href="iswlower" title="c/string/wide/iswlower">iswlower</a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>"print"</code> </td> <td> identifies the category used by <code><a href="iswprint" title="c/string/wide/iswprint">iswprint</a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>"space"</code> </td> <td> identifies the category used by <code><a href="iswspace" title="c/string/wide/iswspace">iswspace</a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>"upper"</code> </td> <td> identifies the category used by <code><a href="iswupper" title="c/string/wide/iswupper">iswupper</a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>"xdigit"</code> </td> <td> identifies the category used by <code><a href="iswxdigit" title="c/string/wide/iswxdigit">iswxdigit</a></code> </td> +</tr> </table> <h3 id="Return_value"> Return value</h3> <p><code>wctype_t</code> object suitable for use with <code><a href="iswctype" title="c/string/wide/iswctype">iswctype</a></code> to classify wide characters according to the named category of the current C locale or zero if <code>str</code> does not name a category supported by the current C locale.</p> +<h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.30.2.2.2 The wctype function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.30.2.2.2 The wctype function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.30.2.2.2 The wctype function (p: 452) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.25.2.2.2 The wctype function (p: 398) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="iswctype" title="c/string/wide/iswctype"> <span class="t-lines"><span>iswctype</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> classifies a wide character according to the specified <code><a href="../../locale/lc_categories" title="c/locale/LC categories">LC_CTYPE</a></code> category <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wctype" title="cpp/string/wide/wctype">C++ documentation</a></span> for <code>wctype</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wctype" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wctype</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwmemchr.html b/devdocs/c/string%2Fwide%2Fwmemchr.html new file mode 100644 index 00000000..d2d9a2db --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwmemchr.html @@ -0,0 +1,51 @@ + <h1 id="firstHeading" class="firstHeading">wmemchr</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">wchar_t *wmemchr( const wchar_t *ptr, wchar_t ch, size_t count );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> <tr class="t-dcl"> <td> <pre data-language="c">/*QWchar_t*/ *wmemchr( /*Qwchar_t*/ *ptr, wchar_t ch, size_t count );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Locates the first occurrence of wide character <code>ch</code> in the initial <code>count</code> wide characters of the wide character array or integer array of compatible type, pointed to by <code>ptr</code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Type-generic function equivalent to <span class="t-v">(1)</span>. Let <code>T</code> be an unqualified wide character object type. <ul> +<li> If <code>ptr</code> is of type <code>const T*</code>, the return type is <code>const wchar_t*</code>. </li> +<li> Otherwise, if <code>ptr</code> is of type <code>T*</code>, the return type is <code>wchar_t*</code>. </li> +<li> Otherwise, the behavior is undefined. </li> +</ul> If a macro definition of each of these generic functions is suppressed to access an actual function (e.g. if <code>(wmemchr)</code> or a function pointer is used), the actual function declaration <span class="t-v">(1)</span> becomes visible.</div> <p>If <code>count</code> is zero, the function returns a null pointer.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ptr </td> <td> - </td> <td> pointer to the wide character array to be examined </td> +</tr> <tr class="t-par"> <td> ch </td> <td> - </td> <td> wide character to search for </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> number of wide characters to examine </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Pointer to the location of the wide character, or a null pointer if no such character is found.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <wchar.h> + +int main(void) +{ + wchar_t str[] = L"诺不轻信，故人不负我\0诺不轻许，故我不负人。"; + size_t sz = sizeof str / sizeof *str; + + wchar_t target = L'许'; + wchar_t* result = wmemchr(str, target, sz); + + if (result) + { + setlocale(LC_ALL, "en_US.utf8"); + printf("Found '%lc' at position %td\n",target, result - str); + } +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Found '许' at position 14</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.29.4.5.8 The wmemchr function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.29.4.5.8 The wmemchr function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.4.5.8 The wmemchr function (p: 438) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.5.8 The wmemchr function (p: 384) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/memchr" title="c/string/byte/memchr"> <span class="t-lines"><span>memchr</span></span></a></div> </td> <td> searches an array for the first occurrence of a character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcschr" title="c/string/wide/wcschr"> <span class="t-lines"><span>wcschr</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> finds the first occurrence of a wide character in a wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wmemchr" title="cpp/string/wide/wmemchr">C++ documentation</a></span> for <code>wmemchr</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wmemchr" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wmemchr</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwmemcmp.html b/devdocs/c/string%2Fwide%2Fwmemcmp.html new file mode 100644 index 00000000..656ec979 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwmemcmp.html @@ -0,0 +1,68 @@ + <h1 id="firstHeading" class="firstHeading">wmemcmp</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">int wmemcmp( const wchar_t* lhs, const wchar_t* rhs, size_t count );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Compares the first <code>count</code> wide characters of the wide character (or compatible integer type) arrays pointed to by <code>lhs</code> and <code>rhs</code>. The comparison is done lexicographically.</p> +<p>The sign of the result is the sign of the difference between the values of the first pair of wide characters that differ in the arrays being compared.</p> +<p>If <code>count</code> is zero, the function does nothing.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> lhs, rhs </td> <td> - </td> <td> pointers to the wide character arrays to compare </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> number of wide characters to examine </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Negative value if the value of the first differing wide character in <code>lhs</code> is less than the value of the corresponding wide character in <code>rhs</code>: <code>lhs</code> precedes <code>rhs</code> in lexicographical order.</p> +<p><code>0</code> if all <code>count</code> wide characters of <code>lhs</code> and <code>rhs</code> are equal.</p> +<p>Positive value if the value of the first differing wide character in <code>lhs</code> is greater than the value of the corresponding wide character in <code>rhs</code>: <code>rhs</code> precedes <code>lhs</code> in lexicographical order.</p> +<h3 id="Notes"> Notes</h3> <p>This function is not locale-sensitive and pays no attention to the values of the <code>wchar_t</code> objects it examines: nulls as well as invalid wide characters are compared too.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <wchar.h> + +void demo(const wchar_t* lhs, const wchar_t* rhs, size_t sz) +{ + for (size_t n = 0; n < sz; ++n) + putwchar(lhs[n]); + + int rc = wmemcmp(lhs, rhs, sz); + if (rc == 0) + wprintf(L" compares equal to "); + else if(rc < 0) + wprintf(L" precedes "); + else if(rc > 0) + wprintf(L" follows "); + + for (size_t n = 0; n < sz; ++n) + putwchar(rhs[n]); + wprintf(L" in lexicographical order\n"); +} + +int main(void) +{ + setlocale(LC_ALL, "en_US.utf8"); + + wchar_t a1[] = {L'α',L'β',L'γ'}; + wchar_t a2[] = {L'α',L'β',L'δ'}; + + size_t sz = sizeof a1 / sizeof *a1; + demo(a1, a2, sz); + demo(a2, a1, sz); + demo(a1, a1, sz); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">αβγ precedes αβδ in lexicographical order +αβδ follows αβγ in lexicographical order +αβγ compares equal to αβγ in lexicographical order</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.29.4.4.5 The wmemcmp function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.29.4.4.5 The wmemcmp function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.4.4.5 The wmemcmp function (p: 435) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.4.5 The wmemcmp function (p: 381) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="wcscmp" title="c/string/wide/wcscmp"> <span class="t-lines"><span>wcscmp</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> compares two wide strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../byte/memcmp" title="c/string/byte/memcmp"> <span class="t-lines"><span>memcmp</span></span></a></div> </td> <td> compares two buffers <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wcsncmp" title="c/string/wide/wcsncmp"> <span class="t-lines"><span>wcsncmp</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> compares a certain amount of characters from two wide strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wmemcmp" title="cpp/string/wide/wmemcmp">C++ documentation</a></span> for <code>wmemcmp</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wmemcmp" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wmemcmp</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwmemcpy.html b/devdocs/c/string%2Fwide%2Fwmemcpy.html new file mode 100644 index 00000000..6ab00226 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwmemcpy.html @@ -0,0 +1,69 @@ + <h1 id="firstHeading" class="firstHeading">wmemcpy, wmemcpy_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-since-c95 t-until-c99"> <td> <pre data-language="c">wchar_t* wmemcpy( wchar_t* dest, const wchar_t* src, size_t count );</pre> +</td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> <br><span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">wchar_t *wmemcpy(wchar_t *restrict dest, const wchar_t *restrict src, + size_t count );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t wmemcpy_s( wchar_t *restrict dest, rsize_t destsz, + const wchar_t *restrict src, rsize_t count );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Copies exactly <code>count</code> successive wide characters from the wide character array pointed to by <code>src</code> to the wide character array pointed to by <code>dest</code>. If the objects overlap, the behavior is undefined. If <code>count</code> is zero, the function does nothing.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that the following errors are detected at runtime and call the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> <code>src</code> or <code>dest</code> is a null pointer </li> +<li> <code>destsz</code> or <code>count</code> is greater than <code>RSIZE_MAX/sizeof(wchar_t)</code> </li> +<li> <code>count</code> is greater than <code>destsz</code> (overflow would occur) </li> +<li> overlap would occur between the source and the destination arrays </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>wmemcpy_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../wide" title="c/string/wide"><code><wchar.h></code></a>.</dd> +</dl> +</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the wide character array to copy to </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the wide character array to copy from </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> number of wide characters to copy </td> +</tr> <tr class="t-par"> <td> destsz </td> <td> - </td> <td> max number of wide characters to write (the size of the destination buffer) </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> returns a copy of <code>dest</code> +</div> <div class="t-li1"> +<span class="t-li">2)</span> returns zero on success, returns non-zero on error. Also, on error, fills the entire <code>dst</code> up to and not including <code>dst+dstsz</code> with null wide characters, <code>L'\0'</code> (unless <code>dest</code> is null or <code>destsz</code> is greater than <code>RSIZE_MAX/sizeof(wchar_t)</code>)</div> <h3 id="Notes"> Notes</h3> <p>This function's analog for byte strings is <code><a href="../byte/strncpy" title="c/string/byte/strncpy">strncpy</a></code>, not <code><a href="../byte/strcpy" title="c/string/byte/strcpy">strcpy</a></code>.</p> +<p>This function is not locale-sensitive and pays no attention to the values of the <code>wchar_t</code> objects it copies: nulls as well as invalid characters are copied too.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <wchar.h> +#include <locale.h> + +int main(void) +{ + wchar_t from1[] = L"नमस्ते"; + size_t sz1 = sizeof from1 / sizeof *from1; + wchar_t from2[] = L"Բարև"; + size_t sz2 = sizeof from2 / sizeof *from2; + wchar_t to[sz1 + sz2]; + wmemcpy(to, from1, sz1); // copy from1, along with its null terminator + wmemcpy(to + sz1, from2, sz2); // append from2, along with its null terminator + + setlocale(LC_ALL, "en_US.utf8"); + printf("Wide array contains: "); + for(size_t n = 0; n < sizeof to / sizeof *to; ++n) + if(to[n]) + printf("%lc", to[n]); + else + printf("\\0"); + printf("\n"); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Wide array contains: नमस्ते\0Բարև\0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.29.4.2.3 The wmemcpy function (p: 431) </li> +<li> K.3.9.2.1.3 The wmemcpy_s function (p: 641) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.2.3 The wmemcpy function (p: 377) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="wmemmove" title="c/string/wide/wmemmove"> <span class="t-lines"><span>wmemmove</span><span>wmemmove_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies a certain amount of wide characters between two, possibly overlapping, arrays <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../byte/strncpy" title="c/string/byte/strncpy"> <span class="t-lines"><span>strncpy</span><span>strncpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies a certain amount of characters from one string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wmemcpy" title="cpp/string/wide/wmemcpy">C++ documentation</a></span> for <code>wmemcpy</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wmemcpy" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wmemcpy</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwmemmove.html b/devdocs/c/string%2Fwide%2Fwmemmove.html new file mode 100644 index 00000000..5b6a969c --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwmemmove.html @@ -0,0 +1,66 @@ + <h1 id="firstHeading" class="firstHeading">wmemmove, wmemmove_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c95"> <td> <pre data-language="c">wchar_t* wmemmove( wchar_t* dest, const wchar_t* src, size_t count );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t wmemmove_s( wchar_t *dest, rsize_t destsz, + const wchar_t *src, rsize_t count);</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Copies exactly <code>count</code> successive wide characters from the wide character array pointed to by <code>src</code> to the wide character array pointed to by <code>dest</code>. If <code>count</code> is zero, the function does nothing. The arrays may overlap: copying takes place as if the wide characters were copied to a temporary wide character array and then copied from the temporary array to <code>dest</code>.</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that the following errors are detected at runtime and call the currently installed <a href="../../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <dl> +<dd> +<ul> +<li> <code>src</code> or <code>dest</code> is a null pointer </li> +<li> <code>destsz</code> or <code>count</code> is greater than <code>RSIZE_MAX / sizeof(wchar_t)</code> </li> +<li> <code>count</code> is greater than <code>destsz</code> (overflow would occur) </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>wmemcpy_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../wide" title="c/string/wide"><code><wchar.h></code></a>.</dd> +</dl> +</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the wide character array to copy to </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> pointer to the wide character array to copy from </td> +</tr> <tr class="t-par"> <td> destsz </td> <td> - </td> <td> max number of wide characters to write (the size of the destination buffer) </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> number of wide characters to copy </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> Returns a copy of <code>dest</code> +</div> <div class="t-li1"> +<span class="t-li">2)</span> Returns zero on success, returns non-zero on error. Also, on error, fills the entire <code>dst</code> up to and not including <code>dst+dstsz</code> with null wide characters, <code>L'\0'</code> (unless <code>dest</code> is null or <code>destsz</code> is greater than <code>RSIZE_MAX/sizeof(wchar_t)</code>)</div> <h3 id="Notes"> Notes</h3> <p>This function is not locale-sensitive and pays no attention to the values of the <code>wchar_t</code> objects it copies: nulls as well as invalid characters are copied too.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <wchar.h> + +int main(void) +{ + setlocale(LC_ALL, "en_US.utf8"); + + wchar_t str[] = L"αβγδεζηθικλμνξοπρστυφχψω"; + printf("%ls\n", str); + wmemmove(str + 4, str + 3, 3); // copy from [δεζ] to [εζη] + printf("%ls\n", str); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">αβγδεζηθικλμνξοπρστυφχψω +αβγδδεζθικλμνξοπρστυφχψω</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.29.4.2.4 The wmemmove function (p: TBD) </li> +<li> K.3.9.2.1.4 The wmemmove_s function (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.29.4.2.4 The wmemmove function (p: TBD) </li> +<li> K.3.9.2.1.4 The wmemmove_s function (p: TBD) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.29.4.2.4 The wmemmove function (p: 432) </li> +<li> K.3.9.2.1.4 The wmemmove_s function (p: 642) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.2.4 The wmemmove function (p: 378) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/memmove" title="c/string/byte/memmove"> <span class="t-lines"><span>memmove</span><span>memmove_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> moves one buffer to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wmemcpy" title="c/string/wide/wmemcpy"> <span class="t-lines"><span>wmemcpy</span><span>wmemcpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies a certain amount of wide characters between two non-overlapping arrays <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wmemmove" title="cpp/string/wide/wmemmove">C++ documentation</a></span> for <code>wmemmove</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wmemmove" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wmemmove</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide%2Fwmemset.html b/devdocs/c/string%2Fwide%2Fwmemset.html new file mode 100644 index 00000000..76e41a84 --- /dev/null +++ b/devdocs/c/string%2Fwide%2Fwmemset.html @@ -0,0 +1,45 @@ + <h1 id="firstHeading" class="firstHeading">wmemset</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td> <pre data-language="c">wchar_t* wmemset( wchar_t* dest, wchar_t ch, size_t count );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c95">(since C95)</span> </td> </tr> </table> <p>Copies the wide character <code>ch</code> into each of the first <code>count</code> wide characters of the wide character array (or integer array of compatible type) pointed to by <code>dest</code>.</p> +<p>If overflow occurs, the behavior is undefined.</p> +<p>If <code>count</code> is zero, the function does nothing.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> pointer to the wide character array to fill </td> +</tr> <tr class="t-par"> <td> ch </td> <td> - </td> <td> fill wide character </td> +</tr> <tr class="t-par"> <td> count </td> <td> - </td> <td> number of wide characters to fill </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Returns a copy of <code>dest</code></p> +<h3 id="Notes"> Notes</h3> <p>This function is not locale-sensitive and pays no attention to the values of the <code>wchar_t</code> objects it writes: nulls as well as invalid wide characters are written too.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <locale.h> +#include <stdio.h> +#include <wchar.h> + +int main(void) +{ + wchar_t ar[10] = L"1234567890"; // no trailing null in the array + wmemset(ar, L'\U0001f34c', 5); // replaces [12345] with the 🍌 bananas + wmemset(ar + 5, L'蕉', 5); // replaces [67890] with the 蕉 bananas + + setlocale(LC_ALL, "en_US.utf8"); + for (size_t n = 0; n < sizeof ar / sizeof *ar; ++n) + putwchar(ar[n]); + putwchar(L'\n'); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">🍌🍌🍌🍌🍌蕉蕉蕉蕉蕉</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul><li> 7.29.4.6.2 The wmemset function (p: TBD) </li></ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.29.4.6.2 The wmemset function (p: TBD) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.29.4.6.2 The wmemset function (p: 439) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.24.4.6.2 The wmemset function (p: 385) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../byte/memset" title="c/string/byte/memset"> <span class="t-lines"><span>memset</span><span>memset_explicit</span><span>memset_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> fills a buffer with a character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wmemcpy" title="c/string/wide/wmemcpy"> <span class="t-lines"><span>wmemcpy</span><span>wmemcpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies a certain amount of wide characters between two non-overlapping arrays <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide/wmemset" title="cpp/string/wide/wmemset">C++ documentation</a></span> for <code>wmemset</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide/wmemset" class="_attribution-link">https://en.cppreference.com/w/c/string/wide/wmemset</a> + </p> +</div> diff --git a/devdocs/c/string%2Fwide.html b/devdocs/c/string%2Fwide.html new file mode 100644 index 00000000..3367609f --- /dev/null +++ b/devdocs/c/string%2Fwide.html @@ -0,0 +1,231 @@ + <h1 id="firstHeading" class="firstHeading">Null-terminated wide strings</h1> <p>A null-terminated wide string is a sequence of valid wide characters, ending with a null-character.</p> +<h3 id="Functions"> Functions</h3> <table class="t-dsc-begin"> <tr> <td colspan="2"> <h5 id="Character_classification"> Character classification </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><wctype.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/iswalnum" title="c/string/wide/iswalnum"> <span class="t-lines"><span>iswalnum</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is alphanumeric <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/iswalpha" title="c/string/wide/iswalpha"> <span class="t-lines"><span>iswalpha</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is alphabetic <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/iswlower" title="c/string/wide/iswlower"> <span class="t-lines"><span>iswlower</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is an lowercase character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/iswupper" title="c/string/wide/iswupper"> <span class="t-lines"><span>iswupper</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is an uppercase character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/iswdigit" title="c/string/wide/iswdigit"> <span class="t-lines"><span>iswdigit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is a digit <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/iswxdigit" title="c/string/wide/iswxdigit"> <span class="t-lines"><span>iswxdigit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is a hexadecimal character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/iswcntrl" title="c/string/wide/iswcntrl"> <span class="t-lines"><span>iswcntrl</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is a control character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/iswgraph" title="c/string/wide/iswgraph"> <span class="t-lines"><span>iswgraph</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is a graphical character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/iswspace" title="c/string/wide/iswspace"> <span class="t-lines"><span>iswspace</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is a space character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/iswblank" title="c/string/wide/iswblank"> <span class="t-lines"><span>iswblank</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> checks if a wide character is a blank character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/iswprint" title="c/string/wide/iswprint"> <span class="t-lines"><span>iswprint</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is a printing character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/iswpunct" title="c/string/wide/iswpunct"> <span class="t-lines"><span>iswpunct</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> checks if a wide character is a punctuation character <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/iswctype" title="c/string/wide/iswctype"> <span class="t-lines"><span>iswctype</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> classifies a wide character according to the specified <code><a href="../locale/lc_categories" title="c/locale/LC categories">LC_CTYPE</a></code> category <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wctype" title="c/string/wide/wctype"> <span class="t-lines"><span>wctype</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> looks up a character classification category in the current C locale <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Character_manipulation"> Character manipulation </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><wctype.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/towlower" title="c/string/wide/towlower"> <span class="t-lines"><span>towlower</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> converts a wide character to lowercase <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/towupper" title="c/string/wide/towupper"> <span class="t-lines"><span>towupper</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> converts a wide character to uppercase <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/towctrans" title="c/string/wide/towctrans"> <span class="t-lines"><span>towctrans</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> performs character mapping according to the specified LC_CTYPE mapping category <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wctrans" title="c/string/wide/wctrans"> <span class="t-lines"><span>wctrans</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> looks up a character mapping category in the current C locale <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <table class="wikitable"> <tr> <th colspan="3"> ASCII values </th> <th rowspan="2"> characters </th> <th rowspan="2"> <p><a href="byte/iscntrl" title="c/string/byte/iscntrl"><code>iscntrl</code></a><br> <a href="wide/iswcntrl" title="c/string/wide/iswcntrl"><code>iswcntrl</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/isprint" title="c/string/byte/isprint"><code>isprint</code></a><br> <a href="wide/iswprint" title="c/string/wide/iswprint"><code>iswprint</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/isspace" title="c/string/byte/isspace"><code>isspace</code></a><br> <a href="wide/iswspace" title="c/string/wide/iswspace"><code>iswspace</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/isblank" title="c/string/byte/isblank"><code>isblank</code></a><br> <a href="wide/iswblank" title="c/string/wide/iswblank"><code>iswblank</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/isgraph" title="c/string/byte/isgraph"><code>isgraph</code></a><br> <a href="wide/iswgraph" title="c/string/wide/iswgraph"><code>iswgraph</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/ispunct" title="c/string/byte/ispunct"><code>ispunct</code></a> <br> <a href="wide/iswpunct" title="c/string/wide/iswpunct"><code>iswpunct</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/isalnum" title="c/string/byte/isalnum"><code>isalnum</code></a> <br> <a href="wide/iswalnum" title="c/string/wide/iswalnum"><code>iswalnum</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/isalpha" title="c/string/byte/isalpha"><code>isalpha</code></a> <br> <a href="wide/iswalpha" title="c/string/wide/iswalpha"><code>iswalpha</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/isupper" title="c/string/byte/isupper"><code>isupper</code></a><br> <a href="wide/iswupper" title="c/string/wide/iswupper"><code>iswupper</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/islower" title="c/string/byte/islower"><code>islower</code></a><br> <a href="wide/iswlower" title="c/string/wide/iswlower"><code>iswlower</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/isdigit" title="c/string/byte/isdigit"><code>isdigit</code></a><br> <a href="wide/iswdigit" title="c/string/wide/iswdigit"><code>iswdigit</code></a></p> +</th> <th rowspan="2"> <p><a href="byte/isxdigit" title="c/string/byte/isxdigit"><code>isxdigit</code></a><br> <a href="wide/iswxdigit" title="c/string/wide/iswxdigit"><code>iswxdigit</code></a></p> +</th> +</tr> <tr> <th> decimal </th> <th> hexadecimal </th> <th> octal </th> +</tr> <tr> <td> 0–8 </td> <td> <code>\x0</code>–<code>\x8</code> </td> <td> <code>\0</code>–<code>\10</code> </td> <td> control codes (<code>NUL</code>, etc.) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 9 </td> <td> <code>\x9</code> </td> <td> <code>\11</code> </td> <td> tab (<code>\t</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 10–13 </td> <td> <code>\xA</code>–<code>\xD</code> </td> <td> <code>\12</code>–<code>\15</code> </td> <td> whitespaces (<code>\n</code>, <code>\v</code>, <code>\f</code>, <code>\r</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 14–31 </td> <td> <code>\xE</code>–<code>\x1F</code> </td> <td> <code>\16</code>–<code>\37</code> </td> <td> control codes </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 32 </td> <td> <code>\x20</code> </td> <td> <code>\40</code> </td> <td> space </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 33–47 </td> <td> <code>\x21</code>–<code>\x2F</code> </td> <td> <code>\41</code>–<code>\57</code> </td> <td> <code>!"#$%&'()*+,-./</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 48–57 </td> <td> <code>\x30</code>–<code>\x39</code> </td> <td> <code>\60</code>–<code>\71</code> </td> <td> <code>0123456789</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 58–64 </td> <td> <code>\x3A</code>–<code>\x40</code> </td> <td> <code>\72</code>–<code>\100</code> </td> <td> <code>:;<=>?@</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 65–70 </td> <td> <code>\x41</code>–<code>\x46</code> </td> <td> <code>\101</code>–<code>\106</code> </td> <td> <code>ABCDEF</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 71–90 </td> <td> <code>\x47</code>–<code>\x5A</code> </td> <td> <code>\107</code>–<code>\132</code> </td> <td> <code>GHIJKLMNOP</code><br><code>QRSTUVWXYZ</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 91–96 </td> <td> <code>\x5B</code>–<code>\x60</code> </td> <td> <code>\133</code>–<code>\140</code> </td> <td> <code>[\]^_`</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 97–102 </td> <td> <code>\x61</code>–<code>\x66</code> </td> <td> <code>\141</code>–<code>\146</code> </td> <td> <code>abcdef</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> +</tr> <tr> <td> 103–122 </td> <td> <code>\x67</code>–<code>\x7A</code> </td> <td> <code>\147</code>–<code>\172</code> </td> <td> <code>ghijklmnop</code><br><code>qrstuvwxyz</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 123–126 </td> <td> <code>\x7B</code>–<code>\x7E</code> </td> <td> <code>\172</code>–<code>\176</code> </td> <td> <code>{|}~</code> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> <tr> <td> 127 </td> <td> <code>\x7F</code> </td> <td> <code>\177</code> </td> <td> backspace character (<code>DEL</code>) </td> <td class="table-yes"> +<b><code>≠0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> <td class="table-no"> <b><code>0</code></b> </td> +</tr> +</table> <table class="t-dsc-begin"> <tr> <td colspan="2"> <h5 id="Conversions_to_numeric_formats"> Conversions to numeric formats </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><wchar.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wcstol" title="c/string/wide/wcstol"> <span class="t-lines"><span>wcstol</span><span>wcstoll</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a wide string to an integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wcstoul" title="c/string/wide/wcstoul"> <span class="t-lines"><span>wcstoul</span><span>wcstoull</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a wide string to an unsigned integer value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wcstof" title="c/string/wide/wcstof"> <span class="t-lines"><span>wcstof</span><span>wcstod</span><span>wcstold</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a wide string to a floating-point value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><inttypes.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wcstoimax" title="c/string/wide/wcstoimax"> <span class="t-lines"><span>wcstoimax</span><span>wcstoumax</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> converts a wide string to <code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw118">intmax_t</span></a></code> or <code><a href="http://en.cppreference.com/w/c/types/integer"><span class="kw132">uintmax_t</span></a></code> <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <table class="t-dsc-begin"> <tr> <td colspan="2"> <h5 id="String_manipulation"> String manipulation </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><wchar.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wcscpy" title="c/string/wide/wcscpy"> <span class="t-lines"><span>wcscpy</span><span>wcscpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies one wide string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wcsncpy" title="c/string/wide/wcsncpy"> <span class="t-lines"><span>wcsncpy</span><span>wcsncpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies a certain amount of wide characters from one string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wcscat" title="c/string/wide/wcscat"> <span class="t-lines"><span>wcscat</span><span>wcscat_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> appends a copy of one wide string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wcsncat" title="c/string/wide/wcsncat"> <span class="t-lines"><span>wcsncat</span><span>wcsncat_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> appends a certain amount of wide characters from one wide string to another <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wcsxfrm" title="c/string/wide/wcsxfrm"> <span class="t-lines"><span>wcsxfrm</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> transform a wide string so that wcscmp would produce the same result as wcscoll <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="String_examination"> String examination </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><wchar.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wcslen" title="c/string/wide/wcslen"> <span class="t-lines"><span>wcslen</span><span>wcsnlen_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> returns the length of a wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wcscmp" title="c/string/wide/wcscmp"> <span class="t-lines"><span>wcscmp</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> compares two wide strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wcsncmp" title="c/string/wide/wcsncmp"> <span class="t-lines"><span>wcsncmp</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> compares a certain amount of characters from two wide strings <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wcscoll" title="c/string/wide/wcscoll"> <span class="t-lines"><span>wcscoll</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> compares two wide strings in accordance to the current locale <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wcschr" title="c/string/wide/wcschr"> <span class="t-lines"><span>wcschr</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> finds the first occurrence of a wide character in a wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wcsrchr" title="c/string/wide/wcsrchr"> <span class="t-lines"><span>wcsrchr</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> finds the last occurrence of a wide character in a wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wcsspn" title="c/string/wide/wcsspn"> <span class="t-lines"><span>wcsspn</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> returns the length of the maximum initial segment that consists <br> of only the wide characters found in another wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wcscspn" title="c/string/wide/wcscspn"> <span class="t-lines"><span>wcscspn</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> returns the length of the maximum initial segment that consists <br> of only the wide chars <i>not</i> found in another wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wcspbrk" title="c/string/wide/wcspbrk"> <span class="t-lines"><span>wcspbrk</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> finds the first location of any wide character in one wide string, in another wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wcsstr" title="c/string/wide/wcsstr"> <span class="t-lines"><span>wcsstr</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> finds the first occurrence of a wide string within another wide string <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wcstok" title="c/string/wide/wcstok"> <span class="t-lines"><span>wcstok</span><span>wcstok_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> finds the next token in a wide string <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <table class="t-dsc-begin"> <tr> <td colspan="2"> <h5 id="Wide_character_array_manipulation"> Wide character array manipulation </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><wchar.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wmemcpy" title="c/string/wide/wmemcpy"> <span class="t-lines"><span>wmemcpy</span><span>wmemcpy_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies a certain amount of wide characters between two non-overlapping arrays <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wmemmove" title="c/string/wide/wmemmove"> <span class="t-lines"><span>wmemmove</span><span>wmemmove_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> copies a certain amount of wide characters between two, possibly overlapping, arrays <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wmemcmp" title="c/string/wide/wmemcmp"> <span class="t-lines"><span>wmemcmp</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> compares a certain amount of wide characters from two arrays <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wmemchr" title="c/string/wide/wmemchr"> <span class="t-lines"><span>wmemchr</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> finds the first occurrence of a wide character in a wide character array <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="wide/wmemset" title="c/string/wide/wmemset"> <span class="t-lines"><span>wmemset</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> copies the given wide character to every position in a wide character array <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <h3 id="Types"> Types</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stddef.h></code> </th> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdlib.h></code> </th> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><wchar.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>wchar_t</span></span></div> </td> <td> integer type that can hold any valid wide character <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><wchar.h></code> </th> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><wctype.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>wint_t</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> integer type that can hold any valid wide character and at least one more value <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><wctype.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>wctrans_t</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> scalar type that holds locale-specific character mapping <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>wctype_t</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> scalar type that holds locale-specific character classification <br> <span class="t-mark">(typedef)</span> </td> +</tr> </table> <h3 id="Macros"> Macros</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><wchar.h></code> </th> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><wctype.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>WEOF</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> a non-character value of type wint_t used to indicate errors <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><wchar.h></code> </th> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdint.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>WCHAR_MIN</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> the smallest valid value of wchar_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>WCHAR_MAX</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> the largest valid value of wchar_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.19 Common definitions <stddef.h> (p: 288) </li> +<li> 7.29 Extended multibyte and wide character utilities <wchar.h> (p: 402-446) </li> +<li> 7.30 Wide character classification and mapping utilities <wctype.h> (p: 447-454) </li> +<li> 7.31.16 Extended multibyte and wide character utilities <wchar.h> (p: 456) </li> +<li> 7.31.17 Wide character classification and mapping utilities <wctype.h> (p: 457) </li> +<li> K.3.3 Common definitions <stddef.h> (p: 585) </li> +<li> K.3.9 Extended multibyte and wide character utilities <wchar.h> (p: 627-651) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.17 Common definitions <stddef.h> (p: 254) </li> +<li> 7.24 Extended multibyte and wide character utilities <wchar.h> (p: 348-392) </li> +<li> 7.25 Wide character classification and mapping utilities <wctype.h> (p: 393-400) </li> +<li> 7.26.12 Extended multibyte and wide character utilities <wchar.h> (p: 402) </li> +<li> 7.26.13 Wide character classification and mapping utilities <wctype.h> (p: 402) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.1.5 Common definitions <stddef.h> </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string/wide" title="cpp/string/wide">C++ documentation</a></span> for <span class=""><span><code>Null</code>-terminated wide strings</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string/wide" class="_attribution-link">https://en.cppreference.com/w/c/string/wide</a> + </p> +</div> diff --git a/devdocs/c/string.html b/devdocs/c/string.html new file mode 100644 index 00000000..77b470d2 --- /dev/null +++ b/devdocs/c/string.html @@ -0,0 +1,10 @@ + <h1 id="firstHeading" class="firstHeading">Strings library</h1> <h3 id="Null-terminated_byte_string_management"> <a href="string/byte" title="c/string/byte"> Null-terminated byte string management</a> +</h3> <h3 id="Null-terminated_multibyte_string_management"> <a href="string/multibyte" title="c/string/multibyte"> Null-terminated multibyte string management</a> +</h3> <h3 id="Null-terminated_wide_string_management"> <a href="string/wide" title="c/string/wide"> Null-terminated wide string management</a> +</h3> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/string" title="cpp/string">C++ documentation</a></span> for <span class=""><span>Strings library</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/string" class="_attribution-link">https://en.cppreference.com/w/c/string</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fcall_once.html b/devdocs/c/thread%2Fcall_once.html new file mode 100644 index 00000000..c49a1c35 --- /dev/null +++ b/devdocs/c/thread%2Fcall_once.html @@ -0,0 +1,55 @@ + <h1 id="firstHeading" class="firstHeading">call_once, once_flag, ONCE_FLAG_INIT</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">void call_once( once_flag* flag, void (*func)(void) );</pre> +</td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">typedef /* unspecified */ once_flag</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">#define ONCE_FLAG_INIT /* unspecified */</pre> +</td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Calls function <code>func</code> exactly once, even if invoked from several threads. The completion of the function <code>func</code> synchronizes with all previous or subsequent calls to <code>call_once</code> with the same <code>flag</code> variable.</div> <div class="t-li1"> +<span class="t-li">2)</span> Complete object type capable of holding a flag used by <code>call_once</code>.</div> <div class="t-li1"> +<span class="t-li">3)</span> Expands to a value that can be used to initialize an object of type <code>once_flag</code>.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> flag </td> <td> - </td> <td> pointer to an object of type <code>call_once</code> that is used to ensure <code>func</code> is called only once </td> +</tr> <tr class="t-par"> <td> func </td> <td> - </td> <td> the function to execute only once </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="Notes"> Notes</h3> <p>The POSIX equivalent of this function is <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_once.html"><code>pthread_once</code></a>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <threads.h> + +void do_once(void) { + puts("called once"); +} + +static once_flag flag = ONCE_FLAG_INIT; +int func(void* data) +{ + call_once(&flag, do_once); +} + +int main(void) +{ + thrd_t t1, t2, t3, t4; + thrd_create(&t1, func, NULL); + thrd_create(&t2, func, NULL); + thrd_create(&t3, func, NULL); + thrd_create(&t4, func, NULL); + + thrd_join(t1, NULL); + thrd_join(t2, NULL); + thrd_join(t3, NULL); + thrd_join(t4, NULL); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">called once</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.26.2.1 The call_once function (p: 275) </li> +<li> 7.26.1/3 ONCE_FLAG_INIT (p: 274) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.26.2.1 The call_once function (p: 378) </li> +<li> 7.26.1/3 ONCE_FLAG_INIT (p: 376) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/call_once" title="cpp/thread/call once">C++ documentation</a></span> for <code>call_once</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/call_once" class="_attribution-link">https://en.cppreference.com/w/c/thread/call_once</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fcnd_broadcast.html b/devdocs/c/thread%2Fcnd_broadcast.html new file mode 100644 index 00000000..e007c0bc --- /dev/null +++ b/devdocs/c/thread%2Fcnd_broadcast.html @@ -0,0 +1,20 @@ + <h1 id="firstHeading" class="firstHeading">cnd_broadcast</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int cnd_broadcast( cnd_t *cond );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Unblocks all threads that are blocked on condition variable <code>cond</code> at the time of the call. If no threads are blocked on <code>cond</code>, the function does nothing and returns <code>thrd_success</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> cond </td> <td> - </td> <td> pointer to a condition variable </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code><a href="thrd_errors" title="c/thread/thrd errors">thrd_success</a></code> if successful, <code><a href="thrd_errors" title="c/thread/thrd errors">thrd_error</a></code> otherwise.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.3.1 The cnd_broadcast function (p: 275-276) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.3.1 The cnd_broadcast function (p: 378) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="cnd_signal" title="c/thread/cnd signal"> <span class="t-lines"><span>cnd_signal</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> unblocks one thread blocked on a condition variable <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/condition_variable/notify_all" title="cpp/thread/condition variable/notify all">C++ documentation</a></span> for <code>condition_variable::notify_all</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/condition_variable_any/notify_all" title="cpp/thread/condition variable any/notify all">C++ documentation</a></span> for <code>condition_variable_any::notify_all</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/cnd_broadcast" class="_attribution-link">https://en.cppreference.com/w/c/thread/cnd_broadcast</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fcnd_destroy.html b/devdocs/c/thread%2Fcnd_destroy.html new file mode 100644 index 00000000..91a9bfb1 --- /dev/null +++ b/devdocs/c/thread%2Fcnd_destroy.html @@ -0,0 +1,19 @@ + <h1 id="firstHeading" class="firstHeading">cnd_destroy</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">void cnd_destroy( cnd_t* cond );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Destroys the condition variable pointed to by <code>cond</code>.</p> +<p>If there are threads waiting on <code>cond</code>, the behavior is undefined.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> cond </td> <td> - </td> <td> pointer to the condition variable to destroy </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.3.2 The cnd_destroy function (p: 276) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.3.2 The cnd_destroy function (p: 378-379) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/condition_variable/%7Econdition_variable" title="cpp/thread/condition variable/~condition variable">C++ documentation</a></span> for <code>~condition_variable</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/condition_variable_any/%7Econdition_variable_any" title="cpp/thread/condition variable any/~condition variable any">C++ documentation</a></span> for <code>~condition_variable_any</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/cnd_destroy" class="_attribution-link">https://en.cppreference.com/w/c/thread/cnd_destroy</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fcnd_init.html b/devdocs/c/thread%2Fcnd_init.html new file mode 100644 index 00000000..c9527ac5 --- /dev/null +++ b/devdocs/c/thread%2Fcnd_init.html @@ -0,0 +1,18 @@ + <h1 id="firstHeading" class="firstHeading">cnd_init</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int cnd_init( cnd_t* cond );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Initializes new condition variable. The object pointed to by <code>cond</code> will be set to value that identifies the condition variable.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> cond </td> <td> - </td> <td> pointer to a variable to store identifier of the condition variable to </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code><a href="thrd_errors" title="c/thread/thrd errors">thrd_success</a></code> if the condition variable was successfully created. Otherwise returns <code><a href="thrd_errors" title="c/thread/thrd errors">thrd_nomem</a></code> if there was insufficient amount of memory or <code>thrd_error</code> if another error occurred.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.3.3 The cnd_init function (p: 276) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.3.3 The cnd_init function (p: 379) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/condition_variable/condition_variable" title="cpp/thread/condition variable/condition variable">C++ documentation</a></span> for <code>condition_variable</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/condition_variable_any/condition_variable_any" title="cpp/thread/condition variable any/condition variable any">C++ documentation</a></span> for <code>condition_variable_any</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/cnd_init" class="_attribution-link">https://en.cppreference.com/w/c/thread/cnd_init</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fcnd_signal.html b/devdocs/c/thread%2Fcnd_signal.html new file mode 100644 index 00000000..37a894ce --- /dev/null +++ b/devdocs/c/thread%2Fcnd_signal.html @@ -0,0 +1,20 @@ + <h1 id="firstHeading" class="firstHeading">cnd_signal</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int cnd_signal( cnd_t *cond );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Unblocks one thread that currently waits on condition variable pointed to by <code>cond</code>. If no threads are blocked, does nothing and returns <code>thrd_success</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> cond </td> <td> - </td> <td> pointer to a condition variable </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code><a href="thrd_errors" title="c/thread/thrd errors">thrd_success</a></code> if successful, <code><a href="thrd_errors" title="c/thread/thrd errors">thrd_error</a></code> otherwise.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.3.4 The cnd_signal function (p: 276) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.3.4 The cnd_signal function (p: 379) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="cnd_broadcast" title="c/thread/cnd broadcast"> <span class="t-lines"><span>cnd_broadcast</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> unblocks all threads blocked on a condition variable <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/condition_variable/notify_one" title="cpp/thread/condition variable/notify one">C++ documentation</a></span> for <code>condition_variable::notify_one</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/condition_variable_any/notify_one" title="cpp/thread/condition variable any/notify one">C++ documentation</a></span> for <code>condition_variable_any::notify_one</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/cnd_signal" class="_attribution-link">https://en.cppreference.com/w/c/thread/cnd_signal</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fcnd_timedwait.html b/devdocs/c/thread%2Fcnd_timedwait.html new file mode 100644 index 00000000..96b61762 --- /dev/null +++ b/devdocs/c/thread%2Fcnd_timedwait.html @@ -0,0 +1,24 @@ + <h1 id="firstHeading" class="firstHeading">cnd_timedwait</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int cnd_timedwait( cnd_t* restrict cond, mtx_t* restrict mutex, + const struct timespec* restrict time_point );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Atomically unlocks the mutex pointed to by <code>mutex</code> and blocks on the condition variable pointed to by <code>cond</code> until the thread is signalled by <code><a href="cnd_signal" title="c/thread/cnd signal">cnd_signal</a></code> or <code><a href="cnd_broadcast" title="c/thread/cnd broadcast">cnd_broadcast</a></code>, or until the <code>TIME_UTC</code> based time point pointed to by <code>time_point</code> has been reached, or until a spurious wake-up occurs. The mutex is locked again before the function returns.</p> +<p>The behavior is undefined if the mutex is not already locked by the calling thread.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> cond </td> <td> - </td> <td> pointer to the condition variable to block on </td> +</tr> <tr class="t-par"> <td> mutex </td> <td> - </td> <td> pointer to the mutex to unlock for the duration of the block </td> +</tr> <tr class="t-par"> <td> time_point </td> <td> - </td> <td> pointer to an object specifying timeout time to wait until </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code><a href="thrd_errors" title="c/thread/thrd errors">thrd_success</a></code> if successful, <code>thrd_timedout</code> if the timeout time has been reached before the mutex is locked, or <code><a href="thrd_errors" title="c/thread/thrd errors">thrd_error</a></code> if an error occurred.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.3.5 The cnd_timedwait function (p: 276-277) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.3.5 The cnd_timedwait function (p: 379-380) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="cnd_wait" title="c/thread/cnd wait"> <span class="t-lines"><span>cnd_wait</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> blocks on a condition variable <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/condition_variable/wait_until" title="cpp/thread/condition variable/wait until">C++ documentation</a></span> for <code>condition_variable::wait_until</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/condition_variable_any/wait_until" title="cpp/thread/condition variable any/wait until">C++ documentation</a></span> for <code>condition_variable_any::wait_until</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/cnd_timedwait" class="_attribution-link">https://en.cppreference.com/w/c/thread/cnd_timedwait</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fcnd_wait.html b/devdocs/c/thread%2Fcnd_wait.html new file mode 100644 index 00000000..6bbb3ede --- /dev/null +++ b/devdocs/c/thread%2Fcnd_wait.html @@ -0,0 +1,22 @@ + <h1 id="firstHeading" class="firstHeading">cnd_wait</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int cnd_wait( cnd_t* cond, mtx_t* mutex );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Atomically unlocks the mutex pointed to by <code>mutex</code> and blocks on the condition variable pointed to by <code>cond</code> until the thread is signalled by <code><a href="cnd_signal" title="c/thread/cnd signal">cnd_signal</a></code> or <code><a href="cnd_broadcast" title="c/thread/cnd broadcast">cnd_broadcast</a></code>, or until a spurious wake-up occurs. The mutex is locked again before the function returns.</p> +<p>The behavior is undefined if the mutex is not already locked by the calling thread.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> cond </td> <td> - </td> <td> pointer to the condition variable to block on </td> +</tr> <tr class="t-par"> <td> mutex </td> <td> - </td> <td> pointer to the mutex to unlock for the duration of the block </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code><a href="thrd_errors" title="c/thread/thrd errors">thrd_success</a></code> if successful, <code><a href="thrd_errors" title="c/thread/thrd errors">thrd_error</a></code> otherwise.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.3.6 The cnd_wait function (p: 277) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.3.6 The cnd_wait function (p: 380) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="cnd_timedwait" title="c/thread/cnd timedwait"> <span class="t-lines"><span>cnd_timedwait</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> blocks on a condition variable, with a timeout <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/condition_variable/wait" title="cpp/thread/condition variable/wait">C++ documentation</a></span> for <code>condition_variable::wait</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/condition_variable_any/wait" title="cpp/thread/condition variable any/wait">C++ documentation</a></span> for <code>condition_variable_any::wait</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/cnd_wait" class="_attribution-link">https://en.cppreference.com/w/c/thread/cnd_wait</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fmtx_destroy.html b/devdocs/c/thread%2Fmtx_destroy.html new file mode 100644 index 00000000..eb5bc679 --- /dev/null +++ b/devdocs/c/thread%2Fmtx_destroy.html @@ -0,0 +1,21 @@ + <h1 id="firstHeading" class="firstHeading">mtx_destroy</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">void mtx_destroy( mtx_t *mutex );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Destroys the mutex pointed to by <code>mutex</code>.</p> +<p>If there are threads waiting on <code>mutex</code>, the behavior is undefined.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> mutex </td> <td> - </td> <td> pointer to the mutex to destroy </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.4.1 The mtx_destroy function (p: 277) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.4.1 The mtx_destroy function (p: 380) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/mutex/%7Emutex" title="cpp/thread/mutex/~mutex">C++ documentation</a></span> for <code>~mutex</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/timed_mutex/%7Etimed_mutex" title="cpp/thread/timed mutex/~timed mutex">C++ documentation</a></span> for <code>~timed_mutex</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/recursive_mutex/%7Erecursive_mutex" title="cpp/thread/recursive mutex/~recursive mutex">C++ documentation</a></span> for <code>~recursive_mutex</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/recursive_timed_mutex/%7Erecursive_timed_mutex" title="cpp/thread/recursive timed mutex/~recursive timed mutex">C++ documentation</a></span> for <code>~recursive_timed_mutex</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/mtx_destroy" class="_attribution-link">https://en.cppreference.com/w/c/thread/mtx_destroy</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fmtx_init.html b/devdocs/c/thread%2Fmtx_init.html new file mode 100644 index 00000000..b500c70e --- /dev/null +++ b/devdocs/c/thread%2Fmtx_init.html @@ -0,0 +1,31 @@ + <h1 id="firstHeading" class="firstHeading">mtx_init</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int mtx_init( mtx_t* mutex, int type );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Creates a new mutex object with <code>type</code>. The object pointed to by <code>mutex</code> is set to an identifier of the newly created mutex.</p> +<p><code>type</code> must have one of the following values:</p> +<ul> +<li> +<code><a href="mtx_types" title="c/thread/mtx types">mtx_plain</a></code> - a simple, non-recursive mutex is created. </li> +<li> +<code><a href="mtx_types" title="c/thread/mtx types">mtx_timed</a></code> - a non-recursive mutex, that supports timeout, is created. </li> +<li> +<code><a href="http://en.cppreference.com/w/c/thread/mtx_types"><span class="kw1017">mtx_plain</span></a> <span class="sy3">|</span> <a href="http://en.cppreference.com/w/c/thread/mtx_types"><span class="kw1018">mtx_recursive</span></a></code> - a recursive mutex is created. </li> +<li> +<code><a href="http://en.cppreference.com/w/c/thread/mtx_types"><span class="kw1019">mtx_timed</span></a> <span class="sy3">|</span> <a href="http://en.cppreference.com/w/c/thread/mtx_types"><span class="kw1018">mtx_recursive</span></a></code> - a recursive mutex, that supports timeout, is created. </li> +</ul> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> mutex </td> <td> - </td> <td> pointer to the mutex to initialize </td> +</tr> <tr class="t-par"> <td> type </td> <td> - </td> <td> the type of the mutex </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code><a href="thrd_errors" title="c/thread/thrd errors">thrd_success</a></code> if successful, <code><a href="thrd_errors" title="c/thread/thrd errors">thrd_error</a></code> otherwise.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.4.2 The mtx_init function (p: 277-278) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.4.2 The mtx_init function (p: 381) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/mutex/mutex" title="cpp/thread/mutex/mutex">C++ documentation</a></span> for <code>mutex</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/timed_mutex/timed_mutex" title="cpp/thread/timed mutex/timed mutex">C++ documentation</a></span> for <code>timed_mutex</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/recursive_mutex/recursive_mutex" title="cpp/thread/recursive mutex/recursive mutex">C++ documentation</a></span> for <code>recursive_mutex</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/recursive_timed_mutex/recursive_timed_mutex" title="cpp/thread/recursive timed mutex/recursive timed mutex">C++ documentation</a></span> for <code>recursive_timed_mutex</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/mtx_init" class="_attribution-link">https://en.cppreference.com/w/c/thread/mtx_init</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fmtx_lock.html b/devdocs/c/thread%2Fmtx_lock.html new file mode 100644 index 00000000..88ff3dfe --- /dev/null +++ b/devdocs/c/thread%2Fmtx_lock.html @@ -0,0 +1,28 @@ + <h1 id="firstHeading" class="firstHeading">mtx_lock</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int mtx_lock( mtx_t* mutex );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Blocks the current thread until the mutex pointed to by <code>mutex</code> is locked.</p> +<p>The behavior is undefined if the current thread has already locked the mutex and the mutex is not recursive.</p> +<p>Prior calls to <code><a href="mtx_unlock" title="c/thread/mtx unlock">mtx_unlock</a></code> on the same mutex <i>synchronize-with</i> this operation, and all lock/unlock operations on any given mutex form a single total order (similar to the modification order of an atomic)</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> mutex </td> <td> - </td> <td> pointer to the mutex to lock </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code><a href="thrd_errors" title="c/thread/thrd errors">thrd_success</a></code> if successful, <code><a href="thrd_errors" title="c/thread/thrd errors">thrd_error</a></code> otherwise.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.4.3 The mtx_lock function (p: 278) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.4.3 The mtx_lock function (p: 381) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="mtx_timedlock" title="c/thread/mtx timedlock"> <span class="t-lines"><span>mtx_timedlock</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> blocks until locks a mutex or times out <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="mtx_trylock" title="c/thread/mtx trylock"> <span class="t-lines"><span>mtx_trylock</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> locks a mutex or returns without blocking if already locked <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="mtx_unlock" title="c/thread/mtx unlock"> <span class="t-lines"><span>mtx_unlock</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> unlocks a mutex <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/mutex/lock" title="cpp/thread/mutex/lock">C++ documentation</a></span> for <code>mutex::lock</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/timed_mutex/lock" title="cpp/thread/timed mutex/lock">C++ documentation</a></span> for <code>timed_mutex::lock</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/recursive_mutex/lock" title="cpp/thread/recursive mutex/lock">C++ documentation</a></span> for <code>recursive_mutex::lock</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/recursive_timed_mutex/lock" title="cpp/thread/recursive timed mutex/lock">C++ documentation</a></span> for <code>recursive_timed_mutex::lock</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/mtx_lock" class="_attribution-link">https://en.cppreference.com/w/c/thread/mtx_lock</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fmtx_timedlock.html b/devdocs/c/thread%2Fmtx_timedlock.html new file mode 100644 index 00000000..706bf816 --- /dev/null +++ b/devdocs/c/thread%2Fmtx_timedlock.html @@ -0,0 +1,35 @@ + <h1 id="firstHeading" class="firstHeading">mtx_timedlock</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int mtx_timedlock( mtx_t *restrict mutex, + const struct timespec *restrict time_point );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Blocks the current thread until the mutex pointed to by <code>mutex</code> is locked or until the <code>TIME_UTC</code> based absolute calendar time point pointed to by <code>time_point</code> has been reached.</p> +<p>Since this function takes an absolute time, if a duration is required, the calendar time point must be calculated manually.</p> +<p>The behavior is undefined if the current thread has already locked the mutex and the mutex is not recursive.</p> +<p>The behavior is undefined if the mutex does not support timeout.</p> +<p>Prior calls to <code><a href="mtx_unlock" title="c/thread/mtx unlock">mtx_unlock</a></code> on the same mutex <i>synchronize-with</i> this operation (if this operation succeeds), and all lock/unlock operations on any given mutex form a single total order (similar to the modification order of an atomic)</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> mutex </td> <td> - </td> <td> pointer to the mutex to lock </td> +</tr> <tr class="t-par"> <td> time_point </td> <td> - </td> <td> pointer to the absolute calendar time until which to wait for the timeout </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code><a href="thrd_errors" title="c/thread/thrd errors">thrd_success</a></code> if successful, <code>thrd_timedout</code> if the timeout time has been reached before the mutex is locked, <code><a href="thrd_errors" title="c/thread/thrd errors">thrd_error</a></code> if an error occurs.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.4.4 The mtx_timedlock function (p: 278) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.4.4 The mtx_timedlock function (p: 381-382) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../chrono/timespec" title="c/chrono/timespec"> <span class="t-lines"><span>timespec</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> time in seconds and nanoseconds <br><span class="t-mark">(struct)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="mtx_lock" title="c/thread/mtx lock"> <span class="t-lines"><span>mtx_lock</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> blocks until locks a mutex <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="mtx_trylock" title="c/thread/mtx trylock"> <span class="t-lines"><span>mtx_trylock</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> locks a mutex or returns without blocking if already locked <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="mtx_unlock" title="c/thread/mtx unlock"> <span class="t-lines"><span>mtx_unlock</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> unlocks a mutex <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/timed_mutex/try_lock_until" title="cpp/thread/timed mutex/try lock until">C++ documentation</a></span> for <code>timed_mutex::try_lock_until</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/recursive_timed_mutex/try_lock_until" title="cpp/thread/recursive timed mutex/try lock until">C++ documentation</a></span> for <code>recursive_timed_mutex::try_lock_until</code> </td> +</tr> </table> <h3 id="External_links"> External links</h3> <table> <tr> <td> +<a rel="nofollow" class="external text" href="https://www.gnu.org/software/libc/manual/html_node/ISO-C-Mutexes.html">GNU GCC Libc Manual: ISO-C-Mutexes</a> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/mtx_timedlock" class="_attribution-link">https://en.cppreference.com/w/c/thread/mtx_timedlock</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fmtx_trylock.html b/devdocs/c/thread%2Fmtx_trylock.html new file mode 100644 index 00000000..04c49311 --- /dev/null +++ b/devdocs/c/thread%2Fmtx_trylock.html @@ -0,0 +1,33 @@ + <h1 id="firstHeading" class="firstHeading">mtx_trylock</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int mtx_trylock( mtx_t *mutex );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Tries to lock the mutex pointed to by <code>mutex</code> without blocking. Returns immediately if the mutex is already locked.</p> +<p>Prior calls to <code><a href="mtx_unlock" title="c/thread/mtx unlock">mtx_unlock</a></code> on the same mutex <i>synchronize-with</i> this operation (if this operation succeeds), and all lock/unlock operations on any given mutex form a single total order (similar to the modification order of an atomic)</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> mutex </td> <td> - </td> <td> pointer to the mutex to lock </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code><a href="thrd_errors" title="c/thread/thrd errors">thrd_success</a></code> if successful, <code><a href="thrd_errors" title="c/thread/thrd errors">thrd_busy</a></code> if the mutex has already been locked or due to a spurious failure to acquire an available mutex, <code><a href="thrd_errors" title="c/thread/thrd errors">thrd_error</a></code> if an error occurs.</p> +<h3 id="Defect_reports"> Defect reports</h3> <p>The following behavior-changing defect reports were applied retroactively to previously published C standards.</p> +<table class="dsctable"> <tr> <th>DR </th> <th>Applied to </th> <th>Behavior as published </th> <th>Correct behavior </th> +</tr> <tr> <td> +<a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_470">DR 470</a> </td> <td>C11 </td> <td> +<code>mtx_trylock</code> was not allowed to fail spuriously </td> <td>allowed </td> +</tr> +</table> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.4.5 The mtx_trylock function (p: 278-279) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.4.5 The mtx_trylock function (p: 382) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="mtx_lock" title="c/thread/mtx lock"> <span class="t-lines"><span>mtx_lock</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> blocks until locks a mutex <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="mtx_timedlock" title="c/thread/mtx timedlock"> <span class="t-lines"><span>mtx_timedlock</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> blocks until locks a mutex or times out <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="mtx_unlock" title="c/thread/mtx unlock"> <span class="t-lines"><span>mtx_unlock</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> unlocks a mutex <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/mutex/try_lock" title="cpp/thread/mutex/try lock">C++ documentation</a></span> for <code>mutex::try_lock</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/timed_mutex/try_lock" title="cpp/thread/timed mutex/try lock">C++ documentation</a></span> for <code>timed_mutex::try_lock</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/recursive_mutex/try_lock" title="cpp/thread/recursive mutex/try lock">C++ documentation</a></span> for <code>recursive_mutex::try_lock</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/recursive_timed_mutex/try_lock" title="cpp/thread/recursive timed mutex/try lock">C++ documentation</a></span> for <code>recursive_timed_mutex::try_lock</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/mtx_trylock" class="_attribution-link">https://en.cppreference.com/w/c/thread/mtx_trylock</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fmtx_types.html b/devdocs/c/thread%2Fmtx_types.html new file mode 100644 index 00000000..ecd98707 --- /dev/null +++ b/devdocs/c/thread%2Fmtx_types.html @@ -0,0 +1,23 @@ + <h1 id="firstHeading" class="firstHeading">mtx_plain, mtx_recursive, mtx_timed</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">enum { + mtx_plain = /* unspecified */, + mtx_recursive = /* unspecified */, + mtx_timed = /* unspecified */ +};</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>When passed to <code><a href="mtx_init" title="c/thread/mtx init">mtx_init</a></code>, identifies the type of a mutex to create.</p> +<table class="t-dsc-begin"> <tr class="t-dsc-hitem"> <th> Constant </th> <th> Explanation </th> +</tr> <tr class="t-dsc"> <td> <code>mtx_plain</code> </td> <td> plain mutex </td> +</tr> <tr class="t-dsc"> <td> <code>mtx_recursive</code> </td> <td> recursive mutex </td> +</tr> <tr class="t-dsc"> <td> <code>mtx_timed</code> </td> <td> timed mutex </td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.1/5 mtx_plain, mtx_recursive, mtx_timed (p: 274-275) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.1/5 mtx_plain, mtx_recursive, mtx_timed (p: 377) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="mtx_init" title="c/thread/mtx init"> <span class="t-lines"><span>mtx_init</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> creates a mutex <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/mtx_types" class="_attribution-link">https://en.cppreference.com/w/c/thread/mtx_types</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fmtx_unlock.html b/devdocs/c/thread%2Fmtx_unlock.html new file mode 100644 index 00000000..14d4a14f --- /dev/null +++ b/devdocs/c/thread%2Fmtx_unlock.html @@ -0,0 +1,28 @@ + <h1 id="firstHeading" class="firstHeading">mtx_unlock</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int mtx_unlock( mtx_t *mutex );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Unlocks the mutex pointed to by <code>mutex</code>.</p> +<p>The behavior is undefined if the mutex is not locked by the calling thread.</p> +<p>This function <i>synchronizes-with</i> subsequent <code><a href="mtx_lock" title="c/thread/mtx lock">mtx_lock</a></code>, <code><a href="mtx_trylock" title="c/thread/mtx trylock">mtx_trylock</a></code>, or <code><a href="mtx_timedlock" title="c/thread/mtx timedlock">mtx_timedlock</a></code> on the same mutex. All lock/unlock operations on any given mutex form a single total order (similar to the modification order of an atomic).</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> mutex </td> <td> - </td> <td> pointer to the mutex to unlock </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code><a href="thrd_errors" title="c/thread/thrd errors">thrd_success</a></code> if successful, <code><a href="thrd_errors" title="c/thread/thrd errors">thrd_error</a></code> otherwise.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.4.6 The mtx_unlock function (p: 279) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.4.6 The mtx_unlock function (p: 382) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="mtx_lock" title="c/thread/mtx lock"> <span class="t-lines"><span>mtx_lock</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> blocks until locks a mutex <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="mtx_timedlock" title="c/thread/mtx timedlock"> <span class="t-lines"><span>mtx_timedlock</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> blocks until locks a mutex or times out <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="mtx_trylock" title="c/thread/mtx trylock"> <span class="t-lines"><span>mtx_trylock</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> locks a mutex or returns without blocking if already locked <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/mutex/unlock" title="cpp/thread/mutex/unlock">C++ documentation</a></span> for <code>mutex::unlock</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/timed_mutex/unlock" title="cpp/thread/timed mutex/unlock">C++ documentation</a></span> for <code>timed_mutex::unlock</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/recursive_mutex/unlock" title="cpp/thread/recursive mutex/unlock">C++ documentation</a></span> for <code>recursive_mutex::unlock</code> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/recursive_timed_mutex/unlock" title="cpp/thread/recursive timed mutex/unlock">C++ documentation</a></span> for <code>recursive_timed_mutex::unlock</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/mtx_unlock" class="_attribution-link">https://en.cppreference.com/w/c/thread/mtx_unlock</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fthrd_create.html b/devdocs/c/thread%2Fthrd_create.html new file mode 100644 index 00000000..f81cb8fa --- /dev/null +++ b/devdocs/c/thread%2Fthrd_create.html @@ -0,0 +1,29 @@ + <h1 id="firstHeading" class="firstHeading">thrd_create</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int thrd_create( thrd_t *thr, thrd_start_t func, void *arg );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Creates a new thread executing the function <code>func</code>. The function is invoked as <code>func(arg)</code>.</p> +<p>If successful, the object pointed to by <code>thr</code> is set to the identifier of the new thread.</p> +<p>The completion of this function <i>synchronizes-with</i> the beginning of the thread.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> thr </td> <td> - </td> <td> pointer to memory location to put the identifier of the new thread </td> +</tr> <tr class="t-par"> <td> func </td> <td> - </td> <td> function to execute </td> +</tr> <tr class="t-par"> <td> arg </td> <td> - </td> <td> argument to pass to the function </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code><a href="thrd_errors" title="c/thread/thrd errors">thrd_success</a></code> if the creation of the new thread was successful. Otherwise returns <code><a href="thrd_errors" title="c/thread/thrd errors">thrd_nomem</a></code> if there was insufficient amount of memory or <code><a href="thrd_errors" title="c/thread/thrd errors">thrd_error</a></code> if another error occurred.</p> +<h3 id="Notes"> Notes</h3> <p>The thread identifiers may be reused for new threads once the thread has finished and joined or detached.</p> +<p>The type <code><a href="../thread" title="c/thread">thrd_start_t</a></code> is a typedef of <code>int(*)(void*)</code>, which differs from the POSIX equivalent <code>void*(*)(void*)</code></p> +<p>All thread-specific storage values (see <code><a href="tss_create" title="c/thread/tss create">tss_create</a></code>) are initialized to <code><a href="../types/null" title="c/types/NULL">NULL</a></code>.</p> +<p>Return from the function <code>func</code> is equivalent to calling <code><a href="thrd_exit" title="c/thread/thrd exit">thrd_exit</a></code> with the argument equal to the return value of <code>func</code>.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.5.1 The thrd_create function (p: 279) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.5.1 The thrd_create function (p: 383) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="thrd_detach" title="c/thread/thrd detach"> <span class="t-lines"><span>thrd_detach</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> detaches a thread <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thrd_join" title="c/thread/thrd join"> <span class="t-lines"><span>thrd_join</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> blocks until a thread terminates <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/thread/thread" title="cpp/thread/thread/thread">C++ documentation</a></span> for <code>thread</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/thrd_create" class="_attribution-link">https://en.cppreference.com/w/c/thread/thrd_create</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fthrd_current.html b/devdocs/c/thread%2Fthrd_current.html new file mode 100644 index 00000000..3d5512bc --- /dev/null +++ b/devdocs/c/thread%2Fthrd_current.html @@ -0,0 +1,16 @@ + <h1 id="firstHeading" class="firstHeading">thrd_current</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">thrd_t thrd_current( void );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Returns the identifier of the calling thread.</p> +<h3 id="Parameters"> Parameters</h3> <p>(none)</p> +<h3 id="Return_value"> Return value</h3> <p>The identifier of the calling thread.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.5.2 The thrd_current function (p: 279) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.5.2 The thrd_current function (p: 383) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/get_id" title="cpp/thread/get id">C++ documentation</a></span> for <code>get_id</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/thrd_current" class="_attribution-link">https://en.cppreference.com/w/c/thread/thrd_current</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fthrd_detach.html b/devdocs/c/thread%2Fthrd_detach.html new file mode 100644 index 00000000..4708224e --- /dev/null +++ b/devdocs/c/thread%2Fthrd_detach.html @@ -0,0 +1,19 @@ + <h1 id="firstHeading" class="firstHeading">thrd_detach</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int thrd_detach( thrd_t thr );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Detaches the thread identified by <code>thr</code> from the current environment. The resources held by the thread will be freed automatically once the thread exits.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> thr </td> <td> - </td> <td> identifier of the thread to detach </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code><a href="thrd_errors" title="c/thread/thrd errors">thrd_success</a></code> if successful, <code><a href="thrd_errors" title="c/thread/thrd errors">thrd_error</a></code> otherwise.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.5.3 The thrd_detach function (p: 280) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.5.3 The thrd_detach function (p: 383-384) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="thrd_join" title="c/thread/thrd join"> <span class="t-lines"><span>thrd_join</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> blocks until a thread terminates <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/thread/detach" title="cpp/thread/thread/detach">C++ documentation</a></span> for <code>detach</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/thrd_detach" class="_attribution-link">https://en.cppreference.com/w/c/thread/thrd_detach</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fthrd_equal.html b/devdocs/c/thread%2Fthrd_equal.html new file mode 100644 index 00000000..e0d3c1f6 --- /dev/null +++ b/devdocs/c/thread%2Fthrd_equal.html @@ -0,0 +1,17 @@ + <h1 id="firstHeading" class="firstHeading">thrd_equal</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int thrd_equal( thrd_t lhs, thrd_t rhs );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Checks whether <code>lhs</code> and <code>rhs</code> refer to the same thread.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> lhs, rhs </td> <td> - </td> <td> threads to compare </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Non-zero value if <code>lhs</code> and <code>rhs</code> refer to the same value, <code>0</code> otherwise.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.5.4 The thrd_equal function (p: 280) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.5.4 The thrd_equal function (p: 384) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/thread/id/operator_cmp" title="cpp/thread/thread/id/operator cmp">C++ documentation</a></span> for <code>operator_cmp</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/thrd_equal" class="_attribution-link">https://en.cppreference.com/w/c/thread/thrd_equal</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fthrd_errors.html b/devdocs/c/thread%2Fthrd_errors.html new file mode 100644 index 00000000..afdded4d --- /dev/null +++ b/devdocs/c/thread%2Fthrd_errors.html @@ -0,0 +1,25 @@ + <h1 id="firstHeading" class="firstHeading">thrd_success, thrd_timedout, thrd_busy, thrd_nomem, thrd_error</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">enum { + thrd_success = /* unspecified */, + thrd_nomem = /* unspecified */, + thrd_timedout = /* unspecified */, + thrd_busy = /* unspecified */, + thrd_error = /* unspecified */ +};</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Identifiers for thread states and errors.</p> +<table class="t-dsc-begin"> <tr class="t-dsc-hitem"> <th> Constant </th> <th> Explanation </th> +</tr> <tr class="t-dsc"> <td> <code>thrd_success</code> </td> <td> indicates successful return value </td> +</tr> <tr class="t-dsc"> <td> <code>thrd_nomem</code> </td> <td> indicates unsuccessful return value due to out of memory condition </td> +</tr> <tr class="t-dsc"> <td> <code>thrd_timedout</code> </td> <td> indicates timed out return value </td> +</tr> <tr class="t-dsc"> <td> <code>thrd_busy</code> </td> <td> indicates unsuccessful return value due to resource temporary unavailable </td> +</tr> <tr class="t-dsc"> <td> <code>thrd_error</code> </td> <td> indicates unsuccessful return value </td> +</tr> </table> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.1/5 thrd_success, thrd_timedout, ... (p: 275) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.1/5 thrd_success, thrd_timedout, ... (p: 377) </li></ul> +</ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/thrd_errors" class="_attribution-link">https://en.cppreference.com/w/c/thread/thrd_errors</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fthrd_exit.html b/devdocs/c/thread%2Fthrd_exit.html new file mode 100644 index 00000000..03680641 --- /dev/null +++ b/devdocs/c/thread%2Fthrd_exit.html @@ -0,0 +1,25 @@ + <h1 id="firstHeading" class="firstHeading">thrd_exit</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11 t-until-c23"> <td><pre data-language="c">_Noreturn void thrd_exit( int res );</pre></td> <td class="t-dcl-nopad"> </td> <td> +<span class="t-mark-rev t-since-c11">(since C11)</span> <br><span class="t-mark-rev t-until-c23">(until C23)</span> +</td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">[[noreturn]] void thrd_exit( int res );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <p>First, for every thread-specific storage key which was created with a non-null destructor and for which the associated value is non-null (see <code><a href="tss_create" title="c/thread/tss create">tss_create</a></code>), <code>thrd_exit</code> sets the value associated with the key to <code><a href="http://en.cppreference.com/w/c/types/NULL"><span class="kw103">NULL</span></a></code> and then invokes the destructor with the previous value of the key. The order in which the destructors are invoked is unspecified.</p> +<p>If, after this, there remain keys with both non-null destructors and values (e.g. if a destructor executed <code><a href="tss_set" title="c/thread/tss set">tss_set</a></code>), the process is repeated up to <code><a href="tss_dtor_iterations" title="c/thread/TSS DTOR ITERATIONS">TSS_DTOR_ITERATIONS</a></code> times.</p> +<p>Finally, the <code>thrd_exit</code> function terminates execution of the calling thread and sets its result code to <code>res</code>.</p> +<p>If the last thread in the program is terminated with <code>thrd_exit</code>, the entire program terminates as if by calling <code><a href="../program/exit" title="c/program/exit">exit</a></code> with <code><a href="../program/exit_status" title="c/program/EXIT status">EXIT_SUCCESS</a></code> as the argument (so the functions registered by <code><a href="../program/atexit" title="c/program/atexit">atexit</a></code> are executed in the context of that last thread)</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> res </td> <td> - </td> <td> the result value to return </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.5.5 The thrd_exit function (p: 280) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.5.5 The thrd_exit function (p: 384) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="thrd_join" title="c/thread/thrd join"> <span class="t-lines"><span>thrd_join</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> blocks until a thread terminates <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thrd_detach" title="c/thread/thrd detach"> <span class="t-lines"><span>thrd_detach</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> detaches a thread <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/thrd_exit" class="_attribution-link">https://en.cppreference.com/w/c/thread/thrd_exit</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fthrd_join.html b/devdocs/c/thread%2Fthrd_join.html new file mode 100644 index 00000000..e4764b63 --- /dev/null +++ b/devdocs/c/thread%2Fthrd_join.html @@ -0,0 +1,25 @@ + <h1 id="firstHeading" class="firstHeading">thrd_join</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int thrd_join( thrd_t thr, int *res );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Blocks the current thread until the thread identified by <code>thr</code> finishes execution.</p> +<p>If <code>res</code> is not a null pointer, the result code of the thread is put to the location pointed to by <code>res</code>.</p> +<p>The termination of the thread <i>synchronizes-with</i> the completion of this function.</p> +<p>The behavior is undefined if the thread was previously detached or joined by another thread.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> thr </td> <td> - </td> <td> identifier of the thread to join </td> +</tr> <tr class="t-par"> <td> res </td> <td> - </td> <td> location to put the result code to </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code><a href="thrd_errors" title="c/thread/thrd errors">thrd_success</a></code> if successful, <code><a href="thrd_errors" title="c/thread/thrd errors">thrd_error</a></code> otherwise.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.5.6 The thrd_join function (p: 280-281) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.5.6 The thrd_join function (p: 384-385) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="thrd_detach" title="c/thread/thrd detach"> <span class="t-lines"><span>thrd_detach</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> detaches a thread <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thrd_exit" title="c/thread/thrd exit"> <span class="t-lines"><span>thrd_exit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> terminates the calling thread <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/thread/join" title="cpp/thread/thread/join">C++ documentation</a></span> for <code>join</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/thrd_join" class="_attribution-link">https://en.cppreference.com/w/c/thread/thrd_join</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fthrd_sleep.html b/devdocs/c/thread%2Fthrd_sleep.html new file mode 100644 index 00000000..2c7cd59a --- /dev/null +++ b/devdocs/c/thread%2Fthrd_sleep.html @@ -0,0 +1,36 @@ + <h1 id="firstHeading" class="firstHeading">thrd_sleep</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int thrd_sleep( const struct timespec* duration, + struct timespec* remaining );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Blocks the execution of the current thread for <i>at least</i> until the <code>TIME_UTC</code> based duration pointed to by <code>duration</code> has elapsed.</p> +<p>The sleep may resume earlier if a <code><a href="../program/signal" title="c/program/signal">signal</a></code> that is not ignored is received. In such case, if <code>remaining</code> is not <code><a href="../types/null" title="c/types/NULL">NULL</a></code>, the remaining time duration is stored into the object pointed to by <code>remaining</code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> duration </td> <td> - </td> <td> pointer to the duration to sleep for </td> +</tr> <tr class="t-par"> <td> remaining </td> <td> - </td> <td> pointer to the object to put the remaining time on interruption. May be <code><a href="../types/null" title="c/types/NULL">NULL</a></code>, in which case it is ignored </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>0</code> on successful sleep, <code>-1</code> if a signal occurred, other negative value if an error occurred.</p> +<h3 id="Notes"> Notes</h3> <p><code>duration</code> and <code>remaining</code> may point at the same object, which simplifies re-running the function after a signal.</p> +<p>The actual sleep time may be longer than requested because it is rounded up to the timer granularity and because of scheduling and context switching overhead.</p> +<p>The POSIX equivalent of this function is <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/nanosleep.html"><code>nanosleep</code></a>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <threads.h> +#include <time.h> +#include <stdio.h> + +int main(void) +{ + printf("Time: %s", ctime(&(time_t){time(NULL)})); + thrd_sleep(&(struct timespec){.tv_sec=1}, NULL); // sleep 1 sec + printf("Time: %s", ctime(&(time_t){time(NULL)})); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">Time: Mon Feb 2 16:18:41 2015 +Time: Mon Feb 2 16:18:42 2015</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.5.7 The thrd_sleep function (p: 281) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.5.7 The thrd_sleep function (p: 385) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="thrd_yield" title="c/thread/thrd yield"> <span class="t-lines"><span>thrd_yield</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> yields the current time slice <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/sleep_for" title="cpp/thread/sleep for">C++ documentation</a></span> for <code>sleep_for</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/thrd_sleep" class="_attribution-link">https://en.cppreference.com/w/c/thread/thrd_sleep</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fthrd_yield.html b/devdocs/c/thread%2Fthrd_yield.html new file mode 100644 index 00000000..7eb8bcad --- /dev/null +++ b/devdocs/c/thread%2Fthrd_yield.html @@ -0,0 +1,52 @@ + <h1 id="firstHeading" class="firstHeading">thrd_yield</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">void thrd_yield(void);</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Provides a hint to the implementation to reschedule the execution of threads, allowing other threads to run.</p> +<h3 id="Parameters"> Parameters</h3> <p>(none)</p> +<h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="Notes"> Notes</h3> <p>The exact behavior of this function depends on the implementation, in particular on the mechanics of the OS scheduler in use and the state of the system. For example, a first-in-first-out realtime scheduler (<code>SCHED_FIFO</code> in Linux) would suspend the current thread and put it on the back of the queue of the same-priority threads that are ready to run (and if there are no other threads at the same priority, <code>yield</code> has no effect).</p> +<p>The POSIX equivalent of this function is <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/sched_yield.html"><code>sched_yield</code></a>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <time.h> +#include <threads.h> + +// utility function: difference between timespecs in microseconds +double usdiff(struct timespec s, struct timespec e) +{ + double sdiff = difftime(e.tv_sec, s.tv_sec); + long nsdiff = e.tv_nsec - s.tv_nsec; + if(nsdiff < 0) return 1000000*(sdiff-1) + (1000000000L+nsdiff)/1000.0; + else return 1000000*(sdiff) + nsdiff/1000.0; +} + +// busy wait while yielding +void sleep_100us() +{ + struct timespec start, end; + timespec_get(&start, TIME_UTC); + do { + thrd_yield(); + timespec_get(&end, TIME_UTC); + } while(usdiff(start, end) < 100.0); +} + +int main() +{ + struct timespec start, end; + timespec_get(&start, TIME_UTC); + sleep_100us(); + timespec_get(&end, TIME_UTC); + printf("Waited for %.3f us\n", usdiff(start, end)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Waited for 100.344 us</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.5.8 The thrd_yield function (p: 281) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.5.8 The thrd_yield function (p: 385) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="thrd_sleep" title="c/thread/thrd sleep"> <span class="t-lines"><span>thrd_sleep</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> suspends execution of the calling thread for the given period of time <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread/yield" title="cpp/thread/yield">C++ documentation</a></span> for <code>yield</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/thrd_yield" class="_attribution-link">https://en.cppreference.com/w/c/thread/thrd_yield</a> + </p> +</div> diff --git a/devdocs/c/thread%2Fthread_local.html b/devdocs/c/thread%2Fthread_local.html new file mode 100644 index 00000000..7d760252 --- /dev/null +++ b/devdocs/c/thread%2Fthread_local.html @@ -0,0 +1,15 @@ + <h1 id="firstHeading" class="firstHeading">thread_local</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11 t-until-c23"> <td> <pre data-language="c">#define thread_local _Thread_local</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> <br><span class="t-mark-rev t-until-c23">(removed in C23)</span> </td> </tr> </table> <p>Convenience macro which can be used to specify that an object has <a href="../language/storage_duration" title="c/language/storage duration">thread-local storage duration</a>.</p> +<h3 id="Notes"> Notes</h3> <p>Since C23, <code>thread_local</code> is itself a keyword, which may also be a predefined macro, so <code><threads.h></code> no longer provides it.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.1/3 thread_local (p: 274) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.1/3 thread_local (p: 376) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/keyword/thread_local" title="cpp/keyword/thread local">C++ documentation</a></span> for <code>thread_local</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/thread_local" class="_attribution-link">https://en.cppreference.com/w/c/thread/thread_local</a> + </p> +</div> diff --git a/devdocs/c/thread%2Ftss_create.html b/devdocs/c/thread%2Ftss_create.html new file mode 100644 index 00000000..749b3ebd --- /dev/null +++ b/devdocs/c/thread%2Ftss_create.html @@ -0,0 +1,27 @@ + <h1 id="firstHeading" class="firstHeading">tss_create</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int tss_create( tss_t* tss_key, tss_dtor_t destructor );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Creates new thread-specific storage key and stores it in the object pointed to by <code>tss_key</code>. Although the same key value may be used by different threads, the values bound to the key by <code><a href="tss_set" title="c/thread/tss set">tss_set</a></code> are maintained on a per-thread basis and persist for the life of the calling thread.</p> +<p>The value <code><a href="../types/null" title="c/types/NULL">NULL</a></code> is associated with the newly created key in all existing threads, and upon thread creation, the values associated with all TSS keys is initialized to <code><a href="../types/null" title="c/types/NULL">NULL</a></code>.</p> +<p>If <code>destructor</code> is not a null pointer, then also associates the destructor which is called when the storage is released by <code><a href="thrd_exit" title="c/thread/thrd exit">thrd_exit</a></code> (but not by <code><a href="tss_delete" title="c/thread/tss delete">tss_delete</a></code> and not at program termination by <code><a href="../program/exit" title="c/program/exit">exit</a></code>).</p> +<p>A call to <code>tss_create</code> from within a thread-specific storage destructor results in undefined behavior.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> tss_key </td> <td> - </td> <td> pointer to memory location to store the new thread-specific storage key </td> +</tr> <tr class="t-par"> <td> destructor </td> <td> - </td> <td> pointer to a function to call at thread exit </td> +</tr> +</table> <h3 id="Notes"> Notes</h3> <p>The POSIX equivalent of this function is <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_key_create.html"><code>pthread_key_create</code></a>.</p> +<h3 id="Return_value"> Return value</h3> <p><code><a href="thrd_errors" title="c/thread/thrd errors">thrd_success</a></code> if successful, <code><a href="thrd_errors" title="c/thread/thrd errors">thrd_error</a></code> otherwise.</p> +<h3 id="Example"> Example</h3> <div class="c source-c"><pre data-language="c">int thread_func(void *arg) { + tss_t key; + if (thrd_success == tss_create(&key, free)) { + tss_set(key, malloc(4)); // stores a pointer on TSS + // ... + } +} // calls free() for the pointer stored on TSS</pre></div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.6.1 The tss_create function (p: 281-282) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.6.1 The tss_create function (p: 386) </li></ul> +</ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/tss_create" class="_attribution-link">https://en.cppreference.com/w/c/thread/tss_create</a> + </p> +</div> diff --git a/devdocs/c/thread%2Ftss_delete.html b/devdocs/c/thread%2Ftss_delete.html new file mode 100644 index 00000000..3540ac07 --- /dev/null +++ b/devdocs/c/thread%2Ftss_delete.html @@ -0,0 +1,21 @@ + <h1 id="firstHeading" class="firstHeading">tss_delete</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">void tss_delete( tss_t tss_id );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Destroys the thread-specific storage identified by <code>tss_id</code>.</p> +<p>The destructor, if one was registered by <code><a href="tss_create" title="c/thread/tss create">tss_create</a></code>, is not called (they are only called at thread exit, either by <code><a href="thrd_exit" title="c/thread/thrd exit">thrd_exit</a></code> or by returning from the thread function), it is the responsibility of the programmer to ensure that every thread that is aware of <code>tss_id</code> performed all necessary cleanup, before the call to <code>tss_delete</code> is made.</p> +<p>If <code>tss_delete</code> is called while another thread is executing destructors for <code>tss_id</code>, it's unspecified whether this changes the number of invocations to the associated destructor.</p> +<p>If <code>tss_delete</code> is called while the calling thread is executing destructors, then the destructor associated with <code>tss_id</code> will not be executed again on this thread.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> tss_id </td> <td> - </td> <td> thread-specific storage key previously returned by <code><a href="tss_create" title="c/thread/tss create">tss_create</a></code> and not yet deleted by <code>tss_delete</code> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>(none)</p> +<h3 id="Notes"> Notes</h3> <p>The POSIX equivalent of this function is <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_key_delete.html"><code>pthread_key_delete</code></a>.</p> +<p>The reason <code>tss_delete</code> never calls destructors is that the destructors (called at thread exit) are normally intended to be executed by the same thread that originally set the value (via <code><a href="tss_set" title="c/thread/tss set">tss_set</a></code>) that the destructor will be dealing with, and may even rely on the values of that or other thread-specific data as seen by that thread. The thread executing <code>tss_delete</code> has no access to other threads' TSS. Even if it were possible to call the destructor for each thread's own value associated with <code>tss_id</code>, <code>tss_delete</code> would have to synchronize with every thread if only to examine whether the value of this TSS in that thread is null (destructors are only called against non-null values).</p> +<h3 id="Example"> Example</h3> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.6.2 The tss_delete function (p: 282) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.6.2 The tss_delete function (p: 386) </li></ul> +</ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/tss_delete" class="_attribution-link">https://en.cppreference.com/w/c/thread/tss_delete</a> + </p> +</div> diff --git a/devdocs/c/thread%2Ftss_dtor_iterations.html b/devdocs/c/thread%2Ftss_dtor_iterations.html new file mode 100644 index 00000000..265b360d --- /dev/null +++ b/devdocs/c/thread%2Ftss_dtor_iterations.html @@ -0,0 +1,14 @@ + <h1 id="firstHeading" class="firstHeading">TSS_DTOR_ITERATIONS</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">#define TSS_DTOR_ITERATIONS /* unspecified */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Expands to a positive integral <a href="../language/constant_expression" title="c/language/constant expression">constant expression</a> defining the maximum number of times a destructor for thread-local storage pointer will be called by <code><a href="thrd_exit" title="c/thread/thrd exit">thrd_exit</a></code>.</p> +<p>This constant is equivalent to the POSIX <code>PTHREAD_DESTRUCTOR_ITERATIONS</code>.</p> +<h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.1/3 TSS_DTOR_ITERATIONS (p: 274) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.1/3 TSS_DTOR_ITERATIONS (p: 376) </li></ul> +</ul> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/TSS_DTOR_ITERATIONS" class="_attribution-link">https://en.cppreference.com/w/c/thread/TSS_DTOR_ITERATIONS</a> + </p> +</div> diff --git a/devdocs/c/thread%2Ftss_get.html b/devdocs/c/thread%2Ftss_get.html new file mode 100644 index 00000000..195f2ef1 --- /dev/null +++ b/devdocs/c/thread%2Ftss_get.html @@ -0,0 +1,20 @@ + <h1 id="firstHeading" class="firstHeading">tss_get</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">void *tss_get( tss_t tss_key );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Returns the value held in thread-specific storage for the current thread identified by <code>tss_key</code>. Different threads may get different values identified by the same key.</p> +<p>On thread startup (see <code><a href="thrd_create" title="c/thread/thrd create">thrd_create</a></code>), the values associated with all TSS keys are NULL. Different value may be placed in the thread-specific storage with <code><a href="tss_set" title="c/thread/tss set">tss_set</a></code>.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> tss_key </td> <td> - </td> <td> thread-specific storage key, obtained from <code><a href="tss_create" title="c/thread/tss create">tss_create</a></code> and not deleted by <code><a href="tss_delete" title="c/thread/tss delete">tss_delete</a></code> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>The value on success, <code><a href="../types/null" title="c/types/NULL">NULL</a></code> on failure.</p> +<h3 id="Notes"> Notes</h3> <p>The POSIX equivalent for this function is <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_getspecific.html"><code>pthread_getspecific</code></a>.</p> +<h3 id="Example"> Example</h3> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.6.3 The tss_get function (p: 282) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.6.3 The tss_get function (p: 386) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="tss_set" title="c/thread/tss set"> <span class="t-lines"><span>tss_set</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> write to thread-specific storage <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/tss_get" class="_attribution-link">https://en.cppreference.com/w/c/thread/tss_get</a> + </p> +</div> diff --git a/devdocs/c/thread%2Ftss_set.html b/devdocs/c/thread%2Ftss_set.html new file mode 100644 index 00000000..88b4629a --- /dev/null +++ b/devdocs/c/thread%2Ftss_set.html @@ -0,0 +1,29 @@ + <h1 id="firstHeading" class="firstHeading">tss_set</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><threads.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">int tss_set( tss_t tss_id, void *val );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p>Sets the value of the thread-specific storage identified by <code>tss_id</code> for the current thread to <code>val</code>. Different threads may set different values to the same key.</p> +<p>The destructor, if available, is not invoked.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> tss_id </td> <td> - </td> <td> thread-specific storage key, obtained from <code><a href="tss_create" title="c/thread/tss create">tss_create</a></code> and not deleted by <code><a href="tss_delete" title="c/thread/tss delete">tss_delete</a></code> </td> +</tr> <tr class="t-par"> <td> val </td> <td> - </td> <td> value to set thread-specific storage to </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code><a href="thrd_errors" title="c/thread/thrd errors">thrd_success</a></code> if successful, <code><a href="thrd_errors" title="c/thread/thrd errors">thrd_error</a></code> otherwise.</p> +<h3 id="Notes"> Notes</h3> <p>The POSIX equivalent of this function is <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_setspecific.html"><code>pthread_setspecific</code></a>.</p> +<p>Typically TSS is used to store pointers to blocks of dynamically allocated memory that have been reserved for use by the calling thread.</p> +<p><code>tss_set</code> may be called in the TSS destructor. If the destructor exits with non-NULL value in the TSS storage, it will be retried by <code><a href="thrd_exit" title="c/thread/thrd exit">thrd_exit</a></code> up to <code><a href="tss_dtor_iterations" title="c/thread/TSS DTOR ITERATIONS">TSS_DTOR_ITERATIONS</a></code> times, after which the storage will be lost.</p> +<h3 id="Example"> Example</h3> <div class="c source-c"><pre data-language="c">int thread_func(void *arg) { + tss_t key; + if (thrd_success == tss_create(&key, free)) { + tss_set(key, malloc(4)); // stores a pointer on TSS + // ... + } +} // calls free() for the pointer stored on TSS</pre></div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.26.6.4 The tss_set function (p: 282-283) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.26.6.4 The tss_set function (p: 387) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="tss_get" title="c/thread/tss get"> <span class="t-lines"><span>tss_get</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads from thread-specific storage <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread/tss_set" class="_attribution-link">https://en.cppreference.com/w/c/thread/tss_set</a> + </p> +</div> diff --git a/devdocs/c/thread.html b/devdocs/c/thread.html new file mode 100644 index 00000000..0eca97fb --- /dev/null +++ b/devdocs/c/thread.html @@ -0,0 +1,205 @@ + <h1 id="firstHeading" class="firstHeading">Concurrency support library</h1> <p>C includes built-in support for threads, atomic operations, mutual exclusion, condition variables, and thread-specific storages.</p> +<p>These features are optionally provided:</p> +<ul> +<li> if the macro constant <code>__STDC_NO_THREADS__</code> is defined by the compiler, the header <code><threads.h></code> and all of the names provided in it are not provided; </li> +<li> if the macro constant <code>__STDC_NO_ATOMICS__</code> is defined by the compiler, the header <a href="thread#Atomic_operations" title="c/thread"><code><stdatomic.h></code></a> and all of the names provided in it are not provided. </li> +</ul> <p>See also <a href="language/atomic" title="c/language/atomic"><code>_Atomic</code> type specifier and qualifier</a>.</p> +<h3 id="Threads"> Threads</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><threads.h></code> </th> +</tr> <tr class="t-dsc"> <td> <code>thrd_t</code> </td> <td> implementation-defined complete object type identifying a thread </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/thrd_create" title="c/thread/thrd create"> <span class="t-lines"><span>thrd_create</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> creates a thread <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/thrd_equal" title="c/thread/thrd equal"> <span class="t-lines"><span>thrd_equal</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> checks if two identifiers refer to the same thread <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/thrd_current" title="c/thread/thrd current"> <span class="t-lines"><span>thrd_current</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> obtains the current thread identifier <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/thrd_sleep" title="c/thread/thrd sleep"> <span class="t-lines"><span>thrd_sleep</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> suspends execution of the calling thread for the given period of time <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/thrd_yield" title="c/thread/thrd yield"> <span class="t-lines"><span>thrd_yield</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> yields the current time slice <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/thrd_exit" title="c/thread/thrd exit"> <span class="t-lines"><span>thrd_exit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> terminates the calling thread <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/thrd_detach" title="c/thread/thrd detach"> <span class="t-lines"><span>thrd_detach</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> detaches a thread <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/thrd_join" title="c/thread/thrd join"> <span class="t-lines"><span>thrd_join</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> blocks until a thread terminates <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/thrd_errors" title="c/thread/thrd errors"> <span class="t-lines"><span>thrd_success</span><span>thrd_timedout</span><span>thrd_busy</span><span>thrd_nomem</span><span>thrd_error</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> indicates a thread error status <br> <span class="t-mark">(constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>thrd_start_t</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> a typedef of the function pointer type <code>int(*)(void*)</code>, used by <code><a href="http://en.cppreference.com/w/c/thread/thrd_create"><span class="kw996">thrd_create</span></a></code> <br> <span class="t-mark">(typedef)</span> </td> +</tr> </table> <h3 id="Atomic_operations"> Atomic operations</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdatomic.h></code> </th> +</tr> <tr> <td colspan="2"> <h5 id="Operations_on_atomic_types"> Operations on atomic types </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_lock_free_consts" title="c/atomic/ATOMIC LOCK FREE consts"> <span class="t-lines"><span>ATOMIC_BOOL_LOCK_FREE</span><span>ATOMIC_CHAR_LOCK_FREE</span><span>ATOMIC_CHAR16_T_LOCK_FREE</span><span>ATOMIC_CHAR32_T_LOCK_FREE</span><span>ATOMIC_WCHAR_T_LOCK_FREE</span><span>ATOMIC_SHORT_LOCK_FREE</span><span>ATOMIC_INT_LOCK_FREE</span><span>ATOMIC_LONG_LOCK_FREE</span><span>ATOMIC_LLONG_LOCK_FREE</span><span>ATOMIC_POINTER_LOCK_FREE</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> indicates that the given atomic type is lock-free <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_is_lock_free" title="c/atomic/atomic is lock free"> <span class="t-lines"><span>atomic_is_lock_free</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> indicates whether the atomic object is lock-free <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_store" title="c/atomic/atomic store"> <span class="t-lines"><span>atomic_store</span><span>atomic_store_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> stores a value in an atomic object <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_load" title="c/atomic/atomic load"> <span class="t-lines"><span>atomic_load</span><span>atomic_load_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads a value from an atomic object <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_exchange" title="c/atomic/atomic exchange"> <span class="t-lines"><span>atomic_exchange</span><span>atomic_exchange_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> swaps a value with the value of an atomic object <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_compare_exchange" title="c/atomic/atomic compare exchange"> <span class="t-lines"><span>atomic_compare_exchange_strong</span><span>atomic_compare_exchange_strong_explicit</span><span>atomic_compare_exchange_weak</span><span>atomic_compare_exchange_weak_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> swaps a value with an atomic object if the old value is what is expected, otherwise reads the old value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_fetch_add" title="c/atomic/atomic fetch add"> <span class="t-lines"><span>atomic_fetch_add</span><span>atomic_fetch_add_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> atomic addition <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_fetch_sub" title="c/atomic/atomic fetch sub"> <span class="t-lines"><span>atomic_fetch_sub</span><span>atomic_fetch_sub_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> atomic subtraction <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_fetch_or" title="c/atomic/atomic fetch or"> <span class="t-lines"><span>atomic_fetch_or</span><span>atomic_fetch_or_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> atomic bitwise OR <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_fetch_xor" title="c/atomic/atomic fetch xor"> <span class="t-lines"><span>atomic_fetch_xor</span><span>atomic_fetch_xor_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> atomic bitwise exclusive OR <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_fetch_and" title="c/atomic/atomic fetch and"> <span class="t-lines"><span>atomic_fetch_and</span><span>atomic_fetch_and_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> atomic bitwise AND <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Flag_type_and_operations"> Flag type and operations </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_flag" title="c/atomic/atomic flag"> <span class="t-lines"><span>atomic_flag</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> lock-free atomic boolean flag <br><span class="t-mark">(struct)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_flag_test_and_set" title="c/atomic/atomic flag test and set"> <span class="t-lines"><span>atomic_flag_test_and_set</span><span>atomic_flag_test_and_set_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> sets an atomic_flag to true and returns the old value <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_flag_clear" title="c/atomic/atomic flag clear"> <span class="t-lines"><span>atomic_flag_clear</span><span>atomic_flag_clear_explicit</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> sets an atomic_flag to false <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Initialization"> Initialization </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_init" title="c/atomic/atomic init"> <span class="t-lines"><span>atomic_init</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> initializes an existing atomic object <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_var_init" title="c/atomic/ATOMIC VAR INIT"> <span class="t-lines"><span>ATOMIC_VAR_INIT</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span><span class="t-mark-rev t-deprecated-c17">(deprecated in C17)</span><span class="t-mark-rev t-until-c23">(removed in C23)</span></span></span></div> </td> <td> initializes a new atomic object <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_flag_init" title="c/atomic/ATOMIC FLAG INIT"> <span class="t-lines"><span>ATOMIC_FLAG_INIT</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> initializes a new <code><a href="http://en.cppreference.com/w/c/atomic/atomic_flag"><span class="kw917">atomic_flag</span></a></code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Memory_synchronization_ordering"> Memory synchronization ordering </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/memory_order" title="c/atomic/memory order"> <span class="t-lines"><span>memory_order</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> defines memory ordering constraints <br> <span class="t-mark">(enum)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/kill_dependency" title="c/atomic/kill dependency"> <span class="t-lines"><span>kill_dependency</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> breaks a dependency chain for <code><a href="http://en.cppreference.com/w/c/atomic/memory_order"><span class="kw912">memory_order_consume</span></a></code> <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_thread_fence" title="c/atomic/atomic thread fence"> <span class="t-lines"><span>atomic_thread_fence</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> generic memory order-dependent fence synchronization primitive <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="atomic/atomic_signal_fence" title="c/atomic/atomic signal fence"> <span class="t-lines"><span>atomic_signal_fence</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> fence between a thread and a signal handler executed in the same thread <br> <span class="t-mark">(function)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Convenience_type_aliases"> Convenience type aliases </h5> </td> +</tr> <tr class="t-dsc-hitem"> <th> Typedef name </th> <th> Full type name </th> +</tr> <tr class="t-dsc"> <td> <code>atomic_bool</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic _Bool</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_char</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic char</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_schar</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic signed char</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uchar</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic unsigned char</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_short</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic short</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_ushort</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic unsigned short</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_int</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic int</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uint</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic unsigned int</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_long</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic long</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_ulong</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic unsigned long</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_llong</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic long long</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_ullong</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic unsigned long long</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_char8_t</code><span class="t-mark-rev t-since-c23">(C23)</span> </td> <td> <code>_Atomic char8_t</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_char16_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic char16_t</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_char32_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic char32_t</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_wchar_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic wchar_t</code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_int_least8_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw114">int_least8_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uint_least8_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw128">uint_least8_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_int_least16_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw115">int_least16_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uint_least16_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw129">uint_least16_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_int_least32_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw116">int_least32_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uint_least32_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw130">uint_least32_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_int_least64_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw117">int_least64_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uint_least64_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw131">uint_least64_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_int_fast8_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw110">int_fast8_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uint_fast8_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw124">uint_fast8_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_int_fast16_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw111">int_fast16_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uint_fast16_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw125">uint_fast16_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_int_fast32_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw112">int_fast32_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uint_fast32_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw126">uint_fast32_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_int_fast64_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw113">int_fast64_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uint_fast64_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw127">uint_fast64_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_intptr_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw119">intptr_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uintptr_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw133">uintptr_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_size_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/size_t"><span class="kw100">size_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_ptrdiff_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/ptrdiff_t"><span class="kw101">ptrdiff_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_intmax_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw118">intmax_t</span></a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>atomic_uintmax_t</code><span class="t-mark-rev t-since-c11">(C11)</span> </td> <td> <code>_Atomic <a href="http://en.cppreference.com/w/c/types/integer"><span class="kw132">uintmax_t</span></a></code> </td> +</tr> </table> <h3 id="Mutual_exclusion"> Mutual exclusion</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><threads.h></code> </th> +</tr> <tr class="t-dsc"> <td> <code>mtx_t</code> </td> <td> mutex identifier </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/mtx_init" title="c/thread/mtx init"> <span class="t-lines"><span>mtx_init</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> creates a mutex <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/mtx_lock" title="c/thread/mtx lock"> <span class="t-lines"><span>mtx_lock</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> blocks until locks a mutex <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/mtx_timedlock" title="c/thread/mtx timedlock"> <span class="t-lines"><span>mtx_timedlock</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> blocks until locks a mutex or times out <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/mtx_trylock" title="c/thread/mtx trylock"> <span class="t-lines"><span>mtx_trylock</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> locks a mutex or returns without blocking if already locked <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/mtx_unlock" title="c/thread/mtx unlock"> <span class="t-lines"><span>mtx_unlock</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> unlocks a mutex <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/mtx_destroy" title="c/thread/mtx destroy"> <span class="t-lines"><span>mtx_destroy</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> destroys a mutex <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/mtx_types" title="c/thread/mtx types"> <span class="t-lines"><span>mtx_plain</span><span>mtx_recursive</span><span>mtx_timed</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> defines the type of a mutex <br> <span class="t-mark">(enum)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Call_once"> Call once </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/call_once" title="c/thread/call once"> <span class="t-lines"><span>call_once</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> calls a function exactly once <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <h3 id="Condition_variables"> Condition variables</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><threads.h></code> </th> +</tr> <tr class="t-dsc"> <td> <code>cnd_t</code> </td> <td> condition variable identifier </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/cnd_init" title="c/thread/cnd init"> <span class="t-lines"><span>cnd_init</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> creates a condition variable <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/cnd_signal" title="c/thread/cnd signal"> <span class="t-lines"><span>cnd_signal</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> unblocks one thread blocked on a condition variable <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/cnd_broadcast" title="c/thread/cnd broadcast"> <span class="t-lines"><span>cnd_broadcast</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> unblocks all threads blocked on a condition variable <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/cnd_wait" title="c/thread/cnd wait"> <span class="t-lines"><span>cnd_wait</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> blocks on a condition variable <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/cnd_timedwait" title="c/thread/cnd timedwait"> <span class="t-lines"><span>cnd_timedwait</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> blocks on a condition variable, with a timeout <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/cnd_destroy" title="c/thread/cnd destroy"> <span class="t-lines"><span>cnd_destroy</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> destroys a condition variable <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <h3 id="Thread-local_storage"> Thread-local storage</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><threads.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/thread_local" title="c/thread/thread local"> <span class="t-lines"><span>thread_local</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span><span class="t-mark-rev t-until-c23">(removed in C23)</span></span></span></div> </td> <td> convenience macro for storage-class specifier <code>_Thread_local</code> <br> <span class="t-mark">(keyword macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <code>tss_t</code> </td> <td> thread-specific storage pointer </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/tss_dtor_iterations" title="c/thread/TSS DTOR ITERATIONS"> <span class="t-lines"><span>TSS_DTOR_ITERATIONS</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> maximum number of times destructors are called <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span><code>tss_dtor_t</code></span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> function pointer type <code>void(*)(void*)</code>, used for TSS destructor <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/tss_create" title="c/thread/tss create"> <span class="t-lines"><span>tss_create</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> creates thread-specific storage pointer with a given destructor <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/tss_get" title="c/thread/tss get"> <span class="t-lines"><span>tss_get</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> reads from thread-specific storage <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/tss_set" title="c/thread/tss set"> <span class="t-lines"><span>tss_set</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> write to thread-specific storage <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="thread/tss_delete" title="c/thread/tss delete"> <span class="t-lines"><span>tss_delete</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> releases the resources held by a given thread-specific pointer <br> <span class="t-mark">(function)</span> </td> +</tr> </table> <h3 id="Reserved_identifiers"> Reserved identifiers</h3> <p>In future revisions of the C standard:</p> +<ul> +<li> function names, type names, and enumeration constants that begin with either <code>cnd_</code>, <code>mtx_</code>, <code>thrd_</code>, or <code>tss_</code>, and a lowercase letter may be added to the declarations in the <code><threads.h></code> header; </li> +<li> macros that begin with <code>ATOMIC_</code> and an uppercase letter may be added to the macros defined in the <a href="thread#Atomic_operations" title="c/thread"><code><stdatomic.h></code></a> header; </li> +<li> typedef names that begin with either <code>atomic_</code> or <code>memory_</code>, and a lowercase letter may be added to the declarations in the <a href="thread#Atomic_operations" title="c/thread"><code><stdatomic.h></code></a> header; </li> +<li> enumeration constants that begin with <code>memory_order_</code> and a lowercase letter may be added to the definition of the <code><a href="atomic/memory_order" title="c/atomic/memory order">memory_order</a></code> type in the <a href="thread#Atomic_operations" title="c/thread"><code><stdatomic.h></code></a> header; </li> +<li> function names that begin with <code>atomic_</code> and a lowercase letter may be added to the declarations in the <a href="thread#Atomic_operations" title="c/thread"><code><stdatomic.h></code></a> header. </li> +</ul> <p>Identifiers reserved for functions names are always <span class="t-rev-inl t-since-c23"><span>potentially</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> reserved for use as identifiers with external linkage, while other identifiers list here are <span class="t-rev-inl t-since-c23"><span>potentially</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> reserved when <a href="thread#Atomic_operations" title="c/thread"><code><stdatomic.h></code></a> is included.</p> +<p>Declaring, defining, or <code>#undef</code>ing such an identifier results in undefined behavior<span class="t-rev-inl t-since-c23"><span> if it is provided by the standard or implementation</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>. Portable programs should not use those identifiers.</p> +<h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.17 Atomics <stdatomic.h> (p: TBD) </li> +<li> 7.26 Threads <threads.h> (p: TBD) </li> +<li> 7.31.8 Atomics <stdatomic.h> (p: TBD) </li> +<li> 7.31.15 Threads <threads.h> (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.17 Atomics <stdatomic.h> (p: 200-209) </li> +<li> 7.26 Threads <threads.h> (p: 274-283) </li> +<li> 7.31.8 Atomics <stdatomic.h> (p: 332) </li> +<li> 7.31.15 Threads <threads.h> (p: 333) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.17 Atomics <stdatomic.h> (p: 273-286) </li> +<li> 7.26 Threads <threads.h> (p: 376-387) </li> +<li> 7.31.8 Atomics <stdatomic.h> (p: 455-456) </li> +<li> 7.31.15 Threads <threads.h> (p: 456) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/thread" title="cpp/thread">C++ documentation</a></span> for <span class=""><span>Concurrency support library</span></span> </td> +</tr> </table> <h3 id="External_links"> External links</h3> <table> <tr> <td> +<a rel="nofollow" class="external text" href="https://www.gnu.org/software/libc/manual/html_node/ISO-C-Mutexes.html">GNU GCC Libc Manual: ISO C Mutexes</a> </td> +</tr> +</table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/thread" class="_attribution-link">https://en.cppreference.com/w/c/thread</a> + </p> +</div> diff --git a/devdocs/c/types%2Finteger.html b/devdocs/c/types%2Finteger.html new file mode 100644 index 00000000..2815d35d --- /dev/null +++ b/devdocs/c/types%2Finteger.html @@ -0,0 +1,140 @@ + <h1 id="firstHeading" class="firstHeading">Fixed width integer types <span class="t-mark-rev t-since-c99">(since C99)</span> +</h1> <h3 id="Types"> Types</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdint.h></code> </th> +</tr> <tr class="t-dsc"> <td> <code>int8_t</code><br><code>int16_t</code><br><code>int32_t</code><br><code>int64_t</code> </td> <td> signed integer type with width of<br> exactly 8, 16, 32 and 64 bits respectively<br>with no padding bits and using 2's complement for negative values<br>(provided only if the implementation directly supports the type) </td> +</tr> <tr class="t-dsc"> <td> <code>int_fast8_t</code><br><code>int_fast16_t</code><br><code>int_fast32_t</code><br><code>int_fast64_t</code> </td> <td> fastest signed integer type with width of<br> at least 8, 16, 32 and 64 bits respectively </td> +</tr> <tr class="t-dsc"> <td> <code>int_least8_t</code><br><code>int_least16_t</code><br><code>int_least32_t</code><br><code>int_least64_t</code> </td> <td> smallest signed integer type with width of<br> at least 8, 16, 32 and 64 bits respectively </td> +</tr> <tr class="t-dsc"> <td> <code>intmax_t</code> </td> <td> maximum width integer type </td> +</tr> <tr class="t-dsc"> <td> <code>intptr_t</code> </td> <td> integer type capable of holding a pointer </td> +</tr> <tr class="t-dsc"> <td> <code>uint8_t</code><br><code>uint16_t</code><br><code>uint32_t</code><br><code>uint64_t</code> </td> <td> unsigned integer type with width of<br> exactly 8, 16, 32 and 64 bits respectively <br>(provided only if the implementation directly supports the type) </td> +</tr> <tr class="t-dsc"> <td> <code>uint_fast8_t</code><br><code>uint_fast16_t</code><br><code>uint_fast32_t</code><br><code>uint_fast64_t</code> </td> <td> fastest unsigned integer type with width of<br> at least 8, 16, 32 and 64 bits respectively </td> +</tr> <tr class="t-dsc"> <td> <code>uint_least8_t</code><br><code>uint_least16_t</code><br><code>uint_least32_t</code><br><code>uint_least64_t</code> </td> <td> smallest unsigned integer type with width of<br> at least 8, 16, 32 and 64 bits respectively </td> +</tr> <tr class="t-dsc"> <td> <code>uintmax_t</code> </td> <td> maximum width unsigned integer type </td> +</tr> <tr class="t-dsc"> <td> <code>uintptr_t</code> </td> <td> unsigned integer type capable of holding a pointer </td> +</tr> </table> <p>The implementation may define typedef names <code>int<i>N</i>_t</code>, <code>int_fast<i>N</i>_t</code>, <code>int_least<i>N</i>_t</code>, <code>uint<i>N</i>_t</code>, <code>uint_fast<i>N</i>_t</code>, and <code>uint_least<i>N</i>_t</code> when <i>N</i> is not 8, 16, 32 or 64. Typedef names of the form <code>int<i>N</i>_t</code> may only be defined if the implementation supports an integer type of that width with no padding. Thus, uint24_t denotes an unsigned integer type with a width of exactly 24 bits.</p> +<p>Each of the macros listed in below is defined if and only if the implementation defines the corresponding typedef name. The macros <code>INT<i>N</i>_C</code> and <code>UINT<i>N</i>_C</code> correspond to the typedef names <code>int_least<i>N</i>_t</code> and <code>uint_least<i>N</i>_t</code>, respectively.</p> +<h3 id="Macro_constants"> Macro constants</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdint.h></code> </th> +</tr> <tr> <td colspan="2"> <h5 id="Signed_integers_:_width"> Signed integers : width </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>INT8_WIDTH</span><span>INT16_WIDTH</span><span>INT32_WIDTH</span><span>INT64_WIDTH</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span><span class="t-mark">(optional)</span></span></span></div> </td> <td> bit width of an object of type int8_t, int16_t, int32_t, int64_t (exactly 8, 16, 32, 64) <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>INT_FAST8_WIDTH</span><span>INT_FAST16_WIDTH</span><span>INT_FAST32_WIDTH</span><span>INT_FAST64_WIDTH</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> bit width of an object of type int_fast8_t, int_fast16_t, int_fast32_t, int_fast64_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>INT_LEAST8_WIDTH</span><span>INT_LEAST16_WIDTH</span><span>INT_LEAST32_WIDTH</span><span>INT_LEAST64_WIDTH</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> bit width of an object of type int_least8_t, int_least16_t, int_least32_t, int_least64_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>INTPTR_WIDTH</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span><span class="t-mark">(optional)</span></span></span></div> </td> <td> bit width of an object of type intptr_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>INTMAX_WIDTH</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> bit width of an object of type intmax_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Signed_integers_:_minimum_value"> Signed integers : minimum value </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>INT8_MIN</span><span>INT16_MIN</span><span>INT32_MIN</span><span>INT64_MIN</span></span></div> </td> <td> minimum value of an object of type int8_t, int16_t, int32_t, int64_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>INT_FAST8_MIN</span><span>INT_FAST16_MIN</span><span>INT_FAST32_MIN</span><span>INT_FAST64_MIN</span></span></div> </td> <td> minimum value of an object of type int_fast8_t, int_fast16_t, int_fast32_t, int_fast64_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>INT_LEAST8_MIN</span><span>INT_LEAST16_MIN</span><span>INT_LEAST32_MIN</span><span>INT_LEAST64_MIN</span></span></div> </td> <td> minimum value of an object of type int_least8_t, int_least16_t, int_least32_t, int_least64_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>INTPTR_MIN</span></span></div> </td> <td> minimum value of an object of type intptr_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>INTMAX_MIN</span></span></div> </td> <td> minimum value of an object of type intmax_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Signed_integers_:_maximum_value"> Signed integers : maximum value </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>INT8_MAX</span><span>INT16_MAX</span><span>INT32_MAX</span><span>INT64_MAX</span></span></div> </td> <td> maximum value of an object of type int8_t, int16_t, int32_t, int64_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>INT_FAST8_MAX</span><span>INT_FAST16_MAX</span><span>INT_FAST32_MAX</span><span>INT_FAST64_MAX</span></span></div> </td> <td> maximum value of an object of type int_fast8_t, int_fast16_t, int_fast32_t, int_fast64_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>INT_LEAST8_MAX</span><span>INT_LEAST16_MAX</span><span>INT_LEAST32_MAX</span><span>INT_LEAST64_MAX</span></span></div> </td> <td> maximum value of an object of type int_least8_t, int_least16_t, int_least32_t, int_least64_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>INTPTR_MAX</span></span></div> </td> <td> maximum value of an object of type intptr_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>INTMAX_MAX</span></span></div> </td> <td> maximum value of an object of type intmax_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Unsigned_integers_:_width"> Unsigned integers : width </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>UINT8_WIDTH</span><span>UINT16_WIDTH</span><span>UINT32_WIDTH</span><span>UINT64_WIDTH</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span><span class="t-mark">(optional)</span></span></span></div> </td> <td> bit width of an object of type uint8_t, uint16_t, uint32_t, uint64_t (exactly 8, 16, 32, 64) <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>UINT_FAST8_WIDTH</span><span>UINT_FAST16_WIDTH</span><span>UINT_FAST32_WIDTH</span><span>UINT_FAST64_WIDTH</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> bit width of an object of type uint_fast8_t, uint_fast16_t, uint_fast32_t, uint_fast64_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>UINT_LEAST8_WIDTH</span><span>UINT_LEAST16_WIDTH</span><span>UINT_LEAST32_WIDTH</span><span>UINT_LEAST64_WIDTH</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> bit width of an object of type uint_least8_t, uint_least16_t, uint_least32_t, uint_least64_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>UINTPTR_WIDTH</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span><span class="t-mark">(optional)</span></span></span></div> </td> <td> bit width of an object of type uintptr_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>UINTMAX_WIDTH</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> bit width of an object of type uintmax_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Unsigned_integers_:_maximum_value"> Unsigned integers : maximum value </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>UINT8_MAX</span><span>UINT16_MAX</span><span>UINT32_MAX</span><span>UINT64_MAX</span></span></div> </td> <td> maximum value of an object of type uint8_t, uint16_t, uint32_t, uint64_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>UINT_FAST8_MAX</span><span>UINT_FAST16_MAX</span><span>UINT_FAST32_MAX</span><span>UINT_FAST64_MAX</span></span></div> </td> <td> maximum value of an object of type uint_fast8_t, uint_fast16_t, uint_fast32_t, uint_fast64_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>UINT_LEAST8_MAX</span><span>UINT_LEAST16_MAX</span><span>UINT_LEAST32_MAX</span><span>UINT_LEAST64_MAX</span></span></div> </td> <td> maximum value of an object of type uint_least8_t, uint_least16_t, uint_least32_t, uint_least64_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>UINTPTR_MAX</span></span></div> </td> <td> maximum value of an object of type uintptr_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>UINTMAX_MAX</span></span></div> </td> <td> maximum value of an object of type uintmax_t <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> <h3 id="Function_macros_for_minimum-width_integer_constants"> Function macros for minimum-width integer constants</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>INT8_C</span><span>INT16_C</span><span>INT32_C</span><span>INT64_C</span></span></div> </td> <td> expands to an integer constant expression having the value specified by its argument and the type int_least8_t, int_least16_t, int_least32_t, int_least64_t respectively <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>INTMAX_C</span></span></div> </td> <td> expands to an integer constant expression having the value specified by its argument and the type intmax_t <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>UINT8_C</span><span>UINT16_C</span><span>UINT32_C</span><span>UINT64_C</span></span></div> </td> <td> expands to an integer constant expression having the value specified by its argument and the type uint_least8_t, uint_least16_t, uint_least32_t, uint_least64_t respectively <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>UINTMAX_C</span></span></div> </td> <td> expands to an integer constant expression having the value specified by its argument and the type uintmax_t <br> <span class="t-mark">(function macro)</span> </td> +</tr> </table> <div class="c source-c"><pre data-language="c">#include <stdint.h> +UINT64_C(0x123) // might expand to 0x123ULL or 0x123UL</pre></div> <h3 id="Format_macro_constants"> Format macro constants</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><inttypes.h></code> </th> +</tr> </table> <h4 id="Format_constants_for_the_fprintf_family_of_functions"> Format constants for the <code><a href="../io/fprintf" title="c/io/fprintf">fprintf</a></code> family of functions</h4> <p>Each of the <code>PRI</code> macros listed here is defined if and only if the implementation defines the corresponding typedef name.</p> +<table class="wikitable"> <tr> <th rowspan="2">Equivalent<br>for <span class="kw4">int</span> or<br><span class="kw4">unsigned</span> <span class="kw4">int</span> </th> <th rowspan="2">Description </th> <th colspan="5">Macros for data types </th> +</tr> <tr> <td> +<br><br><br><br><div><code>[u]intx_t</code></div> +<br><br><br><br> </td> <td> +<div><code>[u]int_leastx_t</code></div> </td> <td> +<div><code>[u]int_fastx_t</code></div> </td> <td> +<div><code>[u]intmax_t</code></div> </td> <td> +<div><code>[u]intptr_t</code></div> </td> +</tr> <tr> <th> <code>d</code> </th> <td rowspan="2">output of a signed decimal integer value </td> <td>PRId<b>x</b> </td> <td>PRIdLEAST<b>x</b> </td> <td>PRIdFAST<b>x</b> </td> <td>PRIdMAX </td> <td>PRIdPTR </td> +</tr> <tr> <th> <code>i</code> </th> <td>PRIi<b>x</b> </td> <td>PRIiLEAST<b>x</b> </td> <td>PRIiFAST<b>x</b> </td> <td>PRIiMAX </td> <td>PRIiPTR </td> +</tr> <tr> <th> <code>u</code> </th> <td>output of an unsigned decimal integer value </td> <td>PRIu<b>x</b> </td> <td>PRIuLEAST<b>x</b> </td> <td>PRIuFAST<b>x</b> </td> <td>PRIuMAX </td> <td>PRIuPTR </td> +</tr> <tr> <th> <code>o</code> </th> <td>output of an unsigned octal integer value </td> <td>PRIo<b>x</b> </td> <td>PRIoLEAST<b>x</b> </td> <td>PRIoFAST<b>x</b> </td> <td>PRIoMAX </td> <td>PRIoPTR </td> +</tr> <tr> <th> <code>x</code> </th> <td>output of an unsigned lowercase hexadecimal integer value </td> <td>PRIx<b>x</b> </td> <td>PRIxLEAST<b>x</b> </td> <td>PRIxFAST<b>x</b> </td> <td>PRIxMAX </td> <td>PRIxPTR </td> +</tr> <tr> <th> <code>X</code> </th> <td>output of an unsigned uppercase hexadecimal integer value </td> <td>PRIX<b>x</b> </td> <td>PRIXLEAST<b>x</b> </td> <td>PRIXFAST<b>x</b> </td> <td>PRIXMAX </td> <td>PRIXPTR </td> +</tr> +</table> <h4 id="Format_constants_for_the_fscanf_family_of_functions"> Format constants for the <code><a href="../io/fscanf" title="c/io/fscanf">fscanf</a></code> family of functions</h4> <p>Each of the <code>SCN</code> macros listed in here is defined if and only if the implementation defines the corresponding typedef name and has a suitable <code><a href="../io/fscanf" title="c/io/fscanf">fscanf</a></code> length modifier for the type.</p> +<table class="wikitable"> <tr> <th rowspan="2">Equivalent<br>for <span class="kw4">int</span> or<br><span class="kw4">unsigned</span> <span class="kw4">int</span> </th> <th rowspan="2">Description </th> <th colspan="5">Macros for data types </th> +</tr> <tr> <td> +<br><br><br><br><div><code>[u]intx_t</code></div> +<br><br><br><br> </td> <td> +<div><code>[u]int_leastx_t</code></div> </td> <td> +<div><code>[u]int_fastx_t</code></div> </td> <td> +<div><code>[u]intmax_t</code></div> </td> <td> +<div><code>[u]intptr_t</code></div> </td> +</tr> <tr> <th> <code>d</code> </th> <td>input of a signed decimal integer value </td> <td>SCNd<b>x</b> </td> <td>SCNdLEAST<b>x</b> </td> <td>SCNdFAST<b>x</b> </td> <td>SCNdMAX </td> <td>SCNdPTR </td> +</tr> <tr> <th> <code>i</code> </th> <td>input of a signed integer value (base is determined by the first characters parsed) </td> <td>SCNi<b>x</b> </td> <td>SCNiLEAST<b>x</b> </td> <td>SCNiFAST<b>x</b> </td> <td>SCNiMAX </td> <td>SCNiPTR </td> +</tr> <tr> <th> <code>u</code> </th> <td>input of an unsigned decimal integer value </td> <td>SCNu<b>x</b> </td> <td>SCNuLEAST<b>x</b> </td> <td>SCNuFAST<b>x</b> </td> <td>SCNuMAX </td> <td>SCNuPTR </td> +</tr> <tr> <th> <code>o</code> </th> <td>input of an unsigned octal integer value </td> <td>SCNo<b>x</b> </td> <td>SCNoLEAST<b>x</b> </td> <td>SCNoFAST<b>x</b> </td> <td>SCNoMAX </td> <td>SCNoPTR </td> +</tr> <tr> <th> <code>x</code> </th> <td>input of an unsigned hexadecimal integer value </td> <td>SCNx<b>x</b> </td> <td>SCNxLEAST<b>x</b> </td> <td>SCNxFAST<b>x</b> </td> <td>SCNxMAX </td> <td>SCNxPTR </td> +</tr> +</table> <h3 id="Example"> Example</h3> <div class="t-example"> +<p>See also <a href="https://en.cppreference.com/w/cpp/language/user_literal#Notes" title="cpp/language/user literal">C++ compatibility note</a> regarding spaces before <a href="#Format_macro_constants">format macros</a> used in this example.</p> +<div class="c source-c"><pre data-language="c">#include <inttypes.h> +#include <stdio.h> + +int main(void) +{ + printf("%zu\n", sizeof(int64_t)); + printf("%s\n", PRId64); + printf("%+" PRId64 "\n", INT64_MIN); + printf("%+" PRId64 "\n", INT64_MAX); + + int64_t n = 7; + printf("%+" PRId64 "\n", n); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">8 +lld +-9223372036854775808 ++9223372036854775807 ++7</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 7.8.1 Macros for format specifiers (p: TBD) </li> +<li> 7.18 Integer types <stdint.h> (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.8.1 Macros for format specifiers (p: 158-159) </li> +<li> 7.18 Integer types <stdint.h> (p: 212-216) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.8.1 Macros for format specifiers (p: 217-218) </li> +<li> 7.18 Integer types <stdint.h> (p: 289-295) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.8.1 Macros for format specifiers (p: 198-199) </li> +<li> 7.18 Integer types <stdint.h> (p: 255-261) </li> +</ul> +</ul> <h3 id="See_also"> See also</h3> <ul><li> <a href="../language/arithmetic_types" title="c/language/arithmetic types">Arithmetic types</a> </li></ul> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/types/integer" title="cpp/types/integer">C++ documentation</a></span> for <span class=""><span>Fixed width integer types</span></span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/user_literal" title="cpp/language/user literal">C++ documentation</a></span> for <span class=""><span>User-defined literals (<a href="https://en.cppreference.com/w/cpp/language/user_literal#Notes" title="cpp/language/user literal">formatting macros note</a>)</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/types/integer" class="_attribution-link">https://en.cppreference.com/w/c/types/integer</a> + </p> +</div> diff --git a/devdocs/c/types%2Flimits%2Fflt_eval_method.html b/devdocs/c/types%2Flimits%2Fflt_eval_method.html new file mode 100644 index 00000000..805e2a66 --- /dev/null +++ b/devdocs/c/types%2Flimits%2Fflt_eval_method.html @@ -0,0 +1,19 @@ + <h1 id="firstHeading" class="firstHeading">FLT_EVAL_METHOD</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><float.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">#define FLT_EVAL_METHOD /* implementation defined */</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>Specifies range and precision of floating-point values obtained from floating-point constants and from all operations (operators, implicit conversions of operands) except assignment, cast, and library function call.</p> +<table class="t-dsc-begin"> <tr class="t-dsc-hitem"> <th> Value </th> <th> Explanation </th> +</tr> <tr class="t-dsc"> <td> negative values except <code>-1</code> </td> <td> implementation-defined behavior </td> +</tr> <tr class="t-dsc"> <td> <code>-1</code> </td> <td> the default precision is not known </td> +</tr> <tr class="t-dsc"> <td> <code>0</code> </td> <td> all operations and constants evaluate in the range and precision of the type used. Additionally, <code>float_t</code> and <code>double_t</code> are equivalent to <code>float</code> and <code>double</code> respectively </td> +</tr> <tr class="t-dsc"> <td> <code>1</code> </td> <td> all operations and constants evaluate in the range and precision of <code>double</code>. Additionally, both <code>float_t</code> and <code>double_t</code> are equivalent to <code>double</code> </td> +</tr> <tr class="t-dsc"> <td> <code>2</code> </td> <td> all operations and constants evaluate in the range and precision of <code>long double</code>. Additionally, both <code>float_t</code> and <code>double_t</code> are equivalent to <code>long double</code> </td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>Regardless of the value of <code>FLT_EVAL_METHOD</code>, any floating-point expression may be <i>contracted</i>, that is, calculated as if all intermediate results have infinite range and precision (unless <a href="../../preprocessor/impl" title="c/preprocessor/impl">#pragma</a> <code>STDC FP_CONTRACT</code> is off)</p> +<p>Cast and assignment strip away any extraneous range and precision: this models the action of storing a value from an extended-precision FPU register into a standard-sized memory location.</p> +<h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../../numeric/math/float_t" title="c/numeric/math/float t"> <span class="t-lines"><span>float_t</span><span>double_t</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> most efficient floating-point type at least as wide as <code>float</code> or <code>double</code> <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/types/climits/FLT_EVAL_METHOD" title="cpp/types/climits/FLT EVAL METHOD">C++ documentation</a></span> for <code>FLT_EVAL_METHOD</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/types/limits/FLT_EVAL_METHOD" class="_attribution-link">https://en.cppreference.com/w/c/types/limits/FLT_EVAL_METHOD</a> + </p> +</div> diff --git a/devdocs/c/types%2Flimits%2Fflt_rounds.html b/devdocs/c/types%2Flimits%2Fflt_rounds.html new file mode 100644 index 00000000..0386877f --- /dev/null +++ b/devdocs/c/types%2Flimits%2Fflt_rounds.html @@ -0,0 +1,21 @@ + <h1 id="firstHeading" class="firstHeading">FLT_ROUNDS</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><float.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define FLT_ROUNDS /* implementation defined */</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Returns the current rounding direction of floating-point arithmetic operations.</p> +<table class="t-dsc-begin"> <tr class="t-dsc-hitem"> <th> Value </th> <th> Explanation </th> +</tr> <tr class="t-dsc"> <td> <code>-1</code> </td> <td> the default rounding direction is not known </td> +</tr> <tr class="t-dsc"> <td> <code>0</code> </td> <td> toward zero; same meaning as <code><a href="../../numeric/fenv/fe_round" title="c/numeric/fenv/FE round">FE_TOWARDZERO</a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>1</code> </td> <td> to nearest; same meaning as <code><a href="../../numeric/fenv/fe_round" title="c/numeric/fenv/FE round">FE_TONEAREST</a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>2</code> </td> <td> towards positive infinity; same meaning as <code><a href="../../numeric/fenv/fe_round" title="c/numeric/fenv/FE round">FE_UPWARD</a></code> </td> +</tr> <tr class="t-dsc"> <td> <code>3</code> </td> <td> towards negative infinity; same meaning as <code><a href="../../numeric/fenv/fe_round" title="c/numeric/fenv/FE round">FE_DOWNWARD</a></code> </td> +</tr> <tr class="t-dsc"> <td> other values </td> <td> implementation-defined behavior </td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>The rounding mode can be changed with <code><a href="../../numeric/fenv/feround" title="c/numeric/fenv/feround">fesetround</a></code> and <code>FLT_ROUNDS</code> reflects that change.</p> +<h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="../../numeric/fenv/feround" title="c/numeric/fenv/feround"> <span class="t-lines"><span>fegetround</span><span>fesetround</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> gets or sets rounding direction <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="../../numeric/fenv/fe_round" title="c/numeric/fenv/FE round"> <span class="t-lines"><span>FE_DOWNWARD</span><span>FE_TONEAREST</span><span>FE_TOWARDZERO</span><span>FE_UPWARD</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> floating-point rounding direction <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/types/climits/FLT_ROUNDS" title="cpp/types/climits/FLT ROUNDS">C++ documentation</a></span> for <code>FLT_ROUNDS</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/types/limits/FLT_ROUNDS" class="_attribution-link">https://en.cppreference.com/w/c/types/limits/FLT_ROUNDS</a> + </p> +</div> diff --git a/devdocs/c/types%2Flimits.html b/devdocs/c/types%2Flimits.html new file mode 100644 index 00000000..ea79ff4c --- /dev/null +++ b/devdocs/c/types%2Flimits.html @@ -0,0 +1,218 @@ + <h1 id="firstHeading" class="firstHeading">Numeric limits</h1> <h3 id="Limits_of_integer_types"> Limits of integer types</h3> <table class="t-dsc-begin"> <tr> <td colspan="2"> <h5 id="Limits_of_core_language_integer_types"> Limits of core language integer types </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><limits.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>BOOL_WIDTH</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> bit width of _Bool <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>CHAR_BIT</span></span></div> </td> <td> number of bits in a byte <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>MB_LEN_MAX</span></span></div> </td> <td> maximum number of bytes in a multibyte character <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>CHAR_WIDTH</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> bit width of <span class="kw4">char</span>, same as <code>CHAR_BIT</code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>CHAR_MIN</span></span></div> </td> <td> minimum value of <span class="kw4">char</span> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>CHAR_MAX</span></span></div> </td> <td> maximum value of <span class="kw4">char</span> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>SCHAR_WIDTH</span><span>SHRT_WIDTH</span><span>INT_WIDTH</span><span>LONG_WIDTH</span><span>LLONG_WIDTH</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> bit width of <span class="kw4">signed</span> <span class="kw4">char</span>, <span class="kw4">short</span>, <span class="kw4">int</span>, <span class="kw4">long</span>, and <span class="kw4">long</span> <span class="kw4">long</span> respectively <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>SCHAR_MIN</span><span>SHRT_MIN</span><span>INT_MIN</span><span>LONG_MIN</span><span>LLONG_MIN</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> minimum value of <span class="kw4">signed</span> <span class="kw4">char</span>, <span class="kw4">short</span>, <span class="kw4">int</span>, <span class="kw4">long</span> and <span class="kw4">long</span> <span class="kw4">long</span> respectively <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>SCHAR_MAX</span><span>SHRT_MAX</span><span>INT_MAX</span><span>LONG_MAX</span><span>LLONG_MAX</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> maximum value of <span class="kw4">signed</span> <span class="kw4">char</span>, <span class="kw4">short</span>, <span class="kw4">int</span>, <span class="kw4">long</span> and <span class="kw4">long</span> <span class="kw4">long</span> respectively <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>UCHAR_WIDTH</span><span>USHRT_WIDTH</span><span>UINT_WIDTH</span><span>ULONG_WIDTH</span><span>ULLONG_WIDTH</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c23">(C23)</span></span><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> bit width of <span class="kw4">unsigned</span> <span class="kw4">char</span>, <span class="kw4">unsigned</span> <span class="kw4">short</span>, <span class="kw4">unsigned</span> <span class="kw4">int</span>, <span class="kw4">unsigned</span> <span class="kw4">long</span>, and <span class="kw4">unsigned</span> <span class="kw4">long</span> <span class="kw4">long</span> respectively <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>UCHAR_MAX</span><span>USHRT_MAX</span><span>UINT_MAX</span><span>ULONG_MAX</span><span>ULLONG_MAX</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> maximum value of <span class="kw4">unsigned</span> <span class="kw4">char</span>, <span class="kw4">unsigned</span> <span class="kw4">short</span>, <span class="kw4">unsigned</span> <span class="kw4">int</span>,<br><span class="kw4">unsigned</span> <span class="kw4">long</span> and <span class="kw4">unsigned</span> <span class="kw4">long</span> <span class="kw4">long</span> respectively <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>BITINT_MAXWIDTH</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> maximum width N supported by the declaration of a bit-precise integer in the type specifier _BitInt<span class="br0">(</span>N<span class="br0">)</span>, greater than or equal to <code>ULLONG_WIDTH</code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Limits_of_library_type_aliases"> Limits of library type aliases </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdint.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>PTRDIFF_WIDTH</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> bit width of object of <code><a href="ptrdiff_t" title="c/types/ptrdiff t">ptrdiff_t</a></code> type <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>PTRDIFF_MIN</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> minimum value of <code><a href="ptrdiff_t" title="c/types/ptrdiff t">ptrdiff_t</a></code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>PTRDIFF_MAX</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> maximum value of <code><a href="ptrdiff_t" title="c/types/ptrdiff t">ptrdiff_t</a></code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>SIZE_WIDTH</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> bit width of object of <code><a href="size_t" title="c/types/size t">size_t</a></code> type <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>SIZE_MAX</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> maximum value of <code><a href="size_t" title="c/types/size t">size_t</a></code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>SIG_ATOMIC_WIDTH</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> bit width of object of <code><a href="../program/sig_atomic_t" title="c/program/sig atomic t">sig_atomic_t</a></code> type <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>SIG_ATOMIC_MIN</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> minimum value of <code><a href="../program/sig_atomic_t" title="c/program/sig atomic t">sig_atomic_t</a></code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>SIG_ATOMIC_MAX</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> maximum value of <code><a href="../program/sig_atomic_t" title="c/program/sig atomic t">sig_atomic_t</a></code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>WINT_WIDTH</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> bit width of object of wint_t type <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>WINT_MIN</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> minimum value of <code>wint_t</code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>WINT_MAX</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> maximum value of <code>wint_t</code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><wchar.h></code> </th> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdint.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>WCHAR_WIDTH</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> bit width of object of <span class="kw4">wchar_t</span> type <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>WCHAR_MIN</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> minimum value of <span class="kw4">wchar_t</span> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>WCHAR_MAX</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> maximum value of <span class="kw4">wchar_t</span> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> <h4 id="Notes"> Notes</h4> <p>The types of these constants, other than <code>CHAR_BIT</code> and <code>MB_LEN_MAX</code>, are required to match the results of the <a href="../language/conversion#Integer_promotions" title="c/language/conversion">integral promotions</a> as applied to objects of the types they describe: <code>CHAR_MAX</code> may have type <span class="kw4">int</span> or <span class="kw4">unsigned</span> <span class="kw4">int</span>, but never <span class="kw4">char</span>. Similarly <code>USHRT_MAX</code> may not be of an unsigned type: its type may be <span class="kw4">int</span>.</p> +<p>A freestanding implementation may lack <code><a href="../program/sig_atomic_t" title="c/program/sig atomic t">sig_atomic_t</a></code> and/or wint_t typedef names, in which case the <code>SIG_ATOMIC_*</code> and/or <code>WINT_*</code> macros are correspondingly absent.</p> +<h4 id="Example"> Example</h4> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <limits.h> +#include <stdint.h> +#include <stdio.h> + +int main(void) +{ + printf("CHAR_BIT = %d\n", CHAR_BIT); + printf("MB_LEN_MAX = %d\n\n", MB_LEN_MAX); + + printf("CHAR_MIN = %+d\n", CHAR_MIN); + printf("CHAR_MAX = %+d\n", CHAR_MAX); + printf("SCHAR_MIN = %+d\n", SCHAR_MIN); + printf("SCHAR_MAX = %+d\n", SCHAR_MAX); + printf("UCHAR_MAX = %u\n\n", UCHAR_MAX); + + printf("SHRT_MIN = %+d\n", SHRT_MIN); + printf("SHRT_MAX = %+d\n", SHRT_MAX); + printf("USHRT_MAX = %u\n\n", USHRT_MAX); + + printf("INT_MIN = %+d\n", INT_MIN); + printf("INT_MAX = %+d\n", INT_MAX); + printf("UINT_MAX = %u\n\n", UINT_MAX); + + printf("LONG_MIN = %+ld\n", LONG_MIN); + printf("LONG_MAX = %+ld\n", LONG_MAX); + printf("ULONG_MAX = %lu\n\n", ULONG_MAX); + + printf("LLONG_MIN = %+lld\n", LLONG_MIN); + printf("LLONG_MAX = %+lld\n", LLONG_MAX); + printf("ULLONG_MAX = %llu\n\n", ULLONG_MAX); + + printf("PTRDIFF_MIN = %td\n", PTRDIFF_MIN); + printf("PTRDIFF_MAX = %+td\n", PTRDIFF_MAX); + printf("SIZE_MAX = %zu\n", SIZE_MAX); + printf("SIG_ATOMIC_MIN = %+jd\n",(intmax_t)SIG_ATOMIC_MIN); + printf("SIG_ATOMIC_MAX = %+jd\n",(intmax_t)SIG_ATOMIC_MAX); + printf("WCHAR_MIN = %+jd\n",(intmax_t)WCHAR_MIN); + printf("WCHAR_MAX = %+jd\n",(intmax_t)WCHAR_MAX); + printf("WINT_MIN = %jd\n", (intmax_t)WINT_MIN); + printf("WINT_MAX = %jd\n", (intmax_t)WINT_MAX); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">CHAR_BIT = 8 +MB_LEN_MAX = 16 + +CHAR_MIN = -128 +CHAR_MAX = +127 +SCHAR_MIN = -128 +SCHAR_MAX = +127 +UCHAR_MAX = 255 + +SHRT_MIN = -32768 +SHRT_MAX = +32767 +USHRT_MAX = 65535 + +INT_MIN = -2147483648 +INT_MAX = +2147483647 +UINT_MAX = 4294967295 + +LONG_MIN = -9223372036854775808 +LONG_MAX = +9223372036854775807 +ULONG_MAX = 18446744073709551615 + +LLONG_MIN = -9223372036854775808 +LLONG_MAX = +9223372036854775807 +ULLONG_MAX = 18446744073709551615 + +PTRDIFF_MIN = -9223372036854775808 +PTRDIFF_MAX = +9223372036854775807 +SIZE_MAX = 18446744073709551615 +SIG_ATOMIC_MIN = -2147483648 +SIG_ATOMIC_MAX = +2147483647 +WCHAR_MIN = -2147483648 +WCHAR_MAX = +2147483647 +WINT_MIN = 0 +WINT_MAX = 4294967295</pre></div> </div> <h3 id="Limits_of_floating-point_types"> Limits of floating-point types</h3> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><float.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>FLT_RADIX</span></span></div> </td> <td> the radix (integer base) used by the representation of all three floating-point types <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>DECIMAL_DIG</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> conversion from <span class="kw4">long</span> <span class="kw4">double</span> to decimal with at least <code>DECIMAL_DIG</code> digits and back to <span class="kw4">long</span> <span class="kw4">double</span> is the identity conversion: this is the decimal precision required to serialize/deserialize a <span class="kw4">long</span> <span class="kw4">double</span> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>FLT_DECIMAL_DIG</span><span>DBL_DECIMAL_DIG</span><span>LDBL_DECIMAL_DIG</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> conversion from <span class="kw4">float</span>/<span class="kw4">double</span>/<span class="kw4">long</span> <span class="kw4">double</span> to decimal with at least <code>FLT_DECIMAL_DIG</code>/<code>DBL_DECIMAL_DIG</code>/<code>LDBL_DECIMAL_DIG</code> digits and back is the identity conversion: this is the decimal precision required to serialize/deserialize a floating-point value. Defined to at least <code>6</code>, <code>10</code>, and <code>10</code> respectively, or <code>9</code> for IEEE float and <code>17</code> for IEEE double (see also the C++ analog: <a href="https://en.cppreference.com/w/cpp/types/numeric_limits/max_digits10" title="cpp/types/numeric limits/max digits10"><code>max_digits10</code></a>) <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>FLT_MIN</span><span>DBL_MIN</span><span>LDBL_MIN</span></span></div> </td> <td> minimum, normalized, positive value of <span class="kw4">float</span>, <span class="kw4">double</span> and <span class="kw4">long</span> <span class="kw4">double</span> respectively <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>FLT_TRUE_MIN</span><span>DBL_TRUE_MIN</span><span>LDBL_TRUE_MIN</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> minimum positive value of <span class="kw4">float</span>, <span class="kw4">double</span> and <span class="kw4">long</span> <span class="kw4">double</span> respectively <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>FLT_MAX</span><span>DBL_MAX</span><span>LDBL_MAX</span></span></div> </td> <td> maximum finite value of <span class="kw4">float</span>, <span class="kw4">double</span> and <span class="kw4">long</span> <span class="kw4">double</span> respectively <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>FLT_EPSILON</span><span>DBL_EPSILON</span><span>LDBL_EPSILON</span></span></div> </td> <td> absolute value difference between <code>1.0</code> and the next representable value for <span class="kw4">float</span>, <span class="kw4">double</span> and <span class="kw4">long</span> <span class="kw4">double</span> respectively <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>FLT_DIG</span><span>DBL_DIG</span><span>LDBL_DIG</span></span></div> </td> <td> number of decimal digits that are guaranteed to be preserved in text → <span class="kw4">float</span>/<span class="kw4">double</span>/<span class="kw4">long</span> <span class="kw4">double</span> → text roundtrip without change due to rounding or overflow (see the C++ analog <a href="https://en.cppreference.com/w/cpp/types/numeric_limits/digits10" title="cpp/types/numeric limits/digits10"><code>digits10</code></a> for detail) <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>FLT_MANT_DIG</span><span>DBL_MANT_DIG</span><span>LDBL_MANT_DIG</span></span></div> </td> <td> number of base-<code>FLT_RADIX</code> digits that are in the floating-point mantissa and that can be represented without losing precision for <span class="kw4">float</span>, <span class="kw4">double</span> and <span class="kw4">long</span> <span class="kw4">double</span> respectively <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>FLT_MIN_EXP</span><span>DBL_MIN_EXP</span><span>LDBL_MIN_EXP</span></span></div> </td> <td> minimum negative integer such that <code>FLT_RADIX</code> raised by power one less than that integer is a normalized <span class="kw4">float</span>, <span class="kw4">double</span> and <span class="kw4">long</span> <span class="kw4">double</span> respectively <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>FLT_MIN_10_EXP</span><span>DBL_MIN_10_EXP</span><span>LDBL_MIN_10_EXP</span></span></div> </td> <td> minimum negative integer such that 10 raised by power one less than that integer is a normalized <span class="kw4">float</span>, <span class="kw4">double</span> and <span class="kw4">long</span> <span class="kw4">double</span> respectively <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>FLT_MAX_EXP</span><span>DBL_MAX_EXP</span><span>LDBL_MAX_EXP</span></span></div> </td> <td> maximum positive integer such that <code>FLT_RADIX</code> raised by power one less than that integer is a representable finite <span class="kw4">float</span>, <span class="kw4">double</span> and <span class="kw4">long</span> <span class="kw4">double</span> respectively <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>FLT_MAX_10_EXP</span><span>DBL_MAX_10_EXP</span><span>LDBL_MAX_10_EXP</span></span></div> </td> <td> maximum positive integer such that 10 raised by power one less than that integer is a representable finite <span class="kw4">float</span>, <span class="kw4">double</span> and <span class="kw4">long</span> <span class="kw4">double</span> respectively <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="limits/flt_rounds" title="c/types/limits/FLT ROUNDS"> <span class="t-lines"><span>FLT_ROUNDS</span></span></a></div> </td> <td> rounding mode of floating-point arithmetic <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="limits/flt_eval_method" title="c/types/limits/FLT EVAL METHOD"> <span class="t-lines"><span>FLT_EVAL_METHOD</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> use of extended precision for intermediate results:<br> <code>0</code> – not used, <code>1</code> – <span class="kw4">double</span> is used instead of <span class="kw4">float</span>, <code>2</code> – <span class="kw4">long</span> <span class="kw4">double</span> is used <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>FLT_HAS_SUBNORM</span><span>DBL_HAS_SUBNORM</span><span>LDBL_HAS_SUBNORM</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span><span class="t-mark-rev t-deprecated-c23">(deprecated in C23)</span></span></span></div> </td> <td> whether the type supports subnormal (<a href="https://en.wikipedia.org/wiki/Denormal_number" class="extiw" title="enwiki:Denormal number">denormal</a>) numbers:<br><code>-1</code> – indeterminable, <code>0</code> – absent, <code>1</code> – present <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> <h4 id="Example_2"> Example</h4> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <float.h> +#include <math.h> +#include <stdio.h> + +int main(void) +{ + printf("DECIMAL_DIG = %d\n", DECIMAL_DIG); + printf("FLT_DECIMAL_DIG = %d\n", FLT_DECIMAL_DIG); + printf("FLT_RADIX = %d\n", FLT_RADIX); + printf("FLT_MIN = %e\n", FLT_MIN); + printf("FLT_MAX = %e\n", FLT_MAX); + printf("FLT_EPSILON = %e\n", FLT_EPSILON); + printf("FLT_DIG = %d\n", FLT_DIG); + printf("FLT_MANT_DIG = %d\n", FLT_MANT_DIG); + printf("FLT_MIN_EXP = %d\n", FLT_MIN_EXP); + printf("FLT_MIN_10_EXP = %d\n", FLT_MIN_10_EXP); + printf("FLT_MAX_EXP = %d\n", FLT_MAX_EXP); + printf("FLT_MAX_10_EXP = %d\n", FLT_MAX_10_EXP); + printf("FLT_ROUNDS = %d\n", FLT_ROUNDS); + printf("FLT_EVAL_METHOD = %d\n", FLT_EVAL_METHOD); + printf("FLT_HAS_SUBNORM = %d\n", FLT_HAS_SUBNORM); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">DECIMAL_DIG = 37 +FLT_DECIMAL_DIG = 9 +FLT_RADIX = 2 +FLT_MIN = 1.175494e-38 +FLT_MAX = 3.402823e+38 +FLT_EPSILON = 1.192093e-07 +FLT_DIG = 6 +FLT_MANT_DIG = 24 +FLT_MIN_EXP = -125 +FLT_MIN_10_EXP = -37 +FLT_MAX_EXP = 128 +FLT_MAX_10_EXP = 38 +FLT_ROUNDS = 1 +FLT_EVAL_METHOD = 1 +FLT_HAS_SUBNORM = 1</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 5.2.4.2 Numerical limits (p: TBD) </li> +<li> 7.22.3 Limits of other integer types (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 5.2.4.2 Numerical limits (p: 20-27) </li> +<li> 7.20.3 Limits of other integer types (p: 215-216) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 5.2.4.2 Numerical limits (p: 26-34) </li> +<li> 7.20.3 Limits of other integer types (p: 293-294) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 5.2.4.2 Numerical limits (p: 21-28) </li> +<li> 7.18.3 Limits of other integer types (p: 259-260) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 2.2.4.2 Numerical limits </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/types/climits" title="cpp/types/climits">C++ documentation</a></span> for <span class=""><span>C numeric limits interface</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/types/limits" class="_attribution-link">https://en.cppreference.com/w/c/types/limits</a> + </p> +</div> diff --git a/devdocs/c/types%2Fmax_align_t.html b/devdocs/c/types%2Fmax_align_t.html new file mode 100644 index 00000000..32a94bae --- /dev/null +++ b/devdocs/c/types%2Fmax_align_t.html @@ -0,0 +1,34 @@ + <h1 id="firstHeading" class="firstHeading">max_align_t</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stddef.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">typedef /*implementation-defined*/ max_align_t;</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <p><code>max_align_t</code> is a type whose alignment requirement is at least as strict (as large) as that of every scalar type.</p> +<h3 id="Notes"> Notes</h3> <p>Pointers returned by allocation functions such as <code><a href="../memory/malloc" title="c/memory/malloc">malloc</a></code> are suitably aligned for any object, which means they are aligned at least as strictly as <code>max_align_t</code>.</p> +<p><code>max_align_t</code> is usually synonymous with the largest scalar type, which is <code>long double</code> on most platforms, and its alignment requirement is either 8 or 16.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stddef.h> +#include <stdalign.h> +#include <stdlib.h> +#include <stdint.h> +#include <inttypes.h> + +int main(void) +{ + size_t a = alignof(max_align_t); + printf("Alignment of max_align_t is %zu (%#zx)\n", a, a); + + void *p = malloc(123); + printf("The address obtained from malloc(123) is %#" PRIxPTR"\n", + (uintptr_t)p); + free(p); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Alignment of max_align_t is 16 (0x10) +The address obtained from malloc(123) is 0x1fa67010</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.19 Common definitions <stddef.h> (p: 211) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.19 Common definitions <stddef.h> (p: 288) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/types/max_align_t" title="cpp/types/max align t">C++ documentation</a></span> for <code>max_align_t</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/types/max_align_t" class="_attribution-link">https://en.cppreference.com/w/c/types/max_align_t</a> + </p> +</div> diff --git a/devdocs/c/types%2Fnull.html b/devdocs/c/types%2Fnull.html new file mode 100644 index 00000000..fc9462a8 --- /dev/null +++ b/devdocs/c/types%2Fnull.html @@ -0,0 +1,47 @@ + <h1 id="firstHeading" class="firstHeading">NULL</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><locale.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><stddef.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><time.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define NULL /*implementation-defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>The macro <code>NULL</code> is an implementation-defined null pointer constant, which may be</p> +<ul> +<li> an integer <a href="../language/constant_expression#Integer_constant_expression" title="c/language/constant expression">constant expression</a> with the value <code>0</code> </li> +<li> an integer constant expression with the value <code>0</code> <a href="../language/conversion#Pointer_conversions" title="c/language/conversion">cast to the type</a> <code>void*</code> </li> +</ul> <table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <ul><li> predefined constant <a href="../language/nullptr" title="c/language/nullptr"><code>nullptr</code></a> </li></ul> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <p>A null pointer constant may be <a href="../language/conversion#Pointer_conversions" title="c/language/conversion">converted</a> to any pointer type; such conversion results in the null pointer value of that type.</p> +<h3 id="Possible_implementation"> Possible implementation</h3> <table class="eq-fun-cpp-table"> <tr> <td> <div class="c source-c"><pre data-language="c">// C++ compatible: +#define NULL 0 +// C++ incompatible: +#define NULL (10*2 - 20) +#define NULL ((void*)0) +// since C23 (compatible with C++11 and later) +#define NULL nullptr</pre></div> </td> +</tr> +</table> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <inttypes.h> +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + // any kind of pointer can be set to NULL + int* p = NULL; + struct S *s = NULL; + void(*f)(int, double) = NULL; + printf("%p %p %p\n", (void*)p, (void*)s, (void*)(long)f); + + // many pointer-returning functions use null pointers to indicate error + char *ptr = malloc(0xFULL); + if (ptr == NULL) + printf("Out of memory"); + else + printf("ptr = %#" PRIxPTR"\n", (uintptr_t)ptr); + free(ptr); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">(nil) (nil) (nil) +ptr = 0xc001cafe</pre></div> </div> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="nullptr_t" title="c/types/nullptr t"> <span class="t-lines"><span>nullptr_t</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> the type of the predefined null pointer constant <a href="../language/nullptr" title="c/language/nullptr"><code>nullptr</code></a> <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/types/NULL" title="cpp/types/NULL">C++ documentation</a></span> for <code>NULL</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/types/NULL" class="_attribution-link">https://en.cppreference.com/w/c/types/NULL</a> + </p> +</div> diff --git a/devdocs/c/types%2Fnullptr_t.html b/devdocs/c/types%2Fnullptr_t.html new file mode 100644 index 00000000..ea058783 --- /dev/null +++ b/devdocs/c/types%2Fnullptr_t.html @@ -0,0 +1,32 @@ + <h1 id="firstHeading" class="firstHeading">nullptr_t</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stddef.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">typedef typeof(nullptr) nullptr_t;</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <p><code>nullptr_t</code> is the type of the predefined null pointer constant, <a href="../language/nullptr" title="c/language/nullptr"><code>nullptr</code></a>. It is a distinct type that is not itself a pointer type. It can be <a href="../language/conversion" title="c/language/conversion">implicitly converted</a> to any pointer type or <code>bool</code>, and the result is the null pointer value of that type or <code>false</code> respectively. No type other than <code>nullptr_t</code> itself can be converted or explicitly cast to <code>nullptr_t</code>.</p> +<p><code>sizeof(nullptr_t)</code> and <code>alignof(nullptr_t)</code> are equal to <code>sizeof(void*)</code> and <code>alignof(void*)</code> respectively.</p> +<p><code>nullptr_t</code> has only one valid value, i.e., <code>nullptr</code>. The object representation of <code>nullptr</code> is same as that of <code>(void*)0</code>. If a program produces a <code>nullptr_t</code> value with a different object representation, the behavior is undefined.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>Demonstrate that <code>nullptr_t</code> is a distinct type.</p> +<div class="c source-c"><pre data-language="c">#include <stddef.h> +#include <stdio.h> + +#define DETECT_NULL_POINTER_CONSTANT(e) \ + _Generic(e, \ + void* : puts("void*"), \ + nullptr_t : puts("nullptr_t"), \ + default : puts("other") \ + ) + +int main() +{ + DETECT_NULL_POINTER_CONSTANT(((void*)0)); + DETECT_NULL_POINTER_CONSTANT(0); + DETECT_NULL_POINTER_CONSTANT(nullptr); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">void* +other +nullptr_t</pre></div> </div> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="null" title="c/types/NULL"> <span class="t-lines"><span>NULL</span></span></a></div> </td> <td> implementation-defined null pointer constant <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/types/nullptr_t" title="cpp/types/nullptr t">C++ documentation</a></span> for <code>nullptr_t</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/types/nullptr_t" class="_attribution-link">https://en.cppreference.com/w/c/types/nullptr_t</a> + </p> +</div> diff --git a/devdocs/c/types%2Foffsetof.html b/devdocs/c/types%2Foffsetof.html new file mode 100644 index 00000000..b8739a55 --- /dev/null +++ b/devdocs/c/types%2Foffsetof.html @@ -0,0 +1,39 @@ + <h1 id="firstHeading" class="firstHeading">offsetof</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stddef.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define offsetof(type, member) /*implementation-defined*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>The macro <code>offsetof</code> expands to an <a href="../language/constant_expression#Integer_constant_expression" title="c/language/constant expression">integer constant expression</a> of type <code><a href="size_t" title="c/types/size t">size_t</a></code>, the value of which is the offset, in bytes, from the beginning of an object of specified type to its specified subobject, including padding if any.</p> +<p>Given an object <code>o</code> of type <code>type</code> with static storage duration, <code>&(o.member)</code> shall be an address constant expression and point to a subobject of <code>o</code>. Otherwise, the behavior is undefined.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p>If the type name specified in <code>type</code> contains a comma not between matching parentheses, the behavior is undefined.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>If <code>offsetof</code> is applied to a bit-field member, the behavior is undefined, because the address of a bit-field cannot be taken.</p> +<p><code>member</code> is not restricted to a direct member. It can denote a subobject of a given member, such as an element of an array member.</p> +<p>Even though it is specified in C23 that specifying a new type containg an unparenthesized comma in <code>offsetof</code> is undefined behavior, such usage is generally not supported even in earlier modes: <code>offsetof(struct Foo { int a, b; }, a)</code> generally fails to compile.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p><a href="../language/typeof" title="c/language/typeof"><code>typeof</code></a> can be used to avoid the bad effect of commas in the definition of a new type, e.g. <code>offsetof(typeof(struct { int i, j; }), i)</code> is well-defined.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stddef.h> + +struct S { + char c; + double d; +}; + +int main(void) +{ + printf("the first element is at offset %zu\n", offsetof(struct S, c)); + printf("the double is at offset %zu\n", offsetof(struct S, d)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">the first element is at offset 0 +the double is at offset 8</pre></div> </div> <h3 id="Defect_reports"> Defect reports</h3> <p>The following behavior-changing defect reports were applied retroactively to previously published C standards.</p> +<table class="dsctable"> <tr> <th>DR </th> <th>Applied to </th> <th>Behavior as published </th> <th>Correct behavior </th> +</tr> <tr> <td> +<a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_496">DR 496</a> </td> <td>C89 </td> <td>only structs and struct members were mentioned </td> <td>unions and other subobjects are also supported </td> +</tr> +</table> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="size_t" title="c/types/size t"> <span class="t-lines"><span>size_t</span></span></a></div> </td> <td> unsigned integer type returned by the <a href="../language/sizeof" title="c/language/sizeof"><code>sizeof</code></a> operator <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/types/offsetof" title="cpp/types/offsetof">C++ documentation</a></span> for <code>offsetof</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/types/offsetof" class="_attribution-link">https://en.cppreference.com/w/c/types/offsetof</a> + </p> +</div> diff --git a/devdocs/c/types%2Fptrdiff_t.html b/devdocs/c/types%2Fptrdiff_t.html new file mode 100644 index 00000000..a576a926 --- /dev/null +++ b/devdocs/c/types%2Fptrdiff_t.html @@ -0,0 +1,56 @@ + <h1 id="firstHeading" class="firstHeading">ptrdiff_t</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stddef.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">typedef /*implementation-defined*/ ptrdiff_t;</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p><code>ptrdiff_t</code> is the signed integer type of the result of <a href="../language/operator_arithmetic#Pointer_arithmetic" title="c/language/operator arithmetic">subtracting two pointers</a>.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99 t-until-c23"> +<td> <p>The bit width of <code>ptrdiff_t</code> is not less than 17.</p> +</td> <td> +<span class="t-mark-rev t-since-c99">(since C99)</span><br><span class="t-mark-rev t-until-c23">(until C23)</span> +</td> +</tr> <tr class="t-rev t-since-c23"> +<td> <p>The bit width of <code>ptrdiff_t</code> is not less than 16.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p><code>ptrdiff_t</code> is used for pointer arithmetic and array indexing, if negative values are possible. Programs that use other types, such as <code>int</code>, may fail on, e.g. 64-bit systems when the index exceeds <code><a href="limits" title="c/types/limits">INT_MAX</a></code> or if it relies on 32-bit modular arithmetic.</p> +<p>Only pointers to elements of the same array (including the pointer one past the end of the array) may be subtracted from each other.</p> +<p>If an array is so large (greater than <code><a href="limits" title="c/types/limits">PTRDIFF_MAX</a></code> elements, but equal to or less than <code><a href="limits" title="c/types/limits">SIZE_MAX</a></code> bytes), that the difference between two pointers may not be representable as <code>ptrdiff_t</code>, the result of subtracting two such pointers is undefined.</p> +<p>For char arrays shorter than <code><a href="limits" title="c/types/limits">PTRDIFF_MAX</a></code>, <code>ptrdiff_t</code> acts as the signed counterpart of <code><a href="size_t" title="c/types/size t">size_t</a></code>: it can store the size of the array of any type and is, on most platforms, synonymous with <code>intptr_t</code>).</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stddef.h> +#include <stdint.h> +#include <stdio.h> + +int main(void) +{ + const size_t N = 100; + int numbers[N]; + + printf("PTRDIFF_MAX = %ld\n", PTRDIFF_MAX); + int *p1 = &numbers[18], *p2 = &numbers[23]; + ptrdiff_t diff = p2 - p1; + printf("p2-p1 = %td\n", diff); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">PTRDIFF_MAX = 9223372036854775807 +p2-p1 = 5</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.19 Common definitions <stddef.h> (p: 211) </li> +<li> 7.20.3 Limits of other integer types (p: 215) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.19 Common definitions <stddef.h> (p: 288) </li> +<li> 7.20.3 Limits of other integer types (p: 293) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.17 Common definitions <stddef.h> (p: 253) </li> +<li> 7.18.3 Limits of other integer types (p: 258) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.1.6 Common definitions <stddef.h> </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="size_t" title="c/types/size t"> <span class="t-lines"><span>size_t</span></span></a></div> </td> <td> unsigned integer type returned by the <a href="../language/sizeof" title="c/language/sizeof"><code>sizeof</code></a> operator <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="offsetof" title="c/types/offsetof"> <span class="t-lines"><span>offsetof</span></span></a></div> </td> <td> byte offset from the beginning of a struct type to specified member <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/types/ptrdiff_t" title="cpp/types/ptrdiff t">C++ documentation</a></span> for <code>ptrdiff_t</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/types/ptrdiff_t" class="_attribution-link">https://en.cppreference.com/w/c/types/ptrdiff_t</a> + </p> +</div> diff --git a/devdocs/c/types%2Fsize_t.html b/devdocs/c/types%2Fsize_t.html new file mode 100644 index 00000000..de4fdb66 --- /dev/null +++ b/devdocs/c/types%2Fsize_t.html @@ -0,0 +1,49 @@ + <h1 id="firstHeading" class="firstHeading">size_t</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stddef.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><stdlib.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><string.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><time.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><uchar.h></code> </th> <th> </th> <th><span class="t-mark-rev t-since-c11">(since C11)</span></th> </tr> <tr class="t-dsc-header"> <th> Defined in header <code><wchar.h></code> </th> <th> </th> <th><span class="t-mark-rev t-since-c95">(since C95)</span></th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">typedef /*implementation-defined*/ size_t;</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p><code>size_t</code> is the unsigned integer type of the result of <a href="../language/sizeof" title="c/language/sizeof"><code>sizeof</code></a> <span class="t-rev-inl t-since-c11"><span>, <a href="../language/_alignof" title="c/language/ Alignof"><code>_Alignof</code></a></span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> and <code><a href="offsetof" title="c/types/offsetof">offsetof</a></code>, depending on the <a href="../language/arithmetic_types#Data_models" title="c/language/arithmetic types">data model</a>.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c99"> +<td> <p>The bit width of <code>size_t</code> is not less than 16.</p> +</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p><code>size_t</code> can store the maximum size of a theoretically possible object of any type (including array).</p> +<p><code>size_t</code> is commonly used for array indexing and loop counting. Programs that use other types, such as <code>unsigned int</code>, for array indexing may fail on, e.g. 64-bit systems when the index exceeds <code><a href="limits" title="c/types/limits">UINT_MAX</a></code> or if it relies on 32-bit modular arithmetic.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stddef.h> +#include <stdint.h> + +int main(void) +{ + const size_t N = 100; + int numbers[N]; + for (size_t ndx = 0; ndx < N; ++ndx) + numbers[ndx] = ndx; + printf("SIZE_MAX = %zu\n", SIZE_MAX); + size_t size = sizeof numbers; + printf("size = %zu\n", size); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">SIZE_MAX = 18446744073709551615 +size = 400</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.19 Common definitions <stddef.h> (p: 211) </li> +<li> 7.20.3 Limits of other integer types (p: 215) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.19 Common definitions <stddef.h> (p: 288) </li> +<li> 7.20.3 Limits of other integer types (p: 293) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.17 Common definitions <stddef.h> (p: 253) </li> +<li> 7.18.3 Limits of other integer types (p: 258) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.1.6 Common definitions <stddef.h> </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="ptrdiff_t" title="c/types/ptrdiff t"> <span class="t-lines"><span>ptrdiff_t</span></span></a></div> </td> <td> signed integer type returned when subtracting two pointers <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="offsetof" title="c/types/offsetof"> <span class="t-lines"><span>offsetof</span></span></a></div> </td> <td> byte offset from the beginning of a struct type to specified member <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/types/size_t" title="cpp/types/size t">C++ documentation</a></span> for <code>size_t</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/types/size_t" class="_attribution-link">https://en.cppreference.com/w/c/types/size_t</a> + </p> +</div> diff --git a/devdocs/c/types.html b/devdocs/c/types.html new file mode 100644 index 00000000..7f02a985 --- /dev/null +++ b/devdocs/c/types.html @@ -0,0 +1,87 @@ + <h1 id="firstHeading" class="firstHeading">Type support</h1> <p>See also <a href="language/types" title="c/language/types" class="mw-redirect"> type system overview</a> and <a href="language/arithmetic_types" title="c/language/arithmetic types"> arithmetic types defined by the language</a>.</p> +<h3 id="Basic_types"> Basic types</h3> <h4 id="Additional_basic_types_and_convenience_macros"> Additional basic types and convenience macros</h4> <table class="t-dsc-begin"> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stddef.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="types/size_t" title="c/types/size t"> <span class="t-lines"><span>size_t</span></span></a></div> </td> <td> unsigned integer type returned by the <a href="language/sizeof" title="c/language/sizeof"><code>sizeof</code></a> operator <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="types/ptrdiff_t" title="c/types/ptrdiff t"> <span class="t-lines"><span>ptrdiff_t</span></span></a></div> </td> <td> signed integer type returned when subtracting two pointers <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="types/nullptr_t" title="c/types/nullptr t"> <span class="t-lines"><span>nullptr_t</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> the type of the predefined null pointer constant <a href="language/nullptr" title="c/language/nullptr"><code>nullptr</code></a> <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="types/null" title="c/types/NULL"> <span class="t-lines"><span>NULL</span></span></a></div> </td> <td> implementation-defined null pointer constant <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="types/max_align_t" title="c/types/max align t"> <span class="t-lines"><span>max_align_t</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> a type with alignment requirement as great as any other scalar type <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="types/offsetof" title="c/types/offsetof"> <span class="t-lines"><span>offsetof</span></span></a></div> </td> <td> byte offset from the beginning of a struct type to specified member <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdbool.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>bool</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span><span class="t-mark-rev t-until-c23">(removed in C23)</span></span></span></div> </td> <td> convenience macro, expands to <a href="keyword/_bool" title="c/keyword/ Bool"><code>_Bool</code></a> <br> <span class="t-mark">(keyword macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>true</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span><span class="t-mark-rev t-until-c23">(removed in C23)</span></span></span></div> </td> <td> expands to integer constant <code>1</code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>false</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span><span class="t-mark-rev t-until-c23">(removed in C23)</span></span></span></div> </td> <td> expands to integer constant <code>0</code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__bool_true_false_are_defined</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span><span class="t-mark-rev t-deprecated-c23">(deprecated in C23)</span></span></span></div> </td> <td> expands to integer constant <code>1</code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdalign.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>alignas</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span><span class="t-mark-rev t-until-c23">(removed in C23)</span></span></span></div> </td> <td> convenience macro, expands to keyword <a href="keyword/_alignas" title="c/keyword/ Alignas"><code>_Alignas</code></a> <br> <span class="t-mark">(keyword macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>alignof</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span><span class="t-mark-rev t-until-c23">(removed in C23)</span></span></span></div> </td> <td> convenience macro, expands to keyword <a href="keyword/_alignof" title="c/keyword/ Alignof"><code>_Alignof</code></a> <br> <span class="t-mark">(keyword macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__alignas_is_defined</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span><span class="t-mark-rev t-until-c23">(removed in C23)</span></span></span></div> </td> <td> expands to integer constant <code>1</code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__alignof_is_defined</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span><span class="t-mark-rev t-until-c23">(removed in C23)</span></span></span></div> </td> <td> expands to integer constant <code>1</code> <br> <span class="t-mark">(macro constant)</span> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdnoreturn.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>noreturn</span></span></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span><span class="t-mark-rev t-deprecated-c23">(deprecated in C23)</span></span></span></div> </td> <td> convenience macro, expands to <a href="keyword/_noreturn" title="c/keyword/ Noreturn"><code>_Noreturn</code></a> <br> <span class="t-mark">(keyword macro)</span> </td> +</tr> </table> <h4 id="Fixed_width_integer_types_.28since_C99.29"> <a href="types/integer" title="c/types/integer"> Fixed width integer types</a> <span class="t-mark-rev t-since-c99">(since C99)</span> +</h4> <h4 id="Numeric_limits"> <a href="types/limits" title="c/types/limits"> Numeric limits</a> +</h4> <h3 id="Notes"> Notes</h3> <table class="t-rev-begin"> <tr class="t-rev t-since-c99 t-until-c23"> +<td> <p>The type of <code>true</code> and <code>false</code> is <code>int</code> rather than <code>_Bool</code>.</p> +<p>A program may undefine and perhaps then redefine the macros <code>bool</code>, <code>true</code> and <code>false</code>. However, such ability is a deprecated feature.</p> +</td> <td> +<span class="t-mark-rev t-since-c99">(since C99)</span><br><span class="t-mark-rev t-until-c23">(until C23)</span> +</td> +</tr> <tr class="t-rev t-since-c23"> +<td> <p>The type of <code>true</code> and <code>false</code> is <code>bool</code>. It is unspecified whether any of <code>bool</code>, <code>_Bool</code>, <code>true</code>, or <code>false</code> is implemented as a predefined macro.</p> +<p>If <code>bool</code>, <code>true</code>, or <code>false</code> (but not <code>_Bool</code>) is defined as a predefined macro, a program may undefine and perhaps redefine it.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdbool.h> +#include <stdalign.h> + +int main(void) +{ + printf("%d %d %d\n", true && false, true || false, !false); + printf("%d %d\n", true ^ true, true + true); + printf("%zu\n", alignof(short)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">0 1 1 +0 2 +2</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.15 Alignment <stdalign.h> (p: 196) </li> +<li> 7.18 Boolean type and values <stdbool.h> (p: 210) </li> +<li> 7.19 Common definitions <stddef.h> (p: 211) </li> +<li> 7.23 _Noreturn <stdnoreturn.h> (p: 263) </li> +<li> 7.31.9 Boolean type and values <stdbool.h> (p: 332) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.15 Alignment <stdalign.h> (p: 268) </li> +<li> 7.18 Boolean type and values <stdbool.h> (p: 287) </li> +<li> 7.19 Common definitions <stddef.h> (p: 288) </li> +<li> 7.23 _Noreturn <stdnoreturn.h> (p: 361) </li> +<li> 7.31.9 Boolean type and values <stdbool.h> (p: 456) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul> +<li> 7.18 Boolean type and values <stdbool.h> (p: 253) </li> +<li> 7.19 Common definitions <stddef.h> (p: 254) </li> +<li> 7.26.7 Boolean type and values <stdbool.h> (p: 401) </li> +</ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.1.5 Common definitions <stddef.h> </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/types" title="cpp/types">C++ documentation</a></span> for <span class=""><span>Type support library</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/types" class="_attribution-link">https://en.cppreference.com/w/c/types</a> + </p> +</div> diff --git a/devdocs/c/variadic%2Fva_arg.html b/devdocs/c/variadic%2Fva_arg.html new file mode 100644 index 00000000..841667fa --- /dev/null +++ b/devdocs/c/variadic%2Fva_arg.html @@ -0,0 +1,54 @@ + <h1 id="firstHeading" class="firstHeading">va_arg</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdarg.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">T va_arg( va_list ap, T );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>The <code>va_arg</code> macro expands to an expression of type <code>T</code> that corresponds to the next parameter from the <code>va_list</code> <code>ap</code>.</p> +<p>Prior to calling <code>va_arg</code>, <code>ap</code> must be initialized by a call to either <code>va_start</code> or <code>va_copy</code>, with no intervening call to <code>va_end</code>. Each invocation of the <code>va_arg</code> macro modifies <code>ap</code> to point to the next variable argument.</p> +<p>If the type of the next argument in <code>ap</code> (after promotions) is not compatible with <code>T</code>, the behavior is undefined, unless:</p> +<ul> +<li> one type is a signed integer type, the other type is the corresponding unsigned integer type, and the value is representable in both types; or </li> +<li> one type is pointer to <code>void</code> and the other is a pointer to a character type. </li> +</ul> <p>If <code>va_arg</code> is called when there are no more arguments in <code>ap</code>, the behavior is undefined.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ap </td> <td> - </td> <td> an instance of the <code>va_list</code> type </td> +</tr> <tr class="t-par"> <td> T </td> <td> - </td> <td> the type of the next parameter in <code>ap</code> </td> +</tr> +</table> <h3 id="Expanded_value"> Expanded value</h3> <p>the next variable parameter in <code>ap</code></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdarg.h> +#include <math.h> + +double stddev(int count, ...) +{ + double sum = 0; + double sum_sq = 0; + va_list args; + va_start(args, count); + for (int i = 0; i < count; ++i) { + double num = va_arg(args, double); + sum += num; + sum_sq += num*num; + } + va_end(args); + return sqrt(sum_sq/count - (sum/count)*(sum/count)); +} + +int main(void) +{ + printf("%f\n", stddev(4, 25.0, 27.3, 26.9, 25.7)); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">0.920258</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.16.1.1 The va_arg macro (p: 269-270) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.15.1.1 The va_arg macro (p: 249-250) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.8.1.2 The va_arg macro </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="va_copy" title="c/variadic/va copy"> <span class="t-lines"><span>va_copy</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> makes a copy of the variadic function arguments <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="va_end" title="c/variadic/va end"> <span class="t-lines"><span>va_end</span></span></a></div> </td> <td> ends traversal of the variadic function arguments <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="va_list" title="c/variadic/va list"> <span class="t-lines"><span>va_list</span></span></a></div> </td> <td> holds the information needed by va_start, va_arg, va_end, and va_copy <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="va_start" title="c/variadic/va start"> <span class="t-lines"><span>va_start</span></span></a></div> </td> <td> enables access to variadic function arguments <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/variadic/va_arg" title="cpp/utility/variadic/va arg">C++ documentation</a></span> for <code>va_arg</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/variadic/va_arg" class="_attribution-link">https://en.cppreference.com/w/c/variadic/va_arg</a> + </p> +</div> diff --git a/devdocs/c/variadic%2Fva_copy.html b/devdocs/c/variadic%2Fva_copy.html new file mode 100644 index 00000000..fe57eb4c --- /dev/null +++ b/devdocs/c/variadic%2Fva_copy.html @@ -0,0 +1,56 @@ + <h1 id="firstHeading" class="firstHeading">va_copy</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdarg.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">void va_copy( va_list dest, va_list src );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> </table> <p>The <code>va_copy</code> macro copies <code>src</code> to <code>dest</code>.</p> +<p><code>va_end</code> should be called on <code>dest</code> before the function returns or any subsequent re-initialization of <code>dest</code> (via calls to <code>va_start</code> or <code>va_copy</code>).</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> dest </td> <td> - </td> <td> an instance of the <code>va_list</code> type to initialize </td> +</tr> <tr class="t-par"> <td> src </td> <td> - </td> <td> the source <code>va_list</code> that will be used to initialize <code>dest</code> </td> +</tr> +</table> <h3 id="Expanded_value"> Expanded value</h3> <p>(none)</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdarg.h> +#include <math.h> + +double sample_stddev(int count, ...) +{ + /* Compute the mean with args1. */ + double sum = 0; + va_list args1; + va_start(args1, count); + va_list args2; + va_copy(args2, args1); /* copy va_list object */ + for (int i = 0; i < count; ++i) { + double num = va_arg(args1, double); + sum += num; + } + va_end(args1); + double mean = sum / count; + + /* Compute standard deviation with args2 and mean. */ + double sum_sq_diff = 0; + for (int i = 0; i < count; ++i) { + double num = va_arg(args2, double); + sum_sq_diff += (num-mean) * (num-mean); + } + va_end(args2); + return sqrt(sum_sq_diff / count); +} + +int main(void) +{ + printf("%f\n", sample_stddev(4, 25.0, 27.3, 26.9, 25.7)); +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">0.920258</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.16.1.2 The va_copy macro (p: 270) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.15.1.2 The va_copy macro (p: 250) </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="va_arg" title="c/variadic/va arg"> <span class="t-lines"><span>va_arg</span></span></a></div> </td> <td> accesses the next variadic function argument <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="va_end" title="c/variadic/va end"> <span class="t-lines"><span>va_end</span></span></a></div> </td> <td> ends traversal of the variadic function arguments <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="va_list" title="c/variadic/va list"> <span class="t-lines"><span>va_list</span></span></a></div> </td> <td> holds the information needed by va_start, va_arg, va_end, and va_copy <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="va_start" title="c/variadic/va start"> <span class="t-lines"><span>va_start</span></span></a></div> </td> <td> enables access to variadic function arguments <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/variadic/va_copy" title="cpp/utility/variadic/va copy">C++ documentation</a></span> for <code>va_copy</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/variadic/va_copy" class="_attribution-link">https://en.cppreference.com/w/c/variadic/va_copy</a> + </p> +</div> diff --git a/devdocs/c/variadic%2Fva_end.html b/devdocs/c/variadic%2Fva_end.html new file mode 100644 index 00000000..d6c1cddf --- /dev/null +++ b/devdocs/c/variadic%2Fva_end.html @@ -0,0 +1,25 @@ + <h1 id="firstHeading" class="firstHeading">va_end</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdarg.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">void va_end( va_list ap );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>The <code>va_end</code> macro performs cleanup for an <code>ap</code> object initialized by a call to <code>va_start</code> or <code>va_copy</code>. <code>va_end</code> may modify <code>ap</code> so that it is no longer usable.</p> +<p>If there is no corresponding call to <code>va_start</code> or <code>va_copy</code>, or if <code>va_end</code> is not called before a function that calls <code>va_start</code> or <code>va_copy</code> returns, the behavior is undefined.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ap </td> <td> - </td> <td> an instance of the <code>va_list</code> type to clean up </td> +</tr> +</table> <h3 id="Expanded_value"> Expanded value</h3> <p>(none)</p> +<h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.16.1.3 The va_end macro (p: 270-271) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.15.1.3 The va_end macro (p: 250-251) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.8.1.3 The va_end macro </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="va_arg" title="c/variadic/va arg"> <span class="t-lines"><span>va_arg</span></span></a></div> </td> <td> accesses the next variadic function argument <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="va_copy" title="c/variadic/va copy"> <span class="t-lines"><span>va_copy</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> makes a copy of the variadic function arguments <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="va_list" title="c/variadic/va list"> <span class="t-lines"><span>va_list</span></span></a></div> </td> <td> holds the information needed by va_start, va_arg, va_end, and va_copy <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="va_start" title="c/variadic/va start"> <span class="t-lines"><span>va_start</span></span></a></div> </td> <td> enables access to variadic function arguments <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/variadic/va_end" title="cpp/utility/variadic/va end">C++ documentation</a></span> for <code>va_end</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/variadic/va_end" class="_attribution-link">https://en.cppreference.com/w/c/variadic/va_end</a> + </p> +</div> diff --git a/devdocs/c/variadic%2Fva_list.html b/devdocs/c/variadic%2Fva_list.html new file mode 100644 index 00000000..507162c4 --- /dev/null +++ b/devdocs/c/variadic%2Fva_list.html @@ -0,0 +1,23 @@ + <h1 id="firstHeading" class="firstHeading">va_list</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdarg.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">/* unspecified */ va_list;</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p><code>va_list</code> is a complete object type suitable for holding the information needed by the macros <code>va_start</code>, <code>va_copy</code>, <code>va_arg</code>, and <code>va_end</code>.</p> +<p>If a <code>va_list</code> instance is created, passed to another function, and used via <code>va_arg</code> in that function, then any subsequent use in the calling function should be preceded by a call to <code>va_end</code>.</p> +<p>It is legal to pass a pointer to a <code>va_list</code> object to another function and then use that object after the function returns.</p> +<h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.16/3 Variable arguments <stdarg.h> (p: 269) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.15/3 Variable arguments <stdarg.h> (p: 249) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.8 VARIABLE ARGUMENTS <stdarg.h> </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="va_arg" title="c/variadic/va arg"> <span class="t-lines"><span>va_arg</span></span></a></div> </td> <td> accesses the next variadic function argument <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="va_copy" title="c/variadic/va copy"> <span class="t-lines"><span>va_copy</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> makes a copy of the variadic function arguments <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="va_end" title="c/variadic/va end"> <span class="t-lines"><span>va_end</span></span></a></div> </td> <td> ends traversal of the variadic function arguments <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="va_start" title="c/variadic/va start"> <span class="t-lines"><span>va_start</span></span></a></div> </td> <td> enables access to variadic function arguments <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/variadic/va_list" title="cpp/utility/variadic/va list">C++ documentation</a></span> for <code>va_list</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/variadic/va_list" class="_attribution-link">https://en.cppreference.com/w/c/variadic/va_list</a> + </p> +</div> diff --git a/devdocs/c/variadic%2Fva_start.html b/devdocs/c/variadic%2Fva_start.html new file mode 100644 index 00000000..8dd8a365 --- /dev/null +++ b/devdocs/c/variadic%2Fva_start.html @@ -0,0 +1,77 @@ + <h1 id="firstHeading" class="firstHeading">va_start</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdarg.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-until-c23"> <td><pre data-language="c">void va_start( va_list ap, parmN );</pre></td> <td class="t-dcl-nopad"> </td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">void va_start( va_list ap, ... );</pre> +</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr> </table> <p>The <code>va_start</code> macro enables access to the variable arguments<span class="t-rev-inl t-until-c23"><span> following the named argument <code>parmN</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span>.</p> +<p><code>va_start</code> shall be invoked with an instance to a valid <code>va_list</code> object <code>ap</code> before any calls to <code>va_arg</code>.</p> +<table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>If <code>parmN</code> is declared with <code>register</code> storage class specifier, with an array type, with a function type, or with a type not compatible with the type that results from default argument promotions, the behavior is undefined.</p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> <tr class="t-rev t-since-c23"> +<td> <p>Only the first argument passed to <code>va_start</code> is evaluated. Any additional arguments are neither expanded nor used in any way.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> ap </td> <td> - </td> <td> an instance of the <code>va_list</code> type </td> +</tr> <tr class="t-par"> <td> parmN </td> <td> - </td> <td> the named parameter preceding the first variable parameter </td> +</tr> +</table> <h3 id="Expanded_value"> Expanded value</h3> <p>(none)</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdarg.h> + +int add_nums_C99(int count, ...) +{ + int result = 0; + va_list args; + va_start(args, count); // count can be omitted since C23 + + for (int i = 0; i < count; ++i) { + result += va_arg(args, int); + } + + va_end(args); + return result; +} + +#if __STDC_VERSION__ > 201710L +// Same as above, valid since C23 +int add_nums_C23(...) +{ + int result = 0; + va_list args; + va_start(args); + + int count = va_arg(args, int); + for (int i = 0; i < count; ++i) { + result += va_arg(args, int); + } + + va_end(args); + return result; +} +#endif + +int main(void) +{ + printf("%d\n", add_nums_C99(4, 25, 25, 50, 50)); +#if __STDC_VERSION__ > 201710L + printf("%d\n", add_nums_C23(4, 25, 25, 50, 50)); +#endif +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">150 +150</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.16.1.4 The va_start macro (p: 198-199) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.16.1.4 The va_start macro (p: 271-272) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.15.1.4 The va_start macro (p: 251-252) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.8.1.1 The va_start macro </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="va_arg" title="c/variadic/va arg"> <span class="t-lines"><span>va_arg</span></span></a></div> </td> <td> accesses the next variadic function argument <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="va_copy" title="c/variadic/va copy"> <span class="t-lines"><span>va_copy</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> makes a copy of the variadic function arguments <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="va_end" title="c/variadic/va end"> <span class="t-lines"><span>va_end</span></span></a></div> </td> <td> ends traversal of the variadic function arguments <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="va_list" title="c/variadic/va list"> <span class="t-lines"><span>va_list</span></span></a></div> </td> <td> holds the information needed by va_start, va_arg, va_end, and va_copy <br> <span class="t-mark">(typedef)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/variadic/va_start" title="cpp/utility/variadic/va start">C++ documentation</a></span> for <code>va_start</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/variadic/va_start" class="_attribution-link">https://en.cppreference.com/w/c/variadic/va_start</a> + </p> +</div> diff --git a/devdocs/c/variadic.html b/devdocs/c/variadic.html new file mode 100644 index 00000000..a824c453 --- /dev/null +++ b/devdocs/c/variadic.html @@ -0,0 +1,62 @@ + <h1 id="firstHeading" class="firstHeading">Variadic functions</h1> <p>Variadic functions are functions (e.g. <code><a href="io/fprintf" title="c/io/fprintf">printf</a></code>) which take a variable number of arguments.</p> +<p>The declaration of a variadic function uses an ellipsis as the last parameter, e.g. <code><span class="kw4">int</span> <a href="http://en.cppreference.com/w/c/io/fprintf"><span class="kw851">printf</span></a><span class="br0">(</span><span class="kw4">const</span> <span class="kw4">char</span><span class="sy2">*</span> format, ...<span class="br0">)</span><span class="sy4">;</span></code>. See <a href="language/variadic" title="c/language/variadic">variadic arguments</a> for additional detail on the syntax and automatic argument conversions.</p> +<p>Accessing the variadic arguments from the function body uses the following library facilities:</p> +<table class="t-dsc-begin"> <tr> <td colspan="2"> <h5 id="Macros"> Macros </h5> </td> +</tr> <tr class="t-dsc-header"> <th colspan="2"> Defined in header <code><stdarg.h></code> </th> +</tr> <tr class="t-dsc"> <td> <div><a href="variadic/va_start" title="c/variadic/va start"> <span class="t-lines"><span>va_start</span></span></a></div> </td> <td> enables access to variadic function arguments <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="variadic/va_arg" title="c/variadic/va arg"> <span class="t-lines"><span>va_arg</span></span></a></div> </td> <td> accesses the next variadic function argument <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="variadic/va_copy" title="c/variadic/va copy"> <span class="t-lines"><span>va_copy</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> makes a copy of the variadic function arguments <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="variadic/va_end" title="c/variadic/va end"> <span class="t-lines"><span>va_end</span></span></a></div> </td> <td> ends traversal of the variadic function arguments <br> <span class="t-mark">(function macro)</span> </td> +</tr> <tr> <td colspan="2"> <h5 id="Type"> Type </h5> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="variadic/va_list" title="c/variadic/va list"> <span class="t-lines"><span>va_list</span></span></a></div> </td> <td> holds the information needed by va_start, va_arg, va_end, and va_copy <br> <span class="t-mark">(typedef)</span> </td> +</tr> </table> <h3 id="Example"> Example</h3> <div class="t-example"> +<p>Print values of different types.</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdarg.h> + +void simple_printf(const char* fmt, ...) +{ + va_list args; + va_start(args, fmt); + + while (*fmt != '\0') { + if (*fmt == 'd') { + int i = va_arg(args, int); + printf("%d\n", i); + } else if (*fmt == 'c') { + // A 'char' variable will be promoted to 'int' + // A character literal in C is already 'int' by itself + int c = va_arg(args, int); + printf("%c\n", c); + } else if (*fmt == 'f') { + double d = va_arg(args, double); + printf("%f\n", d); + } + ++fmt; + } + + va_end(args); +} + +int main(void) +{ + simple_printf("dcff", 3, 'a', 1.999, 42.5); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">3 +a +1.999000 +42.50000</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.16 Variable arguments <stdarg.h> (p: 269-272) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.15 Variable arguments <stdarg.h> (p: 249-252) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.8 VARIABLE ARGUMENTS <stdarg.h> </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/variadic" title="cpp/utility/variadic">C++ documentation</a></span> for <span class=""><span>Variadic functions</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/variadic" class="_attribution-link">https://en.cppreference.com/w/c/variadic</a> + </p> +</div> |