X-Git-Url: https://oss.titaniummirror.com/gitweb?a=blobdiff_plain;f=libstdc%2B%2B-v3%2Fdoc%2Fhtml%2Fmanual%2Fusing_headers.html;fp=libstdc%2B%2B-v3%2Fdoc%2Fhtml%2Fmanual%2Fusing_headers.html;h=be531fb4baf8e7b7f518452356fba03e646daa10;hb=6fed43773c9b0ce596dca5686f37ac3fc0fa11c0;hp=0000000000000000000000000000000000000000;hpb=27b11d56b743098deb193d510b337ba22dc52e5c;p=msp430-gcc.git diff --git a/libstdc++-v3/doc/html/manual/using_headers.html b/libstdc++-v3/doc/html/manual/using_headers.html new file mode 100644 index 00000000..be531fb4 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/using_headers.html @@ -0,0 +1,101 @@ + + +
+ The C++ standard specifies the entire set of header files that
+ must be available to all hosted implementations. Actually, the
+ word "files" is a misnomer, since the contents of the
+ headers don't necessarily have to be in any kind of external
+ file. The only rule is that when one #include
's a
+ header, the contents of that header become available, no matter
+ how.
+
+ That said, in practice files are used. +
+ There are two main types of include files: header files related + to a specific version of the ISO C++ standard (called Standard + Headers), and all others (TR1, C++ ABI, and Extensions). +
+ Two dialects of standard headers are supported, corresponding to + the 1998 standard as updated for 2003, and the draft of the + upcoming 200x standard. +
+ C++98/03 include files. These are available in the default compilation mode, i.e. -std=c++98
or -std=gnu++98
.
+
Table 3.1. C++ 1998 Library Headers
algorithm | bitset | complex | deque | exception |
fstream | functional | iomanip | ios | iosfwd |
iostream | istream | iterator | limits | list |
locale | map | memory | new | numeric |
ostream | queue | set | sstream | stack |
stdexcept | streambuf | string | utility | typeinfo |
valarray | vector | Â | Â | Â |
Table 3.2. C++ 1998 Library Headers for C Library Facilities
cassert | cerrno | cctype | cfloat | ciso646 |
climits | clocale | cmath | csetjmp | csignal |
cstdarg | cstddef | cstdio | cstdlib | cstring |
ctime | cwchar | cwctype | Â | Â |
+C++0x include files. These are only available in C++0x compilation
+mode, i.e. -std=c++0x
or -std=gnu++0x
.
+
Table 3.3. C++ 200x Library Headers
algorithm | array | bitset | chrono | complex |
condition_variable | deque | exception | forward_list | fstream |
functional | initalizer_list | iomanip | ios | iosfwd |
iostream | istream | iterator | limits | list |
locale | map | memory | mutex | new |
numeric | ostream | queue | random | ratio |
regex | set | sstream | stack | stdexcept |
streambuf | string | system_error | thread | tuple |
type_traits | typeinfo | unordered_map | unordered_set | utility |
valarray | vector | Â | Â | Â |
Table 3.4. C++ 200x Library Headers for C Library Facilities
cassert | ccomplex | cctype | cerrno | cfenv |
cfloat | cinttypes | ciso646 | climits | clocale |
cmath | csetjmp | csignal | cstdarg | cstdatomic |
cstdbool | cstddef | cstdint | cstdlib | cstdio |
cstring | ctgmath | ctime | cuchar | cwchar |
cwctype | stdatomic.h | Â | Â | Â |
+ In addition, TR1 includes as: +
Table 3.5. C++ TR1 Library Headers
tr1/array | tr1/complex | tr1/memory | tr1/functional | tr1/random |
tr1/regex | tr1/tuple | tr1/type_traits | tr1/unordered_map | tr1/unordered_set |
tr1/utility | Â | Â | Â | Â |
Table 3.6. C++ TR1 Library Headers for C Library Facilities
tr1/ccomplex | tr1/cfenv | tr1/cfloat | tr1/cmath | tr1/cinttypes |
tr1/climits | tr1/cstdarg | tr1/cstdbool | tr1/cstdint | tr1/cstdio |
tr1/cstdlib | tr1/ctgmath | tr1/ctime | tr1/cwchar | tr1/cwctype |
+ Also included are files for the C++ ABI interface: +
+ And a large variety of extensions. +
Table 3.8. Extension Headers
ext/algorithm | ext/atomicity.h | ext/array_allocator.h | ext/bitmap_allocator.h | ext/cast.h |
ext/codecvt_specializations.h | ext/concurrence.h | ext/debug_allocator.h | ext/enc_filebuf.h | ext/extptr_allocator.h |
ext/functional | ext/iterator | ext/malloc_allocator.h | ext/memory | ext/mt_allocator.h |
ext/new_allocator.h | ext/numeric | ext/numeric_traits.h | ext/pb_ds/assoc_container.h | ext/pb_ds/priority_queue.h |
ext/pod_char_traits.h | ext/pool_allocator.h | ext/rb_tree | ext/rope | ext/slist |
ext/stdio_filebuf.h | ext/stdio_sync_filebuf.h | ext/throw_allocator.h | ext/typelist.h | ext/type_traits.h |
ext/vstring.h | Â | Â | Â | Â |
Table 3.9. Extension Debug Headers
debug/bitset | debug/deque | debug/list | debug/map | debug/set |
debug/string | debug/unordered_map | debug/unordered_set | debug/vector | Â |
A few simple rules. +
First, mixing different dialects of the standard headers is not +possible. It's an all-or-nothing affair. Thus, code like +
+#include <array> +#include <functional> +
Implies C++0x mode. To use the entities in <array>, the C++0x +compilation mode must be used, which implies the C++0x functionality +(and deprecations) in <functional> will be present. +
Second, the other headers can be included with either dialect of
+the standard headers, although features and types specific to C++0x
+are still only enabled when in C++0x compilation mode. So, to use
+rvalue references with __gnu_cxx::vstring
, or to use the
+debug-mode versions of std::unordered_map
, one must use
+the std=gnu++0x
compiler flag. (Or std=c++0x
, of course.)
+
A special case of the second rule is the mixing of TR1 and C++0x +facilities. It is possible (although not especially prudent) to +include both the TR1 version and the C++0x version of header in the +same translation unit: +
+#include <tr1/type_traits> +#include <type_traits> +
Several parts of C++0x diverge quite substantially from TR1 predecessors. +
+ The standard specifies that if one includes the C-style header
+ (<math.h> in this case), the symbols will be available
+ in the global namespace and perhaps in
+ namespace std::
(but this is no longer a firm
+ requirement.) One the other hand, including the C++-style
+ header (<cmath>) guarantees that the entities will be
+ found in namespace std and perhaps in the global namespace.
+
+Usage of C++-style headers is recommended, as then
+C-linkage names can be disambiguated by explicit qualification, such
+as by std::abort
. In addition, the C++-style headers can
+use function overloading to provide a simpler interface to certain
+families of C-functions. For instance in <cmath>, the
+function std::sin
has overloads for all the builtin
+floating-point types. This means that std::sin
can be
+used uniformly, instead of a combination
+of std::sinf
, std::sin
,
+and std::sinl
.
+
There are three base header files that are provided. They can be +used to precompile the standard headers and extensions into binary +files that may the be used to speed compiles that use these headers. +
stdc++.h
Includes all standard headers. Actual content varies depending on +language dialect. +
stdtr1c++.h
Includes all of <stdc++.h>, and adds all the TR1 headers. +
extc++.h
Includes all of <stdtr1c++.h>, and adds all the Extension headers. +
How to construct a .gch file from one of these base header files.
First, find the include directory for the compiler. One way to do +this is:
+g++ -v hello.cc + +#include <...> search starts here: + /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0 +... +End of search list. +
Then, create a precompiled header file with the same flags that +will be used to compile other projects.
+g++ -Winvalid-pch -x c++-header -g -O2 -o ./stdc++.h.gch /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/x86_64-unknown-linux-gnu/bits/stdc++.h +
The resulting file will be quite large: the current size is around +thirty megabytes.
How to use the resulting file.
+g++ -I. -include stdc++.h -H -g -O2 hello.cc +
Verification that the PCH file is being used is easy:
+g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe +! ./stdc++.h.gch +. /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/iostream +. /mnt/share/bld/H-x86-gcc.20071201include/c++/4.3.0/string +
The exclamation point to the left of the stdc++.h.gch
listing means that the generated PCH file was used, and thus the
Detailed information about creating precompiled header files can be found in the GCC documentation. +