xref: /netbsd-src/external/gpl3/gcc/dist/libstdc++-v3/doc/doxygen/doxygroups.cc (revision b1e838363e3c6fc78a55519254d99869742dd33c)
14fee23f9Smrg /*
2*b1e83836Smrg    Copyright (C) 2001-2022 Free Software Foundation, Inc.
34fee23f9Smrg    See license.html for license.
44fee23f9Smrg 
54fee23f9Smrg    This just provides documentation for stuff that doesn't need to be in the
64fee23f9Smrg    source headers themselves.  It is a ".cc" file for the sole cheesy reason
74fee23f9Smrg    that it triggers many different text editors into doing Nice Things when
84fee23f9Smrg    typing comments.  However, it is mentioned nowhere except the *cfg.in files.
94fee23f9Smrg 
104fee23f9Smrg    Some actual code (declarations) is exposed here, but no compiler ever
114fee23f9Smrg    sees it.  The decls must be visible to doxygen, and sometimes their real
124fee23f9Smrg    declarations are not visible, or not visible in a way we want.
134fee23f9Smrg 
144fee23f9Smrg    Pieces separated by '// //' lines will usually not be presented to the
154fee23f9Smrg    user on the same page.
164fee23f9Smrg */
174fee23f9Smrg 
184fee23f9Smrg // // // // // // // // // // // // // // // // // // // // // // // //
194fee23f9Smrg /** @namespace std
204fee23f9Smrg  *  @brief ISO C++ entities toplevel namespace is std.
214fee23f9Smrg */
22*b1e83836Smrg /** @namespace std::literals
23fb8a8121Smrg  *  @brief ISO C++ inline namespace for literal suffixes.
24fb8a8121Smrg */
254fee23f9Smrg /** @namespace std::__detail
264fee23f9Smrg  *  @brief Implementation details not part of the namespace std interface.
274fee23f9Smrg */
284fee23f9Smrg /** @namespace std::tr1
294fee23f9Smrg  *  @brief ISO C++ TR1 entities toplevel namespace is std::tr1.
304fee23f9Smrg */
314fee23f9Smrg /** @namespace std::tr1::__detail
324fee23f9Smrg  *  @brief Implementation details not part of the namespace std::tr1 interface.
334fee23f9Smrg */
3448fb7bfaSmrg /** @namespace std::tr2
35fb8a8121Smrg  *  @brief Namespace for non-standard "TR2" extensions.
36fb8a8121Smrg  *  @ingroup extensions
3748fb7bfaSmrg */
3848fb7bfaSmrg /** @namespace std::tr2::__detail
3948fb7bfaSmrg  *  @brief Implementation details not part of the namespace std::tr2 interface.
4048fb7bfaSmrg */
414fee23f9Smrg /** @namespace __gnu_cxx
424fee23f9Smrg  *  @brief GNU extensions for public use.
43fb8a8121Smrg  *  @ingroup extensions
444fee23f9Smrg */
454fee23f9Smrg /** @namespace __gnu_cxx::__detail
464fee23f9Smrg  *  @brief Implementation details not part of the namespace __gnu_cxx
474fee23f9Smrg  *  interface.
484fee23f9Smrg */
494fee23f9Smrg /** @namespace __gnu_internal
504fee23f9Smrg  *  @brief GNU implemenation details, not for public use or
514fee23f9Smrg  *  export. Used only when anonymous namespaces cannot be substituted.
524fee23f9Smrg */
53fb8a8121Smrg /** @namespace std::experimental
54fb8a8121Smrg  *  @brief Namespace for features defined in ISO Technical Specifications.
55fb8a8121Smrg  */
564fee23f9Smrg // // // // // // // // // // // // // // // // // // // // // // // //
574fee23f9Smrg 
584fee23f9Smrg /**
594fee23f9Smrg  * @defgroup extensions Extensions
604fee23f9Smrg  *
614fee23f9Smrg  * Components generally useful that are not part of any standard.
624fee23f9Smrg  */
634fee23f9Smrg 
644fee23f9Smrg /** @defgroup SGIextensions SGI
654fee23f9Smrg  * @ingroup extensions
664fee23f9Smrg Because libstdc++ based its implementation of the STL subsections of
674fee23f9Smrg the library on the SGI 3.3 implementation, we inherited their extensions
684fee23f9Smrg as well.
694fee23f9Smrg 
704fee23f9Smrg They are additionally documented in the
714fee23f9Smrg <a href="http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html">
724fee23f9Smrg online documentation</a>, a copy of which is also shipped with the
734fee23f9Smrg library source code (in .../docs/html/documentation.html).  You can also
744fee23f9Smrg read the documentation <a href="http://www.sgi.com/tech/stl/">on SGI's
754fee23f9Smrg site</a>, which is still running even though the code is not maintained.
764fee23f9Smrg 
774fee23f9Smrg <strong>NB</strong> that the following notes are pulled from various
784fee23f9Smrg comments all over the place, so they may seem stilted.
794fee23f9Smrg <hr>
804fee23f9Smrg */
814fee23f9Smrg 
824fee23f9Smrg /** @defgroup containers Containers
834fee23f9Smrg Containers are collections of objects.
844fee23f9Smrg 
854fee23f9Smrg A container may hold any type which meets certain requirements, but the type
864fee23f9Smrg of contained object is chosen at compile time, and all objects in a given
874fee23f9Smrg container must be of the same type.  (Polymorphism is possible by declaring a
884fee23f9Smrg container of pointers to a base class and then populating it with pointers to
894fee23f9Smrg instances of derived classes.  Variant value types such as the @c any class
904fee23f9Smrg from <a href="http://www.boost.org/">Boost</a> can also be used.
914fee23f9Smrg 
924fee23f9Smrg All contained types must be @c Assignable and @c CopyConstructible.
934fee23f9Smrg Specific containers may place additional requirements on the types of
944fee23f9Smrg their contained objects.
954fee23f9Smrg 
964fee23f9Smrg Containers manage memory allocation and deallocation themselves when
974fee23f9Smrg storing your objects.  The objects are destroyed when the container is
984fee23f9Smrg itself destroyed.  Note that if you are storing pointers in a container,
994fee23f9Smrg @c delete is @e not automatically called on the pointers before destroying them.
1004fee23f9Smrg 
1014fee23f9Smrg All containers must meet certain requirements, summarized in
1024fee23f9Smrg <a href="tables.html">tables</a>.
1034fee23f9Smrg 
1044fee23f9Smrg The standard containers are further refined into
1054fee23f9Smrg @link sequences Sequences@endlink and
1064fee23f9Smrg @link associative_containers Associative Containers@endlink.
1074fee23f9Smrg @link unordered_associative_containers Unordered Associative Containers@endlink.
1084fee23f9Smrg */
1094fee23f9Smrg 
1104fee23f9Smrg /** @defgroup sequences Sequences
1114fee23f9Smrg  * @ingroup containers
1124fee23f9Smrg Sequences arrange a collection of objects into a strictly linear order.
1134fee23f9Smrg 
1144fee23f9Smrg The differences between sequences are usually due to one or both of the
1154fee23f9Smrg following:
1164fee23f9Smrg   - memory management
1174fee23f9Smrg   - algorithmic complexity
1184fee23f9Smrg 
1194fee23f9Smrg As an example of the first case, @c vector is required to use a contiguous
1204fee23f9Smrg memory layout, while other sequences such as @c deque are not.
1214fee23f9Smrg 
1224fee23f9Smrg The prime reason for choosing one sequence over another should be based on
1234fee23f9Smrg the second category of differences, algorithmic complexity.  For example, if
1244fee23f9Smrg you need to perform many inserts and removals from the middle of a sequence,
1254fee23f9Smrg @c list would be ideal.  But if you need to perform constant-time access to
1264fee23f9Smrg random elements of the sequence, then @c list should not be used.
1274fee23f9Smrg 
1284fee23f9Smrg All sequences must meet certain requirements, summarized in
1294fee23f9Smrg <a href="tables.html">tables</a>.
1304fee23f9Smrg */
1314fee23f9Smrg 
1324fee23f9Smrg /** @defgroup associative_containers Associative
1334fee23f9Smrg  * @ingroup containers
1344fee23f9Smrg Associative containers allow fast retrieval of data based on keys.
1354fee23f9Smrg 
1364fee23f9Smrg Each container type is parameterized on a @c Key type, and an ordering
1374fee23f9Smrg relation used to sort the elements of the container.
1384fee23f9Smrg 
1394fee23f9Smrg All associative containers must meet certain requirements, summarized in
1404fee23f9Smrg <a href="tables.html">tables</a>.
1414fee23f9Smrg */
1424fee23f9Smrg 
1434fee23f9Smrg /** @defgroup unordered_associative_containers Unordered Associative
1444fee23f9Smrg  * @ingroup containers
1454fee23f9Smrg Unordered associative containers allow fast retrieval of data based on keys.
1464fee23f9Smrg 
1474fee23f9Smrg Each container type is parameterized on a @c Key type, a @c Hash type
1484fee23f9Smrg providing a hashing functor, and an ordering relation used to sort the
1494fee23f9Smrg elements of the container.
1504fee23f9Smrg 
1514fee23f9Smrg All unordered associative containers must meet certain requirements,
1524fee23f9Smrg summarized in <a href="tables.html">tables</a>.  */
1534fee23f9Smrg 
1544fee23f9Smrg /**
1554fee23f9Smrg  * @defgroup diagnostics Diagnostics
1564fee23f9Smrg  *
1574fee23f9Smrg  * Components for error handling, reporting, and diagnostic operations.
1584fee23f9Smrg  */
1594fee23f9Smrg 
1604fee23f9Smrg /**
1614fee23f9Smrg  * @defgroup concurrency Concurrency
1624fee23f9Smrg  *
1634fee23f9Smrg  * Components for concurrent operations, including threads, mutexes,
1644fee23f9Smrg  * and condition variables.
1654fee23f9Smrg  */
166fb8a8121Smrg 
167fb8a8121Smrg /**
168fb8a8121Smrg  * @defgroup experimental Technical Specifications
169fb8a8121Smrg  *
170fb8a8121Smrg  * Components specified by various Technical Specifications.
171fb8a8121Smrg  *
172fb8a8121Smrg  * As indicated by the std::experimental namespace and the header paths,
173fb8a8121Smrg  * the contents of these Technical Specifications are experimental and not
174fb8a8121Smrg  * part of the C++ standard. As such the interfaces and implementations may
175fb8a8121Smrg  * change in the future, and there is <STRONG> no guarantee of compatibility
176fb8a8121Smrg  * between different GCC releases </STRONG> for these features.
177fb8a8121Smrg  */
178