]>
Commit | Line | Data |
---|---|---|
82b61df5 | 1 | /* |
aac2878e | 2 | Copyright (C) 2001, 2002, 2005, 2008, 2009 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 BK |
21 | */ |
22 | /** @namespace std::__detail | |
939759fc | 23 | * @brief Implementation details not part of the namespace std interface. |
ffe94f83 | 24 | */ |
0aa06b18 | 25 | /** @namespace std::tr1 |
939759fc | 26 | * @brief ISO C++ TR1 entities toplevel namespace is std::tr1. |
78a53887 BK |
27 | */ |
28 | /** @namespace std::tr1::__detail | |
29 | * @brief Implementation details not part of the namespace std::tr1 interface. | |
0aa06b18 | 30 | */ |
ad68e9fc BK |
31 | /** @namespace std::chrono |
32 | * @brief ISO C++ 0x entities sub namespace for time and date. | |
939759fc BK |
33 | */ |
34 | /** @namespace std::placeholders | |
35 | * @brief ISO C++ 0x entities sub namespace for functional. | |
36 | */ | |
ad68e9fc BK |
37 | /** @namespace std::regex_constants |
38 | * @brief ISO C++ 0x entities sub namespace for regex. | |
39 | */ | |
68a97d24 BK |
40 | /** @namespace std::this_thread |
41 | * @brief ISO C++ 0x entities sub namespace for thread. | |
42 | */ | |
ffe94f83 | 43 | /** @namespace __gnu_cxx |
861e48cb BK |
44 | * @brief GNU extensions for public use. |
45 | */ | |
78a53887 | 46 | /** @namespace __gnu_cxx::__detail |
939759fc | 47 | * @brief Implementation details not part of the namespace __gnu_cxx |
78a53887 BK |
48 | * interface. |
49 | */ | |
861e48cb | 50 | /** @namespace __gnu_internal |
78a53887 BK |
51 | * @brief GNU implemenation details, not for public use or |
52 | * export. Used only when anonymous namespaces cannot be substituted. | |
861e48cb | 53 | */ |
729e3d3f | 54 | // // // // // // // // // // // // // // // // // // // // // // // // |
aac2878e BK |
55 | /** @namespace abi |
56 | * @brief The cross-vendor C++ Application Binary Interface. A | |
57 | * namespace alias to __cxxabiv1. | |
58 | * | |
59 | * A brief overview of an ABI is given in the libstdc++ FAQ, question | |
60 | * 5.8 (you may have a copy of the FAQ locally, or you can view the online | |
61 | * version at http://gcc.gnu.org/onlinedocs/libstdc++/faq/index.html#5_8). | |
62 | * | |
63 | * GCC subscribes to a relatively-new cross-vendor ABI for C++, sometimes | |
64 | * called the IA64 ABI because it happens to be the native ABI for that | |
65 | * platform. It is summarized at http://www.codesourcery.com/cxx-abi/ | |
66 | * along with the current specification. | |
67 | * | |
68 | * For users of GCC greater than or equal to 3.x, entry points are | |
69 | * available in <cxxabi.h>, which notes, <em>"It is not normally | |
70 | * necessary for user programs to include this header, or use the | |
71 | * entry points directly. However, this header is available should | |
72 | * that be needed."</em> | |
73 | */ | |
74 | ||
75 | namespace abi { | |
76 | /** | |
77 | @brief New ABI-mandated entry point in the C++ runtime library for demangling. | |
78 | ||
79 | @param mangled_name A NUL-terminated character string containing the name | |
80 | to be demangled. | |
81 | ||
82 | @param output_buffer A region of memory, allocated with malloc, of | |
83 | @a *length bytes, into which the demangled name | |
84 | is stored. If @a output_buffer is not long enough, | |
85 | it is expanded using realloc. @a output_buffer may | |
86 | instead be NULL; in that case, the demangled name is | |
87 | placed in a region of memory allocated with malloc. | |
88 | ||
89 | @param length If @a length is non-NULL, the length of the buffer containing | |
90 | the demangled name is placed in @a *length. | |
91 | ||
92 | @param status @a *status is set to one of the following values: | |
93 | - 0: The demangling operation succeeded. | |
94 | - -1: A memory allocation failiure occurred. | |
95 | - -2: @a mangled_name is not a valid name under the C++ ABI | |
96 | mangling rules. | |
97 | - -3: One of the arguments is invalid. | |
98 | ||
99 | @return A pointer to the start of the NUL-terminated demangled name, or NULL | |
100 | if the demangling fails. The caller is responsible for deallocating | |
101 | this memory using @c free. | |
102 | ||
103 | ||
104 | The demangling is performed using the C++ ABI mangling rules, with | |
105 | GNU extensions. For example, this function is used | |
106 | in __gnu_cxx::__verbose_terminate_handler. See | |
107 | http://gcc.gnu.org/onlinedocs/libstdc++/18_support/howto.html#5 for other | |
108 | examples of use. | |
109 | ||
110 | @note The same demangling functionality is available via libiberty | |
111 | (@c <libiberty/demangle.h> and @c libiberty.a) in GCC 3.1 and later, but that | |
112 | requires explicit installation (@c --enable-install-libiberty) and uses a | |
113 | different API, although the ABI is unchanged. | |
114 | */ | |
115 | char* __cxa_demangle (const char* mangled_name, char* output_buffer, | |
116 | size_t* length, int* status); | |
117 | } // namespace abi | |
118 | ||
119 | // // // // // // // // // // // // // // // // // // // // // // // // | |
120 | ||
121 | /** | |
122 | * @defgroup extensions Extensions | |
123 | * | |
124 | * Components generally useful that are not part of any standard. | |
125 | */ | |
126 | ||
127 | /** @defgroup SGIextensions SGI STL extensions | |
128 | * @ingroup extensions | |
78a53887 | 129 | Because libstdc++ based its implementation of the STL subsections of |
729e3d3f PE |
130 | the library on the SGI 3.3 implementation, we inherited their extensions |
131 | as well. | |
132 | ||
133 | They are additionally documented in the | |
134 | <a href="http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html"> | |
135 | online documentation</a>, a copy of which is also shipped with the | |
136 | library source code (in .../docs/html/documentation.html). You can also | |
137 | read the documentation <a href="http://www.sgi.com/tech/stl/">on SGI's | |
138 | site</a>, which is still running even though the code is not maintained. | |
139 | ||
140 | <strong>NB</strong> that the following notes are pulled from various | |
141 | comments all over the place, so they may seem stilted. | |
142 | <hr> | |
143 | */ | |
144 | ||
145 | // // // // // // // // // // // // // // // // // // // // // // // // | |
146 | // This is standalone because, unlike the functor introduction, there is no | |
147 | // single header file which serves as a base "all containers must include | |
148 | // this header". We do some quoting of 14882 here. | |
aac2878e | 149 | /** @defgroup containers Containers |
729e3d3f PE |
150 | Containers are collections of objects. |
151 | ||
152 | A container may hold any type which meets certain requirements, but the type | |
153 | of contained object is chosen at compile time, and all objects in a given | |
154 | container must be of the same type. (Polymorphism is possible by declaring a | |
155 | container of pointers to a base class and then populating it with pointers to | |
156 | instances of derived classes. Variant value types such as the @c any class | |
157 | from <a href="http://www.boost.org/">Boost</a> can also be used. | |
158 | ||
159 | All contained types must be @c Assignable and @c CopyConstructible. | |
160 | Specific containers may place additional requirements on the types of | |
161 | their contained objects. | |
162 | ||
163 | Containers manage memory allocation and deallocation themselves when | |
164 | storing your objects. The objects are destroyed when the container is | |
165 | itself destroyed. Note that if you are storing pointers in a container, | |
166 | @c delete is @e not automatically called on the pointers before destroying them. | |
167 | ||
04b7c941 PE |
168 | All containers must meet certain requirements, summarized in |
169 | <a href="tables.html">tables</a>. | |
729e3d3f PE |
170 | |
171 | The standard containers are further refined into | |
172 | @link Sequences Sequences@endlink and | |
173 | @link Assoc_containers Associative Containers@endlink. | |
aac2878e | 174 | @link Unordered_assoc_containers Unordered Associative Containers@endlink. |
77cd227e PE |
175 | */ |
176 | ||
aac2878e BK |
177 | /** @defgroup sequences Sequences |
178 | * @ingroup containers | |
729e3d3f PE |
179 | Sequences arrange a collection of objects into a strictly linear order. |
180 | ||
181 | The differences between sequences are usually due to one or both of the | |
182 | following: | |
183 | - memory management | |
184 | - algorithmic complexity | |
185 | ||
186 | As an example of the first case, @c vector is required to use a contiguous | |
187 | memory layout, while other sequences such as @c deque are not. | |
188 | ||
c5504edb | 189 | The prime reason for choosing one sequence over another should be based on |
729e3d3f PE |
190 | the second category of differences, algorithmic complexity. For example, if |
191 | you need to perform many inserts and removals from the middle of a sequence, | |
192 | @c list would be ideal. But if you need to perform constant-time access to | |
193 | random elements of the sequence, then @c list should not be used. | |
04b7c941 PE |
194 | |
195 | All sequences must meet certain requirements, summarized in | |
196 | <a href="tables.html">tables</a>. | |
729e3d3f PE |
197 | */ |
198 | ||
aac2878e BK |
199 | /** @defgroup associative_containers Associative Containers |
200 | * @ingroup containers | |
729e3d3f PE |
201 | Associative containers allow fast retrieval of data based on keys. |
202 | ||
203 | Each container type is parameterized on a @c Key type, and an ordering | |
204 | relation used to sort the elements of the container. | |
04b7c941 | 205 | |
04b7c941 PE |
206 | All associative containers must meet certain requirements, summarized in |
207 | <a href="tables.html">tables</a>. | |
729e3d3f PE |
208 | */ |
209 | ||
aac2878e BK |
210 | /** @defgroup unordered_associative_containers Unordered Associative Containers |
211 | * @ingroup containers | |
212 | Unordered associative containers allow fast retrieval of data based on keys. | |
efe44c60 | 213 | |
aac2878e BK |
214 | Each container type is parameterized on a @c Key type, a @c Hash type |
215 | providing a hashing functor, and an ordering relation used to sort the | |
216 | elements of the container. | |
efe44c60 | 217 | |
aac2878e BK |
218 | All unordered associative containers must meet certain requirements, |
219 | summarized in <a href="tables.html">tables</a>. */ | |
119dbb1f | 220 | |
bf551f96 | 221 | // // // // // // // // // // // // // // // // // // // // // // // // |
aac2878e | 222 | /* * @defgroup groupname description of group |
bf551f96 PE |
223 | placeholder text |
224 | */ | |
225 | ||
efe44c60 | 226 | // // // // // // // // // // // // // // // // // // // // // // // // |