]>
Commit | Line | Data |
---|---|---|
82b61df5 | 1 | /* |
04b7c941 PE |
2 | Copyright (C) 2001, 2002 Free Software Foundation, Inc. |
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 | |
ffe94f83 PE |
20 | * @brief Everything defined by the ISO C++ Standard is within namespace std. |
21 | */ | |
22 | /** @namespace __gnu_cxx | |
8f94053d | 23 | * @brief This namespace serves two purposes. |
ffe94f83 | 24 | * |
8f94053d | 25 | * This namespace is used for two things: |
ffe94f83 | 26 | * - sequestering internal (implementation-only) names away from the |
8f94053d PE |
27 | * global namespace; these are details of the implementation and should |
28 | * not be touched by users | |
29 | * - GNU extensions for public use | |
ffe94f83 | 30 | * |
8f94053d PE |
31 | * This is still fluid and changing rapidly. Currently the rule is: if an |
32 | * entitity is found in the user-level documentation, it falls into the | |
33 | * second category. | |
5adf72de PE |
34 | */ |
35 | ||
729e3d3f PE |
36 | // // // // // // // // // // // // // // // // // // // // // // // // |
37 | /** @addtogroup SGIextensions STL extensions from SGI | |
38 | Because libstdc++-v3 based its implementation of the STL subsections of | |
39 | the library on the SGI 3.3 implementation, we inherited their extensions | |
40 | as well. | |
41 | ||
42 | They are additionally documented in the | |
43 | <a href="http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html"> | |
44 | online documentation</a>, a copy of which is also shipped with the | |
45 | library source code (in .../docs/html/documentation.html). You can also | |
46 | read the documentation <a href="http://www.sgi.com/tech/stl/">on SGI's | |
47 | site</a>, which is still running even though the code is not maintained. | |
48 | ||
49 | <strong>NB</strong> that the following notes are pulled from various | |
50 | comments all over the place, so they may seem stilted. | |
51 | <hr> | |
52 | */ | |
53 | ||
54 | // // // // // // // // // // // // // // // // // // // // // // // // | |
55 | // This is standalone because, unlike the functor introduction, there is no | |
56 | // single header file which serves as a base "all containers must include | |
57 | // this header". We do some quoting of 14882 here. | |
58 | /** @addtogroup Containers Containers | |
59 | Containers are collections of objects. | |
60 | ||
61 | A container may hold any type which meets certain requirements, but the type | |
62 | of contained object is chosen at compile time, and all objects in a given | |
63 | container must be of the same type. (Polymorphism is possible by declaring a | |
64 | container of pointers to a base class and then populating it with pointers to | |
65 | instances of derived classes. Variant value types such as the @c any class | |
66 | from <a href="http://www.boost.org/">Boost</a> can also be used. | |
67 | ||
68 | All contained types must be @c Assignable and @c CopyConstructible. | |
69 | Specific containers may place additional requirements on the types of | |
70 | their contained objects. | |
71 | ||
72 | Containers manage memory allocation and deallocation themselves when | |
73 | storing your objects. The objects are destroyed when the container is | |
74 | itself destroyed. Note that if you are storing pointers in a container, | |
75 | @c delete is @e not automatically called on the pointers before destroying them. | |
76 | ||
04b7c941 PE |
77 | All containers must meet certain requirements, summarized in |
78 | <a href="tables.html">tables</a>. | |
729e3d3f PE |
79 | |
80 | The standard containers are further refined into | |
81 | @link Sequences Sequences@endlink and | |
82 | @link Assoc_containers Associative Containers@endlink. | |
77cd227e PE |
83 | */ |
84 | ||
729e3d3f PE |
85 | /** @addtogroup Sequences Sequences |
86 | Sequences arrange a collection of objects into a strictly linear order. | |
87 | ||
88 | The differences between sequences are usually due to one or both of the | |
89 | following: | |
90 | - memory management | |
91 | - algorithmic complexity | |
92 | ||
93 | As an example of the first case, @c vector is required to use a contiguous | |
94 | memory layout, while other sequences such as @c deque are not. | |
95 | ||
c5504edb | 96 | The prime reason for choosing one sequence over another should be based on |
729e3d3f PE |
97 | the second category of differences, algorithmic complexity. For example, if |
98 | you need to perform many inserts and removals from the middle of a sequence, | |
99 | @c list would be ideal. But if you need to perform constant-time access to | |
100 | random elements of the sequence, then @c list should not be used. | |
04b7c941 PE |
101 | |
102 | All sequences must meet certain requirements, summarized in | |
103 | <a href="tables.html">tables</a>. | |
729e3d3f PE |
104 | */ |
105 | ||
106 | /** @addtogroup Assoc_containers Associative Containers | |
107 | Associative containers allow fast retrieval of data based on keys. | |
108 | ||
109 | Each container type is parameterized on a @c Key type, and an ordering | |
110 | relation used to sort the elements of the container. | |
04b7c941 PE |
111 | |
112 | There should be more text here. | |
113 | ||
114 | All associative containers must meet certain requirements, summarized in | |
115 | <a href="tables.html">tables</a>. | |
729e3d3f PE |
116 | */ |
117 | ||
118 | // // // // // // // // // // // // // // // // // // // // // // // // | |
efe44c60 PE |
119 | /** @namespace abi |
120 | * @brief The cross-vendor C++ Application Binary Interface. | |
121 | * | |
122 | * A brief overview of an ABI is given in the libstdc++-v3 FAQ, question | |
123 | * 5.8 (you may have a copy of the FAQ locally, or you can view the online | |
124 | * version at http://gcc.gnu.org/onlinedocs/libstdc++/faq/index.html#5_8). | |
125 | * | |
126 | * GCC subscribes to a relatively-new cross-vendor ABI for C++, sometimes | |
127 | * called the IA64 ABI because it happens to be the native ABI for that | |
128 | * platform. It is summarized at http://www.codesourcery.com/cxx-abi/ | |
129 | * along with the current specification. | |
130 | * | |
131 | * For users of GCC 3.x, entry points are available in <cxxabi.h>, which notes, | |
132 | * <em>"It is not normally necessary for user programs to include this header, | |
133 | * or use the entry points directly. However, this header is available | |
134 | * should that be needed."</em> | |
135 | */ | |
136 | ||
137 | namespace abi { | |
138 | /** | |
139 | @brief New ABI-mandated entry point in the C++ runtime library for demangling. | |
140 | ||
141 | @param mangled_name A NUL-terminated character string containing the name | |
142 | to be demangled. | |
143 | ||
144 | @param output_buffer A region of memory, allocated with malloc, of | |
145 | @a *length bytes, into which the demangled name | |
146 | is stored. If @a output_buffer is not long enough, | |
147 | it is expanded using realloc. @a output_buffer may | |
148 | instead be NULL; in that case, the demangled name is | |
149 | placed in a region of memory allocated with malloc. | |
150 | ||
151 | @param length If @a length is non-NULL, the length of the buffer containing | |
152 | the demangled name is placed in @a *length. | |
153 | ||
154 | @param status @a *status is set to one of the following values: | |
155 | - 0: The demangling operation succeeded. | |
156 | - -1: A memory allocation failiure occurred. | |
157 | - -2: @a mangled_name is not a valid name under the C++ ABI | |
158 | mangling rules. | |
159 | - -3: One of the arguments is invalid. | |
160 | ||
161 | @return A pointer to the start of the NUL-terminated demangled name, or NULL | |
162 | if the demangling fails. The caller is responsible for deallocating | |
163 | this memory using @c free. | |
164 | ||
165 | ||
166 | The demagling is performed using the C++ ABI mangling rules, with | |
167 | GNU extensions. For example, this function is used | |
168 | in __gnu_cxx::__verbose_terminate_handler. See | |
169 | http://gcc.gnu.org/onlinedocs/libstdc++/18_support/howto.html#5 for other | |
170 | examples of use. | |
171 | ||
172 | @note The same demangling functionality is available via libiberty | |
173 | (@c <libiberty/demangle.h> and @c libiberty.a) in GCC 3.1 and later, but that | |
174 | requires explicit installation (@c --enable-install-libiberty) and uses a | |
175 | different API, although the ABI is unchanged. | |
176 | */ | |
177 | char* __cxa_demangle (const char* mangled_name, char* output_buffer, | |
178 | size_t* length, int* status); | |
179 | } // namespace abi | |
180 | ||
bf551f96 PE |
181 | // // // // // // // // // // // // // // // // // // // // // // // // |
182 | /** @addtogroup binarysearch Binary search algorithms | |
183 | These algorithms are variations of a classic binary search. They all assume | |
184 | that the sequence being searched is already sorted. | |
185 | ||
186 | The number of comparisons will be logarithmic (and as few as possible). | |
187 | The number of steps through the sequence will be logarithmic for | |
188 | random-access iterators (e.g., pointers), and linear otherwise. | |
189 | ||
190 | The LWG has passed Defect Report 270, which notes: <em>The proposed | |
191 | resolution reinterprets binary search. Instead of thinking about searching | |
192 | for a value in a sorted range, we view that as an important special | |
193 | case of a more general algorithm: searching for the partition point in a | |
194 | partitioned range. We also add a guarantee that the old wording did not: | |
195 | we ensure that the upper bound is no earlier than the lower bound, that | |
196 | the pair returned by equal_range is a valid range, and that the first part | |
197 | of that pair is the lower bound.</em> | |
198 | ||
199 | The actual effect of the first sentence is that a comparison functor | |
200 | passed by the user doesn't necessarily need to induce a strict weak ordering | |
201 | relation. Rather, it partitions the range. | |
202 | */ | |
203 | ||
204 | // // // // // // // // // // // // // // // // // // // // // // // // | |
205 | ||
206 | // // // // // // // // // // // // // // // // // // // // // // // // | |
207 | /* * @addtogroup groupname description of group | |
208 | placeholder text | |
209 | */ | |
210 | ||
efe44c60 PE |
211 | // // // // // // // // // // // // // // // // // // // // // // // // |
212 | ||
213 | // vim:et:noai: | |
729e3d3f | 214 |