depish/cppdraft_translate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Init

Browse Source
This commit is contained in:
Leonov Artur (Depish)
2025-10-25 03:02:53 +03:00
commit 043225d523
3416 changed files with 681196 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

219
cppdraft/headers.md Normal file
View File

@@ -0,0 +1,219 @@
[headers]
# 16 Library introduction [[library]](./#library)
## 16.4 Library-wide requirements [[requirements]](requirements#headers)
### 16.4.2 Library contents and organization [[organization]](organization#headers)
#### 16.4.2.3 Headers [headers]
[1](#1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L1182)
Each element of the C++ standard library is declared or defined (as appropriate) in a[*header*](#def:header "16.4.2.3 Headers [headers]")[.](#1.sentence-1)[144](#footnote-144 "A header is not necessarily a source file, nor are the sequences delimited by < and > in header names necessarily valid source file names ([cpp.include]).")
[2](#2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L1191)
The C++ standard library provides the[*C++ library headers*](#def:header,C++_library "16.4.2.3 Headers [headers]"),
shown in Table [24](#tab:headers.cpp "Table 24: C++ library headers")[.](#2.sentence-1)
Table [24](#tab:headers.cpp) — C++ library headers [[tab:headers.cpp]](./tab:headers.cpp)
| [🔗](#tab:headers.cpp-row-1)<br><algorithm> | <forward_list> | <meta> | <stack> |
| --- | --- | --- | --- |
| [🔗](#tab:headers.cpp-row-2)<br><any> | <fstream> | <mutex> | <stacktrace> |
| [🔗](#tab:headers.cpp-row-3)<br><array> | <functional> | <new> | <stdexcept> |
| [🔗](#tab:headers.cpp-row-4)<br><atomic> | <future> | <numbers> | <stdfloat> |
| [🔗](#tab:headers.cpp-row-5)<br><barrier> | <generator> | <numeric> | <stop_token> |
| [🔗](#tab:headers.cpp-row-6)<br><bit> | <hazard_pointer> | <optional> | <streambuf> |
| [🔗](#tab:headers.cpp-row-7)<br><bitset> | <hive> | <ostream> | <string> |
| [🔗](#tab:headers.cpp-row-8)<br><charconv> | <initializer_list> | <print> | <string_view> |
| [🔗](#tab:headers.cpp-row-9)<br><chrono> | <inplace_vector> | <queue> | <syncstream> |
| [🔗](#tab:headers.cpp-row-10)<br><compare> | <iomanip> | <random> | <system_error> |
| [🔗](#tab:headers.cpp-row-11)<br><complex> | <ios> | <ranges> | <text_encoding> |
| [🔗](#tab:headers.cpp-row-12)<br><concepts> | <iosfwd> | <ratio> | <thread> |
| [🔗](#tab:headers.cpp-row-13)<br><condition_variable> | <iostream> | <rcu> | <tuple> |
| [🔗](#tab:headers.cpp-row-14)<br><contracts> | <istream> | <regex> | <type_traits> |
| [🔗](#tab:headers.cpp-row-15)<br><coroutine> | <iterator> | <scoped_allocator> | <typeindex> |
| [🔗](#tab:headers.cpp-row-16)<br><debugging> | <latch> | <semaphore> | <typeinfo> |
| [🔗](#tab:headers.cpp-row-17)<br><deque> | <limits> | <set> | <unordered_map> |
| [🔗](#tab:headers.cpp-row-18)<br><exception> | <linalg> | <shared_mutex> | <unordered_set> |
| [🔗](#tab:headers.cpp-row-19)<br><execution> | <list> | <simd> | <utility> |
| [🔗](#tab:headers.cpp-row-20)<br><expected> | <locale> | <source_location> | <valarray> |
| [🔗](#tab:headers.cpp-row-21)<br><filesystem> | <map> | <span> | <variant> |
| [🔗](#tab:headers.cpp-row-22)<br><flat_map> | <mdspan> | <spanstream> | <vector> |
| [🔗](#tab:headers.cpp-row-23)<br><flat_set> | <memory> | <sstream> | <version> |
| [🔗](#tab:headers.cpp-row-24)<br><format> | <memory_resource> | | |
[3](#3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L1297)
The facilities of the C standard library are provided in theadditional headers shown in Table [25](#tab:headers.cpp.c "Table 25: C++ headers for C library facilities")[.](#3.sentence-1)[145](#footnote-145 "It is intentional that there is no C++ header for any of these C headers: <stdnoreturn.h>, <threads.h>.")
Table [25](#tab:headers.cpp.c) — C++ headers for C library facilities [[tab:headers.cpp.c]](./tab:headers.cpp.c)
| [🔗](#tab:headers.cpp.c-row-1)<br><cassert> | <cfenv> | <climits> | <csetjmp> | <cstddef> | <cstdlib> | <cuchar> |
| --- | --- | --- | --- | --- | --- | --- |
| [🔗](#tab:headers.cpp.c-row-2)<br><cctype> | <cfloat> | <clocale> | <csignal> | <cstdint> | <cstring> | <cwchar> |
| [🔗](#tab:headers.cpp.c-row-3)<br><cerrno> | <cinttypes> | <cmath> | <cstdarg> | <cstdio> | <ctime> | <cwctype> |
[4](#4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L1339)
The headers listed in Table [24](#tab:headers.cpp "Table 24: C++ library headers"), or,
for a freestanding implementation,
the subset of such headers that are provided by the implementation,
are collectively known as
the [*importable C++ library headers*](#def:C++_library_headers,importable "16.4.2.3 Headers [headers]")[.](#4.sentence-1)
[*Note [1](#note-1)*:
Importable C++ library headers can be
imported ([[module.import]](module.import "10.3 Import declaration"))[.](#4.sentence-2)
— *end note*]
[*Example [1](#example-1)*: import <vector>; // imports the <vector> header unit std::vector<int> vi; // OK — *end example*]
[5](#5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L1356)
Except as noted in [[library]](library "16 Library introduction") through [[exec]](exec "33 Execution control library") and [[depr]](depr "Annex D (normative) Compatibility features"), the contents of each header c*name* is
the same as that of the corresponding header *name*.h as
specified in the [C standard library](intro.refs#def:C,standard_library "2 Normative references [intro.refs]")[.](#5.sentence-1)
In the C++ standard library, however, the
declarations (except for names which are defined as macros in C) are within[namespace scope](basic.scope.namespace "6.4.6 Namespace scope [basic.scope.namespace]") of the namespace std[.](#5.sentence-2)
It is unspecified whether these names (including any overloads added in[[support]](support "17 Language support library") through [[exec]](exec "33 Execution control library") and [[depr]](depr "Annex D (normative) Compatibility features"))
are first declared within the global namespace scope
and are then injected into namespace std by explicit[*using-declaration*](namespace.udecl#nt:using-declaration "9.10 The using declaration [namespace.udecl]")*s* ([[namespace.udecl]](namespace.udecl "9.10 The using declaration"))[.](#5.sentence-3)
[6](#6)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L1370)
Names which are defined as macros in C shall be defined as macros in the C++
standard library, even if C grants license for implementation as functions[.](#6.sentence-1)
[*Note [2](#note-2)*:
The names defined as macros in C include the following:assert, offsetof, setjmp, va_arg,va_end, and va_start[.](#6.sentence-2)
— *end note*]
[7](#7)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L1379)
Names that are defined as functions in C shall be defined as functions in the
C++ standard library[.](#7.sentence-1)[146](#footnote-146 "This disallows the practice, allowed in C, of providing a masking macro in addition to the function prototype. The only way to achieve equivalent inline behavior in C++ is to provide a definition as an extern inline function.")
[8](#8)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L1389)
Identifiers that are keywords or operators in C++ shall not be defined as
macros in C++ standard library headers[.](#8.sentence-1)[147](#footnote-147 "In particular, including the standard header <iso646.h> has no effect.")
[9](#9)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L1397)
Subclause [[support.c.headers]](support.c.headers "17.15 C headers") describes the effects of using
the *name*.h (C header) form in a C++ program[.](#9.sentence-1)[148](#footnote-148 "The &quot;.h&quot; headers dump all their names into the global namespace, whereas the newer forms keep their names in namespace std. Therefore, the newer forms are the preferred forms for all uses except for C++ programs which are intended to be strictly compatible with C.")
[10](#10)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L1408)
ISO/IEC 9899:2024, Annex K describes a large number of functions,
with associated types and macros,
which “promote safer, more secure programming”
than many of the traditional C library functions[.](#10.sentence-1)
The names of the functions have a suffix of _s;
most of them provide the same service
as the C library function with the unsuffixed name,
but generally take an additional argument
whose value is the size of the result array[.](#10.sentence-2)
If any C++ header is included,
it is implementation-defined
whether any of these names
is declared in the global namespace[.](#10.sentence-3)
(None of them is declared in namespace std[.](#10.sentence-4))
[11](#11)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L1425)
Table [26](#tab:c.annex.k.names "Table 26: Names from ISO/IEC 9899:2024, Annex K") lists the Annex K names
that may be declared in some header[.](#11.sentence-1)
These names are also subject to the restrictions of [[macro.names]](macro.names "16.4.5.3.3 Macro names")[.](#11.sentence-2)
Table [26](#tab:c.annex.k.names) — Names from ISO/IEC 9899:2024, Annex K [[tab:c.annex.k.names]](./tab:c.annex.k.names)
| [🔗](#tab:c.annex.k.names-row-1)<br>abort_handler_s | mbstowcs_s | strncat_s | vswscanf_s |
| --- | --- | --- | --- |
| [🔗](#tab:c.annex.k.names-row-2)<br>asctime_s | memcpy_s | strncpy_s | vwprintf_s |
| [🔗](#tab:c.annex.k.names-row-3)<br>bsearch_s | memmove_s | strtok_s | vwscanf_s |
| [🔗](#tab:c.annex.k.names-row-4)<br>constraint_handler_t | memset_s | swprintf_s | wcrtomb_s |
| [🔗](#tab:c.annex.k.names-row-5)<br>ctime_s | printf_s | swscanf_s | wcscat_s |
| [🔗](#tab:c.annex.k.names-row-6)<br>errno_t | qsort_s | tmpfile_s | wcscpy_s |
| [🔗](#tab:c.annex.k.names-row-7)<br>fopen_s | RSIZE_MAX | TMP_MAX_S | wcsncat_s |
| [🔗](#tab:c.annex.k.names-row-8)<br>fprintf_s | rsize_t | tmpnam_s | wcsncpy_s |
| [🔗](#tab:c.annex.k.names-row-9)<br>freopen_s | scanf_s | vfprintf_s | wcsnlen_s |
| [🔗](#tab:c.annex.k.names-row-10)<br>fscanf_s | set_constraint_handler_s | vfscanf_s | wcsrtombs_s |
| [🔗](#tab:c.annex.k.names-row-11)<br>fwprintf_s | snprintf_s | vfwprintf_s | wcstok_s |
| [🔗](#tab:c.annex.k.names-row-12)<br>fwscanf_s | snwprintf_s | vfwscanf_s | wcstombs_s |
| [🔗](#tab:c.annex.k.names-row-13)<br>getenv_s | sprintf_s | vprintf_s | wctomb_s |
| [🔗](#tab:c.annex.k.names-row-14)<br>gets_s | sscanf_s | vscanf_s | wmemcpy_s |
| [🔗](#tab:c.annex.k.names-row-15)<br>gmtime_s | strcat_s | vsnprintf_s | wmemmove_s |
| [🔗](#tab:c.annex.k.names-row-16)<br>ignore_handler_s | strcpy_s | vsnwprintf_s | wprintf_s |
| [🔗](#tab:c.annex.k.names-row-17)<br>localtime_s | strerrorlen_s | vsprintf_s | wscanf_s |
| [🔗](#tab:c.annex.k.names-row-18)<br>L_tmpnam_s | strerror_s | vsscanf_s | |
| [🔗](#tab:c.annex.k.names-row-19)<br>mbsrtowcs_s | strlen_s | vswprintf_s | |
[144)](#footnote-144)[144)](#footnoteref-144)
A header is not necessarily a source file, nor are the
sequences delimited by < and > in header names necessarily valid source
file names ([[cpp.include]](cpp.include "15.3 Source file inclusion"))[.](#footnote-144.sentence-1)
[145)](#footnote-145)[145)](#footnoteref-145)
It is intentional that there is no C++ header
for any of these C headers:<stdnoreturn.h>,<threads.h>[.](#footnote-145.sentence-1)
[146)](#footnote-146)[146)](#footnoteref-146)
This disallows the practice, allowed in C, of
providing a masking macro in addition to the function prototype[.](#footnote-146.sentence-1)
The only way to
achieve equivalent inline behavior in C++ is to provide a definition as an
extern inline function[.](#footnote-146.sentence-2)
[147)](#footnote-147)[147)](#footnoteref-147)
In particular, including the
standard header [<iso646.h>](iso646.h.syn#header:%3ciso646.h%3e "17.15.3 Header <iso646.h> synopsis [iso646.h.syn]") has no effect[.](#footnote-147.sentence-1)
[148)](#footnote-148)[148)](#footnoteref-148)
The".h" headers dump all their names into the global namespace, whereas the
newer forms keep their names in namespace std[.](#footnote-148.sentence-1)
Therefore, the newer
forms are the preferred forms for all uses except for C++ programs which are
intended to be strictly compatible with C[.](#footnote-148.sentence-2)