libstdc++: doxygroups.cc Source File

libstdc++

doxygroups.cc
1/*
2 Copyright (C) 2001-2026 Free Software Foundation, Inc.
3 See license.html for license.
4
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.
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
14 Pieces separated by '// //' lines will usually not be presented to the
15 user on the same page.
16*/
17
18// // // // // // // // // // // // // // // // // // // // // // // //
19/** @namespace std
20 * @brief ISO C++ entities toplevel namespace is std.
21*/
22/** @namespace std::literals
23 * @brief ISO C++ inline namespace for literal suffixes.
24*/
25/** @namespace std::__detail
26 * @brief Implementation details not part of the namespace std interface.
27*/
28/** @namespace std::tr1
29 * @brief ISO C++ TR1 entities toplevel namespace is std::tr1.
30*/
31/** @namespace std::tr1::__detail
32 * @brief Implementation details not part of the namespace std::tr1 interface.
33*/
34/** @namespace std::tr2
35 * @brief Namespace for non-standard "TR2" extensions.
36 * @ingroup extensions
37*/
38/** @namespace std::tr2::__detail
39 * @brief Implementation details not part of the namespace std::tr2 interface.
40*/
41/** @namespace __gnu_cxx
42 * @brief GNU extensions for public use.
43 * @ingroup extensions
44*/
45/** @namespace __gnu_cxx::__detail
46 * @brief Implementation details not part of the namespace __gnu_cxx
47 * interface.
48*/
49/** @namespace __gnu_internal
50 * @brief GNU implemenation details, not for public use or
51 * export. Used only when anonymous namespaces cannot be substituted.
52*/
53/** @namespace std::experimental
54 * @brief Namespace for features defined in ISO Technical Specifications.
55 */
56// // // // // // // // // // // // // // // // // // // // // // // //
57
58/**
59 * @defgroup extensions Extensions
60 *
61 * Components generally useful that are not part of any standard.
62 */
63
64/** @defgroup SGIextensions SGI
65 * @ingroup extensions
66Because libstdc++ based its implementation of the STL subsections of
67the library on the SGI 3.3 implementation, we inherited their extensions
68as well.
69
70They are additionally documented in the
71<a href="http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html">
72online documentation</a>, a copy of which is also shipped with the
73library source code (in .../docs/html/documentation.html). You can also
74read the documentation <a href="http://www.sgi.com/tech/stl/">on SGI's
75site</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
78comments all over the place, so they may seem stilted.
79<hr>
80*/
81
82/** @defgroup containers Containers
83Containers are collections of objects.
84
85A container may hold any type which meets certain requirements, but the type
86of contained object is chosen at compile time, and all objects in a given
87container must be of the same type. (Polymorphism is possible by declaring a
88container of pointers to a base class and then populating it with pointers to
89instances of derived classes. Variant value types such as the @c any class
90from <a href="http://www.boost.org/">Boost</a> can also be used.
91
92All contained types must be @c Assignable and @c CopyConstructible.
93Specific containers may place additional requirements on the types of
94their contained objects.
95
96Containers manage memory allocation and deallocation themselves when
97storing your objects. The objects are destroyed when the container is
98itself 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
101All containers must meet certain requirements, summarized in
102<a href="tables.html">tables</a>.
103
104The standard containers are further refined into
105@link sequences Sequences@endlink and
106@link associative_containers Associative Containers@endlink.
107@link unordered_associative_containers Unordered Associative Containers@endlink.
108*/
109
110/** @defgroup sequences Sequences
111 * @ingroup containers
112Sequences arrange a collection of objects into a strictly linear order.
113
114The differences between sequences are usually due to one or both of the
115following:
116 - memory management
117 - algorithmic complexity
118
119As an example of the first case, @c vector is required to use a contiguous
120memory layout, while other sequences such as @c deque are not.
121
122The prime reason for choosing one sequence over another should be based on
123the second category of differences, algorithmic complexity. For example, if
124you 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
126random elements of the sequence, then @c list should not be used.
127
128All sequences must meet certain requirements, summarized in
129<a href="tables.html">tables</a>.
130*/
131
132/** @defgroup associative_containers Associative
133 * @ingroup containers
134Associative containers allow fast retrieval of data based on keys.
135
136Each container type is parameterized on a @c Key type, and an ordering
137relation used to sort the elements of the container.
138
139All associative containers must meet certain requirements, summarized in
140<a href="tables.html">tables</a>.
141*/
142
143/** @defgroup unordered_associative_containers Unordered Associative
144 * @ingroup containers
145Unordered associative containers allow fast retrieval of data based on keys.
146
147Each container type is parameterized on a @c Key type, a @c Hash type
148providing a hashing functor, and an ordering relation used to sort the
149elements of the container.
150
151All unordered associative containers must meet certain requirements,
152summarized in <a href="tables.html">tables</a>. */
153
154/**
155 * @defgroup diagnostics Diagnostics
156 *
157 * Components for error handling, reporting, and diagnostic operations.
158 */
159
160/**
161 * @defgroup concurrency Concurrency
162 *
163 * Components for concurrent operations, including threads, mutexes,
164 * and condition variables.
165 */
166
167/**
168 * @defgroup variable_templates Variable Templates
169 * @ingroup metaprogramming
170 * @since C++17
171 *
172 * Each trait in `<type_traits>` that has a `value` static data member is
173 * also available as a variable template, using the same name with a `_v`
174 * suffix. For example, `std::is_integral_v<T>` is a `bool` constant with
175 * the same value as `std::is_integral<T>::value`.
176 *
177 * In some cases, using the variable template instead of the `::value` member
178 * avoids instantiating the class template for the trait. This gives the
179 * compiler less work to do and can make your code compile a little faster.
180 */
181
182/**
183 * @defgroup experimental Technical Specifications
184 *
185 * Components specified by various Technical Specifications.
186 *
187 * As indicated by the std::experimental namespace and the header paths,
188 * the contents of these Technical Specifications are experimental and not
189 * part of the C++ standard. As such the interfaces and implementations may
190 * change in the future, and there is <STRONG> no guarantee of compatibility
191 * between different GCC releases </STRONG> for these features.
192 */