]>
Commit | Line | Data |
---|---|---|
82b61df5 | 1 | /* |
a945c346 | 2 | Copyright (C) 2001-2024 Free Software Foundation, Inc. |
04b7c941 PE |
3 | See license.html for license. |
4 | ||
82b61df5 PE |
5 | This just provides documentation for stuff that doesn't need to be in the |
6 | source headers themselves. It is a ".cc" file for the sole cheesy reason | |
7 | that it triggers many different text editors into doing Nice Things when | |
8 | typing comments. However, it is mentioned nowhere except the *cfg.in files. | |
efe44c60 PE |
9 | |
10 | Some actual code (declarations) is exposed here, but no compiler ever | |
11 | sees it. The decls must be visible to doxygen, and sometimes their real | |
12 | declarations are not visible, or not visible in a way we want. | |
13 | ||
82b61df5 PE |
14 | Pieces separated by '// //' lines will usually not be presented to the |
15 | user on the same page. | |
16 | */ | |
77cd227e | 17 | |
5adf72de PE |
18 | // // // // // // // // // // // // // // // // // // // // // // // // |
19 | /** @namespace std | |
939759fc | 20 | * @brief ISO C++ entities toplevel namespace is std. |
78a53887 | 21 | */ |
f2ce64b5 | 22 | /** @namespace std::literals |
c34d3fd3 JW |
23 | * @brief ISO C++ inline namespace for literal suffixes. |
24 | */ | |
78a53887 | 25 | /** @namespace std::__detail |
939759fc | 26 | * @brief Implementation details not part of the namespace std interface. |
ffe94f83 | 27 | */ |
0aa06b18 | 28 | /** @namespace std::tr1 |
939759fc | 29 | * @brief ISO C++ TR1 entities toplevel namespace is std::tr1. |
78a53887 BK |
30 | */ |
31 | /** @namespace std::tr1::__detail | |
32 | * @brief Implementation details not part of the namespace std::tr1 interface. | |
0aa06b18 | 33 | */ |
c3b0bfe1 | 34 | /** @namespace std::tr2 |
19aaf814 JW |
35 | * @brief Namespace for non-standard "TR2" extensions. |
36 | * @ingroup extensions | |
c3b0bfe1 BK |
37 | */ |
38 | /** @namespace std::tr2::__detail | |
39 | * @brief Implementation details not part of the namespace std::tr2 interface. | |
40 | */ | |
ffe94f83 | 41 | /** @namespace __gnu_cxx |
861e48cb | 42 | * @brief GNU extensions for public use. |
19aaf814 | 43 | * @ingroup extensions |
861e48cb | 44 | */ |
78a53887 | 45 | /** @namespace __gnu_cxx::__detail |
f2ce64b5 | 46 | * @brief Implementation details not part of the namespace __gnu_cxx |
78a53887 BK |
47 | * interface. |
48 | */ | |
861e48cb | 49 | /** @namespace __gnu_internal |
78a53887 BK |
50 | * @brief GNU implemenation details, not for public use or |
51 | * export. Used only when anonymous namespaces cannot be substituted. | |
861e48cb | 52 | */ |
19aaf814 JW |
53 | /** @namespace std::experimental |
54 | * @brief Namespace for features defined in ISO Technical Specifications. | |
55 | */ | |
aac2878e BK |
56 | // // // // // // // // // // // // // // // // // // // // // // // // |
57 | ||
58 | /** | |
59 | * @defgroup extensions Extensions | |
60 | * | |
61 | * Components generally useful that are not part of any standard. | |
62 | */ | |
63 | ||
5ab3a5af | 64 | /** @defgroup SGIextensions SGI |
aac2878e | 65 | * @ingroup extensions |
78a53887 | 66 | Because libstdc++ based its implementation of the STL subsections of |
729e3d3f PE |
67 | the library on the SGI 3.3 implementation, we inherited their extensions |
68 | as well. | |
69 | ||
70 | They are additionally documented in the | |
71 | <a href="http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html"> | |
72 | online documentation</a>, a copy of which is also shipped with the | |
73 | library source code (in .../docs/html/documentation.html). You can also | |
74 | read the documentation <a href="http://www.sgi.com/tech/stl/">on SGI's | |
75 | site</a>, which is still running even though the code is not maintained. | |
76 | ||
77 | <strong>NB</strong> that the following notes are pulled from various | |
78 | comments all over the place, so they may seem stilted. | |
79 | <hr> | |
80 | */ | |
81 | ||
aac2878e | 82 | /** @defgroup containers Containers |
729e3d3f PE |
83 | Containers are collections of objects. |
84 | ||
85 | A container may hold any type which meets certain requirements, but the type | |
86 | of contained object is chosen at compile time, and all objects in a given | |
87 | container must be of the same type. (Polymorphism is possible by declaring a | |
88 | container of pointers to a base class and then populating it with pointers to | |
89 | instances of derived classes. Variant value types such as the @c any class | |
90 | from <a href="http://www.boost.org/">Boost</a> can also be used. | |
91 | ||
92 | All contained types must be @c Assignable and @c CopyConstructible. | |
93 | Specific containers may place additional requirements on the types of | |
94 | their contained objects. | |
95 | ||
96 | Containers manage memory allocation and deallocation themselves when | |
97 | storing your objects. The objects are destroyed when the container is | |
98 | itself destroyed. Note that if you are storing pointers in a container, | |
99 | @c delete is @e not automatically called on the pointers before destroying them. | |
100 | ||
04b7c941 PE |
101 | All containers must meet certain requirements, summarized in |
102 | <a href="tables.html">tables</a>. | |
729e3d3f PE |
103 | |
104 | The standard containers are further refined into | |
5b9daa7e BK |
105 | @link sequences Sequences@endlink and |
106 | @link associative_containers Associative Containers@endlink. | |
107 | @link unordered_associative_containers Unordered Associative Containers@endlink. | |
77cd227e PE |
108 | */ |
109 | ||
aac2878e BK |
110 | /** @defgroup sequences Sequences |
111 | * @ingroup containers | |
729e3d3f PE |
112 | Sequences arrange a collection of objects into a strictly linear order. |
113 | ||
114 | The differences between sequences are usually due to one or both of the | |
115 | following: | |
116 | - memory management | |
117 | - algorithmic complexity | |
118 | ||
119 | As an example of the first case, @c vector is required to use a contiguous | |
120 | memory layout, while other sequences such as @c deque are not. | |
121 | ||
c5504edb | 122 | The prime reason for choosing one sequence over another should be based on |
729e3d3f PE |
123 | the second category of differences, algorithmic complexity. For example, if |
124 | you need to perform many inserts and removals from the middle of a sequence, | |
125 | @c list would be ideal. But if you need to perform constant-time access to | |
126 | random elements of the sequence, then @c list should not be used. | |
04b7c941 PE |
127 | |
128 | All sequences must meet certain requirements, summarized in | |
129 | <a href="tables.html">tables</a>. | |
729e3d3f PE |
130 | */ |
131 | ||
5ab3a5af | 132 | /** @defgroup associative_containers Associative |
aac2878e | 133 | * @ingroup containers |
729e3d3f PE |
134 | Associative containers allow fast retrieval of data based on keys. |
135 | ||
136 | Each container type is parameterized on a @c Key type, and an ordering | |
137 | relation used to sort the elements of the container. | |
04b7c941 | 138 | |
04b7c941 PE |
139 | All associative containers must meet certain requirements, summarized in |
140 | <a href="tables.html">tables</a>. | |
729e3d3f PE |
141 | */ |
142 | ||
5ab3a5af | 143 | /** @defgroup unordered_associative_containers Unordered Associative |
aac2878e BK |
144 | * @ingroup containers |
145 | Unordered associative containers allow fast retrieval of data based on keys. | |
efe44c60 | 146 | |
aac2878e BK |
147 | Each container type is parameterized on a @c Key type, a @c Hash type |
148 | providing a hashing functor, and an ordering relation used to sort the | |
149 | elements of the container. | |
efe44c60 | 150 | |
aac2878e BK |
151 | All unordered associative containers must meet certain requirements, |
152 | summarized in <a href="tables.html">tables</a>. */ | |
119dbb1f | 153 | |
5b9daa7e BK |
154 | /** |
155 | * @defgroup diagnostics Diagnostics | |
156 | * | |
157 | * Components for error handling, reporting, and diagnostic operations. | |
158 | */ | |
bf551f96 | 159 | |
5b9daa7e BK |
160 | /** |
161 | * @defgroup concurrency Concurrency | |
162 | * | |
163 | * Components for concurrent operations, including threads, mutexes, | |
164 | * and condition variables. | |
165 | */ | |
1ababc8b JW |
166 | |
167 | /** | |
168 | * @defgroup experimental Technical Specifications | |
169 | * | |
170 | * Components specified by various Technical Specifications. | |
171 | * | |
172 | * As indicated by the std::experimental namespace and the header paths, | |
173 | * the contents of these Technical Specifications are experimental and not | |
174 | * part of the C++ standard. As such the interfaces and implementations may | |
175 | * change in the future, and there is <STRONG> no guarantee of compatibility | |
176 | * between different GCC releases </STRONG> for these features. | |
177 | */ |