]>
Commit | Line | Data |
---|---|---|
77cd227e PE |
1 | |
2 | // This just provides documentation for stuff that doesn't need to be in the | |
3 | // source headers themselves. It is a ".cc" file for the sole cheesy reason | |
4 | // that it triggers many different text editors into doing Nice Things when | |
5 | // typing comments. However, it is mentioned nowhere except the *cfg.in files. | |
729e3d3f PE |
6 | // Pieces separated by '// //' lines will usually not be presented to the |
7 | // user on the same page. | |
77cd227e | 8 | |
729e3d3f PE |
9 | // // // // // // // // // // // // // // // // // // // // // // // // |
10 | /** @addtogroup SGIextensions STL extensions from SGI | |
11 | Because libstdc++-v3 based its implementation of the STL subsections of | |
12 | the library on the SGI 3.3 implementation, we inherited their extensions | |
13 | as well. | |
14 | ||
15 | They are additionally documented in the | |
16 | <a href="http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html"> | |
17 | online documentation</a>, a copy of which is also shipped with the | |
18 | library source code (in .../docs/html/documentation.html). You can also | |
19 | read the documentation <a href="http://www.sgi.com/tech/stl/">on SGI's | |
20 | site</a>, which is still running even though the code is not maintained. | |
21 | ||
22 | <strong>NB</strong> that the following notes are pulled from various | |
23 | comments all over the place, so they may seem stilted. | |
24 | <hr> | |
25 | */ | |
26 | ||
27 | // // // // // // // // // // // // // // // // // // // // // // // // | |
28 | // This is standalone because, unlike the functor introduction, there is no | |
29 | // single header file which serves as a base "all containers must include | |
30 | // this header". We do some quoting of 14882 here. | |
31 | /** @addtogroup Containers Containers | |
32 | Containers are collections of objects. | |
33 | ||
34 | A container may hold any type which meets certain requirements, but the type | |
35 | of contained object is chosen at compile time, and all objects in a given | |
36 | container must be of the same type. (Polymorphism is possible by declaring a | |
37 | container of pointers to a base class and then populating it with pointers to | |
38 | instances of derived classes. Variant value types such as the @c any class | |
39 | from <a href="http://www.boost.org/">Boost</a> can also be used. | |
40 | ||
41 | All contained types must be @c Assignable and @c CopyConstructible. | |
42 | Specific containers may place additional requirements on the types of | |
43 | their contained objects. | |
44 | ||
45 | Containers manage memory allocation and deallocation themselves when | |
46 | storing your objects. The objects are destroyed when the container is | |
47 | itself destroyed. Note that if you are storing pointers in a container, | |
48 | @c delete is @e not automatically called on the pointers before destroying them. | |
49 | ||
50 | All containers must meet certain requirements. They would be listed here | |
51 | except I'm not certain how much of 14882 can be reproduced without a | |
52 | copyright violation. Reproducing Tables 65 through 69 is a lot of typing... | |
53 | ||
54 | The standard containers are further refined into | |
55 | @link Sequences Sequences@endlink and | |
56 | @link Assoc_containers Associative Containers@endlink. | |
77cd227e PE |
57 | */ |
58 | ||
729e3d3f PE |
59 | /** @addtogroup Sequences Sequences |
60 | Sequences arrange a collection of objects into a strictly linear order. | |
61 | ||
62 | The differences between sequences are usually due to one or both of the | |
63 | following: | |
64 | - memory management | |
65 | - algorithmic complexity | |
66 | ||
67 | As an example of the first case, @c vector is required to use a contiguous | |
68 | memory layout, while other sequences such as @c deque are not. | |
69 | ||
70 | The prime reason for chosing one sequence over another should be based on | |
71 | the second category of differences, algorithmic complexity. For example, if | |
72 | you need to perform many inserts and removals from the middle of a sequence, | |
73 | @c list would be ideal. But if you need to perform constant-time access to | |
74 | random elements of the sequence, then @c list should not be used. | |
75 | */ | |
76 | ||
77 | /** @addtogroup Assoc_containers Associative Containers | |
78 | Associative containers allow fast retrieval of data based on keys. | |
79 | ||
80 | Each container type is parameterized on a @c Key type, and an ordering | |
81 | relation used to sort the elements of the container. | |
82 | */ | |
83 | ||
84 | // // // // // // // // // // // // // // // // // // // // // // // // | |
85 |