From 18246cedb54858482e28e44693f7459528f2714e Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Wed, 21 Apr 2010 23:33:44 +0000 Subject: [PATCH] faq.xml: Link to manual. 2010-04-22 Jonathan Wakely * doc/xml/faq.xml: Link to manual. * doc/xml/manual/using.xml: Expand dynamic libraries section. * doc/xml/manual/strings.xml: Mention shrink_to_fit() member. * doc/xml/manual/prerequisites.xml: Link to doxygen requirements. * doc/xml/manual/appendix_contributing.xml: Update Bash version. * doc/html/*: Regenerate. From-SVN: r158624 --- libstdc++-v3/ChangeLog | 9 + libstdc++-v3/doc/html/api.html | 35 +- libstdc++-v3/doc/html/bk02.html | 2 +- libstdc++-v3/doc/html/bk03.html | 2 +- libstdc++-v3/doc/html/faq.html | 16 +- libstdc++-v3/doc/html/manual/abi.html | 157 ++-- libstdc++-v3/doc/html/manual/algorithms.html | 60 +- libstdc++-v3/doc/html/manual/api.html | 14 +- .../html/manual/appendix_contributing.html | 54 +- .../doc/html/manual/appendix_free.html | 12 +- .../doc/html/manual/appendix_gfdl.html | 8 +- .../doc/html/manual/appendix_gpl.html | 12 +- .../doc/html/manual/appendix_porting.html | 12 +- libstdc++-v3/doc/html/manual/associative.html | 113 ++- libstdc++-v3/doc/html/manual/atomics.html | 31 + libstdc++-v3/doc/html/manual/auto_ptr.html | 90 --- libstdc++-v3/doc/html/manual/backwards.html | 211 +++-- .../doc/html/manual/bitmap_allocator.html | 14 +- libstdc++-v3/doc/html/manual/bitset.html | 105 --- libstdc++-v3/doc/html/manual/bk01ix01.html | 51 -- libstdc++-v3/doc/html/manual/bk01pt02.html | 46 ++ .../doc/html/manual/bk01pt02ch04s02.html | 49 -- .../doc/html/manual/bk01pt02ch04s03.html | 29 - ...bk01pt03ch08.html => bk01pt02ch05s02.html} | 9 +- .../doc/html/manual/bk01pt02pr01.html | 17 - .../doc/html/manual/bk01pt03ch07s02.html | 20 - .../doc/html/manual/bk01pt03ch07s03.html | 4 - ...1pt12ch30s02.html => bk01pt03ch17s02.html} | 6 +- .../doc/html/manual/bk01pt03ch17s03.html | 24 + ...1pt12ch30s04.html => bk01pt03ch17s04.html} | 32 +- ...1pt12ch31s02.html => bk01pt03ch18s02.html} | 4 +- ...1pt12ch31s03.html => bk01pt03ch18s03.html} | 6 +- ...1pt12ch31s04.html => bk01pt03ch18s04.html} | 10 +- ...1pt12ch31s05.html => bk01pt03ch18s05.html} | 8 +- ...1pt12ch32s02.html => bk01pt03ch19s02.html} | 22 +- ...1pt12ch32s03.html => bk01pt03ch19s03.html} | 4 +- ...1pt12ch32s04.html => bk01pt03ch19s04.html} | 4 +- ...1pt12ch32s05.html => bk01pt03ch19s05.html} | 14 +- ...1pt12ch32s06.html => bk01pt03ch19s06.html} | 16 +- ...1pt12ch32s07.html => bk01pt03ch19s07.html} | 100 +-- ...1pt12ch34s02.html => bk01pt03ch21s02.html} | 6 +- ...1pt12ch34s03.html => bk01pt03ch21s03.html} | 4 +- ...1pt12ch41s02.html => bk01pt03ch28s02.html} | 6 +- ...1pt12ch41s03.html => bk01pt03ch28s03.html} | 7 +- .../{bk01pt12pr03.html => bk01pt03pr01.html} | 14 +- libstdc++-v3/doc/html/manual/bk01pt04.html | 21 + .../doc/html/manual/bk01pt05ch13.html | 90 --- .../doc/html/manual/bk01pt05ch13s02.html | 40 - .../doc/html/manual/bk01pt05ch13s03.html | 57 -- .../doc/html/manual/bk01pt05ch13s04.html | 79 -- .../doc/html/manual/bk01pt05ch13s05.html | 16 - .../doc/html/manual/bk01pt05ch13s06.html | 94 --- .../doc/html/manual/bk01pt08ch19.html | 39 - .../doc/html/manual/bk01pt08ch19s02.html | 86 --- .../doc/html/manual/bk01pt09ch20.html | 19 - .../doc/html/manual/bk01pt09pr02.html | 41 - .../doc/html/manual/bk01pt10ch23s02.html | 19 - .../doc/html/manual/bk01pt11ch25s02.html | 77 -- .../doc/html/manual/bk01pt11ch27s02.html | 101 --- .../doc/html/manual/bk01pt11ch28s02.html | 49 -- .../doc/html/manual/bk01pt12ch30s03.html | 24 - libstdc++-v3/doc/html/manual/bugs.html | 270 +++---- libstdc++-v3/doc/html/manual/codecvt.html | 379 --------- libstdc++-v3/doc/html/manual/complex.html | 25 - libstdc++-v3/doc/html/manual/concurrency.html | 42 + libstdc++-v3/doc/html/manual/configure.html | 258 +++---- libstdc++-v3/doc/html/manual/containers.html | 54 +- .../doc/html/manual/containers_and_c.html | 20 +- libstdc++-v3/doc/html/manual/debug.html | 33 +- libstdc++-v3/doc/html/manual/debug_mode.html | 8 +- libstdc++-v3/doc/html/manual/diagnostics.html | 42 +- .../doc/html/manual/documentation_style.html | 76 +- .../doc/html/manual/dynamic_memory.html | 15 +- libstdc++-v3/doc/html/manual/exceptions.html | 22 - .../doc/html/manual/ext_algorithms.html | 10 +- .../doc/html/manual/ext_allocators.html | 80 +- .../doc/html/manual/ext_compile_checks.html | 6 +- .../doc/html/manual/ext_concurrency.html | 16 +- .../doc/html/manual/ext_containers.html | 6 +- .../doc/html/manual/ext_demangling.html | 8 +- libstdc++-v3/doc/html/manual/ext_io.html | 58 +- .../doc/html/manual/ext_iterators.html | 6 +- .../doc/html/manual/ext_numerics.html | 6 +- .../doc/html/manual/ext_utilities.html | 14 +- libstdc++-v3/doc/html/manual/extensions.html | 8 +- libstdc++-v3/doc/html/manual/facets.html | 723 +++++++++++++++++- libstdc++-v3/doc/html/manual/fstreams.html | 114 ++- libstdc++-v3/doc/html/manual/functors.html | 15 - .../doc/html/manual/fundamental_types.html | 43 -- .../generalized_numeric_operations.html | 11 +- libstdc++-v3/doc/html/manual/internals.html | 86 +-- libstdc++-v3/doc/html/manual/intro.html | 2 +- libstdc++-v3/doc/html/manual/io.html | 120 ++- libstdc++-v3/doc/html/manual/io_and_c.html | 54 +- .../doc/html/manual/iostream_objects.html | 119 --- libstdc++-v3/doc/html/manual/iterators.html | 129 +++- libstdc++-v3/doc/html/manual/license.html | 4 +- libstdc++-v3/doc/html/manual/locales.html | 428 ----------- .../doc/html/manual/localization.html | 438 ++++++++++- libstdc++-v3/doc/html/manual/memory.html | 511 +++++++++++-- libstdc++-v3/doc/html/manual/messages.html | 284 ------- libstdc++-v3/doc/html/manual/numerics.html | 29 +- .../doc/html/manual/numerics_and_c.html | 22 +- libstdc++-v3/doc/html/manual/pairs.html | 11 +- .../doc/html/manual/parallel_mode.html | 10 +- .../doc/html/manual/profile_mode.html | 22 +- libstdc++-v3/doc/html/manual/sequences.html | 43 -- libstdc++-v3/doc/html/manual/setup.html | 18 +- libstdc++-v3/doc/html/manual/shared_ptr.html | 304 -------- .../doc/html/manual/source_code_style.html | 92 +-- .../doc/html/manual/source_organization.html | 12 +- libstdc++-v3/doc/html/manual/spine.html | 40 +- libstdc++-v3/doc/html/manual/status.html | 28 +- libstdc++-v3/doc/html/manual/streambufs.html | 83 +- libstdc++-v3/doc/html/manual/strings.html | 365 ++++++++- .../doc/html/manual/stringstreams.html | 10 +- libstdc++-v3/doc/html/manual/support.html | 129 +++- libstdc++-v3/doc/html/manual/termination.html | 104 ++- libstdc++-v3/doc/html/manual/test.html | 10 +- libstdc++-v3/doc/html/manual/traits.html | 6 +- libstdc++-v3/doc/html/manual/using.html | 4 +- .../doc/html/manual/using_concurrency.html | 2 +- .../html/manual/using_dynamic_or_shared.html | 26 +- .../doc/html/manual/using_exceptions.html | 91 ++- .../doc/html/manual/using_headers.html | 12 +- .../doc/html/manual/using_macros.html | 10 +- libstdc++-v3/doc/html/manual/utilities.html | 16 +- libstdc++-v3/doc/html/manual/vector.html | 13 - .../doc/html/manual/verbose_termination.html | 79 -- libstdc++-v3/doc/html/spine.html | 38 +- libstdc++-v3/doc/xml/faq.xml | 10 +- .../doc/xml/manual/appendix_contributing.xml | 2 +- libstdc++-v3/doc/xml/manual/prerequisites.xml | 6 + libstdc++-v3/doc/xml/manual/strings.xml | 4 + libstdc++-v3/doc/xml/manual/using.xml | 28 +- 135 files changed, 4338 insertions(+), 4205 deletions(-) create mode 100644 libstdc++-v3/doc/html/manual/atomics.html delete mode 100644 libstdc++-v3/doc/html/manual/auto_ptr.html delete mode 100644 libstdc++-v3/doc/html/manual/bitset.html delete mode 100644 libstdc++-v3/doc/html/manual/bk01ix01.html create mode 100644 libstdc++-v3/doc/html/manual/bk01pt02.html delete mode 100644 libstdc++-v3/doc/html/manual/bk01pt02ch04s02.html delete mode 100644 libstdc++-v3/doc/html/manual/bk01pt02ch04s03.html rename libstdc++-v3/doc/html/manual/{bk01pt03ch08.html => bk01pt02ch05s02.html} (61%) delete mode 100644 libstdc++-v3/doc/html/manual/bk01pt02pr01.html delete mode 100644 libstdc++-v3/doc/html/manual/bk01pt03ch07s02.html delete mode 100644 libstdc++-v3/doc/html/manual/bk01pt03ch07s03.html rename libstdc++-v3/doc/html/manual/{bk01pt12ch30s02.html => bk01pt03ch17s02.html} (92%) create mode 100644 libstdc++-v3/doc/html/manual/bk01pt03ch17s03.html rename libstdc++-v3/doc/html/manual/{bk01pt12ch30s04.html => bk01pt03ch17s04.html} (96%) rename libstdc++-v3/doc/html/manual/{bk01pt12ch31s02.html => bk01pt03ch18s02.html} (82%) rename libstdc++-v3/doc/html/manual/{bk01pt12ch31s03.html => bk01pt03ch18s03.html} (95%) rename libstdc++-v3/doc/html/manual/{bk01pt12ch31s04.html => bk01pt03ch18s04.html} (95%) rename libstdc++-v3/doc/html/manual/{bk01pt12ch31s05.html => bk01pt03ch18s05.html} (84%) rename libstdc++-v3/doc/html/manual/{bk01pt12ch32s02.html => bk01pt03ch19s02.html} (86%) rename libstdc++-v3/doc/html/manual/{bk01pt12ch32s03.html => bk01pt03ch19s03.html} (80%) rename libstdc++-v3/doc/html/manual/{bk01pt12ch32s04.html => bk01pt03ch19s04.html} (80%) rename libstdc++-v3/doc/html/manual/{bk01pt12ch32s05.html => bk01pt03ch19s05.html} (88%) rename libstdc++-v3/doc/html/manual/{bk01pt12ch32s06.html => bk01pt03ch19s06.html} (89%) rename libstdc++-v3/doc/html/manual/{bk01pt12ch32s07.html => bk01pt03ch19s07.html} (94%) rename libstdc++-v3/doc/html/manual/{bk01pt12ch34s02.html => bk01pt03ch21s02.html} (89%) rename libstdc++-v3/doc/html/manual/{bk01pt12ch34s03.html => bk01pt03ch21s03.html} (92%) rename libstdc++-v3/doc/html/manual/{bk01pt12ch41s02.html => bk01pt03ch28s02.html} (92%) rename libstdc++-v3/doc/html/manual/{bk01pt12ch41s03.html => bk01pt03ch28s03.html} (63%) rename libstdc++-v3/doc/html/manual/{bk01pt12pr03.html => bk01pt03pr01.html} (81%) create mode 100644 libstdc++-v3/doc/html/manual/bk01pt04.html delete mode 100644 libstdc++-v3/doc/html/manual/bk01pt05ch13.html delete mode 100644 libstdc++-v3/doc/html/manual/bk01pt05ch13s02.html delete mode 100644 libstdc++-v3/doc/html/manual/bk01pt05ch13s03.html delete mode 100644 libstdc++-v3/doc/html/manual/bk01pt05ch13s04.html delete mode 100644 libstdc++-v3/doc/html/manual/bk01pt05ch13s05.html delete mode 100644 libstdc++-v3/doc/html/manual/bk01pt05ch13s06.html delete mode 100644 libstdc++-v3/doc/html/manual/bk01pt08ch19.html delete mode 100644 libstdc++-v3/doc/html/manual/bk01pt08ch19s02.html delete mode 100644 libstdc++-v3/doc/html/manual/bk01pt09ch20.html delete mode 100644 libstdc++-v3/doc/html/manual/bk01pt09pr02.html delete mode 100644 libstdc++-v3/doc/html/manual/bk01pt10ch23s02.html delete mode 100644 libstdc++-v3/doc/html/manual/bk01pt11ch25s02.html delete mode 100644 libstdc++-v3/doc/html/manual/bk01pt11ch27s02.html delete mode 100644 libstdc++-v3/doc/html/manual/bk01pt11ch28s02.html delete mode 100644 libstdc++-v3/doc/html/manual/bk01pt12ch30s03.html delete mode 100644 libstdc++-v3/doc/html/manual/codecvt.html delete mode 100644 libstdc++-v3/doc/html/manual/complex.html create mode 100644 libstdc++-v3/doc/html/manual/concurrency.html delete mode 100644 libstdc++-v3/doc/html/manual/exceptions.html delete mode 100644 libstdc++-v3/doc/html/manual/functors.html delete mode 100644 libstdc++-v3/doc/html/manual/fundamental_types.html delete mode 100644 libstdc++-v3/doc/html/manual/iostream_objects.html delete mode 100644 libstdc++-v3/doc/html/manual/locales.html delete mode 100644 libstdc++-v3/doc/html/manual/messages.html delete mode 100644 libstdc++-v3/doc/html/manual/sequences.html delete mode 100644 libstdc++-v3/doc/html/manual/shared_ptr.html delete mode 100644 libstdc++-v3/doc/html/manual/vector.html delete mode 100644 libstdc++-v3/doc/html/manual/verbose_termination.html diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index d34b55a8362..841dd99d7f6 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,12 @@ +2010-04-22 Jonathan Wakely + + * doc/xml/faq.xml: Link to manual. + * doc/xml/manual/using.xml: Expand dynamic libraries section. + * doc/xml/manual/strings.xml: Mention shrink_to_fit() member. + * doc/xml/manual/prerequisites.xml: Link to doxygen requirements. + * doc/xml/manual/appendix_contributing.xml: Update Bash version. + * doc/html/*: Regenerate. + 2010-04-13 Ian Lance Taylor * include/backward/hash_map: Don't #include "backward_warning.h" diff --git a/libstdc++-v3/doc/html/api.html b/libstdc++-v3/doc/html/api.html index 61ddda971a2..5a40764298d 100644 --- a/libstdc++-v3/doc/html/api.html +++ b/libstdc++-v3/doc/html/api.html @@ -1,24 +1,25 @@ -API and Source Level Documentation
API and Source Level Documentation
Prev  Next

API and Source Level Documentation

Copyright © +API Documentation

API Documentation
Prev  Next

API Documentation

Copyright © 2008 + , + 2010 FSF -

-The GNU C++ library sources have been specially formatted so that with the -proper invocation of another tool (Doxygen), a set of HTML pages -are generated from the sources files themselves. The resultant -documentation is referred to as Source Level Documentation, and is -useful for examining the signatures of public member functions for -the library classes, finding out what is in a particular include -file, looking at inheritance diagrams, etc. + The GNU C++ library sources have been specially formatted so that + with the proper invocation of another tool (Doxygen), a set of + indexed reference material can generated from the sources files + themselves. The resultant documentation is referred to as the API + documentation, and is useful for examining the signatures of public + member functions for the library classes, finding out what is in a + particular include file, looking at inheritance diagrams, etc.

-The source-level documentation for the most recent releases can be -viewed online: + The API documentation, rendered into HTML, can be viewed online:

  • for the 3.4 release @@ -39,16 +40,14 @@ viewed online: (For the main development tree; see the date on the first page.)

-This generated HTML collection, as above, is also available for download in the libstdc++ snapshots directory at + The rendered HTML, as above, is also available for download on the + gcc.org site in a directory located at <URL:ftp://gcc.gnu.org/pub/gcc/libstdc++/doxygen/>. You will almost certainly need to use one of the mirror sites to download - the tarball. After unpacking, simply load libstdc++-html-*/index.html + the tarball. After unpacking, simply load libstdc++-html-*/index.html into a browser.

-Documentation for older releases is available for download only, not -online viewing. -

-In addition, an initial set of man pages are also available in the -same place as the HTML collections. Start with C++Intro(3). + In addition, a rendered set of man pages are available in the same + location specified above. Start with C++Intro(3).

Prev Up Next
 Home 
diff --git a/libstdc++-v3/doc/html/bk02.html b/libstdc++-v3/doc/html/bk02.html index f0dbebb2ac4..16ac5f094f6 100644 --- a/libstdc++-v3/doc/html/bk02.html +++ b/libstdc++-v3/doc/html/bk02.html @@ -1,3 +1,3 @@ -
Prev   Next

Table of Contents

API and Source Level Documentation
Prev   Next
Backwards Compatibility Home API and Source Level Documentation
+
Prev   Next

Table of Contents

API Documentation
Prev   Next
Backwards Compatibility Home API Documentation
diff --git a/libstdc++-v3/doc/html/bk03.html b/libstdc++-v3/doc/html/bk03.html index bc43c8d07bb..89beabfeb26 100644 --- a/libstdc++-v3/doc/html/bk03.html +++ b/libstdc++-v3/doc/html/bk03.html @@ -1,3 +1,3 @@ -
Prev   Next

Table of Contents

Frequently Asked Questions
Prev   Next
API and Source Level Documentation Home Frequently Asked Questions
+
Prev   Next

Table of Contents

Frequently Asked Questions
Prev   Next
API Documentation Home Frequently Asked Questions
diff --git a/libstdc++-v3/doc/html/faq.html b/libstdc++-v3/doc/html/faq.html index 31ba54106aa..046cbb3bc83 100644 --- a/libstdc++-v3/doc/html/faq.html +++ b/libstdc++-v3/doc/html/faq.html @@ -4,7 +4,7 @@ 2008 FSF -

1. General Information
1.1. +

1. General Information
1.1. What is libstdc++?
1.2. Why should I use libstdc++? @@ -315,12 +315,15 @@ and ldconfig for more information. The dynamic linker has different names on different platforms but the man page is usually called something such as ld.so/rtld/dld.so. +

+ Using LD_LIBRARY_PATH is not always the best solution, Finding Dynamic or Shared + Libraries in the manual gives some alternatives.

3.5.

What's libsupc++?

If the only functions from libstdc++.a which you need are language support functions (those listed in - clause 18 of the + clause 18 of the standard, e.g., new and delete), then try linking against libsupc++.a, which is a subset of @@ -647,8 +650,9 @@ typo, or wrong visibility, or you just plain forgot, etc).

More information, including how to optionally enable/disable the - checks, is available - here. + checks, is available in the + Diagnostics. + chapter of the manual.

6.6.

Program crashes when using library code in a dynamically-loaded library @@ -685,7 +689,7 @@ list::size() is O(n)!

See - the Containers + the Containers chapter.

6.9.

Aw, that's easy to fix! @@ -869,6 +873,6 @@     

The copy will take O(n) time and the swap is constant time.

- See Shrink-to-fit + See Shrink-to-fit strings for a similar solution for strings.

Prev Up 
 Home 
diff --git a/libstdc++-v3/doc/html/manual/abi.html b/libstdc++-v3/doc/html/manual/abi.html index 25d0a568ee6..618da46367b 100644 --- a/libstdc++-v3/doc/html/manual/abi.html +++ b/libstdc++-v3/doc/html/manual/abi.html @@ -8,12 +8,12 @@ C++ applications often dependent on specific language support routines, say for throwing exceptions, or catching exceptions, and perhaps also dependent on features in the C++ Standard Library. -

+

The C++ Standard Library has many include files, types defined in those include files, specific named functions, and other behavior. The text of these behaviors, as written in source include files, is called the Application Programing Interface, or API. -

+

Furthermore, C++ source that is compiled into object files is transformed by the compiler: it arranges objects with specific alignment and in a particular layout, mangling names according to a @@ -32,7 +32,7 @@ -fno-exceptions, but include others: see the complete list in the GCC manual under the heading Options for Code Generation Conventions. -

+

The configure options used when building a specific libstdc++ version may also impact the resulting library ABI. The available configure options, and their impact on the library ABI, are @@ -240,11 +240,11 @@ int main() %g++ hello.cc -o hello.out %ldd hello.out - libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000) - libm.so.6 => /lib/tls/libm.so.6 (0x004a8000) - libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000) - libc.so.6 => /lib/tls/libc.so.6 (0x0036d000) - /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) + libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000) + libm.so.6 => /lib/tls/libm.so.6 (0x004a8000) + libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000) + libc.so.6 => /lib/tls/libc.so.6 (0x0036d000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) %nm hello.out

@@ -273,7 +273,7 @@ class that would otherwise have implicit versions. This will change the way the compiler deals with this class in by-value return statements or parameters: instead of being passing instances of this class in registers, the compiler will be forced to use memory. See this part - of the C++ ABI documentation for further details. + of the C++ ABI documentation for further details.

Implementation

  1. Separation of interface and implementation

    @@ -298,7 +298,7 @@ class in registers, the compiler will be forced to use memory. See wchar_t instantiations, and includes basic_string, the locale facets, and the types in iostreams. -

+

In addition, these techniques have the additional benefit that they reduce binary size, which can increase runtime performance.

  • @@ -329,7 +329,7 @@ standard includes.

    • <

    Testing the C++ compiler ABI can be done various ways.

    - One. Intel ABI checker. + One. Intel ABI checker.

    Two. The second is yet unreleased, but has been announced on the gcc @@ -344,16 +344,16 @@ discussed on the gcc mailing lists.

    Testing the C++ library ABI can also be done various ways.

    -One. -(Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways, +One. +(Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways, one with a new compiler and an old library, and the other with an old compiler and a new library, and look for testsuite regressions)

    Details on how to set this kind of test up can be found here: http://gcc.gnu.org/ml/gcc/2002-08/msg00142.html

    -Two. -Use the 'make check-abi' rule in the libstdc++ Makefile. +Two. +Use the 'make check-abi' rule in the libstdc++ Makefile.

    This is a proactive check the library ABI. Currently, exported symbol names that are either weak or defined are checked against a last known @@ -372,7 +372,7 @@ machinery.

    This dataset is insufficient, yet a start. Also needed is a comprehensive check for all user-visible types part of the standard -library for sizeof() and alignof() changes. +library for sizeof() and alignof() changes.

    Verifying compatible layouts of objects is not even attempted. It should be possible to use sizeof, alignof, and offsetof to compute @@ -403,7 +403,7 @@ exceptions, locale, etc. %$bld/H-x86-gcc-3.4.0/bin/g++ -c a.cc -%ar cru libone.a a.o +%ar cru libone.a a.o

    And, libtwo is constructed as follows: 

     %$bld/H-x86-gcc-3.3.3/bin/g++ -fPIC -DPIC -c b.cc
 
@@ -413,24 +413,24 @@ exceptions, locale, etc.
 
 %$bld/H-x86-gcc-3.3.3/bin/g++ -c b.cc
 
-%ar cru libtwo.a b.o 
+%ar cru libtwo.a b.o

    ...with the resulting libraries looking like 

     
 %ldd libone.so.1.0.0
-        libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40016000)
-        libm.so.6 => /lib/tls/libm.so.6 (0x400fa000)
-        libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000)
-        libc.so.6 => /lib/tls/libc.so.6 (0x40125000)
-        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
+	libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40016000)
+	libm.so.6 => /lib/tls/libm.so.6 (0x400fa000)
+	libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000)
+	libc.so.6 => /lib/tls/libc.so.6 (0x40125000)
+	/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
 
 %ldd libtwo.so.1.0.0
-        libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x40027000)
-        libm.so.6 => /lib/tls/libm.so.6 (0x400e1000)
-        libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000)
-        libc.so.6 => /lib/tls/libc.so.6 (0x4010c000)
-        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
+	libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x40027000)
+	libm.so.6 => /lib/tls/libm.so.6 (0x400e1000)
+	libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000)
+	libc.so.6 => /lib/tls/libc.so.6 (0x4010c000)
+	/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
 
-

    +

    Then, the "C" compiler is used to compile a source file that uses functions from each library. 

    @@ -440,18 +440,18 @@ gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so.
 
     
 %ldd a.out
-        libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000)
-        libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40015000)
-        libc.so.6 => /lib/tls/libc.so.6 (0x0036d000)
-        libm.so.6 => /lib/tls/libm.so.6 (0x004a8000)
-        libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000)
-        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
+	libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000)
+	libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40015000)
+	libc.so.6 => /lib/tls/libc.so.6 (0x0036d000)
+	libm.so.6 => /lib/tls/libm.so.6 (0x004a8000)
+	libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000)
+	/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
 
 
    
   This resulting binary, when executed, will be able to safely use
   code from both liba, and the dependent libstdc++.so.6, and libb,
   with the dependent libstdc++.so.5.
-

    Outstanding Issues

    +

    Outstanding Issues

    Some features in the C++ language make versioning especially difficult. In particular, compiler generated constructs such as implicit instantiations for templates, typeinfo information, and @@ -464,60 +464,71 @@ gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so. 24660: versioning weak symbols in libstdc++

    19664: libstdc++ headers should have pop/push of the visibility around the declarations -

    Bibliography

    - ABIcheck, a vague idea of checking ABI compatibility - . +

    Bibliography

    + + ABIcheck, a vague idea of checking ABI compatibility + - .

    - C++ ABI Reference - . + .

    + + C++ ABI Reference + - .

    - Intel® Compilers for Linux* -Compatibility with the GNU Compilers - . + .

    + + Intel Compilers for Linux Compatibility with the GNU Compilers + - .

    - Sun Solaris 2.9 : Linker and Libraries Guide (document 816-1386) - . + .

    + + Sun Solaris 2.9 : Linker and Libraries Guide (document 816-1386) + - .

    - Sun Solaris 2.9 : C++ Migration Guide (document 816-2459) - . + .

    + + Sun Solaris 2.9 : C++ Migration Guide (document 816-2459) + - .

    - How to Write Shared Libraries - . Ulrich Drepper. + .

    + + How to Write Shared Libraries + - .

    - C++ ABI for the ARM Architecture - . + . Ulrich Drepper.

    + + C++ ABI for the ARM Architecture + - .

    - Dynamic Shared Objects: Survey and Issues - . - ISO C++ J16/06-0046 - . Benjamin Kosnik. + .

    + + Dynamic Shared Objects: Survey and Issues + - .

    - Versioning With Namespaces - . - ISO C++ J16/06-0083 - . Benjamin Kosnik. + . + ISO C++ J16/06-0046 + . Benjamin Kosnik.

    + + Versioning With Namespaces + - .

    - Binary Compatibility of Shared Libraries Implemented in C++ on GNU/Linux Systems - . -SYRCoSE 2009 - . Pavel Shved. Denis Silakov. + . + ISO C++ J16/06-0083 + . Benjamin Kosnik.

    + + Binary Compatibility of Shared Libraries Implemented in C++ + on GNU/Linux Systems + - .

    Prev Up Next
    Test Home API Evolution and Deprecation History
    + . + SYRCoSE 2009 + . Pavel Shved. Denis Silakov.

    Prev Up Next
    Test Home API Evolution and Deprecation History
    diff --git a/libstdc++-v3/doc/html/manual/algorithms.html b/libstdc++-v3/doc/html/manual/algorithms.html index 6049cd8ec0e..3e5b3a5a86e 100644 --- a/libstdc++-v3/doc/html/manual/algorithms.html +++ b/libstdc++-v3/doc/html/manual/algorithms.html @@ -1,9 +1,61 @@ -Part IX.  Algorithms
    Part IX.  +Chapter 11.  Algorithms
    Chapter 11.  Algorithms -
    Prev The GNU C++ Library Next

    Part IX.  +

    Prev Part II.  + Standard Contents + Next

    Chapter 11.  Algorithms - -

    Table of Contents

    20. Mutating
    swap
    Specializations
    Prev Up Next
    One Past the End Home 
    + +

    Table of Contents

    Mutating
    swap

    + The neatest accomplishment of the algorithms sect1 is that all the + work is done via iterators, not containers directly. This means two + important things: +

    1. + Anything that behaves like an iterator can be used in one of + these algorithms. Raw pointers make great candidates, thus + built-in arrays are fine containers, as well as your own + iterators. +

    2. + The algorithms do not (and cannot) affect the container as a + whole; only the things between the two iterator endpoints. If + you pass a range of iterators only enclosing the middle third of + a container, then anything outside that range is inviolate. +

    + Even strings can be fed through the algorithms here, although the + string class has specialized versions of many of these functions + (for example, string::find()). Most of the examples + on this page will use simple arrays of integers as a playground + for algorithms, just to keep things simple. The use of + N as a size in the examples is to keep things + easy to read but probably won't be valid code. You can use wrappers + such as those described in + the containers sect1 to keep + real code readable. +

    + The single thing that trips people up the most is the definition + of range used with iterators; the famous + "past-the-end" rule that everybody loves to hate. The + iterators sect1 of this + document has a complete explanation of this simple rule that seems + to cause so much confusion. Once you + get range into your head (it's not that hard, + honest!), then the algorithms are a cakewalk. +

    Mutating

    swap

    Specializations

    If you call std::swap(x,y); where x and y are standard + containers, then the call will automatically be replaced by a call to + x.swap(y); instead. +

    This allows member functions of each container class to take over, and + containers' swap functions should have O(1) complexity according to + the standard. (And while "should" allows implementations to + behave otherwise and remain compliant, this implementation does in + fact use constant-time swaps.) This should not be surprising, since + for two containers of the same type to swap contents, only some + internal pointers to storage need to be exchanged. +

    Prev Up Next
    Chapter 10.  + Iterators + + Home Chapter 12.  + Numerics + +
    diff --git a/libstdc++-v3/doc/html/manual/api.html b/libstdc++-v3/doc/html/manual/api.html index 0b70a4cb1bc..a8b88b7d5a9 100644 --- a/libstdc++-v3/doc/html/manual/api.html +++ b/libstdc++-v3/doc/html/manual/api.html @@ -30,8 +30,8 @@ Removal of ext/tree, moved to backward/strstream.h.

    Allocator changes. Change __malloc_alloc to malloc_allocator and __new_alloc to new_allocator.

    For GCC releases from 2.95 through the 3.1 series, defining __USE_MALLOC on the gcc command line would change the default allocation strategy to instead use malloc and - free. (This same functionality is now spelled _GLIBCXX_FORCE_NEW, see - this page + free. (This same functionality is now spelled _GLIBCXX_FORCE_NEW, see + this page for details.

    Error handling in iostreams cleaned up, made consistent.

    3.3

    3.4

    @@ -75,11 +75,11 @@ _Alloc_traits have been removed. __alloc to select an underlying allocator that satisfied memory allocation requests. The selection of this underlying allocator was not user-configurable. -

    Table B.1. Extension Allocators

    Allocator (3.4)Header (3.4)Allocator (3.[0-3])Header (3.[0-3])
    __gnu_cxx::new_allocator<T>ext/new_allocator.hstd::__new_allocmemory
    __gnu_cxx::malloc_allocator<T>ext/malloc_allocator.hstd::__malloc_alloc_template<int>memory
    __gnu_cxx::debug_allocator<T>ext/debug_allocator.hstd::debug_alloc<T>memory
    __gnu_cxx::__pool_alloc<T>ext/pool_allocator.hstd::__default_alloc_template<bool,int>memory
    __gnu_cxx::__mt_alloc<T>ext/mt_allocator.h
    __gnu_cxx::bitmap_allocator<T>ext/bitmap_allocator.h

    Releases after gcc-3.4 have continued to add to the collection +

    Table B.1. Extension Allocators

    Allocator (3.4)Header (3.4)Allocator (3.[0-3])Header (3.[0-3])
    __gnu_cxx::new_allocator<T>ext/new_allocator.hstd::__new_allocmemory
    __gnu_cxx::malloc_allocator<T>ext/malloc_allocator.hstd::__malloc_alloc_template<int>memory
    __gnu_cxx::debug_allocator<T>ext/debug_allocator.hstd::debug_alloc<T>memory
    __gnu_cxx::__pool_alloc<T>ext/pool_allocator.hstd::__default_alloc_template<bool,int>memory
    __gnu_cxx::__mt_alloc<T>ext/mt_allocator.h
    __gnu_cxx::bitmap_allocator<T>ext/bitmap_allocator.h

    Releases after gcc-3.4 have continued to add to the collection of available allocators. All of these new allocators are standard-style. The following table includes details, along with the first released version of GCC that included the extension allocator. -

    Table B.2. Extension Allocators Continued

    AllocatorIncludeVersion
    __gnu_cxx::array_allocator<T>ext/array_allocator.h4.0.0
    __gnu_cxx::throw_allocator<T>ext/throw_allocator.h4.2.0

    +

    Table B.2. Extension Allocators Continued

    AllocatorIncludeVersion
    __gnu_cxx::array_allocator<T>ext/array_allocator.h4.0.0
    __gnu_cxx::throw_allocator<T>ext/throw_allocator.h4.2.0

    Debug mode first appears.

    Precompiled header support PCH support. @@ -143,13 +143,13 @@ Debug mode for unordered_map and tuple and - functional. + functional.

    Default what implementations give more elaborate exception strings for bad_cast, bad_typeid, bad_exception, and bad_alloc.

    -PCH binary files no longer installed. Instead, the source files are installed. +PCH binary files no longer installed. Instead, the source files are installed.

    Namespace pb_ds moved to __gnu_pb_ds.

    4.4

    @@ -227,7 +227,7 @@ C++0X features.

    Profile mode first appears.

    -Support for decimal floating-point arithmetic, including decimal32, decimal64, and decimal128. +Support for decimal floating-point arithmetic, including decimal32, decimal64, and decimal128.

    Python pretty-printers are added for use with appropriately-advanced versions of gdb.

    diff --git a/libstdc++-v3/doc/html/manual/appendix_contributing.html b/libstdc++-v3/doc/html/manual/appendix_contributing.html index 422b57a813e..467f7fd0988 100644 --- a/libstdc++-v3/doc/html/manual/appendix_contributing.html +++ b/libstdc++-v3/doc/html/manual/appendix_contributing.html @@ -1,17 +1,19 @@ -Appendix A.  Contributing

    Appendix A.  +Appendix A.  Contributing
    Appendix A.  Contributing -
    Prev The GNU C++ Library Next

    Appendix A.  +

    Prev Part IV.  + Appendices + Next

    Appendix A.  Contributing - -

    Table of Contents

    Contributor Checklist
    Reading
    Assignment
    Getting Sources
    Submitting Patches
    Directory Layout and Source Conventions
    Coding Style
    Bad Identifiers
    By Example
    Documentation Style
    Doxygen
    Docbook
    Design Notes

    + +

    Table of Contents

    Contributor Checklist
    Reading
    Assignment
    Getting Sources
    Submitting Patches
    Directory Layout and Source Conventions
    Coding Style
    Bad Identifiers
    By Example
    Documentation Style
    Doxygen
    Docbook
    Combines
    Design Notes

    The GNU C++ Library follows an open development model. Active contributors are assigned maintainer-ship responsibility, and given write access to the source repository. First time contributors should follow this procedure: -

    Contributor Checklist

    Reading

    • +

      Contributor Checklist

      Reading

      • Get and read the relevant sections of the C++ language specification. Copies of the full ISO 14882 standard are available on line via the ISO mirror site for committee @@ -21,29 +23,29 @@ the standard from their respective national standards organization. In the USA, this national standards organization is ANSI and their web-site is right - here. - (And if you've already registered with them, clicking this link will take you to directly to the place where you can + here. + (And if you've already registered with them, clicking this link will take you to directly to the place where you can buy the standard on-line.) -

      • +

      • The library working group bugs, and known defects, can be obtained here: http://www.open-std.org/jtc1/sc22/wg21 -

      • +

      • The newsgroup dedicated to standardization issues is comp.std.c++: this FAQ for this group is quite useful and can be found here . -

      • +

      • Peruse the GNU Coding Standards, and chuckle when you hit the part about “Using Languages Other Than C”. -

      • +

      • Be familiar with the extensions that preceded these general GNU rules. These style issues for libstdc++ can be found here. -

      • +

      • And last but certainly not least, read the library-specific information found here. @@ -51,8 +53,8 @@ Small changes can be accepted without a copyright assignment form on file. New code and additions to the library need completed copyright assignment form on file at the FSF. Note: your employer may be required - to fill out appropriate disclaimer forms as well. -

        + to fill out appropriate disclaimer forms as well. +

        Historically, the libstdc++ assignment form added the following question:

        @@ -64,7 +66,7 @@ While not strictly necessary, humoring the maintainers and answering this question would be appreciated.

        - For more information about getting a copyright assignment, please see + For more information about getting a copyright assignment, please see Legal Matters.

        @@ -81,22 +83,22 @@ Every patch must have several pieces of information before it can be properly evaluated. Ideally (and to ensure the fastest possible response from the maintainers) it would have all of these pieces: -

        • +

          • A description of the bug and how your patch fixes this bug. For new features a description of the feature and your - implementation. -

          • + implementation. +

          • A ChangeLog entry as plain text; see the various ChangeLog files for format and content. If you are using emacs as your editor, simply position the insertion point at the beginning of your change and hit CX-4a to bring up the appropriate ChangeLog entry. See--magic! Similar - functionality also exists for vi. -

          • + functionality also exists for vi. +

          • A testsuite submission or sample program that will easily and simply show the existing error or test new - functionality. -

          • + functionality. +

          • The patch itself. If you are accessing the SVN repository use svn update; svn diff NEW; else, use diff -cp OLD NEW ... If your @@ -105,9 +107,11 @@ diff. The SVN Tricks wiki page has information on customising the output of svn diff. -

          • +

          • When you have all these pieces, bundle them up in a mail message and send it to libstdc++@gcc.gnu.org. All patches and related discussion should be sent to the - libstdc++ mailing list. -

      Prev Up Next
      Use Home Directory Layout and Source Conventions
      + libstdc++ mailing list. +

    Prev Up Next
    Part IV.  + Appendices + Home Directory Layout and Source Conventions
    diff --git a/libstdc++-v3/doc/html/manual/appendix_free.html b/libstdc++-v3/doc/html/manual/appendix_free.html index dd77c972f07..bc6c37655ea 100644 --- a/libstdc++-v3/doc/html/manual/appendix_free.html +++ b/libstdc++-v3/doc/html/manual/appendix_free.html @@ -1,11 +1,13 @@ -Appendix C.  Free Software Needs Free Documentation
    Appendix C.  +Appendix C.  Free Software Needs Free Documentation
    Appendix C.  Free Software Needs Free Documentation -
    Prev The GNU C++ Library Next

    Appendix C.  +

    Prev Part IV.  + Appendices + Next

    Appendix C.  Free Software Needs Free Documentation - +

    The biggest deficiency in free operating systems is not in the software--it is the lack of good free manuals that we can include in @@ -35,7 +37,7 @@ restrict it so that we cannot use it.

    Given that writing good English is a rare skill among programmers, we can ill afford to lose manuals this way. -

    +

    Free documentation, like free software, is a matter of freedom, not price. The problem with these manuals was not that O'Reilly Associates charged a price for printed copies--that in itself is fine. @@ -119,6 +121,6 @@ prefer copylefted manuals to non-copylefted ones. that lists free books available from other publishers].

    Copyright © 2004, 2005, 2006, 2007 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA

    Verbatim copying and distribution of this entire article are permitted worldwide, without royalty, in any medium, provided this -notice is preserved.

    Report any problems or suggestions to .

    Prev Up Next
    Backwards Compatibility Home Appendix D.  +notice is preserved.

    Report any problems or suggestions to .

    Prev Up Next
    Backwards Compatibility Home Appendix D.  GNU General Public License version 3
    diff --git a/libstdc++-v3/doc/html/manual/appendix_gfdl.html b/libstdc++-v3/doc/html/manual/appendix_gfdl.html index 6b6e69ea86d..edb2f0c3f4d 100644 --- a/libstdc++-v3/doc/html/manual/appendix_gfdl.html +++ b/libstdc++-v3/doc/html/manual/appendix_gfdl.html @@ -1,6 +1,8 @@ -Appendix E. GNU Free Documentation License
    Appendix E. GNU Free Documentation License
    Prev The GNU C++ Library Next

    Appendix E. GNU Free Documentation License

    +Appendix E. GNU Free Documentation License

    Appendix E. GNU Free Documentation License
    Prev Part IV.  + Appendices + Next

    Appendix E. GNU Free Documentation License

    Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc. 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. Everyone is permitted to copy and @@ -390,6 +392,6 @@ recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software. -

    Prev Up Next
    Appendix D.  +

    Prev Up Next
    Appendix D.  GNU General Public License version 3 -  Home Index
    +      		Home 
    diff --git a/libstdc++-v3/doc/html/manual/appendix_gpl.html b/libstdc++-v3/doc/html/manual/appendix_gpl.html index 5dd0a7da6d1..42a68eca06d 100644 --- a/libstdc++-v3/doc/html/manual/appendix_gpl.html +++ b/libstdc++-v3/doc/html/manual/appendix_gpl.html @@ -1,8 +1,10 @@ -Appendix D.  GNU General Public License version 3
    Appendix D.  +Appendix D.  GNU General Public License version 3
    Appendix D.  GNU General Public License version 3 -
    Prev The GNU C++ Library Next

    Appendix D.  +

    Prev Part IV.  + Appendices + Next

    Appendix D.  GNU General Public License version 3

    Version 3, 29 June 2007 @@ -76,7 +78,7 @@

    The precise terms and conditions for copying, distribution and modification follow. -

    +

    TERMS AND CONDITIONS

    0. Definitions. @@ -617,7 +619,7 @@ waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee. -

    +

    END OF TERMS AND CONDITIONS

    How to Apply These Terms to Your New Programs @@ -675,7 +677,7 @@ under certain conditions; type ‘show c’ for det proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read http://www.gnu.org/philosophy/why-not-lgpl.html. -

    Prev Up Next
    Appendix C.  +

    Prev Up Next
    Appendix C.  Free Software Needs Free Documentation  Home Appendix E. GNU Free Documentation License
    diff --git a/libstdc++-v3/doc/html/manual/appendix_porting.html b/libstdc++-v3/doc/html/manual/appendix_porting.html index ef6924f2892..47d342a193f 100644 --- a/libstdc++-v3/doc/html/manual/appendix_porting.html +++ b/libstdc++-v3/doc/html/manual/appendix_porting.html @@ -1,12 +1,14 @@ -Appendix B.  Porting and Maintenance
    Appendix B.  +Appendix B.  Porting and Maintenance
    Appendix B.  Porting and Maintenance -
    Prev The GNU C++ Library Next

    Appendix B.  +

    Prev Part IV.  + Appendices + Next

    Appendix B.  Porting and Maintenance - -

    Table of Contents

    Configure and Build Hacking
    Prerequisites
    Overview: What Comes from Where
    Storing Information in non-AC files (like configure.host)
    Coding and Commenting Conventions
    The acinclude.m4 layout
    GLIBCXX_ENABLE, the --enable maker
    Porting to New Hardware or Operating Systems
    Operating System
    CPU
    Character Types
    Thread Safety
    Numeric Limits
    Libtool
    Test
    Organization
    Running the Testsuite
    Writing a new test case
    Test Harness and Utilities
    Special Topics
    ABI Policy and Guidelines
    The C++ Interface
    Versioning
    Allowed Changes
    Prohibited Changes
    Implementation
    Testing
    Outstanding Issues
    API Evolution and Deprecation History
    3.0
    3.1
    3.2
    3.3
    3.4
    4.0
    4.1
    4.2
    4.3
    4.4
    4.5
    Backwards Compatibility
    First
    Second
    Third

    Configure and Build Hacking

    Prerequisites

    + +

    Table of Contents

    Configure and Build Hacking
    Prerequisites
    Overview: What Comes from Where
    Storing Information in non-AC files (like configure.host)
    Coding and Commenting Conventions
    The acinclude.m4 layout
    GLIBCXX_ENABLE, the --enable maker
    Porting to New Hardware or Operating Systems
    Operating System
    CPU
    Character Types
    Thread Safety
    Numeric Limits
    Libtool
    Test
    Organization
    Running the Testsuite
    Writing a new test case
    Test Harness and Utilities
    Special Topics
    ABI Policy and Guidelines
    The C++ Interface
    Versioning
    Allowed Changes
    Prohibited Changes
    Implementation
    Testing
    Outstanding Issues
    API Evolution and Deprecation History
    3.0
    3.1
    3.2
    3.3
    3.4
    4.0
    4.1
    4.2
    4.3
    4.4
    4.5
    Backwards Compatibility
    First
    Second
    Third

    Configure and Build Hacking

    Prerequisites

    As noted previously, certain other tools are necessary for hacking on files that control configure (configure.ac, @@ -227,4 +229,4 @@ argument checking at all is done in this signature. See GLIBCXX_ENABLE_CXX_FLAGS for an example of handling, and an error message. -

    Prev Up Next
    Design Notes Home Porting to New Hardware or Operating Systems
    +

    Prev Up Next
    Design Notes Home Porting to New Hardware or Operating Systems
    diff --git a/libstdc++-v3/doc/html/manual/associative.html b/libstdc++-v3/doc/html/manual/associative.html index bf0731243c9..2173413e41c 100644 --- a/libstdc++-v3/doc/html/manual/associative.html +++ b/libstdc++-v3/doc/html/manual/associative.html @@ -1,9 +1,9 @@ -Chapter 17. Associative
    Chapter 17. Associative
    Prev Part VII.  +Associative
    Associative
    Prev Chapter 9.  Containers - Next

    Chapter 17. Associative

    Table of Contents

    Insertion Hints
    bitset
    Size Variable
    Type String

    Insertion Hints

    +

    		 Next

    Associative

    Insertion Hints

    Section [23.1.2], Table 69, of the C++ standard lists this function for all of the associative containers (map, set, etc): 

    @@ -48,7 +48,7 @@
 	  end(), then the item being inserted should have
 	  a key greater than all the other keys in the container.  The
 	  item will be inserted at the end of the container, becoming
-	  the new entry before end().  
+	  the new entry before end().
       
  • 
 	  neither begin() nor end(), then:
 	  Let h be the entry in the container pointed to
@@ -84,4 +84,109 @@
      the new item would in fact belong there.  If the hint does not
      point to the correct place, then no further local searching is
      done; the search begins from scratch in logarithmic time.
-
    • Prev Up Next
    vector Home bitset
    +

    bitset

    Size Variable

    + No, you cannot write code of the form + 

    +      #include <bitset>
+
+      void foo (size_t n)
+      {
+	  std::bitset<n>   bits;
+	  ....
+      }
+

    + because n must be known at compile time. Your + compiler is correct; it is not a bug. That's the way templates + work. (Yes, it is a feature.) +

    + There are a couple of ways to handle this kind of thing. Please + consider all of them before passing judgement. They include, in + no chaptericular order: +

    • A very large N in bitset<N>.

    • A container<bool>.

    • Extremely weird solutions.

    + A very large N in + bitset<N>.   It has been + pointed out a few times in newsgroups that N bits only takes up + (N/8) bytes on most systems, and division by a factor of eight is + pretty impressive when speaking of memory. Half a megabyte given + over to a bitset (recall that there is zero space overhead for + housekeeping info; it is known at compile time exactly how large + the set is) will hold over four million bits. If you're using + those bits as status flags (e.g., + “changed”/“unchanged” flags), that's a + lot of state. +

    + You can then keep track of the “maximum bit used” + during some testing runs on representative data, make note of how + many of those bits really need to be there, and then reduce N to + a smaller number. Leave some extra space, of course. (If you + plan to write code like the incorrect example above, where the + bitset is a local variable, then you may have to talk your + compiler into allowing that much stack space; there may be zero + space overhead, but it's all allocated inside the object.) +

    + A container<bool>.   The + Committee made provision for the space savings possible with that + (N/8) usage previously mentioned, so that you don't have to do + wasteful things like Container<char> or + Container<short int>. Specifically, + vector<bool> is required to be specialized for + that space savings. +

    + The problem is that vector<bool> doesn't + behave like a normal vector anymore. There have been + journal articles which discuss the problems (the ones by Herb + Sutter in the May and July/August 1999 issues of C++ Report cover + it well). Future revisions of the ISO C++ Standard will change + the requirement for vector<bool> + specialization. In the meantime, deque<bool> + is recommended (although its behavior is sane, you probably will + not get the space savings, but the allocation scheme is different + than that of vector). +

    + Extremely weird solutions.   If + you have access to the compiler and linker at runtime, you can do + something insane, like figuring out just how many bits you need, + then writing a temporary source code file. That file contains an + instantiation of bitset for the required number of + bits, inside some wrapper functions with unchanging signatures. + Have your program then call the compiler on that file using + Position Independent Code, then open the newly-created object + file and load those wrapper functions. You'll have an + instantiation of bitset<N> for the exact + N that you need at the time. Don't forget to delete + the temporary files. (Yes, this can be, and + has been, done.) +

    + This would be the approach of either a visionary genius or a + raving lunatic, depending on your programming and management + style. Probably the latter. +

    + Which of the above techniques you use, if any, are up to you and + your intended application. Some time/space profiling is + indicated if it really matters (don't just guess). And, if you + manage to do anything along the lines of the third category, the + author would love to hear from you... +

    + Also note that the implementation of bitset used in libstdc++ has + some extensions. +

    Type String

    +

    + Bitmasks do not take char* nor const char* arguments in their + constructors. This is something of an accident, but you can read + about the problem: follow the library's “Links” from + the homepage, and from the C++ information “defect + reflector” link, select the library issues list. Issue + number 116 describes the problem. +

    + For now you can simply make a temporary string object using the + constructor expression: + 

    +      std::bitset<5> b ( std::string(“10110”) );
+

    + instead of + 

    +      std::bitset<5> b ( “10110” );    // invalid
+
    Prev Up Next
    Chapter 9.  + Containers + + Home Interacting with C
    diff --git a/libstdc++-v3/doc/html/manual/atomics.html b/libstdc++-v3/doc/html/manual/atomics.html new file mode 100644 index 00000000000..1db9a81fbe1 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/atomics.html @@ -0,0 +1,31 @@ + + +Chapter 14.  Atomics
    Chapter 14.  + Atomics + +
    Prev Part II.  + Standard Contents + Next

    Chapter 14.  + Atomics + +

    Table of Contents

    API Reference

    + Facilities for atomic operations. +

    API Reference

    + All items are declared in the standard header + file atomic. +

    + Set of typedefs that map int to + atomic_int, and so on for all builtin + integral types. Global enumeration memory_order to + control memory ordering. Also includes + atomic, a class template with member + functions such as load and + store that is instantiable such that + atomic_int is the base class of + atomic<int>. +

    + Full API details. +

    Prev Up Next
    Interacting with C Home Chapter 15.  + Concurrency + +
    diff --git a/libstdc++-v3/doc/html/manual/auto_ptr.html b/libstdc++-v3/doc/html/manual/auto_ptr.html deleted file mode 100644 index 777264504bf..00000000000 --- a/libstdc++-v3/doc/html/manual/auto_ptr.html +++ /dev/null @@ -1,90 +0,0 @@ - - -auto_ptr
    auto_ptr
    Prev Chapter 11. Memory Next

    auto_ptr

    Limitations

    Explaining all of the fun and delicious things that can - happen with misuse of the auto_ptr class - template (called AP here) would take some - time. Suffice it to say that the use of AP - safely in the presence of copying has some subtleties. -

    - The AP class is a really - nifty idea for a smart pointer, but it is one of the dumbest of - all the smart pointers -- and that's fine. -

    - AP is not meant to be a supersmart solution to all resource - leaks everywhere. Neither is it meant to be an effective form - of garbage collection (although it can help, a little bit). - And it can notbe used for arrays! -

    - AP is meant to prevent nasty leaks in the - presence of exceptions. That's all. This - code is AP-friendly: - 

    -    // Not a recommend naming scheme, but good for web-based FAQs.
-    typedef std::auto_ptr<MyClass>  APMC;
-
-    extern function_taking_MyClass_pointer (MyClass*);
-    extern some_throwable_function ();
-
-    void func (int data)
-    {
-        APMC  ap (new MyClass(data));
-
-        some_throwable_function();   // this will throw an exception
-
-        function_taking_MyClass_pointer (ap.get());
-    }
-

    When an exception gets thrown, the instance of MyClass that's - been created on the heap will be delete'd as the stack is - unwound past func(). -

    Changing that code as follows is not AP-friendly: - 

    -        APMC  ap (new MyClass[22]);
-

    You will get the same problems as you would without the use - of AP: - 

    -        char*  array = new char[10];       // array new...
-        ...
-        delete array;                      // ...but single-object delete
-

    - AP cannot tell whether the pointer you've passed at creation points - to one or many things. If it points to many things, you are about - to die. AP is trivial to write, however, so you could write your - own auto_array_ptr for that situation (in fact, this has - been done many times; check the mailing lists, Usenet, Boost, etc). -

    Use in Containers

    -

    All of the containers - described in the standard library require their contained types - to have, among other things, a copy constructor like this: - 

    -    struct My_Type
-    {
-        My_Type (My_Type const&);
-    };
-

    - Note the const keyword; the object being copied shouldn't change. - The template class auto_ptr (called AP here) does not - meet this requirement. Creating a new AP by copying an existing - one transfers ownership of the pointed-to object, which means that - the AP being copied must change, which in turn means that the - copy ctors of AP do not take const objects. -

    - The resulting rule is simple: Never ever use a - container of auto_ptr objects. The standard says that - “undefined” behavior is the result, but it is - guaranteed to be messy. -

    - To prevent you from doing this to yourself, the - concept checks built - in to this implementation will issue an error if you try to - compile code like this: - 

    -    #include <vector>
-    #include <memory>
-    
-    void f()
-    {
-        std::vector< std::auto_ptr<int> >   vec_ap_int;
-    }
-

    -Should you try this with the checks enabled, you will see an error. -

    Prev Up Next
    Chapter 11. Memory Home shared_ptr
    diff --git a/libstdc++-v3/doc/html/manual/backwards.html b/libstdc++-v3/doc/html/manual/backwards.html index 2844247f184..8656c934d1f 100644 --- a/libstdc++-v3/doc/html/manual/backwards.html +++ b/libstdc++-v3/doc/html/manual/backwards.html @@ -17,8 +17,8 @@ ISO Standard (e.g., statistical analysis). While there are a lot of really useful things that are used by a lot of people, the Standards Committee couldn't include everything, and so a lot of those “obvious” classes didn't get included. -

    Known Issues include many of the limitations of its immediate ancestor.

    Portability notes and known implementation limitations are as follows.

    No ios_base

    At least some older implementations don't have std::ios_base, so you should use std::ios::badbit, std::ios::failbit and std::ios::eofbit and std::ios::goodbit. -

    No cout in ostream.h, no cin in istream.h

    +

    Known Issues include many of the limitations of its immediate ancestor.

    Portability notes and known implementation limitations are as follows.

    No ios_base

    At least some older implementations don't have std::ios_base, so you should use std::ios::badbit, std::ios::failbit and std::ios::eofbit and std::ios::goodbit. +

    No cout in ostream.h, no cin in istream.h

    In earlier versions of the standard, fstream.h, ostream.h @@ -32,26 +32,26 @@ archived. For the desperate, the GCC extensions page describes where to find the last libg++ source. The code is considered replaced and rewritten. -

    Second

    +

    Second

    The second generation GNU C++ library was called libstdc++, or libstdc++-v2. It spans the time between libg++ and pre-ISO C++ standardization and is usually associated with the following GCC releases: egcs 1.x, gcc 2.95, and gcc 2.96. -

    +

    The STL portions of this library are based on SGI/HP STL release 3.11.

    This project is no longer maintained or supported, and the sources archived. The code is considered replaced and rewritten.

    Portability notes and known implementation limitations are as follows. -

    Namespace std:: not supported

    +

    Namespace std:: not supported

    Some care is required to support C++ compiler and or library implementation that do not have the standard library in namespace std.

    The following sections list some possible solutions to support compilers that cannot ignore std::-qualified names. -

    +

    First, see if the compiler has a flag for this. Namespace back-portability-issues are generally not a problem for g++ compilers that do not have libstdc++ in std::, as the @@ -62,7 +62,7 @@ considered replaced and rewritten. probably applies to some other compilers as well.

    Second, experiment with a variety of pre-processor tricks. -

    +

    By defining std as a macro, fully-qualified namespace calls become global. Volia. 

    @@ -99,8 +99,8 @@ AC_DEFUN([AC_CXX_NAMESPACE_STD], [
   ac_cv_cxx_have_std_namespace,
   [AC_LANG_SAVE
   AC_LANG_CPLUSPLUS
-  AC_TRY_COMPILE([#include <iostream> 
-                  std::istream& is = std::cin;],,
+  AC_TRY_COMPILE([#include <iostream>
+		  std::istream& is = std::cin;],,
   ac_cv_cxx_have_std_namespace=yes, ac_cv_cxx_have_std_namespace=no)
   AC_LANG_RESTORE
   ])
@@ -108,7 +108,7 @@ AC_DEFUN([AC_CXX_NAMESPACE_STD], [
     AC_DEFINE(HAVE_NAMESPACE_STD,,[Define if g++ supports namespace std. ])
   fi
 ])
-

    Illegal iterator usage

    +

    Illegal iterator usage

    The following illustrate implementation-allowed illegal iterator use, and then correct use.

    • @@ -120,28 +120,28 @@ AC_DEFUN([AC_CXX_NAMESPACE_STD], [ 0) => use iterator = iterator_type();

    • if (iterator) won't work any more => use - if (iterator != iterator_type()) -

    isspace from cctype is a macro -

    + if (iterator != iterator_type()) +

    isspace from cctype is a macro +

    Glibc 2.0.x and 2.1.x define ctype.h functionality as macros (isspace, isalpha etc.).

    This implementations of libstdc++, however, keep these functions as macros, and so it is not back-portable to use fully qualified names. For example: - 

     
-#include <cctype> 
-int main() { std::isspace('X'); } 
+  
    +#include <cctype>
+int main() { std::isspace('X'); }
 
    
   Results in something like this:
-
     
-std:: (__ctype_b[(int) ( ( 'X' ) )] & (unsigned short int) _ISspace ) ; 
-
     
+
    +std:: (__ctype_b[(int) ( ( 'X' ) )] & (unsigned short int) _ISspace ) ;
+
    
   A solution is to modify a header-file so that the compiler tells
   ctype.h to define functions
   instead of macros:
 
    -// This keeps isalnum, et al from being propagated as macros. 
+// This keeps isalnum, et al from being propagated as macros.
 #if __linux__
 # define __NO_CTYPE 1
 #endif
@@ -154,7 +154,7 @@ std:: (__ctype_b[(int) ( ( 'X' ) )] & (unsigned short int) _ISspace ) ;
   (ctype.h) and the
   definitions in namespace std::
   (<cctype>).
-

    No vector::at, deque::at, string::at

    +

    No vector::at, deque::at, string::at

    One solution is to add an autoconf-test for this: 

     AC_MSG_CHECKING(for container::at)
@@ -163,7 +163,7 @@ AC_TRY_COMPILE(
 #include <vector>
 #include <deque>
 #include <string>
-	
+
 using namespace std;
 ],
 [
@@ -180,7 +180,7 @@ AC_DEFINE(HAVE_CONTAINER_AT)],

    If you are using other (non-GNU) compilers it might be a good idea to check for string::at separately. -

    No std::char_traits<char>::eof

    +

    No std::char_traits<char>::eof

    Use some kind of autoconf test, plus this: 

     #ifdef HAVE_CHAR_TRAITS
@@ -188,45 +188,45 @@ AC_DEFINE(HAVE_CONTAINER_AT)],
 #else
 #define CPP_EOF EOF
 #endif
-

    No string::clear

    +

    No string::clear

    There are two functions for deleting the contents of a string: clear and erase (the latter returns the string). 

    -void 
+void
 clear() { _M_mutate(0, this->size(), 0); }
 
    -basic_string& 
+basic_string&
 erase(size_type __pos = 0, size_type __n = npos)
-{ 
+{
   return this->replace(_M_check(__pos), _M_fold(__pos, __n),
-                          _M_data(), _M_data()); 
+			  _M_data(), _M_data());
 }

    Unfortunately, clear is not implemented in this version, so you should use erase (which is probably faster than operator=(charT*)). -

    +

    Removal of ostream::form and istream::scan extensions -

    +

    These are no longer supported. Please use stringstreams instead. -

    No basic_stringbuf, basic_stringstream

    +

    No basic_stringbuf, basic_stringstream

    Although the ISO standard i/ostringstream-classes are provided, (sstream), for compatibility with older implementations the pre-ISO i/ostrstream (strstream) interface is also provided, with these caveats: -

    • +

      • strstream is considered to be deprecated -

      • +

      • strstream is limited to char -

      • +

      • with ostringstream you don't have to take care of - terminating the string or freeing its memory -

      • + terminating the string or freeing its memory +

      • istringstream can be re-filled (clear(); - str(input);) + str(input);)

      You can then use output-stringstreams like this: 

      @@ -268,7 +268,7 @@ std::istrstream iss(input.c_str());
 #endif
 
 int i;
-iss >> i; 
+iss >> i;

      One (the only?) restriction is that an istrstream cannot be re-filled: 

       std::istringstream iss(numerator);
@@ -295,18 +295,18 @@ if (iss.fail())
 throw runtime_error(..)
 any = temp;
 }
-

      - Another example of using stringstreams is in this howto. +

      + Another example of using stringstreams is in this howto.

      There is additional information in the libstdc++-v2 info files, in particular “info iostream”. -

    Little or no wide character support

    +

    Little or no wide character support

    Classes wstring and char_traits<wchar_t> are not supported. -

    No templatized iostreams

    +

    No templatized iostreams

    Classes wfilebuf and wstringstream are not supported. -

    Thread safety issues

    +

    Thread safety issues

    Earlier GCC releases had a somewhat different approach to threading configuration and proper compilation. Before GCC 3.0, configuration of the threading model was dictated by compiler @@ -348,10 +348,10 @@ particular “info iostream”

  • - This message inspired a recent updating of issues with - threading and the SGI STL library. It also contains some - example POSIX-multithreaded STL code. -

    • + This message inspired a recent updating of issues with + threading and the SGI STL library. It also contains some + example POSIX-multithreaded STL code. +

    (A large selection of links to older messages has been removed; many of the messages from 1999 were lost in a disk crash, and the few people with access to the backup tapes have been too swamped @@ -360,11 +360,11 @@ particular “info iostream”

    Third

    The third generation GNU C++ library is called libstdc++, or libstdc++-v3.

    The subset commonly known as the Standard Template Library - (chapters 23 through 25, mostly) is adapted from the final release - of the SGI STL (version 3.3), with extensive changes. + (chapters 23 through 25, mostly) is adapted from the final release + of the SGI STL (version 3.3), with extensive changes.

    A more formal description of the V3 goals can be found in the - official design document. -

    Portability notes and known implementation limitations are as follows.

    Pre-ISO headers moved to backwards or removed

    The pre-ISO C++ headers + official design document. +

    Portability notes and known implementation limitations are as follows.

    Pre-ISO headers moved to backwards or removed

    The pre-ISO C++ headers (iostream.h, defalloc.h etc.) are available, unlike previous libstdc++ versions, but inclusion generates a warning that you are using deprecated headers. @@ -385,7 +385,7 @@ AC_DEFUN([AC_HEADER_PRE_STDCXX], [ [AC_LANG_SAVE AC_LANG_CPLUSPLUS ac_save_CXXFLAGS="$CXXFLAGS" - CXXFLAGS="$CXXFLAGS -Wno-deprecated" + CXXFLAGS="$CXXFLAGS -Wno-deprecated" # Omit defalloc.h, as compilation with newer compilers is problematic. AC_TRY_COMPILE([ @@ -436,11 +436,11 @@ like vector.h can be replaced with using namespace std; can be put at the global scope. This should be enough to get this code compiling, assuming the other usage is correct. -

    Extension headers hash_map, hash_set moved to ext or backwards

    At this time most of the features of the SGI STL extension have been - replaced by standardized libraries. - In particular, the unordered_map and unordered_set containers of TR1 - are suitable replacement for the non-standard hash_map and hash_set - containers in the SGI STL. +

    Extension headers hash_map, hash_set moved to ext or backwards

    At this time most of the features of the SGI STL extension have been + replaced by standardized libraries. + In particular, the unordered_map and unordered_set containers of TR1 + are suitable replacement for the non-standard hash_map and hash_set + containers in the SGI STL.

    Header files hash_map and hash_set moved to ext/hash_map and ext/hash_set, respectively. At the same time, all types in these files are enclosed @@ -448,29 +448,29 @@ in namespace __gnu_cxx. Later versions move deprecate these files, and suggest using TR1's unordered_map and unordered_set instead.

    The extensions are no longer in the global or std - namespaces, instead they are declared in the __gnu_cxx - namespace. For maximum portability, consider defining a namespace - alias to use to talk about extensions, e.g.: + namespaces, instead they are declared in the __gnu_cxx + namespace. For maximum portability, consider defining a namespace + alias to use to talk about extensions, e.g.: 

           #ifdef __GNUC__
       #if __GNUC__ < 3
-        #include <hash_map.h>
-        namespace extension { using ::hash_map; }; // inherit globals
+	#include <hash_map.h>
+	namespace extension { using ::hash_map; }; // inherit globals
       #else
-        #include <backward/hash_map>
-        #if __GNUC__ == 3 && __GNUC_MINOR__ == 0
-          namespace extension = std;               // GCC 3.0
-        #else
-          namespace extension = ::__gnu_cxx;       // GCC 3.1 and later
-        #endif
+	#include <backward/hash_map>
+	#if __GNUC__ == 3 && __GNUC_MINOR__ == 0
+	  namespace extension = std;               // GCC 3.0
+	#else
+	  namespace extension = ::__gnu_cxx;       // GCC 3.1 and later
+	#endif
       #endif
       #else      // ...  there are other compilers, right?
-        namespace extension = std;
+	namespace extension = std;
       #endif
 
-      extension::hash_map<int,int> my_map; 
+      extension::hash_map<int,int> my_map;

    This is a bit cleaner than defining typedefs for all the - instantiations you might need. + instantiations you might need.

    The following autoconf tests check for working HP/SGI hash containers. 

     # AC_HEADER_EXT_HASH_MAP
@@ -480,7 +480,7 @@ AC_DEFUN([AC_HEADER_EXT_HASH_MAP], [
   [AC_LANG_SAVE
   AC_LANG_CPLUSPLUS
   ac_save_CXXFLAGS="$CXXFLAGS"
-  CXXFLAGS="$CXXFLAGS -Werror"	
+  CXXFLAGS="$CXXFLAGS -Werror"
   AC_TRY_COMPILE([#include <ext/hash_map>], [using __gnu_cxx::hash_map;],
   ac_cv_cxx_ext_hash_map=yes, ac_cv_cxx_ext_hash_map=no)
   CXXFLAGS="$ac_save_CXXFLAGS"
@@ -498,7 +498,7 @@ AC_DEFUN([AC_HEADER_EXT_HASH_SET], [
   [AC_LANG_SAVE
   AC_LANG_CPLUSPLUS
   ac_save_CXXFLAGS="$CXXFLAGS"
-  CXXFLAGS="$CXXFLAGS -Werror"	
+  CXXFLAGS="$CXXFLAGS -Werror"
   AC_TRY_COMPILE([#include <ext/hash_set>], [using __gnu_cxx::hash_set;],
   ac_cv_cxx_ext_hash_set=yes, ac_cv_cxx_ext_hash_set=no)
   CXXFLAGS="$ac_save_CXXFLAGS"
@@ -508,7 +508,7 @@ AC_DEFUN([AC_HEADER_EXT_HASH_SET], [
     AC_DEFINE(HAVE_EXT_HASH_SET,,[Define if ext/hash_set is present. ])
   fi
 ])
-

    No ios::nocreate/ios::noreplace. +

    No ios::nocreate/ios::noreplace.

    The existence of ios::nocreate being used for input-streams has been confirmed, most probably because the author thought it would be more correct to specify nocreate explicitly. So @@ -519,7 +519,7 @@ open the file for reading, check if it has been opened, and then decide whether you want to create/replace or not. To my knowledge, even older implementations support app, ate and trunc (except for app ?). -

    +

    No stream::attach(int fd)

    Phil Edwards writes: It was considered and rejected for the ISO @@ -531,7 +531,7 @@ No stream::attach(int fd) std::streambuf (or std::basic_streambuf<..>) which opens a file given a descriptor, and then pass an instance of this to the - stream-constructor. + stream-constructor.

    An extension is available that implements this. ext/stdio_filebuf.h contains a derived class called @@ -540,9 +540,9 @@ No stream::attach(int fd) descriptor, and provides the fd() function.

    For another example of this, refer to - fdstream example + fdstream example by Nicolai Josuttis. -

    +

    Support for C++98 dialect.

    Check for complete library coverage of the C++1998/2003 standard. 

    @@ -610,7 +610,7 @@ AC_DEFUN([AC_HEADER_STDCXX_98], [
     AC_DEFINE(STDCXX_98_HEADERS,,[Define if ISO C++ 1998 header files are present. ])
   fi
 ])
-

    +

    Support for C++TR1 dialect.

    Check for library coverage of the TR1 standard. 

    @@ -687,7 +687,7 @@ AC_DEFUN([AC_HEADER_TR1_UNORDERED_SET], [
     AC_DEFINE(HAVE_TR1_UNORDERED_SET,,[Define if tr1/unordered_set is present. ])
   fi
 ])
-

    +

    Support for C++0x dialect.

    Check for baseline language coverage in the compiler for the C++0xstandard. 

    @@ -699,7 +699,7 @@ AC_DEFUN([AC_COMPILE_STDCXX_0X], [
   AC_LANG_CPLUSPLUS
   AC_TRY_COMPILE([
   template <typename T>
-    struct check 
+    struct check
     {
       static_assert(sizeof(int) <= sizeof(T), "not big enough");
     };
@@ -721,10 +721,10 @@ AC_DEFUN([AC_COMPILE_STDCXX_0X], [
   [AC_LANG_SAVE
   AC_LANG_CPLUSPLUS
   ac_save_CXXFLAGS="$CXXFLAGS"
-  CXXFLAGS="$CXXFLAGS -std=c++0x"	
+  CXXFLAGS="$CXXFLAGS -std=c++0x"
   AC_TRY_COMPILE([
   template <typename T>
-    struct check 
+    struct check
     {
       static_assert(sizeof(int) <= sizeof(T), "not big enough");
     };
@@ -747,10 +747,10 @@ AC_DEFUN([AC_COMPILE_STDCXX_0X], [
   [AC_LANG_SAVE
   AC_LANG_CPLUSPLUS
   ac_save_CXXFLAGS="$CXXFLAGS"
-  CXXFLAGS="$CXXFLAGS -std=gnu++0x"	
+  CXXFLAGS="$CXXFLAGS -std=gnu++0x"
   AC_TRY_COMPILE([
   template <typename T>
-    struct check 
+    struct check
     {
       static_assert(sizeof(int) <= sizeof(T), "not big enough");
     };
@@ -768,8 +768,8 @@ AC_DEFUN([AC_COMPILE_STDCXX_0X], [
   AC_LANG_RESTORE
   ])
 
-  if test "$ac_cv_cxx_compile_cxx0x_native" = yes || 
-     test "$ac_cv_cxx_compile_cxx0x_cxx" = yes || 
+  if test "$ac_cv_cxx_compile_cxx0x_native" = yes ||
+     test "$ac_cv_cxx_compile_cxx0x_cxx" = yes ||
      test "$ac_cv_cxx_compile_cxx0x_gxx" = yes; then
     AC_DEFINE(HAVE_STDCXX_0X,,[Define if g++ supports C++0x features. ])
   fi
@@ -784,7 +784,7 @@ AC_DEFUN([AC_HEADER_STDCXX_0X], [
   AC_LANG_SAVE
   AC_LANG_CPLUSPLUS
   ac_save_CXXFLAGS="$CXXFLAGS"
-  CXXFLAGS="$CXXFLAGS -std=gnu++0x"	
+  CXXFLAGS="$CXXFLAGS -std=gnu++0x"
 
   AC_TRY_COMPILE([
     #include <cassert>
@@ -870,7 +870,7 @@ AC_DEFUN([AC_HEADER_UNORDERED_MAP], [
   AC_LANG_SAVE
   AC_LANG_CPLUSPLUS
   ac_save_CXXFLAGS="$CXXFLAGS"
-  CXXFLAGS="$CXXFLAGS -std=gnu++0x"	
+  CXXFLAGS="$CXXFLAGS -std=gnu++0x"
   AC_TRY_COMPILE([#include <unordered_map>], [using std::unordered_map;],
   ac_cv_cxx_unordered_map=yes, ac_cv_cxx_unordered_map=no)
   CXXFLAGS="$ac_save_CXXFLAGS"
@@ -889,7 +889,7 @@ AC_DEFUN([AC_HEADER_UNORDERED_SET], [
   AC_LANG_SAVE
   AC_LANG_CPLUSPLUS
   ac_save_CXXFLAGS="$CXXFLAGS"
-  CXXFLAGS="$CXXFLAGS -std=gnu++0x"	
+  CXXFLAGS="$CXXFLAGS -std=gnu++0x"
   AC_TRY_COMPILE([#include <unordered_set>], [using std::unordered_set;],
   ac_cv_cxx_unordered_set=yes, ac_cv_cxx_unordered_set=no)
   CXXFLAGS="$ac_save_CXXFLAGS"
@@ -899,32 +899,29 @@ AC_DEFUN([AC_HEADER_UNORDERED_SET], [
     AC_DEFINE(HAVE_UNORDERED_SET,,[Define if unordered_set is present. ])
   fi
 ])
-

    +

    Container::iterator_type is not necessarily Container::value_type*

    This is a change in behavior from the previous version. Now, most iterator_type typedefs in container classes are POD objects, not value_type pointers. -

    Bibliography

    [ - kegel41 - ] - Migrating to GCC 4.1 - . Dan Kegel. +

    Bibliography

    - - .

    [ - kegel41 - ] - Building the Whole Debian Archive with GCC 4.1: A Summary - . Martin Michlmayr. + + Migrating to GCC 4.1 + + + . Dan Kegel.

    + + Building the Whole Debian Archive with GCC 4.1: A Summary + - .

    [ - lbl32 - ] - Migration guide for GCC-3.2 - . + . Martin Michlmayr.

    + + Migration guide for GCC-3.2 + .

    Prev Up Next
    API Evolution and Deprecation History Home Appendix C.  Free Software Needs Free Documentation diff --git a/libstdc++-v3/doc/html/manual/bitmap_allocator.html b/libstdc++-v3/doc/html/manual/bitmap_allocator.html index 32a44a2bb2c..2d750160b29 100644 --- a/libstdc++-v3/doc/html/manual/bitmap_allocator.html +++ b/libstdc++-v3/doc/html/manual/bitmap_allocator.html @@ -1,6 +1,6 @@ -bitmap_allocator
    bitmap_allocator
    Prev Chapter 33. Allocators Next

    bitmap_allocator

    +bitmap_allocator

    bitmap_allocator
    Prev Chapter 20. Allocators Next

    bitmap_allocator

    Design

    As this name suggests, this allocator uses a bit-map to keep track of the used and unused memory locations for it's book-keeping @@ -103,7 +103,7 @@ else return false.

    Consider a block of size 64 ints. In memory, it would look like this: (assume a 32-bit system where, size_t is a 32-bit entity). -

    Table 33.1. Bitmap Allocator Memory Map

    268042949672954294967295Data -> Space for 64 ints

    +

    Table 20.1. Bitmap Allocator Memory Map

    268042949672954294967295Data -> Space for 64 ints

    The first Column(268) represents the size of the Block in bytes as seen by the Bitmap Allocator. Internally, a global free list is used to keep track of the free blocks used and given back by the @@ -192,20 +192,20 @@ For map/multimap: k = 12, and c = 4 (int and double), we get: 37.524% _S_refill_pool which does the following:

    • Gets more memory from the Global Free List of the Required - size. + size.

    • - Adjusts the size for the next call to itself. + Adjusts the size for the next call to itself.

    • Writes the appropriate headers in the bit-maps.

    • Sets the use count for that super-block just allocated to 0 - (zero). + (zero).

    • All of the above accounts to maintaining the basic invariant for the allocator. If the invariant is maintained, we are sure that all is well. Now, the same process is applied on the newly acquired free blocks, which are dispatched - accordingly. + accordingly.

    Thus, you can clearly see that the allocate function is nothing but a combination of the next-fit and first-fit algorithm optimized ONLY for @@ -337,4 +337,4 @@ equivalent.

  • And also this would preserve the cac sizeof(size_t) x 8 which is the number of bits in an integer, which can fit exactly in a CPU register. Hence, the term given is exponential growth of the internal pool. -

    • Prev Up Next
    Chapter 33. Allocators Home Chapter 34. Containers
    +

    Prev Up Next
    Chapter 20. Allocators Home Chapter 21. Containers
    diff --git a/libstdc++-v3/doc/html/manual/bitset.html b/libstdc++-v3/doc/html/manual/bitset.html deleted file mode 100644 index 0d9fbeb2088..00000000000 --- a/libstdc++-v3/doc/html/manual/bitset.html +++ /dev/null @@ -1,105 +0,0 @@ - - -bitset
    bitset
    Prev Chapter 17. Associative Next

    bitset

    Size Variable

    - No, you cannot write code of the form - 

    -      #include <bitset>
-
-      void foo (size_t n)
-      {
-          std::bitset<n>   bits;
-          ....
-      } 
-

    - because n must be known at compile time. Your - compiler is correct; it is not a bug. That's the way templates - work. (Yes, it is a feature.) -

    - There are a couple of ways to handle this kind of thing. Please - consider all of them before passing judgement. They include, in - no particular order: -

    • A very large N in bitset<N>.

    • A container<bool>.

    • Extremely weird solutions.

    - A very large N in - bitset<N>.   It has been - pointed out a few times in newsgroups that N bits only takes up - (N/8) bytes on most systems, and division by a factor of eight is - pretty impressive when speaking of memory. Half a megabyte given - over to a bitset (recall that there is zero space overhead for - housekeeping info; it is known at compile time exactly how large - the set is) will hold over four million bits. If you're using - those bits as status flags (e.g., - “changed”/“unchanged” flags), that's a - lot of state. -

    - You can then keep track of the “maximum bit used” - during some testing runs on representative data, make note of how - many of those bits really need to be there, and then reduce N to - a smaller number. Leave some extra space, of course. (If you - plan to write code like the incorrect example above, where the - bitset is a local variable, then you may have to talk your - compiler into allowing that much stack space; there may be zero - space overhead, but it's all allocated inside the object.) -

    - A container<bool>.   The - Committee made provision for the space savings possible with that - (N/8) usage previously mentioned, so that you don't have to do - wasteful things like Container<char> or - Container<short int>. Specifically, - vector<bool> is required to be specialized for - that space savings. -

    - The problem is that vector<bool> doesn't - behave like a normal vector anymore. There have been - journal articles which discuss the problems (the ones by Herb - Sutter in the May and July/August 1999 issues of C++ Report cover - it well). Future revisions of the ISO C++ Standard will change - the requirement for vector<bool> - specialization. In the meantime, deque<bool> - is recommended (although its behavior is sane, you probably will - not get the space savings, but the allocation scheme is different - than that of vector). -

    - Extremely weird solutions.   If - you have access to the compiler and linker at runtime, you can do - something insane, like figuring out just how many bits you need, - then writing a temporary source code file. That file contains an - instantiation of bitset for the required number of - bits, inside some wrapper functions with unchanging signatures. - Have your program then call the compiler on that file using - Position Independent Code, then open the newly-created object - file and load those wrapper functions. You'll have an - instantiation of bitset<N> for the exact - N that you need at the time. Don't forget to delete - the temporary files. (Yes, this can be, and - has been, done.) -

    - This would be the approach of either a visionary genius or a - raving lunatic, depending on your programming and management - style. Probably the latter. -

    - Which of the above techniques you use, if any, are up to you and - your intended application. Some time/space profiling is - indicated if it really matters (don't just guess). And, if you - manage to do anything along the lines of the third category, the - author would love to hear from you... -

    - Also note that the implementation of bitset used in libstdc++ has - some extensions. -

    Type String

    -

    - Bitmasks do not take char* nor const char* arguments in their - constructors. This is something of an accident, but you can read - about the problem: follow the library's “Links” from - the homepage, and from the C++ information “defect - reflector” link, select the library issues list. Issue - number 116 describes the problem. -

    - For now you can simply make a temporary string object using the - constructor expression: - 

    -      std::bitset<5> b ( std::string(“10110”) );
-

    - instead of - 

    -      std::bitset<5> b ( “10110” );    // invalid
-
    Prev Up Next
    Chapter 17. Associative Home Chapter 18. Interacting with C
    diff --git a/libstdc++-v3/doc/html/manual/bk01ix01.html b/libstdc++-v3/doc/html/manual/bk01ix01.html deleted file mode 100644 index 185b1c4bd2a..00000000000 --- a/libstdc++-v3/doc/html/manual/bk01ix01.html +++ /dev/null @@ -1,51 +0,0 @@ - - -Index
    Index
    Prev The GNU C++ Library Next

    Index

    A

    Algorithms, - Algorithms - -
    Appendix
    Contributing, - Contributing - -
    Free Documentation, - Free Software Needs Free Documentation - -
    Porting and Maintenance, - Porting and Maintenance - -

    C

    Containers, - Containers - -

    D

    Diagnostics, - Diagnostics - -

    E

    Extensions, - Extensions - -

    I

    Input and Output, - Input and Output - -
    Introduction, - Introduction - -
    Iterators, - Iterators - -

    L

    Localization, - Localization - -

    N

    Numerics, - Numerics - -

    S

    Strings, - Strings - -
    Support, - Support - -

    T

    Test
    Exception Safety, - Qualifying Exception Safety Guarantees - -

    U

    Utilities, - Utilities - -
    Prev Up Next
    Appendix E. GNU Free Documentation License Home 
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt02.html b/libstdc++-v3/doc/html/manual/bk01pt02.html new file mode 100644 index 00000000000..b9aa00be293 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt02.html @@ -0,0 +1,46 @@ + + +Part II.  Standard Contents
    Part II.  + Standard Contents +
    Prev The GNU C++ Library Next

    Part II.  + Standard Contents +

    Table of Contents

    4. + Support + +
    Types
    Fundamental Types
    Numeric Properties
    NULL
    Dynamic Memory
    Termination
    Termination Handlers
    Verbose Terminate Handler
    5. + Diagnostics + +
    Exceptions
    API Reference
    Adding Data to exception
    Concept Checking
    6. + Utilities + +
    Functors
    Pairs
    Memory
    Allocators
    auto_ptr
    shared_ptr
    Traits
    7. + Strings + +
    String Classes
    Simple Transformations
    Case Sensitivity
    Arbitrary Character Types
    Tokenizing
    Shrink to Fit
    CString (MFC)
    8. + Localization + +
    Locales
    locale
    Facets
    ctype
    codecvt
    messages
    9. + Containers + +
    Sequences
    list
    vector
    Associative
    Insertion Hints
    bitset
    Interacting with C
    Containers vs. Arrays
    10. + Iterators + +
    Predefined
    Iterators vs. Pointers
    One Past the End
    11. + Algorithms + +
    Mutating
    swap
    12. + Numerics + +
    Complex
    complex Processing
    Generalized Operations
    Interacting with C
    Numerics vs. Arrays
    C99
    13. + Input and Output + +
    Iostream Objects
    Stream Buffers
    Derived streambuf Classes
    Buffering
    Memory Based Streams
    Compatibility With strstream
    File Based Streams
    Copying a File
    Binary Input and Output
    Interacting with C
    Using FILE* and file descriptors
    Performance
    14. + Atomics + +
    API Reference
    15. + Concurrency + +
    API Reference
    Prev Up Next
    Debugging Support Home Chapter 4.  + Support + +
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt02ch04s02.html b/libstdc++-v3/doc/html/manual/bk01pt02ch04s02.html deleted file mode 100644 index 45fa1f6e2b4..00000000000 --- a/libstdc++-v3/doc/html/manual/bk01pt02ch04s02.html +++ /dev/null @@ -1,49 +0,0 @@ - - -Numeric Properties
    Numeric Properties
    Prev Chapter 4. Types Next

    Numeric Properties

    - The header limits defines - traits classes to give access to various implementation - defined-aspects of the fundamental types. The traits classes -- - fourteen in total -- are all specializations of the template class - numeric_limits, documented here - and defined as follows: - 

    -   template<typename T> 
-     struct class 
-     {
-       static const bool is_specialized;
-       static T max() throw();
-       static T min() throw();
-
-       static const int digits;
-       static const int digits10;
-       static const bool is_signed;
-       static const bool is_integer;
-       static const bool is_exact;
-       static const int radix;
-       static T epsilon() throw();
-       static T round_error() throw();
-
-       static const int min_exponent;
-       static const int min_exponent10;
-       static const int max_exponent;
-       static const int max_exponent10;
-
-       static const bool has_infinity;
-       static const bool has_quiet_NaN;
-       static const bool has_signaling_NaN;
-       static const float_denorm_style has_denorm;
-       static const bool has_denorm_loss;
-       static T infinity() throw();
-       static T quiet_NaN() throw();
-       static T denorm_min() throw();
-
-       static const bool is_iec559;
-       static const bool is_bounded;
-       static const bool is_modulo;
-
-       static const bool traps;
-       static const bool tinyness_before;
-       static const float_round_style round_style;
-     };
-
    Prev Up Next
    Chapter 4. Types Home NULL
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt02ch04s03.html b/libstdc++-v3/doc/html/manual/bk01pt02ch04s03.html deleted file mode 100644 index c9225c8b9ca..00000000000 --- a/libstdc++-v3/doc/html/manual/bk01pt02ch04s03.html +++ /dev/null @@ -1,29 +0,0 @@ - - -NULL
    NULL
    Prev Chapter 4. Types Next

    NULL

    - The only change that might affect people is the type of - NULL: while it is required to be a macro, - the definition of that macro is not allowed - to be (void*)0, which is often used in C. -

    - For g++, NULL is - 

    #define

    'd to be - __null, a magic keyword extension of - g++. -

    - The biggest problem of #defining NULL to be - something like “0L” is that the compiler will view - that as a long integer before it views it as a pointer, so - overloading won't do what you expect. (This is why - g++ has a magic extension, so that - NULL is always a pointer.) -

    In his book Effective - C++, Scott Meyers points out that the best way - to solve this problem is to not overload on pointer-vs-integer - types to begin with. He also offers a way to make your own magic - NULL that will match pointers before it - matches integers. -

    See - the - Effective C++ CD example -

    Prev Up Next
    Numeric Properties Home Chapter 5. Dynamic Memory
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch08.html b/libstdc++-v3/doc/html/manual/bk01pt02ch05s02.html similarity index 61% rename from libstdc++-v3/doc/html/manual/bk01pt03ch08.html rename to libstdc++-v3/doc/html/manual/bk01pt02ch05s02.html index b66b555a2da..3487b705f00 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt03ch08.html +++ b/libstdc++-v3/doc/html/manual/bk01pt02ch05s02.html @@ -1,9 +1,9 @@ -Chapter 8. Concept Checking
    Chapter 8. Concept Checking
    Prev Part III.  +Concept Checking
    Concept Checking
    Prev Chapter 5.  Diagnostics - Next

    Chapter 8. Concept Checking

    +

    		 Next

    Concept Checking

    In 1999, SGI added “concept checkers” to their implementation of the STL: code which checked the template parameters of instantiated pieces of the STL, in order to insure @@ -39,7 +39,10 @@ support for template parameter constraints based on concepts in the core language. This will obviate the need for the library-simulated concept checking described above. -

    Prev Up Next
    Adding Data to Exceptions Home Part IV.  +

    Prev Up Next
    Chapter 5.  + Diagnostics + + Home Chapter 6.  Utilities
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt02pr01.html b/libstdc++-v3/doc/html/manual/bk01pt02pr01.html deleted file mode 100644 index d88bbccff21..00000000000 --- a/libstdc++-v3/doc/html/manual/bk01pt02pr01.html +++ /dev/null @@ -1,17 +0,0 @@ - - -
    Prev Part II.  - Support - - Next

    - This part deals with the functions called and objects created - automatically during the course of a program's existence. -

    - While we can't reproduce the contents of the Standard here (you - need to get your own copy from your nation's member body; see our - homepage for help), we can mention a couple of changes in what - kind of support a C++ program gets from the Standard Library. -

    Prev Up Next
    Part II.  - Support - - Home Chapter 4. Types
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch07s02.html b/libstdc++-v3/doc/html/manual/bk01pt03ch07s02.html deleted file mode 100644 index 54df29a6553..00000000000 --- a/libstdc++-v3/doc/html/manual/bk01pt03ch07s02.html +++ /dev/null @@ -1,20 +0,0 @@ - - -Adding Data to Exceptions
    Adding Data to Exceptions
    Prev Chapter 7. Exceptions Next

    Adding Data to Exceptions

    - The standard exception classes carry with them a single string as - data (usually describing what went wrong or where the 'throw' took - place). It's good to remember that you can add your own data to - these exceptions when extending the hierarchy: - 

    -   struct My_Exception : public std::runtime_error
-   {
-     public:
-       My_Exception (const string& whatarg)
-           : std::runtime_error(whatarg), e(errno), id(GetDataBaseID()) { }
-       int  errno_at_time_of_throw() const { return e; }
-       DBID id_of_thing_that_threw() const { return id; }
-     protected:
-       int    e;
-       DBID   id;     // some user-defined type
-   };
-
    Prev Up Next
    Chapter 7. Exceptions Home Chapter 8. Concept Checking
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch07s03.html b/libstdc++-v3/doc/html/manual/bk01pt03ch07s03.html deleted file mode 100644 index b6bbc40ea0b..00000000000 --- a/libstdc++-v3/doc/html/manual/bk01pt03ch07s03.html +++ /dev/null @@ -1,4 +0,0 @@ - - -Cancellation
    Cancellation
    Prev Chapter 7. Exceptions Next

    Cancellation

    -

    Prev Up Next
    Adding Data to Exceptions Home Chapter 8. Concept Checking
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt12ch30s02.html b/libstdc++-v3/doc/html/manual/bk01pt03ch17s02.html similarity index 92% rename from libstdc++-v3/doc/html/manual/bk01pt12ch30s02.html rename to libstdc++-v3/doc/html/manual/bk01pt03ch17s02.html index 2605ad3b453..f2f1f483c00 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt12ch30s02.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch17s02.html @@ -1,6 +1,6 @@ -Semantics
    Semantics
    Prev Chapter 30. Debug Mode Next

    Semantics

    +Semantics

    Semantics
    Prev Chapter 17. Debug Mode Next

    Semantics

    A program that uses the C++ standard library correctly will maintain the same semantics under debug mode as it had with the normal (release) library. All functional and exception-handling @@ -10,7 +10,7 @@ instance, erasing an element in a std::list is a constant-time operation in normal library, but in debug mode it is linear in the number of iterators that reference that particular - list. So while your (correct) program won't change its results, it + list. So while your (correct) program won't change its results, it is likely to execute more slowly.

    libstdc++ includes many extensions to the C++ standard library. In some cases the extensions are obvious, such as the hashed associative containers, whereas other extensions give predictable @@ -52,4 +52,4 @@ with the debug-mode checks included, but this is unsupported and not guaranteed to work. For full debug-mode support you can use the __gnu_debug::basic_string debugging container directly, which always works correctly. -

    Prev Up Next
    Chapter 30. Debug Mode Home Using
    +

    Prev Up Next
    Chapter 17. Debug Mode Home Using
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt03ch17s03.html b/libstdc++-v3/doc/html/manual/bk01pt03ch17s03.html new file mode 100644 index 00000000000..ae2b3b830ae --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch17s03.html @@ -0,0 +1,24 @@ + + +Using
    Using
    Prev Chapter 17. Debug Mode Next

    Using

    +

    Using the Debug Mode

    To use the libstdc++ debug mode, compile your application with the + compiler flag -D_GLIBCXX_DEBUG. Note that this flag + changes the sizes and behavior of standard class templates such + as std::vector, and therefore you can only link code + compiled with debug mode and code compiled without debug mode if no + instantiation of a container is passed between the two translation + units.

    By default, error messages are formatted to fit on lines of about + 78 characters. The environment variable + GLIBCXX_DEBUG_MESSAGE_LENGTH can be used to request a + different length.

    Using a Specific Debug Container

    When it is not feasible to recompile your entire application, or + only specific containers need checking, debugging containers are + available as GNU extensions. These debugging containers are + functionally equivalent to the standard drop-in containers used in + debug mode, but they are available in a separate namespace as GNU + extensions and may be used in programs compiled with either release + mode or with debug mode. The + following table provides the names and headers of the debugging + containers: +

    Table 17.1. Debugging Containers

    ContainerHeaderDebug containerDebug header
    std::bitsetbitset__gnu_debug::bitset<debug/bitset>
    std::dequedeque__gnu_debug::deque<debug/deque>
    std::listlist__gnu_debug::list<debug/list>
    std::mapmap__gnu_debug::map<debug/map>
    std::multimapmap__gnu_debug::multimap<debug/map>
    std::multisetset__gnu_debug::multiset<debug/set>
    std::setset__gnu_debug::set<debug/set>
    std::stringstring__gnu_debug::string<debug/string>
    std::wstringstring__gnu_debug::wstring<debug/string>
    std::basic_stringstring__gnu_debug::basic_string<debug/string>
    std::vectorvector__gnu_debug::vector<debug/vector>

    In addition, when compiling in C++0x mode, these additional +containers have additional debug capability. +

    Table 17.2. Debugging Containers C++0x

    ContainerHeaderDebug containerDebug header
    std::unordered_mapunordered_map__gnu_debug::unordered_map<debug/unordered_map>
    std::unordered_multimapunordered_map__gnu_debug::unordered_multimap<debug/unordered_map>
    std::unordered_setunordered_set__gnu_debug::unordered_set<debug/unordered_set>
    std::unordered_multisetunordered_set__gnu_debug::unordered_multiset<debug/unordered_set>

    Prev Up Next
    Semantics Home Design
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt12ch30s04.html b/libstdc++-v3/doc/html/manual/bk01pt03ch17s04.html similarity index 96% rename from libstdc++-v3/doc/html/manual/bk01pt12ch30s04.html rename to libstdc++-v3/doc/html/manual/bk01pt03ch17s04.html index 862789635a7..758af487ad7 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt12ch30s04.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch17s04.html @@ -1,6 +1,6 @@ -Design
    Design
    Prev Chapter 30. Debug Mode Next

    Design

    +Design

    Design
    Prev Chapter 17. Debug Mode Next

    Design

    Goals

    The libstdc++ debug mode replaces unsafe (but efficient) standard containers and iterators with semantically equivalent safe standard @@ -38,7 +38,7 @@ own usability and implementation characteristics. In general, the higher-numbered conformance levels are more usable (i.e., require less recompilation) but are more complicated to implement than - the lower-numbered conformance levels. + the lower-numbered conformance levels.

    1. Full recompilation: The user must recompile his or her entire application and all C++ libraries it depends on, including the C++ standard library that ships with the @@ -101,7 +101,7 @@ container that will perform the actual work. This design decision ensures that we cannot regress release-mode performance (because the release-mode containers are left untouched) and partially - enables mixing debug and + enables mixing debug and release code at link time, although that will not be discussed at this time.

      Two types of wrappers are used in the implementation of the debug mode: container wrappers and iterator wrappers. The two types of @@ -133,8 +133,8 @@ version) as appropriate. However, all safe containers inherit from the class template __gnu_debug::_Safe_sequence, instantiated with the type of the safe container itself (an instance - of the curiously recurring template pattern).

      The iterators of a container wrapper will be - safe + of the curiously recurring template pattern).

      The iterators of a container wrapper will be + safe iterators that reference sequences of this type and wrap the iterators provided by the release-mode base class. The debugging container will use only the safe iterators within its own interface @@ -221,7 +221,7 @@ namespace std }; } // namespace std

      In debug mode we include the release-mode container (which is now -defined in in the namespace __norm) and also the +defined in the namespace __norm) and also the debug-mode container. The debug-mode container is defined within the namespace __debug, which is associated with namespace std via the C++0x namespace association language feature. This @@ -236,7 +236,7 @@ namespace std template<typename _Tp, typename _Alloc = allocator<_Tp> > class list { - // ... + // ... }; } // namespace __gnu_norm @@ -245,9 +245,9 @@ namespace std template<typename _Tp, typename _Alloc = allocator<_Tp> > class list : public __norm::list<_Tp, _Alloc>, - public __gnu_debug::_Safe_sequence<list<_Tp, _Alloc> > + public __gnu_debug::_Safe_sequence<list<_Tp, _Alloc> > { - // ... + // ... }; } // namespace __norm @@ -256,7 +256,7 @@ namespace std }

    Link- and run-time coexistence of release- and debug-mode components

    Because each component has a distinct and separate release and -debug implementation, there are are no issues with link-time +debug implementation, there is no issue with link-time coexistence: the separate namespaces result in different mangled names, and thus unique linkage.

    However, components that are defined and used within the C++ standard library itself face additional constraints. For instance, @@ -273,12 +273,12 @@ runtime errors. A simplified example of this problem is as follows. #include <string> std::string test02(); - + std::string test01() { return test02(); } - + int main() { test01(); @@ -286,7 +286,7 @@ int main() }

    ... and linked to this translation unit, compiled in release mode:

     #include <string>
- 
+
 std::string
 test02()
 {
@@ -349,7 +349,7 @@ test02()
       enticing option, because it would eliminate the need for
       the link_name extension by aliasing the
       templates. However, there is no true template aliasing mechanism
-      is C++, because both using directives and using
+      in C++, because both using directives and using
       declarations disallow specialization. This method fails
       the correctness criteria.
  •  Use implementation-specific properties of anonymous
     namespaces. 
@@ -375,7 +375,7 @@ test02()
     include ordering. Two, ODR issues remained with container member
     functions taking no arguments in mixed-mode settings resulting in
     equivalent link names,  vector::push_back()  being
-    one example. 
+    one example.
     See link
     name

    • Other options may exist for implementing the debug mode, many of which have probably been considered and others that may still be @@ -409,4 +409,4 @@ test02() a full debug-mode implementation (including debugging for CodeWarrior extensions) and is easy to use, although it meets only the "Full recompilation" (1) recompilation - guarantee.

    Prev Up Next
    Using Home Chapter 31. Parallel Mode
    + guarantee.

    Prev Up Next
    Using Home Chapter 18. Parallel Mode
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt12ch31s02.html b/libstdc++-v3/doc/html/manual/bk01pt03ch18s02.html similarity index 82% rename from libstdc++-v3/doc/html/manual/bk01pt12ch31s02.html rename to libstdc++-v3/doc/html/manual/bk01pt03ch18s02.html index 64acc0aa5c3..29f7dad3cca 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt12ch31s02.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch18s02.html @@ -1,6 +1,6 @@ -Semantics
    Semantics
    Prev Chapter 31. Parallel Mode Next

    Semantics

    The parallel mode STL algorithms are currently not exception-safe, +Semantics

    Semantics
    Prev Chapter 18. Parallel Mode Next

    Semantics

    The parallel mode STL algorithms are currently not exception-safe, i.e. user-defined functors must not throw exceptions. Also, the order of execution is not guaranteed for some functions, of course. Therefore, user-defined functors should not have any concurrent side effects. @@ -8,4 +8,4 @@ Therefore, user-defined functors should not have any concurrent side effects. OpenMP parallel regions in concurrent threads, it is not possible to call parallel STL algorithm in concurrent threads, either. -It might work with other compilers, though.

    Prev Up Next
    Chapter 31. Parallel Mode Home Using
    +It might work with other compilers, though.

    Prev Up Next
    Chapter 18. Parallel Mode Home Using
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt12ch31s03.html b/libstdc++-v3/doc/html/manual/bk01pt03ch18s03.html similarity index 95% rename from libstdc++-v3/doc/html/manual/bk01pt12ch31s03.html rename to libstdc++-v3/doc/html/manual/bk01pt03ch18s03.html index 45d01b93b99..778d35acbcd 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt12ch31s03.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch18s03.html @@ -1,13 +1,13 @@ -Using
    Using
    Prev Chapter 31. Parallel Mode Next

    Using

    Prerequisite Compiler Flags

    +Using

    Using
    Prev Chapter 18. Parallel Mode Next

    Using

    Prerequisite Compiler Flags

    Any use of parallel functionality requires additional compiler and runtime support, in particular support for OpenMP. Adding this support is not difficult: just compile your application with the compiler flag -fopenmp. This will link in libgomp, the GNU OpenMP implementation, - whose presence is mandatory. + whose presence is mandatory.

    In addition, hardware that supports atomic operations and a compiler capable of producing atomic operations is mandatory: GCC defaults to no @@ -63,4 +63,4 @@ Then compile this code with the prerequisite compiler flags flags for atomic operations.)

    The following table provides the names and headers of all the parallel algorithms that can be used in a similar manner: -

    Table 31.1. Parallel Algorithms

    AlgorithmHeaderParallel algorithmParallel header
    std::accumulatenumeric__gnu_parallel::accumulateparallel/numeric
    std::adjacent_differencenumeric__gnu_parallel::adjacent_differenceparallel/numeric
    std::inner_productnumeric__gnu_parallel::inner_productparallel/numeric
    std::partial_sumnumeric__gnu_parallel::partial_sumparallel/numeric
    std::adjacent_findalgorithm__gnu_parallel::adjacent_findparallel/algorithm
    std::countalgorithm__gnu_parallel::countparallel/algorithm
    std::count_ifalgorithm__gnu_parallel::count_ifparallel/algorithm
    std::equalalgorithm__gnu_parallel::equalparallel/algorithm
    std::findalgorithm__gnu_parallel::findparallel/algorithm
    std::find_ifalgorithm__gnu_parallel::find_ifparallel/algorithm
    std::find_first_ofalgorithm__gnu_parallel::find_first_ofparallel/algorithm
    std::for_eachalgorithm__gnu_parallel::for_eachparallel/algorithm
    std::generatealgorithm__gnu_parallel::generateparallel/algorithm
    std::generate_nalgorithm__gnu_parallel::generate_nparallel/algorithm
    std::lexicographical_comparealgorithm__gnu_parallel::lexicographical_compareparallel/algorithm
    std::mismatchalgorithm__gnu_parallel::mismatchparallel/algorithm
    std::searchalgorithm__gnu_parallel::searchparallel/algorithm
    std::search_nalgorithm__gnu_parallel::search_nparallel/algorithm
    std::transformalgorithm__gnu_parallel::transformparallel/algorithm
    std::replacealgorithm__gnu_parallel::replaceparallel/algorithm
    std::replace_ifalgorithm__gnu_parallel::replace_ifparallel/algorithm
    std::max_elementalgorithm__gnu_parallel::max_elementparallel/algorithm
    std::mergealgorithm__gnu_parallel::mergeparallel/algorithm
    std::min_elementalgorithm__gnu_parallel::min_elementparallel/algorithm
    std::nth_elementalgorithm__gnu_parallel::nth_elementparallel/algorithm
    std::partial_sortalgorithm__gnu_parallel::partial_sortparallel/algorithm
    std::partitionalgorithm__gnu_parallel::partitionparallel/algorithm
    std::random_shufflealgorithm__gnu_parallel::random_shuffleparallel/algorithm
    std::set_unionalgorithm__gnu_parallel::set_unionparallel/algorithm
    std::set_intersectionalgorithm__gnu_parallel::set_intersectionparallel/algorithm
    std::set_symmetric_differencealgorithm__gnu_parallel::set_symmetric_differenceparallel/algorithm
    std::set_differencealgorithm__gnu_parallel::set_differenceparallel/algorithm
    std::sortalgorithm__gnu_parallel::sortparallel/algorithm
    std::stable_sortalgorithm__gnu_parallel::stable_sortparallel/algorithm
    std::unique_copyalgorithm__gnu_parallel::unique_copyparallel/algorithm

    Prev Up Next
    Semantics Home Design
    +

    Table 18.1. Parallel Algorithms

    AlgorithmHeaderParallel algorithmParallel header
    std::accumulatenumeric__gnu_parallel::accumulateparallel/numeric
    std::adjacent_differencenumeric__gnu_parallel::adjacent_differenceparallel/numeric
    std::inner_productnumeric__gnu_parallel::inner_productparallel/numeric
    std::partial_sumnumeric__gnu_parallel::partial_sumparallel/numeric
    std::adjacent_findalgorithm__gnu_parallel::adjacent_findparallel/algorithm
    std::countalgorithm__gnu_parallel::countparallel/algorithm
    std::count_ifalgorithm__gnu_parallel::count_ifparallel/algorithm
    std::equalalgorithm__gnu_parallel::equalparallel/algorithm
    std::findalgorithm__gnu_parallel::findparallel/algorithm
    std::find_ifalgorithm__gnu_parallel::find_ifparallel/algorithm
    std::find_first_ofalgorithm__gnu_parallel::find_first_ofparallel/algorithm
    std::for_eachalgorithm__gnu_parallel::for_eachparallel/algorithm
    std::generatealgorithm__gnu_parallel::generateparallel/algorithm
    std::generate_nalgorithm__gnu_parallel::generate_nparallel/algorithm
    std::lexicographical_comparealgorithm__gnu_parallel::lexicographical_compareparallel/algorithm
    std::mismatchalgorithm__gnu_parallel::mismatchparallel/algorithm
    std::searchalgorithm__gnu_parallel::searchparallel/algorithm
    std::search_nalgorithm__gnu_parallel::search_nparallel/algorithm
    std::transformalgorithm__gnu_parallel::transformparallel/algorithm
    std::replacealgorithm__gnu_parallel::replaceparallel/algorithm
    std::replace_ifalgorithm__gnu_parallel::replace_ifparallel/algorithm
    std::max_elementalgorithm__gnu_parallel::max_elementparallel/algorithm
    std::mergealgorithm__gnu_parallel::mergeparallel/algorithm
    std::min_elementalgorithm__gnu_parallel::min_elementparallel/algorithm
    std::nth_elementalgorithm__gnu_parallel::nth_elementparallel/algorithm
    std::partial_sortalgorithm__gnu_parallel::partial_sortparallel/algorithm
    std::partitionalgorithm__gnu_parallel::partitionparallel/algorithm
    std::random_shufflealgorithm__gnu_parallel::random_shuffleparallel/algorithm
    std::set_unionalgorithm__gnu_parallel::set_unionparallel/algorithm
    std::set_intersectionalgorithm__gnu_parallel::set_intersectionparallel/algorithm
    std::set_symmetric_differencealgorithm__gnu_parallel::set_symmetric_differenceparallel/algorithm
    std::set_differencealgorithm__gnu_parallel::set_differenceparallel/algorithm
    std::sortalgorithm__gnu_parallel::sortparallel/algorithm
    std::stable_sortalgorithm__gnu_parallel::stable_sortparallel/algorithm
    std::unique_copyalgorithm__gnu_parallel::unique_copyparallel/algorithm

    Prev Up Next
    Semantics Home Design
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt12ch31s04.html b/libstdc++-v3/doc/html/manual/bk01pt03ch18s04.html similarity index 95% rename from libstdc++-v3/doc/html/manual/bk01pt12ch31s04.html rename to libstdc++-v3/doc/html/manual/bk01pt03ch18s04.html index 0e5f92549a5..2b2fd27996e 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt12ch31s04.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch18s04.html @@ -1,6 +1,6 @@ -Design
    Design
    Prev Chapter 31. Parallel Mode Next

    Design

    +Design

    Design
    Prev Chapter 18. Parallel Mode Next

    Design

    Interface Basics

    All parallel algorithms are intended to have signatures that are equivalent to the ISO C++ algorithms replaced. For instance, the @@ -105,7 +105,7 @@ For the following algorithms in general, we have __gnu_parallel::parallel_tag and __gnu_parallel::default_parallel_tag, in addition to __gnu_parallel::sequential_tag. -__gnu_parallel::default_parallel_tag chooses the default +__gnu_parallel::default_parallel_tag chooses the default algorithm at compiletime, as does omitting the tag. __gnu_parallel::parallel_tag postpones the decision to runtime (see next section). @@ -120,7 +120,7 @@ Exact and sampling are the two available splitting strategies. For the sort and stable_sort algorithms, there are several additional choices, namely __gnu_parallel::multiway_mergesort_tag, -__gnu_parallel::multiway_mergesort_exact_tag, +__gnu_parallel::multiway_mergesort_exact_tag, __gnu_parallel::multiway_mergesort_sampling_tag, __gnu_parallel::quicksort_tag, and __gnu_parallel::balanced_quicksort_tag. @@ -198,7 +198,7 @@ int main() explicitly sequential: __gnu_serial.

    Two namespaces contain the parallel mode: -std::__parallel and __gnu_parallel. +std::__parallel and __gnu_parallel.

    Parallel implementations of standard components, including template helpers to select parallelism, are defined in namespace std::__parallel. For instance, std::transform from algorithm has a parallel counterpart in @@ -210,4 +210,4 @@ __gnu_parallel.

    More information, and an organized index of types and functions related to the parallel mode on a per-namespace basis, can be found in the generated source documentation. -

    Prev Up Next
    Using Home Testing
    +

    Prev Up Next
    Using Home Testing
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt12ch31s05.html b/libstdc++-v3/doc/html/manual/bk01pt03ch18s05.html similarity index 84% rename from libstdc++-v3/doc/html/manual/bk01pt12ch31s05.html rename to libstdc++-v3/doc/html/manual/bk01pt03ch18s05.html index 6a10f32eea9..7a92bbaba9c 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt12ch31s05.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch18s05.html @@ -1,9 +1,9 @@ -Testing
    Testing
    Prev Chapter 31. Parallel Mode Next

    Testing

    +Testing

    Testing
    Prev Chapter 18. Parallel Mode Next

    Testing

    Both the normal conformance and regression tests and the supplemental performance tests work. -

    +

    To run the conformance and regression tests with the parallel mode active, 

    @@ -11,7 +11,7 @@

    The log and summary files for conformance testing are in the testsuite/parallel directory. -

    +

    To run the performance tests with the parallel mode active, 

       make check-performance-parallel
@@ -23,4 +23,4 @@
     additional software dependencies than the usual bare-boned text
     file, and can be generated by using the make
     doc-performance rule in the testsuite's Makefile.
-
    Prev Up Next
    Design Home Chapter 32. Profile Mode
    +

    Prev Up Next
    Design Home Chapter 19. Profile Mode
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt12ch32s02.html b/libstdc++-v3/doc/html/manual/bk01pt03ch19s02.html similarity index 86% rename from libstdc++-v3/doc/html/manual/bk01pt12ch32s02.html rename to libstdc++-v3/doc/html/manual/bk01pt03ch19s02.html index 3d3439b1fa3..575a89dc0c2 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt12ch32s02.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch19s02.html @@ -1,7 +1,7 @@ -Design
    Design
    Prev Chapter 32. Profile Mode Next

    Design

    -

    Table 32.1. Code Location

    Code LocationUse
    libstdc++-v3/include/std/*Preprocessor code to redirect to profile extension headers.
    libstdc++-v3/include/profile/*Profile extension public headers (map, vector, ...).
    libstdc++-v3/include/profile/impl/*Profile extension internals. Implementation files are +Design
    Design
    Prev Chapter 19. Profile Mode Next

    Design

    +

    Table 19.1. Profile Code Location

    Code LocationUse
    libstdc++-v3/include/std/*Preprocessor code to redirect to profile extension headers.
    libstdc++-v3/include/profile/*Profile extension public headers (map, vector, ...).
    libstdc++-v3/include/profile/impl/*Profile extension internals. Implementation files are only included from impl/profiler.h, which is the only file included from the public headers.

    Wrapper Model

    @@ -10,12 +10,12 @@ we use the same wrapper model as the debug mode. We subclass entities from the release version. Wherever _GLIBCXX_PROFILE is defined, the release namespace is - std::__norm, whereas the profile namespace is + std::__norm, whereas the profile namespace is std::__profile. Using plain std translates into std::__profile.

    Whenever possible, we try to wrap at the public interface level, e.g., - in unordered_set rather than in hashtable, + in unordered_set rather than in hashtable, in order not to depend on implementation.

    Mixing object files built with and without the profile mode must @@ -29,12 +29,12 @@ Instead of instrumenting every public entry and exit point, we chose to add instrumentation on demand, as needed by individual diagnostics. - The main reason is that some diagnostics require us to extract bits of + The main reason is that some diagnostics require us to extract bits of internal state that are particular only to that diagnostic. We plan to formalize this later, after we learn more about the requirements of several diagnostics.

    - All the instrumentation points can be switched on and off using + All the instrumentation points can be switched on and off using -D[_NO]_GLIBCXX_PROFILE_<diagnostic> options. With all the instrumentation calls off, there should be negligible overhead over the release version. This property is needed to support @@ -42,7 +42,7 @@ we anticipate turning most of the instrumentation off in order to prevent profiling overhead from polluting time measurements, and thus diagnostics.

    - All the instrumentation on/off compile time switches live in + All the instrumentation on/off compile time switches live in include/profile/profiler.h.

    Run Time Behavior

    For practical reasons, the instrumentation library processes the trace @@ -60,7 +60,7 @@ is destroyed, we accumulate its effect to the corresponding entry for the call stack of its constructor location.

    - For details, see + For details, see paper presented at CGO 2009.

    Analysis and Diagnostics

    @@ -71,7 +71,7 @@ The input to the analysis is a table indexed by profile type and call stack. The data type for each entry depends on the profile type.

    Cost Model

    - While it is likely that cost models become complex as we get into + While it is likely that cost models become complex as we get into more sophisticated analysis, we will try to follow a simple set of rules at the beginning.

    • Relative benefit estimation: @@ -95,7 +95,7 @@ and report the one that performs best for each call context.

    • Show stoppers: We may decide that the presence of an operation nullifies the advice. - For instance, when considering switching from set to + For instance, when considering switching from set to unordered_set, if we detect use of operator ++, we will simply not issue the advice, since this could signal that the use care require a sorted container.

    Reports

    @@ -119,4 +119,4 @@ it helps the user focus on the key problems and ignore the uninteresting ones. We created a profile directory in the test suite. Each diagnostic must come with at least two tests, one for false positives and one for false negatives. -

    Prev Up Next
    Chapter 32. Profile Mode Home Extensions for Custom Containers
    +

    Prev Up Next
    Chapter 19. Profile Mode Home Extensions for Custom Containers
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt12ch32s03.html b/libstdc++-v3/doc/html/manual/bk01pt03ch19s03.html similarity index 80% rename from libstdc++-v3/doc/html/manual/bk01pt12ch32s03.html rename to libstdc++-v3/doc/html/manual/bk01pt03ch19s03.html index f943e20f0e7..89c14c0a821 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt12ch32s03.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch19s03.html @@ -1,10 +1,10 @@ -Extensions for Custom Containers
    Extensions for Custom Containers
    Prev Chapter 32. Profile Mode Next

    Extensions for Custom Containers

    +Extensions for Custom Containers

    Extensions for Custom Containers
    Prev Chapter 19. Profile Mode Next

    Extensions for Custom Containers

    Many large projects use their own data structures instead of the ones in the standard library. If these data structures are similar in functionality to the standard library, they can be instrumented with the same hooks that are used to instrument the standard library. The instrumentation API is exposed in file profiler.h (look for "Instrumentation hooks"). -

    Prev Up Next
    Design Home Empirical Cost Model
    +

    Prev Up Next
    Design Home Empirical Cost Model
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt12ch32s04.html b/libstdc++-v3/doc/html/manual/bk01pt03ch19s04.html similarity index 80% rename from libstdc++-v3/doc/html/manual/bk01pt12ch32s04.html rename to libstdc++-v3/doc/html/manual/bk01pt03ch19s04.html index 70a142871d2..64a3a19822a 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt12ch32s04.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch19s04.html @@ -1,6 +1,6 @@ -Empirical Cost Model
    Empirical Cost Model
    Prev Chapter 32. Profile Mode Next

    Empirical Cost Model

    +Empirical Cost Model

    Empirical Cost Model
    Prev Chapter 19. Profile Mode Next

    Empirical Cost Model

    Currently, the cost model uses formulas with predefined relative weights for alternative containers or container implementations. For instance, iterating through a vector is X times faster than iterating through a list. @@ -15,4 +15,4 @@ filled in either by hand or by an automated training mechanism. The analysis module will then use this database instead of the built in. generic parameters. -

    Prev Up Next
    Extensions for Custom Containers Home Implementation Issues
    +

    Prev Up Next
    Extensions for Custom Containers Home Implementation Issues
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt12ch32s05.html b/libstdc++-v3/doc/html/manual/bk01pt03ch19s05.html similarity index 88% rename from libstdc++-v3/doc/html/manual/bk01pt12ch32s05.html rename to libstdc++-v3/doc/html/manual/bk01pt03ch19s05.html index d64fd47518f..025dbb12679 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt12ch32s05.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch19s05.html @@ -1,6 +1,6 @@ -Implementation Issues
    Implementation Issues
    Prev Chapter 32. Profile Mode Next

    Implementation Issues

    Stack Traces

    +Implementation Issues

    Implementation Issues
    Prev Chapter 19. Profile Mode Next

    Implementation Issues

    Stack Traces

    Accurate stack traces are needed during profiling since we group events by call context and dynamic instance. Without accurate traces, diagnostics may be hard to interpret. For instance, when giving advice to the user @@ -24,15 +24,15 @@ During profiling, we keep a single information table per diagnostic. There is a single lock per information table.

    Using the Standard Library in the Instrumentation Implementation

    - As much as we would like to avoid uses of stdlibc++ within our - instrumentation library, containers such as unordered_map are very - appealing. We plan to use them as long as they are named properly + As much as we would like to avoid uses of libstdc++ within our + instrumentation library, containers such as unordered_map are very + appealing. We plan to use them as long as they are named properly to avoid ambiguity.

    Malloc Hooks

    User applications/libraries can provide malloc hooks. When the implementation of the malloc hooks uses stdlibc++, there can be an infinite cycle between the profile mode instrumentation and the - the malloc hook code. + malloc hook code.

    We protect against reentrance to the profile mode instrumentation code, which should avoid this problem in most cases. @@ -46,6 +46,6 @@ The profiling library state is initialized at the first call to a profiling method. This allows us to record the construction of all global objects. However, we cannot do the same at destruction time. The trace is written - by a function registered by atexit, thus invoked by + by a function registered by atexit, thus invoked by exit. -

    Prev Up Next
    Empirical Cost Model Home Developer Information
    +

    Prev Up Next
    Empirical Cost Model Home Developer Information
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt12ch32s06.html b/libstdc++-v3/doc/html/manual/bk01pt03ch19s06.html similarity index 89% rename from libstdc++-v3/doc/html/manual/bk01pt12ch32s06.html rename to libstdc++-v3/doc/html/manual/bk01pt03ch19s06.html index ec752d398de..a4eb97333e8 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt12ch32s06.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch19s06.html @@ -1,21 +1,21 @@ -Developer Information
    Developer Information
    Prev Chapter 32. Profile Mode Next

    Developer Information

    Big Picture

    The profile mode headers are included with - -D_GLIBCXX_PROFILE through preprocessor directives in +Developer Information

    Developer Information
    Prev Chapter 19. Profile Mode Next

    Developer Information

    Big Picture

    The profile mode headers are included with + -D_GLIBCXX_PROFILE through preprocessor directives in include/std/*. -

    Instrumented implementations are provided in +

    Instrumented implementations are provided in include/profile/*. All instrumentation hooks are macros defined in include/profile/profiler.h. -

    All the implementation of the instrumentation hooks is in +

    All the implementation of the instrumentation hooks is in include/profile/impl/*. Although all the code gets included, thus is publicly visible, only a small number of functions are called from outside this directory. All calls to hook implementations must be done through macros defined in profiler.h. The macro - must ensure (1) that the call is guarded against reentrance and + must ensure (1) that the call is guarded against reentrance and (2) that the call can be turned off at compile time using a -D_GLIBCXX_PROFILE_... compiler option.

    How To Add A Diagnostic

    Let's say the diagnostic name is "magic". -

    If you need to instrument a header not already under +

    If you need to instrument a header not already under include/profile/*, first edit the corresponding header under include/std/ and add a preprocessor directive such as the one in include/std/vector: @@ -57,7 +57,7 @@ Define class __magic_stack_info: public __magic_info. This defines the content of a line in the stack table.

  • - Define class __trace_magic: public __trace_base<__magic_info, + Define class __trace_magic: public __trace_base<__magic_info, __magic_stack_info>. It defines the content of the trace associated with this diagnostic.

    • @@ -65,4 +65,4 @@ include/profile/impl/profiler_trace.h. Use __trace_vector_to_list as an example.

    Add documentation in file doc/xml/manual/profile_mode.xml. -

    Prev Up Next
    Implementation Issues Home Diagnostics
    +

    Prev Up Next
    Implementation Issues Home Diagnostics
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt12ch32s07.html b/libstdc++-v3/doc/html/manual/bk01pt03ch19s07.html similarity index 94% rename from libstdc++-v3/doc/html/manual/bk01pt12ch32s07.html rename to libstdc++-v3/doc/html/manual/bk01pt03ch19s07.html index 390d5665ebc..e5d00f5a9d9 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt12ch32s07.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch19s07.html @@ -1,12 +1,12 @@ -Diagnostics
    Diagnostics
    Prev Chapter 32. Profile Mode Next

    Diagnostics

    +Diagnostics

    Diagnostics
    Prev Chapter 19. Profile Mode Next

    Diagnostics

    The table below presents all the diagnostics we intend to implement. Each diagnostic has a corresponding compile time switch -D_GLIBCXX_PROFILE_<diagnostic>. Groups of related diagnostics can be turned on with a single switch. For instance, -D_GLIBCXX_PROFILE_LOCALITY is equivalent to - -D_GLIBCXX_PROFILE_SOFTWARE_PREFETCH + -D_GLIBCXX_PROFILE_SOFTWARE_PREFETCH -D_GLIBCXX_PROFILE_RBTREE_LOCALITY.

    The benefit, cost, expected frequency and accuracy of each diagnostic @@ -18,7 +18,7 @@ A high accuracy means that the diagnostic is unlikely to be wrong. These grades are not perfect. They are just meant to guide users with specific needs or time budgets. -

    Table 32.2. Diagnostics

    GroupFlagBenefitCostFreq.Implemented
    +

    Table 19.2. Profile Diagnostics

    GroupFlagBenefitCostFreq.Implemented 
    CONTAINERS HASHTABLE_TOO_SMALL101 10yes
      HASHTABLE_TOO_LARGE51 10yes
      @@ -57,22 +57,22 @@ advice sample _GLIBCXX_PROFILE_CONTAINERS.

    Hashtable Too Small

    • Switch: _GLIBCXX_PROFILE_HASHTABLE_TOO_SMALL. -

    • Goal: Detect hashtables with many +

    • Goal: Detect hashtables with many rehash operations, small construction size and large destruction size.

    • Fundamentals: Rehash is very expensive. Read content, follow chains within bucket, evaluate hash function, place at new location in different order.

    • Sample runtime reduction: 36%. Code similar to example below. -

    • Recommendation: +

    • Recommendation: Set initial size to N at construction site S. -

    • To instrument: +

    • To instrument: unordered_set, unordered_map constructor, destructor, rehash.

    • Analysis: For each dynamic instance of unordered_[multi]set|map, record initial size and call context of the constructor. Record size increase, if any, after each relevant operation such as insert. Record the estimated rehash cost.

    • Cost model: - Number of individual rehash operations * cost per rehash.

    • Example: + Number of individual rehash operations * cost per rehash.

    • Example: 

       1 unordered_set<int> us;
 2 for (int k = 0; k < 1000000; ++k) {
@@ -89,16 +89,16 @@ foo.cc:1: advice: Changing initial unordered_set size from 10 to 1000000 saves 1

    • Fundamentals: Save memory, which is good in itself and may also improve memory reference performance through fewer cache and TLB misses.

    • Sample runtime reduction: unknown. -

    • Recommendation: +

    • Recommendation: Set initial size to N at construction site S. -

    • To instrument: +

    • To instrument: unordered_set, unordered_map constructor, destructor, rehash.

    • Analysis: For each dynamic instance of unordered_[multi]set|map, record initial size and call context of the constructor, and correlate it with its size at destruction time.

    • Cost model: - Number of iteration operations + memory saved.

    • Example: + Number of iteration operations + memory saved.

    • Example: 

       1 vector<unordered_set<int>> v(100000, unordered_set<int>(100)) ;
 2 for (int k = 0; k < 100000; ++k) {
@@ -114,7 +114,7 @@ bytes of memory and M iteration steps.
   _GLIBCXX_PROFILE_INEFFICIENT_HASH.

    • Goal: Detect hashtables with polarized distribution. -

    • Fundamentals: A non-uniform +

    • Fundamentals: A non-uniform distribution may lead to long chains, thus possibly increasing complexity by a factor up to the number of elements.

    • Sample runtime reduction: factor up @@ -128,7 +128,7 @@ bytes of memory and M iteration steps.

    • Analysis: Count the exact number of link traversals.

    • Cost model: - Total number of links traversed.

    • Example: + Total number of links traversed.

    • Example: 

       class dumb_hash {
  public:
@@ -143,7 +143,7 @@ class dumb_hash {

    Vector Too Small

    • Switch: _GLIBCXX_PROFILE_VECTOR_TOO_SMALL. -

    • Goal:Detect vectors with many +

    • Goal:Detect vectors with many resize operations, small construction size and large destruction size..

    • Fundamentals:Resizing can be expensive. Copying large amounts of data takes time. Resizing many small vectors may @@ -153,17 +153,17 @@ class dumb_hash {

    • Analysis: For each dynamic instance of vector, record initial size and call context of the constructor. - Record size increase, if any, after each relevant operation such as + Record size increase, if any, after each relevant operation such as push_back. Record the estimated resize cost.

    • Cost model: - Total number of words copied * time to copy a word.

    • Example: + Total number of words copied * time to copy a word.

    • Example: 

       1 vector<int> v;
 2 for (int k = 0; k < 1000000; ++k) {
 3   v.push_back(k);
 4 }
 
-foo.cc:1: advice: Changing initial vector size from 10 to 1000000 saves 
+foo.cc:1: advice: Changing initial vector size from 10 to 1000000 saves
 copying 4000000 bytes and 20 memory allocations and deallocations.

    Vector Too Large

    • Switch: @@ -180,7 +180,7 @@ copying 4000000 bytes and 20 memory allocations and deallocations. For each dynamic instance of vector, record initial size and call context of the constructor, and correlate it with its size at destruction time.

    • Cost model: - Total amount of memory saved.

    • Example: + Total amount of memory saved.

    • Example: 

       1 vector<vector<int>> v(100000, vector<int>(100)) ;
 2 for (int k = 0; k < 100000; ++k) {
@@ -194,20 +194,20 @@ bytes of memory and may reduce the number of cache and TLB misses.

    Vector to Hashtable

    • Switch: _GLIBCXX_PROFILE_VECTOR_TO_HASHTABLE. -

    • Goal: Detect uses of +

    • Goal: Detect uses of vector that can be substituted with unordered_set to reduce execution time.

    • Fundamentals: Linear search in a vector is very expensive, whereas searching in a hashtable is very quick.

    • Sample runtime reduction:factor up to container size. -

    • Recommendation:Replace +

    • Recommendation:Replace vector with unordered_set at site S.

    • To instrument:vector operations and access methods.

    • Analysis: For each dynamic instance of vector, record call context of the constructor. Issue the advice only if the - only methods called on this vector are push_back, + only methods called on this vector are push_back, insert and find.

    • Cost model: Cost(vector::push_back) + cost(vector::insert) + cost(find, vector) - @@ -225,18 +225,18 @@ comparisons.

    Hashtable to Vector

    • Switch: _GLIBCXX_PROFILE_HASHTABLE_TO_VECTOR. -

    • Goal: Detect uses of +

    • Goal: Detect uses of unordered_set that can be substituted with vector to reduce execution time.

    • Fundamentals: Hashtable iterator is slower than vector iterator.

    • Sample runtime reduction:95%. -

    • Recommendation:Replace +

    • Recommendation:Replace unordered_set with vector at site S.

    • To instrument:unordered_set operations and access methods.

    • Analysis: For each dynamic instance of unordered_set, record call context of the constructor. Issue the advice only if the - number of find, insert and [] + number of find, insert and [] operations on this unordered_set are small relative to the number of elements, and methods begin or end are invoked (suggesting iteration).

    • Cost model: @@ -254,11 +254,11 @@ indirections and may achieve better data locality.

    Vector to List

    • Switch: _GLIBCXX_PROFILE_VECTOR_TO_LIST. -

    • Goal: Detect cases where +

    • Goal: Detect cases where vector could be substituted with list for better performance.

    • Fundamentals: - Inserting in the middle of a vector is expensive compared to inserting in a + Inserting in the middle of a vector is expensive compared to inserting in a list.

    • Sample runtime reduction:factor up to container size. @@ -272,19 +272,19 @@ indirections and may achieve better data locality.

    • Cost model: (Sum(cost(vector::method)) - Sum(cost(list::method)), for method in [push_back, insert, erase]) - + (Cost(iterate vector) - Cost(iterate list))

    • Example: + + (Cost(iterate vector) - Cost(iterate list))

    • Example: 

       1  vector<int> v;
 2  for (int i = 0; i < 10000; ++i) {
 3    v.insert(v.begin(), i);
 4  }
 
-foo.cc:1: advice: Changing "vector" to "list" will save about 5,000,000 
+foo.cc:1: advice: Changing "vector" to "list" will save about 5,000,000
 operations.

    List to Vector

    • Switch: _GLIBCXX_PROFILE_LIST_TO_VECTOR. -

    • Goal: Detect cases where +

    • Goal: Detect cases where list could be substituted with vector for better performance.

    • Fundamentals: @@ -297,7 +297,7 @@ operations.

    • Cost model: (Sum(cost(vector::method)) - Sum(cost(list::method)), for method in [push_back, insert, erase]) - + (Cost(iterate vector) - Cost(iterate list))

    • Example: + + (Cost(iterate vector) - Cost(iterate list))

    • Example: 

       1  list<int> l;
 ...
@@ -311,7 +311,7 @@ memory references.

    List to Forward List (Slist)

    • Switch: _GLIBCXX_PROFILE_LIST_TO_SLIST. -

    • Goal: Detect cases where +

    • Goal: Detect cases where list could be substituted with forward_list for better performance.

    • Fundamentals: @@ -328,7 +328,7 @@ memory references. Issue the advice if there are no backwards traversals or insertion before a given node.

    • Cost model: - Always true.

    • Example: + Always true.

    • Example: 

       1  list<int> l;
 ...
@@ -344,7 +344,7 @@ foo.cc:1: advice: Change "list" to "forward_list".

    • Goal: Detect cases where ordered associative containers can be replaced with unordered ones.

    • Fundamentals: - Insert and search are quicker in a hashtable than in + Insert and search are quicker in a hashtable than in a red-black tree.

    • Sample runtime reduction:52%.

    • Recommendation: Replace set with unordered_set at site S.

    • To instrument: @@ -374,9 +374,9 @@ foo.cc:1: advice: Change "list" to "forward_list". performance based on actual input. For instance, advise Radix Sort over Quick Sort for a particular call context.

    • Fundamentals: - See papers: + See papers: - A framework for adaptive algorithm selection in STAPL and + A framework for adaptive algorithm selection in STAPL and Optimizing Sorting with Machine Learning Algorithms.

    • Sample runtime reduction:60%. @@ -384,7 +384,7 @@ foo.cc:1: advice: Change "list" to "forward_list". at site S from X Sort to Y Sort.

    • To instrument: sort algorithm.

    • Analysis: Issue the advice if the cost model tells us that another sort algorithm - would do better on this input. Requires us to know what algorithm we + would do better on this input. Requires us to know what algorithm we are using in our sort implementation in release mode.

    • Cost model: Runtime(algo) for algo in [radix, quick, merge, ...]

    • Example: 

      @@ -399,13 +399,13 @@ foo.cc:1: advice: Change "list" to "forward_list".

    • Fundamentals: Indirect references are hard to predict and are very expensive when they miss in caches.

    • Sample runtime reduction:25%. -

    • Recommendation: Insert prefetch +

    • Recommendation: Insert prefetch instruction.

    • To instrument: Vector iterator and access operator [].

    • Analysis: First, get cache line size and page size from system. Then record iterator dereference sequences for which the value is a pointer. - For each sequence within a container, issue a warning if successive pointer + For each sequence within a container, issue a warning if successive pointer addresses are not within cache lines and do not form a linear pattern (otherwise they may be prefetched by hardware). If they also step across page boundaries, make the warning stronger. @@ -417,11 +417,11 @@ foo.cc:1: advice: Change "list" to "forward_list".

      This analysis is a little oversimplified. A better cost model could be created by understanding the capability of the hardware prefetcher. - This model could be trained automatically by running a set of synthetic + This model could be trained automatically by running a set of synthetic cases.

    • Cost model: Total distance between pointer values of successive elements in vectors - of pointers.

    • Example: + of pointers.

    • Example: 

       1 int zero = 0;
 2 vector<int*> v(10000000, &zero);
@@ -441,14 +441,14 @@ foo.cc:7: advice: Insert prefetch instruction.
   with respect to their actual traversal patterns.

    • Fundamentals:Allocation can be tuned to a specific traversal pattern, to result in better data locality. - See paper: + See paper: Custom Memory Allocation for Free.

    • Sample runtime reduction:30%.

    • Recommendation: High scatter score N for container built at site S. Consider changing allocation sequence or choosing a structure conscious - allocator.

    • To instrument: Methods of all + allocator.

    • To instrument: Methods of all containers using linked structures.

    • Analysis: First, get cache line size and page size from system. Then record the number of successive elements that are on different line @@ -502,7 +502,7 @@ the allocation sequence or switching to a structure conscious allocator. container member accesses. Issue advice for elements referenced by multiple threads. See paper: - The LRPD test: speculative run-time parallelization of loops with + The LRPD test: speculative run-time parallelization of loops with privatization and reduction parallelization.

    • Cost model: Number of accesses to elements referenced from multiple threads @@ -512,7 +512,7 @@ the allocation sequence or switching to a structure conscious allocator.

    False Sharing

    • Switch: _GLIBCXX_PROFILE_FALSE_SHARING.

    • Goal: Detect elements in the - same container which share a cache line, are written by at least one + same container which share a cache line, are written by at least one thread, and accessed by different threads.

    • Fundamentals: Under these assumptions, cache protocols require @@ -523,14 +523,14 @@ the allocation sequence or switching to a structure conscious allocator. and iterators.

    • Analysis: First, get the cache line size. - For each shared container, record all the associated iterator dereferences + For each shared container, record all the associated iterator dereferences and member access methods with the thread id. Compare the address lists - across threads to detect references in two different threads to the same - cache line. Issue a warning only if the ratio to total references is - significant. Do the same for iterator dereference values if they are + across threads to detect references in two different threads to the same + cache line. Issue a warning only if the ratio to total references is + significant. Do the same for iterator dereference values if they are pointers.

    • Cost model: Number of accesses to same cache line from different threads. -

    • Example: +

    • Example: 

       1     vector<int> v(2, 0);
 2 #pragma omp parallel for shared(v, SIZE) schedule(static, 1)
@@ -539,7 +539,7 @@ the allocation sequence or switching to a structure conscious allocator.
 5     }
 
 OMP_NUM_THREADS=2 ./a.out
-foo.cc:1: advice: Change container structure or padding to avoid false 
+foo.cc:1: advice: Change container structure or padding to avoid false
 sharing in multithreaded access at foo.cc:4.  Detected N shared cache lines.

    Statistics

    @@ -555,4 +555,4 @@ sharing in multithreaded access at foo.cc:4. Detected N shared cache lines. This diagnostic will not issue any advice, but it will print statistics for each container construction site. The statistics will contain the cost of each operation actually performed on the container. -

    Prev Up Next
    Developer Information Home Chapter 33. Allocators
    +

    Prev Up Next
    Developer Information Home Chapter 20. Allocators
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt12ch34s02.html b/libstdc++-v3/doc/html/manual/bk01pt03ch21s02.html similarity index 89% rename from libstdc++-v3/doc/html/manual/bk01pt12ch34s02.html rename to libstdc++-v3/doc/html/manual/bk01pt03ch21s02.html index 70e4d924cec..185d3ad8df4 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt12ch34s02.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch21s02.html @@ -1,6 +1,6 @@ -HP/SGI
    HP/SGI
    Prev Chapter 34. Containers Next

    HP/SGI

    +HP/SGI

    HP/SGI
    Prev Chapter 21. Containers Next

    HP/SGI

    A few extensions and nods to backwards-compatibility have been made with containers. Those dealing with older SGI-style allocators are dealt with elsewhere. The remaining ones all deal with bits: @@ -26,7 +26,7 @@

    Note that these may in fact be removed in the future, although we have no present plans to do so (and there doesn't seem to be any immediate reason to). -

    The semantics of member function operator[] are not specified +

    The semantics of member function operator[] are not specified in the C++ standard. A long-standing defect report calls for sensible obvious semantics, which are already implemented here: op[] on a const bitset returns a bool, and for a non-const bitset returns a @@ -40,4 +40,4 @@ 

        size_t _Find_first() const;
    size_t _Find_next (size_t prev) const;

    The same caveat given for the _Unchecked_* functions applies here also. -

    Prev Up Next
    Chapter 34. Containers Home Deprecated HP/SGI
    +

    Prev Up Next
    Chapter 21. Containers Home Deprecated HP/SGI
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt12ch34s03.html b/libstdc++-v3/doc/html/manual/bk01pt03ch21s03.html similarity index 92% rename from libstdc++-v3/doc/html/manual/bk01pt12ch34s03.html rename to libstdc++-v3/doc/html/manual/bk01pt03ch21s03.html index b9f0849bf5a..7486167b089 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt12ch34s03.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch21s03.html @@ -1,6 +1,6 @@ -Deprecated HP/SGI
    Deprecated HP/SGI
    Prev Chapter 34. Containers Next

    Deprecated HP/SGI

    +Deprecated HP/SGI

    Deprecated HP/SGI
    Prev Chapter 21. Containers Next

    Deprecated HP/SGI

    The SGI hashing classes hash_set and hash_set have been deprecated by the unordered_set, unordered_multiset, unordered_map, @@ -47,4 +47,4 @@ possibility of pathological cases, you'll probably get better performance from hash_map. -

    Prev Up Next
    HP/SGI Home Chapter 35. Utilities
    +

    Prev Up Next
    HP/SGI Home Chapter 22. Utilities
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt12ch41s02.html b/libstdc++-v3/doc/html/manual/bk01pt03ch28s02.html similarity index 92% rename from libstdc++-v3/doc/html/manual/bk01pt12ch41s02.html rename to libstdc++-v3/doc/html/manual/bk01pt03ch28s02.html index 6dee3ae2abb..ec4a92763c4 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt12ch41s02.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch28s02.html @@ -1,6 +1,6 @@ -Implementation
    Implementation
    Prev Chapter 41. Concurrency Next

    Implementation

    Using Builtin Atomic Functions

    The functions for atomic operations described above are either +Implementation

    Implementation
    Prev Chapter 28. Concurrency Next

    Implementation

    Using Builtin Atomic Functions

    The functions for atomic operations described above are either implemented via compiler intrinsics (if the underlying host is capable) or by library fallbacks.

    Compiler intrinsics (builtins) are always preferred. However, as the compiler builtins for atomics are not universally implemented, @@ -12,7 +12,7 @@ missing reference to __sync_fetch_and_add_4.) conditionally, via the -march command line flag. This makes usage vary depending on the target hardware and the flags used during compile. -

    +

    If builtins are possible for bool-sized integral types, _GLIBCXX_ATOMIC_BUILTINS_1 will be defined. If builtins are possible for int-sized integral types, @@ -38,4 +38,4 @@ use this layer. More detail as to the specific interface can be found in the sou functions, and usage found in the usual <pthread.h> file, including pthread_t, pthread_once_t, pthread_create, etc. -

    Prev Up Next
    Chapter 41. Concurrency Home Use
    +

    Prev Up Next
    Chapter 28. Concurrency Home Use
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt12ch41s03.html b/libstdc++-v3/doc/html/manual/bk01pt03ch28s03.html similarity index 63% rename from libstdc++-v3/doc/html/manual/bk01pt12ch41s03.html rename to libstdc++-v3/doc/html/manual/bk01pt03ch28s03.html index deb28ca2ca4..e5835a70b76 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt12ch41s03.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03ch28s03.html @@ -1,6 +1,6 @@ -Use
    Use
    Prev Chapter 41. Concurrency Next

    Use

    Typical usage of the last two constructs is demonstrated as follows: +Use

    Use
    Prev Chapter 28. Concurrency Next

    Use

    Typical usage of the last two constructs is demonstrated as follows: 

     #include <ext/concurrence.h>
 
@@ -31,7 +31,6 @@ the mutex as control moves out of this block.
 concurrence-related errors. These classes
 are: __concurrence_lock_error, __concurrence_unlock_error, __concurrence_wait_error,
 and __concurrence_broadcast_error.
-
    Prev Up Next
    Implementation Home Appendix A.  - Contributing - +

    Prev Up Next
    Implementation Home Part IV.  + Appendices
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt12pr03.html b/libstdc++-v3/doc/html/manual/bk01pt03pr01.html similarity index 81% rename from libstdc++-v3/doc/html/manual/bk01pt12pr03.html rename to libstdc++-v3/doc/html/manual/bk01pt03pr01.html index a3af7c689c3..be1c0f16ae2 100644 --- a/libstdc++-v3/doc/html/manual/bk01pt12pr03.html +++ b/libstdc++-v3/doc/html/manual/bk01pt03pr01.html @@ -1,26 +1,26 @@ -
    Prev Part XII.  +
    Prev Part III.  Extensions - Next

    +

    		 Next

    Here we will make an attempt at describing the non-Standard extensions to the library. Some of these are from SGI's STL, some of these are GNU's, and some just seemed to appear on the doorstep.

    Before you leap in and use any of these extensions, be aware of two things:

    1. - Non-Standard means exactly that. + Non-Standard means exactly that.

      The behavior, and the very existence, of these extensions may change with little or no warning. (Ideally, the really good ones will appear in the next revision of C++.) Also, other platforms, other compilers, other versions of g++ or libstdc++ may not recognize these names, or - treat them differently, or... + treat them differently, or...

    2. - You should know how to access these headers properly. -

    Prev Up Next
    Part XII.  + You should know how to access these headers properly. +

    Prev Up Next
    Part III.  Extensions - Home Chapter 29. Compile Time Checks
    +     		Home Chapter 16. Compile Time Checks
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt04.html b/libstdc++-v3/doc/html/manual/bk01pt04.html new file mode 100644 index 00000000000..66713b1213d --- /dev/null +++ b/libstdc++-v3/doc/html/manual/bk01pt04.html @@ -0,0 +1,21 @@ + + +Part IV.  Appendices
    Part IV.  + Appendices +
    Prev The GNU C++ Library Next

    Part IV.  + Appendices +

    Table of Contents

    A. + Contributing + +
    Contributor Checklist
    Reading
    Assignment
    Getting Sources
    Submitting Patches
    Directory Layout and Source Conventions
    Coding Style
    Bad Identifiers
    By Example
    Documentation Style
    Doxygen
    Docbook
    Combines
    Design Notes
    B. + Porting and Maintenance + +
    Configure and Build Hacking
    Prerequisites
    Overview: What Comes from Where
    Storing Information in non-AC files (like configure.host)
    Coding and Commenting Conventions
    The acinclude.m4 layout
    GLIBCXX_ENABLE, the --enable maker
    Porting to New Hardware or Operating Systems
    Operating System
    CPU
    Character Types
    Thread Safety
    Numeric Limits
    Libtool
    Test
    Organization
    Running the Testsuite
    Writing a new test case
    Test Harness and Utilities
    Special Topics
    ABI Policy and Guidelines
    The C++ Interface
    Versioning
    Allowed Changes
    Prohibited Changes
    Implementation
    Testing
    Outstanding Issues
    API Evolution and Deprecation History
    3.0
    3.1
    3.2
    3.3
    3.4
    4.0
    4.1
    4.2
    4.3
    4.4
    4.5
    Backwards Compatibility
    First
    Second
    Third
    C. + Free Software Needs Free Documentation + +
    D. + GNU General Public License version 3 +
    E. GNU Free Documentation License
    Prev Up Next
    Use Home Appendix A.  + Contributing + +
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt05ch13.html b/libstdc++-v3/doc/html/manual/bk01pt05ch13.html deleted file mode 100644 index e86d7fe1779..00000000000 --- a/libstdc++-v3/doc/html/manual/bk01pt05ch13.html +++ /dev/null @@ -1,90 +0,0 @@ - - -Chapter 13. String Classes
    Chapter 13. String Classes
    Prev Part V.  - Strings - - Next

    Chapter 13. String Classes

    Table of Contents

    Simple Transformations
    Case Sensitivity
    Arbitrary Character Types
    Tokenizing
    Shrink to Fit
    CString (MFC)

    Simple Transformations

    - Here are Standard, simple, and portable ways to perform common - transformations on a string instance, such as - "convert to all upper case." The word transformations - is especially apt, because the standard template function - transform<> is used. -

    - This code will go through some iterations. Here's a simple - version: - 

    -   #include <string>
-   #include <algorithm>
-   #include <cctype>      // old <ctype.h>
-
-   struct ToLower
-   {
-     char operator() (char c) const  { return std::tolower(c); }
-   };
-
-   struct ToUpper
-   {
-     char operator() (char c) const  { return std::toupper(c); }
-   };
-
-   int main()
-   {
-     std::string  s ("Some Kind Of Initial Input Goes Here");
-
-     // Change everything into upper case
-     std::transform (s.begin(), s.end(), s.begin(), ToUpper());
-
-     // Change everything into lower case
-     std::transform (s.begin(), s.end(), s.begin(), ToLower());
-
-     // Change everything back into upper case, but store the
-     // result in a different string
-     std::string  capital_s;
-     capital_s.resize(s.size());
-     std::transform (s.begin(), s.end(), capital_s.begin(), ToUpper());
-   } 
-

    - Note that these calls all - involve the global C locale through the use of the C functions - toupper/tolower. This is absolutely guaranteed to work -- - but only if the string contains only characters - from the basic source character set, and there are only - 96 of those. Which means that not even all English text can be - represented (certain British spellings, proper names, and so forth). - So, if all your input forevermore consists of only those 96 - characters (hahahahahaha), then you're done. -

    Note that the - ToUpper and ToLower function objects - are needed because toupper and tolower - are overloaded names (declared in <cctype> and - <locale>) so the template-arguments for - transform<> cannot be deduced, as explained in - this - message. - - At minimum, you can write short wrappers like - 

    -   char toLower (char c)
-   {
-      return std::tolower(c);
-   }

    (Thanks to James Kanze for assistance and suggestions on all of this.) -

    Another common operation is trimming off excess whitespace. Much - like transformations, this task is trivial with the use of string's - find family. These examples are broken into multiple - statements for readability: - 

    -   std::string  str (" \t blah blah blah    \n ");
-
-   // trim leading whitespace
-   string::size_type  notwhite = str.find_first_not_of(" \t\n");
-   str.erase(0,notwhite);
-
-   // trim trailing whitespace
-   notwhite = str.find_last_not_of(" \t\n"); 
-   str.erase(notwhite+1);

    Obviously, the calls to find could be inserted directly - into the calls to erase, in case your compiler does not - optimize named temporaries out of existence. -

    Prev Up Next
    Part V.  - Strings - - Home Case Sensitivity
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt05ch13s02.html b/libstdc++-v3/doc/html/manual/bk01pt05ch13s02.html deleted file mode 100644 index 2cd970a12bf..00000000000 --- a/libstdc++-v3/doc/html/manual/bk01pt05ch13s02.html +++ /dev/null @@ -1,40 +0,0 @@ - - -Case Sensitivity
    Case Sensitivity
    Prev Chapter 13. String Classes Next

    Case Sensitivity

    -

    The well-known-and-if-it-isn't-well-known-it-ought-to-be - Guru of the Week - discussions held on Usenet covered this topic in January of 1998. - Briefly, the challenge was, “write a 'ci_string' class which - is identical to the standard 'string' class, but is - case-insensitive in the same way as the (common but nonstandard) - C function stricmp()”. - 

    -   ci_string s( "AbCdE" );
-
-   // case insensitive
-   assert( s == "abcde" );
-   assert( s == "ABCDE" );
-
-   // still case-preserving, of course
-   assert( strcmp( s.c_str(), "AbCdE" ) == 0 );
-   assert( strcmp( s.c_str(), "abcde" ) != 0 );

    The solution is surprisingly easy. The original answer was - posted on Usenet, and a revised version appears in Herb Sutter's - book Exceptional C++ and on his website as GotW 29. -

    See? Told you it was easy!

    - Added June 2000: The May 2000 issue of C++ - Report contains a fascinating article by - Matt Austern (yes, the Matt Austern) on why - case-insensitive comparisons are not as easy as they seem, and - why creating a class is the wrong way to go - about it in production code. (The GotW answer mentions one of - the principle difficulties; his article mentions more.) -

    Basically, this is "easy" only if you ignore some things, - things which may be too important to your program to ignore. (I chose - to ignore them when originally writing this entry, and am surprised - that nobody ever called me on it...) The GotW question and answer - remain useful instructional tools, however. -

    Added September 2000: James Kanze provided a link to a - Unicode - Technical Report discussing case handling, which provides some - very good information. -

    Prev Up Next
    Chapter 13. String Classes Home Arbitrary Character Types
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt05ch13s03.html b/libstdc++-v3/doc/html/manual/bk01pt05ch13s03.html deleted file mode 100644 index aa2afea53a6..00000000000 --- a/libstdc++-v3/doc/html/manual/bk01pt05ch13s03.html +++ /dev/null @@ -1,57 +0,0 @@ - - -Arbitrary Character Types
    Arbitrary Character Types
    Prev Chapter 13. String Classes Next

    Arbitrary Character Types

    -

    The std::basic_string is tantalizingly general, in that - it is parameterized on the type of the characters which it holds. - In theory, you could whip up a Unicode character class and instantiate - std::basic_string<my_unicode_char>, or assuming - that integers are wider than characters on your platform, maybe just - declare variables of type std::basic_string<int>. -

    That's the theory. Remember however that basic_string has additional - type parameters, which take default arguments based on the character - type (called CharT here): - 

    -      template <typename CharT,
-                typename Traits = char_traits<CharT>,
-                typename Alloc = allocator<CharT> >
-      class basic_string { .... };

    Now, allocator<CharT> will probably Do The Right - Thing by default, unless you need to implement your own allocator - for your characters. -

    But char_traits takes more work. The char_traits - template is declared but not defined. - That means there is only - 

    -      template <typename CharT>
-        struct char_traits
-        {
-            static void foo (type1 x, type2 y);
-            ...
-        };

    and functions such as char_traits<CharT>::foo() are not - actually defined anywhere for the general case. The C++ standard - permits this, because writing such a definition to fit all possible - CharT's cannot be done. -

    The C++ standard also requires that char_traits be specialized for - instantiations of char and wchar_t, and it - is these template specializations that permit entities like - basic_string<char,char_traits<char>> to work. -

    If you want to use character types other than char and wchar_t, - such as unsigned char and int, you will - need suitable specializations for them. For a time, in earlier - versions of GCC, there was a mostly-correct implementation that - let programmers be lazy but it broke under many situations, so it - was removed. GCC 3.4 introduced a new implementation that mostly - works and can be specialized even for int and other - built-in types. -

    If you want to use your own special character class, then you have - a lot - of work to do, especially if you with to use i18n features - (facets require traits information but don't have a traits argument). -

    Another example of how to specialize char_traits was given on the - mailing list and at a later date was put into the file - include/ext/pod_char_traits.h. We agree - that the way it's used with basic_string (scroll down to main()) - doesn't look nice, but that's because the - nice-looking first attempt turned out to not - be conforming C++, due to the rule that CharT must be a POD. - (See how tricky this is?) -

    Prev Up Next
    Case Sensitivity Home Tokenizing
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt05ch13s04.html b/libstdc++-v3/doc/html/manual/bk01pt05ch13s04.html deleted file mode 100644 index 12d1ee7fb5c..00000000000 --- a/libstdc++-v3/doc/html/manual/bk01pt05ch13s04.html +++ /dev/null @@ -1,79 +0,0 @@ - - -Tokenizing
    Tokenizing
    Prev Chapter 13. String Classes Next

    Tokenizing

    -

    The Standard C (and C++) function strtok() leaves a lot to - be desired in terms of user-friendliness. It's unintuitive, it - destroys the character string on which it operates, and it requires - you to handle all the memory problems. But it does let the client - code decide what to use to break the string into pieces; it allows - you to choose the "whitespace," so to speak. -

    A C++ implementation lets us keep the good things and fix those - annoyances. The implementation here is more intuitive (you only - call it once, not in a loop with varying argument), it does not - affect the original string at all, and all the memory allocation - is handled for you. -

    It's called stringtok, and it's a template function. Sources are - as below, in a less-portable form than it could be, to keep this - example simple (for example, see the comments on what kind of - string it will accept). - 

    -#include <string>
-template <typename Container>
-void
-stringtok(Container &container, string const &in,
-          const char * const delimiters = " \t\n")
-{
-    const string::size_type len = in.length();
-          string::size_type i = 0;
-
-    while (i < len)
-    {
-        // Eat leading whitespace
-        i = in.find_first_not_of(delimiters, i);
-        if (i == string::npos)
-	  return;   // Nothing left but white space
-
-        // Find the end of the token
-        string::size_type j = in.find_first_of(delimiters, i);
-
-        // Push token
-        if (j == string::npos) 
-	{
-	  container.push_back(in.substr(i));
-	  return;
-        } 
-	else
-	  container.push_back(in.substr(i, j-i));
-
-        // Set up for next loop
-        i = j + 1;
-    }
-}
-

    - The author uses a more general (but less readable) form of it for - parsing command strings and the like. If you compiled and ran this - code using it: - 

    -   std::list<string>  ls;
-   stringtok (ls, " this  \t is\t\n  a test  ");
-   for (std::list<string>const_iterator i = ls.begin();
-        i != ls.end(); ++i)
-   {
-       std::cerr << ':' << (*i) << ":\n";
-   }

    You would see this as output: - 

    -   :this:
-   :is:
-   :a:
-   :test:

    with all the whitespace removed. The original s is still - available for use, ls will clean up after itself, and - ls.size() will return how many tokens there were. -

    As always, there is a price paid here, in that stringtok is not - as fast as strtok. The other benefits usually outweigh that, however. -

    Added February 2001: Mark Wilden pointed out that the - standard std::getline() function can be used with standard - istringstreams to perform - tokenizing as well. Build an istringstream from the input text, - and then use std::getline with varying delimiters (the three-argument - signature) to extract tokens into a string. -

    Prev Up Next
    Arbitrary Character Types Home Shrink to Fit
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt05ch13s05.html b/libstdc++-v3/doc/html/manual/bk01pt05ch13s05.html deleted file mode 100644 index b6a5da10d20..00000000000 --- a/libstdc++-v3/doc/html/manual/bk01pt05ch13s05.html +++ /dev/null @@ -1,16 +0,0 @@ - - -Shrink to Fit
    Shrink to Fit
    Prev Chapter 13. String Classes Next

    Shrink to Fit

    -

    From GCC 3.4 calling s.reserve(res) on a - string s with res < s.capacity() will - reduce the string's capacity to std::max(s.size(), res). -

    This behaviour is suggested, but not required by the standard. Prior - to GCC 3.4 the following alternative can be used instead - 

    -      std::string(str.data(), str.size()).swap(str);
-

    This is similar to the idiom for reducing - a vector's memory usage - (see this FAQ - entry) but the regular copy constructor cannot be used - because libstdc++'s string is Copy-On-Write. -

    Prev Up Next
    Tokenizing Home CString (MFC)
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt05ch13s06.html b/libstdc++-v3/doc/html/manual/bk01pt05ch13s06.html deleted file mode 100644 index 29ad197e1dd..00000000000 --- a/libstdc++-v3/doc/html/manual/bk01pt05ch13s06.html +++ /dev/null @@ -1,94 +0,0 @@ - - -CString (MFC)
    CString (MFC)
    Prev Chapter 13. String Classes Next

    CString (MFC)

    -

    A common lament seen in various newsgroups deals with the Standard - string class as opposed to the Microsoft Foundation Class called - CString. Often programmers realize that a standard portable - answer is better than a proprietary nonportable one, but in porting - their application from a Win32 platform, they discover that they - are relying on special functions offered by the CString class. -

    Things are not as bad as they seem. In - this - message, Joe Buck points out a few very important things: -

    • The Standard string supports all the operations - that CString does, with three exceptions. -

    • Two of those exceptions (whitespace trimming and case - conversion) are trivial to implement. In fact, we do so - on this page. -

    • The third is CString::Format, which allows formatting - in the style of sprintf. This deserves some mention: -

    - The old libg++ library had a function called form(), which did much - the same thing. But for a Standard solution, you should use the - stringstream classes. These are the bridge between the iostream - hierarchy and the string class, and they operate with regular - streams seamlessly because they inherit from the iostream - hierarchy. An quick example: - 

    -   #include <iostream>
-   #include <string>
-   #include <sstream>
-
-   string f (string& incoming)     // incoming is "foo  N"
-   {
-       istringstream   incoming_stream(incoming);
-       string          the_word;
-       int             the_number;
-
-       incoming_stream >> the_word        // extract "foo"
-                       >> the_number;     // extract N
-
-       ostringstream   output_stream;
-       output_stream << "The word was " << the_word
-                     << " and 3*N was " << (3*the_number);
-
-       return output_stream.str();
-   }

    A serious problem with CString is a design bug in its memory - allocation. Specifically, quoting from that same message: - 

    -   CString suffers from a common programming error that results in
-   poor performance.  Consider the following code:
-   
-   CString n_copies_of (const CString& foo, unsigned n)
-   {
-           CString tmp;
-           for (unsigned i = 0; i < n; i++)
-                   tmp += foo;
-           return tmp;
-   }
-   
-   This function is O(n^2), not O(n).  The reason is that each +=
-   causes a reallocation and copy of the existing string.  Microsoft
-   applications are full of this kind of thing (quadratic performance
-   on tasks that can be done in linear time) -- on the other hand,
-   we should be thankful, as it's created such a big market for high-end
-   ix86 hardware. :-)
-   
-   If you replace CString with string in the above function, the
-   performance is O(n).
-

    Joe Buck also pointed out some other things to keep in mind when - comparing CString and the Standard string class: -

    • CString permits access to its internal representation; coders - who exploited that may have problems moving to string. -

    • Microsoft ships the source to CString (in the files - MFC\SRC\Str{core,ex}.cpp), so you could fix the allocation - bug and rebuild your MFC libraries. - Note: It looks like the CString shipped - with VC++6.0 has fixed this, although it may in fact have been - one of the VC++ SPs that did it. -

    • string operations like this have O(n) complexity - if the implementors do it correctly. The libstdc++ - implementors did it correctly. Other vendors might not. -

    • While parts of the SGI STL are used in libstdc++, their - string class is not. The SGI string is essentially - vector<char> and does not do any reference - counting like libstdc++'s does. (It is O(n), though.) - So if you're thinking about SGI's string or rope classes, - you're now looking at four possibilities: CString, the - libstdc++ string, the SGI string, and the SGI rope, and this - is all before any allocator or traits customizations! (More - choices than you can shake a stick at -- want fries with that?) -

    Prev Up Next
    Shrink to Fit Home Part VI.  - Localization - -
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt08ch19.html b/libstdc++-v3/doc/html/manual/bk01pt08ch19.html deleted file mode 100644 index 6b6bb02dbde..00000000000 --- a/libstdc++-v3/doc/html/manual/bk01pt08ch19.html +++ /dev/null @@ -1,39 +0,0 @@ - - -Chapter 19. Predefined
    Chapter 19. Predefined
    Prev Part VIII.  - Iterators - - Next

    Chapter 19. Predefined

    Table of Contents

    Iterators vs. Pointers
    One Past the End

    Iterators vs. Pointers

    - The following -FAQ entry points out that -iterators are not implemented as pointers. They are a generalization -of pointers, but they are implemented in libstdc++ as separate -classes. -

    Keeping that simple fact in mind as you design your code will - prevent a whole lot of difficult-to-understand bugs. -

    You can think of it the other way 'round, even. Since iterators - are a generalization, that means that pointers are - iterators, and that pointers can be used whenever an - iterator would be. All those functions in the Algorithms chapter - of the Standard will work just as well on plain arrays and their - pointers. -

    That doesn't mean that when you pass in a pointer, it gets wrapped - into some special delegating iterator-to-pointer class with a layer - of overhead. (If you think that's the case anywhere, you don't - understand templates to begin with...) Oh, no; if you pass - in a pointer, then the compiler will instantiate that template - using T* as a type, and good old high-speed pointer arithmetic as - its operations, so the resulting code will be doing exactly the same - things as it would be doing if you had hand-coded it yourself (for - the 273rd time). -

    How much overhead is there when using an iterator class? - Very little. Most of the layering classes contain nothing but - typedefs, and typedefs are "meta-information" that simply - tell the compiler some nicknames; they don't create code. That - information gets passed down through inheritance, so while the - compiler has to do work looking up all the names, your runtime code - does not. (This has been a prime concern from the beginning.) -

    Prev Up Next
    Part VIII.  - Iterators - - Home One Past the End
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt08ch19s02.html b/libstdc++-v3/doc/html/manual/bk01pt08ch19s02.html deleted file mode 100644 index 2a0e28d40da..00000000000 --- a/libstdc++-v3/doc/html/manual/bk01pt08ch19s02.html +++ /dev/null @@ -1,86 +0,0 @@ - - -One Past the End
    One Past the End
    Prev Chapter 19. Predefined Next

    One Past the End

    This starts off sounding complicated, but is actually very easy, - especially towards the end. Trust me. -

    Beginners usually have a little trouble understand the whole - 'past-the-end' thing, until they remember their early algebra classes - (see, they told you that stuff would come in handy!) and - the concept of half-open ranges. -

    First, some history, and a reminder of some of the funkier rules in - C and C++ for builtin arrays. The following rules have always been - true for both languages: -

    1. You can point anywhere in the array, or to the first element - past the end of the array. A pointer that points to one - past the end of the array is guaranteed to be as unique as a - pointer to somewhere inside the array, so that you can compare - such pointers safely. -

    2. You can only dereference a pointer that points into an array. - If your array pointer points outside the array -- even to just - one past the end -- and you dereference it, Bad Things happen. -

    3. Strictly speaking, simply pointing anywhere else invokes - undefined behavior. Most programs won't puke until such a - pointer is actually dereferenced, but the standards leave that - up to the platform. -

    The reason this past-the-end addressing was allowed is to make it - easy to write a loop to go over an entire array, e.g., - while (*d++ = *s++);. -

    So, when you think of two pointers delimiting an array, don't think - of them as indexing 0 through n-1. Think of them as boundary - markers: - 

    -
-   beginning            end
-     |                   |
-     |                   |               This is bad.  Always having to
-     |                   |               remember to add or subtract one.
-     |                   |               Off-by-one bugs very common here.
-     V                   V
-        array of N elements
-     |---|---|--...--|---|---|
-     | 0 | 1 |  ...  |N-2|N-1|
-     |---|---|--...--|---|---|
-
-     ^                       ^
-     |                       |
-     |                       |           This is good.  This is safe.  This
-     |                       |           is guaranteed to work.  Just don't
-     |                       |           dereference 'end'.
-   beginning                end
-
-

    See? Everything between the boundary markers is part of the array. - Simple. -

    Now think back to your junior-high school algebra course, when you - were learning how to draw graphs. Remember that a graph terminating - with a solid dot meant, "Everything up through this point," - and a graph terminating with an open dot meant, "Everything up - to, but not including, this point," respectively called closed - and open ranges? Remember how closed ranges were written with - brackets, [a,b], and open ranges were written with parentheses, - (a,b)? -

    The boundary markers for arrays describe a half-open range, - starting with (and including) the first element, and ending with (but - not including) the last element: [beginning,end). See, I - told you it would be simple in the end. -

    Iterators, and everything working with iterators, follows this same - time-honored tradition. A container's begin() method returns - an iterator referring to the first element, and its end() - method returns a past-the-end iterator, which is guaranteed to be - unique and comparable against any other iterator pointing into the - middle of the container. -

    Container constructors, container methods, and algorithms, all take - pairs of iterators describing a range of values on which to operate. - All of these ranges are half-open ranges, so you pass the beginning - iterator as the starting parameter, and the one-past-the-end iterator - as the finishing parameter. -

    This generalizes very well. You can operate on sub-ranges quite - easily this way; functions accepting a [first,last) range - don't know or care whether they are the boundaries of an entire {array, - sequence, container, whatever}, or whether they only enclose a few - elements from the center. This approach also makes zero-length - sequences very simple to recognize: if the two endpoints compare - equal, then the {array, sequence, container, whatever} is empty. -

    Just don't dereference end(). -

    Prev Up Next
    Chapter 19. Predefined Home Part IX.  - Algorithms - -
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt09ch20.html b/libstdc++-v3/doc/html/manual/bk01pt09ch20.html deleted file mode 100644 index a343f9c50f4..00000000000 --- a/libstdc++-v3/doc/html/manual/bk01pt09ch20.html +++ /dev/null @@ -1,19 +0,0 @@ - - -Chapter 20. Mutating
    Chapter 20. Mutating
    Prev Part IX.  - Algorithms - - Next

    Chapter 20. Mutating

    Table of Contents

    swap
    Specializations

    swap

    Specializations

    If you call std::swap(x,y); where x and y are standard - containers, then the call will automatically be replaced by a call to - x.swap(y); instead. -

    This allows member functions of each container class to take over, and - containers' swap functions should have O(1) complexity according to - the standard. (And while "should" allows implementations to - behave otherwise and remain compliant, this implementation does in - fact use constant-time swaps.) This should not be surprising, since - for two containers of the same type to swap contents, only some - internal pointers to storage need to be exchanged. -

    Prev Up Next
     Home Part X.  - Numerics - -
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt09pr02.html b/libstdc++-v3/doc/html/manual/bk01pt09pr02.html deleted file mode 100644 index c81bbee976e..00000000000 --- a/libstdc++-v3/doc/html/manual/bk01pt09pr02.html +++ /dev/null @@ -1,41 +0,0 @@ - - -
    Prev Part IX.  - Algorithms - - Next

    - The neatest accomplishment of the algorithms chapter is that all the - work is done via iterators, not containers directly. This means two - important things: -

    1. - Anything that behaves like an iterator can be used in one of - these algorithms. Raw pointers make great candidates, thus - built-in arrays are fine containers, as well as your own iterators. -

    2. - The algorithms do not (and cannot) affect the container as a - whole; only the things between the two iterator endpoints. If - you pass a range of iterators only enclosing the middle third of - a container, then anything outside that range is inviolate. -

    - Even strings can be fed through the algorithms here, although the - string class has specialized versions of many of these functions - (for example, string::find()). Most of the examples - on this page will use simple arrays of integers as a playground - for algorithms, just to keep things simple. The use of - N as a size in the examples is to keep - things easy to read but probably won't be valid code. You can - use wrappers such as those described in the containers chapter to - keep real code readable. -

    - The single thing that trips people up the most is the definition - of range used with iterators; the famous - "past-the-end" rule that everybody loves to hate. The - iterators - chapter of this document has a complete explanation of - this simple rule that seems to cause so much confusion. Once you - get range into your head (it's not that - hard, honest!), then the algorithms are a cakewalk. -

    Prev Up Next
    Part IX.  - Algorithms - - Home Chapter 20. Mutating
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt10ch23s02.html b/libstdc++-v3/doc/html/manual/bk01pt10ch23s02.html deleted file mode 100644 index 31c37c741cf..00000000000 --- a/libstdc++-v3/doc/html/manual/bk01pt10ch23s02.html +++ /dev/null @@ -1,19 +0,0 @@ - - -C99
    C99
    Prev Chapter 23. Interacting with C Next

    C99

    In addition to the other topics on this page, we'll note here some - of the C99 features that appear in libstdc++. -

    The C99 features depend on the --enable-c99 configure flag. - This flag is already on by default, but it can be disabled by the - user. Also, the configuration machinery will disable it if the - necessary support for C99 (e.g., header files) cannot be found. -

    As of GCC 3.0, C99 support includes classification functions - such as isnormal, isgreater, - isnan, etc. - The functions used for 'long long' support such as strtoll - are supported, as is the lldiv_t typedef. Also supported - are the wide character functions using 'long long', like - wcstoll. -

    Prev Up Next
    Chapter 23. Interacting with C Home Part XI.  - Input and Output - -
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt11ch25s02.html b/libstdc++-v3/doc/html/manual/bk01pt11ch25s02.html deleted file mode 100644 index b713ad2ef02..00000000000 --- a/libstdc++-v3/doc/html/manual/bk01pt11ch25s02.html +++ /dev/null @@ -1,77 +0,0 @@ - - -Buffering
    Buffering
    Prev Chapter 25. Stream Buffers Next

    Buffering

    First, are you sure that you understand buffering? Particularly - the fact that C++ may not, in fact, have anything to do with it? -

    The rules for buffering can be a little odd, but they aren't any - different from those of C. (Maybe that's why they can be a bit - odd.) Many people think that writing a newline to an output - stream automatically flushes the output buffer. This is true only - when the output stream is, in fact, a terminal and not a file - or some other device -- and that may not even be true - since C++ says nothing about files nor terminals. All of that is - system-dependent. (The "newline-buffer-flushing only occurring - on terminals" thing is mostly true on Unix systems, though.) -

    Some people also believe that sending endl down an - output stream only writes a newline. This is incorrect; after a - newline is written, the buffer is also flushed. Perhaps this - is the effect you want when writing to a screen -- get the text - out as soon as possible, etc -- but the buffering is largely - wasted when doing this to a file: - 

    -   output << "a line of text" << endl;
-   output << some_data_variable << endl;
-   output << "another line of text" << endl;

    The proper thing to do in this case to just write the data out - and let the libraries and the system worry about the buffering. - If you need a newline, just write a newline: - 

    -   output << "a line of text\n"
-          << some_data_variable << '\n'
-          << "another line of text\n";

    I have also joined the output statements into a single statement. - You could make the code prettier by moving the single newline to - the start of the quoted text on the last line, for example. -

    If you do need to flush the buffer above, you can send an - endl if you also need a newline, or just flush the buffer - yourself: - 

    -   output << ...... << flush;    // can use std::flush manipulator
-   output.flush();               // or call a member fn

    On the other hand, there are times when writing to a file should - be like writing to standard error; no buffering should be done - because the data needs to appear quickly (a prime example is a - log file for security-related information). The way to do this is - just to turn off the buffering before any I/O operations at - all have been done (note that opening counts as an I/O operation): - 

    -   std::ofstream    os;
-   std::ifstream    is;
-   int   i;
-
-   os.rdbuf()->pubsetbuf(0,0);
-   is.rdbuf()->pubsetbuf(0,0);
-
-   os.open("/foo/bar/baz");
-   is.open("/qux/quux/quuux");
-   ...
-   os << "this data is written immediately\n";
-   is >> i;   // and this will probably cause a disk read

    Since all aspects of buffering are handled by a streambuf-derived - member, it is necessary to get at that member with rdbuf(). - Then the public version of setbuf can be called. The - arguments are the same as those for the Standard C I/O Library - function (a buffer area followed by its size). -

    A great deal of this is implementation-dependent. For example, - streambuf does not specify any actions for its own - setbuf()-ish functions; the classes derived from - streambuf each define behavior that "makes - sense" for that class: an argument of (0,0) turns off buffering - for filebuf but does nothing at all for its siblings - stringbuf and strstreambuf, and specifying - anything other than (0,0) has varying effects. - User-defined classes derived from streambuf can - do whatever they want. (For filebuf and arguments for - (p,s) other than zeros, libstdc++ does what you'd expect: - the first s bytes of p are used as a buffer, - which you must allocate and deallocate.) -

    A last reminder: there are usually more buffers involved than - just those at the language/library level. Kernel buffers, disk - buffers, and the like will also have an effect. Inspecting and - changing those are system-dependent. -

    Prev Up Next
    Chapter 25. Stream Buffers Home Chapter 26. Memory Based Streams
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt11ch27s02.html b/libstdc++-v3/doc/html/manual/bk01pt11ch27s02.html deleted file mode 100644 index 4366e8fd8c0..00000000000 --- a/libstdc++-v3/doc/html/manual/bk01pt11ch27s02.html +++ /dev/null @@ -1,101 +0,0 @@ - - -Binary Input and Output
    Binary Input and Output
    Prev Chapter 27. File Based Streams Next

    Binary Input and Output

    -

    The first and most important thing to remember about binary I/O is - that opening a file with ios::binary is not, repeat - not, the only thing you have to do. It is not a silver - bullet, and will not allow you to use the <</>> - operators of the normal fstreams to do binary I/O. -

    Sorry. Them's the breaks. -

    This isn't going to try and be a complete tutorial on reading and - writing binary files (because "binary" - covers a lot of ground), but we will try and clear - up a couple of misconceptions and common errors. -

    First, ios::binary has exactly one defined effect, no more - and no less. Normal text mode has to be concerned with the newline - characters, and the runtime system will translate between (for - example) '\n' and the appropriate end-of-line sequence (LF on Unix, - CRLF on DOS, CR on Macintosh, etc). (There are other things that - normal mode does, but that's the most obvious.) Opening a file in - binary mode disables this conversion, so reading a CRLF sequence - under Windows won't accidentally get mapped to a '\n' character, etc. - Binary mode is not supposed to suddenly give you a bitstream, and - if it is doing so in your program then you've discovered a bug in - your vendor's compiler (or some other part of the C++ implementation, - possibly the runtime system). -

    Second, using << to write and >> to - read isn't going to work with the standard file stream classes, even - if you use skipws during reading. Why not? Because - ifstream and ofstream exist for the purpose of formatting, - not reading and writing. Their job is to interpret the data into - text characters, and that's exactly what you don't want to happen - during binary I/O. -

    Third, using the get() and put()/write() member - functions still aren't guaranteed to help you. These are - "unformatted" I/O functions, but still character-based. - (This may or may not be what you want, see below.) -

    Notice how all the problems here are due to the inappropriate use - of formatting functions and classes to perform something - which requires that formatting not be done? There are a - seemingly infinite number of solutions, and a few are listed here: -

    • “Derive your own fstream-type classes and write your own - <</>> operators to do binary I/O on whatever data - types you're using.” -

      - This is a Bad Thing, because while - the compiler would probably be just fine with it, other humans - are going to be confused. The overloaded bitshift operators - have a well-defined meaning (formatting), and this breaks it. -

    • - “Build the file structure in memory, then - mmap() the file and copy the - structure. - ” -

      - Well, this is easy to make work, and easy to break, and is - pretty equivalent to using ::read() and - ::write() directly, and makes no use of the - iostream library at all... -

    • - “Use streambufs, that's what they're there for.” -

      - While not trivial for the beginner, this is the best of all - solutions. The streambuf/filebuf layer is the layer that is - responsible for actual I/O. If you want to use the C++ - library for binary I/O, this is where you start. -

    How to go about using streambufs is a bit beyond the scope of this - document (at least for now), but while streambufs go a long way, - they still leave a couple of things up to you, the programmer. - As an example, byte ordering is completely between you and the - operating system, and you have to handle it yourself. -

    Deriving a streambuf or filebuf - class from the standard ones, one that is specific to your data - types (or an abstraction thereof) is probably a good idea, and - lots of examples exist in journals and on Usenet. Using the - standard filebufs directly (either by declaring your own or by - using the pointer returned from an fstream's rdbuf()) - is certainly feasible as well. -

    One area that causes problems is trying to do bit-by-bit operations - with filebufs. C++ is no different from C in this respect: I/O - must be done at the byte level. If you're trying to read or write - a few bits at a time, you're going about it the wrong way. You - must read/write an integral number of bytes and then process the - bytes. (For example, the streambuf functions take and return - variables of type int_type.) -

    Another area of problems is opening text files in binary mode. - Generally, binary mode is intended for binary files, and opening - text files in binary mode means that you now have to deal with all of - those end-of-line and end-of-file problems that we mentioned before. -

    - An instructive thread from comp.lang.c++.moderated delved off into - this topic starting more or less at - this - post and continuing to the end of the thread. (The subject heading is "binary iostreams" on both comp.std.c++ - and comp.lang.c++.moderated.) Take special note of the replies by James Kanze and Dietmar Kühl. -

    Briefly, the problems of byte ordering and type sizes mean that - the unformatted functions like ostream::put() and - istream::get() cannot safely be used to communicate - between arbitrary programs, or across a network, or from one - invocation of a program to another invocation of the same program - on a different platform, etc. -

    Prev Up Next
    Chapter 27. File Based Streams Home Chapter 28. Interacting with C
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt11ch28s02.html b/libstdc++-v3/doc/html/manual/bk01pt11ch28s02.html deleted file mode 100644 index 69fa0f12ec1..00000000000 --- a/libstdc++-v3/doc/html/manual/bk01pt11ch28s02.html +++ /dev/null @@ -1,49 +0,0 @@ - - -Performance
    Performance
    Prev Chapter 28. Interacting with C Next

    Performance

    - Pathetic Performance? Ditch C. -

    It sounds like a flame on C, but it isn't. Really. Calm down. - I'm just saying it to get your attention. -

    Because the C++ library includes the C library, both C-style and - C++-style I/O have to work at the same time. For example: - 

    -     #include <iostream>
-     #include <cstdio>
-
-     std::cout << "Hel";
-     std::printf ("lo, worl");
-     std::cout << "d!\n";
-

    This must do what you think it does. -

    Alert members of the audience will immediately notice that buffering - is going to make a hash of the output unless special steps are taken. -

    The special steps taken by libstdc++, at least for version 3.0, - involve doing very little buffering for the standard streams, leaving - most of the buffering to the underlying C library. (This kind of - thing is tricky to get right.) - The upside is that correctness is ensured. The downside is that - writing through cout can quite easily lead to awful - performance when the C++ I/O library is layered on top of the C I/O - library (as it is for 3.0 by default). Some patches have been applied - which improve the situation for 3.1. -

    However, the C and C++ standard streams only need to be kept in sync - when both libraries' facilities are in use. If your program only uses - C++ I/O, then there's no need to sync with the C streams. The right - thing to do in this case is to call - 

    -     #include any of the I/O headers such as ios, iostream, etc
-
-     std::ios::sync_with_stdio(false);
-

    You must do this before performing any I/O via the C++ stream objects. - Once you call this, the C++ streams will operate independently of the - (unused) C streams. For GCC 3.x, this means that cout and - company will become fully buffered on their own. -

    Note, by the way, that the synchronization requirement only applies to - the standard streams (cin, cout, - cerr, - clog, and their wide-character counterparts). File stream - objects that you declare yourself have no such requirement and are fully - buffered. -

    Prev Up Next
    Chapter 28. Interacting with C Home Part XII.  - Extensions - -
    diff --git a/libstdc++-v3/doc/html/manual/bk01pt12ch30s03.html b/libstdc++-v3/doc/html/manual/bk01pt12ch30s03.html deleted file mode 100644 index 2d56fc66378..00000000000 --- a/libstdc++-v3/doc/html/manual/bk01pt12ch30s03.html +++ /dev/null @@ -1,24 +0,0 @@ - - -Using
    Using
    Prev Chapter 30. Debug Mode Next

    Using

    -

    Using the Debug Mode

    To use the libstdc++ debug mode, compile your application with the - compiler flag -D_GLIBCXX_DEBUG. Note that this flag - changes the sizes and behavior of standard class templates such - as std::vector, and therefore you can only link code - compiled with debug mode and code compiled without debug mode if no - instantiation of a container is passed between the two translation - units.

    By default, error messages are formatted to fit on lines of about - 78 characters. The environment variable - GLIBCXX_DEBUG_MESSAGE_LENGTH can be used to request a - different length.

    Using a Specific Debug Container

    When it is not feasible to recompile your entire application, or - only specific containers need checking, debugging containers are - available as GNU extensions. These debugging containers are - functionally equivalent to the standard drop-in containers used in - debug mode, but they are available in a separate namespace as GNU - extensions and may be used in programs compiled with either release - mode or with debug mode. The - following table provides the names and headers of the debugging - containers: -

    Table 30.1. Debugging Containers

    ContainerHeaderDebug containerDebug header
    std::bitsetbitset__gnu_debug::bitsetbitset
    std::dequedeque__gnu_debug::dequedeque
    std::listlist__gnu_debug::listlist
    std::mapmap__gnu_debug::mapmap
    std::multimapmap__gnu_debug::multimapmap
    std::multisetset__gnu_debug::multisetset
    std::setset__gnu_debug::setset
    std::stringstring__gnu_debug::stringstring
    std::wstringstring__gnu_debug::wstringstring
    std::basic_stringstring__gnu_debug::basic_stringstring
    std::vectorvector__gnu_debug::vectorvector

    In addition, when compiling in C++0x mode, these additional -containers have additional debug capability. -

    Table 30.2. Debugging Containers C++0x

    ContainerHeaderDebug containerDebug header
    std::unordered_mapunordered_map__gnu_debug::unordered_mapunordered_map
    std::unordered_multimapunordered_map__gnu_debug::unordered_multimapunordered_map
    std::unordered_setunordered_set__gnu_debug::unordered_setunordered_set
    std::unordered_multisetunordered_set__gnu_debug::unordered_multisetunordered_set

    Prev Up Next
    Semantics Home Design
    diff --git a/libstdc++-v3/doc/html/manual/bugs.html b/libstdc++-v3/doc/html/manual/bugs.html index 20da4a8fbf4..88ec80cabb2 100644 --- a/libstdc++-v3/doc/html/manual/bugs.html +++ b/libstdc++-v3/doc/html/manual/bugs.html @@ -36,317 +36,317 @@ of style. Note that we usually do not make changes to the code until an issue has reached DR status.

    5: - string::compare specification questionable + string::compare specification questionable

    This should be two overloaded functions rather than a single function.

    17: - Bad bool parsing + Bad bool parsing

    Apparently extracting Boolean values was messed up...

    19: - "Noconv" definition too vague + "Noconv" definition too vague

    If codecvt::do_in returns noconv there are - no changes to the values in [to, to_limit). + no changes to the values in [to, to_limit).

    22: - Member open vs flags + Member open vs flags

    Re-opening a file stream does not clear the state flags.

    23: - Num_get overflow result + Num_get overflow result

    Implement the proposed resolution.

    25: - String operator<< uses width() value wrong + String operator<< uses width() value wrong

    Padding issues.

    48: - Use of non-existent exception constructor + Use of non-existent exception constructor

    An instance of ios_base::failure is constructed instead.

    49: - Underspecification of ios_base::sync_with_stdio + Underspecification of ios_base::sync_with_stdio

    The return type is the previous state of synchronization.

    50: - Copy constructor and assignment operator of ios_base + Copy constructor and assignment operator of ios_base

    These members functions are declared private and are - thus inaccessible. Specifying the correct semantics of - "copying stream state" was deemed too complicated. + thus inaccessible. Specifying the correct semantics of + "copying stream state" was deemed too complicated.

    60: - What is a formatted input function? + What is a formatted input function?

    This DR made many widespread changes to basic_istream - and basic_ostream all of which have been implemented. + and basic_ostream all of which have been implemented.

    63: - Exception-handling policy for unformatted output + Exception-handling policy for unformatted output

    Make the policy consistent with that of formatted input, unformatted - input, and formatted output. + input, and formatted output.

    68: - Extractors for char* should store null at end + Extractors for char* should store null at end

    And they do now. An editing glitch in the last item in the list of - [27.6.1.2.3]/7. + [27.6.1.2.3]/7.

    74: - Garbled text for codecvt::do_max_length + Garbled text for codecvt::do_max_length

    The text of the standard was gibberish. Typos gone rampant.

    75: - Contradiction in codecvt::length's argument types + Contradiction in codecvt::length's argument types

    Change the first parameter to stateT& and implement - the new effects paragraph. + the new effects paragraph.

    83: - string::npos vs. string::max_size() + string::npos vs. string::max_size()

    Safety checks on the size of the string should test against - max_size() rather than npos. + max_size() rather than npos.

    90: - Incorrect description of operator>> for strings + Incorrect description of operator>> for strings

    The effect contain isspace(c,getloc()) which must be - replaced by isspace(c,is.getloc()). + replaced by isspace(c,is.getloc()).

    91: - Description of operator>> and getline() for string<> + Description of operator>> and getline() for string<> might cause endless loop

    They behave as a formatted input function and as an unformatted - input function, respectively (except that getline is + input function, respectively (except that getline is not required to set gcount).

    103: - set::iterator is required to be modifiable, but this allows + set::iterator is required to be modifiable, but this allows modification of keys.

    For associative containers where the value type is the same as - the key type, both iterator and const_iterator + the key type, both iterator and const_iterator are constant iterators.

    109: - Missing binders for non-const sequence elements + Missing binders for non-const sequence elements

    The binder1st and binder2nd didn't have an - operator() taking a non-const parameter. + operator() taking a non-const parameter.

    110: - istreambuf_iterator::equal not const + istreambuf_iterator::equal not const

    This was not a const member function. Note that the DR says to - replace the function with a const one; we have instead provided an - overloaded version with identical contents. + replace the function with a const one; we have instead provided an + overloaded version with identical contents.

    117: - basic_ostream uses nonexistent num_put member functions + basic_ostream uses nonexistent num_put member functions

    num_put::put() was overloaded on the wrong types.

    118: - basic_istream uses nonexistent num_get member functions + basic_istream uses nonexistent num_get member functions

    Same as 117, but for num_get::get().

    129: - Need error indication from seekp() and seekg() + Need error indication from seekp() and seekg()

    These functions set failbit on error now.

    130: - Return type of container::erase(iterator) differs for associative containers -

    Make member erase return iterator for set, multiset, map, multimap. + Return type of container::erase(iterator) differs for associative containers +

    Make member erase return iterator for set, multiset, map, multimap.

    136: - seekp, seekg setting wrong streams? + seekp, seekg setting wrong streams?

    seekp should only set the output stream, and - seekg should only set the input stream. + seekg should only set the input stream.

    167: - Improper use of traits_type::length() + Improper use of traits_type::length()

    op<< with a const char* was - calculating an incorrect number of characters to write. + calculating an incorrect number of characters to write.

    169: - Bad efficiency of overflow() mandated + Bad efficiency of overflow() mandated

    Grow efficiently the internal array object.

    171: - Strange seekpos() semantics due to joint position + Strange seekpos() semantics due to joint position

    Quite complex to summarize...

    181: - make_pair() unintended behavior + make_pair() unintended behavior

    This function used to take its arguments as reference-to-const, now - it copies them (pass by value). + it copies them (pass by value).

    195: - Should basic_istream::sentry's constructor ever set eofbit? + Should basic_istream::sentry's constructor ever set eofbit?

    Yes, it can, specifically if EOF is reached while skipping whitespace.

    211: - operator>>(istream&, string&) doesn't set failbit + operator>>(istream&, string&) doesn't set failbit

    If nothing is extracted into the string, op>> now - sets failbit (which can cause an exception, etc., etc.). + sets failbit (which can cause an exception, etc., etc.).

    214: - set::find() missing const overload + set::find() missing const overload

    Both set and multiset were missing - overloaded find, lower_bound, upper_bound, and equal_range functions - for const instances. + overloaded find, lower_bound, upper_bound, and equal_range functions + for const instances.

    231: - Precision in iostream? + Precision in iostream?

    For conversion from a floating-point type, str.precision() - is specified in the conversion specification. + is specified in the conversion specification.

    233: - Insertion hints in associative containers + Insertion hints in associative containers

    Implement N1780, first check before then check after, insert as close - to hint as possible. + to hint as possible.

    235: - No specification of default ctor for reverse_iterator + No specification of default ctor for reverse_iterator

    The declaration of reverse_iterator lists a default constructor. - However, no specification is given what this constructor should do. + However, no specification is given what this constructor should do.

    241: - Does unique_copy() require CopyConstructible and Assignable? + Does unique_copy() require CopyConstructible and Assignable?

    Add a helper for forward_iterator/output_iterator, fix the existing - one for input_iterator/output_iterator to not rely on Assignability. + one for input_iterator/output_iterator to not rely on Assignability.

    243: - get and getline when sentry reports failure + get and getline when sentry reports failure

    Store a null character only if the character array has a non-zero size.

    251: - basic_stringbuf missing allocator_type + basic_stringbuf missing allocator_type

    This nested typedef was originally not specified.

    253: - valarray helper functions are almost entirely useless + valarray helper functions are almost entirely useless

    Make the copy constructor and copy-assignment operator declarations - public in gslice_array, indirect_array, mask_array, slice_array; provide + public in gslice_array, indirect_array, mask_array, slice_array; provide definitions.

    265: - std::pair::pair() effects overly restrictive + std::pair::pair() effects overly restrictive

    The default ctor would build its members from copies of temporaries; - now it simply uses their respective default ctors. + now it simply uses their respective default ctors.

    266: - bad_exception::~bad_exception() missing Effects clause + bad_exception::~bad_exception() missing Effects clause

    The bad_* classes no longer have destructors (they - are trivial), since no description of them was ever given. + are trivial), since no description of them was ever given.

    271: - basic_iostream missing typedefs + basic_iostream missing typedefs

    The typedefs it inherits from its base classes can't be used, since - (for example) basic_iostream<T>::traits_type is ambiguous. + (for example) basic_iostream<T>::traits_type is ambiguous.

    275: - Wrong type in num_get::get() overloads + Wrong type in num_get::get() overloads

    Similar to 118.

    280: - Comparison of reverse_iterator to const reverse_iterator + Comparison of reverse_iterator to const reverse_iterator

    Add global functions with two template parameters. - (NB: not added for now a templated assignment operator) + (NB: not added for now a templated assignment operator)

    292: - Effects of a.copyfmt (a) + Effects of a.copyfmt (a)

    If (this == &rhs) do nothing.

    300: - List::merge() specification incomplete + List::merge() specification incomplete

    If (this == &x) do nothing.

    303: - Bitset input operator underspecified -

    Basically, compare the input character to - is.widen(0) and is.widen(1). + Bitset input operator underspecified +

    Basically, compare the input character to + is.widen(0) and is.widen(1).

    305: - Default behavior of codecvt<wchar_t, char, - mbstate_t>::length() -

    Do not specify what codecvt<wchar_t, char, - mbstate_t>::do_length must return. + Default behavior of codecvt<wchar_t, char, + mbstate_t>::length() +

    Do not specify what codecvt<wchar_t, char, + mbstate_t>::do_length must return.

    328: - Bad sprintf format modifier in - money_put<>::do_put() + Bad sprintf format modifier in + money_put<>::do_put()

    Change the format string to "%.0Lf".

    365: - Lack of const-qualification in clause 27 + Lack of const-qualification in clause 27

    Add const overloads of is_open.

    387: - std::complex over-encapsulated + std::complex over-encapsulated

    Add the real(T) and imag(T) - members; in C++0x mode, also adjust the existing - real() and imag() members and - free functions. + members; in C++0x mode, also adjust the existing + real() and imag() members and + free functions.

    389: - Const overload of valarray::operator[] returns - by value + Const overload of valarray::operator[] returns + by value

    Change it to return a const T&.

    396: - what are characters zero and one + what are characters zero and one

    Implement the proposed resolution.

    402: - Wrong new expression in [some_]allocator::construct + Wrong new expression in [some_]allocator::construct

    Replace "new" with "::new".

    408: - - Is vector<reverse_iterator<char*> > forbidden? - + + Is vector<reverse_iterator<char*> > forbidden? +

    Tweak the debug-mode checks in _Safe_iterator.

    409: - Closing an fstream should clear the error state + Closing an fstream should clear the error state

    Have open clear the error flags.

    431: - Swapping containers with unequal allocators + Swapping containers with unequal allocators

    Implement Option 3, as per N1599.

    432: - stringbuf::overflow() makes only one write position + stringbuf::overflow() makes only one write position available

    Implement the resolution, beyond DR 169.

    434: - bitset::to_string() hard to use + bitset::to_string() hard to use

    Add three overloads, taking fewer template arguments.

    438: - Ambiguity in the "do the right thing" clause + Ambiguity in the "do the right thing" clause

    Implement the resolution, basically cast less.

    453: - basic_stringbuf::seekoff need not always fail for an empty stream + basic_stringbuf::seekoff need not always fail for an empty stream

    Don't fail if the next pointer is null and newoff is zero.

    455: - cerr::tie() and wcerr::tie() are overspecified + cerr::tie() and wcerr::tie() are overspecified

    Initialize cerr tied to cout and wcerr tied to wcout.

    464: - Suggestion for new member functions in standard containers + Suggestion for new member functions in standard containers

    Add data() to std::vector and - at(const key_type&) to std::map. + at(const key_type&) to std::map.

    508: - Bad parameters for ranlux64_base_01 + Bad parameters for ranlux64_base_01

    Fix the parameters.

    512: - Seeding subtract_with_carry_01 from a single unsigned long + Seeding subtract_with_carry_01 from a single unsigned long

    Construct a linear_congruential engine and seed with it.

    526: - Is it undefined if a function in the standard changes in + Is it undefined if a function in the standard changes in parameters?

    Use &value.

    538: - 241 again: Does unique_copy() require CopyConstructible + 241 again: Does unique_copy() require CopyConstructible and Assignable?

    In case of input_iterator/output_iterator rely on Assignability of - input_iterator' value_type. + input_iterator' value_type.

    539: - partial_sum and adjacent_difference should mention - requirements + partial_sum and adjacent_difference should mention + requirements

    We were almost doing the right thing, just use std::move - in adjacent_difference. + in adjacent_difference.

    541: - shared_ptr template assignment and void + shared_ptr template assignment and void

    Add an auto_ptr<void> specialization.

    543: - valarray slice default constructor + valarray slice default constructor

    Follow the straightforward proposed resolution.

    550: - What should the return type of pow(float,int) be? + What should the return type of pow(float,int) be?

    In C++0x mode, remove the pow(float,int), etc., signatures.

    586: - string inserter not a formatted function + string inserter not a formatted function

    Change it to be a formatted output function (i.e. catch exceptions).

    596: - 27.8.1.3 Table 112 omits "a+" and "a+b" modes + 27.8.1.3 Table 112 omits "a+" and "a+b" modes

    Add the missing modes to fopen_mode.

    630: - arrays of valarray + arrays of valarray

    Implement the simple resolution.

    660: - Missing bitwise operations + Missing bitwise operations

    Add the missing operations.

    691: - const_local_iterator cbegin, cend missing from TR1 + const_local_iterator cbegin, cend missing from TR1

    In C++0x mode add cbegin(size_type) and cend(size_type) - to the unordered containers. + to the unordered containers.

    693: - std::bitset::all() missing + std::bitset::all() missing

    Add it, consistently with the discussion.

    695: - ctype<char>::classic_table() not accessible + ctype<char>::classic_table() not accessible

    Make the member functions table and classic_table public.

    696: - istream::operator>>(int&) broken + istream::operator>>(int&) broken

    Implement the straightforward resolution.

    761: - unordered_map needs an at() member function + unordered_map needs an at() member function

    In C++0x mode, add at() and at() const.

    775: - Tuple indexing should be unsigned? + Tuple indexing should be unsigned?

    Implement the int -> size_t replacements.

    776: - Undescribed assign function of std::array + Undescribed assign function of std::array

    In C++0x mode, remove assign, add fill.

    781: - std::complex should add missing C99 functions + std::complex should add missing C99 functions

    In C++0x mode, add std::proj.

    809: - std::swap should be overloaded for array types + std::swap should be overloaded for array types

    Add the overload.

    844: - complex pow return type is ambiguous + complex pow return type is ambiguous

    In C++0x mode, remove the pow(complex<T>, int) signature.

    853: - to_string needs updating with zero and one + to_string needs updating with zero and one

    Update / add the signatures.

    865: - More algorithms that throw away information + More algorithms that throw away information

    The traditional HP / SGI return type and value is blessed - by the resolution of the DR. + by the resolution of the DR.

    Prev Up Next
    License Home Chapter 2. Setup
    diff --git a/libstdc++-v3/doc/html/manual/codecvt.html b/libstdc++-v3/doc/html/manual/codecvt.html deleted file mode 100644 index 1e45a2582cb..00000000000 --- a/libstdc++-v3/doc/html/manual/codecvt.html +++ /dev/null @@ -1,379 +0,0 @@ - - -codecvt
    codecvt
    Prev Chapter 15. Facets aka Categories Next

    codecvt

    -The standard class codecvt attempts to address conversions between -different character encoding schemes. In particular, the standard -attempts to detail conversions between the implementation-defined wide -characters (hereafter referred to as wchar_t) and the standard type -char that is so beloved in classic “C” (which can now be -referred to as narrow characters.) This document attempts to describe -how the GNU libstdc++ implementation deals with the conversion between -wide and narrow characters, and also presents a framework for dealing -with the huge number of other encodings that iconv can convert, -including Unicode and UTF8. Design issues and requirements are -addressed, and examples of correct usage for both the required -specializations for wide and narrow characters and the -implementation-provided extended functionality are given. -

    Requirements

    -Around page 425 of the C++ Standard, this charming heading comes into view: -

    -22.2.1.5 - Template class codecvt -

    -The text around the codecvt definition gives some clues: -

    - --1- The class codecvt<internT,externT,stateT> is for use when -converting from one codeset to another, such as from wide characters -to multibyte characters, between wide character encodings such as -Unicode and EUC. - -

    -Hmm. So, in some unspecified way, Unicode encodings and -translations between other character sets should be handled by this -class. -

    - --2- The stateT argument selects the pair of codesets being mapped between. - -

    -Ah ha! Another clue... -

    - --3- The instantiations required in the Table ?? -(lib.locale.category), namely codecvt<wchar_t,char,mbstate_t> and -codecvt<char,char,mbstate_t>, convert the implementation-defined -native character set. codecvt<char,char,mbstate_t> implements a -degenerate conversion; it does not convert at -all. codecvt<wchar_t,char,mbstate_t> converts between the native -character sets for tiny and wide characters. Instantiations on -mbstate_t perform conversion between encodings known to the library -implementor. Other encodings can be converted by specializing on a -user-defined stateT type. The stateT object can contain any state that -is useful to communicate to or from the specialized do_convert member. - -

    -At this point, a couple points become clear: -

    -One: The standard clearly implies that attempts to add non-required -(yet useful and widely used) conversions need to do so through the -third template parameter, stateT.

    -Two: The required conversions, by specifying mbstate_t as the third -template parameter, imply an implementation strategy that is mostly -(or wholly) based on the underlying C library, and the functions -mcsrtombs and wcsrtombs in particular.

    Design

    wchar_t Size

    - The simple implementation detail of wchar_t's size seems to - repeatedly confound people. Many systems use a two byte, - unsigned integral type to represent wide characters, and use an - internal encoding of Unicode or UCS2. (See AIX, Microsoft NT, - Java, others.) Other systems, use a four byte, unsigned integral - type to represent wide characters, and use an internal encoding - of UCS4. (GNU/Linux systems using glibc, in particular.) The C - programming language (and thus C++) does not specify a specific - size for the type wchar_t. -

    - Thus, portable C++ code cannot assume a byte size (or endianness) either. -

    Support for Unicode

    - Probably the most frequently asked question about code conversion - is: "So dudes, what's the deal with Unicode strings?" - The dude part is optional, but apparently the usefulness of - Unicode strings is pretty widely appreciated. Sadly, this specific - encoding (And other useful encodings like UTF8, UCS4, ISO 8859-10, - etc etc etc) are not mentioned in the C++ standard. -

    - A couple of comments: -

    - The thought that all one needs to convert between two arbitrary - codesets is two types and some kind of state argument is - unfortunate. In particular, encodings may be stateless. The naming - of the third parameter as stateT is unfortunate, as what is really - needed is some kind of generalized type that accounts for the - issues that abstract encodings will need. The minimum information - that is required includes: -

    • - Identifiers for each of the codesets involved in the - conversion. For example, using the iconv family of functions - from the Single Unix Specification (what used to be called - X/Open) hosted on the GNU/Linux operating system allows - bi-directional mapping between far more than the following - tantalizing possibilities: -

      - (An edited list taken from `iconv --list` on a - Red Hat 6.2/Intel system: - 

      -8859_1, 8859_9, 10646-1:1993, 10646-1:1993/UCS4, ARABIC, ARABIC7,
-ASCII, EUC-CN, EUC-JP, EUC-KR, EUC-TW, GREEK-CCIcode, GREEK, GREEK7-OLD,
-GREEK7, GREEK8, HEBREW, ISO-8859-1, ISO-8859-2, ISO-8859-3,
-ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8,
-ISO-8859-9, ISO-8859-10, ISO-8859-11, ISO-8859-13, ISO-8859-14,
-ISO-8859-15, ISO-10646, ISO-10646/UCS2, ISO-10646/UCS4,
-ISO-10646/UTF-8, ISO-10646/UTF8, SHIFT-JIS, SHIFT_JIS, UCS-2, UCS-4,
-UCS2, UCS4, UNICODE, UNICODEBIG, UNICODELIcodeLE, US-ASCII, US, UTF-8,
-UTF-16, UTF8, UTF16).
-

      -For iconv-based implementations, string literals for each of the -encodings (i.e. "UCS-2" and "UTF-8") are necessary, -although for other, -non-iconv implementations a table of enumerated values or some other -mechanism may be required. -

    • - Maximum length of the identifying string literal. -

    • - Some encodings require explicit endian-ness. As such, some kind - of endian marker or other byte-order marker will be necessary. See - "Footnotes for C/C++ developers" in Haible for more information on - UCS-2/Unicode endian issues. (Summary: big endian seems most likely, - however implementations, most notably Microsoft, vary.) -

    • - Types representing the conversion state, for conversions involving - the machinery in the "C" library, or the conversion descriptor, for - conversions using iconv (such as the type iconv_t.) Note that the - conversion descriptor encodes more information than a simple encoding - state type. -

    • - Conversion descriptors for both directions of encoding. (i.e., both - UCS-2 to UTF-8 and UTF-8 to UCS-2.) -

    • - Something to indicate if the conversion requested if valid. -

    • - Something to represent if the conversion descriptors are valid. -

    • - Some way to enforce strict type checking on the internal and - external types. As part of this, the size of the internal and - external types will need to be known. -

    Other Issues

    -In addition, multi-threaded and multi-locale environments also impact -the design and requirements for code conversions. In particular, they -affect the required specialization codecvt<wchar_t, char, mbstate_t> -when implemented using standard "C" functions. -

    -Three problems arise, one big, one of medium importance, and one small. -

    -First, the small: mcsrtombs and wcsrtombs may not be multithread-safe -on all systems required by the GNU tools. For GNU/Linux and glibc, -this is not an issue. -

    -Of medium concern, in the grand scope of things, is that the functions -used to implement this specialization work on null-terminated -strings. Buffers, especially file buffers, may not be null-terminated, -thus giving conversions that end prematurely or are otherwise -incorrect. Yikes! -

    -The last, and fundamental problem, is the assumption of a global -locale for all the "C" functions referenced above. For something like -C++ iostreams (where codecvt is explicitly used) the notion of -multiple locales is fundamental. In practice, most users may not run -into this limitation. However, as a quality of implementation issue, -the GNU C++ library would like to offer a solution that allows -multiple locales and or simultaneous usage with computationally -correct results. In short, libstdc++ is trying to offer, as an -option, a high-quality implementation, damn the additional complexity! -

    -For the required specialization codecvt<wchar_t, char, mbstate_t> , -conversions are made between the internal character set (always UCS4 -on GNU/Linux) and whatever the currently selected locale for the -LC_CTYPE category implements. -

    Implementation

    -The two required specializations are implemented as follows: -

    - -codecvt<char, char, mbstate_t> - -

    -This is a degenerate (i.e., does nothing) specialization. Implementing -this was a piece of cake. -

    - -codecvt<char, wchar_t, mbstate_t> - -

    -This specialization, by specifying all the template parameters, pretty -much ties the hands of implementors. As such, the implementation is -straightforward, involving mcsrtombs for the conversions between char -to wchar_t and wcsrtombs for conversions between wchar_t and char. -

    -Neither of these two required specializations deals with Unicode -characters. As such, libstdc++ implements a partial specialization -of the codecvt class with and iconv wrapper class, encoding_state as the -third template parameter. -

    -This implementation should be standards conformant. First of all, the -standard explicitly points out that instantiations on the third -template parameter, stateT, are the proper way to implement -non-required conversions. Second of all, the standard says (in Chapter -17) that partial specializations of required classes are a-ok. Third -of all, the requirements for the stateT type elsewhere in the standard -(see 21.1.2 traits typedefs) only indicate that this type be copy -constructible. -

    -As such, the type encoding_state is defined as a non-templatized, POD -type to be used as the third type of a codecvt instantiation. This -type is just a wrapper class for iconv, and provides an easy interface -to iconv functionality. -

    -There are two constructors for encoding_state: -

    - -encoding_state() : __in_desc(0), __out_desc(0) - -

    -This default constructor sets the internal encoding to some default -(currently UCS4) and the external encoding to whatever is returned by -nl_langinfo(CODESET). -

    - -encoding_state(const char* __int, const char* __ext) - -

    -This constructor takes as parameters string literals that indicate the -desired internal and external encoding. There are no defaults for -either argument. -

    -One of the issues with iconv is that the string literals identifying -conversions are not standardized. Because of this, the thought of -mandating and or enforcing some set of pre-determined valid -identifiers seems iffy: thus, a more practical (and non-migraine -inducing) strategy was implemented: end-users can specify any string -(subject to a pre-determined length qualifier, currently 32 bytes) for -encodings. It is up to the user to make sure that these strings are -valid on the target system. -

    - -void -_M_init() - -

    -Strangely enough, this member function attempts to open conversion -descriptors for a given encoding_state object. If the conversion -descriptors are not valid, the conversion descriptors returned will -not be valid and the resulting calls to the codecvt conversion -functions will return error. -

    - -bool -_M_good() - -

    -Provides a way to see if the given encoding_state object has been -properly initialized. If the string literals describing the desired -internal and external encoding are not valid, initialization will -fail, and this will return false. If the internal and external -encodings are valid, but iconv_open could not allocate conversion -descriptors, this will also return false. Otherwise, the object is -ready to convert and will return true. -

    - -encoding_state(const encoding_state&) - -

    -As iconv allocates memory and sets up conversion descriptors, the copy -constructor can only copy the member data pertaining to the internal -and external code conversions, and not the conversion descriptors -themselves. -

    -Definitions for all the required codecvt member functions are provided -for this specialization, and usage of codecvt<internal character type, -external character type, encoding_state> is consistent with other -codecvt usage. -

    Use

    A conversions involving string literal.

    -  typedef codecvt_base::result                  result;
-  typedef unsigned short                        unicode_t;
-  typedef unicode_t                             int_type;
-  typedef char                                  ext_type;
-  typedef encoding_state                          state_type;
-  typedef codecvt<int_type, ext_type, state_type> unicode_codecvt;
-
-  const ext_type*       e_lit = "black pearl jasmine tea";
-  int                   size = strlen(e_lit);
-  int_type              i_lit_base[24] = 
-  { 25088, 27648, 24832, 25344, 27392, 8192, 28672, 25856, 24832, 29184, 
-    27648, 8192, 27136, 24832, 29440, 27904, 26880, 28160, 25856, 8192, 29696,
-    25856, 24832, 2560
-  };
-  const int_type*       i_lit = i_lit_base;
-  const ext_type*       efrom_next;
-  const int_type*       ifrom_next;
-  ext_type*             e_arr = new ext_type[size + 1];
-  ext_type*             eto_next;
-  int_type*             i_arr = new int_type[size + 1];
-  int_type*             ito_next;
-
-  // construct a locale object with the specialized facet.
-  locale                loc(locale::classic(), new unicode_codecvt);
-  // sanity check the constructed locale has the specialized facet.
-  VERIFY( has_facet<unicode_codecvt>(loc) );
-  const unicode_codecvt& cvt = use_facet<unicode_codecvt>(loc); 
-  // convert between const char* and unicode strings
-  unicode_codecvt::state_type state01("UNICODE", "ISO_8859-1");
-  initialize_state(state01);
-  result r1 = cvt.in(state01, e_lit, e_lit + size, efrom_next, 
-                     i_arr, i_arr + size, ito_next);
-  VERIFY( r1 == codecvt_base::ok );
-  VERIFY( !int_traits::compare(i_arr, i_lit, size) ); 
-  VERIFY( efrom_next == e_lit + size );
-  VERIFY( ito_next == i_arr + size );
-

    Future

    • - a. things that are sketchy, or remain unimplemented: - do_encoding, max_length and length member functions - are only weakly implemented. I have no idea how to do - this correctly, and in a generic manner. Nathan? -

    • - b. conversions involving std::string -

      • - how should operators != and == work for string of - different/same encoding? -

      • - what is equal? A byte by byte comparison or an - encoding then byte comparison? -

      • - conversions between narrow, wide, and unicode strings -

    • - c. conversions involving std::filebuf and std::ostream -

      • - how to initialize the state object in a - standards-conformant manner? -

      • - how to synchronize the "C" and "C++" - conversion information? -

      • - wchar_t/char internal buffers and conversions between - internal/external buffers? -

    Bibliography

    - The GNU C Library - . Roland McGrath. Ulrich Drepper. Copyright © 2007 FSF. Chapters 6 Character Set Handling and 7 Locales and Internationalization.

    - Correspondence - . Ulrich Drepper. Copyright © 2002 .

    - ISO/IEC 14882:1998 Programming languages - C++ - . Copyright © 1998 ISO.

    - ISO/IEC 9899:1999 Programming languages - C - . Copyright © 1999 ISO.

    - The Open Group Base Specifications, Issue 6 (IEEE Std. 1003.1-2004) - . Copyright © 1999 - The Open Group/The Institute of Electrical and Electronics Engineers, Inc.. - - - .

    - The C++ Programming Language, Special Edition - . Bjarne Stroustrup. Copyright © 2000 Addison Wesley, Inc.. Appendix D. - Addison Wesley - .

    - Standard C++ IOStreams and Locales - . - Advanced Programmer's Guide and Reference - . Angelika Langer. Klaus Kreft. Copyright © 2000 Addison Wesley Longman, Inc.. - Addison Wesley Longman - .

    - A brief description of Normative Addendum 1 - . Clive Feather. Extended Character Sets. - - - .

    - The Unicode HOWTO - . Bruno Haible. - - - .

    - UTF-8 and Unicode FAQ for Unix/Linux - . Markus Khun. - - - .

    Prev Up Next
    Chapter 15. Facets aka Categories Home messages
    diff --git a/libstdc++-v3/doc/html/manual/complex.html b/libstdc++-v3/doc/html/manual/complex.html deleted file mode 100644 index cb82e609eab..00000000000 --- a/libstdc++-v3/doc/html/manual/complex.html +++ /dev/null @@ -1,25 +0,0 @@ - - -Chapter 21. Complex
    Chapter 21. Complex
    Prev Part X.  - Numerics - - Next

    Chapter 21. Complex

    Table of Contents

    complex Processing

    -

    complex Processing

    -

    Using complex<> becomes even more comple- er, sorry, - complicated, with the not-quite-gratuitously-incompatible - addition of complex types to the C language. David Tribble has - compiled a list of C++98 and C99 conflict points; his description of - C's new type versus those of C++ and how to get them playing together - nicely is -here. -

    complex<> is intended to be instantiated with a - floating-point type. As long as you meet that and some other basic - requirements, then the resulting instantiation has all of the usual - math operators defined, as well as definitions of op<< - and op>> that work with iostreams: op<< - prints (u,v) and op>> can read u, - (u), and (u,v). -

    Prev Up Next
    Part X.  - Numerics - - Home Chapter 22. Generalized Operations
    diff --git a/libstdc++-v3/doc/html/manual/concurrency.html b/libstdc++-v3/doc/html/manual/concurrency.html new file mode 100644 index 00000000000..86de72e9c04 --- /dev/null +++ b/libstdc++-v3/doc/html/manual/concurrency.html @@ -0,0 +1,42 @@ + + +Chapter 15.  Concurrency
    Chapter 15.  + Concurrency + +
    Prev Part II.  + Standard Contents + Next

    Chapter 15.  + Concurrency + +

    Table of Contents

    API Reference

    + Facilities for concurrent operation, and control thereof. +

    API Reference

    + All items are declared in one of four standard header files. +

    + In header mutex, class + template mutex and variants, + class once_flag, and class + template unique_lock. +

    + In header condition_variable, + classes condition_variable + and condition_variable_any. +

    + In header thread, + class thread and + namespace this_thread. +

    + In header future, class + template future and class + template shared_future, class + template promise, + and packaged_task. +

    + Full API details. +

    Prev Up Next
    Chapter 14.  + Atomics + + Home Part III.  + Extensions + +
    diff --git a/libstdc++-v3/doc/html/manual/configure.html b/libstdc++-v3/doc/html/manual/configure.html index c5ee8c3b546..47f58f47f89 100644 --- a/libstdc++-v3/doc/html/manual/configure.html +++ b/libstdc++-v3/doc/html/manual/configure.html @@ -19,43 +19,43 @@ available for a given set of libstdc++ sources is to go to the source directory and then type:./configure --help.

    --enable-multilib[default]

    This is part of the generic multilib support for building cross - compilers. As such, targets like "powerpc-elf" will have - libstdc++ built many different ways: "-msoft-float" - and not, etc. A different libstdc++ will be built for each of - the different multilib versions. This option is on by default. + compilers. As such, targets like "powerpc-elf" will have + libstdc++ built many different ways: "-msoft-float" + and not, etc. A different libstdc++ will be built for each of + the different multilib versions. This option is on by default.

    --enable-sjlj-exceptions

    Forces old, set-jump/long-jump exception handling model. If - at all possible, the new, frame unwinding exception handling routines - should be used instead, as they significantly reduce both - runtime memory usage and executable size. This option can - change the library ABI. + at all possible, the new, frame unwinding exception handling routines + should be used instead, as they significantly reduce both + runtime memory usage and executable size. This option can + change the library ABI.

    --enable-version-specific-runtime-libs

    Specify that run-time libraries should be installed in the - compiler-specific subdirectory (i.e., - ${libdir}/gcc-lib/${target_alias}/${gcc_version}) - instead of ${libdir}. This option is useful if you - intend to use several versions of gcc in parallel. In addition, - libstdc++'s include files will be installed in - ${libdir}/gcc-lib/${target_alias}/${gcc_version}/include/g++, - unless you also specify + compiler-specific subdirectory (i.e., + ${libdir}/gcc-lib/${target_alias}/${gcc_version}) + instead of ${libdir}. This option is useful if you + intend to use several versions of gcc in parallel. In addition, + libstdc++'s include files will be installed in + ${libdir}/gcc-lib/${target_alias}/${gcc_version}/include/g++, + unless you also specify --with-gxx-include-dir=dirname during configuration.

    --with-gxx-include-dir=<include-files dir>

    Adds support for named libstdc++ include directory. For instance, - the following puts all the libstdc++ headers into a directory - called "4.4-20090404" instead of the usual - "c++/(version)". + the following puts all the libstdc++ headers into a directory + called "4.4-20090404" instead of the usual + "c++/(version)". 

        --with-gxx-include-dir=/foo/H-x86-gcc-3-c-gxx-inc/include/4.4-20090404
    --enable-cstdio

    This is an abbreviated form of '--enable-cstdio=stdio' - (described next). + (described next).

    --enable-cstdio=OPTION

    Select a target-specific I/O package. At the moment, the only - choice is to use 'stdio', a generic "C" abstraction. - The default is 'stdio'. This option can change the library ABI. + choice is to use 'stdio', a generic "C" abstraction. + The default is 'stdio'. This option can change the library ABI.

    --enable-clocale

    This is an abbreviated form of '--enable-clocale=generic' - (described next). + (described next).

    --enable-clocale=OPTION

    Select a target-specific underlying locale package. The - choices are 'ieee_1003.1-2001' to specify an X/Open, Standard Unix - (IEEE Std. 1003.1-2001) model based on langinfo/iconv/catgets, - 'gnu' to specify a model based on functionality from the GNU C - library (langinfo/iconv/gettext) (from glibc, the GNU C - library), or 'generic' to use a generic "C" - abstraction which consists of "C" locale info. + choices are 'ieee_1003.1-2001' to specify an X/Open, Standard Unix + (IEEE Std. 1003.1-2001) model based on langinfo/iconv/catgets, + 'gnu' to specify a model based on functionality from the GNU C + library (langinfo/iconv/gettext) (from glibc, the GNU C + library), or 'generic' to use a generic "C" + abstraction which consists of "C" locale info.

    If not explicitly specified, the configure proccess tries to guess the most suitable package from the choices above. The default is 'generic'. On glibc-based systems of sufficient @@ -63,124 +63,124 @@ FR locale data), 'gnu' is automatically selected. This option can change the library ABI.

    --enable-libstdcxx-allocator

    This is an abbreviated form of - '--enable-libstdcxx-allocator=auto' (described - next). + '--enable-libstdcxx-allocator=auto' (described + next).

    --enable-libstdcxx-allocator=OPTION

    Select a target-specific underlying std::allocator. The - choices are 'new' to specify a wrapper for new, 'malloc' to - specify a wrapper for malloc, 'mt' for a fixed power of two allocator, + choices are 'new' to specify a wrapper for new, 'malloc' to + specify a wrapper for malloc, 'mt' for a fixed power of two allocator, 'pool' for the SGI pooled allocator or 'bitmap' for a bitmap allocator. - See this page for more information on allocator - extensions. This option - can change the library ABI. + See this page for more information on allocator + extensions. This option + can change the library ABI.

    --enable-cheaders=OPTION

    This allows the user to define the approach taken for C header - compatibility with C++. Options are c, c_std, and c_global. - These correspond to the source directory's include/c, - include/c_std, and include/c_global, and may also include - include/c_compatibility. The default is 'c_global'. + compatibility with C++. Options are c, c_std, and c_global. + These correspond to the source directory's include/c, + include/c_std, and include/c_global, and may also include + include/c_compatibility. The default is 'c_global'.

    --enable-threads

    This is an abbreviated form of '--enable-threads=yes' - (described next). + (described next).

    --enable-threads=OPTION

    Select a threading library. A full description is - given in the - general compiler - configuration instructions. This option can change the - library ABI. + given in the + general compiler + configuration instructions. This option can change the + library ABI.

    --enable-libstdcxx-debug

    Build separate debug libraries in addition to what is normally built. - By default, the debug libraries are compiled with - CXXFLAGS='-g3 -O0 -fno-inline' - , are installed in ${libdir}/debug, and have the - same names and versioning information as the non-debug - libraries. This option is off by default. + By default, the debug libraries are compiled with + CXXFLAGS='-g3 -O0 -fno-inline' + , are installed in ${libdir}/debug, and have the + same names and versioning information as the non-debug + libraries. This option is off by default.

    Note this make command, executed in - the build directory, will do much the same thing, without the - configuration difference and without building everything twice: - make CXXFLAGS='-g3 -O0 -fno-inline' all + the build directory, will do much the same thing, without the + configuration difference and without building everything twice: + make CXXFLAGS='-g3 -O0 -fno-inline' all

    --enable-libstdcxx-debug-flags=FLAGS

    This option is only valid when --enable-debug - is also specified, and applies to the debug builds only. With - this option, you can pass a specific string of flags to the - compiler to use when building the debug versions of libstdc++. - FLAGS is a quoted string of options, like + is also specified, and applies to the debug builds only. With + this option, you can pass a specific string of flags to the + compiler to use when building the debug versions of libstdc++. + FLAGS is a quoted string of options, like 

       --enable-libstdcxx-debug-flags='-g3 -O1 -fno-inline'
    --enable-cxx-flags=FLAGS

    With this option, you can pass a string of -f (functionality) - flags to the compiler to use when building libstdc++. This - option can change the library ABI. FLAGS is a quoted string of - options, like + flags to the compiler to use when building libstdc++. This + option can change the library ABI. FLAGS is a quoted string of + options, like 

       --enable-cxx-flags='-fvtable-gc -fomit-frame-pointer -ansi'

    - Note that the flags don't necessarily have to all be -f flags, - as shown, but usually those are the ones that will make sense - for experimentation and configure-time overriding. + Note that the flags don't necessarily have to all be -f flags, + as shown, but usually those are the ones that will make sense + for experimentation and configure-time overriding.

    The advantage of --enable-cxx-flags over setting CXXFLAGS in - the 'make' environment is that, if files are automatically - rebuilt, the same flags will be used when compiling those files - as well, so that everything matches. + the 'make' environment is that, if files are automatically + rebuilt, the same flags will be used when compiling those files + as well, so that everything matches.

    Fun flags to try might include combinations of 

       -fstrict-aliasing
   -fno-exceptions
   -ffunction-sections
   -fvtable-gc

    and opposite forms (-fno-) of the same. Tell us (the libstdc++ - mailing list) if you discover more! + mailing list) if you discover more!

    --enable-c99

    The "long long" type was introduced in C99, along - with many other functions for wide characters, and math - classification macros, etc. If enabled, all C99 functions not - specified by the C++ standard will be put into namespace - __gnu_cxx, and then all these names will - be injected into namespace std, so that C99 functions can be - used "as if" they were in the C++ standard (as they - will eventually be in some future revision of the standard, - without a doubt). By default, C99 support is on, assuming the - configure probes find all the necessary functions and bits - necessary. This option can change the library ABI. + with many other functions for wide characters, and math + classification macros, etc. If enabled, all C99 functions not + specified by the C++ standard will be put into namespace + __gnu_cxx, and then all these names will + be injected into namespace std, so that C99 functions can be + used "as if" they were in the C++ standard (as they + will eventually be in some future revision of the standard, + without a doubt). By default, C99 support is on, assuming the + configure probes find all the necessary functions and bits + necessary. This option can change the library ABI.

    --enable-wchar_t[default]

    Template specializations for the "wchar_t" type are - required for wide character conversion support. Disabling - wide character specializations may be expedient for initial - porting efforts, but builds only a subset of what is required by - ISO, and is not recommended. By default, this option is on. - This option can change the library ABI. + required for wide character conversion support. Disabling + wide character specializations may be expedient for initial + porting efforts, but builds only a subset of what is required by + ISO, and is not recommended. By default, this option is on. + This option can change the library ABI.

    --enable-long-long

    The "long long" type was introduced in C99. It is - provided as a GNU extension to C++98 in g++. This flag builds - support for "long long" into the library (specialized - templates and the like for iostreams). This option is on by default: - if enabled, users will have to either use the new-style "C" - headers by default (i.e., <cmath> not <math.h>) - or add appropriate compile-time flags to all compile lines to - allow "C" visibility of this feature (on GNU/Linux, - the flag is -D_ISOC99_SOURCE, which is added automatically via - CPLUSPLUS_CPP_SPEC's addition of _GNU_SOURCE). - This option can change the library ABI. + provided as a GNU extension to C++98 in g++. This flag builds + support for "long long" into the library (specialized + templates and the like for iostreams). This option is on by default: + if enabled, users will have to either use the new-style "C" + headers by default (i.e., <cmath> not <math.h>) + or add appropriate compile-time flags to all compile lines to + allow "C" visibility of this feature (on GNU/Linux, + the flag is -D_ISOC99_SOURCE, which is added automatically via + CPLUSPLUS_CPP_SPEC's addition of _GNU_SOURCE). + This option can change the library ABI.

    --enable-fully-dynamic-string

    This option enables a special version of basic_string avoiding - the optimization that allocates empty objects in static memory. + the optimization that allocates empty objects in static memory. Mostly useful together with shared memory allocators, see PR libstdc++/16612 for details.

    --enable-concept-checks

    This turns on additional compile-time checks for instantiated - library templates, in the form of specialized templates, - described here. They - can help users discover when they break the rules of the STL, before - their programs run. + library templates, in the form of specialized templates, + described here. They + can help users discover when they break the rules of the STL, before + their programs run.

    --enable-symvers[=style]

    In 3.1 and later, tries to turn on symbol versioning in the - shared library (if a shared library has been - requested). Values for 'style' that are currently supported - are 'gnu', 'gnu-versioned-namespace', 'darwin', and - 'darwin-export'. Both gnu- options require that a recent - version of the GNU linker be in use. Both darwin options are - equivalent. With no style given, the configure script will try - to guess correct defaults for the host system, probe to see if - additional requirements are necessary and present for - activation, and if so, will turn symbol versioning on. This - option can change the library ABI. + shared library (if a shared library has been + requested). Values for 'style' that are currently supported + are 'gnu', 'gnu-versioned-namespace', 'darwin', and + 'darwin-export'. Both gnu- options require that a recent + version of the GNU linker be in use. Both darwin options are + equivalent. With no style given, the configure script will try + to guess correct defaults for the host system, probe to see if + additional requirements are necessary and present for + activation, and if so, will turn symbol versioning on. This + option can change the library ABI.

    --enable-visibility

    In 4.2 and later, enables or disables visibility attributes. - If enabled (as by default), and the compiler seems capable of - passing the simple sanity checks thrown at it, adjusts items - in namespace std, namespace std::tr1, and namespace __gnu_cxx - so that -fvisibility options work. + If enabled (as by default), and the compiler seems capable of + passing the simple sanity checks thrown at it, adjusts items + in namespace std, namespace std::tr1, and namespace __gnu_cxx + so that -fvisibility options work.

    --enable-libstdcxx-pch

    In 3.4 and later, tries to turn on the generation of - stdc++.h.gch, a pre-compiled file including all the standard - C++ includes. If enabled (as by default), and the compiler - seems capable of passing the simple sanity checks thrown at - it, try to build stdc++.h.gch as part of the make process. - In addition, this generated file is used later on (by appending - --include bits/stdc++.h to CXXFLAGS) when running the - testsuite. + stdc++.h.gch, a pre-compiled file including all the standard + C++ includes. If enabled (as by default), and the compiler + seems capable of passing the simple sanity checks thrown at + it, try to build stdc++.h.gch as part of the make process. + In addition, this generated file is used later on (by appending + --include bits/stdc++.h to CXXFLAGS) when running the + testsuite.

    --disable-hosted-libstdcxx

    By default, a complete hosted C++ library is built. The C++ Standard also describes a @@ -188,17 +188,17 @@ minimal set of headers are provided. This option builds such an environment.

    --enable-libstdcxx-time

    This is an abbreviated form of - '--enable-libstdcxx-time=yes'(described next). + '--enable-libstdcxx-time=yes'(described next).

    --enable-libstdcxx-time=OPTION

    Enables link-type checks for the availability of the - clock_gettime clocks, used in the implementation of [time.clock], - and of the nanosleep and sched_yield functions, used in the - implementation of [thread.thread.this] of the current C++0x draft. - The choice OPTION=yes checks for the availability of the facilities - in libc and libposix4. In case of need the latter is also linked - to libstdc++ as part of the build process. OPTION=rt also searches - (and, in case, links) librt. Note that the latter is not always - desirable because, in glibc, for example, in turn it triggers the - linking of libpthread too, which activates locking, a large overhead - for single-thread programs. OPTION=no skips the tests completely. - The default is OPTION=no. + clock_gettime clocks, used in the implementation of [time.clock], + and of the nanosleep and sched_yield functions, used in the + implementation of [thread.thread.this] of the current C++0x draft. + The choice OPTION=yes checks for the availability of the facilities + in libc and libposix4. In case of need the latter is also linked + to libstdc++ as part of the build process. OPTION=rt also searches + (and, in case, links) librt. Note that the latter is not always + desirable because, in glibc, for example, in turn it triggers the + linking of libpthread too, which activates locking, a large overhead + for single-thread programs. OPTION=no skips the tests completely. + The default is OPTION=no.

    Prev Up Next
    Chapter 2. Setup Home Make
    diff --git a/libstdc++-v3/doc/html/manual/containers.html b/libstdc++-v3/doc/html/manual/containers.html index ff94f4751e5..4aceb1bbedc 100644 --- a/libstdc++-v3/doc/html/manual/containers.html +++ b/libstdc++-v3/doc/html/manual/containers.html @@ -1,9 +1,55 @@ -Part VII.  Containers
    Part VII.  +Chapter 9.  Containers
    Chapter 9.  Containers -
    Prev The GNU C++ Library Next

    Part VII.  +

    Prev Part II.  + Standard Contents + Next

    Chapter 9.  Containers - -

    Table of Contents

    16. Sequences
    list
    list::size() is O(n)
    vector
    Space Overhead Management
    17. Associative
    Insertion Hints
    bitset
    Size Variable
    Type String
    18. Interacting with C
    Containers vs. Arrays
    Prev Up Next
    messages Home Chapter 16. Sequences
    + +

    Table of Contents

    Sequences
    list
    vector
    Associative
    Insertion Hints
    bitset
    Interacting with C
    Containers vs. Arrays

    Sequences

    list

    list::size() is O(n)

    + Yes it is, and that's okay. This is a decision that we preserved + when we imported SGI's STL implementation. The following is + quoted from their FAQ: +

    + The size() member function, for list and slist, takes time + proportional to the number of elements in the list. This was a + deliberate tradeoff. The only way to get a constant-time + size() for linked lists would be to maintain an extra member + variable containing the list's size. This would require taking + extra time to update that variable (it would make splice() a + linear time operation, for example), and it would also make the + list larger. Many list algorithms don't require that extra + word (algorithms that do require it might do better with + vectors than with lists), and, when it is necessary to maintain + an explicit size count, it's something that users can do + themselves. +

    + This choice is permitted by the C++ standard. The standard says + that size() “should” be constant time, and + “should” does not mean the same thing as + “shall”. This is the officially recommended ISO + wording for saying that an implementation is supposed to do + something unless there is a good reason not to. +

    + One implication of linear time size(): you should never write + 

    +	 if (L.size() == 0)
+	     ...
+

    + Instead, you should write + 

    +	 if (L.empty())
+	     ...
+

    vector

    +

    Space Overhead Management

    + In this + message to the list, Daniel Kostecky announced work on an + alternate form of std::vector that would support + hints on the number of elements to be over-allocated. The design + was also described, along with possible implementation choices. +

    + The first two alpha releases were announced here + and here. +

    Prev Up Next
    Facets Home Associative
    diff --git a/libstdc++-v3/doc/html/manual/containers_and_c.html b/libstdc++-v3/doc/html/manual/containers_and_c.html index 3f658590f44..4967255c4ce 100644 --- a/libstdc++-v3/doc/html/manual/containers_and_c.html +++ b/libstdc++-v3/doc/html/manual/containers_and_c.html @@ -1,9 +1,9 @@ -Chapter 18. Interacting with C
    Chapter 18. Interacting with C
    Prev Part VII.  +Interacting with C
    Interacting with C
    Prev Chapter 9.  Containers - Next

    Chapter 18. Interacting with C

    Table of Contents

    Containers vs. Arrays

    Containers vs. Arrays

    +

    		 Next

    Interacting with C

    Containers vs. Arrays

    You're writing some code and can't decide whether to use builtin arrays or some kind of container. There are compelling reasons to use one of the container classes, but you're afraid that @@ -18,7 +18,7 @@ container classes, these are iterators (usually begin() and end(), but not always). For builtin arrays, these are the address of the first element - and the past-the-end element. + and the past-the-end element.

    Some very simple wrapper functions can hide all of that from the rest of the code. For example, a pair of functions called @@ -48,27 +48,27 @@ template<typename T> { return v.begin(); } template<typename T, unsigned int sz> - inline T* + inline T* beginof(T (&array)[sz]) { return array; } // endof template<typename T> - inline typename vector<T>::iterator + inline typename vector<T>::iterator endof(vector<T> &v) { return v.end(); } template<typename T, unsigned int sz> - inline T* + inline T* endof(T (&array)[sz]) { return array + sz; } // lengthof template<typename T> - inline typename vector<T>::size_type + inline typename vector<T>::size_type lengthof(vector<T> &v) { return v.size(); } template<typename T, unsigned int sz> - inline unsigned int + inline unsigned int lengthof(T (&)[sz]) { return sz; }

    Astute readers will notice two things at once: first, that the @@ -81,10 +81,10 @@ template<typename T, unsigned int sz>

    Second, the line 

    -    inline unsigned int lengthof (T (&)[sz]) { return sz; } 
+    inline unsigned int lengthof (T (&)[sz]) { return sz; }

    looks just weird! Hint: unused parameters can be left nameless. -

    Prev Up Next
    bitset Home Part VIII.  +

    Prev Up Next
    Associative Home Chapter 10.  Iterators
    diff --git a/libstdc++-v3/doc/html/manual/debug.html b/libstdc++-v3/doc/html/manual/debug.html index e05fb66b802..9a16afd14d2 100644 --- a/libstdc++-v3/doc/html/manual/debug.html +++ b/libstdc++-v3/doc/html/manual/debug.html @@ -1,10 +1,10 @@ -Debugging Support
    Debugging Support
    Prev Chapter 3. Using Next

    Debugging Support

    +Debugging Support

    Debugging Support
    Prev Chapter 3. Using Next

    Debugging Support

    There are numerous things that can be done to improve the ease with which C++ binaries are debugged when using the GNU tool chain. Here are some of them. -

    Using g++

    +

    Using g++

    Compiler flags determine how debug information is transmitted between compilation and debug or analysis tools.

    @@ -46,13 +46,13 @@ separate directory tree, in (prefix)/lib/debug. For more information, look at the configuration section.

    - A second approach is to use the configuration flags + A second approach is to use the configuration flags 

          make CXXFLAGS='-g3 -fno-inline -O0' all

    This quick and dirty approach is often sufficient for quick debugging tasks, when you cannot or don't want to recompile your - application to use the debug mode.

    Memory Leak Hunting

    + application to use the debug mode.

    Memory Leak Hunting

    There are various third party memory tracing and debug utilities that can be used to provide detailed memory allocation information about C++ code. An exhaustive list of tools is not going to be @@ -111,17 +111,17 @@ int main() { extern void* __dso_handle __attribute__ ((__weak__)); - __cxa_atexit((void (*) (void *)) __libc_freeres, NULL, - &__dso_handle ? __dso_handle : NULL); + __cxa_atexit((void (*) (void *)) __libc_freeres, NULL, + &__dso_handle ? __dso_handle : NULL); do_test(); return 0; }

    Suggested valgrind flags, given the suggestions above about setting up the runtime environment, library, and test file, might be: -

     
+
        valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out
-

    Using gdb

    +

    Using gdb

    Many options are available for gdb itself: please see "GDB features for C++" in the gdb documentation. Also @@ -145,7 +145,7 @@ To enable these printers, check-out the latest printers to a local directory: 

    -  svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python 
+  svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python

    Next, add the following section to your ~/.gdbinit The path must match the location where the Python module above was checked-out. @@ -175,18 +175,17 @@ "GDB: The GNU Project Debugger" .

    Tracking uncaught exceptions

    - The verbose + The verbose termination handler gives information about uncaught exceptions which are killing the program. It is described in the linked-to page. -

    Debug Mode

    The Debug Mode +

    Debug Mode

    The Debug Mode has compile and run-time checks for many containers. -

    Compile Time Checking

    The Compile-Time +

    Compile Time Checking

    The Compile-Time Checks Extension has compile-time checks for many algorithms. -

    Profile-based Performance Analysis

    The Profile-based - Performance Analysis Extension has performance checks for many +

    Profile-based Performance Analysis

    The Profile-based + Performance Analysis Extension has performance checks for many algorithms. -

    Prev Up Next
    Exceptions Home Part II.  - Support - +

    Prev Up Next
    Exceptions Home Part II.  + Standard Contents
    diff --git a/libstdc++-v3/doc/html/manual/debug_mode.html b/libstdc++-v3/doc/html/manual/debug_mode.html index 9231ca944b7..fcaeb9c5209 100644 --- a/libstdc++-v3/doc/html/manual/debug_mode.html +++ b/libstdc++-v3/doc/html/manual/debug_mode.html @@ -1,9 +1,9 @@ -Chapter 30. Debug Mode
    Chapter 30. Debug Mode
    Prev Part XII.  +Chapter 17. Debug Mode
    Chapter 17. Debug Mode
    Prev Part III.  Extensions - Next

    Chapter 30. Debug Mode

    Table of Contents

    Intro
    Semantics
    Using
    Using the Debug Mode
    Using a Specific Debug Container
    Design
    Goals
    Methods
    Other Implementations

    Intro

    +

    		 Next

    Chapter 17. Debug Mode

    Table of Contents

    Intro
    Semantics
    Using
    Using the Debug Mode
    Using a Specific Debug Container
    Design
    Goals
    Methods
    Other Implementations

    Intro

    By default, libstdc++ is built with efficiency in mind, and therefore performs little or no error checking that is not required by the C++ standard. This means that programs that @@ -15,7 +15,7 @@ library facilities, and will report errors in the use of libstdc++ as soon as they can be detected by emitting a description of the problem to standard error and aborting the program. This debug - mode is available with GCC 3.4.0 and later versions. + mode is available with GCC 3.4.0 and later versions.

    The libstdc++ debug mode performs checking for many areas of the C++ standard, but the focus is on checking interactions among @@ -34,4 +34,4 @@ the same predicate that was passed to set_intersection; the libstdc++ debug mode will detect an error if the sequence is not sorted or was sorted by a - different predicate.

    Prev Up Next
    Chapter 29. Compile Time Checks Home Semantics
    + different predicate.

    Prev Up Next
    Chapter 16. Compile Time Checks Home Semantics
    diff --git a/libstdc++-v3/doc/html/manual/diagnostics.html b/libstdc++-v3/doc/html/manual/diagnostics.html index 746a9f4185a..d04585fbcd9 100644 --- a/libstdc++-v3/doc/html/manual/diagnostics.html +++ b/libstdc++-v3/doc/html/manual/diagnostics.html @@ -1,9 +1,43 @@ -Part III.  Diagnostics
    Part III.  +Chapter 5.  Diagnostics
    Chapter 5.  Diagnostics -
    Prev The GNU C++ Library Next

    Part III.  +

    Prev Part II.  + Standard Contents + Next

    Chapter 5.  Diagnostics - -

    Table of Contents

    7. Exceptions
    Exception Classes
    Adding Data to Exceptions
    8. Concept Checking
    Prev Up Next
    Verbose Terminate Handler Home Chapter 7. Exceptions
    + +

    Table of Contents

    Exceptions
    API Reference
    Adding Data to exception
    Concept Checking

    Exceptions

    API Reference

    + All exception objects are defined in one of the standard header + files: exception, + stdexcept, new, and + typeinfo. +

    + The base exception object is exception, + located in exception. This object has no + string member. +

    + Derived from this are several classes that may have a + string member: a full hierarchy can be + found in the source documentation. +

    + Full API details. +

    Adding Data to exception

    + The standard exception classes carry with them a single string as + data (usually describing what went wrong or where the 'throw' took + place). It's good to remember that you can add your own data to + these exceptions when extending the hierarchy: + 

    +   struct My_Exception : public std::runtime_error
+   {
+     public:
+       My_Exception (const string& whatarg)
+	   : std::runtime_error(whatarg), e(errno), id(GetDataBaseID()) { }
+       int  errno_at_time_of_throw() const { return e; }
+       DBID id_of_thing_that_threw() const { return id; }
+     protected:
+       int    e;
+       DBID   id;     // some user-defined type
+   };
+
    Prev Up Next
    Termination Home Concept Checking
    diff --git a/libstdc++-v3/doc/html/manual/documentation_style.html b/libstdc++-v3/doc/html/manual/documentation_style.html index 39c0b446a97..e32947a2626 100644 --- a/libstdc++-v3/doc/html/manual/documentation_style.html +++ b/libstdc++-v3/doc/html/manual/documentation_style.html @@ -4,25 +4,29 @@ Contributing     		 Next

    Documentation Style

    Doxygen

    Prerequisites

    - Prerequisite tools are Bash 2.x, + Prerequisite tools are Bash 2.x or higher, Doxygen, and the GNU coreutils. (GNU versions of find, xargs, and possibly sed and grep are used, just because the GNU versions make - things very easy.) + things very easy.)

    To generate the pretty pictures and hierarchy graphs, the - Graphviz - package will need to be installed. + Graphviz package + will need to be installed. For PDF + output, + pdflatex is required.

    Generating the Doxygen Files

    The following Makefile rules run Doxygen to generate HTML - docs, XML docs, and the man pages. + docs, XML docs, PDF docs, and the man pages. 

    make doc-html-doxygen

    make doc-xml-doxygen

    + 

    make doc-pdf-doxygen

    + 

    make doc-man-doxygen

    Careful observers will see that the Makefile rules simply call @@ -64,7 +68,7 @@ ...not the Qt style. The intermediate *'s are preferred.

  • Use the triple-slash style only for one-line comments (the - “brief” mode). + “brief” mode).

  • This is disgusting. Don't do this.

    • @@ -95,7 +99,7 @@    * @brief A model of a linear congruential random number generator.
       *
       * @f[
    -   *     x_{i+1}\leftarrow(ax_{i} + c) \bmod m 
    +   *     x_{i+1}\leftarrow(ax_{i} + c) \bmod m
       * @f]
       */

    @@ -104,7 +108,7 @@ writing Doxygen comments. Single and double quotes, and separators in filenames are two common trouble spots. When in doubt, consult the following table. -

    Table A.1. HTML to Doxygen markup comparison

    HTMLDoxygen
    \\\
    "\"
    '\'
    <i>@a word
    <b>@b word
    <code>@c word
    <em>@a word
    <em><em>two words or more</em>

    Docbook

    Prerequisites

    +

    Table A.1. HTML to Doxygen Markup Comparison

    HTMLDoxygen
    \\\
    "\"
    '\'
    <i>@a word
    <b>@b word
    <code>@c word
    <em>@a word
    <em><em>two words or more</em>

    Docbook

    Prerequisites

    Editing the DocBook sources requires an XML editor. Many exist: some notable options include emacs, Kate, @@ -139,33 +143,35 @@ by a vendor package like libxml2.

    For PDF output, something that transforms valid XML to PDF is - required. Possible solutions include xmlto, - Apache - FOP, or prince. Other options are - listed on the DocBook web pages. Please + required. Possible solutions include + dblatex, + xmlto, or prince. Other + options are listed on the DocBook + web pages. Please consult the list when - preparing printed manuals for current best practice and suggestions. + preparing printed manuals for current best practice and + suggestions.

    Make sure that the XML documentation and markup is valid for any change. This can be done easily, with the validation rules - in the Makefile, which is equivalent to doing: + in the Makefile, which is equivalent to doing: 

     	  
 xmllint --noout --valid xml/index.xml

    Generating the DocBook Files

    The following Makefile rules generate (in order): an HTML - version of all the documentation, a PDF version of the same, a + version of all the DocBook documentation, a PDF version of the same, a single XML document, and the result of validating the entire XML document.

    - 

    make doc-html

    + 

    make doc-html-docbook

    - 

    make doc-pdf

    + 

    make doc-pdf-docbook

    - 

    make doc-xml-single

    + 

    make doc-xml-single-docbook

    - 

    make doc-xml-validate

    + 

    make doc-xml-validate-docbook

    File Organization and Basics


          Which files are important

    @@ -173,11 +179,11 @@ xmllint --noout --valid xml/index.xml       libstdc++-v3/doc/xml

          Inside this directory, the files of importance:
    -      spine.xml   - index to documentation set
    +      spine.xml   - index to documentation set
          manual/spine.xml  - index to manual
          manual/*.xml   - individual chapters and sections of the manual
          faq.xml   - index to FAQ
    -      api.xml   - index to source level / API 
    +      api.xml   - index to source level / API

          All *.txml files are template xml files, i.e., otherwise empty files with
          the correct structure, suitable for filling in with new information.
    @@ -205,7 +211,7 @@ xmllint --noout --valid xml/index.xml       </chapter>
          </book>

    -      <book>
    +      <book>
          <part>
          <chapter>
          <section>
    @@ -222,20 +228,21 @@ xmllint --noout --valid xml/index.xml
          <chapter>
          </chapter>
    -      </part>  
    +      </part>
          </book>

          </set>
        

    Markup By Example

    -Complete details on Docbook markup can be found in the DocBook Element -Reference, online. An -incomplete reference for HTML to Docbook conversion is detailed in the -table below. -

    Table A.2. HTML to Docbook XML markup comparison

    HTMLDocbook
    <p><para>
    <pre><computeroutput>, <programlisting>, + Complete details on Docbook markup can be found in the DocBook + Element Reference, + online. + An incomplete reference for HTML to Docbook conversion is + detailed in the table below. +

    Table A.2. HTML to Docbook XML Markup Comparison

    HTMLDocbook
    <p><para>
    <pre><computeroutput>, <programlisting>, <literallayout>
    <ul><itemizedlist>
    <ol><orderedlist>
    <il><listitem>
    <dl><variablelist>
    <dt><term>
    <dd><listitem>
    <a href=""><ulink url="">
    <code><literal>, <programlisting>
    <strong><emphasis>
    <em><emphasis>
    "<quote>

    And examples of detailed markup for which there are no real HTML equivalents are listed in the table below. -

    Table A.3. Docbook XML Element Use

    ElementUse
    <structname><structname>char_traits</structname>
    <classname><classname>string</classname>
    <function> +

    Table A.3. Docbook XML Element Use

    ElementUse
    <structname><structname>char_traits</structname>
    <classname><classname>string</classname>
    <function>

    <function>clear()</function>

    <function>fs.clear()</function>

    <type><type>long long</type>
    <varname><varname>fs</varname>
    <literal> @@ -248,4 +255,13 @@ table below.

    <filename class="headerfile">ctype.h</filename>

    <filename class="directory">/home/gcc/build</filename>

    <filename class="libraryfile">libstdc++.so</filename>

    -

    Prev Up Next
    Coding Style Home Design Notes
    +

    Combines

    Generating Combines and Assemblages

    + The following Makefile rules are defaults, and are usually + aliased to variable rules. +

    + 

    make doc-html

    +

    + 

    make doc-man

    +

    + 

    make doc-pdf

    +

    Prev Up Next
    Coding Style Home Design Notes
    diff --git a/libstdc++-v3/doc/html/manual/dynamic_memory.html b/libstdc++-v3/doc/html/manual/dynamic_memory.html index e23fdf5c272..4403ae80a5a 100644 --- a/libstdc++-v3/doc/html/manual/dynamic_memory.html +++ b/libstdc++-v3/doc/html/manual/dynamic_memory.html @@ -1,9 +1,9 @@ -Chapter 5. Dynamic Memory
    Chapter 5. Dynamic Memory
    Prev Part II.  +Dynamic Memory
    Dynamic Memory
    Prev Chapter 4.  Support - Next

    Chapter 5. Dynamic Memory

    +

    		 Next

    Dynamic Memory

    There are six flavors each of new and delete, so make certain that you're using the right ones. Here are quickie descriptions of new: @@ -51,8 +51,8 @@ { delete[] safety; popup_window ("Dude, you are running low on heap memory. You - should, like, close some windows, or something. - The next time you run out, we're gonna burn!"); + should, like, close some windows, or something. + The next time you run out, we're gonna burn!"); set_new_handler (old_handler); return; } @@ -65,5 +65,8 @@ }

    bad_alloc is derived from the base exception - class defined in Chapter 19. -

    Prev Up Next
    NULL Home Chapter 6. Termination
    + class defined in Sect1 19. +

    Prev Up Next
    Chapter 4.  + Support + + Home Termination
    diff --git a/libstdc++-v3/doc/html/manual/exceptions.html b/libstdc++-v3/doc/html/manual/exceptions.html deleted file mode 100644 index 3e6b12b93e4..00000000000 --- a/libstdc++-v3/doc/html/manual/exceptions.html +++ /dev/null @@ -1,22 +0,0 @@ - - -Chapter 7. Exceptions
    Chapter 7. Exceptions
    Prev Part III.  - Diagnostics - - Next

    Chapter 7. Exceptions

    Table of Contents

    Exception Classes
    Adding Data to Exceptions

    Exception Classes

    - All exception objects are defined in one of the standard header - files: exception, - stdexcept, new, and - typeinfo. -

    - The base exception object is exception, - located in exception. This object has no - string member. -

    - Derived from this are several classes that may have a - string member: a full hierarchy can be - found in the source documentation. -

    Prev Up Next
    Part III.  - Diagnostics - - Home Adding Data to Exceptions
    diff --git a/libstdc++-v3/doc/html/manual/ext_algorithms.html b/libstdc++-v3/doc/html/manual/ext_algorithms.html index 02231d43e4d..1b42f7da28e 100644 --- a/libstdc++-v3/doc/html/manual/ext_algorithms.html +++ b/libstdc++-v3/doc/html/manual/ext_algorithms.html @@ -1,9 +1,9 @@ -Chapter 36. Algorithms
    Chapter 36. Algorithms
    Prev Part XII.  +Chapter 23. Algorithms
    Chapter 23. Algorithms
    Prev Part III.  Extensions - Next

    Chapter 36. Algorithms

    25.1.6 (count, count_if) is extended with two more versions of count +

    		 Next

    Chapter 23. Algorithms

    25.1.6 (count, count_if) is extended with two more versions of count and count_if. The standard versions return their results. The additional signatures return void, but take a final parameter by reference to which they assign their results, e.g., @@ -16,8 +16,8 @@

    25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper predicates. Look in the doxygen-generated pages for notes on these.

    • is_heap tests whether or not a range is a heap.

    • is_sorted tests whether or not a range is sorted in - nondescending order.

    25.3.8 (lexicographical_compare) is extended with + nondescending order.

    25.3.8 (lexicographical_compare) is extended with 

        lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1,
-                                 _InputIter2 first2, _InputIter2 last2)

    which does... what? -

    Prev Up Next
    Chapter 35. Utilities Home Chapter 37. Numerics
    + _InputIter2 first2, _InputIter2 last2)

    which does... what? +

    Prev Up Next
    Chapter 22. Utilities Home Chapter 24. Numerics
    diff --git a/libstdc++-v3/doc/html/manual/ext_allocators.html b/libstdc++-v3/doc/html/manual/ext_allocators.html index bbb5300fb2b..37bed0b14f7 100644 --- a/libstdc++-v3/doc/html/manual/ext_allocators.html +++ b/libstdc++-v3/doc/html/manual/ext_allocators.html @@ -1,10 +1,10 @@ -Chapter 33. Allocators
    Chapter 33. Allocators
    Prev Part XII.  +Chapter 20. Allocators
    Chapter 20. Allocators
    Prev Part III.  Extensions - Next

    Chapter 33. Allocators

    Table of Contents

    mt_allocator
    Intro
    Design Issues
    Implementation
    Single Thread Example
    Multiple Thread Example
    bitmap_allocator
    Design
    Implementation

    mt_allocator

    -

    Intro

    +

    		 Next

    Chapter 20. Allocators

    Table of Contents

    mt_allocator
    Intro
    Design Issues
    Implementation
    Single Thread Example
    Multiple Thread Example
    bitmap_allocator
    Design
    Implementation

    mt_allocator

    +

    Intro

    The mt allocator [hereinafter referred to simply as "the allocator"] is a fixed size (power of two) allocator that was initially developed specifically to suit the needs of multi threaded @@ -25,7 +25,7 @@ describing the characteristics of the memory pool, a policy class containing this pool that links instantiation types to common or individual pools, and a class inheriting from the policy class that is the actual allocator. -

    The datum describing pools characteristics is +

    The datum describing pools characteristics is 

       template<bool _Thread>
     class __pool
@@ -82,9 +82,9 @@ int main()
   tune_type t_single(16, 5120, 32, 5120, 1, 10, false);
 
   tune_type t;
-  t = allocator_type::_M_get_options();  
+  t = allocator_type::_M_get_options();
   allocator_type::_M_set_options(t_opt);
-  t = allocator_type::_M_get_options();  
+  t = allocator_type::_M_get_options();
 
   allocator_type a;
   allocator_type::pointer p1 = a.allocate(128);
@@ -111,18 +111,18 @@ The _S_initialize() function:
   allocate() to return memory directly from a new() call, and deallocate will
   only do a delete() call.
 
    
-- If the GLIBCXX_FORCE_NEW environment variable is not set, both ST and MT 
+- If the GLIBCXX_FORCE_NEW environment variable is not set, both ST and MT
   applications will:
   - Calculate the number of bins needed. A bin is a specific power of two size
-    of bytes. I.e., by default the allocator will deal with requests of up to 
-    128 bytes (or whatever the value of _S_max_bytes is when _S_init() is 
-    called). This means that there will be bins of the following sizes 
-    (in bytes): 1, 2, 4, 8, 16, 32, 64, 128. 
+    of bytes. I.e., by default the allocator will deal with requests of up to
+    128 bytes (or whatever the value of _S_max_bytes is when _S_init() is
+    called). This means that there will be bins of the following sizes
+    (in bytes): 1, 2, 4, 8, 16, 32, 64, 128.
 
-  - Create the _S_binmap array. All requests are rounded up to the next 
-    "large enough" bin. I.e., a request for 29 bytes will cause a block from 
-    the "32 byte bin" to be returned to the application. The purpose of 
-    _S_binmap is to speed up the process of finding out which bin to use. 
+  - Create the _S_binmap array. All requests are rounded up to the next
+    "large enough" bin. I.e., a request for 29 bytes will cause a block from
+    the "32 byte bin" to be returned to the application. The purpose of
+    _S_binmap is to speed up the process of finding out which bin to use.
     I.e., the value of _S_binmap[ 29 ] is initialized to 5 (bin 5 = 32 bytes).
 
    
   - Create the _S_bin array. This array consists of bin_records. There will be
@@ -130,35 +130,35 @@ The _S_initialize() function:
     earlier. I.e., if _S_max_bytes = 128 there will be 8 entries.
     Each bin_record is then initialized:
     - bin_record->first = An array of pointers to block_records. There will be
-      as many block_records pointers as there are maximum number of threads 
-      (in a ST application there is only 1 thread, in a MT application there 
+      as many block_records pointers as there are maximum number of threads
+      (in a ST application there is only 1 thread, in a MT application there
       are _S_max_threads).
       This holds the pointer to the first free block for each thread in this
       bin. I.e., if we would like to know where the first free block of size 32
       for thread number 3 is we would look this up by: _S_bin[ 5 ].first[ 3 ]
 
-    The above created block_record pointers members are now initialized to 
+    The above created block_record pointers members are now initialized to
     their initial values. I.e. _S_bin[ n ].first[ n ] = NULL;
 
    
 - Additionally a MT application will:
   - Create a list of free thread id's. The pointer to the first entry
-    is stored in _S_thread_freelist_first. The reason for this approach is 
-    that the __gthread_self() call will not return a value that corresponds to 
+    is stored in _S_thread_freelist_first. The reason for this approach is
+    that the __gthread_self() call will not return a value that corresponds to
     the maximum number of threads allowed but rather a process id number or
     something else. So what we do is that we create a list of thread_records.
     This list is _S_max_threads long and each entry holds a size_t thread_id
     which is initialized to 1, 2, 3, 4, 5 and so on up to _S_max_threads.
-    Each time a thread calls allocate() or deallocate() we call 
+    Each time a thread calls allocate() or deallocate() we call
     _S_get_thread_id() which looks at the value of _S_thread_key which is a
     thread local storage pointer. If this is NULL we know that this is a newly
     created thread and we pop the first entry from this list and saves the
-    pointer to this record in the _S_thread_key variable. The next time 
-    we will get the pointer to the thread_record back and we use the 
-    thread_record->thread_id as identification. I.e., the first thread that 
+    pointer to this record in the _S_thread_key variable. The next time
+    we will get the pointer to the thread_record back and we use the
+    thread_record->thread_id as identification. I.e., the first thread that
     calls allocate will get the first record in this list and thus be thread
     number 1 and will then find the pointer to its first free 32 byte block
     in _S_bin[ 5 ].first[ 1 ]
-    When we create the _S_thread_key we also define a destructor 
+    When we create the _S_thread_key we also define a destructor
     (_S_thread_key_destr) which means that when the thread dies, this
     thread_record is returned to the front of this list and the thread id
     can then be reused if a new thread is created.
@@ -176,7 +176,7 @@ The _S_initialize() function:
       has made 678 requests (and no deallocations...) of 32-byte blocks this
       counter will read 678.
 
-    The above created arrays are now initialized with their initial values. 
+    The above created arrays are now initialized with their initial values.
     I.e. _S_bin[ n ].free[ n ] = 0;
 
    
   - Initialize the mutex of each bin_record: The bin_record->mutex
@@ -260,39 +260,39 @@ This is the first two blocks in freelist for thread id 3 in bin 3 (8 bytes):
 +----------------+

    With this in mind we simplify things a bit for a while and say that there is -only one thread (a ST application). In this case all operations are made to +only one thread (a ST application). In this case all operations are made to what is referred to as the global pool - thread id 0 (No thread may be assigned this id since they span from 1 to _S_max_threads in a MT application).

    When the application requests memory (calling allocate()) we first look at the requested size and if this is > _S_max_bytes we call new() directly and return.

    -If the requested size is within limits we start by finding out from which +If the requested size is within limits we start by finding out from which bin we should serve this request by looking in _S_binmap.

    A quick look at _S_bin[ bin ].first[ 0 ] tells us if there are any blocks of this size on the freelist (0). If this is not NULL - fine, just remove the -block that _S_bin[ bin ].first[ 0 ] points to from the list, +block that _S_bin[ bin ].first[ 0 ] points to from the list, update _S_bin[ bin ].first[ 0 ] and return a pointer to that blocks data.

    -If the freelist is empty (the pointer is NULL) we must get memory from the +If the freelist is empty (the pointer is NULL) we must get memory from the system and build us a freelist within this memory. All requests for new memory -is made in chunks of _S_chunk_size. Knowing the size of a block_record and -the bytes that this bin stores we then calculate how many blocks we can create +is made in chunks of _S_chunk_size. Knowing the size of a block_record and +the bytes that this bin stores we then calculate how many blocks we can create within this chunk, build the list, remove the first block, update the pointer -(_S_bin[ bin ].first[ 0 ]) and return a pointer to that blocks data. +(_S_bin[ bin ].first[ 0 ]) and return a pointer to that blocks data.

    Deallocation is equally simple; the pointer is casted back to a block_record -pointer, lookup which bin to use based on the size, add the block to the front -of the global freelist and update the pointer as needed +pointer, lookup which bin to use based on the size, add the block to the front +of the global freelist and update the pointer as needed (_S_bin[ bin ].first[ 0 ]).

    The decision to add deallocated blocks to the front of the freelist was made after a set of performance measurements that showed that this is roughly 10% faster than maintaining a set of "last pointers" as well.

    Multiple Thread Example

    -In the ST example we never used the thread_id variable present in each block. -Let's start by explaining the purpose of this in a MT application. +In the ST example we never used the thread_id variable present in each block. +Let's start by explaining the purpose of this in a MT application.

    The concept of "ownership" was introduced since many MT applications allocate and deallocate memory to shared containers from different @@ -321,10 +321,10 @@ When the application requests memory (calling allocate()) we first look at the requested size and if this is >_S_max_bytes we call new() directly and return.

    -If the requested size is within limits we start by finding out from which +If the requested size is within limits we start by finding out from which bin we should serve this request by looking in _S_binmap.

    -A call to _S_get_thread_id() returns the thread id for the calling thread +A call to _S_get_thread_id() returns the thread id for the calling thread (and if no value has been set in _S_thread_key, a new id is assigned and returned).

    @@ -394,4 +394,4 @@ mutex to be locked) this operation is also made in chunks of blocks a threads freelist mentioned above). The "formula" used can probably be improved to further reduce the risk of blocks being "bounced back and forth" between freelists. -

    Prev Up Next
    Diagnostics Home bitmap_allocator
    +

    Prev Up Next
    Diagnostics Home bitmap_allocator
    diff --git a/libstdc++-v3/doc/html/manual/ext_compile_checks.html b/libstdc++-v3/doc/html/manual/ext_compile_checks.html index 104d81a9908..e99452bdb59 100644 --- a/libstdc++-v3/doc/html/manual/ext_compile_checks.html +++ b/libstdc++-v3/doc/html/manual/ext_compile_checks.html @@ -1,9 +1,9 @@ -Chapter 29. Compile Time Checks
    Chapter 29. Compile Time Checks
    Prev Part XII.  +Chapter 16. Compile Time Checks
    Chapter 16. Compile Time Checks
    Prev Part III.  Extensions - Next

    Chapter 29. Compile Time Checks

    +

    		 Next

    Chapter 16. Compile Time Checks

    Also known as concept checking.

    In 1999, SGI added concept checkers to their implementation of the STL: code which checked the template parameters of @@ -37,4 +37,4 @@ support for template parameter constraints based on concepts in the core language. This will obviate the need for the library-simulated concept checking described above. -

    Prev Up Next
     Home Chapter 30. Debug Mode
    +

    Prev Up Next
     Home Chapter 17. Debug Mode
    diff --git a/libstdc++-v3/doc/html/manual/ext_concurrency.html b/libstdc++-v3/doc/html/manual/ext_concurrency.html index 0d660c7402c..c9922a9b6bc 100644 --- a/libstdc++-v3/doc/html/manual/ext_concurrency.html +++ b/libstdc++-v3/doc/html/manual/ext_concurrency.html @@ -1,9 +1,9 @@ -Chapter 41. Concurrency
    Chapter 41. Concurrency
    Prev Part XII.  +Chapter 28. Concurrency
    Chapter 28. Concurrency
    Prev Part III.  Extensions - Next

    Chapter 41. Concurrency

    Table of Contents

    Design
    Interface to Locks and Mutexes
    Interface to Atomic Functions
    Implementation
    Using Builtin Atomic Functions
    Thread Abstraction
    Use

    Design

    Interface to Locks and Mutexes

    The file <ext/concurrence.h> contains all the higher-level +

    		 Next

    Chapter 28. Concurrency

    Table of Contents

    Design
    Interface to Locks and Mutexes
    Interface to Atomic Functions
    Implementation
    Using Builtin Atomic Functions
    Thread Abstraction
    Use

    Design

    Interface to Locks and Mutexes

    The file <ext/concurrence.h> contains all the higher-level constructs for playing with threads. In contrast to the atomics layer, the concurrence layer consists largely of types. All types are defined within namespace __gnu_cxx.

    @@ -31,7 +31,7 @@ locks it during construction of __scoped_locke and unlocks it during destruction. This is an efficient way of locking critical sections, while retaining exception-safety.

    Interface to Atomic Functions

    -Two functions and one type form the base of atomic support. +Two functions and one type form the base of atomic support.

    The type _Atomic_word is a signed integral type supporting atomic operations.

    @@ -56,7 +56,7 @@ __atomic_add_dispatch

    Adds the second argument's value to the first argument. Has no return value.

    These functions forward to one of several specialized helper -functions, depending on the circumstances. For instance, +functions, depending on the circumstances. For instance,

    __exchange_and_add_dispatch @@ -67,7 +67,7 @@ Calls through to either of:

    Multi-thread version. Inlined if compiler-generated builtin atomics can be used, otherwise resolved at link time to a non-builtin code sequence. -

  • __exchange_and_add_single +

  • __exchange_and_add_single

    Single threaded version. Inlined.

    • However, only __exchange_and_add_dispatch and __atomic_add_dispatch should be used. These functions can be used in a portable manner, regardless of the specific @@ -79,13 +79,13 @@ operations.) In addition, there are two macros

    -_GLIBCXX_READ_MEM_BARRIER +_GLIBCXX_READ_MEM_BARRIER

    -_GLIBCXX_WRITE_MEM_BARRIER +_GLIBCXX_WRITE_MEM_BARRIER

    Which expand to the appropriate write and read barrier required by the host hardware and operating system. -

    Prev Up Next
    Chapter 40. Demangling Home Implementation
    +

    Prev Up Next
    Chapter 27. Demangling Home Implementation
    diff --git a/libstdc++-v3/doc/html/manual/ext_containers.html b/libstdc++-v3/doc/html/manual/ext_containers.html index 5b767d27922..79fe759fcd9 100644 --- a/libstdc++-v3/doc/html/manual/ext_containers.html +++ b/libstdc++-v3/doc/html/manual/ext_containers.html @@ -1,9 +1,9 @@ -Chapter 34. Containers
    Chapter 34. Containers
    Prev Part XII.  +Chapter 21. Containers
    Chapter 21. Containers
    Prev Part III.  Extensions - Next

    Chapter 34. Containers

    Table of Contents

    Policy Based Data Structures
    HP/SGI
    Deprecated HP/SGI

    +

    		 Next

    Chapter 21. Containers

    Table of Contents

    Policy Based Data Structures
    HP/SGI
    Deprecated HP/SGI

    Policy Based Data Structures

    More details here. -

    Prev Up Next
    bitmap_allocator Home HP/SGI
    +

    Prev Up Next
    bitmap_allocator Home HP/SGI
    diff --git a/libstdc++-v3/doc/html/manual/ext_demangling.html b/libstdc++-v3/doc/html/manual/ext_demangling.html index 9214423d3b5..4a991d0313d 100644 --- a/libstdc++-v3/doc/html/manual/ext_demangling.html +++ b/libstdc++-v3/doc/html/manual/ext_demangling.html @@ -1,9 +1,9 @@ -Chapter 40. Demangling
    Chapter 40. Demangling
    Prev Part XII.  +Chapter 27. Demangling
    Chapter 27. Demangling
    Prev Part III.  Extensions - Next

    Chapter 40. Demangling

    +

    		 Next

    Chapter 27. Demangling

    Transforming C++ ABI identifiers (like RTTI symbols) into the original C++ source identifiers is called “demangling.” @@ -63,7 +63,7 @@ int main() 

        
       St13bad_exception       => std::bad_exception   : 0
-      3barI5emptyLi17EE       => bar<empty, 17>       : 0 
+      3barI5emptyLi17EE       => bar<empty, 17>       : 0

    The demangler interface is described in the source documentation @@ -71,4 +71,4 @@ int main() be writing C++ in order to demangle C++. (That also means we have to use crummy memory management facilities, so don't forget to free() the returned char array.) -

    Prev Up Next
    Chapter 39. Input and Output Home Chapter 41. Concurrency
    +

    Prev Up Next
    Chapter 26. Input and Output Home Chapter 28. Concurrency
    diff --git a/libstdc++-v3/doc/html/manual/ext_io.html b/libstdc++-v3/doc/html/manual/ext_io.html index 0afa23ddf96..0c67bf6a2e5 100644 --- a/libstdc++-v3/doc/html/manual/ext_io.html +++ b/libstdc++-v3/doc/html/manual/ext_io.html @@ -1,9 +1,9 @@ -Chapter 39. Input and Output
    Chapter 39. Input and Output
    Prev Part XII.  +Chapter 26. Input and Output
    Chapter 26. Input and Output
    Prev Part III.  Extensions - Next

    Chapter 39. Input and Output

    Table of Contents

    Derived filebufs

    +

    		 Next

    Chapter 26. Input and Output

    Table of Contents

    Derived filebufs

    Extensions allowing filebufs to be constructed from "C" types like FILE*s and file descriptors.

    Derived filebufs

    The v2 library included non-standard extensions to construct @@ -13,38 +13,38 @@ IOStreams is via the stdio_filebuf class (see below), but earlier releases provided slightly different mechanisms.

    • 3.0.x filebufs have another ctor with this signature: - basic_filebuf(__c_file_type*, ios_base::openmode, int_type); + basic_filebuf(__c_file_type*, ios_base::openmode, int_type); - This comes in very handy in a number of places, such as - attaching Unix sockets, pipes, and anything else which uses file - descriptors, into the IOStream buffering classes. The three - arguments are as follows: -

      • __c_file_type* F - // the __c_file_type typedef usually boils down to stdio's FILE -

      • ios_base::openmode M - // same as all the other uses of openmode -

      • int_type B - // buffer size, defaults to BUFSIZ if not specified -

      - For those wanting to use file descriptors instead of FILE*'s, I - invite you to contemplate the mysteries of C's fdopen(). + This comes in very handy in a number of places, such as + attaching Unix sockets, pipes, and anything else which uses file + descriptors, into the IOStream buffering classes. The three + arguments are as follows: +

      • __c_file_type* F + // the __c_file_type typedef usually boils down to stdio's FILE +

      • ios_base::openmode M + // same as all the other uses of openmode +

      • int_type B + // buffer size, defaults to BUFSIZ if not specified +

      + For those wanting to use file descriptors instead of FILE*'s, I + invite you to contemplate the mysteries of C's fdopen().

    • In library snapshot 3.0.95 and later, filebufs bring - back an old extension: the fd() member function. The - integer returned from this function can be used for whatever file - descriptors can be used for on your platform. Naturally, the - library cannot track what you do on your own with a file descriptor, - so if you perform any I/O directly, don't expect the library to be - aware of it. + back an old extension: the fd() member function. The + integer returned from this function can be used for whatever file + descriptors can be used for on your platform. Naturally, the + library cannot track what you do on your own with a file descriptor, + so if you perform any I/O directly, don't expect the library to be + aware of it.

    • Beginning with 3.1, the extra filebuf constructor and - the fd() function were removed from the standard - filebuf. Instead, <ext/stdio_filebuf.h> contains - a derived class called - __gnu_cxx::stdio_filebuf. - This class can be constructed from a C FILE* or a file - descriptor, and provides the fd() function. + the fd() function were removed from the standard + filebuf. Instead, <ext/stdio_filebuf.h> contains + a derived class called + __gnu_cxx::stdio_filebuf. + This class can be constructed from a C FILE* or a file + descriptor, and provides the fd() function.

    If you want to access a filebuf's file descriptor to implement file locking (e.g. using the fcntl() system call) then you might be interested in Henry Suter's RWLock class.

    -

    Prev Up Next
    Chapter 38. Iterators Home Chapter 40. Demangling
    +

    Prev Up Next
    Chapter 25. Iterators Home Chapter 27. Demangling
    diff --git a/libstdc++-v3/doc/html/manual/ext_iterators.html b/libstdc++-v3/doc/html/manual/ext_iterators.html index 88259a8ace9..5f5a5348547 100644 --- a/libstdc++-v3/doc/html/manual/ext_iterators.html +++ b/libstdc++-v3/doc/html/manual/ext_iterators.html @@ -1,9 +1,9 @@ -Chapter 38. Iterators
    Chapter 38. Iterators
    Prev Part XII.  +Chapter 25. Iterators
    Chapter 25. Iterators
    Prev Part III.  Extensions - Next

    Chapter 38. Iterators

    24.3.2 describes struct iterator, which didn't exist in the +

    		 Next

    Chapter 25. Iterators

    24.3.2 describes struct iterator, which didn't exist in the original HP STL implementation (the language wasn't rich enough at the time). For backwards compatibility, base classes are provided which declare the same nested typedefs: @@ -11,4 +11,4 @@ two iterators and returns a result. It is extended by another signature which takes two iterators and a reference to a result. The result is modified, and the function returns nothing. -

    Prev Up Next
    Chapter 37. Numerics Home Chapter 39. Input and Output
    +

    Prev Up Next
    Chapter 24. Numerics Home Chapter 26. Input and Output
    diff --git a/libstdc++-v3/doc/html/manual/ext_numerics.html b/libstdc++-v3/doc/html/manual/ext_numerics.html index e8f86678a7c..3316ec1d0ea 100644 --- a/libstdc++-v3/doc/html/manual/ext_numerics.html +++ b/libstdc++-v3/doc/html/manual/ext_numerics.html @@ -1,9 +1,9 @@ -Chapter 37. Numerics
    Chapter 37. Numerics
    Prev Part XII.  +Chapter 24. Numerics
    Chapter 24. Numerics
    Prev Part III.  Extensions - Next

    Chapter 37. Numerics

    26.4, the generalized numeric operations such as accumulate, are extended +

    		 Next

    Chapter 24. Numerics

    26.4, the generalized numeric operations such as accumulate, are extended with the following functions: 

        power (x, n);
@@ -17,4 +17,4 @@
    That is, it assigns value to *first, value + 1 to *(first + 1) and so
    on."  Quoted from SGI documentation.
 
    -   void iota(_ForwardIter first, _ForwardIter last, _Tp value);
    Prev Up Next
    Chapter 36. Algorithms Home Chapter 38. Iterators
    + void iota(_ForwardIter first, _ForwardIter last, _Tp value);
    Prev Up Next
    Chapter 23. Algorithms Home Chapter 25. Iterators
    diff --git a/libstdc++-v3/doc/html/manual/ext_utilities.html b/libstdc++-v3/doc/html/manual/ext_utilities.html index 2685de374b9..3485222aa4b 100644 --- a/libstdc++-v3/doc/html/manual/ext_utilities.html +++ b/libstdc++-v3/doc/html/manual/ext_utilities.html @@ -1,19 +1,19 @@ -Chapter 35. Utilities
    Chapter 35. Utilities
    Prev Part XII.  +Chapter 22. Utilities
    Chapter 22. Utilities
    Prev Part III.  Extensions - Next

    Chapter 35. Utilities

    +

    		 Next

    Chapter 22. Utilities

    The <functional> header contains many additional functors and helper functions, extending section 20.3. They are implemented in the file stl_function.h: -

    • identity_element for addition and multiplication. * +

      • identity_element for addition and multiplication. *

      • The functor identity, whose operator() - returns the argument unchanged. * + returns the argument unchanged. *

      • Composition functors unary_function and binary_function, and their helpers compose1 - and compose2. * -

      • select1st and select2nd, to strip pairs. * + and compose2. * +

      • select1st and select2nd, to strip pairs. *

      • project1st and project2nd. *

      • A set of functors/functions which always return the same result. They are constant_void_fun, constant_binary_fun, constant_unary_fun, constant0, @@ -38,4 +38,4 @@ get_temporary_buffer(5, (int*)0);

        The specialized algorithms of section 20.4.4 are extended with uninitialized_copy_n. * -

      Prev Up Next
      Deprecated HP/SGI Home Chapter 36. Algorithms
      +

    Prev Up Next
    Deprecated HP/SGI Home Chapter 23. Algorithms
    diff --git a/libstdc++-v3/doc/html/manual/extensions.html b/libstdc++-v3/doc/html/manual/extensions.html index f441d4c8ad8..1046b4ba442 100644 --- a/libstdc++-v3/doc/html/manual/extensions.html +++ b/libstdc++-v3/doc/html/manual/extensions.html @@ -1,9 +1,9 @@ -Part XII.  Extensions
    Part XII.  +Part III.  Extensions
    Part III.  Extensions -
    Prev The GNU C++ Library Next

    Part XII.  +

    Prev The GNU C++ Library Next

    Part III.  Extensions - -

    Table of Contents

    29. Compile Time Checks
    30. Debug Mode
    Intro
    Semantics
    Using
    Using the Debug Mode
    Using a Specific Debug Container
    Design
    Goals
    Methods
    Other Implementations
    31. Parallel Mode
    Intro
    Semantics
    Using
    Prerequisite Compiler Flags
    Using Parallel Mode
    Using Specific Parallel Components
    Design
    Interface Basics
    Configuration and Tuning
    Implementation Namespaces
    Testing
    Bibliography
    32. Profile Mode
    Intro
    Using the Profile Mode
    Tuning the Profile Mode
    Design
    Wrapper Model
    Instrumentation
    Run Time Behavior
    Analysis and Diagnostics
    Cost Model
    Reports
    Testing
    Extensions for Custom Containers
    Empirical Cost Model
    Implementation Issues
    Stack Traces
    Symbolization of Instruction Addresses
    Concurrency
    Using the Standard Library in the Instrumentation Implementation
    Malloc Hooks
    Construction and Destruction of Global Objects
    Developer Information
    Big Picture
    How To Add A Diagnostic
    Diagnostics
    Diagnostic Template
    Containers
    Algorithms
    Data Locality
    Multithreaded Data Access
    Statistics
    Bibliography
    33. Allocators
    mt_allocator
    Intro
    Design Issues
    Implementation
    Single Thread Example
    Multiple Thread Example
    bitmap_allocator
    Design
    Implementation
    34. Containers
    Policy Based Data Structures
    HP/SGI
    Deprecated HP/SGI
    35. Utilities
    36. Algorithms
    37. Numerics
    38. Iterators
    39. Input and Output
    Derived filebufs
    40. Demangling
    41. Concurrency
    Design
    Interface to Locks and Mutexes
    Interface to Atomic Functions
    Implementation
    Using Builtin Atomic Functions
    Thread Abstraction
    Use
    Prev Up Next
    Performance Home 
    + +

    Table of Contents

    16. Compile Time Checks
    17. Debug Mode
    Intro
    Semantics
    Using
    Using the Debug Mode
    Using a Specific Debug Container
    Design
    Goals
    Methods
    Other Implementations
    18. Parallel Mode
    Intro
    Semantics
    Using
    Prerequisite Compiler Flags
    Using Parallel Mode
    Using Specific Parallel Components
    Design
    Interface Basics
    Configuration and Tuning
    Implementation Namespaces
    Testing
    Bibliography
    19. Profile Mode
    Intro
    Using the Profile Mode
    Tuning the Profile Mode
    Design
    Wrapper Model
    Instrumentation
    Run Time Behavior
    Analysis and Diagnostics
    Cost Model
    Reports
    Testing
    Extensions for Custom Containers
    Empirical Cost Model
    Implementation Issues
    Stack Traces
    Symbolization of Instruction Addresses
    Concurrency
    Using the Standard Library in the Instrumentation Implementation
    Malloc Hooks
    Construction and Destruction of Global Objects
    Developer Information
    Big Picture
    How To Add A Diagnostic
    Diagnostics
    Diagnostic Template
    Containers
    Algorithms
    Data Locality
    Multithreaded Data Access
    Statistics
    Bibliography
    20. Allocators
    mt_allocator
    Intro
    Design Issues
    Implementation
    Single Thread Example
    Multiple Thread Example
    bitmap_allocator
    Design
    Implementation
    21. Containers
    Policy Based Data Structures
    HP/SGI
    Deprecated HP/SGI
    22. Utilities
    23. Algorithms
    24. Numerics
    25. Iterators
    26. Input and Output
    Derived filebufs
    27. Demangling
    28. Concurrency
    Design
    Interface to Locks and Mutexes
    Interface to Atomic Functions
    Implementation
    Using Builtin Atomic Functions
    Thread Abstraction
    Use
    Prev Up Next
    Facets Home 
    diff --git a/libstdc++-v3/doc/html/manual/facets.html b/libstdc++-v3/doc/html/manual/facets.html index ba3728e93d1..3a8542aff28 100644 --- a/libstdc++-v3/doc/html/manual/facets.html +++ b/libstdc++-v3/doc/html/manual/facets.html @@ -1,9 +1,9 @@ -Chapter 15. Facets aka Categories
    Chapter 15. Facets aka Categories
    Prev Part VI.  +Facets
    Facets
    Prev Chapter 8.  Localization - Next

    Chapter 15. Facets aka Categories

    Table of Contents

    ctype
    Implementation
    Future
    codecvt
    Requirements
    Design
    Implementation
    Use
    Future
    messages
    Requirements
    Design
    Implementation
    Use
    Future

    ctype

    Implementation

    Specializations

    +

    		 Next

    Facets

    ctype

    Implementation

    Specializations

    For the required specialization codecvt<wchar_t, char, mbstate_t> , conversions are made between the internal character set (always UCS4 on GNU/Linux) and whatever the currently selected locale for the @@ -28,50 +28,725 @@ to wchar_t and wcsrtombs for conversions between wchar_t and char.

    Neither of these two required specializations deals with Unicode characters. -

    Future

    • - How to deal with the global locale issue? -

    • +

    Future

    • + How to deal with the global locale issue? +

    • How to deal with different types than char, wchar_t?

    • - Overlap between codecvt/ctype: narrow/widen -

    • + Overlap between codecvt/ctype: narrow/widen +

    • Mask typedef in codecvt_base, argument types in codecvt. what - is know about this type? -

    • + is know about this type? +

    • Why mask* argument in codecvt?

    • Can this be made (more) generic? is there a simple way to straighten out the configure-time mess that is a by-product of - this class? -

    • + this class? +

    • Get the ctype<wchar_t>::mask stuff under control. Need to make some kind of static table, and not do lookup every time somebody hits the do_is... functions. Too bad we can't just - redefine mask for ctype<wchar_t> -

    • + redefine mask for ctype<wchar_t> +

    • Rename abstract base class. See if just smash-overriding is a better approach. Clarify, add sanity to naming. -

    Bibliography

    +

    Bibliography

    The GNU C Library - . Roland McGrath. Ulrich Drepper. Copyright © 2007 FSF. Chapters 6 Character Set Handling and 7 Locales and Internationalization.

    + . Roland McGrath. Ulrich Drepper. Copyright © 2007 FSF. Chapters 6 Character Set Handling and 7 Locales and Internationalization.

    Correspondence - . Ulrich Drepper. Copyright © 2002 .

    + . Ulrich Drepper. Copyright © 2002 .

    ISO/IEC 14882:1998 Programming languages - C++ - . Copyright © 1998 ISO.

    + . Copyright © 1998 ISO.

    ISO/IEC 9899:1999 Programming languages - C - . Copyright © 1999 ISO.

    - The Open Group Base Specifications, Issue 6 (IEEE Std. 1003.1-2004) - . Copyright © 1999 - The Open Group/The Institute of Electrical and Electronics Engineers, Inc.. + . Copyright © 1999 ISO.

    + + The Open Group Base Specifications, Issue 6 (IEEE Std. 1003.1-2004) + - .

    + . Copyright © 1999 + The Open Group/The Institute of Electrical and Electronics Engineers, Inc..

    The C++ Programming Language, Special Edition . Bjarne Stroustrup. Copyright © 2000 Addison Wesley, Inc.. Appendix D. Addison Wesley - .

    + .

    Standard C++ IOStreams and Locales . Advanced Programmer's Guide and Reference . Angelika Langer. Klaus Kreft. Copyright © 2000 Addison Wesley Longman, Inc.. Addison Wesley Longman - .

    Prev Up Next
    Chapter 14. Locales Home codecvt
    + .

    codecvt

    +The standard class codecvt attempts to address conversions between +different character encoding schemes. In particular, the standard +attempts to detail conversions between the implementation-defined wide +characters (hereafter referred to as wchar_t) and the standard type +char that is so beloved in classic “C” (which can now be +referred to as narrow characters.) This document attempts to describe +how the GNU libstdc++ implementation deals with the conversion between +wide and narrow characters, and also presents a framework for dealing +with the huge number of other encodings that iconv can convert, +including Unicode and UTF8. Design issues and requirements are +addressed, and examples of correct usage for both the required +specializations for wide and narrow characters and the +implementation-provided extended functionality are given. +

    Requirements

    +Around page 425 of the C++ Standard, this charming heading comes into view: +

    +22.2.1.5 - Template class codecvt +

    +The text around the codecvt definition gives some clues: +

    + +-1- The class codecvt<internT,externT,stateT> is for use when +converting from one codeset to another, such as from wide characters +to multibyte characters, between wide character encodings such as +Unicode and EUC. + +

    +Hmm. So, in some unspecified way, Unicode encodings and +translations between other character sets should be handled by this +class. +

    + +-2- The stateT argument selects the pair of codesets being mapped between. + +

    +Ah ha! Another clue... +

    + +-3- The instantiations required in the Table ?? +(lib.locale.category), namely codecvt<wchar_t,char,mbstate_t> and +codecvt<char,char,mbstate_t>, convert the implementation-defined +native character set. codecvt<char,char,mbstate_t> implements a +degenerate conversion; it does not convert at +all. codecvt<wchar_t,char,mbstate_t> converts between the native +character sets for tiny and wide characters. Instantiations on +mbstate_t perform conversion between encodings known to the library +implementor. Other encodings can be converted by specializing on a +user-defined stateT type. The stateT object can contain any state that +is useful to communicate to or from the specialized do_convert member. + +

    +At this point, a couple points become clear: +

    +One: The standard clearly implies that attempts to add non-required +(yet useful and widely used) conversions need to do so through the +third template parameter, stateT.

    +Two: The required conversions, by specifying mbstate_t as the third +template parameter, imply an implementation strategy that is mostly +(or wholly) based on the underlying C library, and the functions +mcsrtombs and wcsrtombs in particular.

    Design

    wchar_t Size

    + The simple implementation detail of wchar_t's size seems to + repeatedly confound people. Many systems use a two byte, + unsigned integral type to represent wide characters, and use an + internal encoding of Unicode or UCS2. (See AIX, Microsoft NT, + Java, others.) Other systems, use a four byte, unsigned integral + type to represent wide characters, and use an internal encoding + of UCS4. (GNU/Linux systems using glibc, in particular.) The C + programming language (and thus C++) does not specify a specific + size for the type wchar_t. +

    + Thus, portable C++ code cannot assume a byte size (or endianness) either. +

    Support for Unicode

    + Probably the most frequently asked question about code conversion + is: "So dudes, what's the deal with Unicode strings?" + The dude part is optional, but apparently the usefulness of + Unicode strings is pretty widely appreciated. Sadly, this specific + encoding (And other useful encodings like UTF8, UCS4, ISO 8859-10, + etc etc etc) are not mentioned in the C++ standard. +

    + A couple of comments: +

    + The thought that all one needs to convert between two arbitrary + codesets is two types and some kind of state argument is + unfortunate. In particular, encodings may be stateless. The naming + of the third parameter as stateT is unfortunate, as what is really + needed is some kind of generalized type that accounts for the + issues that abstract encodings will need. The minimum information + that is required includes: +

    • + Identifiers for each of the codesets involved in the + conversion. For example, using the iconv family of functions + from the Single Unix Specification (what used to be called + X/Open) hosted on the GNU/Linux operating system allows + bi-directional mapping between far more than the following + tantalizing possibilities: +

      + (An edited list taken from `iconv --list` on a + Red Hat 6.2/Intel system: + 

      +8859_1, 8859_9, 10646-1:1993, 10646-1:1993/UCS4, ARABIC, ARABIC7,
+ASCII, EUC-CN, EUC-JP, EUC-KR, EUC-TW, GREEK-CCIcode, GREEK, GREEK7-OLD,
+GREEK7, GREEK8, HEBREW, ISO-8859-1, ISO-8859-2, ISO-8859-3,
+ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8,
+ISO-8859-9, ISO-8859-10, ISO-8859-11, ISO-8859-13, ISO-8859-14,
+ISO-8859-15, ISO-10646, ISO-10646/UCS2, ISO-10646/UCS4,
+ISO-10646/UTF-8, ISO-10646/UTF8, SHIFT-JIS, SHIFT_JIS, UCS-2, UCS-4,
+UCS2, UCS4, UNICODE, UNICODEBIG, UNICODELIcodeLE, US-ASCII, US, UTF-8,
+UTF-16, UTF8, UTF16).
+

      +For iconv-based implementations, string literals for each of the +encodings (i.e. "UCS-2" and "UTF-8") are necessary, +although for other, +non-iconv implementations a table of enumerated values or some other +mechanism may be required. +

    • + Maximum length of the identifying string literal. +

    • + Some encodings require explicit endian-ness. As such, some kind + of endian marker or other byte-order marker will be necessary. See + "Footnotes for C/C++ developers" in Haible for more information on + UCS-2/Unicode endian issues. (Summary: big endian seems most likely, + however implementations, most notably Microsoft, vary.) +

    • + Types representing the conversion state, for conversions involving + the machinery in the "C" library, or the conversion descriptor, for + conversions using iconv (such as the type iconv_t.) Note that the + conversion descriptor encodes more information than a simple encoding + state type. +

    • + Conversion descriptors for both directions of encoding. (i.e., both + UCS-2 to UTF-8 and UTF-8 to UCS-2.) +

    • + Something to indicate if the conversion requested if valid. +

    • + Something to represent if the conversion descriptors are valid. +

    • + Some way to enforce strict type checking on the internal and + external types. As part of this, the size of the internal and + external types will need to be known. +

    Other Issues

    +In addition, multi-threaded and multi-locale environments also impact +the design and requirements for code conversions. In particular, they +affect the required specialization codecvt<wchar_t, char, mbstate_t> +when implemented using standard "C" functions. +

    +Three problems arise, one big, one of medium importance, and one small. +

    +First, the small: mcsrtombs and wcsrtombs may not be multithread-safe +on all systems required by the GNU tools. For GNU/Linux and glibc, +this is not an issue. +

    +Of medium concern, in the grand scope of things, is that the functions +used to implement this specialization work on null-terminated +strings. Buffers, especially file buffers, may not be null-terminated, +thus giving conversions that end prematurely or are otherwise +incorrect. Yikes! +

    +The last, and fundamental problem, is the assumption of a global +locale for all the "C" functions referenced above. For something like +C++ iostreams (where codecvt is explicitly used) the notion of +multiple locales is fundamental. In practice, most users may not run +into this limitation. However, as a quality of implementation issue, +the GNU C++ library would like to offer a solution that allows +multiple locales and or simultaneous usage with computationally +correct results. In short, libstdc++ is trying to offer, as an +option, a high-quality implementation, damn the additional complexity! +

    +For the required specialization codecvt<wchar_t, char, mbstate_t> , +conversions are made between the internal character set (always UCS4 +on GNU/Linux) and whatever the currently selected locale for the +LC_CTYPE category implements. +

    Implementation

    +The two required specializations are implemented as follows: +

    + +codecvt<char, char, mbstate_t> + +

    +This is a degenerate (i.e., does nothing) specialization. Implementing +this was a piece of cake. +

    + +codecvt<char, wchar_t, mbstate_t> + +

    +This specialization, by specifying all the template parameters, pretty +much ties the hands of implementors. As such, the implementation is +straightforward, involving mcsrtombs for the conversions between char +to wchar_t and wcsrtombs for conversions between wchar_t and char. +

    +Neither of these two required specializations deals with Unicode +characters. As such, libstdc++ implements a partial specialization +of the codecvt class with and iconv wrapper class, encoding_state as the +third template parameter. +

    +This implementation should be standards conformant. First of all, the +standard explicitly points out that instantiations on the third +template parameter, stateT, are the proper way to implement +non-required conversions. Second of all, the standard says (in Chapter +17) that partial specializations of required classes are a-ok. Third +of all, the requirements for the stateT type elsewhere in the standard +(see 21.1.2 traits typedefs) only indicate that this type be copy +constructible. +

    +As such, the type encoding_state is defined as a non-templatized, POD +type to be used as the third type of a codecvt instantiation. This +type is just a wrapper class for iconv, and provides an easy interface +to iconv functionality. +

    +There are two constructors for encoding_state: +

    + +encoding_state() : __in_desc(0), __out_desc(0) + +

    +This default constructor sets the internal encoding to some default +(currently UCS4) and the external encoding to whatever is returned by +nl_langinfo(CODESET). +

    + +encoding_state(const char* __int, const char* __ext) + +

    +This constructor takes as parameters string literals that indicate the +desired internal and external encoding. There are no defaults for +either argument. +

    +One of the issues with iconv is that the string literals identifying +conversions are not standardized. Because of this, the thought of +mandating and or enforcing some set of pre-determined valid +identifiers seems iffy: thus, a more practical (and non-migraine +inducing) strategy was implemented: end-users can specify any string +(subject to a pre-determined length qualifier, currently 32 bytes) for +encodings. It is up to the user to make sure that these strings are +valid on the target system. +

    + +void +_M_init() + +

    +Strangely enough, this member function attempts to open conversion +descriptors for a given encoding_state object. If the conversion +descriptors are not valid, the conversion descriptors returned will +not be valid and the resulting calls to the codecvt conversion +functions will return error. +

    + +bool +_M_good() + +

    +Provides a way to see if the given encoding_state object has been +properly initialized. If the string literals describing the desired +internal and external encoding are not valid, initialization will +fail, and this will return false. If the internal and external +encodings are valid, but iconv_open could not allocate conversion +descriptors, this will also return false. Otherwise, the object is +ready to convert and will return true. +

    + +encoding_state(const encoding_state&) + +

    +As iconv allocates memory and sets up conversion descriptors, the copy +constructor can only copy the member data pertaining to the internal +and external code conversions, and not the conversion descriptors +themselves. +

    +Definitions for all the required codecvt member functions are provided +for this specialization, and usage of codecvt<internal character type, +external character type, encoding_state> is consistent with other +codecvt usage. +

    Use

    A conversions involving string literal.

    +  typedef codecvt_base::result                  result;
+  typedef unsigned short                        unicode_t;
+  typedef unicode_t                             int_type;
+  typedef char                                  ext_type;
+  typedef encoding_state                          state_type;
+  typedef codecvt<int_type, ext_type, state_type> unicode_codecvt;
+
+  const ext_type*       e_lit = "black pearl jasmine tea";
+  int                   size = strlen(e_lit);
+  int_type              i_lit_base[24] =
+  { 25088, 27648, 24832, 25344, 27392, 8192, 28672, 25856, 24832, 29184,
+    27648, 8192, 27136, 24832, 29440, 27904, 26880, 28160, 25856, 8192, 29696,
+    25856, 24832, 2560
+  };
+  const int_type*       i_lit = i_lit_base;
+  const ext_type*       efrom_next;
+  const int_type*       ifrom_next;
+  ext_type*             e_arr = new ext_type[size + 1];
+  ext_type*             eto_next;
+  int_type*             i_arr = new int_type[size + 1];
+  int_type*             ito_next;
+
+  // construct a locale object with the specialized facet.
+  locale                loc(locale::classic(), new unicode_codecvt);
+  // sanity check the constructed locale has the specialized facet.
+  VERIFY( has_facet<unicode_codecvt>(loc) );
+  const unicode_codecvt& cvt = use_facet<unicode_codecvt>(loc);
+  // convert between const char* and unicode strings
+  unicode_codecvt::state_type state01("UNICODE", "ISO_8859-1");
+  initialize_state(state01);
+  result r1 = cvt.in(state01, e_lit, e_lit + size, efrom_next,
+		     i_arr, i_arr + size, ito_next);
+  VERIFY( r1 == codecvt_base::ok );
+  VERIFY( !int_traits::compare(i_arr, i_lit, size) );
+  VERIFY( efrom_next == e_lit + size );
+  VERIFY( ito_next == i_arr + size );
+

    Future

    • + a. things that are sketchy, or remain unimplemented: + do_encoding, max_length and length member functions + are only weakly implemented. I have no idea how to do + this correctly, and in a generic manner. Nathan? +

    • + b. conversions involving std::string +

      • + how should operators != and == work for string of + different/same encoding? +

      • + what is equal? A byte by byte comparison or an + encoding then byte comparison? +

      • + conversions between narrow, wide, and unicode strings +

    • + c. conversions involving std::filebuf and std::ostream +

      • + how to initialize the state object in a + standards-conformant manner? +

      • + how to synchronize the "C" and "C++" + conversion information? +

      • + wchar_t/char internal buffers and conversions between + internal/external buffers? +

    Bibliography

    + The GNU C Library + . Roland McGrath. Ulrich Drepper. Copyright © 2007 FSF. + Chapters 6 Character Set Handling and 7 Locales and Internationalization + .

    + Correspondence + . Ulrich Drepper. Copyright © 2002 .

    + ISO/IEC 14882:1998 Programming languages - C++ + . Copyright © 1998 ISO.

    + ISO/IEC 9899:1999 Programming languages - C + . Copyright © 1999 ISO.

    + + + System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008) + + + . Copyright © 2008 + The Open Group/The Institute of Electrical and Electronics + Engineers, Inc. + .

    + The C++ Programming Language, Special Edition + . Bjarne Stroustrup. Copyright © 2000 Addison Wesley, Inc.. Appendix D. + Addison Wesley + .

    + Standard C++ IOStreams and Locales + . + Advanced Programmer's Guide and Reference + . Angelika Langer. Klaus Kreft. Copyright © 2000 Addison Wesley Longman, Inc.. + Addison Wesley Longman + .

    + + + A brief description of Normative Addendum 1 + + + . Clive Feather. Extended Character Sets.

    + + + The Unicode HOWTO + + + . Bruno Haible.

    + + + UTF-8 and Unicode FAQ for Unix/Linux + + + . Markus Khun.

    messages

    +The std::messages facet implements message retrieval functionality +equivalent to Java's java.text.MessageFormat .using either GNU gettext +or IEEE 1003.1-200 functions. +

    Requirements

    +The std::messages facet is probably the most vaguely defined facet in +the standard library. It's assumed that this facility was built into +the standard library in order to convert string literals from one +locale to the other. For instance, converting the "C" locale's +const char* c = "please" to a German-localized "bitte" +during program execution. +

    +22.2.7.1 - Template class messages [lib.locale.messages] +

    +This class has three public member functions, which directly +correspond to three protected virtual member functions. +

    +The public member functions are: +

    +catalog open(const string&, const locale&) const +

    +string_type get(catalog, int, int, const string_type&) const +

    +void close(catalog) const +

    +While the virtual functions are: +

    +catalog do_open(const string&, const locale&) const +

    + +-1- Returns: A value that may be passed to get() to retrieve a +message, from the message catalog identified by the string name +according to an implementation-defined mapping. The result can be used +until it is passed to close(). Returns a value less than 0 if no such +catalog can be opened. + +

    +string_type do_get(catalog, int, int, const string_type&) const +

    + +-3- Requires: A catalog cat obtained from open() and not yet closed. +-4- Returns: A message identified by arguments set, msgid, and dfault, +according to an implementation-defined mapping. If no such message can +be found, returns dfault. + +

    +void do_close(catalog) const +

    + +-5- Requires: A catalog cat obtained from open() and not yet closed. +-6- Effects: Releases unspecified resources associated with cat. +-7- Notes: The limit on such resources, if any, is implementation-defined. + +

    Design

    +A couple of notes on the standard. +

    +First, why is messages_base::catalog specified as a typedef +to int? This makes sense for implementations that use +catopen, but not for others. Fortunately, it's not heavily +used and so only a minor irritant. +

    +Second, by making the member functions const, it is +impossible to save state in them. Thus, storing away information used +in the 'open' member function for use in 'get' is impossible. This is +unfortunate. +

    +The 'open' member function in particular seems to be oddly +designed. The signature seems quite peculiar. Why specify a const +string& argument, for instance, instead of just const +char*? Or, why specify a const locale& argument that is +to be used in the 'get' member function? How, exactly, is this locale +argument useful? What was the intent? It might make sense if a locale +argument was associated with a given default message string in the +'open' member function, for instance. Quite murky and unclear, on +reflection. +

    +Lastly, it seems odd that messages, which explicitly require code +conversion, don't use the codecvt facet. Because the messages facet +has only one template parameter, it is assumed that ctype, and not +codecvt, is to be used to convert between character sets. +

    +It is implicitly assumed that the locale for the default message +string in 'get' is in the "C" locale. Thus, all source code is assumed +to be written in English, so translations are always from "en_US" to +other, explicitly named locales. +

    Implementation

    Models

    + This is a relatively simple class, on the face of it. The standard + specifies very little in concrete terms, so generic + implementations that are conforming yet do very little are the + norm. Adding functionality that would be useful to programmers and + comparable to Java's java.text.MessageFormat takes a bit of work, + and is highly dependent on the capabilities of the underlying + operating system. +

    + Three different mechanisms have been provided, selectable via + configure flags: +

    • + generic +

      + This model does very little, and is what is used by default. +

    • + gnu +

      + The gnu model is complete and fully tested. It's based on the + GNU gettext package, which is part of glibc. It uses the + functions textdomain, bindtextdomain, gettext to + implement full functionality. Creating message catalogs is a + relatively straight-forward process and is lightly documented + below, and fully documented in gettext's distributed + documentation. +

    • + ieee_1003.1-200x +

      + This is a complete, though untested, implementation based on + the IEEE standard. The functions catopen, catgets, + catclose are used to retrieve locale-specific messages + given the appropriate message catalogs that have been + constructed for their use. Note, the script + po2msg.sed that is part of the gettext distribution can + convert gettext catalogs into catalogs that + catopen can use. +

    +A new, standards-conformant non-virtual member function signature was +added for 'open' so that a directory could be specified with a given +message catalog. This simplifies calling conventions for the gnu +model. +

    The GNU Model

    + The messages facet, because it is retrieving and converting + between characters sets, depends on the ctype and perhaps the + codecvt facet in a given locale. In addition, underlying "C" + library locale support is necessary for more than just the + LC_MESSAGES mask: LC_CTYPE is also + necessary. To avoid any unpleasantness, all bits of the "C" mask + (i.e. LC_ALL) are set before retrieving messages. +

    + Making the message catalogs can be initially tricky, but become + quite simple with practice. For complete info, see the gettext + documentation. Here's an idea of what is required: +

    • + Make a source file with the required string literals that need + to be translated. See intl/string_literals.cc for + an example. +

    • + Make initial catalog (see "4 Making the PO Template File" from + the gettext docs).

      + xgettext --c++ --debug string_literals.cc -o libstdc++.pot +

    • Make language and country-specific locale catalogs.

      + cp libstdc++.pot fr_FR.po +

      + cp libstdc++.pot de_DE.po +

    • + Edit localized catalogs in emacs so that strings are + translated. +

      + emacs fr_FR.po +

    • Make the binary mo files.

      + msgfmt fr_FR.po -o fr_FR.mo +

      + msgfmt de_DE.po -o de_DE.mo +

    • Copy the binary files into the correct directory structure.

      + cp fr_FR.mo (dir)/fr_FR/LC_MESSAGES/libstdc++.mo +

      + cp de_DE.mo (dir)/de_DE/LC_MESSAGES/libstdc++.mo +

    • Use the new message catalogs.

      + locale loc_de("de_DE"); +

      + + use_facet<messages<char> >(loc_de).open("libstdc++", locale(), dir); + +

    Use

    + A simple example using the GNU model of message conversion. + 

    +#include <iostream>
+#include <locale>
+using namespace std;
+
+void test01()
+{
+  typedef messages<char>::catalog catalog;
+  const char* dir =
+  "/mnt/egcs/build/i686-pc-linux-gnu/libstdc++/po/share/locale";
+  const locale loc_de("de_DE");
+  const messages<char>& mssg_de = use_facet<messages<char> >(loc_de);
+
+  catalog cat_de = mssg_de.open("libstdc++", loc_de, dir);
+  string s01 = mssg_de.get(cat_de, 0, 0, "please");
+  string s02 = mssg_de.get(cat_de, 0, 0, "thank you");
+  cout << "please in german:" << s01 << '\n';
+  cout << "thank you in german:" << s02 << '\n';
+  mssg_de.close(cat_de);
+}
+

    Future

    • + Things that are sketchy, or remain unimplemented: +

      • + _M_convert_from_char, _M_convert_to_char are in flux, + depending on how the library ends up doing character set + conversions. It might not be possible to do a real character + set based conversion, due to the fact that the template + parameter for messages is not enough to instantiate the + codecvt facet (1 supplied, need at least 2 but would prefer + 3). +

      • + There are issues with gettext needing the global locale set + to extract a message. This dependence on the global locale + makes the current "gnu" model non MT-safe. Future versions + of glibc, i.e. glibc 2.3.x will fix this, and the C++ library + bits are already in place. +

    • + Development versions of the GNU "C" library, glibc 2.3 will allow + a more efficient, MT implementation of std::messages, and will + allow the removal of the _M_name_messages data member. If this is + done, it will change the library ABI. The C++ parts to support + glibc 2.3 have already been coded, but are not in use: once this + version of the "C" library is released, the marked parts of the + messages implementation can be switched over to the new "C" + library functionality. +

    • + At some point in the near future, std::numpunct will probably use + std::messages facilities to implement truename/falsename + correctly. This is currently not done, but entries in + libstdc++.pot have already been made for "true" and "false" string + literals, so all that remains is the std::numpunct coding and the + configure/make hassles to make the installed library search its + own catalog. Currently the libstdc++.mo catalog is only searched + for the testsuite cases involving messages members. +

    • The following member functions:

      + + catalog + open(const basic_string<char>& __s, const locale& __loc) const + +

      + + catalog + open(const basic_string<char>&, const locale&, const char*) const; + +

      + Don't actually return a "value less than 0 if no such catalog + can be opened" as required by the standard in the "gnu" + model. As of this writing, it is unknown how to query to see + if a specified message catalog exists using the gettext + package. +

    Bibliography

    + The GNU C Library + . Roland McGrath. Ulrich Drepper. Copyright © 2007 FSF. Chapters 6 Character Set Handling, and 7 Locales and Internationalization + .

    + Correspondence + . Ulrich Drepper. Copyright © 2002 .

    + ISO/IEC 14882:1998 Programming languages - C++ + . Copyright © 1998 ISO.

    + ISO/IEC 9899:1999 Programming languages - C + . Copyright © 1999 ISO.

    + + + System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008) + + + . Copyright © 2008 + The Open Group/The Institute of Electrical and Electronics + Engineers, Inc. + .

    + The C++ Programming Language, Special Edition + . Bjarne Stroustrup. Copyright © 2000 Addison Wesley, Inc.. Appendix D. + Addison Wesley + .

    + Standard C++ IOStreams and Locales + . + Advanced Programmer's Guide and Reference + . Angelika Langer. Klaus Kreft. Copyright © 2000 Addison Wesley Longman, Inc.. + Addison Wesley Longman + .

    + + + API Specifications, Java Platform + + + . java.util.Properties, java.text.MessageFormat, +java.util.Locale, java.util.ResourceBundle + .

    + + + GNU gettext tools, version 0.10.38, Native Language Support +Library and Tools. + + + .

    Prev Up Next
    Chapter 8.  + Localization + + Home Chapter 9.  + Containers + +
    diff --git a/libstdc++-v3/doc/html/manual/fstreams.html b/libstdc++-v3/doc/html/manual/fstreams.html index 6b0a06bca32..0795443b26d 100644 --- a/libstdc++-v3/doc/html/manual/fstreams.html +++ b/libstdc++-v3/doc/html/manual/fstreams.html @@ -1,9 +1,9 @@ -Chapter 27. File Based Streams
    Chapter 27. File Based Streams
    Prev Part XI.  +File Based Streams
    File Based Streams
    Prev Chapter 13.  Input and Output - Next

    Chapter 27. File Based Streams

    Table of Contents

    Copying a File
    Binary Input and Output

    Copying a File

    +

    		 Next

    File Based Streams

    Copying a File

    So you want to copy a file quickly and easily, and most important, completely portably. And since this is C++, you have an open ifstream (call it IN) and an open ofstream (call it OUT): @@ -22,7 +22,7 @@ of "output_file" may surprise you.

    Seriously, go do it. Get surprised, then come back. It's worth it.

    The thing to remember is that the basic_[io]stream classes - handle formatting, nothing else. In particular, they break up on + handle formatting, nothing else. In chaptericular, they break up on whitespace. The actual reading, writing, and storing of data is handled by the basic_streambuf family. Fortunately, the operator<< is overloaded to take an ostream and @@ -31,13 +31,13 @@

    Why a pointer to streambuf and not just a streambuf? Well, the [io]streams hold pointers (or references, depending on the implementation) to their buffers, not the actual - buffers. This allows polymorphic behavior on the part of the buffers + buffers. This allows polymorphic behavior on the chapter of the buffers as well as the streams themselves. The pointer is easily retrieved using the rdbuf() member function. Therefore, the easiest way to copy the file is: 

        OUT << IN.rdbuf();

    So what was happening with OUT<<IN? Undefined - behavior, since that particular << isn't defined by the Standard. + behavior, since that chaptericular << isn't defined by the Standard. I have seen instances where it is implemented, but the character extraction process removes all the whitespace, leaving you with no blank lines and only "Thequickbrownfox...". With @@ -45,8 +45,106 @@ member pointers) sometimes gets converted to a void*, and the output file then contains a perfect text representation of a hexadecimal address (quite a big surprise). Others don't compile at all. -

    Also note that none of this is specific to o*f*streams. - The operators shown above are all defined in the parent +

    Also note that none of this is specific to o*f*streams. + The operators shown above are all defined in the parent basic_ostream class and are therefore available with all possible descendants. -

    Prev Up Next
    Chapter 26. Memory Based Streams Home Binary Input and Output
    +

    Binary Input and Output

    +

    The first and most important thing to remember about binary I/O is + that opening a file with ios::binary is not, repeat + not, the only thing you have to do. It is not a silver + bullet, and will not allow you to use the <</>> + operators of the normal fstreams to do binary I/O. +

    Sorry. Them's the breaks. +

    This isn't going to try and be a complete tutorial on reading and + writing binary files (because "binary" + covers a lot of ground), but we will try and clear + up a couple of misconceptions and common errors. +

    First, ios::binary has exactly one defined effect, no more + and no less. Normal text mode has to be concerned with the newline + characters, and the runtime system will translate between (for + example) '\n' and the appropriate end-of-line sequence (LF on Unix, + CRLF on DOS, CR on Macintosh, etc). (There are other things that + normal mode does, but that's the most obvious.) Opening a file in + binary mode disables this conversion, so reading a CRLF sequence + under Windows won't accidentally get mapped to a '\n' character, etc. + Binary mode is not supposed to suddenly give you a bitstream, and + if it is doing so in your program then you've discovered a bug in + your vendor's compiler (or some other chapter of the C++ implementation, + possibly the runtime system). +

    Second, using << to write and >> to + read isn't going to work with the standard file stream classes, even + if you use skipws during reading. Why not? Because + ifstream and ofstream exist for the purpose of formatting, + not reading and writing. Their job is to interpret the data into + text characters, and that's exactly what you don't want to happen + during binary I/O. +

    Third, using the get() and put()/write() member + functions still aren't guaranteed to help you. These are + "unformatted" I/O functions, but still character-based. + (This may or may not be what you want, see below.) +

    Notice how all the problems here are due to the inappropriate use + of formatting functions and classes to perform something + which requires that formatting not be done? There are a + seemingly infinite number of solutions, and a few are listed here: +

    • “Derive your own fstream-type classes and write your own + <</>> operators to do binary I/O on whatever data + types you're using.” +

      + This is a Bad Thing, because while + the compiler would probably be just fine with it, other humans + are going to be confused. The overloaded bitshift operators + have a well-defined meaning (formatting), and this breaks it. +

    • + “Build the file structure in memory, then + mmap() the file and copy the + structure. + ” +

      + Well, this is easy to make work, and easy to break, and is + pretty equivalent to using ::read() and + ::write() directly, and makes no use of the + iostream library at all... +

    • + “Use streambufs, that's what they're there for.” +

      + While not trivial for the beginner, this is the best of all + solutions. The streambuf/filebuf layer is the layer that is + responsible for actual I/O. If you want to use the C++ + library for binary I/O, this is where you start. +

    How to go about using streambufs is a bit beyond the scope of this + document (at least for now), but while streambufs go a long way, + they still leave a couple of things up to you, the programmer. + As an example, byte ordering is completely between you and the + operating system, and you have to handle it yourself. +

    Deriving a streambuf or filebuf + class from the standard ones, one that is specific to your data + types (or an abstraction thereof) is probably a good idea, and + lots of examples exist in journals and on Usenet. Using the + standard filebufs directly (either by declaring your own or by + using the pointer returned from an fstream's rdbuf()) + is certainly feasible as well. +

    One area that causes problems is trying to do bit-by-bit operations + with filebufs. C++ is no different from C in this respect: I/O + must be done at the byte level. If you're trying to read or write + a few bits at a time, you're going about it the wrong way. You + must read/write an integral number of bytes and then process the + bytes. (For example, the streambuf functions take and return + variables of type int_type.) +

    Another area of problems is opening text files in binary mode. + Generally, binary mode is intended for binary files, and opening + text files in binary mode means that you now have to deal with all of + those end-of-line and end-of-file problems that we mentioned before. +

    + An instructive thread from comp.lang.c++.moderated delved off into + this topic starting more or less at + this + post and continuing to the end of the thread. (The subject heading is "binary iostreams" on both comp.std.c++ + and comp.lang.c++.moderated.) Take special note of the replies by James Kanze and Dietmar Kühl. +

    Briefly, the problems of byte ordering and type sizes mean that + the unformatted functions like ostream::put() and + istream::get() cannot safely be used to communicate + between arbitrary programs, or across a network, or from one + invocation of a program to another invocation of the same program + on a different platform, etc. +

    Prev Up Next
    Memory Based Streams Home Interacting with C
    diff --git a/libstdc++-v3/doc/html/manual/functors.html b/libstdc++-v3/doc/html/manual/functors.html deleted file mode 100644 index eca77856530..00000000000 --- a/libstdc++-v3/doc/html/manual/functors.html +++ /dev/null @@ -1,15 +0,0 @@ - - -Chapter 9. Functors
    Chapter 9. Functors
    Prev Part IV.  - Utilities - - Next

    Chapter 9. Functors

    If you don't know what functors are, you're not alone. Many people - get slightly the wrong idea. In the interest of not reinventing - the wheel, we will refer you to the introduction to the functor - concept written by SGI as part of their STL, in - their - http://www.sgi.com/tech/stl/functors.html. -

    Prev Up Next
    Part IV.  - Utilities - - Home Chapter 10. Pairs
    diff --git a/libstdc++-v3/doc/html/manual/fundamental_types.html b/libstdc++-v3/doc/html/manual/fundamental_types.html deleted file mode 100644 index 0196e5a8dec..00000000000 --- a/libstdc++-v3/doc/html/manual/fundamental_types.html +++ /dev/null @@ -1,43 +0,0 @@ - - -Chapter 4. Types
    Chapter 4. Types
    Prev Part II.  - Support - - Next

    Chapter 4. Types

    Table of Contents

    Fundamental Types
    Numeric Properties
    NULL

    Fundamental Types

    - C++ has the following builtin types: -

    • - char -

    • - signed char -

    • - unsigned char -

    • - signed short -

    • - signed int -

    • - signed long -

    • - unsigned short -

    • - unsigned int -

    • - unsigned long -

    • - bool -

    • - wchar_t -

    • - float -

    • - double -

    • - long double -

    - These fundamental types are always available, without having to - include a header file. These types are exactly the same in - either C++ or in C. -

    - Specializing parts of the library on these types is prohibited: - instead, use a POD. -

    Prev Up Next
     Home Numeric Properties
    diff --git a/libstdc++-v3/doc/html/manual/generalized_numeric_operations.html b/libstdc++-v3/doc/html/manual/generalized_numeric_operations.html index 74e54b47d44..7047824afa3 100644 --- a/libstdc++-v3/doc/html/manual/generalized_numeric_operations.html +++ b/libstdc++-v3/doc/html/manual/generalized_numeric_operations.html @@ -1,15 +1,15 @@ -Chapter 22. Generalized Operations
    Chapter 22. Generalized Operations
    Prev Part X.  +Generalized Operations
    Generalized Operations
    Prev Chapter 12.  Numerics - Next

    Chapter 22. Generalized Operations

    +

    		 Next

    Generalized Operations

    There are four generalized functions in the <numeric> header that follow the same conventions as those in <algorithm>. Each of them is overloaded: one signature for common default operations, and a second for fully general operations. Their names are self-explanatory to anyone who works with numerics on a regular basis: -

    • accumulate

    • inner_product

    • partial_sum

    • adjacent_difference

    Here is a simple example of the two forms of accumulate. +

    • accumulate

    • inner_product

    • chapterial_sum

    • adjacent_difference

    Here is a simple example of the two forms of accumulate. 

        int   ar[50];
    int   someval = somefunction();
@@ -26,4 +26,7 @@
       and multiplies all the members of the array; here we must obviously
       use 1 as a starting value instead of 0.
    
    The other three functions have similar dual-signature forms.
-
    Prev Up Next
    Chapter 21. Complex Home Chapter 23. Interacting with C
    +

    Prev Up Next
    Chapter 12.  + Numerics + + Home Interacting with C
    diff --git a/libstdc++-v3/doc/html/manual/internals.html b/libstdc++-v3/doc/html/manual/internals.html index cc6df8ba72c..1512752fa74 100644 --- a/libstdc++-v3/doc/html/manual/internals.html +++ b/libstdc++-v3/doc/html/manual/internals.html @@ -41,7 +41,7 @@ in sparc-sun-solaris2.8. If the new directory is name OS portion of the triplet (the default), then nothing needs to be changed.

    The first file to create in this directory, should be called os_defines.h. This file contains basic macro definitions -that are required to allow the C++ library to work with your C library. +that are required to allow the C++ library to work with your C library.

    Several libstdc++ source files unconditionally define the macro _POSIX_SOURCE. On many systems, defining this macro causes large portions of the C library header files to be eliminated @@ -91,7 +91,7 @@ are exposing proper support for the related set of functions. If defined, it must be 0 while bootstrapping the compiler/rebuilding the library.

    Finally, you should bracket the entire file in an include-guard, like this: - 

         
+   
     
 #ifndef _GLIBCXX_OS_DEFINES
 #define _GLIBCXX_OS_DEFINES
@@ -131,7 +131,7 @@ upper-case, lower-case, alphabetic, etc.  The ctype_base.h<ctype.h> to figure out
 how to define the values required by this file.
-   
    The ctype_base.h header file does not need include guards. 
+   
    The ctype_base.h header file does not need include guards.
 It should contain a single struct definition called
 ctype_base.  This struct should contain two type
 declarations, and one enumeration declaration, like this example, taken
@@ -141,20 +141,20 @@ from the IRIX configuration:
      {
        typedef unsigned int 	mask;
        typedef int* 		__to_type;
-     
+
        enum
        {
-         space = _ISspace,
-         print = _ISprint,
-         cntrl = _IScntrl,
-         upper = _ISupper,
-         lower = _ISlower,
-         alpha = _ISalpha,
-         digit = _ISdigit,
-         punct = _ISpunct,
-         xdigit = _ISxdigit,
-         alnum = _ISalnum,
-         graph = _ISgraph
+	 space = _ISspace,
+	 print = _ISprint,
+	 cntrl = _IScntrl,
+	 upper = _ISupper,
+	 lower = _ISlower,
+	 alpha = _ISalpha,
+	 digit = _ISdigit,
+	 punct = _ISpunct,
+	 xdigit = _ISxdigit,
+	 alnum = _ISalnum,
+	 graph = _ISgraph
        };
      };
 
    The mask type is the type of the elements in the table.  If your
@@ -176,14 +176,14 @@ function that must be written is the ctype<char>::ctype
 constructor.  Here is the IRIX example:
    
     ctype<char>::ctype(const mask* __table = 0, bool __del = false,
-           size_t __refs = 0)
+	   size_t __refs = 0)
        : _Ctype_nois<char>(__refs), _M_del(__table != 0 && __del),
-         _M_toupper(NULL),
-         _M_tolower(NULL),
-         _M_ctable(NULL),
-         _M_table(!__table
-                  ? (const mask*) (__libc_attr._ctype_tbl->_class + 1)
-                  : __table)
+	 _M_toupper(NULL),
+	 _M_tolower(NULL),
+	 _M_ctable(NULL),
+	 _M_table(!__table
+		  ? (const mask*) (__libc_attr._ctype_tbl->_class + 1)
+		  : __table)
        { }
 
    There are two parts of this that you might choose to alter. The first,
 and most important, is the line involving __libc_attr.  That is
@@ -199,7 +199,7 @@ lower-case, and vice versa.  Here are the IRIX versions:
      char
      ctype<char>::do_toupper(char __c) const
      { return _toupper(__c); }
-     
+
      char
      ctype<char>::do_tolower(char __c) const
      { return _tolower(__c); }
@@ -215,21 +215,21 @@ machinery to do that on your system:
      ctype<char>::do_toupper(char* __low, const char* __high) const
      {
        while (__low < __high)
-         {
-           *__low = do_toupper(*__low);
-           ++__low;
-         }
+	 {
+	   *__low = do_toupper(*__low);
+	   ++__low;
+	 }
        return __high;
      }
-     
+
      const char*
      ctype<char>::do_tolower(char* __low, const char* __high) const
      {
        while (__low < __high)
-         {
-           *__low = do_tolower(*__low);
-           ++__low;
-         }
+	 {
+	   *__low = do_tolower(*__low);
+	   ++__low;
+	 }
        return __high;
      }

    You must also provide the ctype_inline.h file, which @@ -244,7 +244,7 @@ properties; they are analogous to the functions like isalpha< ctype<char>:: is(mask __m, char __c) const throw() { return (_M_table)[(unsigned char)(__c)] & __m; } -

    The _M_table is the table passed in above, in the constructor. +

    The _M_table is the table passed in above, in the constructor. This is the table that contains the bitmasks for each character. The implementation here should work on all systems.

    The next function is: @@ -254,7 +254,7 @@ implementation here should work on all systems. is(const char* __low, const char* __high, mask* __vec) const throw() { while (__low < __high) - *__vec++ = (_M_table)[(unsigned char)(*__low++)]; + *__vec++ = (_M_table)[(unsigned char)(*__low++)]; return __high; }

    This function is similar; it copies the masks for all the characters @@ -267,16 +267,16 @@ from __low up until __high i scan_is(mask __m, const char* __low, const char* __high) const throw() { while (__low < __high && !this->is(__m, *__low)) - ++__low; + ++__low; return __low; } - + const char* ctype<char>:: scan_not(mask __m, const char* __low, const char* __high) const throw() { while (__low < __high && this->is(__m, *__low)) - ++__low; + ++__low; return __low; }

    Thread Safety

    The C++ library string functionality requires a couple of atomic @@ -312,7 +312,7 @@ type, and two functions.

    The type is _Atomic_word. Here is the version used on IRIX: 

     typedef long _Atomic_word;
-

    This type must be a signed integral type supporting atomic operations. +

    This type must be a signed integral type supporting atomic operations. If you're using the OS approach, use the same type used by your system's primitives. Otherwise, use the type for which your CPU provides atomic primitives. @@ -327,7 +327,7 @@ must be equivalent to those provided here, but using atomic operations: *__mem += __val; return __result; } - + static inline void __attribute__ ((__unused__)) __atomic_add (_Atomic_word* __mem, int __val) @@ -335,18 +335,18 @@ must be equivalent to those provided here, but using atomic operations: *__mem += __val; }

    Numeric Limits

    The C++ library requires information about the fundamental data types, -such as the minimum and maximum representable values of each type. +such as the minimum and maximum representable values of each type. You can define each of these values individually, but it is usually easiest just to indicate how many bits are used in each of the data types and let the library do the rest. For information about the macros to define, see the top of include/bits/std_limits.h. -

    If you need to define any macros, you can do so in os_defines.h. +

    If you need to define any macros, you can do so in os_defines.h. However, if all operating systems for your CPU are likely to use the same values, you can provide a CPU-specific file instead so that you -do not have to provide the same definitions for each operating system. +do not have to provide the same definitions for each operating system. To take that approach, create a new file called cpu_limits.h in your CPU configuration directory (see CPU). -

    Libtool

    The C++ library is compiled, archived and linked with libtool. +

    Libtool

    The C++ library is compiled, archived and linked with libtool. Explaining the full workings of libtool is beyond the scope of this document, but there are a few, particular bits that are necessary for porting. diff --git a/libstdc++-v3/doc/html/manual/intro.html b/libstdc++-v3/doc/html/manual/intro.html index 690722ffdf9..15091ef0834 100644 --- a/libstdc++-v3/doc/html/manual/intro.html +++ b/libstdc++-v3/doc/html/manual/intro.html @@ -5,5 +5,5 @@

    Prev The GNU C++ Library Next

    Part I.  Introduction - +

    Table of Contents

    1. Status
    Implementation Status
    C++ 1998/2003
    C++ 200x
    C++ TR1
    C++ TR 24733
    License
    The Code: GPL
    The Documentation: GPL, FDL
    Bugs
    Implementation Bugs
    Standard Bugs
    2. Setup
    Prerequisites
    Configure
    Make
    3. Using
    Command Options
    Headers
    Header Files
    Mixing Headers
    The C Headers and namespace std
    Precompiled Headers
    Macros
    Namespaces
    Available Namespaces
    namespace std
    Using Namespace Composition
    Linking
    Almost Nothing
    Finding Dynamic or Shared Libraries
    Concurrency
    Prerequisites
    Thread Safety
    Atomics
    IO
    Containers
    Exceptions
    Exception Safety
    Exception Neutrality
    Doing without
    Compatibility
    Debugging Support
    Using g++
    Debug Versions of Library Binary Files
    Memory Leak Hunting
    Using gdb
    Tracking uncaught exceptions
    Debug Mode
    Compile Time Checking
    Profile-based Performance Analysis
    Prev Up Next
    The GNU C++ Library Home Chapter 1. Status
    diff --git a/libstdc++-v3/doc/html/manual/io.html b/libstdc++-v3/doc/html/manual/io.html index 90dbc6c5271..65f598db241 100644 --- a/libstdc++-v3/doc/html/manual/io.html +++ b/libstdc++-v3/doc/html/manual/io.html @@ -1,9 +1,121 @@ -Part XI.  Input and Output
    Part XI.  +Chapter 13.  Input and Output
    Chapter 13.  Input and Output -
    Prev The GNU C++ Library Next

    Part XI.  +

    Prev Part II.  + Standard Contents + Next

    Chapter 13.  Input and Output - -

    Table of Contents

    24. Iostream Objects
    25. Stream Buffers
    Derived streambuf Classes
    Buffering
    26. Memory Based Streams
    Compatibility With strstream
    27. File Based Streams
    Copying a File
    Binary Input and Output
    28. Interacting with C
    Using FILE* and file descriptors
    Performance
    Prev Up Next
    C99 Home Chapter 24. Iostream Objects
    + +

    Table of Contents

    Iostream Objects
    Stream Buffers
    Derived streambuf Classes
    Buffering
    Memory Based Streams
    Compatibility With strstream
    File Based Streams
    Copying a File
    Binary Input and Output
    Interacting with C
    Using FILE* and file descriptors
    Performance

    Iostream Objects

    To minimize the time you have to wait on the compiler, it's good to + only include the headers you really need. Many people simply include + <iostream> when they don't need to -- and that can penalize + your runtime as well. Here are some tips on which header to use + for which situations, starting with the simplest. +

    <iosfwd> should be included whenever you simply + need the name of an I/O-related class, such as + "ofstream" or "basic_streambuf". Like the name + implies, these are forward declarations. (A word to all you fellow + old school programmers: trying to forward declare classes like + "class istream;" won't work. Look in the iosfwd header if + you'd like to know why.) For example, + 

    +    #include <iosfwd>
+
+    class MyClass
+    {
+	....
+	std::ifstream&   input_file;
+    };
+
+    extern std::ostream& operator<< (std::ostream&, MyClass&);
+

    <ios> declares the base classes for the entire + I/O stream hierarchy, std::ios_base and std::basic_ios<charT>, the + counting types std::streamoff and std::streamsize, the file + positioning type std::fpos, and the various manipulators like + std::hex, std::fixed, std::noshowbase, and so forth. +

    The ios_base class is what holds the format flags, the state flags, + and the functions which change them (setf(), width(), precision(), + etc). You can also store extra data and register callback functions + through ios_base, but that has been historically underused. Anything + which doesn't depend on the type of characters stored is consolidated + here. +

    The template class basic_ios is the highest template class in the + hierarchy; it is the first one depending on the character type, and + holds all general state associated with that type: the pointer to the + polymorphic stream buffer, the facet information, etc. +

    <streambuf> declares the template class + basic_streambuf, and two standard instantiations, streambuf and + wstreambuf. If you need to work with the vastly useful and capable + stream buffer classes, e.g., to create a new form of storage + transport, this header is the one to include. +

    <istream>/<ostream> are + the headers to include when you are using the >>/<< + interface, or any of the other abstract stream formatting functions. + For example, + 

    +    #include <istream>
+
+    std::ostream& operator<< (std::ostream& os, MyClass& c)
+    {
+       return os << c.data1() << c.data2();
+    }
+

    The std::istream and std::ostream classes are the abstract parents of + the various concrete implementations. If you are only using the + interfaces, then you only need to use the appropriate interface header. +

    <iomanip> provides "extractors and inserters + that alter information maintained by class ios_base and its derived + classes," such as std::setprecision and std::setw. If you need + to write expressions like os << setw(3); or + is >> setbase(8);, you must include <iomanip>. +

    <sstream>/<fstream> + declare the six stringstream and fstream classes. As they are the + standard concrete descendants of istream and ostream, you will already + know about them. +

    Finally, <iostream> provides the eight standard + global objects (cin, cout, etc). To do this correctly, this header + also provides the contents of the <istream> and <ostream> + headers, but nothing else. The contents of this header look like + 

    +    #include <ostream>
+    #include <istream>
+
+    namespace std
+    {
+	extern istream cin;
+	extern ostream cout;
+	....
+
+	// this is explained below
+	static ios_base::Init __foo;    // not its real name
+    }
+

    Now, the runtime penalty mentioned previously: the global objects + must be initialized before any of your own code uses them; this is + guaranteed by the standard. Like any other global object, they must + be initialized once and only once. This is typically done with a + construct like the one above, and the nested class ios_base::Init is + specified in the standard for just this reason. +

    How does it work? Because the header is included before any of your + code, the __foo object is constructed before any of + your objects. (Global objects are built in the order in which they + are declared, and destroyed in reverse order.) The first time the + constructor runs, the eight stream objects are set up. +

    The static keyword means that each object file compiled + from a source file containing <iostream> will have its own + private copy of __foo. There is no specified order + of construction across object files (it's one of those pesky NP + problems that make life so interesting), so one copy in each object + file means that the stream objects are guaranteed to be set up before + any of your code which uses them could run, thereby meeting the + requirements of the standard. +

    The penalty, of course, is that after the first copy of + __foo is constructed, all the others are just wasted + processor time. The time spent is merely for an increment-and-test + inside a function call, but over several dozen or hundreds of object + files, that time can add up. (It's not in a tight loop, either.) +

    The lesson? Only include <iostream> when you need to use one of + the standard objects in that source file; you'll pay less startup + time. Only include the header files you need to in general; your + compile times will go down when there's less parsing work to do. +

    Prev Up Next
    Interacting with C Home Stream Buffers
    diff --git a/libstdc++-v3/doc/html/manual/io_and_c.html b/libstdc++-v3/doc/html/manual/io_and_c.html index 33b5796ca27..f7a99e6ada0 100644 --- a/libstdc++-v3/doc/html/manual/io_and_c.html +++ b/libstdc++-v3/doc/html/manual/io_and_c.html @@ -1,11 +1,57 @@ -Chapter 28. Interacting with C
    Chapter 28. Interacting with C
    Prev Part XI.  +Interacting with C
    Interacting with C
    Prev Chapter 13.  Input and Output - Next

    Chapter 28. Interacting with C

    Table of Contents

    Using FILE* and file descriptors
    Performance

    Using FILE* and file descriptors

    - See the extensions for using +

    		 Next

    Interacting with C

    Using FILE* and file descriptors

    + See the extensions for using FILE and file descriptors with ofstream and ifstream. -

    Prev Up Next
    Binary Input and Output Home Performance
    +

    Performance

    + Pathetic Performance? Ditch C. +

    It sounds like a flame on C, but it isn't. Really. Calm down. + I'm just saying it to get your attention. +

    Because the C++ library includes the C library, both C-style and + C++-style I/O have to work at the same time. For example: + 

    +     #include <iostream>
+     #include <cstdio>
+
+     std::cout << "Hel";
+     std::printf ("lo, worl");
+     std::cout << "d!\n";
+

    This must do what you think it does. +

    Alert members of the audience will immediately notice that buffering + is going to make a hash of the output unless special steps are taken. +

    The special steps taken by libstdc++, at least for version 3.0, + involve doing very little buffering for the standard streams, leaving + most of the buffering to the underlying C library. (This kind of + thing is tricky to get right.) + The upside is that correctness is ensured. The downside is that + writing through cout can quite easily lead to awful + performance when the C++ I/O library is layered on top of the C I/O + library (as it is for 3.0 by default). Some patches have been applied + which improve the situation for 3.1. +

    However, the C and C++ standard streams only need to be kept in sync + when both libraries' facilities are in use. If your program only uses + C++ I/O, then there's no need to sync with the C streams. The right + thing to do in this case is to call + 

    +     #include any of the I/O headers such as ios, iostream, etc
+
+     std::ios::sync_with_stdio(false);
+

    You must do this before performing any I/O via the C++ stream objects. + Once you call this, the C++ streams will operate independently of the + (unused) C streams. For GCC 3.x, this means that cout and + company will become fully buffered on their own. +

    Note, by the way, that the synchronization requirement only applies to + the standard streams (cin, cout, + cerr, + clog, and their wide-character counterchapters). File stream + objects that you declare yourself have no such requirement and are fully + buffered. +

    Prev Up Next
    File Based Streams Home Chapter 14.  + Atomics + +
    diff --git a/libstdc++-v3/doc/html/manual/iostream_objects.html b/libstdc++-v3/doc/html/manual/iostream_objects.html deleted file mode 100644 index 1133edec3ab..00000000000 --- a/libstdc++-v3/doc/html/manual/iostream_objects.html +++ /dev/null @@ -1,119 +0,0 @@ - - -Chapter 24. Iostream Objects
    Chapter 24. Iostream Objects
    Prev Part XI.  - Input and Output - - Next

    Chapter 24. Iostream Objects

    To minimize the time you have to wait on the compiler, it's good to - only include the headers you really need. Many people simply include - <iostream> when they don't need to -- and that can penalize - your runtime as well. Here are some tips on which header to use - for which situations, starting with the simplest. -

    <iosfwd> should be included whenever you simply - need the name of an I/O-related class, such as - "ofstream" or "basic_streambuf". Like the name - implies, these are forward declarations. (A word to all you fellow - old school programmers: trying to forward declare classes like - "class istream;" won't work. Look in the iosfwd header if - you'd like to know why.) For example, - 

    -    #include <iosfwd>
-
-    class MyClass
-    {
-        ....
-        std::ifstream&   input_file;
-    };
-
-    extern std::ostream& operator<< (std::ostream&, MyClass&);
-

    <ios> declares the base classes for the entire - I/O stream hierarchy, std::ios_base and std::basic_ios<charT>, the - counting types std::streamoff and std::streamsize, the file - positioning type std::fpos, and the various manipulators like - std::hex, std::fixed, std::noshowbase, and so forth. -

    The ios_base class is what holds the format flags, the state flags, - and the functions which change them (setf(), width(), precision(), - etc). You can also store extra data and register callback functions - through ios_base, but that has been historically underused. Anything - which doesn't depend on the type of characters stored is consolidated - here. -

    The template class basic_ios is the highest template class in the - hierarchy; it is the first one depending on the character type, and - holds all general state associated with that type: the pointer to the - polymorphic stream buffer, the facet information, etc. -

    <streambuf> declares the template class - basic_streambuf, and two standard instantiations, streambuf and - wstreambuf. If you need to work with the vastly useful and capable - stream buffer classes, e.g., to create a new form of storage - transport, this header is the one to include. -

    <istream>/<ostream> are - the headers to include when you are using the >>/<< - interface, or any of the other abstract stream formatting functions. - For example, - 

    -    #include <istream>
-
-    std::ostream& operator<< (std::ostream& os, MyClass& c)
-    {
-       return os << c.data1() << c.data2();
-    }
-

    The std::istream and std::ostream classes are the abstract parents of - the various concrete implementations. If you are only using the - interfaces, then you only need to use the appropriate interface header. -

    <iomanip> provides "extractors and inserters - that alter information maintained by class ios_base and its derived - classes," such as std::setprecision and std::setw. If you need - to write expressions like os << setw(3); or - is >> setbase(8);, you must include <iomanip>. -

    <sstream>/<fstream> - declare the six stringstream and fstream classes. As they are the - standard concrete descendants of istream and ostream, you will already - know about them. -

    Finally, <iostream> provides the eight standard - global objects (cin, cout, etc). To do this correctly, this header - also provides the contents of the <istream> and <ostream> - headers, but nothing else. The contents of this header look like - 

    -    #include <ostream>
-    #include <istream>
-
-    namespace std
-    {
-        extern istream cin;
-        extern ostream cout;
-        ....
-
-        // this is explained below
-        static ios_base::Init __foo;    // not its real name
-    }
-

    Now, the runtime penalty mentioned previously: the global objects - must be initialized before any of your own code uses them; this is - guaranteed by the standard. Like any other global object, they must - be initialized once and only once. This is typically done with a - construct like the one above, and the nested class ios_base::Init is - specified in the standard for just this reason. -

    How does it work? Because the header is included before any of your - code, the __foo object is constructed before any of - your objects. (Global objects are built in the order in which they - are declared, and destroyed in reverse order.) The first time the - constructor runs, the eight stream objects are set up. -

    The static keyword means that each object file compiled - from a source file containing <iostream> will have its own - private copy of __foo. There is no specified order - of construction across object files (it's one of those pesky NP - problems that make life so interesting), so one copy in each object - file means that the stream objects are guaranteed to be set up before - any of your code which uses them could run, thereby meeting the - requirements of the standard. -

    The penalty, of course, is that after the first copy of - __foo is constructed, all the others are just wasted - processor time. The time spent is merely for an increment-and-test - inside a function call, but over several dozen or hundreds of object - files, that time can add up. (It's not in a tight loop, either.) -

    The lesson? Only include <iostream> when you need to use one of - the standard objects in that source file; you'll pay less startup - time. Only include the header files you need to in general; your - compile times will go down when there's less parsing work to do. -

    Prev Up Next
    Part XI.  - Input and Output - - Home Chapter 25. Stream Buffers
    diff --git a/libstdc++-v3/doc/html/manual/iterators.html b/libstdc++-v3/doc/html/manual/iterators.html index d9a932be228..6e29f5fcc94 100644 --- a/libstdc++-v3/doc/html/manual/iterators.html +++ b/libstdc++-v3/doc/html/manual/iterators.html @@ -1,9 +1,130 @@ -Part VIII.  Iterators
    Part VIII.  +Chapter 10.  Iterators
    Chapter 10.  Iterators -
    Prev The GNU C++ Library Next

    Part VIII.  +

    Prev Part II.  + Standard Contents + Next

    Chapter 10.  Iterators - -

    Table of Contents

    19. Predefined
    Iterators vs. Pointers
    One Past the End
    Prev Up Next
    bitset Home Chapter 19. Predefined
    + +

    Table of Contents

    Predefined
    Iterators vs. Pointers
    One Past the End

    Predefined

    Iterators vs. Pointers

    + The following +FAQ entry points out that +iterators are not implemented as pointers. They are a generalization +of pointers, but they are implemented in libstdc++ as separate +classes. +

    + Keeping that simple fact in mind as you design your code will + prevent a whole lot of difficult-to-understand bugs. +

    + You can think of it the other way 'round, even. Since iterators + are a generalization, that means + that pointers are + iterators, and that pointers can be used + whenever an iterator would be. All those functions in the + Algorithms sect1 of the Standard will work just as well on plain + arrays and their pointers. +

    + That doesn't mean that when you pass in a pointer, it gets + wrapped into some special delegating iterator-to-pointer class + with a layer of overhead. (If you think that's the case + anywhere, you don't understand templates to begin with...) Oh, + no; if you pass in a pointer, then the compiler will instantiate + that template using T* as a type, and good old high-speed + pointer arithmetic as its operations, so the resulting code will + be doing exactly the same things as it would be doing if you had + hand-coded it yourself (for the 273rd time). +

    + How much overhead is there when using an + iterator class? Very little. Most of the layering classes + contain nothing but typedefs, and typedefs are + "meta-information" that simply tell the compiler some + nicknames; they don't create code. That information gets passed + down through inheritance, so while the compiler has to do work + looking up all the names, your runtime code does not. (This has + been a prime concern from the beginning.) +

    One Past the End

    This starts off sounding complicated, but is actually very easy, + especially towards the end. Trust me. +

    Beginners usually have a little trouble understand the whole + 'past-the-end' thing, until they remember their early algebra classes + (see, they told you that stuff would come in handy!) and + the concept of half-open ranges. +

    First, some history, and a reminder of some of the funkier rules in + C and C++ for builtin arrays. The following rules have always been + true for both languages: +

    1. You can point anywhere in the array, or to the first element + past the end of the array. A pointer that points to one + past the end of the array is guaranteed to be as unique as a + pointer to somewhere inside the array, so that you can compare + such pointers safely. +

    2. You can only dereference a pointer that points into an array. + If your array pointer points outside the array -- even to just + one past the end -- and you dereference it, Bad Things happen. +

    3. Strictly speaking, simply pointing anywhere else invokes + undefined behavior. Most programs won't puke until such a + pointer is actually dereferenced, but the standards leave that + up to the platform. +

    The reason this past-the-end addressing was allowed is to make it + easy to write a loop to go over an entire array, e.g., + while (*d++ = *s++);. +

    So, when you think of two pointers delimiting an array, don't think + of them as indexing 0 through n-1. Think of them as boundary + markers: + 

    +
+   beginning            end
+     |                   |
+     |                   |               This is bad.  Always having to
+     |                   |               remember to add or subtract one.
+     |                   |               Off-by-one bugs very common here.
+     V                   V
+	array of N elements
+     |---|---|--...--|---|---|
+     | 0 | 1 |  ...  |N-2|N-1|
+     |---|---|--...--|---|---|
+
+     ^                       ^
+     |                       |
+     |                       |           This is good.  This is safe.  This
+     |                       |           is guaranteed to work.  Just don't
+     |                       |           dereference 'end'.
+   beginning                end
+
+

    See? Everything between the boundary markers is chapter of the array. + Simple. +

    Now think back to your junior-high school algebra course, when you + were learning how to draw graphs. Remember that a graph terminating + with a solid dot meant, "Everything up through this point," + and a graph terminating with an open dot meant, "Everything up + to, but not including, this point," respectively called closed + and open ranges? Remember how closed ranges were written with + brackets, [a,b], and open ranges were written with parentheses, + (a,b)? +

    The boundary markers for arrays describe a half-open range, + starting with (and including) the first element, and ending with (but + not including) the last element: [beginning,end). See, I + told you it would be simple in the end. +

    Iterators, and everything working with iterators, follows this same + time-honored tradition. A container's begin() method returns + an iterator referring to the first element, and its end() + method returns a past-the-end iterator, which is guaranteed to be + unique and comparable against any other iterator pointing into the + middle of the container. +

    Container constructors, container methods, and algorithms, all take + pairs of iterators describing a range of values on which to operate. + All of these ranges are half-open ranges, so you pass the beginning + iterator as the starting parameter, and the one-past-the-end iterator + as the finishing parameter. +

    This generalizes very well. You can operate on sub-ranges quite + easily this way; functions accepting a [first,last) range + don't know or care whether they are the boundaries of an entire {array, + sequence, container, whatever}, or whether they only enclose a few + elements from the center. This approach also makes zero-length + sequences very simple to recognize: if the two endpoints compare + equal, then the {array, sequence, container, whatever} is empty. +

    Just don't dereference end(). +

    Prev Up Next
    Interacting with C Home Chapter 11.  + Algorithms + +
    diff --git a/libstdc++-v3/doc/html/manual/license.html b/libstdc++-v3/doc/html/manual/license.html index f660ff378a0..04c971a059b 100644 --- a/libstdc++-v3/doc/html/manual/license.html +++ b/libstdc++-v3/doc/html/manual/license.html @@ -2,7 +2,7 @@ License
    License
    Prev Chapter 1. Status Next

    License

    There are two licenses affecting GNU libstdc++: one for the code, - and one for the documentation. + and one for the documentation.

    There is a license section in the FAQ regarding common questions. If you have more questions, ask the FSF or the gcc mailing list. @@ -94,7 +94,7 @@ requirements of the license of GCC.
    GNU Free Documentation License version 1.2. There are no Front-Cover Texts, no Back-Cover Texts, and no Invariant Sections. -

    +

    For documentation generated by doxygen or other automated tools via processing source code comments and markup, the original source code license applies to the generated files. Thus, the doxygen diff --git a/libstdc++-v3/doc/html/manual/locales.html b/libstdc++-v3/doc/html/manual/locales.html deleted file mode 100644 index 040f79f2103..00000000000 --- a/libstdc++-v3/doc/html/manual/locales.html +++ /dev/null @@ -1,428 +0,0 @@ - - -Chapter 14. Locales

    Chapter 14. Locales
    Prev Part VI.  - Localization - - Next

    Chapter 14. Locales

    Table of Contents

    locale
    Requirements
    Design
    Implementation
    Future

    locale

    -Describes the basic locale object, including nested -classes id, facet, and the reference-counted implementation object, -class _Impl. -

    Requirements

    -Class locale is non-templatized and has two distinct types nested -inside of it: -

    - -class facet -22.1.1.1.2 Class locale::facet - -

    -Facets actually implement locale functionality. For instance, a facet -called numpunct is the data object that can be used to query for the -thousands separator in the locale. -

    -Literally, a facet is strictly defined: -

    • - Containing the following public data member: -

      - static locale::id id; -

    • - Derived from another facet: -

      - class gnu_codecvt: public std::ctype<user-defined-type> -

    -Of interest in this class are the memory management options explicitly -specified as an argument to facet's constructor. Each constructor of a -facet class takes a std::size_t __refs argument: if __refs == 0, the -facet is deleted when the locale containing it is destroyed. If __refs -== 1, the facet is not destroyed, even when it is no longer -referenced. -

    - -class id -22.1.1.1.3 - Class locale::id - -

    -Provides an index for looking up specific facets. -

    Design

    -The major design challenge is fitting an object-orientated and -non-global locale design on top of POSIX and other relevant standards, -which include the Single Unix (nee X/Open.) -

    -Because C and earlier versions of POSIX fall down so completely, -portability is an issue. -

    Implementation

    Interacting with "C" locales

    • - `locale -a` displays available locales. - 

      -af_ZA
-ar_AE
-ar_AE.utf8
-ar_BH
-ar_BH.utf8
-ar_DZ
-ar_DZ.utf8
-ar_EG
-ar_EG.utf8
-ar_IN
-ar_IQ
-ar_IQ.utf8
-ar_JO
-ar_JO.utf8
-ar_KW
-ar_KW.utf8
-ar_LB
-ar_LB.utf8
-ar_LY
-ar_LY.utf8
-ar_MA
-ar_MA.utf8
-ar_OM
-ar_OM.utf8
-ar_QA
-ar_QA.utf8
-ar_SA
-ar_SA.utf8
-ar_SD
-ar_SD.utf8
-ar_SY
-ar_SY.utf8
-ar_TN
-ar_TN.utf8
-ar_YE
-ar_YE.utf8
-be_BY
-be_BY.utf8
-bg_BG
-bg_BG.utf8
-br_FR
-bs_BA
-C
-ca_ES
-ca_ES@euro
-ca_ES.utf8
-ca_ES.utf8@euro
-cs_CZ
-cs_CZ.utf8
-cy_GB
-da_DK
-da_DK.iso885915
-da_DK.utf8
-de_AT
-de_AT@euro
-de_AT.utf8
-de_AT.utf8@euro
-de_BE
-de_BE@euro
-de_BE.utf8
-de_BE.utf8@euro
-de_CH
-de_CH.utf8
-de_DE
-de_DE@euro
-de_DE.utf8
-de_DE.utf8@euro
-de_LU
-de_LU@euro
-de_LU.utf8
-de_LU.utf8@euro
-el_GR
-el_GR.utf8
-en_AU
-en_AU.utf8
-en_BW
-en_BW.utf8
-en_CA
-en_CA.utf8
-en_DK
-en_DK.utf8
-en_GB
-en_GB.iso885915
-en_GB.utf8
-en_HK
-en_HK.utf8
-en_IE
-en_IE@euro
-en_IE.utf8
-en_IE.utf8@euro
-en_IN
-en_NZ
-en_NZ.utf8
-en_PH
-en_PH.utf8
-en_SG
-en_SG.utf8
-en_US
-en_US.iso885915
-en_US.utf8
-en_ZA
-en_ZA.utf8
-en_ZW
-en_ZW.utf8
-es_AR
-es_AR.utf8
-es_BO
-es_BO.utf8
-es_CL
-es_CL.utf8
-es_CO
-es_CO.utf8
-es_CR
-es_CR.utf8
-es_DO
-es_DO.utf8
-es_EC
-es_EC.utf8
-es_ES
-es_ES@euro
-es_ES.utf8
-es_ES.utf8@euro
-es_GT
-es_GT.utf8
-es_HN
-es_HN.utf8
-es_MX
-es_MX.utf8
-es_NI
-es_NI.utf8
-es_PA
-es_PA.utf8
-es_PE
-es_PE.utf8
-es_PR
-es_PR.utf8
-es_PY
-es_PY.utf8
-es_SV
-es_SV.utf8
-es_US
-es_US.utf8
-es_UY
-es_UY.utf8
-es_VE
-es_VE.utf8
-et_EE
-et_EE.utf8
-eu_ES
-eu_ES@euro
-eu_ES.utf8
-eu_ES.utf8@euro
-fa_IR
-fi_FI
-fi_FI@euro
-fi_FI.utf8
-fi_FI.utf8@euro
-fo_FO
-fo_FO.utf8
-fr_BE
-fr_BE@euro
-fr_BE.utf8
-fr_BE.utf8@euro
-fr_CA
-fr_CA.utf8
-fr_CH
-fr_CH.utf8
-fr_FR
-fr_FR@euro
-fr_FR.utf8
-fr_FR.utf8@euro
-fr_LU
-fr_LU@euro
-fr_LU.utf8
-fr_LU.utf8@euro
-ga_IE
-ga_IE@euro
-ga_IE.utf8
-ga_IE.utf8@euro
-gl_ES
-gl_ES@euro
-gl_ES.utf8
-gl_ES.utf8@euro
-gv_GB
-gv_GB.utf8
-he_IL
-he_IL.utf8
-hi_IN
-hr_HR
-hr_HR.utf8
-hu_HU
-hu_HU.utf8
-id_ID
-id_ID.utf8
-is_IS
-is_IS.utf8
-it_CH
-it_CH.utf8
-it_IT
-it_IT@euro
-it_IT.utf8
-it_IT.utf8@euro
-iw_IL
-iw_IL.utf8
-ja_JP.eucjp
-ja_JP.utf8
-ka_GE
-kl_GL
-kl_GL.utf8
-ko_KR.euckr
-ko_KR.utf8
-kw_GB
-kw_GB.utf8
-lt_LT
-lt_LT.utf8
-lv_LV
-lv_LV.utf8
-mi_NZ
-mk_MK
-mk_MK.utf8
-mr_IN
-ms_MY
-ms_MY.utf8
-mt_MT
-mt_MT.utf8
-nl_BE
-nl_BE@euro
-nl_BE.utf8
-nl_BE.utf8@euro
-nl_NL
-nl_NL@euro
-nl_NL.utf8
-nl_NL.utf8@euro
-nn_NO
-nn_NO.utf8
-no_NO
-no_NO.utf8
-oc_FR
-pl_PL
-pl_PL.utf8
-POSIX
-pt_BR
-pt_BR.utf8
-pt_PT
-pt_PT@euro
-pt_PT.utf8
-pt_PT.utf8@euro
-ro_RO
-ro_RO.utf8
-ru_RU
-ru_RU.koi8r
-ru_RU.utf8
-ru_UA
-ru_UA.utf8
-se_NO
-sk_SK
-sk_SK.utf8
-sl_SI
-sl_SI.utf8
-sq_AL
-sq_AL.utf8
-sr_YU
-sr_YU@cyrillic
-sr_YU.utf8
-sr_YU.utf8@cyrillic
-sv_FI
-sv_FI@euro
-sv_FI.utf8
-sv_FI.utf8@euro
-sv_SE
-sv_SE.iso885915
-sv_SE.utf8
-ta_IN
-te_IN
-tg_TJ
-th_TH
-th_TH.utf8
-tl_PH
-tr_TR
-tr_TR.utf8
-uk_UA
-uk_UA.utf8
-ur_PK
-uz_UZ
-vi_VN
-vi_VN.tcvn
-wa_BE
-wa_BE@euro
-yi_US
-zh_CN
-zh_CN.gb18030
-zh_CN.gbk
-zh_CN.utf8
-zh_HK
-zh_HK.utf8
-zh_TW
-zh_TW.euctw
-zh_TW.utf8
-

    • - `locale` displays environmental variables that - impact how locale("") will be deduced. - 

      -LANG=en_US
-LC_CTYPE="en_US"
-LC_NUMERIC="en_US"
-LC_TIME="en_US"
-LC_COLLATE="en_US"
-LC_MONETARY="en_US"
-LC_MESSAGES="en_US"
-LC_PAPER="en_US"
-LC_NAME="en_US"
-LC_ADDRESS="en_US"
-LC_TELEPHONE="en_US"
-LC_MEASUREMENT="en_US"
-LC_IDENTIFICATION="en_US"
-LC_ALL=
-

    -From Josuttis, p. 697-698, which says, that "there is only *one* -relation (of the C++ locale mechanism) to the C locale mechanism: the -global C locale is modified if a named C++ locale object is set as the -global locale" (emphasis Paolo), that is: -

    std::locale::global(std::locale(""));

    affects the C functions as if the following call was made:

    std::setlocale(LC_ALL, "");

    - On the other hand, there is *no* vice versa, that is, calling - setlocale has *no* whatsoever on the C++ locale mechanism, in - particular on the working of locale(""), which constructs the locale - object from the environment of the running program, that is, in - practice, the set of LC_ALL, LANG, etc. variable of the shell. -

    Future

    • - Locale initialization: at what point does _S_classic, _S_global - get initialized? Can named locales assume this initialization - has already taken place? -

    • - Document how named locales error check when filling data - members. I.e., a fr_FR locale that doesn't have - numpunct::truename(): does it use "true"? Or is it a blank - string? What's the convention? -

    • - Explain how locale aliasing happens. When does "de_DE" use "de" - information? What is the rule for locales composed of just an - ISO language code (say, "de") and locales with both an ISO - language code and ISO country code (say, "de_DE"). -

    • - What should non-required facet instantiations do? If the - generic implementation is provided, then how to end-users - provide specializations? -

    Bibliography

    - The GNU C Library - . Roland McGrath. Ulrich Drepper. Copyright © 2007 FSF. Chapters 6 Character Set Handling and 7 Locales and Internationalization.

    - Correspondence - . Ulrich Drepper. Copyright © 2002 .

    - ISO/IEC 14882:1998 Programming languages - C++ - . Copyright © 1998 ISO.

    - ISO/IEC 9899:1999 Programming languages - C - . Copyright © 1999 ISO.

    - The Open Group Base Specifications, Issue 6 (IEEE Std. 1003.1-2004) - . Copyright © 1999 - The Open Group/The Institute of Electrical and Electronics Engineers, Inc.. - - - .

    - The C++ Programming Language, Special Edition - . Bjarne Stroustrup. Copyright © 2000 Addison Wesley, Inc.. Appendix D. - Addison Wesley - .

    - Standard C++ IOStreams and Locales - . - Advanced Programmer's Guide and Reference - . Angelika Langer. Klaus Kreft. Copyright © 2000 Addison Wesley Longman, Inc.. - Addison Wesley Longman - .

    Prev Up Next
    Part VI.  - Localization - - Home Chapter 15. Facets aka Categories
    diff --git a/libstdc++-v3/doc/html/manual/localization.html b/libstdc++-v3/doc/html/manual/localization.html index 76d7c37db95..a1f30163645 100644 --- a/libstdc++-v3/doc/html/manual/localization.html +++ b/libstdc++-v3/doc/html/manual/localization.html @@ -1,9 +1,439 @@ -Part VI.  Localization
    Part VI.  +Chapter 8.  Localization
    Chapter 8.  Localization -
    Prev The GNU C++ Library Next

    Part VI.  +

    Prev Part II.  + Standard Contents + Next

    Chapter 8.  Localization - -

    Table of Contents

    14. Locales
    locale
    Requirements
    Design
    Implementation
    Future
    15. Facets aka Categories
    ctype
    Implementation
    Future
    codecvt
    Requirements
    Design
    Implementation
    Use
    Future
    messages
    Requirements
    Design
    Implementation
    Use
    Future
    Prev Up Next
    CString (MFC) Home Chapter 14. Locales
    + +

    Table of Contents

    Locales
    locale
    Facets
    ctype
    codecvt
    messages

    Locales

    locale

    +Describes the basic locale object, including nested +classes id, facet, and the reference-counted implementation object, +class _Impl. +

    Requirements

    +Class locale is non-templatized and has two distinct types nested +inside of it: +

    + +class facet +22.1.1.1.2 Class locale::facet + +

    +Facets actually implement locale functionality. For instance, a facet +called numpunct is the data object that can be used to query for the +thousands separator in the locale. +

    +Literally, a facet is strictly defined: +

    • + Containing the following public data member: +

      + static locale::id id; +

    • + Derived from another facet: +

      + class gnu_codecvt: public std::ctype<user-defined-type> +

    +Of interest in this class are the memory management options explicitly +specified as an argument to facet's constructor. Each constructor of a +facet class takes a std::size_t __refs argument: if __refs == 0, the +facet is deleted when the locale containing it is destroyed. If __refs +== 1, the facet is not destroyed, even when it is no longer +referenced. +

    + +class id +22.1.1.1.3 - Class locale::id + +

    +Provides an index for looking up specific facets. +

    Design

    +The major design challenge is fitting an object-orientated and +non-global locale design on top of POSIX and other relevant standards, +which include the Single Unix (nee X/Open.) +

    +Because C and earlier versions of POSIX fall down so completely, +portability is an issue. +

    Implementation

    Interacting with "C" locales

    • + `locale -a` displays available locales. + 

      +af_ZA
+ar_AE
+ar_AE.utf8
+ar_BH
+ar_BH.utf8
+ar_DZ
+ar_DZ.utf8
+ar_EG
+ar_EG.utf8
+ar_IN
+ar_IQ
+ar_IQ.utf8
+ar_JO
+ar_JO.utf8
+ar_KW
+ar_KW.utf8
+ar_LB
+ar_LB.utf8
+ar_LY
+ar_LY.utf8
+ar_MA
+ar_MA.utf8
+ar_OM
+ar_OM.utf8
+ar_QA
+ar_QA.utf8
+ar_SA
+ar_SA.utf8
+ar_SD
+ar_SD.utf8
+ar_SY
+ar_SY.utf8
+ar_TN
+ar_TN.utf8
+ar_YE
+ar_YE.utf8
+be_BY
+be_BY.utf8
+bg_BG
+bg_BG.utf8
+br_FR
+bs_BA
+C
+ca_ES
+ca_ES@euro
+ca_ES.utf8
+ca_ES.utf8@euro
+cs_CZ
+cs_CZ.utf8
+cy_GB
+da_DK
+da_DK.iso885915
+da_DK.utf8
+de_AT
+de_AT@euro
+de_AT.utf8
+de_AT.utf8@euro
+de_BE
+de_BE@euro
+de_BE.utf8
+de_BE.utf8@euro
+de_CH
+de_CH.utf8
+de_DE
+de_DE@euro
+de_DE.utf8
+de_DE.utf8@euro
+de_LU
+de_LU@euro
+de_LU.utf8
+de_LU.utf8@euro
+el_GR
+el_GR.utf8
+en_AU
+en_AU.utf8
+en_BW
+en_BW.utf8
+en_CA
+en_CA.utf8
+en_DK
+en_DK.utf8
+en_GB
+en_GB.iso885915
+en_GB.utf8
+en_HK
+en_HK.utf8
+en_IE
+en_IE@euro
+en_IE.utf8
+en_IE.utf8@euro
+en_IN
+en_NZ
+en_NZ.utf8
+en_PH
+en_PH.utf8
+en_SG
+en_SG.utf8
+en_US
+en_US.iso885915
+en_US.utf8
+en_ZA
+en_ZA.utf8
+en_ZW
+en_ZW.utf8
+es_AR
+es_AR.utf8
+es_BO
+es_BO.utf8
+es_CL
+es_CL.utf8
+es_CO
+es_CO.utf8
+es_CR
+es_CR.utf8
+es_DO
+es_DO.utf8
+es_EC
+es_EC.utf8
+es_ES
+es_ES@euro
+es_ES.utf8
+es_ES.utf8@euro
+es_GT
+es_GT.utf8
+es_HN
+es_HN.utf8
+es_MX
+es_MX.utf8
+es_NI
+es_NI.utf8
+es_PA
+es_PA.utf8
+es_PE
+es_PE.utf8
+es_PR
+es_PR.utf8
+es_PY
+es_PY.utf8
+es_SV
+es_SV.utf8
+es_US
+es_US.utf8
+es_UY
+es_UY.utf8
+es_VE
+es_VE.utf8
+et_EE
+et_EE.utf8
+eu_ES
+eu_ES@euro
+eu_ES.utf8
+eu_ES.utf8@euro
+fa_IR
+fi_FI
+fi_FI@euro
+fi_FI.utf8
+fi_FI.utf8@euro
+fo_FO
+fo_FO.utf8
+fr_BE
+fr_BE@euro
+fr_BE.utf8
+fr_BE.utf8@euro
+fr_CA
+fr_CA.utf8
+fr_CH
+fr_CH.utf8
+fr_FR
+fr_FR@euro
+fr_FR.utf8
+fr_FR.utf8@euro
+fr_LU
+fr_LU@euro
+fr_LU.utf8
+fr_LU.utf8@euro
+ga_IE
+ga_IE@euro
+ga_IE.utf8
+ga_IE.utf8@euro
+gl_ES
+gl_ES@euro
+gl_ES.utf8
+gl_ES.utf8@euro
+gv_GB
+gv_GB.utf8
+he_IL
+he_IL.utf8
+hi_IN
+hr_HR
+hr_HR.utf8
+hu_HU
+hu_HU.utf8
+id_ID
+id_ID.utf8
+is_IS
+is_IS.utf8
+it_CH
+it_CH.utf8
+it_IT
+it_IT@euro
+it_IT.utf8
+it_IT.utf8@euro
+iw_IL
+iw_IL.utf8
+ja_JP.eucjp
+ja_JP.utf8
+ka_GE
+kl_GL
+kl_GL.utf8
+ko_KR.euckr
+ko_KR.utf8
+kw_GB
+kw_GB.utf8
+lt_LT
+lt_LT.utf8
+lv_LV
+lv_LV.utf8
+mi_NZ
+mk_MK
+mk_MK.utf8
+mr_IN
+ms_MY
+ms_MY.utf8
+mt_MT
+mt_MT.utf8
+nl_BE
+nl_BE@euro
+nl_BE.utf8
+nl_BE.utf8@euro
+nl_NL
+nl_NL@euro
+nl_NL.utf8
+nl_NL.utf8@euro
+nn_NO
+nn_NO.utf8
+no_NO
+no_NO.utf8
+oc_FR
+pl_PL
+pl_PL.utf8
+POSIX
+pt_BR
+pt_BR.utf8
+pt_PT
+pt_PT@euro
+pt_PT.utf8
+pt_PT.utf8@euro
+ro_RO
+ro_RO.utf8
+ru_RU
+ru_RU.koi8r
+ru_RU.utf8
+ru_UA
+ru_UA.utf8
+se_NO
+sk_SK
+sk_SK.utf8
+sl_SI
+sl_SI.utf8
+sq_AL
+sq_AL.utf8
+sr_YU
+sr_YU@cyrillic
+sr_YU.utf8
+sr_YU.utf8@cyrillic
+sv_FI
+sv_FI@euro
+sv_FI.utf8
+sv_FI.utf8@euro
+sv_SE
+sv_SE.iso885915
+sv_SE.utf8
+ta_IN
+te_IN
+tg_TJ
+th_TH
+th_TH.utf8
+tl_PH
+tr_TR
+tr_TR.utf8
+uk_UA
+uk_UA.utf8
+ur_PK
+uz_UZ
+vi_VN
+vi_VN.tcvn
+wa_BE
+wa_BE@euro
+yi_US
+zh_CN
+zh_CN.gb18030
+zh_CN.gbk
+zh_CN.utf8
+zh_HK
+zh_HK.utf8
+zh_TW
+zh_TW.euctw
+zh_TW.utf8
+

    • + `locale` displays environmental variables that + impact how locale("") will be deduced. + 

      +LANG=en_US
+LC_CTYPE="en_US"
+LC_NUMERIC="en_US"
+LC_TIME="en_US"
+LC_COLLATE="en_US"
+LC_MONETARY="en_US"
+LC_MESSAGES="en_US"
+LC_PAPER="en_US"
+LC_NAME="en_US"
+LC_ADDRESS="en_US"
+LC_TELEPHONE="en_US"
+LC_MEASUREMENT="en_US"
+LC_IDENTIFICATION="en_US"
+LC_ALL=
+

    +From Josuttis, p. 697-698, which says, that "there is only *one* +relation (of the C++ locale mechanism) to the C locale mechanism: the +global C locale is modified if a named C++ locale object is set as the +global locale" (emphasis Paolo), that is: +

    std::locale::global(std::locale(""));

    affects the C functions as if the following call was made:

    std::setlocale(LC_ALL, "");

    + On the other hand, there is *no* vice versa, that is, calling + setlocale has *no* whatsoever on the C++ locale mechanism, in + particular on the working of locale(""), which constructs the locale + object from the environment of the running program, that is, in + practice, the set of LC_ALL, LANG, etc. variable of the shell. +

    Future

    • + Locale initialization: at what point does _S_classic, _S_global + get initialized? Can named locales assume this initialization + has already taken place? +

    • + Document how named locales error check when filling data + members. I.e., a fr_FR locale that doesn't have + numpunct::truename(): does it use "true"? Or is it a blank + string? What's the convention? +

    • + Explain how locale aliasing happens. When does "de_DE" use "de" + information? What is the rule for locales composed of just an + ISO language code (say, "de") and locales with both an ISO + language code and ISO country code (say, "de_DE"). +

    • + What should non-required facet instantiations do? If the + generic implementation is provided, then how to end-users + provide specializations? +

    Bibliography

    + The GNU C Library + . Roland McGrath. Ulrich Drepper. Copyright © 2007 FSF. + Chapters 6 Character Set Handling and 7 Locales and + Internationalization + .

    + Correspondence + . Ulrich Drepper. Copyright © 2002 .

    + ISO/IEC 14882:1998 Programming languages - C++ + . Copyright © 1998 ISO.

    + ISO/IEC 9899:1999 Programming languages - C + . Copyright © 1999 ISO.

    + + + System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008) + + + . Copyright © 2008 + The Open Group/The Institute of Electrical and Electronics + Engineers, Inc. + .

    + The C++ Programming Language, Special Edition + . Bjarne Stroustrup. Copyright © 2000 Addison Wesley, Inc.. Appendix D. + Addison Wesley + .

    + Standard C++ IOStreams and Locales + . + Advanced Programmer's Guide and Reference + . Angelika Langer. Klaus Kreft. Copyright © 2000 Addison Wesley Longman, Inc.. + Addison Wesley Longman + .

    Prev Up Next
    Chapter 7.  + Strings + + Home Facets
    diff --git a/libstdc++-v3/doc/html/manual/memory.html b/libstdc++-v3/doc/html/manual/memory.html index 18db2d502bf..82ef8c7125f 100644 --- a/libstdc++-v3/doc/html/manual/memory.html +++ b/libstdc++-v3/doc/html/manual/memory.html @@ -1,15 +1,15 @@ -Chapter 11. Memory
    Chapter 11. Memory
    Prev Part IV.  +Memory
    Memory
    Prev Chapter 6.  Utilities - Next

    Chapter 11. Memory

    Table of Contents

    Allocators
    Requirements
    Design Issues
    Implementation
    Using a Specific Allocator
    Custom Allocators
    Extension Allocators
    auto_ptr
    Limitations
    Use in Containers
    shared_ptr
    Requirements
    Design Issues
    Implementation
    Use
    Acknowledgments

    +

    		 Next

    Memory

    Memory contains three general areas. First, function and operator calls via new and delete operator or member function calls. Second, allocation via allocator. And finally, smart pointer and intelligent pointer abstractions. -

    Allocators

    +

    Allocators

    Memory management for Standard Library entities is encapsulated in a class template called allocator. The allocator abstraction is used throughout the @@ -17,7 +17,7 @@ algorithms, and parts of iostreams. This class, and base classes of it, are the superset of available free store (“heap”) management classes. -

    Requirements

    +

    Requirements

    The C++ standard only gives a few directives in this area:

    • When you add elements to a container, and the container must @@ -32,9 +32,9 @@ container-of-T is allocator<T>.

    • The interface of the allocator<T> class is - extremely simple. It has about 20 public declarations (nested - typedefs, member functions, etc), but the two which concern us most - are: + extremely simple. It has about 20 public declarations (nested + typedefs, member functions, etc), but the two which concern us most + are: 

       	 T*    allocate   (size_type n, const void* hint = 0);
 	 void  deallocate (T* p, size_type n);
@@ -43,18 +43,18 @@
 	 functions is a count of the number of
 	 T's to allocate space for, not their
 	 total size.
-	 (This is a simplification; the real signatures use nested typedefs.)  
+	 (This is a simplification; the real signatures use nested typedefs.)

    • The storage is obtained by calling ::operator new, but it is unspecified when or how - often this function is called. The use of the + often this function is called. The use of the hint is unspecified, but intended as an aid to locality if an implementation so desires. [20.4.1.1]/6 -

    +

    Complete details can be found in the C++ standard, look in [20.4 Memory]. -

    Design Issues

    +

    Design Issues

    The easiest way of fulfilling the requirements is to call operator new each time a container needs memory, and to call operator delete each time @@ -67,7 +67,7 @@ while __gnu_cxx::malloc_allocator implements much the same thing, only with the C language functions std::malloc and free. -

    +

    Another approach is to use intelligence within the allocator class to cache allocations. This extra machinery can take a variety of forms: a bitmap index, an index into an exponentially increasing @@ -93,33 +93,33 @@ or loading and unloading shared objects in memory. As such, using caching allocators on systems that do not support abi::__cxa_atexit is not recommended. -

    Implementation

    Interface Design

    +

    Implementation

    Interface Design

    The only allocator interface that is supported is the standard C++ interface. As such, all STL containers have been adjusted, and all external allocators have - been modified to support this change. -

    + been modified to support this change. +

    The class allocator just has typedef, constructor, and rebind members. It inherits from one of the high-speed extension allocators, covered below. Thus, all allocation and deallocation depends on the base class. -

    +

    The base class that allocator is derived from may not be user-configurable. -

    Selecting Default Allocation Policy

    +

    Selecting Default Allocation Policy

    It's difficult to pick an allocation strategy that will provide maximum utility, without excessively penalizing some behavior. In fact, it's difficult just deciding which typical actions to measure for speed. -

    +

    Three synthetic benchmarks have been created that provide data that is used to compare different C++ allocators. These tests are:

    1. - Insertion. + Insertion.

      Over multiple iterations, various STL container objects have elements inserted to some maximum amount. A variety - of allocators are tested. + of allocators are tested. Test source for sequence and associative containers. @@ -128,22 +128,22 @@

      This test shows the ability of the allocator to reclaim memory on a per-thread basis, as well as measuring thread contention - for memory resources. - Test source + for memory resources. + Test source here.

    2. A threaded producer/consumer model.

      Test source for sequence - and + and associative containers.

    The current default choice for allocator is __gnu_cxx::new_allocator. -

    Disabling Memory Caching

    +

    Disabling Memory Caching

    In use, allocator may allocate and deallocate using implementation-specified strategies and heuristics. Because of this, every call to an allocator object's @@ -151,13 +151,13 @@ call the global operator new. This situation is also duplicated for calls to the deallocate member function. -

    - This can be confusing. -

    +

    + This can be confusing. +

    In particular, this can make debugging memory errors more difficult, especially when using third party tools like valgrind or debug versions of new. -

    +

    There are various ways to solve this problem. One would be to use a custom allocator that just called operators new and delete @@ -179,7 +179,7 @@ environment, it likely means that you linked against objects built against the older library (objects which might still using the cached allocations...). -

    Using a Specific Allocator

    +

    Using a Specific Allocator

    You can specify different memory management schemes on a per-container basis, by overriding the default Allocator template parameter. For example, an easy @@ -190,16 +190,16 @@ Likewise, a debugging form of whichever allocator is currently in use: 

         std::deque <int, __gnu_cxx::debug_allocator<std::allocator<int> > >  debug_deque;
-

    Custom Allocators

    +

    Custom Allocators

    Writing a portable C++ allocator would dictate that the interface would look much like the one specified for allocator. Additional member functions, but not subtractions, would be permissible. -

    +

    Probably the best place to start would be to copy one of the - extension allocators: say a simple one like + extension allocators: say a simple one like new_allocator. -

    Extension Allocators

    +

    Extension Allocators

    Several other allocators are provided as part of this implementation. The location of the extension allocators and their names have changed, but in all cases, functionality is @@ -237,7 +237,7 @@ startup. For usage examples, please consult the testsuite.

  • debug_allocator -

    +

    A wrapper around an arbitrary allocator A. It passes on slightly increased size requests to A, and uses the extra memory to store size information. When a pointer is passed @@ -246,13 +246,13 @@ guarantee they match.

  • throw_allocator -

    +

    Includes memory tracking and marking abilities as well as hooks for throwing exceptions at configurable intervals (including random, - all, none). + all, none).

  • __pool_alloc -

    +

    A high-performance, single pool allocator. The reusable memory is shared among identical instantiations of this type. It calls through ::operator new to @@ -261,7 +261,7 @@ size, then the pool is bypassed, and the allocate/deallocate request is passed to ::operator new directly. -

    +

    Older versions of this class take a boolean template parameter, called thr, and an integer template parameter, called inst. @@ -308,39 +308,422 @@ A high-performance allocator that uses a bit-map to keep track of the used and unused memory locations. It has its own documentation, found here. -

    • Bibliography

    - ISO/IEC 14882:1998 Programming languages - C++ +

    Bibliography

    + ISO/IEC 14882:1998 Programming languages - C++ . isoc++_1998 - 20.4 Memory.

    The Standard Librarian: What Are Allocators Good - . - austernm - Matt Austern. - C/C++ Users Journal - . - + 20.4 Memory.

    + + + The Standard Librarian: What Are Allocators Good For? + - .

    The Hoard Memory Allocator. - emeryb - Emery Berger. + . Matt Austern. + C/C++ Users Journal + .

    + + The Hoard Memory Allocator + - .

    Reconsidering Custom Memory Allocation. - bergerzorn - Emery Berger. Ben Zorn. Kathryn McKinley. Copyright © 2002 OOPSLA. + . Emery Berger.

    + + Reconsidering Custom Memory Allocation + - .

    Allocator Types. - kreftlanger - Klaus Kreft. Angelika Langer. - C/C++ Users Journal - . + . Emery Berger. Ben Zorn. Kathryn McKinley. Copyright © 2002 OOPSLA.

    + + Allocator Types + - .

    The C++ Programming Language. - tcpl - Bjarne Stroustrup. Copyright © 2000 . 19.4 Allocators. + . Klaus Kreft. Angelika Langer. + C/C++ Users Journal + .

    The C++ Programming Language. Bjarne Stroustrup. Copyright © 2000 . 19.4 Allocators. Addison Wesley - .

    Yalloc: A Recycling C++ Allocator. - yenf - Felix Yen. Copyright © .

    Prev Up Next
    Chapter 10. Pairs Home auto_ptr
    + .

    Yalloc: A Recycling C++ Allocator. Felix Yen.

    auto_ptr

    Limitations

    Explaining all of the fun and delicious things that can + happen with misuse of the auto_ptr class + template (called AP here) would take some + time. Suffice it to say that the use of AP + safely in the presence of copying has some subtleties. +

    + The AP class is a really + nifty idea for a smart pointer, but it is one of the dumbest of + all the smart pointers -- and that's fine. +

    + AP is not meant to be a supersmart solution to all resource + leaks everywhere. Neither is it meant to be an effective form + of garbage collection (although it can help, a little bit). + And it can notbe used for arrays! +

    + AP is meant to prevent nasty leaks in the + presence of exceptions. That's all. This + code is AP-friendly: + 

    +    // Not a recommend naming scheme, but good for web-based FAQs.
+    typedef std::auto_ptr<MyClass>  APMC;
+
+    extern function_taking_MyClass_pointer (MyClass*);
+    extern some_throwable_function ();
+
+    void func (int data)
+    {
+	APMC  ap (new MyClass(data));
+
+	some_throwable_function();   // this will throw an exception
+
+	function_taking_MyClass_pointer (ap.get());
+    }
+

    When an exception gets thrown, the instance of MyClass that's + been created on the heap will be delete'd as the stack is + unwound past func(). +

    Changing that code as follows is not AP-friendly: + 

    +	APMC  ap (new MyClass[22]);
+

    You will get the same problems as you would without the use + of AP: + 

    +	char*  array = new char[10];       // array new...
+	...
+	delete array;                      // ...but single-object delete
+

    + AP cannot tell whether the pointer you've passed at creation points + to one or many things. If it points to many things, you are about + to die. AP is trivial to write, however, so you could write your + own auto_array_ptr for that situation (in fact, this has + been done many times; check the mailing lists, Usenet, Boost, etc). +

    Use in Containers

    +

    All of the containers + described in the standard library require their contained types + to have, among other things, a copy constructor like this: + 

    +    struct My_Type
+    {
+	My_Type (My_Type const&);
+    };
+

    + Note the const keyword; the object being copied shouldn't change. + The template class auto_ptr (called AP here) does not + meet this requirement. Creating a new AP by copying an existing + one transfers ownership of the pointed-to object, which means that + the AP being copied must change, which in turn means that the + copy ctors of AP do not take const objects. +

    + The resulting rule is simple: Never ever use a + container of auto_ptr objects. The standard says that + “undefined” behavior is the result, but it is + guaranteed to be messy. +

    + To prevent you from doing this to yourself, the + concept checks built + in to this implementation will issue an error if you try to + compile code like this: + 

    +    #include <vector>
+    #include <memory>
+
+    void f()
+    {
+	std::vector< std::auto_ptr<int> >   vec_ap_int;
+    }
+

    +Should you try this with the checks enabled, you will see an error. +

    shared_ptr

    +The shared_ptr class template stores a pointer, usually obtained via new, +and implements shared ownership semantics. +

    Requirements

    +

    + The standard deliberately doesn't require a reference-counted + implementation, allowing other techniques such as a + circular-linked-list. +

    + At the time of writing the C++0x working paper doesn't mention how + threads affect shared_ptr, but it is likely to follow the existing + practice set by boost::shared_ptr. The + shared_ptr in libstdc++ is derived from Boost's, so the same rules + apply. +

    +

    Design Issues

    +The shared_ptr code is kindly donated to GCC by the Boost +project and the original authors of the code. The basic design and +algorithms are from Boost, the notes below describe details specific to +the GCC implementation. Names have been uglified in this implementation, +but the design should be recognisable to anyone familiar with the Boost +1.32 shared_ptr. +

    +The basic design is an abstract base class, _Sp_counted_base that +does the reference-counting and calls virtual functions when the count +drops to zero. +Derived classes override those functions to destroy resources in a context +where the correct dynamic type is known. This is an application of the +technique known as type erasure. +

    Implementation

    Class Hierarchy

    +A shared_ptr<T> contains a pointer of +type T* and an object of type +__shared_count. The shared_count contains a +pointer of type _Sp_counted_base* which points to the +object that maintains the reference-counts and destroys the managed +resource. +

    _Sp_counted_base<Lp>

    +The base of the hierarchy is parameterized on the lock policy alone. +_Sp_counted_base doesn't depend on the type of pointer being managed, +it only maintains the reference counts and calls virtual functions when +the counts drop to zero. The managed object is destroyed when the last +strong reference is dropped, but the _Sp_counted_base itself must exist +until the last weak reference is dropped. +

    _Sp_counted_base_impl<Ptr, Deleter, Lp>

    +Inherits from _Sp_counted_base and stores a pointer of type Ptr +and a deleter of type Deleter. _Sp_deleter is +used when the user doesn't supply a custom deleter. Unlike Boost's, this +default deleter is not "checked" because GCC already issues a warning if +delete is used with an incomplete type. +This is the only derived type used by shared_ptr<Ptr> +and it is never used by shared_ptr, which uses one of +the following types, depending on how the shared_ptr is constructed. +

    _Sp_counted_ptr<Ptr, Lp>

    +Inherits from _Sp_counted_base and stores a pointer of type Ptr, +which is passed to delete when the last reference is dropped. +This is the simplest form and is used when there is no custom deleter or +allocator. +

    _Sp_counted_deleter<Ptr, Deleter, Alloc>

    +Inherits from _Sp_counted_ptr and adds support for custom deleter and +allocator. Empty Base Optimization is used for the allocator. This class +is used even when the user only provides a custom deleter, in which case +allocator is used as the allocator. +

    _Sp_counted_ptr_inplace<Tp, Alloc, Lp>

    +Used by allocate_shared and make_shared. +Contains aligned storage to hold an object of type Tp, +which is constructed in-place with placement new. +Has a variadic template constructor allowing any number of arguments to +be forwarded to Tp's constructor. +Unlike the other _Sp_counted_* classes, this one is parameterized on the +type of object, not the type of pointer; this is purely a convenience +that simplifies the implementation slightly. +

    Thread Safety

    +The interface of tr1::shared_ptr was extended for C++0x +with support for rvalue-references and the other features from +N2351. As with other libstdc++ headers shared by TR1 and C++0x, +boost_shared_ptr.h uses conditional compilation, based on the macros +_GLIBCXX_INCLUDE_AS_CXX0X and +_GLIBCXX_INCLUDE_AS_TR1, to enable and disable +features. +

    +C++0x-only features are: rvalue-ref/move support, allocator support, +aliasing constructor, make_shared & allocate_shared. Additionally, +the constructors taking auto_ptr parameters are +deprecated in C++0x mode. +

    +The +Thread +Safety section of the Boost shared_ptr documentation says "shared_ptr +objects offer the same level of thread safety as built-in types." +The implementation must ensure that concurrent updates to separate shared_ptr +instances are correct even when those instances share a reference count e.g. +

    +shared_ptr<A> a(new A);
+shared_ptr<A> b(a);
+
+// Thread 1     // Thread 2
+   a.reset();      b.reset();
+

    +The dynamically-allocated object must be destroyed by exactly one of the +threads. Weak references make things even more interesting. +The shared state used to implement shared_ptr must be transparent to the +user and invariants must be preserved at all times. +The key pieces of shared state are the strong and weak reference counts. +Updates to these need to be atomic and visible to all threads to ensure +correct cleanup of the managed resource (which is, after all, shared_ptr's +job!) +On multi-processor systems memory synchronisation may be needed so that +reference-count updates and the destruction of the managed resource are +race-free. +

    +The function _Sp_counted_base::_M_add_ref_lock(), called when +obtaining a shared_ptr from a weak_ptr, has to test if the managed +resource still exists and either increment the reference count or throw +bad_weak_ptr. +In a multi-threaded program there is a potential race condition if the last +reference is dropped (and the managed resource destroyed) between testing +the reference count and incrementing it, which could result in a shared_ptr +pointing to invalid memory. +

    +The Boost shared_ptr (as used in GCC) features a clever lock-free +algorithm to avoid the race condition, but this relies on the +processor supporting an atomic Compare-And-Swap +instruction. For other platforms there are fall-backs using mutex +locks. Boost (as of version 1.35) includes several different +implementations and the preprocessor selects one based on the +compiler, standard library, platform etc. For the version of +shared_ptr in libstdc++ the compiler and library are fixed, which +makes things much simpler: we have an atomic CAS or we don't, see Lock +Policy below for details. +

    Selecting Lock Policy

    +

    +There is a single _Sp_counted_base class, +which is a template parameterized on the enum +__gnu_cxx::_Lock_policy. The entire family of classes is +parameterized on the lock policy, right up to +__shared_ptr, __weak_ptr and +__enable_shared_from_this. The actual +std::shared_ptr class inherits from +__shared_ptr with the lock policy parameter +selected automatically based on the thread model and platform that +libstdc++ is configured for, so that the best available template +specialization will be used. This design is necessary because it would +not be conforming for shared_ptr to have an +extra template parameter, even if it had a default value. The +available policies are: +

    1. + _S_Atomic +

      +Selected when GCC supports a builtin atomic compare-and-swap operation +on the target processor (see Atomic +Builtins.) The reference counts are maintained using a lock-free +algorithm and GCC's atomic builtins, which provide the required memory +synchronisation. +

    2. + _S_Mutex +

      +The _Sp_counted_base specialization for this policy contains a mutex, +which is locked in add_ref_lock(). This policy is used when GCC's atomic +builtins aren't available so explicit memory barriers are needed in places. +

    3. + _S_Single +

      +This policy uses a non-reentrant add_ref_lock() with no locking. It is +used when libstdc++ is built without --enable-threads. +

    + For all three policies, reference count increments and + decrements are done via the functions in + ext/atomicity.h, which detect if the program + is multi-threaded. If only one thread of execution exists in + the program then less expensive non-atomic operations are used. +

    Dual C++0x and TR1 Implementation

    +The classes derived from _Sp_counted_base (see Class Hierarchy +below) and __shared_count are implemented separately for C++0x +and TR1, in bits/boost_sp_shared_count.h and +tr1/boost_sp_shared_count.h respectively. All other classes +including _Sp_counted_base are shared by both implementations. +

    +The TR1 implementation is considered relatively stable, so is unlikely to +change unless bug fixes require it. If the code that is common to both +C++0x and TR1 modes needs to diverge further then it might be necessary to +duplicate additional classes and only make changes to the C++0x versions. +

    Related functions and classes
    dynamic_pointer_cast, static_pointer_cast, +const_pointer_cast

    +As noted in N2351, these functions can be implemented non-intrusively using +the alias constructor. However the aliasing constructor is only available +in C++0x mode, so in TR1 mode these casts rely on three non-standard +constructors in shared_ptr and __shared_ptr. +In C++0x mode these constructors and the related tag types are not needed. +

    enable_shared_from_this

    +The clever overload to detect a base class of type +enable_shared_from_this comes straight from Boost. +There is an extra overload for __enable_shared_from_this to +work smoothly with __shared_ptr<Tp, Lp> using any lock +policy. +

    make_shared, allocate_shared

    +make_shared simply forwards to allocate_shared +with std::allocator as the allocator. +Although these functions can be implemented non-intrusively using the +alias constructor, if they have access to the implementation then it is +possible to save storage and reduce the number of heap allocations. The +newly constructed object and the _Sp_counted_* can be allocated in a single +block and the standard says implementations are "encouraged, but not required," +to do so. This implementation provides additional non-standard constructors +(selected with the type _Sp_make_shared_tag) which create an +object of type _Sp_counted_ptr_inplace to hold the new object. +The returned shared_ptr<A> needs to know the address of the +new A object embedded in the _Sp_counted_ptr_inplace, +but it has no way to access it. +This implementation uses a "covert channel" to return the address of the +embedded object when get_deleter<_Sp_make_shared_tag>() +is called. Users should not try to use this. +As well as the extra constructors, this implementation also needs some +members of _Sp_counted_deleter to be protected where they could otherwise +be private. +

    Use

    Examples

    + Examples of use can be found in the testsuite, under + testsuite/tr1/2_general_utilities/shared_ptr. +

    Unresolved Issues

    + The resolution to C++ Standard Library issue 674, + "shared_ptr interface changes for consistency with N1856" will + need to be implemented after it is accepted into the working + paper. Issue 743 + might also require changes. +

    + The _S_single policy uses atomics when used in MT + code, because it uses the same dispatcher functions that check + __gthread_active_p(). This could be + addressed by providing template specialisations for some members + of _Sp_counted_base<_S_single>. +

    + Unlike Boost, this implementation does not use separate classes + for the pointer+deleter and pointer+deleter+allocator cases in + C++0x mode, combining both into _Sp_counted_deleter and using + allocator when the user doesn't specify + an allocator. If it was found to be beneficial an additional + class could easily be added. With the current implementation, + the _Sp_counted_deleter and __shared_count constructors taking a + custom deleter but no allocator are technically redundant and + could be removed, changing callers to always specify an + allocator. If a separate pointer+deleter class was added the + __shared_count constructor would be needed, so it has been kept + for now. +

    + The hack used to get the address of the managed object from + _Sp_counted_ptr_inplace::_M_get_deleter() + is accessible to users. This could be prevented if + get_deleter<_Sp_make_shared_tag>() + always returned NULL, since the hack only needs to work at a + lower level, not in the public API. This wouldn't be difficult, + but hasn't been done since there is no danger of accidental + misuse: users already know they are relying on unsupported + features if they refer to implementation details such as + _Sp_make_shared_tag. +

    + tr1::_Sp_deleter could be a private member of tr1::__shared_count but it + would alter the ABI. +

    + Exposing the alias constructor in TR1 mode could simplify the + *_pointer_cast functions. Constructor could be private in TR1 + mode, with the cast functions as friends. +

    Acknowledgments

    + The original authors of the Boost shared_ptr, which is really nice + code to work with, Peter Dimov in particular for his help and + invaluable advice on thread safety. Phillip Jordan and Paolo + Carlini for the lock policy implementation. +

    Bibliography

    + + + Improving shared_ptr for C++0x, Revision 2 + + + . + N2351 + .

    + + + C++ Standard Library Active Issues List + + + . + N2456 + .

    + + + Working Draft, Standard for Programming Language C++ + + + . + N2461 + .

    + shared_ptr + + Boost C++ Libraries documentation, shared_ptr + + + . + N2461 + .

    Prev Up Next
    Pairs Home Traits
    diff --git a/libstdc++-v3/doc/html/manual/messages.html b/libstdc++-v3/doc/html/manual/messages.html deleted file mode 100644 index bd663dbf742..00000000000 --- a/libstdc++-v3/doc/html/manual/messages.html +++ /dev/null @@ -1,284 +0,0 @@ - - -messages
    messages
    Prev Chapter 15. Facets aka Categories Next

    messages

    -The std::messages facet implements message retrieval functionality -equivalent to Java's java.text.MessageFormat .using either GNU gettext -or IEEE 1003.1-200 functions. -

    Requirements

    -The std::messages facet is probably the most vaguely defined facet in -the standard library. It's assumed that this facility was built into -the standard library in order to convert string literals from one -locale to the other. For instance, converting the "C" locale's -const char* c = "please" to a German-localized "bitte" -during program execution. -

    -22.2.7.1 - Template class messages [lib.locale.messages] -

    -This class has three public member functions, which directly -correspond to three protected virtual member functions. -

    -The public member functions are: -

    -catalog open(const string&, const locale&) const -

    -string_type get(catalog, int, int, const string_type&) const -

    -void close(catalog) const -

    -While the virtual functions are: -

    -catalog do_open(const string&, const locale&) const -

    - --1- Returns: A value that may be passed to get() to retrieve a -message, from the message catalog identified by the string name -according to an implementation-defined mapping. The result can be used -until it is passed to close(). Returns a value less than 0 if no such -catalog can be opened. - -

    -string_type do_get(catalog, int, int, const string_type&) const -

    - --3- Requires: A catalog cat obtained from open() and not yet closed. --4- Returns: A message identified by arguments set, msgid, and dfault, -according to an implementation-defined mapping. If no such message can -be found, returns dfault. - -

    -void do_close(catalog) const -

    - --5- Requires: A catalog cat obtained from open() and not yet closed. --6- Effects: Releases unspecified resources associated with cat. --7- Notes: The limit on such resources, if any, is implementation-defined. - -

    Design

    -A couple of notes on the standard. -

    -First, why is messages_base::catalog specified as a typedef -to int? This makes sense for implementations that use -catopen, but not for others. Fortunately, it's not heavily -used and so only a minor irritant. -

    -Second, by making the member functions const, it is -impossible to save state in them. Thus, storing away information used -in the 'open' member function for use in 'get' is impossible. This is -unfortunate. -

    -The 'open' member function in particular seems to be oddly -designed. The signature seems quite peculiar. Why specify a const -string& argument, for instance, instead of just const -char*? Or, why specify a const locale& argument that is -to be used in the 'get' member function? How, exactly, is this locale -argument useful? What was the intent? It might make sense if a locale -argument was associated with a given default message string in the -'open' member function, for instance. Quite murky and unclear, on -reflection. -

    -Lastly, it seems odd that messages, which explicitly require code -conversion, don't use the codecvt facet. Because the messages facet -has only one template parameter, it is assumed that ctype, and not -codecvt, is to be used to convert between character sets. -

    -It is implicitly assumed that the locale for the default message -string in 'get' is in the "C" locale. Thus, all source code is assumed -to be written in English, so translations are always from "en_US" to -other, explicitly named locales. -

    Implementation

    Models

    - This is a relatively simple class, on the face of it. The standard - specifies very little in concrete terms, so generic - implementations that are conforming yet do very little are the - norm. Adding functionality that would be useful to programmers and - comparable to Java's java.text.MessageFormat takes a bit of work, - and is highly dependent on the capabilities of the underlying - operating system. -

    - Three different mechanisms have been provided, selectable via - configure flags: -

    • - generic -

      - This model does very little, and is what is used by default. -

    • - gnu -

      - The gnu model is complete and fully tested. It's based on the - GNU gettext package, which is part of glibc. It uses the - functions textdomain, bindtextdomain, gettext to - implement full functionality. Creating message catalogs is a - relatively straight-forward process and is lightly documented - below, and fully documented in gettext's distributed - documentation. -

    • - ieee_1003.1-200x -

      - This is a complete, though untested, implementation based on - the IEEE standard. The functions catopen, catgets, - catclose are used to retrieve locale-specific messages - given the appropriate message catalogs that have been - constructed for their use. Note, the script - po2msg.sed that is part of the gettext distribution can - convert gettext catalogs into catalogs that - catopen can use. -

    -A new, standards-conformant non-virtual member function signature was -added for 'open' so that a directory could be specified with a given -message catalog. This simplifies calling conventions for the gnu -model. -

    The GNU Model

    - The messages facet, because it is retrieving and converting - between characters sets, depends on the ctype and perhaps the - codecvt facet in a given locale. In addition, underlying "C" - library locale support is necessary for more than just the - LC_MESSAGES mask: LC_CTYPE is also - necessary. To avoid any unpleasantness, all bits of the "C" mask - (i.e. LC_ALL) are set before retrieving messages. -

    - Making the message catalogs can be initially tricky, but become - quite simple with practice. For complete info, see the gettext - documentation. Here's an idea of what is required: -

    • - Make a source file with the required string literals that need - to be translated. See intl/string_literals.cc for - an example. -

    • - Make initial catalog (see "4 Making the PO Template File" from - the gettext docs).

      - xgettext --c++ --debug string_literals.cc -o libstdc++.pot -

    • Make language and country-specific locale catalogs.

      - cp libstdc++.pot fr_FR.po -

      - cp libstdc++.pot de_DE.po -

    • - Edit localized catalogs in emacs so that strings are - translated. -

      - emacs fr_FR.po -

    • Make the binary mo files.

      - msgfmt fr_FR.po -o fr_FR.mo -

      - msgfmt de_DE.po -o de_DE.mo -

    • Copy the binary files into the correct directory structure.

      - cp fr_FR.mo (dir)/fr_FR/LC_MESSAGES/libstdc++.mo -

      - cp de_DE.mo (dir)/de_DE/LC_MESSAGES/libstdc++.mo -

    • Use the new message catalogs.

      - locale loc_de("de_DE"); -

      - - use_facet<messages<char> >(loc_de).open("libstdc++", locale(), dir); - -

    Use

    - A simple example using the GNU model of message conversion. - 

    -#include <iostream>
-#include <locale>
-using namespace std;
-
-void test01()
-{
-  typedef messages<char>::catalog catalog;
-  const char* dir =
-  "/mnt/egcs/build/i686-pc-linux-gnu/libstdc++/po/share/locale";  
-  const locale loc_de("de_DE");
-  const messages<char>& mssg_de = use_facet<messages<char> >(loc_de); 
-
-  catalog cat_de = mssg_de.open("libstdc++", loc_de, dir);
-  string s01 = mssg_de.get(cat_de, 0, 0, "please");
-  string s02 = mssg_de.get(cat_de, 0, 0, "thank you");
-  cout << "please in german:" << s01 << '\n';
-  cout << "thank you in german:" << s02 << '\n';
-  mssg_de.close(cat_de);
-}
-

    Future

    • - Things that are sketchy, or remain unimplemented: -

      • - _M_convert_from_char, _M_convert_to_char are in flux, - depending on how the library ends up doing character set - conversions. It might not be possible to do a real character - set based conversion, due to the fact that the template - parameter for messages is not enough to instantiate the - codecvt facet (1 supplied, need at least 2 but would prefer - 3). -

      • - There are issues with gettext needing the global locale set - to extract a message. This dependence on the global locale - makes the current "gnu" model non MT-safe. Future versions - of glibc, i.e. glibc 2.3.x will fix this, and the C++ library - bits are already in place. -

    • - Development versions of the GNU "C" library, glibc 2.3 will allow - a more efficient, MT implementation of std::messages, and will - allow the removal of the _M_name_messages data member. If this is - done, it will change the library ABI. The C++ parts to support - glibc 2.3 have already been coded, but are not in use: once this - version of the "C" library is released, the marked parts of the - messages implementation can be switched over to the new "C" - library functionality. -

    • - At some point in the near future, std::numpunct will probably use - std::messages facilities to implement truename/falsename - correctly. This is currently not done, but entries in - libstdc++.pot have already been made for "true" and "false" string - literals, so all that remains is the std::numpunct coding and the - configure/make hassles to make the installed library search its - own catalog. Currently the libstdc++.mo catalog is only searched - for the testsuite cases involving messages members. -

    • The following member functions:

      - - catalog - open(const basic_string<char>& __s, const locale& __loc) const - -

      - - catalog - open(const basic_string<char>&, const locale&, const char*) const; - -

      - Don't actually return a "value less than 0 if no such catalog - can be opened" as required by the standard in the "gnu" - model. As of this writing, it is unknown how to query to see - if a specified message catalog exists using the gettext - package. -

    Bibliography

    - The GNU C Library - . Roland McGrath. Ulrich Drepper. Copyright © 2007 FSF. Chapters 6 Character Set Handling, and 7 Locales and Internationalization - .

    - Correspondence - . Ulrich Drepper. Copyright © 2002 .

    - ISO/IEC 14882:1998 Programming languages - C++ - . Copyright © 1998 ISO.

    - ISO/IEC 9899:1999 Programming languages - C - . Copyright © 1999 ISO.

    - System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x) - . Copyright © 1999 - The Open Group/The Institute of Electrical and Electronics Engineers, Inc.. - - - .

    - The C++ Programming Language, Special Edition - . Bjarne Stroustrup. Copyright © 2000 Addison Wesley, Inc.. Appendix D. - Addison Wesley - .

    - Standard C++ IOStreams and Locales - . - Advanced Programmer's Guide and Reference - . Angelika Langer. Klaus Kreft. Copyright © 2000 Addison Wesley Longman, Inc.. - Addison Wesley Longman - .

    - Java 2 Platform, Standard Edition, v 1.3.1 API Specification - . java.util.Properties, java.text.MessageFormat, -java.util.Locale, java.util.ResourceBundle. - - - .

    - GNU gettext tools, version 0.10.38, Native Language Support -Library and Tools. - . - - - .

    Prev Up Next
    codecvt Home Part VII.  - Containers - -
    diff --git a/libstdc++-v3/doc/html/manual/numerics.html b/libstdc++-v3/doc/html/manual/numerics.html index 57089cf47e8..de57145c948 100644 --- a/libstdc++-v3/doc/html/manual/numerics.html +++ b/libstdc++-v3/doc/html/manual/numerics.html @@ -1,9 +1,30 @@ -Part X.  Numerics
    Part X.  +Chapter 12.  Numerics
    Chapter 12.  Numerics -
    Prev The GNU C++ Library Next

    Part X.  +

    Prev Part II.  + Standard Contents + Next

    Chapter 12.  Numerics - -

    Table of Contents

    21. Complex
    complex Processing
    22. Generalized Operations
    23. Interacting with C
    Numerics vs. Arrays
    C99
    Prev Up Next
    Chapter 20. Mutating Home Chapter 21. Complex
    + +

    Table of Contents

    Complex
    complex Processing
    Generalized Operations
    Interacting with C
    Numerics vs. Arrays
    C99

    Complex

    +

    complex Processing

    +

    Using complex<> becomes even more comple- er, sorry, + complicated, with the not-quite-gratuitously-incompatible + addition of complex types to the C language. David Tribble has + compiled a list of C++98 and C99 conflict points; his description of + C's new type versus those of C++ and how to get them playing together + nicely is +here. +

    complex<> is intended to be instantiated with a + floating-point type. As long as you meet that and some other basic + requirements, then the resulting instantiation has all of the usual + math operators defined, as well as definitions of op<< + and op>> that work with iostreams: op<< + prints (u,v) and op>> can read u, + (u), and (u,v). +

    Prev Up Next
    Chapter 11.  + Algorithms + + Home Generalized Operations
    diff --git a/libstdc++-v3/doc/html/manual/numerics_and_c.html b/libstdc++-v3/doc/html/manual/numerics_and_c.html index 0bd1b809371..5102af670f3 100644 --- a/libstdc++-v3/doc/html/manual/numerics_and_c.html +++ b/libstdc++-v3/doc/html/manual/numerics_and_c.html @@ -1,9 +1,9 @@ -Chapter 23. Interacting with C
    Chapter 23. Interacting with C
    Prev Part X.  +Interacting with C
    Interacting with C
    Prev Chapter 12.  Numerics - Next

    Chapter 23. Interacting with C

    Table of Contents

    Numerics vs. Arrays
    C99

    Numerics vs. Arrays

    One of the major reasons why FORTRAN can chew through numbers so well +

    		 Next

    Interacting with C

    Numerics vs. Arrays

    One of the major reasons why FORTRAN can chew through numbers so well is that it is defined to be free of pointer aliasing, an assumption that C89 is not allowed to make, and neither is C++98. C99 adds a new keyword, restrict, to apply to individual pointers. The @@ -18,4 +18,20 @@ speaking this is only one of the five template classes, and they are designed to be familiar to people who have worked with the BLAS libraries before. -

    Prev Up Next
    Chapter 22. Generalized Operations Home C99
    +

    C99

    In addition to the other topics on this page, we'll note here some + of the C99 features that appear in libstdc++. +

    The C99 features depend on the --enable-c99 configure flag. + This flag is already on by default, but it can be disabled by the + user. Also, the configuration machinery will disable it if the + necessary support for C99 (e.g., header files) cannot be found. +

    As of GCC 3.0, C99 support includes classification functions + such as isnormal, isgreater, + isnan, etc. + The functions used for 'long long' support such as strtoll + are supported, as is the lldiv_t typedef. Also supported + are the wide character functions using 'long long', like + wcstoll. +

    Prev Up Next
    Generalized Operations Home Chapter 13.  + Input and Output + +
    diff --git a/libstdc++-v3/doc/html/manual/pairs.html b/libstdc++-v3/doc/html/manual/pairs.html index 3b4981bbaa8..719c987df20 100644 --- a/libstdc++-v3/doc/html/manual/pairs.html +++ b/libstdc++-v3/doc/html/manual/pairs.html @@ -1,9 +1,9 @@ -Chapter 10. Pairs
    Chapter 10. Pairs
    Prev Part IV.  +Pairs
    Pairs
    Prev Chapter 6.  Utilities - Next

    Chapter 10. Pairs

    The pair<T1,T2> is a simple and handy way to +

    		 Next

    Pairs

    The pair<T1,T2> is a simple and handy way to carry around a pair of objects. One is of type T1, and another of type T2; they may be the same type, but you don't get anything extra if they are. The two members can be accessed directly, as @@ -31,7 +31,7 @@ is defined as evaluating to: 

         x.first  <  y.first  ||
-        ( !(y.first  <  x.first)  &&  x.second  <  y.second )
+	( !(y.first  <  x.first)  &&  x.second  <  y.second )

    The other operators are not defined using the rel_ops functions above, but their semantics are the same.

    Finally, there is a template function called make_pair @@ -39,4 +39,7 @@ instance of a pair instantiated on their respective types: 

         pair<int,MyClass> p = make_pair(4,myobject);
-
    Prev Up Next
    Chapter 9. Functors Home Chapter 11. Memory
    +
    Prev Up Next
    Chapter 6.  + Utilities + + Home Memory
    diff --git a/libstdc++-v3/doc/html/manual/parallel_mode.html b/libstdc++-v3/doc/html/manual/parallel_mode.html index a21c3a65b2d..b8993b5c9d2 100644 --- a/libstdc++-v3/doc/html/manual/parallel_mode.html +++ b/libstdc++-v3/doc/html/manual/parallel_mode.html @@ -1,9 +1,9 @@ -Chapter 31. Parallel Mode
    Chapter 31. Parallel Mode
    Prev Part XII.  +Chapter 18. Parallel Mode
    Chapter 18. Parallel Mode
    Prev Part III.  Extensions - Next

    Chapter 31. Parallel Mode

    Table of Contents

    Intro
    Semantics
    Using
    Prerequisite Compiler Flags
    Using Parallel Mode
    Using Specific Parallel Components
    Design
    Interface Basics
    Configuration and Tuning
    Implementation Namespaces
    Testing
    Bibliography

    The libstdc++ parallel mode is an experimental parallel +

    		 Next

    Chapter 18. Parallel Mode

    Table of Contents

    Intro
    Semantics
    Using
    Prerequisite Compiler Flags
    Using Parallel Mode
    Using Specific Parallel Components
    Design
    Interface Basics
    Configuration and Tuning
    Implementation Namespaces
    Testing
    Bibliography

    The libstdc++ parallel mode is an experimental parallel implementation of many algorithms the C++ Standard Library.

    Several of the standard algorithms, for instance @@ -13,12 +13,12 @@ explicit source declaration or by compiling existing sources with a specific compiler flag.

    Intro

    The following library components in the include numeric are included in the parallel mode:

    • std::accumulate

    • std::adjacent_difference

    • std::inner_product

    • std::partial_sum

    The following library components in the include -algorithm are included in the parallel mode:

    • std::adjacent_find

    • std::count

    • std::count_if

    • std::equal

    • std::find

    • std::find_if

    • std::find_first_of

    • std::for_each

    • std::generate

    • std::generate_n

    • std::lexicographical_compare

    • std::mismatch

    • std::search

    • std::search_n

    • std::transform

    • std::replace

    • std::replace_if

    • std::max_element

    • std::merge

    • std::min_element

    • std::nth_element

    • std::partial_sort

    • std::partition

    • std::random_shuffle

    • std::set_union

    • std::set_intersection

    • std::set_symmetric_difference

    • std::set_difference

    • std::sort

    • std::stable_sort

    • std::unique_copy

    Bibliography

    +algorithm are included in the parallel mode:

    • std::adjacent_find

    • std::count

    • std::count_if

    • std::equal

    • std::find

    • std::find_if

    • std::find_first_of

    • std::for_each

    • std::generate

    • std::generate_n

    • std::lexicographical_compare

    • std::mismatch

    • std::search

    • std::search_n

    • std::transform

    • std::replace

    • std::replace_if

    • std::max_element

    • std::merge

    • std::min_element

    • std::nth_element

    • std::partial_sort

    • std::partition

    • std::random_shuffle

    • std::set_union

    • std::set_intersection

    • std::set_symmetric_difference

    • std::set_difference

    • std::sort

    • std::stable_sort

    • std::unique_copy

    Bibliography

    Parallelization of Bulk Operations for STL Dictionaries . Johannes Singler. Leonor Frias. Copyright © 2007 . Workshop on Highly Parallel Processing on a Chip (HPPC) 2007. (LNCS) - .

    + .

    The Multi-Core Standard Template Library . Johannes Singler. Peter Sanders. Felix Putze. Copyright © 2007 . Euro-Par 2007: Parallel Processing. (LNCS 4641) - .

    Prev Up Next
    Design Home Semantics
    + .

    Prev Up Next
    Design Home Semantics
    diff --git a/libstdc++-v3/doc/html/manual/profile_mode.html b/libstdc++-v3/doc/html/manual/profile_mode.html index 408dba26f79..8fc828ef1e3 100644 --- a/libstdc++-v3/doc/html/manual/profile_mode.html +++ b/libstdc++-v3/doc/html/manual/profile_mode.html @@ -1,9 +1,9 @@ -Chapter 32. Profile Mode
    Chapter 32. Profile Mode
    Prev Part XII.  +Chapter 19. Profile Mode
    Chapter 19. Profile Mode
    Prev Part III.  Extensions - Next

    Chapter 32. Profile Mode

    Table of Contents

    Intro
    Using the Profile Mode
    Tuning the Profile Mode
    Design
    Wrapper Model
    Instrumentation
    Run Time Behavior
    Analysis and Diagnostics
    Cost Model
    Reports
    Testing
    Extensions for Custom Containers
    Empirical Cost Model
    Implementation Issues
    Stack Traces
    Symbolization of Instruction Addresses
    Concurrency
    Using the Standard Library in the Instrumentation Implementation
    Malloc Hooks
    Construction and Destruction of Global Objects
    Developer Information
    Big Picture
    How To Add A Diagnostic
    Diagnostics
    Diagnostic Template
    Containers
    Algorithms
    Data Locality
    Multithreaded Data Access
    Statistics
    Bibliography

    Intro

    +

    		 Next

    Chapter 19. Profile Mode

    Table of Contents

    Intro
    Using the Profile Mode
    Tuning the Profile Mode
    Design
    Wrapper Model
    Instrumentation
    Run Time Behavior
    Analysis and Diagnostics
    Cost Model
    Reports
    Testing
    Extensions for Custom Containers
    Empirical Cost Model
    Implementation Issues
    Stack Traces
    Symbolization of Instruction Addresses
    Concurrency
    Using the Standard Library in the Instrumentation Implementation
    Malloc Hooks
    Construction and Destruction of Global Objects
    Developer Information
    Big Picture
    How To Add A Diagnostic
    Diagnostics
    Diagnostic Template
    Containers
    Algorithms
    Data Locality
    Multithreaded Data Access
    Statistics
    Bibliography

    Intro

    Goal: Give performance improvement advice based on recognition of suboptimal usage patterns of the standard library.

    @@ -11,13 +11,13 @@ calls to an instrumentation library to record the internal state of various components at interesting entry/exit points to/from the standard library. Process trace, recognize suboptimal patterns, give advice. - For details, see + For details, see paper presented at CGO 2009.

    Strengths:

    • - Unintrusive solution. The application code does not require any + Unintrusive solution. The application code does not require any modification.

    • The advice is call context sensitive, thus capable of identifying precisely interesting dynamic performance behavior. @@ -75,7 +75,7 @@ vector-size: improvement = 3: call stack = 0x804842c ... The warning message. For some warnings, this is static text, e.g., "change vector to list". For other warnings, such as the one above, the message contains numeric advice, e.g., the suggested initial size - of the hashtable. + of the vector.

    Three files are generated. libstdcxx-profile.txt contains human readable advice. libstdcxx-profile.raw @@ -108,7 +108,7 @@ vector-size: improvement = 3: call stack = 0x804842c ... path for the output files.

  • _GLIBCXX_PROFILE_MAX_WARN_COUNT: set it to the maximum number of warnings desired. The default value is 10.

  • - _GLIBCXX_PROFILE_MAX_STACK_DEPTH: if set to 0, + _GLIBCXX_PROFILE_MAX_STACK_DEPTH: if set to 0, the advice will be collected and reported for the program as a whole, and not for each call context. @@ -124,10 +124,10 @@ vector-size: improvement = 3: call stack = 0x804842c ... live containers are deleted. The default is 128 MB.

  • _GLIBCXX_PROFILE_NO_THREADS: - Make the library not use threads. If thread local storage (TLS) is not + Make the library not use threads. If thread local storage (TLS) is not available, you will get a preprocessor error asking you to set -D_GLIBCXX_PROFILE_NO_THREADS if your program is single-threaded. - Multithreded execution without TLS is not supported. + Multithreaded execution without TLS is not supported. (Environment variable not supported.)

  • _GLIBCXX_HAVE_EXECINFO_H: @@ -138,9 +138,9 @@ vector-size: improvement = 3: call stack = 0x804842c ... call context. (Environment variable not supported.)

    • -

    Bibliography

    +

    Bibliography

    Perflint: A Context Sensitive Performance Advisor for C++ Programs . Lixia Liu. Silvius Rus. Copyright © 2009 . Proceedings of the 2009 International Symposium on Code Generation - and Optimization - .

    Prev Up Next
    Testing Home Design
    + and Optimization + .

    Prev Up Next
    Testing Home Design
    diff --git a/libstdc++-v3/doc/html/manual/sequences.html b/libstdc++-v3/doc/html/manual/sequences.html deleted file mode 100644 index fd3ff148e54..00000000000 --- a/libstdc++-v3/doc/html/manual/sequences.html +++ /dev/null @@ -1,43 +0,0 @@ - - -Chapter 16. Sequences
    Chapter 16. Sequences
    Prev Part VII.  - Containers - - Next

    Chapter 16. Sequences

    Table of Contents

    list
    list::size() is O(n)
    vector
    Space Overhead Management

    list

    list::size() is O(n)

    - Yes it is, and that's okay. This is a decision that we preserved - when we imported SGI's STL implementation. The following is - quoted from their FAQ: -

    - The size() member function, for list and slist, takes time - proportional to the number of elements in the list. This was a - deliberate tradeoff. The only way to get a constant-time - size() for linked lists would be to maintain an extra member - variable containing the list's size. This would require taking - extra time to update that variable (it would make splice() a - linear time operation, for example), and it would also make the - list larger. Many list algorithms don't require that extra - word (algorithms that do require it might do better with - vectors than with lists), and, when it is necessary to maintain - an explicit size count, it's something that users can do - themselves. -

    - This choice is permitted by the C++ standard. The standard says - that size() “should” be constant time, and - “should” does not mean the same thing as - “shall”. This is the officially recommended ISO - wording for saying that an implementation is supposed to do - something unless there is a good reason not to. -

    - One implication of linear time size(): you should never write - 

    -         if (L.size() == 0)
-             ...
-

    - Instead, you should write - 

    -         if (L.empty())
-             ...
-
    Prev Up Next
    Part VII.  - Containers - - Home vector
    diff --git a/libstdc++-v3/doc/html/manual/setup.html b/libstdc++-v3/doc/html/manual/setup.html index b0c491e544a..23de8cc5219 100644 --- a/libstdc++-v3/doc/html/manual/setup.html +++ b/libstdc++-v3/doc/html/manual/setup.html @@ -23,7 +23,7 @@ Because libstdc++ is part of GCC, the primary source for installation instructions is the GCC install page. - In particular, list of prerequisite software needed to build the library + In particular, list of prerequisite software needed to build the library starts with those requirements. The same pages also list the tools you will need if you wish to modify the source. @@ -40,7 +40,11 @@ The configure process will automatically detect and use these features if the underlying support is present.

    - Finally, a few system-specific requirements: + To generate the API documentation from the sources you will need + Doxygen, see Documentation + Style in the appendix for full details. +

    + Finally, a few system-specific requirements:

    linux

    If gcc 3.1.0 or later on is being used on linux, an attempt will be made to use "C" library functionality necessary for @@ -90,12 +94,12 @@ zh_TW BIG5

    To install support for locales, do only one of the following:

    • install all locales

      • with RedHat Linux: -

        export LC_ALL=C -

        rpm -e glibc-common --nodeps -

        +

        export LC_ALL=C +

        rpm -e glibc-common --nodeps +

        rpm -i --define "_install_langs all" - glibc-common-2.2.5-34.i386.rpm - + glibc-common-2.2.5-34.i386.rpm +

      • Instructions for other operating systems solicited.

    • install just the necessary locales

      • with Debian Linux:

        Add the above list, as shown, to the file diff --git a/libstdc++-v3/doc/html/manual/shared_ptr.html b/libstdc++-v3/doc/html/manual/shared_ptr.html deleted file mode 100644 index 59666b93b16..00000000000 --- a/libstdc++-v3/doc/html/manual/shared_ptr.html +++ /dev/null @@ -1,304 +0,0 @@ - - -shared_ptr

        shared_ptr
        Prev Chapter 11. Memory Next

        shared_ptr

        -The shared_ptr class template stores a pointer, usually obtained via new, -and implements shared ownership semantics. -

        Requirements

        -

        - The standard deliberately doesn't require a reference-counted - implementation, allowing other techniques such as a - circular-linked-list. -

        - At the time of writing the C++0x working paper doesn't mention how - threads affect shared_ptr, but it is likely to follow the existing - practice set by boost::shared_ptr. The - shared_ptr in libstdc++ is derived from Boost's, so the same rules - apply. -

        -

        Design Issues

        -The shared_ptr code is kindly donated to GCC by the Boost -project and the original authors of the code. The basic design and -algorithms are from Boost, the notes below describe details specific to -the GCC implementation. Names have been uglified in this implementation, -but the design should be recognisable to anyone familiar with the Boost -1.32 shared_ptr. -

        -The basic design is an abstract base class, _Sp_counted_base that -does the reference-counting and calls virtual functions when the count -drops to zero. -Derived classes override those functions to destroy resources in a context -where the correct dynamic type is known. This is an application of the -technique known as type erasure. -

        Implementation

        Class Hierarchy

        -A shared_ptr<T> contains a pointer of -type T* and an object of type -__shared_count. The shared_count contains a -pointer of type _Sp_counted_base* which points to the -object that maintains the reference-counts and destroys the managed -resource. -

        _Sp_counted_base<Lp>

        -The base of the hierarchy is parameterized on the lock policy alone. -_Sp_counted_base doesn't depend on the type of pointer being managed, -it only maintains the reference counts and calls virtual functions when -the counts drop to zero. The managed object is destroyed when the last -strong reference is dropped, but the _Sp_counted_base itself must exist -until the last weak reference is dropped. -

        _Sp_counted_base_impl<Ptr, Deleter, Lp>

        -Inherits from _Sp_counted_base and stores a pointer of type Ptr -and a deleter of type Deleter. _Sp_deleter is -used when the user doesn't supply a custom deleter. Unlike Boost's, this -default deleter is not "checked" because GCC already issues a warning if -delete is used with an incomplete type. -This is the only derived type used by shared_ptr<Ptr> -and it is never used by shared_ptr, which uses one of -the following types, depending on how the shared_ptr is constructed. -

        _Sp_counted_ptr<Ptr, Lp>

        -Inherits from _Sp_counted_base and stores a pointer of type Ptr, -which is passed to delete when the last reference is dropped. -This is the simplest form and is used when there is no custom deleter or -allocator. -

        _Sp_counted_deleter<Ptr, Deleter, Alloc>

        -Inherits from _Sp_counted_ptr and adds support for custom deleter and -allocator. Empty Base Optimization is used for the allocator. This class -is used even when the user only provides a custom deleter, in which case -allocator is used as the allocator. -

        _Sp_counted_ptr_inplace<Tp, Alloc, Lp>

        -Used by allocate_shared and make_shared. -Contains aligned storage to hold an object of type Tp, -which is constructed in-place with placement new. -Has a variadic template constructor allowing any number of arguments to -be forwarded to Tp's constructor. -Unlike the other _Sp_counted_* classes, this one is parameterized on the -type of object, not the type of pointer; this is purely a convenience -that simplifies the implementation slightly. -

        Thread Safety

        -The interface of tr1::shared_ptr was extended for C++0x -with support for rvalue-references and the other features from -N2351. As with other libstdc++ headers shared by TR1 and C++0x, -boost_shared_ptr.h uses conditional compilation, based on the macros -_GLIBCXX_INCLUDE_AS_CXX0X and -_GLIBCXX_INCLUDE_AS_TR1, to enable and disable -features. -

        -C++0x-only features are: rvalue-ref/move support, allocator support, -aliasing constructor, make_shared & allocate_shared. Additionally, -the constructors taking auto_ptr parameters are -deprecated in C++0x mode. -

        -The -Thread -Safety section of the Boost shared_ptr documentation says "shared_ptr -objects offer the same level of thread safety as built-in types." -The implementation must ensure that concurrent updates to separate shared_ptr -instances are correct even when those instances share a reference count e.g. -

        -shared_ptr<A> a(new A);
-shared_ptr<A> b(a);
-
-// Thread 1     // Thread 2
-   a.reset();      b.reset();
-

        -The dynamically-allocated object must be destroyed by exactly one of the -threads. Weak references make things even more interesting. -The shared state used to implement shared_ptr must be transparent to the -user and invariants must be preserved at all times. -The key pieces of shared state are the strong and weak reference counts. -Updates to these need to be atomic and visible to all threads to ensure -correct cleanup of the managed resource (which is, after all, shared_ptr's -job!) -On multi-processor systems memory synchronisation may be needed so that -reference-count updates and the destruction of the managed resource are -race-free. -

        -The function _Sp_counted_base::_M_add_ref_lock(), called when -obtaining a shared_ptr from a weak_ptr, has to test if the managed -resource still exists and either increment the reference count or throw -bad_weak_ptr. -In a multi-threaded program there is a potential race condition if the last -reference is dropped (and the managed resource destroyed) between testing -the reference count and incrementing it, which could result in a shared_ptr -pointing to invalid memory. -

        -The Boost shared_ptr (as used in GCC) features a clever lock-free -algorithm to avoid the race condition, but this relies on the -processor supporting an atomic Compare-And-Swap -instruction. For other platforms there are fall-backs using mutex -locks. Boost (as of version 1.35) includes several different -implementations and the preprocessor selects one based on the -compiler, standard library, platform etc. For the version of -shared_ptr in libstdc++ the compiler and library are fixed, which -makes things much simpler: we have an atomic CAS or we don't, see Lock -Policy below for details. -

        Selecting Lock Policy

        -

        -There is a single _Sp_counted_base class, -which is a template parameterized on the enum -__gnu_cxx::_Lock_policy. The entire family of classes is -parameterized on the lock policy, right up to -__shared_ptr, __weak_ptr and -__enable_shared_from_this. The actual -std::shared_ptr class inherits from -__shared_ptr with the lock policy parameter -selected automatically based on the thread model and platform that -libstdc++ is configured for, so that the best available template -specialization will be used. This design is necessary because it would -not be conforming for shared_ptr to have an -extra template parameter, even if it had a default value. The -available policies are: -

        1. - _S_Atomic -

          -Selected when GCC supports a builtin atomic compare-and-swap operation -on the target processor (see Atomic -Builtins.) The reference counts are maintained using a lock-free -algorithm and GCC's atomic builtins, which provide the required memory -synchronisation. -

        2. - _S_Mutex -

          -The _Sp_counted_base specialization for this policy contains a mutex, -which is locked in add_ref_lock(). This policy is used when GCC's atomic -builtins aren't available so explicit memory barriers are needed in places. -

        3. - _S_Single -

          -This policy uses a non-reentrant add_ref_lock() with no locking. It is -used when libstdc++ is built without --enable-threads. -

        - For all three policies, reference count increments and - decrements are done via the functions in - ext/atomicity.h, which detect if the program - is multi-threaded. If only one thread of execution exists in - the program then less expensive non-atomic operations are used. -

        Dual C++0x and TR1 Implementation

        -The classes derived from _Sp_counted_base (see Class Hierarchy -below) and __shared_count are implemented separately for C++0x -and TR1, in bits/boost_sp_shared_count.h and -tr1/boost_sp_shared_count.h respectively. All other classes -including _Sp_counted_base are shared by both implementations. -

        -The TR1 implementation is considered relatively stable, so is unlikely to -change unless bug fixes require it. If the code that is common to both -C++0x and TR1 modes needs to diverge further then it might be necessary to -duplicate additional classes and only make changes to the C++0x versions. -

        Related functions and classes

        dynamic_pointer_cast, static_pointer_cast, -const_pointer_cast

        -As noted in N2351, these functions can be implemented non-intrusively using -the alias constructor. However the aliasing constructor is only available -in C++0x mode, so in TR1 mode these casts rely on three non-standard -constructors in shared_ptr and __shared_ptr. -In C++0x mode these constructors and the related tag types are not needed. -

        enable_shared_from_this

        -The clever overload to detect a base class of type -enable_shared_from_this comes straight from Boost. -There is an extra overload for __enable_shared_from_this to -work smoothly with __shared_ptr<Tp, Lp> using any lock -policy. -

        make_shared, allocate_shared

        -make_shared simply forwards to allocate_shared -with std::allocator as the allocator. -Although these functions can be implemented non-intrusively using the -alias constructor, if they have access to the implementation then it is -possible to save storage and reduce the number of heap allocations. The -newly constructed object and the _Sp_counted_* can be allocated in a single -block and the standard says implementations are "encouraged, but not required," -to do so. This implementation provides additional non-standard constructors -(selected with the type _Sp_make_shared_tag) which create an -object of type _Sp_counted_ptr_inplace to hold the new object. -The returned shared_ptr<A> needs to know the address of the -new A object embedded in the _Sp_counted_ptr_inplace, -but it has no way to access it. -This implementation uses a "covert channel" to return the address of the -embedded object when get_deleter<_Sp_make_shared_tag>() -is called. Users should not try to use this. -As well as the extra constructors, this implementation also needs some -members of _Sp_counted_deleter to be protected where they could otherwise -be private. -

        Use

        Examples

        - Examples of use can be found in the testsuite, under - testsuite/tr1/2_general_utilities/shared_ptr. -

        Unresolved Issues

        - The resolution to C++ Standard Library issue 674, - "shared_ptr interface changes for consistency with N1856" will - need to be implemented after it is accepted into the working - paper. Issue 743 - might also require changes. -

        - The _S_single policy uses atomics when used in MT - code, because it uses the same dispatcher functions that check - __gthread_active_p(). This could be - addressed by providing template specialisations for some members - of _Sp_counted_base<_S_single>. -

        - Unlike Boost, this implementation does not use separate classes - for the pointer+deleter and pointer+deleter+allocator cases in - C++0x mode, combining both into _Sp_counted_deleter and using - allocator when the user doesn't specify - an allocator. If it was found to be beneficial an additional - class could easily be added. With the current implementation, - the _Sp_counted_deleter and __shared_count constructors taking a - custom deleter but no allocator are technically redundant and - could be removed, changing callers to always specify an - allocator. If a separate pointer+deleter class was added the - __shared_count constructor would be needed, so it has been kept - for now. -

        - The hack used to get the address of the managed object from - _Sp_counted_ptr_inplace::_M_get_deleter() - is accessible to users. This could be prevented if - get_deleter<_Sp_make_shared_tag>() - always returned NULL, since the hack only needs to work at a - lower level, not in the public API. This wouldn't be difficult, - but hasn't been done since there is no danger of accidental - misuse: users already know they are relying on unsupported - features if they refer to implementation details such as - _Sp_make_shared_tag. -

        - tr1::_Sp_deleter could be a private member of tr1::__shared_count but it - would alter the ABI. -

        - Exposing the alias constructor in TR1 mode could simplify the - *_pointer_cast functions. Constructor could be private in TR1 - mode, with the cast functions as friends. -

        Acknowledgments

        - The original authors of the Boost shared_ptr, which is really nice - code to work with, Peter Dimov in particular for his help and - invaluable advice on thread safety. Phillip Jordan and Paolo - Carlini for the lock policy implementation. -

        Bibliography

        [ - n2351 - ] - Improving shared_ptr for C++0x, Revision 2 - . - N2351 - . - - - .

        [ - n2456 - ] - C++ Standard Library Active Issues List (Revision R52) - . - N2456 - . - - - .

        [ - n2461 - ] - Working Draft, Standard for Programming Language C++ - . - N2461 - . - - - .

        [ - boostshared_ptr - ] - Boost C++ Libraries documentation - shared_ptr class template - . - N2461 - . - shared_ptr - - .

        Prev Up Next
        auto_ptr Home Chapter 12. Traits
        diff --git a/libstdc++-v3/doc/html/manual/source_code_style.html b/libstdc++-v3/doc/html/manual/source_code_style.html index 8b9932cd032..dc4e49067ff 100644 --- a/libstdc++-v3/doc/html/manual/source_code_style.html +++ b/libstdc++-v3/doc/html/manual/source_code_style.html @@ -60,7 +60,7 @@       these names as operators have been fixed.]

              The full set of __* identifiers (combined from gcc/cp/lex.c and
        -      gcc/cplus-dem.c) that are either old or new, but are definitely 
        +      gcc/cplus-dem.c) that are either old or new, but are definitely
              recognized by the demangler, is:

              __aa
        @@ -225,8 +225,8 @@       -NOT-
              char *p = "flop";  // wrong
              char &c = *p;      // wrong
        -      
        -      Reason: In C++, definitions are mixed with executable code. Here,       
        +
        +      Reason: In C++, definitions are mixed with executable code. Here,
              p is being initialized, not *p. This is near-universal
              practice among C++ programmers; it is normal for C hackers
              to switch spontaneously as they gain experience.
        @@ -235,9 +235,9 @@       operator==(type)
              -NOT-
              operator == (type)  // wrong
        -      
        +
              Reason: The == is part of the function name. Separating
        -      it makes the declaration look like an expression. 
        +      it makes the declaration look like an expression.

              03. Function names and parentheses
              void mangle()
        @@ -246,22 +246,22 @@
              Reason: no space before parentheses (except after a control-flow
              keyword) is near-universal practice for C++. It identifies the
        -      parentheses as the function-call operator or declarator, as 
        +      parentheses as the function-call operator or declarator, as
              opposed to an expression or other overloaded use of parentheses.

              04. Template function indentation
              template<typename T>
        -      void 
        +      void
              template_function(args)
              { }
              -NOT-
              template<class T>
              void template_function(args) {};
        -      
        +
              Reason: In class definitions, without indentation whitespace is
              needed both above and below the declaration to distinguish
              it visually from other members. (Also, re: "typename"
        -      rather than "class".)  T often could be int, which is 
        +      rather than "class".)  T often could be int, which is
              not a class. ("class", here, is an anachronism.)

              05. Template class indentation
        @@ -299,7 +299,7 @@       07. Member initialization lists
              All one line, separate from class name.

        -      gribble::gribble() 
        +      gribble::gribble()
              : _M_private_data(0), _M_more_stuff(0), _M_helper(0);
              { }
              -NOT-
        @@ -307,18 +307,18 @@       { }

              08. Try/Catch blocks
        -      try 
        +      try
              {
              //
        -      }   
        +      }
              catch (...)
              {
              //
        -      }   
        +      }
              -NOT-
              try {
        -      // 
        -      } catch(...) { 
        +      //
        +      } catch(...) {
              //
              }

        @@ -326,7 +326,7 @@       Keywords such as extern, static, export, explicit, inline, etc
              go on the line above the function name. Thus

        -      virtual int   
        +      virtual int
              foo()
              -NOT-
              virtual int foo()
        @@ -369,7 +369,7 @@
              -NOT-
              public:
        -      
        +
              int foo;

              13. Spacing WRT return statements.
        @@ -428,17 +428,17 @@
              Name patterns:

        -      For nonstandard names appearing in Standard headers, we are constrained 
        +      For nonstandard names appearing in Standard headers, we are constrained
              to use names that begin with underscores. This is called "uglification".
              The convention is:

              Local and argument names:  __[a-z].*

        -      Examples:  __count  __ix  __s1  
        +      Examples:  __count  __ix  __s1

              Type names and template formal-argument names: _[A-Z][^_].*

        -      Examples:  _Helper  _CharT  _N 
        +      Examples:  _Helper  _CharT  _N

              Member data and function names: _M_.*

        @@ -448,7 +448,7 @@
              Examples: _S_max_elements  _S_default_value

        -      Don't use names in the same scope that differ only in the prefix, 
        +      Don't use names in the same scope that differ only in the prefix,
              e.g. _S_top and _M_top. See BADNAMES for a list of forbidden names.
              (The most tempting of these seem to be and "_T" and "__sz".)

        @@ -458,7 +458,7 @@       --------------------------

              [BY EXAMPLE]
        -      
        +
              #ifndef  _HEADER_
              #define  _HEADER_ 1

        @@ -471,37 +471,37 @@
              gribble(const gribble&);

        -      explicit 
        +      explicit
              gribble(int __howmany);

        -      gribble& 
        +      gribble&
              operator=(const gribble&);

        -      virtual 
        +      virtual
              ~gribble() throw ();

              // Start with a capital letter, end with a period.
        -      inline void  
        +      inline void
              public_member(const char* __arg) const;

              // In-class function definitions should be restricted to one-liners.
        -      int 
        +      int
              one_line() { return 0 }

        -      int 
        -      two_lines(const char* arg) 
        +      int
        +      two_lines(const char* arg)
              { return strchr(arg, 'a'); }

        -      inline int 
        +      inline int
              three_lines();  // inline, but defined below.

              // Note indentation.
              template<typename _Formal_argument>
        -      void 
        +      void
              public_template() const throw();

              template<typename _Iterator>
        -      void 
        +      void
              other_template();

              private:
        @@ -512,13 +512,13 @@       _Helper* _M_helper;
              int _M_private_function();

        -      enum _Enum 
        -      { 
        -      _S_one, 
        -      _S_two 
        +      enum _Enum
        +      {
        +      _S_one,
        +      _S_two
              };

        -      static void 
        +      static void
              _S_initialize_library();
              };

        @@ -548,20 +548,20 @@       #endif /* _HEADER_ */


        -      namespace std 
        +      namespace std
              {
              template<typename T>  // notice: "typename", not "class", no space
        -      long_return_value_type<with_many, args>  
        +      long_return_value_type<with_many, args>
              function_name(char* pointer,               // "char *pointer" is wrong.
        -      char* argument, 
        +      char* argument,
              const Reference& ref)
              {
              // int a_local;  /* wrong; see below. */
        -      if (test) 
        -      { 
        -      nested code 
        +      if (test)
        +      {
        +      nested code
              }
        -      
        +
              int a_local = 0;  // declare variable at first use.

              //  char a, b, *p;   /* wrong */
        @@ -574,12 +574,12 @@       // ...
              }
              }
        -      
        +
              gribble::gribble()
              : _M_private_data(0), _M_more_stuff(0), _M_helper(0);
              { }

        -      inline int 
        +      inline int
              gribble::three_lines()
              {
              // doesn't fit in one line.
        diff --git a/libstdc++-v3/doc/html/manual/source_organization.html b/libstdc++-v3/doc/html/manual/source_organization.html index 2ac9f9041a3..4cb92481af7 100644 --- a/libstdc++-v3/doc/html/manual/source_organization.html +++ b/libstdc++-v3/doc/html/manual/source_organization.html @@ -20,26 +20,26 @@ It has subdirectories:

            include/std
              Files meant to be found by #include <name> directives in
        -      standard-conforming user programs.  
        +      standard-conforming user programs.

            include/c
        -      Headers intended to directly include standard C headers. 
        +      Headers intended to directly include standard C headers.
              [NB: this can be enabled via --enable-cheaders=c]

        -    include/c_global 
        +    include/c_global
              Headers intended to include standard C headers in
              the global namespace, and put select names into the std::
              namespace.  [NB: this is the default, and is the same as
              --enable-cheaders=c_global]

        -    include/c_std 
        +    include/c_std
              Headers intended to include standard C headers
              already in namespace std, and put select names into the std::
              namespace.  [NB: this is the same as --enable-cheaders=c_std]

            include/bits
              Files included by standard headers and by other files in
        -      the bits directory. 
        +      the bits directory.

            include/backward
              Headers provided for backward compatibility, such as <iostream.h>.
        @@ -58,7 +58,7 @@ It has subdirectories:
            installed.

          testsuites/[backward, demangle, ext, performance, thread, 17_* to 27_*]
        -    Test programs are here, and may be used to begin to exercise the 
        +    Test programs are here, and may be used to begin to exercise the
            library.  Support for "make check" and "make check-install" is
            complete, and runs through all the subdirectories here when this
            command is issued from the build directory.  Please note that
        diff --git a/libstdc++-v3/doc/html/manual/spine.html b/libstdc++-v3/doc/html/manual/spine.html index f5e3d1ebd3a..bbc038e09bd 100644 --- a/libstdc++-v3/doc/html/manual/spine.html +++ b/libstdc++-v3/doc/html/manual/spine.html @@ -2,48 +2,58 @@ The GNU C++ Library
        The GNU C++ Library
        Prev   Next

        The GNU C++ Library

        Copyright © 2009, 2010 FSF -

        Table of Contents

        I. Introduction -
        1. Status
        Implementation Status
        C++ 1998/2003
        C++ 200x
        C++ TR1
        C++ TR 24733
        License
        The Code: GPL
        The Documentation: GPL, FDL
        Bugs
        Implementation Bugs
        Standard Bugs
        2. Setup
        Prerequisites
        Configure
        Make
        3. Using
        Command Options
        Headers
        Header Files
        Mixing Headers
        The C Headers and namespace std
        Precompiled Headers
        Macros
        Namespaces
        Available Namespaces
        namespace std
        Using Namespace Composition
        Linking
        Almost Nothing
        Finding Dynamic or Shared Libraries
        Concurrency
        Prerequisites
        Thread Safety
        Atomics
        IO
        Containers
        Exceptions
        Exception Safety
        Exception Neutrality
        Doing without
        Compatibility
        Debugging Support
        Using g++
        Debug Versions of Library Binary Files
        Memory Leak Hunting
        Using gdb
        Tracking uncaught exceptions
        Debug Mode
        Compile Time Checking
        Profile-based Performance Analysis
        II. +
        1. Status
        Implementation Status
        C++ 1998/2003
        C++ 200x
        C++ TR1
        C++ TR 24733
        License
        The Code: GPL
        The Documentation: GPL, FDL
        Bugs
        Implementation Bugs
        Standard Bugs
        2. Setup
        Prerequisites
        Configure
        Make
        3. Using
        Command Options
        Headers
        Header Files
        Mixing Headers
        The C Headers and namespace std
        Precompiled Headers
        Macros
        Namespaces
        Available Namespaces
        namespace std
        Using Namespace Composition
        Linking
        Almost Nothing
        Finding Dynamic or Shared Libraries
        Concurrency
        Prerequisites
        Thread Safety
        Atomics
        IO
        Containers
        Exceptions
        Exception Safety
        Exception Neutrality
        Doing without
        Compatibility
        Debugging Support
        Using g++
        Debug Versions of Library Binary Files
        Memory Leak Hunting
        Using gdb
        Tracking uncaught exceptions
        Debug Mode
        Compile Time Checking
        Profile-based Performance Analysis
        II. + Standard Contents +
        4. Support -
        4. Types
        Fundamental Types
        Numeric Properties
        NULL
        5. Dynamic Memory
        6. Termination
        Termination Handlers
        Verbose Terminate Handler
        III. +
        Types
        Fundamental Types
        Numeric Properties
        NULL
        Dynamic Memory
        Termination
        Termination Handlers
        Verbose Terminate Handler
        5. Diagnostics -
        7. Exceptions
        Exception Classes
        Adding Data to Exceptions
        8. Concept Checking
        IV. +
        Exceptions
        API Reference
        Adding Data to exception
        Concept Checking
        6. Utilities -
        9. Functors
        10. Pairs
        11. Memory
        Allocators
        Requirements
        Design Issues
        Implementation
        Using a Specific Allocator
        Custom Allocators
        Extension Allocators
        auto_ptr
        Limitations
        Use in Containers
        shared_ptr
        Requirements
        Design Issues
        Implementation
        Use
        Acknowledgments
        12. Traits
        V. +
        Functors
        Pairs
        Memory
        Allocators
        auto_ptr
        shared_ptr
        Traits
        7. Strings -
        13. String Classes
        Simple Transformations
        Case Sensitivity
        Arbitrary Character Types
        Tokenizing
        Shrink to Fit
        CString (MFC)
        VI. +
        String Classes
        Simple Transformations
        Case Sensitivity
        Arbitrary Character Types
        Tokenizing
        Shrink to Fit
        CString (MFC)
        8. Localization -
        14. Locales
        locale
        Requirements
        Design
        Implementation
        Future
        15. Facets aka Categories
        ctype
        Implementation
        Future
        codecvt
        Requirements
        Design
        Implementation
        Use
        Future
        messages
        Requirements
        Design
        Implementation
        Use
        Future
        VII. +
        Locales
        locale
        Facets
        ctype
        codecvt
        messages
        9. Containers -
        16. Sequences
        list
        list::size() is O(n)
        vector
        Space Overhead Management
        17. Associative
        Insertion Hints
        bitset
        Size Variable
        Type String
        18. Interacting with C
        Containers vs. Arrays
        VIII. +
        Sequences
        list
        vector
        Associative
        Insertion Hints
        bitset
        Interacting with C
        Containers vs. Arrays
        10. Iterators -
        19. Predefined
        Iterators vs. Pointers
        One Past the End
        IX. +
        Predefined
        Iterators vs. Pointers
        One Past the End
        11. Algorithms -
        20. Mutating
        swap
        Specializations
        X. +
        Mutating
        swap
        12. Numerics -
        21. Complex
        complex Processing
        22. Generalized Operations
        23. Interacting with C
        Numerics vs. Arrays
        C99
        XI. +
        Complex
        complex Processing
        Generalized Operations
        Interacting with C
        Numerics vs. Arrays
        C99
        13. Input and Output -
        24. Iostream Objects
        25. Stream Buffers
        Derived streambuf Classes
        Buffering
        26. Memory Based Streams
        Compatibility With strstream
        27. File Based Streams
        Copying a File
        Binary Input and Output
        28. Interacting with C
        Using FILE* and file descriptors
        Performance
        XII. +
        Iostream Objects
        Stream Buffers
        Derived streambuf Classes
        Buffering
        Memory Based Streams
        Compatibility With strstream
        File Based Streams
        Copying a File
        Binary Input and Output
        Interacting with C
        Using FILE* and file descriptors
        Performance
        14. + Atomics + +
        API Reference
        15. + Concurrency + +
        API Reference
        III. Extensions -
        29. Compile Time Checks
        30. Debug Mode
        Intro
        Semantics
        Using
        Using the Debug Mode
        Using a Specific Debug Container
        Design
        Goals
        Methods
        Other Implementations
        31. Parallel Mode
        Intro
        Semantics
        Using
        Prerequisite Compiler Flags
        Using Parallel Mode
        Using Specific Parallel Components
        Design
        Interface Basics
        Configuration and Tuning
        Implementation Namespaces
        Testing
        Bibliography
        32. Profile Mode
        Intro
        Using the Profile Mode
        Tuning the Profile Mode
        Design
        Wrapper Model
        Instrumentation
        Run Time Behavior
        Analysis and Diagnostics
        Cost Model
        Reports
        Testing
        Extensions for Custom Containers
        Empirical Cost Model
        Implementation Issues
        Stack Traces
        Symbolization of Instruction Addresses
        Concurrency
        Using the Standard Library in the Instrumentation Implementation
        Malloc Hooks
        Construction and Destruction of Global Objects
        Developer Information
        Big Picture
        How To Add A Diagnostic
        Diagnostics
        Diagnostic Template
        Containers
        Algorithms
        Data Locality
        Multithreaded Data Access
        Statistics
        Bibliography
        33. Allocators
        mt_allocator
        Intro
        Design Issues
        Implementation
        Single Thread Example
        Multiple Thread Example
        bitmap_allocator
        Design
        Implementation
        34. Containers
        Policy Based Data Structures
        HP/SGI
        Deprecated HP/SGI
        35. Utilities
        36. Algorithms
        37. Numerics
        38. Iterators
        39. Input and Output
        Derived filebufs
        40. Demangling
        41. Concurrency
        Design
        Interface to Locks and Mutexes
        Interface to Atomic Functions
        Implementation
        Using Builtin Atomic Functions
        Thread Abstraction
        Use
        A. +
        16. Compile Time Checks
        17. Debug Mode
        Intro
        Semantics
        Using
        Using the Debug Mode
        Using a Specific Debug Container
        Design
        Goals
        Methods
        Other Implementations
        18. Parallel Mode
        Intro
        Semantics
        Using
        Prerequisite Compiler Flags
        Using Parallel Mode
        Using Specific Parallel Components
        Design
        Interface Basics
        Configuration and Tuning
        Implementation Namespaces
        Testing
        Bibliography
        19. Profile Mode
        Intro
        Using the Profile Mode
        Tuning the Profile Mode
        Design
        Wrapper Model
        Instrumentation
        Run Time Behavior
        Analysis and Diagnostics
        Cost Model
        Reports
        Testing
        Extensions for Custom Containers
        Empirical Cost Model
        Implementation Issues
        Stack Traces
        Symbolization of Instruction Addresses
        Concurrency
        Using the Standard Library in the Instrumentation Implementation
        Malloc Hooks
        Construction and Destruction of Global Objects
        Developer Information
        Big Picture
        How To Add A Diagnostic
        Diagnostics
        Diagnostic Template
        Containers
        Algorithms
        Data Locality
        Multithreaded Data Access
        Statistics
        Bibliography
        20. Allocators
        mt_allocator
        Intro
        Design Issues
        Implementation
        Single Thread Example
        Multiple Thread Example
        bitmap_allocator
        Design
        Implementation
        21. Containers
        Policy Based Data Structures
        HP/SGI
        Deprecated HP/SGI
        22. Utilities
        23. Algorithms
        24. Numerics
        25. Iterators
        26. Input and Output
        Derived filebufs
        27. Demangling
        28. Concurrency
        Design
        Interface to Locks and Mutexes
        Interface to Atomic Functions
        Implementation
        Using Builtin Atomic Functions
        Thread Abstraction
        Use
        IV. + Appendices +
        A. Contributing -
        Contributor Checklist
        Reading
        Assignment
        Getting Sources
        Submitting Patches
        Directory Layout and Source Conventions
        Coding Style
        Bad Identifiers
        By Example
        Documentation Style
        Doxygen
        Docbook
        Design Notes
        B. +
        Contributor Checklist
        Reading
        Assignment
        Getting Sources
        Submitting Patches
        Directory Layout and Source Conventions
        Coding Style
        Bad Identifiers
        By Example
        Documentation Style
        Doxygen
        Docbook
        Combines
        Design Notes
        B. Porting and Maintenance
        Configure and Build Hacking
        Prerequisites
        Overview: What Comes from Where
        Storing Information in non-AC files (like configure.host)
        Coding and Commenting Conventions
        The acinclude.m4 layout
        GLIBCXX_ENABLE, the --enable maker
        Porting to New Hardware or Operating Systems
        Operating System
        CPU
        Character Types
        Thread Safety
        Numeric Limits
        Libtool
        Test
        Organization
        Running the Testsuite
        Writing a new test case
        Test Harness and Utilities
        Special Topics
        ABI Policy and Guidelines
        The C++ Interface
        Versioning
        Allowed Changes
        Prohibited Changes
        Implementation
        Testing
        Outstanding Issues
        API Evolution and Deprecation History
        3.0
        3.1
        3.2
        3.3
        3.4
        4.0
        4.1
        4.2
        4.3
        4.4
        4.5
        Backwards Compatibility
        First
        Second
        Third
        C. @@ -51,7 +61,7 @@
        D. GNU General Public License version 3 -
        E. GNU Free Documentation License
        Index

        List of Tables

        1.1. C++ 1998/2003 Implementation Status
        1.2. C++ 200x Implementation Status
        1.3. C++ TR1 Implementation Status
        1.4. C++ TR 24733 Implementation Status
        3.1. C++ Command Options
        3.2. C++ 1998 Library Headers
        3.3. C++ 1998 Library Headers for C Library Facilities
        3.4. C++ 200x Library Headers
        3.5. C++ 200x Library Headers for C Library Facilities
        3.6. C++ TR 1 Library Headers
        3.7. C++ TR 1 Library Headers for C Library Facilities
        3.8. C++ TR 24733 Decimal Floating-Point Header
        3.9. C++ ABI Headers
        3.10. Extension Headers
        3.11. Extension Debug Headers
        3.12. Extension Profile Headers
        3.13. Extension Parallel Headers
        30.1. Debugging Containers
        30.2. Debugging Containers C++0x
        31.1. Parallel Algorithms
        32.1. Code Location
        32.2. Diagnostics
        33.1. Bitmap Allocator Memory Map
        A.1. HTML to Doxygen markup comparison
        A.2. HTML to Docbook XML markup comparison
        A.3. Docbook XML Element Use
        B.1. Extension Allocators
        B.2. Extension Allocators Continued
        Prev   Next
        The GNU C++ Library Documentation Home Part I.  +
        E. GNU Free Documentation License

        List of Tables

        1.1. C++ 1998/2003 Implementation Status
        1.2. C++ 200x Implementation Status
        1.3. C++ TR1 Implementation Status
        1.4. C++ TR 24733 Implementation Status
        3.1. C++ Command Options
        3.2. C++ 1998 Library Headers
        3.3. C++ 1998 Library Headers for C Library Facilities
        3.4. C++ 200x Library Headers
        3.5. C++ 200x Library Headers for C Library Facilities
        3.6. C++ TR 1 Library Headers
        3.7. C++ TR 1 Library Headers for C Library Facilities
        3.8. C++ TR 24733 Decimal Floating-Point Header
        3.9. C++ ABI Headers
        3.10. Extension Headers
        3.11. Extension Debug Headers
        3.12. Extension Profile Headers
        3.13. Extension Parallel Headers
        17.1. Debugging Containers
        17.2. Debugging Containers C++0x
        18.1. Parallel Algorithms
        19.1. Profile Code Location
        19.2. Profile Diagnostics
        20.1. Bitmap Allocator Memory Map
        A.1. HTML to Doxygen Markup Comparison
        A.2. HTML to Docbook XML Markup Comparison
        A.3. Docbook XML Element Use
        B.1. Extension Allocators
        B.2. Extension Allocators Continued
        Prev   Next
        The GNU C++ Library Documentation Home Part I.  Introduction
        diff --git a/libstdc++-v3/doc/html/manual/status.html b/libstdc++-v3/doc/html/manual/status.html index be894aa296d..2dd8c691a68 100644 --- a/libstdc++-v3/doc/html/manual/status.html +++ b/libstdc++-v3/doc/html/manual/status.html @@ -8,7 +8,7 @@ This status table is based on the table of contents of ISO/IEC 14882:2003.

        This page describes the C++ support in mainline GCC SVN, not in any particular release. -

        Table 1.1. C++ 1998/2003 Implementation Status

        SectionDescriptionStatusComments
        +

        Table 1.1. C++ 1998/2003 Implementation Status

        SectionDescriptionStatusComments
        18 Language support @@ -58,8 +58,8 @@ particular release. [1.3.5] implementation-defined behavior

        Behavior, for a well-formed program construct and correct data, that - depends on the implementation and that each implementation - shall document. + depends on the implementation and that each implementation + shall document.

        We do so here, for the C++ library only. Behavior of the compiler, linker, runtime loader, and other elements of "the @@ -76,7 +76,7 @@ particular release. [17.4.4.5] Non-reentrant functions are probably best discussed in the various sections on multithreading (see above).

        [18.1]/4 The type of NULL is described - here. + here.

        [18.3]/8 Even though it's listed in the library sections, libstdc++ has zero control over what the cleanup code hands back to the runtime loader. Talk to the compiler people. :-) @@ -90,7 +90,7 @@ particular release. class. But they are the mangled names; you will need to call c++filt and pass the names as command-line parameters to demangle them, or call a - runtime demangler function. + runtime demangler function. (The classes in <stdexcept> have constructors which require an argument to use later for what() calls, so the problem of what()'s value does not arise in most @@ -117,11 +117,11 @@ particular release. here would defeat the purpose. :-)

        [21.1.3.1]/5 I don't really know about the mbstate_t stuff... see - the chapter 22 + the chapter 22 notes for what does exist.

        [22.*] Anything and everything we have on locale implementation will be described - over here. + over here.

        [26.2.8]/9 I have no idea what complex<T>'s pow(0,0) returns.

        [27.4.2.4]/2 Calling @@ -139,11 +139,11 @@ particular release.

        [27.7.1.3]/16, [27.8.1.4]/10 The effects of pubsetbuf/setbuf are described - in this chapter. + in this chapter.

        [27.8.1.4]/16 Calling fstream::sync when a get area exists will... whatever fflush() does, I think.

        C++ 200x

        -This table is based on the table of contents of ISO/IEC +This table is based on the table of contents of ISO/IEC Doc No: N3000=09-0190 Date: 2009-11-09 Working Draft, Standard for Programming Language C++

        @@ -157,7 +157,7 @@ presence of the required flag.

        This page describes the C++0x support in mainline GCC SVN, not in any particular release. -

        Table 1.2. C++ 200x Implementation Status

        SectionDescriptionStatusComments
        +

        Table 1.2. C++ 200x Implementation Status

        SectionDescriptionStatusComments
        18 Language support @@ -173,7 +173,7 @@ particular release.

        Uses code from boost::shared_ptr. -

        +

        20.8.13.3Class template weak_ptrY 
        20.8.13.4Class template owner_lessY 
        20.8.13.5Class template emable_shared_from_thisY 
        20.8.13.6shared_ptr atomic accessPartial 
        20.8.13.7Pointer safetyPartial 
        20.8.14AlignN 
        20.8.15C libraryY 
        20.9Time utilities  
        20.9.1Clock requirementsY 
        20.9.2Time-related traits  
        20.9.2.1treat_as_floating_pointY 
        20.9.2.2duration_valuesPartialMissing constexpr
        20.9.2.3Specializations of common_typeY 
        20.9.3Class template durationPartialMissing constexpr
        20.9.4Class template time_pointPartialMissing constexpr
        20.9.5Clocks  
        20.9.5.1Class system_clockY 
        20.9.5.2Class monotonic_clockY 
        20.9.5.3Class high_resolution_clockY 
        20.10Date and time functionsY 
        21 @@ -229,11 +229,11 @@ In this implementation the header names are prefixed by

        This page describes the TR1 support in mainline GCC SVN, not in any particular release. -

        Table 1.3. C++ TR1 Implementation Status

        SectionDescriptionStatusComments
        2General Utilities
        2.1Reference wrappers  
        2.1.1Additions to header <functional> synopsisY 
        2.1.2Class template reference_wrapper  
        2.1.2.1reference_wrapper construct/copy/destroyY 
        2.1.2.2reference_wrapper assignmentY 
        2.1.2.3reference_wrapper accessY 
        2.1.2.4reference_wrapper invocationY 
        2.1.2.5reference_wrapper helper functionsY 
        2.2Smart pointers  
        2.2.1Additions to header <memory> synopsisY 
        2.2.2Class bad_weak_ptrY 
        2.2.3Class template shared_ptr  +

        Table 1.3. C++ TR1 Implementation Status

        SectionDescriptionStatusComments
        2General Utilities
        2.1Reference wrappers  
        2.1.1Additions to header <functional> synopsisY 
        2.1.2Class template reference_wrapper  
        2.1.2.1reference_wrapper construct/copy/destroyY 
        2.1.2.2reference_wrapper assignmentY 
        2.1.2.3reference_wrapper accessY 
        2.1.2.4reference_wrapper invocationY 
        2.1.2.5reference_wrapper helper functionsY 
        2.2Smart pointers  
        2.2.1Additions to header <memory> synopsisY 
        2.2.2Class bad_weak_ptrY 
        2.2.3Class template shared_ptr 

        Uses code from boost::shared_ptr. -

        +

        2.2.3.1shared_ptr constructorsY 
        2.2.3.2shared_ptr destructorY 
        2.2.3.3shared_ptr assignmentY 
        2.2.3.4shared_ptr modifiersY 
        2.2.3.5shared_ptr observersY 
        2.2.3.6shared_ptr comparisonY 
        2.2.3.7shared_ptr I/OY 
        2.2.3.8shared_ptr specialized algorithmsY 
        2.2.3.9shared_ptr castsY 
        2.2.3.10get_deleterY 
        2.2.4Class template weak_ptr  
        2.2.4.1weak_ptr constructorsY 
        2.2.4.2weak_ptr destructorY 
        2.2.4.3weak_ptr assignmentY 
        2.2.4.4weak_ptr modifiersY 
        2.2.4.5weak_ptr observersY 
        2.2.4.6weak_ptr comparisonY 
        2.2.4.7weak_ptr specialized algorithmsY 
        2.2.5Class template enable_shared_from_thisY 
        3Function Objects
        3.1DefinitionsY 
        3.2Additions to <functional> synopsisY 
        3.3RequirementsY 
        3.4Function return typesY 
        3.5Function template mem_fnY 
        3.6Function object binders  
        3.6.1Class template is_bind_expressionY 
        3.6.2Class template is_placeholderY 
        3.6.3Function template bindY 
        3.6.4PlaceholdersY 
        3.7Polymorphic function wrappers  
        3.7.1Class bad_function_callY 
        3.7.1.1bad_function_call constructorY 
        3.7.2Class template function  
        3.7.2.1function construct/copy/destroyY 
        3.7.2.2function modifiersY 
        3.7.2.3function capacityY 
        3.7.2.4function invocationY 
        3.7.2.5function target accessY 
        3.7.2.6undefined operatorsY 
        3.7.2.7null pointer comparison operatorsY 
        3.7.2.8specialized algorithmsY 
        4Metaprogramming and type traits
        4.1RequirementsY 
        4.2Header <type_traits> synopsisY 
        4.3Helper classesY 
        4.4General RequirementsY 
        4.5Unary Type Traits  
        4.5.1Primary Type CategoriesY 
        4.5.2Composite type traitsY 
        4.5.3Type propertiesY 
        4.6Relationships between typesY 
        4.7Transformations between types  
        4.7.1Const-volatile modificationsY 
        4.7.2Reference modificationsY 
        4.7.3Array modificationsY 
        4.7.4Pointer modificationsY 
        4.8Other transformationsY 
        4.9Implementation requirementsY 
        5Numerical Facilities
        5.1Random number generation  
        5.1.1RequirementsY 
        5.1.2Header <random> synopsisY 
        5.1.3Class template variate_generatorY 
        5.1.4Random number engine class templatesY 
        5.1.4.1Class template linear_congruentialY 
        5.1.4.2Class template mersenne_twisterY 
        5.1.4.3Class template subtract_with_carryY 
        5.1.4.4Class template subtract_with_carry_01Y 
        5.1.4.5Class template discard_blockY 
        5.1.4.6Class template xor_combineYoperator()() per N2079
        5.1.5Engines with predefined parametersY 
        5.1.6Class random_deviceY 
        5.1.7Random distribution class templatesY 
        5.1.7.1Class template uniform_intY 
        5.1.7.2Class bernoulli_distributionY 
        5.1.7.3Class template geometric_distributionY 
        5.1.7.4Class template poisson_distributionY 
        5.1.7.5Class template binomial_distributionY 
        5.1.7.6Class template uniform_realY 
        5.1.7.7Class template exponential_distributionY 
        5.1.7.8Class template normal_distributionY 
        5.1.7.9Class template gamma_distributionY 
        5.2Mathematical special functionsY 
        5.2.1Additions to header <cmath> synopsisY 
        5.2.1.1associated Laguerre polynomialsY 
        5.2.1.2associated Legendre functionsY 
        5.2.1.3beta functionY 
        5.2.1.4(complete) elliptic integral of the first kindY 
        5.2.1.5(complete) elliptic integral of the second kindY 
        5.2.1.6(complete) elliptic integral of the third kindY 
        5.2.1.7confluent hypergeometric functionsY 
        5.2.1.8regular modified cylindrical Bessel functionsY 
        5.2.1.9cylindrical Bessel functions (of the first kind)Y 
        5.2.1.10irregular modified cylindrical Bessel functionsY 
        5.2.1.11cylindrical Neumann functionsY 
        5.2.1.12(incomplete) elliptic integral of the first kindY 
        5.2.1.13(incomplete) elliptic integral of the second kindY 
        5.2.1.14(incomplete) elliptic integral of the third kindY 
        5.2.1.15exponential integralY 
        5.2.1.16Hermite polynomialsY 
        5.2.1.17hypergeometric functionsY 
        5.2.1.18Laguerre polynomialsY 
        5.2.1.19Legendre polynomialsY 
        5.2.1.20Riemann zeta functionY 
        5.2.1.21spherical Bessel functions (of the first kind)Y 
        5.2.1.22spherical associated Legendre functionsY 
        5.2.1.23spherical Neumann functionsY 
        5.2.2Additions to header <math.h> synopsisY 
        6Containers
        6.1Tuple typesY 
        6.1.1Header <tuple> synopsisY 
        6.1.2Additions to header <utility> synopsisY 
        6.1.3Class template tupleY 
        6.1.3.1ConstructionY 
        6.1.3.2Tuple creation functionsY 
        6.1.3.3Tuple helper classesY 
        6.1.3.4Element accessY 
        6.1.3.5Relational operatorsY 
        6.1.4PairsY 
        6.2Fixed size arrayY 
        6.2.1Header <array> synopsisY 
        6.2.2Class template arrayY 
        6.2.2.1array constructors, copy, and assignmentY 
        6.2.2.2array specialized algorithmsY 
        6.2.2.3array sizeY 
        6.2.2.4Zero sized arraysY 
        6.2.2.5Tuple interface to class template arrayY 
        6.3Unordered associative containersY 
        6.3.1Unordered associative container requirementsY 
        6.3.1.1Exception safety guaranteesY 
        6.3.2Additions to header <functional> synopsisY 
        6.3.3Class template hashY 
        6.3.4Unordered associative container classesY 
        6.3.4.1Header <unordered_set> synopsisY 
        6.3.4.2Header <unordered_map> synopsisY 
        6.3.4.3Class template unordered_setY 
        6.3.4.3.1unordered_set constructorsY 
        6.3.4.3.2unordered_set swapY 
        6.3.4.4Class template unordered_mapY 
        6.3.4.4.1unordered_map constructorsY 
        6.3.4.4.2unordered_map element accessY 
        6.3.4.4.3unordered_map swapY 
        6.3.4.5Class template unordered_multisetY 
        6.3.4.5.1unordered_multiset constructorsY 
        6.3.4.5.2unordered_multiset swapY 
        6.3.4.6Class template unordered_multimapY 
        6.3.4.6.1unordered_multimap constructorsY 
        6.3.4.6.2unordered_multimap swapY 
        7Regular Expressions
        7.1DefinitionsN 
        7.2RequirementsN 
        7.3Regular expressions summaryN 
        7.4Header <regex> synopsisN 
        7.5Namespace tr1::regex_constantsN 
        7.5.1Bitmask Type syntax_option_typeN 
        7.5.2Bitmask Type regex_constants::match_flag_typeN 
        7.5.3Implementation defined error_typeN 
        7.6Class regex_errorN 
        7.7Class template regex_traitsN 
        7.8Class template basic_regexN 
        7.8.1basic_regex constantsN 
        7.8.2basic_regex constructorsN 
        7.8.3basic_regex assignN 
        7.8.4basic_regex constant operationsN 
        7.8.5basic_regex localeN 
        7.8.6basic_regex swapN 
        7.8.7basic_regex non-member functionsN 
        7.8.7.1basic_regex non-member swapN 
        7.9Class template sub_matchN 
        7.9.1sub_match membersN 
        7.9.2sub_match non-member operatorsN 
        7.10Class template match_resultsN 
        7.10.1match_results constructorsN 
        7.10.2match_results sizeN 
        7.10.3match_results element accessN 
        7.10.4match_results formattingN 
        7.10.5match_results allocatorN 
        7.10.6match_results swapN 
        7.11Regular expression algorithmsN 
        7.11.1exceptionsN 
        7.11.2regex_matchN 
        7.11.3regex_searchN 
        7.11.4regex_replaceN 
        7.12Regular expression IteratorsN 
        7.12.1Class template regex_iteratorN 
        7.12.1.1regex_iterator constructorsN 
        7.12.1.2regex_iterator comparisonsN 
        7.12.1.3regex_iterator dereferenceN 
        7.12.1.4regex_iterator incrementN 
        7.12.2Class template regex_token_iteratorN 
        7.12.2.1regex_token_iterator constructorsN 
        7.12.2.2regex_token_iterator comparisonsN 
        7.12.2.3regex_token_iterator dereferenceN 
        7.12.2.4regex_token_iterator incrementN 
        7.13Modified ECMAScript regular expression grammarN 
        8C Compatibility
        8.1Additions to header <complex>Y 
        8.1.1SynopsisY 
        8.1.2Function acosY 
        8.1.3Function asinY 
        8.1.4Function atanY 
        8.1.5Function acoshY 
        8.1.6Function asinhY 
        8.1.7Function atanhY 
        8.1.8Function fabsY 
        8.1.9Additional OverloadsY 
        8.2Header <ccomplex>NDR 551
        8.3Header <complex.h>NDR 551
        8.4Additions to header <cctype>Y 
        8.4.1SynopsisY 
        8.4.2Function isblankY 
        8.5Additions to header <ctype.h>Y 
        8.6Header <cfenv>Y 
        8.6.1SynopsisY 
        8.6.2DefinitionsY 
        8.7Header <fenv.h>Y 
        8.8Additions to header <cfloat>Y 
        8.9Additions to header <float.h>Y 
        8.10Additions to header <ios>N 
        8.10.1SynopsisN 
        8.10.2Function hexfloatN 
        8.11Header <cinttypes>Y 
        8.11.1SynopsisYDR 557
        8.11.2DefinitionsY 
        8.12Header <inttypes.h>Y 
        8.13Additions to header <climits>Y 
        8.14Additions to header <limits.h>Y 
        8.15Additions to header <locale>N 
        8.16Additions to header <cmath>Y 
        8.16.1SynopsisY 
        8.16.2DefinitionsY 
        8.16.3Function template definitionsY 
        8.16.4Additional overloadsYDR 568; DR 550
        8.17Additions to header <math.h>Y 
        8.18Additions to header <cstdarg>Y 
        8.19Additions to header <stdarg.h>Y 
        8.20The header <cstdbool>Y 
        8.21The header <stdbool.h>Y 
        8.22The header <cstdint>Y 
        8.22.1SynopsisY 
        8.22.2DefinitionsY 
        8.23The header <stdint.h>Y 
        8.24Additions to header <cstdio>Y 
        8.24.1SynopsisY 
        8.24.2DefinitionsY 
        8.24.3Additional format specifiersYC library dependency
        8.24.4Additions to header <stdio.h>Y 
        8.25Additions to header <cstdlib>Y 
        8.25.1SynopsisY 
        8.25.2DefinitionsY 
        8.25.3Function absY 
        8.25.4Function divY 
        8.26Additions to header <stdlib.h>Y 
        8.27Header <ctgmath>YDR 551
        8.28Header <tgmath.h>YDR 551
        8.29Additions to header <ctime>YC library dependency
        8.30Additions to header <cwchar>Y 
        8.30.1SynopsisY 
        8.30.2DefinitionsY 
        8.30.3Additional wide format specifiersYC library dependency
        8.31Additions to header <wchar.h>Y 
        8.32Additions to header <cwctype>Y 
        8.32.1SynopsisY 
        8.32.2Function iswblankY 
        8.33Additions to header <wctype.h>Y 

        C++ TR 24733

        This table is based on the table of contents of ISO/IEC TR 24733 Date: 2009-08-28 @@ -242,7 +242,7 @@ decimal floating-point arithmetic

        This page describes the TR 24733 support in mainline GCC SVN, not in any particular release. -

        Table 1.4. C++ TR 24733 Implementation Status

        SectionDescriptionStatusComments
        +

        Table 1.4. C++ TR 24733 Implementation Status

        SectionDescriptionStatusComments
        0 Introduction diff --git a/libstdc++-v3/doc/html/manual/streambufs.html b/libstdc++-v3/doc/html/manual/streambufs.html index db8445f2a94..277339d6e27 100644 --- a/libstdc++-v3/doc/html/manual/streambufs.html +++ b/libstdc++-v3/doc/html/manual/streambufs.html @@ -1,9 +1,9 @@ -Chapter 25. Stream Buffers
        Chapter 25. Stream Buffers
        Prev Part XI.  +Stream Buffers
        Stream Buffers
        Prev Chapter 13.  Input and Output - Next

        Chapter 25. Stream Buffers

        Table of Contents

        Derived streambuf Classes
        Buffering

        Derived streambuf Classes

        +

        		 Next

        Stream Buffers

        Derived streambuf Classes

        Creating your own stream buffers for I/O can be remarkably easy. If you are interested in doing so, we highly recommend two very excellent books: @@ -57,4 +57,81 @@ include/ext/*_filebuf.h, and in this article by James Kanze: Filtering Streambufs. -

        Prev Up Next
        Chapter 24. Iostream Objects Home Buffering
        +

        Buffering

        First, are you sure that you understand buffering? Chaptericularly + the fact that C++ may not, in fact, have anything to do with it? +

        The rules for buffering can be a little odd, but they aren't any + different from those of C. (Maybe that's why they can be a bit + odd.) Many people think that writing a newline to an output + stream automatically flushes the output buffer. This is true only + when the output stream is, in fact, a terminal and not a file + or some other device -- and that may not even be true + since C++ says nothing about files nor terminals. All of that is + system-dependent. (The "newline-buffer-flushing only occurring + on terminals" thing is mostly true on Unix systems, though.) +

        Some people also believe that sending endl down an + output stream only writes a newline. This is incorrect; after a + newline is written, the buffer is also flushed. Perhaps this + is the effect you want when writing to a screen -- get the text + out as soon as possible, etc -- but the buffering is largely + wasted when doing this to a file: + 

        +   output << "a line of text" << endl;
+   output << some_data_variable << endl;
+   output << "another line of text" << endl;

        The proper thing to do in this case to just write the data out + and let the libraries and the system worry about the buffering. + If you need a newline, just write a newline: + 

        +   output << "a line of text\n"
+	  << some_data_variable << '\n'
+	  << "another line of text\n";

        I have also joined the output statements into a single statement. + You could make the code prettier by moving the single newline to + the start of the quoted text on the last line, for example. +

        If you do need to flush the buffer above, you can send an + endl if you also need a newline, or just flush the buffer + yourself: + 

        +   output << ...... << flush;    // can use std::flush manipulator
+   output.flush();               // or call a member fn

        On the other hand, there are times when writing to a file should + be like writing to standard error; no buffering should be done + because the data needs to appear quickly (a prime example is a + log file for security-related information). The way to do this is + just to turn off the buffering before any I/O operations at + all have been done (note that opening counts as an I/O operation): + 

        +   std::ofstream    os;
+   std::ifstream    is;
+   int   i;
+
+   os.rdbuf()->pubsetbuf(0,0);
+   is.rdbuf()->pubsetbuf(0,0);
+
+   os.open("/foo/bar/baz");
+   is.open("/qux/quux/quuux");
+   ...
+   os << "this data is written immediately\n";
+   is >> i;   // and this will probably cause a disk read

        Since all aspects of buffering are handled by a streambuf-derived + member, it is necessary to get at that member with rdbuf(). + Then the public version of setbuf can be called. The + arguments are the same as those for the Standard C I/O Library + function (a buffer area followed by its size). +

        A great deal of this is implementation-dependent. For example, + streambuf does not specify any actions for its own + setbuf()-ish functions; the classes derived from + streambuf each define behavior that "makes + sense" for that class: an argument of (0,0) turns off buffering + for filebuf but does nothing at all for its siblings + stringbuf and strstreambuf, and specifying + anything other than (0,0) has varying effects. + User-defined classes derived from streambuf can + do whatever they want. (For filebuf and arguments for + (p,s) other than zeros, libstdc++ does what you'd expect: + the first s bytes of p are used as a buffer, + which you must allocate and deallocate.) +

        A last reminder: there are usually more buffers involved than + just those at the language/library level. Kernel buffers, disk + buffers, and the like will also have an effect. Inspecting and + changing those are system-dependent. +

        Prev Up Next
        Chapter 13.  + Input and Output + + Home Memory Based Streams
        diff --git a/libstdc++-v3/doc/html/manual/strings.html b/libstdc++-v3/doc/html/manual/strings.html index 76fba6ee433..d1dfd3b2f71 100644 --- a/libstdc++-v3/doc/html/manual/strings.html +++ b/libstdc++-v3/doc/html/manual/strings.html @@ -1,9 +1,366 @@ -Part V.  Strings
        Part V.  +Chapter 7.  Strings
        Chapter 7.  Strings -
        Prev The GNU C++ Library Next

        Part V.  +

        Prev Part II.  + Standard Contents + Next

        Chapter 7.  Strings - -

        Table of Contents

        13. String Classes
        Simple Transformations
        Case Sensitivity
        Arbitrary Character Types
        Tokenizing
        Shrink to Fit
        CString (MFC)
        Prev Up Next
        shared_ptr Home Chapter 13. String Classes
        + +

        Table of Contents

        String Classes
        Simple Transformations
        Case Sensitivity
        Arbitrary Character Types
        Tokenizing
        Shrink to Fit
        CString (MFC)

        String Classes

        Simple Transformations

        + Here are Standard, simple, and portable ways to perform common + transformations on a string instance, such as + "convert to all upper case." The word transformations + is especially apt, because the standard template function + transform<> is used. +

        + This code will go through some iterations. Here's a simple + version: + 

        +   #include <string>
+   #include <algorithm>
+   #include <cctype>      // old <ctype.h>
+
+   struct ToLower
+   {
+     char operator() (char c) const  { return std::tolower(c); }
+   };
+
+   struct ToUpper
+   {
+     char operator() (char c) const  { return std::toupper(c); }
+   };
+
+   int main()
+   {
+     std::string  s ("Some Kind Of Initial Input Goes Here");
+
+     // Change everything into upper case
+     std::transform (s.begin(), s.end(), s.begin(), ToUpper());
+
+     // Change everything into lower case
+     std::transform (s.begin(), s.end(), s.begin(), ToLower());
+
+     // Change everything back into upper case, but store the
+     // result in a different string
+     std::string  capital_s;
+     capital_s.resize(s.size());
+     std::transform (s.begin(), s.end(), capital_s.begin(), ToUpper());
+   }
+

        + Note that these calls all + involve the global C locale through the use of the C functions + toupper/tolower. This is absolutely guaranteed to work -- + but only if the string contains only characters + from the basic source character set, and there are only + 96 of those. Which means that not even all English text can be + represented (certain British spellings, proper names, and so forth). + So, if all your input forevermore consists of only those 96 + characters (hahahahahaha), then you're done. +

        Note that the + ToUpper and ToLower function objects + are needed because toupper and tolower + are overloaded names (declared in <cctype> and + <locale>) so the template-arguments for + transform<> cannot be deduced, as explained in + this + message. + + At minimum, you can write short wrappers like + 

        +   char toLower (char c)
+   {
+      return std::tolower(c);
+   }

        (Thanks to James Kanze for assistance and suggestions on all of this.) +

        Another common operation is trimming off excess whitespace. Much + like transformations, this task is trivial with the use of string's + find family. These examples are broken into multiple + statements for readability: + 

        +   std::string  str (" \t blah blah blah    \n ");
+
+   // trim leading whitespace
+   string::size_type  notwhite = str.find_first_not_of(" \t\n");
+   str.erase(0,notwhite);
+
+   // trim trailing whitespace
+   notwhite = str.find_last_not_of(" \t\n");
+   str.erase(notwhite+1);

        Obviously, the calls to find could be inserted directly + into the calls to erase, in case your compiler does not + optimize named temporaries out of existence. +

        Case Sensitivity

        +

        The well-known-and-if-it-isn't-well-known-it-ought-to-be + Guru of the Week + discussions held on Usenet covered this topic in January of 1998. + Briefly, the challenge was, “write a 'ci_string' class which + is identical to the standard 'string' class, but is + case-insensitive in the same way as the (common but nonstandard) + C function stricmp()”. + 

        +   ci_string s( "AbCdE" );
+
+   // case insensitive
+   assert( s == "abcde" );
+   assert( s == "ABCDE" );
+
+   // still case-preserving, of course
+   assert( strcmp( s.c_str(), "AbCdE" ) == 0 );
+   assert( strcmp( s.c_str(), "abcde" ) != 0 );

        The solution is surprisingly easy. The original answer was + posted on Usenet, and a revised version appears in Herb Sutter's + book Exceptional C++ and on his website as GotW 29. +

        See? Told you it was easy!

        + Added June 2000: The May 2000 issue of C++ + Report contains a fascinating article by + Matt Austern (yes, the Matt Austern) on why + case-insensitive comparisons are not as easy as they seem, and + why creating a class is the wrong way to go + about it in production code. (The GotW answer mentions one of + the principle difficulties; his article mentions more.) +

        Basically, this is "easy" only if you ignore some things, + things which may be too important to your program to ignore. (I chose + to ignore them when originally writing this entry, and am surprised + that nobody ever called me on it...) The GotW question and answer + remain useful instructional tools, however. +

        Added September 2000: James Kanze provided a link to a + Unicode + Technical Report discussing case handling, which provides some + very good information. +

        Arbitrary Character Types

        +

        The std::basic_string is tantalizingly general, in that + it is parameterized on the type of the characters which it holds. + In theory, you could whip up a Unicode character class and instantiate + std::basic_string<my_unicode_char>, or assuming + that integers are wider than characters on your platform, maybe just + declare variables of type std::basic_string<int>. +

        That's the theory. Remember however that basic_string has additional + type parameters, which take default arguments based on the character + type (called CharT here): + 

        +      template <typename CharT,
+		typename Traits = char_traits<CharT>,
+		typename Alloc = allocator<CharT> >
+      class basic_string { .... };

        Now, allocator<CharT> will probably Do The Right + Thing by default, unless you need to implement your own allocator + for your characters. +

        But char_traits takes more work. The char_traits + template is declared but not defined. + That means there is only + 

        +      template <typename CharT>
+	struct char_traits
+	{
+	    static void foo (type1 x, type2 y);
+	    ...
+	};

        and functions such as char_traits<CharT>::foo() are not + actually defined anywhere for the general case. The C++ standard + permits this, because writing such a definition to fit all possible + CharT's cannot be done. +

        The C++ standard also requires that char_traits be specialized for + instantiations of char and wchar_t, and it + is these template specializations that permit entities like + basic_string<char,char_traits<char>> to work. +

        If you want to use character types other than char and wchar_t, + such as unsigned char and int, you will + need suitable specializations for them. For a time, in earlier + versions of GCC, there was a mostly-correct implementation that + let programmers be lazy but it broke under many situations, so it + was removed. GCC 3.4 introduced a new implementation that mostly + works and can be specialized even for int and other + built-in types. +

        If you want to use your own special character class, then you have + a lot + of work to do, especially if you with to use i18n features + (facets require traits information but don't have a traits argument). +

        Another example of how to specialize char_traits was given on the + mailing list and at a later date was put into the file + include/ext/pod_char_traits.h. We agree + that the way it's used with basic_string (scroll down to main()) + doesn't look nice, but that's because the + nice-looking first attempt turned out to not + be conforming C++, due to the rule that CharT must be a POD. + (See how tricky this is?) +

        Tokenizing

        +

        The Standard C (and C++) function strtok() leaves a lot to + be desired in terms of user-friendliness. It's unintuitive, it + destroys the character string on which it operates, and it requires + you to handle all the memory problems. But it does let the client + code decide what to use to break the string into pieces; it allows + you to choose the "whitespace," so to speak. +

        A C++ implementation lets us keep the good things and fix those + annoyances. The implementation here is more intuitive (you only + call it once, not in a loop with varying argument), it does not + affect the original string at all, and all the memory allocation + is handled for you. +

        It's called stringtok, and it's a template function. Sources are + as below, in a less-portable form than it could be, to keep this + example simple (for example, see the comments on what kind of + string it will accept). + 

        +#include <string>
+template <typename Container>
+void
+stringtok(Container &container, string const &in,
+	  const char * const delimiters = " \t\n")
+{
+    const string::size_type len = in.length();
+	  string::size_type i = 0;
+
+    while (i < len)
+    {
+	// Eat leading whitespace
+	i = in.find_first_not_of(delimiters, i);
+	if (i == string::npos)
+	  return;   // Nothing left but white space
+
+	// Find the end of the token
+	string::size_type j = in.find_first_of(delimiters, i);
+
+	// Push token
+	if (j == string::npos)
+	{
+	  container.push_back(in.substr(i));
+	  return;
+	}
+	else
+	  container.push_back(in.substr(i, j-i));
+
+	// Set up for next loop
+	i = j + 1;
+    }
+}
+

        + The author uses a more general (but less readable) form of it for + parsing command strings and the like. If you compiled and ran this + code using it: + 

        +   std::list<string>  ls;
+   stringtok (ls, " this  \t is\t\n  a test  ");
+   for (std::list<string>const_iterator i = ls.begin();
+	i != ls.end(); ++i)
+   {
+       std::cerr << ':' << (*i) << ":\n";
+   }

        You would see this as output: + 

        +   :this:
+   :is:
+   :a:
+   :test:

        with all the whitespace removed. The original s is still + available for use, ls will clean up after itself, and + ls.size() will return how many tokens there were. +

        As always, there is a price paid here, in that stringtok is not + as fast as strtok. The other benefits usually outweigh that, however. +

        Added February 2001: Mark Wilden pointed out that the + standard std::getline() function can be used with standard + istringstreams to perform + tokenizing as well. Build an istringstream from the input text, + and then use std::getline with varying delimiters (the three-argument + signature) to extract tokens into a string. +

        Shrink to Fit

        +

        From GCC 3.4 calling s.reserve(res) on a + string s with res < s.capacity() will + reduce the string's capacity to std::max(s.size(), res). +

        This behaviour is suggested, but not required by the standard. Prior + to GCC 3.4 the following alternative can be used instead + 

        +      std::string(str.data(), str.size()).swap(str);
+

        This is similar to the idiom for reducing + a vector's memory usage + (see this FAQ + entry) but the regular copy constructor cannot be used + because libstdc++'s string is Copy-On-Write. +

        In C++0x mode you can call + s.shrink_to_fit() to achieve the same effect as + s.reserve(s.size()). +

        CString (MFC)

        +

        A common lament seen in various newsgroups deals with the Standard + string class as opposed to the Microsoft Foundation Class called + CString. Often programmers realize that a standard portable + answer is better than a proprietary nonportable one, but in porting + their application from a Win32 platform, they discover that they + are relying on special functions offered by the CString class. +

        Things are not as bad as they seem. In + this + message, Joe Buck points out a few very important things: +

        • The Standard string supports all the operations + that CString does, with three exceptions. +

        • Two of those exceptions (whitespace trimming and case + conversion) are trivial to implement. In fact, we do so + on this page. +

        • The third is CString::Format, which allows formatting + in the style of sprintf. This deserves some mention: +

        + The old libg++ library had a function called form(), which did much + the same thing. But for a Standard solution, you should use the + stringstream classes. These are the bridge between the iostream + hierarchy and the string class, and they operate with regular + streams seamlessly because they inherit from the iostream + hierarchy. An quick example: + 

        +   #include <iostream>
+   #include <string>
+   #include <sstream>
+
+   string f (string& incoming)     // incoming is "foo  N"
+   {
+       istringstream   incoming_stream(incoming);
+       string          the_word;
+       int             the_number;
+
+       incoming_stream >> the_word        // extract "foo"
+		       >> the_number;     // extract N
+
+       ostringstream   output_stream;
+       output_stream << "The word was " << the_word
+		     << " and 3*N was " << (3*the_number);
+
+       return output_stream.str();
+   }

        A serious problem with CString is a design bug in its memory + allocation. Specifically, quoting from that same message: + 

        +   CString suffers from a common programming error that results in
+   poor performance.  Consider the following code:
+
+   CString n_copies_of (const CString& foo, unsigned n)
+   {
+	   CString tmp;
+	   for (unsigned i = 0; i < n; i++)
+		   tmp += foo;
+	   return tmp;
+   }
+
+   This function is O(n^2), not O(n).  The reason is that each +=
+   causes a reallocation and copy of the existing string.  Microsoft
+   applications are full of this kind of thing (quadratic performance
+   on tasks that can be done in linear time) -- on the other hand,
+   we should be thankful, as it's created such a big market for high-end
+   ix86 hardware. :-)
+
+   If you replace CString with string in the above function, the
+   performance is O(n).
+

        Joe Buck also pointed out some other things to keep in mind when + comparing CString and the Standard string class: +

        • CString permits access to its internal representation; coders + who exploited that may have problems moving to string. +

        • Microsoft ships the source to CString (in the files + MFC\SRC\Str{core,ex}.cpp), so you could fix the allocation + bug and rebuild your MFC libraries. + Note: It looks like the CString shipped + with VC++6.0 has fixed this, although it may in fact have been + one of the VC++ SPs that did it. +

        • string operations like this have O(n) complexity + if the implementors do it correctly. The libstdc++ + implementors did it correctly. Other vendors might not. +

        • While chapters of the SGI STL are used in libstdc++, their + string class is not. The SGI string is essentially + vector<char> and does not do any reference + counting like libstdc++'s does. (It is O(n), though.) + So if you're thinking about SGI's string or rope classes, + you're now looking at four possibilities: CString, the + libstdc++ string, the SGI string, and the SGI rope, and this + is all before any allocator or traits customizations! (More + choices than you can shake a stick at -- want fries with that?) +

        Prev Up Next
        Traits Home Chapter 8.  + Localization + +
        diff --git a/libstdc++-v3/doc/html/manual/stringstreams.html b/libstdc++-v3/doc/html/manual/stringstreams.html index 718965570e4..6e6b77eb4e8 100644 --- a/libstdc++-v3/doc/html/manual/stringstreams.html +++ b/libstdc++-v3/doc/html/manual/stringstreams.html @@ -1,14 +1,14 @@ -Chapter 26. Memory Based Streams
        Chapter 26. Memory Based Streams
        Prev Part XI.  +Memory Based Streams
        Memory Based Streams
        Prev Chapter 13.  Input and Output - Next

        Chapter 26. Memory Based Streams

        Table of Contents

        Compatibility With strstream

        Compatibility With strstream

        +

        		 Next

        Memory Based Streams

        Compatibility With strstream

        Stringstreams (defined in the header <sstream>) are in this author's opinion one of the coolest things since sliced time. An example of their use is in the Received Wisdom - section for Chapter 21 (Strings), - describing how to + section for Sect1 21 (Strings), + describing how to format strings.

        The quick definition is: they are siblings of ifstream and ofstream, and they do for std::string what their siblings do for @@ -34,4 +34,4 @@ memory yourself. The strstreams have been officially deprecated, which means that 1) future revisions of the C++ Standard won't support them, and 2) if you use them, people will laugh at you. -

        Prev Up Next
        Buffering Home Chapter 27. File Based Streams
        +

        Prev Up Next
        Stream Buffers Home File Based Streams
        diff --git a/libstdc++-v3/doc/html/manual/support.html b/libstdc++-v3/doc/html/manual/support.html index 14154ee4622..de3237b4b76 100644 --- a/libstdc++-v3/doc/html/manual/support.html +++ b/libstdc++-v3/doc/html/manual/support.html @@ -1,9 +1,130 @@ -Part II.  Support
        Part II.  +Chapter 4.  Support
        Chapter 4.  Support -
        Prev The GNU C++ Library Next

        Part II.  +

        Prev Part II.  + Standard Contents + Next

        Chapter 4.  Support - -

        Table of Contents

        4. Types
        Fundamental Types
        Numeric Properties
        NULL
        5. Dynamic Memory
        6. Termination
        Termination Handlers
        Verbose Terminate Handler
        Prev Up Next
        Debugging Support Home 
        + +

        Table of Contents

        Types
        Fundamental Types
        Numeric Properties
        NULL
        Dynamic Memory
        Termination
        Termination Handlers
        Verbose Terminate Handler

        + This part deals with the functions called and objects created + automatically during the course of a program's existence. +

        + While we can't reproduce the contents of the Standard here (you + need to get your own copy from your nation's member body; see our + homepage for help), we can mention a couple of changes in what + kind of support a C++ program gets from the Standard Library. +

        Types

        Fundamental Types

        + C++ has the following builtin types: +

        • + char +

        • + signed char +

        • + unsigned char +

        • + signed short +

        • + signed int +

        • + signed long +

        • + unsigned short +

        • + unsigned int +

        • + unsigned long +

        • + bool +

        • + wchar_t +

        • + float +

        • + double +

        • + long double +

        + These fundamental types are always available, without having to + include a header file. These types are exactly the same in + either C++ or in C. +

        + Specializing parts of the library on these types is prohibited: + instead, use a POD. +

        Numeric Properties

        + The header limits defines + traits classes to give access to various implementation + defined-aspects of the fundamental types. The traits classes -- + fourteen in total -- are all specializations of the template class + numeric_limits, documented here + and defined as follows: + 

        +   template<typename T>
+     struct class
+     {
+       static const bool is_specialized;
+       static T max() throw();
+       static T min() throw();
+
+       static const int digits;
+       static const int digits10;
+       static const bool is_signed;
+       static const bool is_integer;
+       static const bool is_exact;
+       static const int radix;
+       static T epsilon() throw();
+       static T round_error() throw();
+
+       static const int min_exponent;
+       static const int min_exponent10;
+       static const int max_exponent;
+       static const int max_exponent10;
+
+       static const bool has_infinity;
+       static const bool has_quiet_NaN;
+       static const bool has_signaling_NaN;
+       static const float_denorm_style has_denorm;
+       static const bool has_denorm_loss;
+       static T infinity() throw();
+       static T quiet_NaN() throw();
+       static T denorm_min() throw();
+
+       static const bool is_iec559;
+       static const bool is_bounded;
+       static const bool is_modulo;
+
+       static const bool traps;
+       static const bool tinyness_before;
+       static const float_round_style round_style;
+     };
+

        NULL

        + The only change that might affect people is the type of + NULL: while it is required to be a macro, + the definition of that macro is not allowed + to be (void*)0, which is often used in C. +

        + For g++, NULL is + 

        #define

        'd to be + __null, a magic keyword extension of + g++. +

        + The biggest problem of #defining NULL to be + something like “0L” is that the compiler will view + that as a long integer before it views it as a pointer, so + overloading won't do what you expect. (This is why + g++ has a magic extension, so that + NULL is always a pointer.) +

        In his book Effective + C++, Scott Meyers points out that the best way + to solve this problem is to not overload on pointer-vs-integer + types to begin with. He also offers a way to make your own magic + NULL that will match pointers before it + matches integers. +

        See + the + Effective C++ CD example +

        Prev Up Next
        Part II.  + Standard Contents + Home Dynamic Memory
        diff --git a/libstdc++-v3/doc/html/manual/termination.html b/libstdc++-v3/doc/html/manual/termination.html index ff86016f613..ab0bf5e19b6 100644 --- a/libstdc++-v3/doc/html/manual/termination.html +++ b/libstdc++-v3/doc/html/manual/termination.html @@ -1,9 +1,9 @@ -Chapter 6. Termination
        Chapter 6. Termination
        Prev Part II.  +Termination
        Termination
        Prev Chapter 4.  Support - Next

        Chapter 6. Termination

        Table of Contents

        Termination Handlers
        Verbose Terminate Handler

        Termination Handlers

        +

        		 Next

        Termination

        Termination Handlers

        Not many changes here to cstdlib. You should note that the abort() function does not call the destructors of automatic nor static objects, so if you're @@ -19,30 +19,106 @@ Static objects are destroyed in reverse order of their creation.

      • Functions registered with atexit() are called in - reverse order of registration, once per registration call. - (This isn't actually new.) + reverse order of registration, once per registration call. + (This isn't actually new.)

      • The previous two actions are “interleaved,” that is, - given this pseudocode: + given this pseudocode: 

           extern "C or C++" void  f1 (void);
   extern "C or C++" void  f2 (void);
-  
+
   static Thing obj1;
   atexit(f1);
   static Thing obj2;
   atexit(f2);

        - then at a call of exit(), - f2 will be called, then - obj2 will be destroyed, then - f1 will be called, and finally - obj1 will be destroyed. If - f1 or f2 allow an - exception to propagate out of them, Bad Things happen. + then at a call of exit(), + f2 will be called, then + obj2 will be destroyed, then + f1 will be called, and finally + obj1 will be destroyed. If + f1 or f2 allow an + exception to propagate out of them, Bad Things happen.

        • Note also that atexit() is only required to store 32 functions, and the compiler/library might already be using some of those slots. If you think you may run out, we recommend using the xatexit/xexit combination from libiberty, which has no such limit. -

        Prev Up Next
        Chapter 5. Dynamic Memory Home Verbose Terminate Handler
        +

        Verbose Terminate Handler

        + If you are having difficulty with uncaught exceptions and want a + little bit of help debugging the causes of the core dumps, you can + make use of a GNU extension, the verbose terminate handler. + 

        +#include <exception>
+
+int main()
+{
+  std::set_terminate(__gnu_cxx::__verbose_terminate_handler);
+  ...
+
+  throw anything;
+}
+

        + The __verbose_terminate_handler function + obtains the name of the current exception, attempts to demangle + it, and prints it to stderr. If the exception is derived from + exception then the output from + what() will be included. +

        + Any replacement termination function is required to kill the + program without returning; this one calls abort. +

        + For example: + 

        +#include <exception>
+#include <stdexcept>
+
+struct argument_error : public std::runtime_error
+{
+  argument_error(const std::string& s): std::runtime_error(s) { }
+};
+
+int main(int argc)
+{
+  std::set_terminate(__gnu_cxx::__verbose_terminate_handler);
+  if (argc > 5)
+    throw argument_error(“argc is greater than 5!”);
+  else
+    throw argc;
+}
+

        + With the verbose terminate handler active, this gives: + 

        +   
+   % ./a.out
+   terminate called after throwing a `int'
+   Aborted
+   % ./a.out f f f f f f f f f f f
+   terminate called after throwing an instance of `argument_error'
+   what(): argc is greater than 5!
+   Aborted
+   
+

        + The 'Aborted' line comes from the call to + abort(), of course. +

        + This is the default termination handler; nothing need be done to + use it. To go back to the previous “silent death” + method, simply include exception and + cstdlib, and call + 

        +     std::set_terminate(std::abort);
+

        + After this, all calls to terminate will use + abort as the terminate handler. +

        + Note: the verbose terminate handler will attempt to write to + stderr. If your application closes stderr or redirects it to an + inappropriate location, + __verbose_terminate_handler will behave in + an unspecified manner. +

        Prev Up Next
        Dynamic Memory Home Chapter 5.  + Diagnostics + +
        diff --git a/libstdc++-v3/doc/html/manual/test.html b/libstdc++-v3/doc/html/manual/test.html index c5bcc1f54c3..9065845c34c 100644 --- a/libstdc++-v3/doc/html/manual/test.html +++ b/libstdc++-v3/doc/html/manual/test.html @@ -278,7 +278,7 @@ runtest --tool libstdc++ --srcdir=/path/to/gcc/libstdc++-v3/testsuite please email the main libstdc++ mailing list if you see something odd or have questions.

        Permutations

        - To run the libstdc++ test suite under the debug mode, edit + To run the libstdc++ test suite under the debug mode, edit libstdc++-v3/scripts/testsuite_flags to add the compile-time flag -D_GLIBCXX_DEBUG to the result printed by the --build-cxx @@ -289,7 +289,7 @@ runtest --tool libstdc++ --srcdir=/path/to/gcc/libstdc++-v3/testsuite release mode: any deviation indicates an error in either the library or the test suite.

        - The parallel + The parallel mode can be tested in much the same manner, substituting -D_GLIBCXX_PARALLEL for -D_GLIBCXX_DEBUG in the previous paragraph. @@ -493,7 +493,7 @@ only default variables. reporting functions including:

        • time_counter

        • resource_counter

        • report_performance

        Special Topics

        Qualifying Exception Safety Guarantees - +

        Overview

        Testing is composed of running a particular test sequence, and looking at what happens to the surrounding code when @@ -508,7 +508,7 @@ only default variables. consistency/coherency of the test subject in the event of a thrown exception.

        - Random code paths can be constructed using the the basic test + Random code paths can be constructed using the basic test sequences and instrumentation as above, only combined in a random or pseudo-random way.

        To compute the code paths that throw, test instruments @@ -543,7 +543,7 @@ only default variables. Which has several tests for container member functions, Includes control and test container objects. Configuration includes random seed, iterations, number of distinct values, and the -probability that and exception will be thrown. Assumes instantiating +probability that an exception will be thrown. Assumes instantiating container uses an extension allocator, __gnu_cxx::throw_allocator_random, as the allocator type. diff --git a/libstdc++-v3/doc/html/manual/traits.html b/libstdc++-v3/doc/html/manual/traits.html index 1d1e6fb75bf..62356dec625 100644 --- a/libstdc++-v3/doc/html/manual/traits.html +++ b/libstdc++-v3/doc/html/manual/traits.html @@ -1,10 +1,10 @@ -Chapter 12. Traits

        Chapter 12. Traits
        Prev Part IV.  +Traits
        Traits
        Prev Chapter 6.  Utilities - Next

        Chapter 12. Traits

        -

        Prev Up Next
        shared_ptr Home Part V.  + Next

        Traits

        +

        Prev Up Next
        Memory Home Chapter 7.  Strings
        diff --git a/libstdc++-v3/doc/html/manual/using.html b/libstdc++-v3/doc/html/manual/using.html index 93114db3d57..51dd333bab4 100644 --- a/libstdc++-v3/doc/html/manual/using.html +++ b/libstdc++-v3/doc/html/manual/using.html @@ -11,5 +11,5 @@ enumerated and detailed in the table below.

        By default, g++ is equivalent to g++ -std=gnu++98. The standard library also defaults to this dialect. -

        Table 3.1. C++ Command Options

        Option FlagsDescription
        -std=c++98Use the 1998 ISO C++ standard plus amendments.
        -std=gnu++98As directly above, with GNU extensions.
        -std=c++0xUse the working draft of the upcoming ISO C++0x standard.
        -std=gnu++0xAs directly above, with GNU extensions.
        -fexceptionsSee exception-free dialect
        -frttiAs above, but RTTI-free dialect.
        -pthread or -pthreadsFor ISO C++0x <thread>, <future>, - <mutex>, or <condition_variable>.
        -fopenmpFor parallel mode.

        Prev Up Next
        Make Home Headers
        +

        Table 3.1. C++ Command Options

        Option FlagsDescription
        -std=c++98Use the 1998 ISO C++ standard plus amendments.
        -std=gnu++98As directly above, with GNU extensions.
        -std=c++0xUse the working draft of the upcoming ISO C++0x standard.
        -std=gnu++0xAs directly above, with GNU extensions.
        -fexceptionsSee exception-free dialect
        -frttiAs above, but RTTI-free dialect.
        -pthread or -pthreadsFor ISO C++0x <thread>, <future>, + <mutex>, or <condition_variable>.
        -fopenmpFor parallel mode.

        Prev Up Next
        Make Home Headers
        diff --git a/libstdc++-v3/doc/html/manual/using_concurrency.html b/libstdc++-v3/doc/html/manual/using_concurrency.html index f0f63a9eee2..f18aec31d8f 100644 --- a/libstdc++-v3/doc/html/manual/using_concurrency.html +++ b/libstdc++-v3/doc/html/manual/using_concurrency.html @@ -200,6 +200,6 @@ gcc version 4.1.2 20070925 (Red Hat 4.1.2-33) this at application run-time see here. Also useful are details - on allocator + on allocator options and capabilities.

        Prev Up Next
        Linking Home Exceptions
        diff --git a/libstdc++-v3/doc/html/manual/using_dynamic_or_shared.html b/libstdc++-v3/doc/html/manual/using_dynamic_or_shared.html index 9e48296929a..38e19313029 100644 --- a/libstdc++-v3/doc/html/manual/using_dynamic_or_shared.html +++ b/libstdc++-v3/doc/html/manual/using_dynamic_or_shared.html @@ -21,7 +21,7 @@

      • typeinfo

        • - In addition, throw in + In addition, throw in

        • cxxabi.h.

        @@ -76,13 +76,27 @@ A quick read of the relevant part of the GCC the linker. The exact format of the options is dependent on which linker you use:

        • - GNU ld (default on Linux):-Wl,--rpath,destdir/lib + GNU ld (default on Linux): + -Wl,-rpath,destdir/lib

        • - IRIX ld: - -Wl,-rpath,destdir/lib + IRIX ld: + -Wl,-rpath,destdir/lib

        • - Solaris ld:-Wl,-Rdestdir/lib -

        + Solaris ld: + -Wl,-Rdestdir/lib +

      • + Some linkers allow you to specify the path to the library by + setting LD_RUN_PATH in your environment + when linking. +

      • + On some platforms the system administrator can configure the + dynamic linker to always look for libraries in + destdir/lib, for example + by using the ldconfig utility on Linux + or the crle utility on Solaris. This is a + system-wide change which can make the system unusable so if you + are unsure then use one of the other methods described above. +

        • Use the ldd utility on the linked executable to show which libstdc++.so diff --git a/libstdc++-v3/doc/html/manual/using_exceptions.html b/libstdc++-v3/doc/html/manual/using_exceptions.html index 39fc1e05cfd..dc8c4daec8b 100644 --- a/libstdc++-v3/doc/html/manual/using_exceptions.html +++ b/libstdc++-v3/doc/html/manual/using_exceptions.html @@ -8,12 +8,12 @@ the throw keyword. These are very powerful constructs, and require some thought when applied to the standard library in order to yield components that work efficiently while cleaning up resources when unexpectedly killed via -exceptional circumstances. +exceptional circumstances.

        Two general topics of discussion follow: exception neutrality and exception safety. -

        Exception Safety

        - What is exception-safe code? +

        Exception Safety

        + What is exception-safe code?

        Will define this as reasonable and well-defined behavior by classes and functions from the standard library when used by user-defined @@ -124,7 +124,7 @@ exception neutrality and exception safety. use -fno-exceptions. If you have some code that uses try or catch, you shouldn't use -fno-exceptions. -

        +

        And what it to be gained, tinkering in the back alleys with a language like this? Exception handling overhead can be measured in the size of the executable binary, and varies with the @@ -194,7 +194,7 @@ exception neutrality and exception safety. library has been transformed, user code may need modification. User code that attempts or expects to do error checking on standard library components compiled with exception handling disabled should - be evaluated and potentially made conditional. + be evaluated and potentially made conditional.

        Some issues remain with this approach (see bugzilla entry 25191). Code paths are not equivalent, in @@ -220,7 +220,7 @@ exception neutrality and exception safety. substitution of the C language keyword const with the uglified doppelganger __const. -

        Compatibility

        With C

        +

        Compatibility

        With C

        C language code that is expecting to interoperate with C++ should be compiled with -fexceptions. This will make debugging a C language function called as part of C++-induced stack @@ -235,7 +235,7 @@ is called. getting these details right. For GNU systems, all appropriate parts of the GNU C library are already compiled with -fexceptions. -

        With POSIX thread cancellation

        +

        With POSIX thread cancellation

        GNU systems re-use some of the exception handling mechanisms to track control flow for POSIX thread cancellation.

        @@ -266,54 +266,63 @@ is called. } catch(...) { this->_M_setstate(ios_base::badbit); } -

        Bibliography

        - System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008) - . +

        Bibliography

        + + + System Interface Definitions, Issue 7 (IEEE Std. 1003.1-2008) + + + . 2.9.5 Thread Cancellation . Copyright © 2008 - The Open Group/The Institute of Electrical and Electronics Engineers, Inc.. - - - .

        - Error and Exception Handling - . David Abrahams . - Boost - . + The Open Group/The Institute of Electrical and Electronics + Engineers, Inc. + .

        + + Error and Exception Handling + - .

        - Exception-Safety in Generic Components - . David Abrahams. + . David Abrahams . Boost - . + .

        + + Exception-Safety in Generic Components + - .

        - Standard Library Exception Policy - . Matt Austern. - WG21 N1077 - . + . David Abrahams. + Boost + .

        + + Standard Library Exception Policy + - .

        - ia64 c++ abi exception handling - . Richard Henderson. - GNU - . + . Matt Austern. + WG21 N1077 + .

        + + ia64 c++ abi exception handling + - .

        - Appendix E: Standard-Library Exception Safety - . Bjarne Stroustrup. + . Richard Henderson. + GNU + .

        + + Appendix E: Standard-Library Exception Safety + - .

        + . Bjarne Stroustrup.

        Exceptional C++ . Exception-Safety Issues and Techniques - . Herb Sutter.

        - exception_defines.h #defines try/catch - . - GCC Bug 25191 - . + . Herb Sutter.

        + + + GCC Bug 25191: exception_defines.h #defines try/catch + + .

        Prev Up Next
        Concurrency Home Debugging Support
        diff --git a/libstdc++-v3/doc/html/manual/using_headers.html b/libstdc++-v3/doc/html/manual/using_headers.html index 5ce54466d6f..155d82874bc 100644 --- a/libstdc++-v3/doc/html/manual/using_headers.html +++ b/libstdc++-v3/doc/html/manual/using_headers.html @@ -20,19 +20,19 @@ upcoming 200x standard.

        C++98/03 include files. These are available in the default compilation mode, i.e. -std=c++98 or -std=gnu++98. -

        Table 3.2. C++ 1998 Library Headers

        algorithmbitsetcomplexdequeexception
        fstreamfunctionaliomanipiosiosfwd
        iostreamistreamiteratorlimitslist
        localemapmemorynewnumeric
        ostreamqueuesetsstreamstack
        stdexceptstreambufstringutilitytypeinfo
        valarrayvector   

        Table 3.3. C++ 1998 Library Headers for C Library Facilities

        cassertcerrnocctypecfloatciso646
        climitsclocalecmathcsetjmpcsignal
        cstdargcstddefcstdiocstdlibcstring
        ctimecwcharcwctype  

        +

        Table 3.2. C++ 1998 Library Headers

        algorithmbitsetcomplexdequeexception
        fstreamfunctionaliomanipiosiosfwd
        iostreamistreamiteratorlimitslist
        localemapmemorynewnumeric
        ostreamqueuesetsstreamstack
        stdexceptstreambufstringutilitytypeinfo
        valarrayvector   

        Table 3.3. C++ 1998 Library Headers for C Library Facilities

        cassertcerrnocctypecfloatciso646
        climitsclocalecmathcsetjmpcsignal
        cstdargcstddefcstdiocstdlibcstring
        ctimecwcharcwctype  

        C++0x include files. These are only available in C++0x compilation mode, i.e. -std=c++0x or -std=gnu++0x. -

        Table 3.4. C++ 200x Library Headers

        algorithmarraybitsetchronocomplex
        condition_variabledequeexceptionforward_listfstream
        functionalfutureinitalizer_listiomanipios
        iosfwdiostreamistreamiteratorlimits
        listlocalemapmemorymutex
        newnumericostreamqueuerandom
        ratioregexsetsstreamstack
        stdexceptstreambufstringsystem_errorthread
        tupletype_traitstypeinfounordered_mapunordered_set
        utilityvalarrayvector  

        Table 3.5. C++ 200x Library Headers for C Library Facilities

        cassertccomplexcctypecerrnocfenv
        cfloatcinttypesciso646climitsclocale
        cmathcsetjmpcsignalcstdargcstdbool
        cstddefcstdintcstdlibcstdiocstring
        ctgmathctimecucharcwcharcwctype
        stdatomic.h    

        +

        Table 3.4. C++ 200x Library Headers

        algorithmarraybitsetchronocomplex
        condition_variabledequeexceptionforward_listfstream
        functionalfutureinitalizer_listiomanipios
        iosfwdiostreamistreamiteratorlimits
        listlocalemapmemorymutex
        newnumericostreamqueuerandom
        ratioregexsetsstreamstack
        stdexceptstreambufstringsystem_errorthread
        tupletype_traitstypeinfounordered_mapunordered_set
        utilityvalarrayvector  

        Table 3.5. C++ 200x Library Headers for C Library Facilities

        cassertccomplexcctypecerrnocfenv
        cfloatcinttypesciso646climitsclocale
        cmathcsetjmpcsignalcstdargcstdbool
        cstddefcstdintcstdlibcstdiocstring
        ctgmathctimecucharcwcharcwctype
        stdatomic.h    

        In addition, TR1 includes as: -

        Table 3.6. C++ TR 1 Library Headers

        tr1/arraytr1/complextr1/memorytr1/functionaltr1/random
        tr1/regextr1/tupletr1/type_traitstr1/unordered_maptr1/unordered_set
        tr1/utility    

        Table 3.7. C++ TR 1 Library Headers for C Library Facilities

        tr1/ccomplextr1/cfenvtr1/cfloattr1/cmathtr1/cinttypes
        tr1/climitstr1/cstdargtr1/cstdbooltr1/cstdinttr1/cstdio
        tr1/cstdlibtr1/ctgmathtr1/ctimetr1/cwchartr1/cwctype

        Decimal floating-point arithmetic is available if the C++ +

        Table 3.6. C++ TR 1 Library Headers

        tr1/arraytr1/complextr1/memorytr1/functionaltr1/random
        tr1/regextr1/tupletr1/type_traitstr1/unordered_maptr1/unordered_set
        tr1/utility    

        Table 3.7. C++ TR 1 Library Headers for C Library Facilities

        tr1/ccomplextr1/cfenvtr1/cfloattr1/cmathtr1/cinttypes
        tr1/climitstr1/cstdargtr1/cstdbooltr1/cstdinttr1/cstdio
        tr1/cstdlibtr1/ctgmathtr1/ctimetr1/cwchartr1/cwctype

        Decimal floating-point arithmetic is available if the C++ compiler supports scalar decimal floating-point types defined via __attribute__((mode(SD|DD|LD))). -

        Table 3.8. C++ TR 24733 Decimal Floating-Point Header

        decimal/decimal

        +

        Table 3.8. C++ TR 24733 Decimal Floating-Point Header

        decimal/decimal

        Also included are files for the C++ ABI interface: -

        Table 3.9. C++ ABI Headers

        cxxabi.hcxxabi_forced.h

        +

        Table 3.9. C++ ABI Headers

        cxxabi.hcxxabi_forced.h

        And a large variety of extensions. -

        Table 3.10. Extension Headers

        ext/algorithmext/atomicity.hext/array_allocator.hext/bitmap_allocator.hext/cast.h
        ext/codecvt_specializations.hext/concurrence.hext/debug_allocator.hext/enc_filebuf.hext/extptr_allocator.h
        ext/functionalext/iteratorext/malloc_allocator.hext/memoryext/mt_allocator.h
        ext/new_allocator.hext/numericext/numeric_traits.hext/pb_ds/assoc_container.hext/pb_ds/priority_queue.h
        ext/pod_char_traits.hext/pool_allocator.hext/rb_treeext/ropeext/slist
        ext/stdio_filebuf.hext/stdio_sync_filebuf.hext/throw_allocator.hext/typelist.hext/type_traits.h
        ext/vstring.h    

        Table 3.11. Extension Debug Headers

        debug/bitsetdebug/dequedebug/listdebug/mapdebug/set
        debug/stringdebug/unordered_mapdebug/unordered_setdebug/vector 

        Table 3.12. Extension Profile Headers

        profile/bitsetprofile/dequeprofile/listprofile/map
        profile/setprofile/unordered_mapprofile/unordered_setprofile/vector

        Table 3.13. Extension Parallel Headers

        parallel/algorithmparallel/numeric

        Mixing Headers

        A few simple rules. +

        Table 3.10. Extension Headers

        ext/algorithmext/atomicity.hext/array_allocator.hext/bitmap_allocator.hext/cast.h
        ext/codecvt_specializations.hext/concurrence.hext/debug_allocator.hext/enc_filebuf.hext/extptr_allocator.h
        ext/functionalext/iteratorext/malloc_allocator.hext/memoryext/mt_allocator.h
        ext/new_allocator.hext/numericext/numeric_traits.hext/pb_ds/assoc_container.hext/pb_ds/priority_queue.h
        ext/pod_char_traits.hext/pool_allocator.hext/rb_treeext/ropeext/slist
        ext/stdio_filebuf.hext/stdio_sync_filebuf.hext/throw_allocator.hext/typelist.hext/type_traits.h
        ext/vstring.h    

        Table 3.11. Extension Debug Headers

        debug/bitsetdebug/dequedebug/listdebug/mapdebug/set
        debug/stringdebug/unordered_mapdebug/unordered_setdebug/vector 

        Table 3.12. Extension Profile Headers

        profile/bitsetprofile/dequeprofile/listprofile/map
        profile/setprofile/unordered_mapprofile/unordered_setprofile/vector

        Table 3.13. Extension Parallel Headers

        parallel/algorithmparallel/numeric

        Mixing Headers

        A few simple rules.

        First, mixing different dialects of the standard headers is not possible. It's an all-or-nothing affair. Thus, code like 

        diff --git a/libstdc++-v3/doc/html/manual/using_macros.html b/libstdc++-v3/doc/html/manual/using_macros.html
index 9daf4d3405c..ded3c5a4c35 100644
--- a/libstdc++-v3/doc/html/manual/using_macros.html
+++ b/libstdc++-v3/doc/html/manual/using_macros.html
@@ -59,19 +59,19 @@
 	--enable-concept-checks.  When defined, performs
 	compile-time checking on certain template instantiations to
 	detect violations of the requirements of the standard.  This
-	is described in more detail here.
+	is described in more detail here.
       
        _GLIBCXX_DEBUG
        
 	Undefined by default. When defined, compiles user code using
-    the debug mode.
+    the debug mode.
       
        _GLIBCXX_DEBUG_PEDANTIC
        
 	Undefined by default. When defined while compiling with
-    the debug mode, makes
+    the debug mode, makes
     the debug mode extremely picky by making the use of libstdc++
     extensions and libstdc++-specific behavior into errors.
       
        _GLIBCXX_PARALLEL
        Undefined by default. When defined, compiles user code
-    using the parallel
+    using the parallel
     mode.
       
        _GLIBCXX_PROFILE
        Undefined by default. When defined, compiles user code
-    using the profile
+    using the profile
     mode.
        Prev Up Next
        Headers Home Namespaces
        diff --git a/libstdc++-v3/doc/html/manual/utilities.html b/libstdc++-v3/doc/html/manual/utilities.html index 643a52964a9..9a801d7a6b3 100644 --- a/libstdc++-v3/doc/html/manual/utilities.html +++ b/libstdc++-v3/doc/html/manual/utilities.html @@ -1,9 +1,17 @@ -Part IV.  Utilities
        Part IV.  +Chapter 6.  Utilities
        Chapter 6.  Utilities -
        Prev The GNU C++ Library Next

        Part IV.  +

        Prev Part II.  + Standard Contents + Next

        Chapter 6.  Utilities - -

        Table of Contents

        9. Functors
        10. Pairs
        11. Memory
        Allocators
        Requirements
        Design Issues
        Implementation
        Using a Specific Allocator
        Custom Allocators
        Extension Allocators
        auto_ptr
        Limitations
        Use in Containers
        shared_ptr
        Requirements
        Design Issues
        Implementation
        Use
        Acknowledgments
        12. Traits
        Prev Up Next
        Adding Data to Exceptions Home Chapter 9. Functors
        + +

        Table of Contents

        Functors
        Pairs
        Memory
        Allocators
        auto_ptr
        shared_ptr
        Traits

        Functors

        If you don't know what functors are, you're not alone. Many people + get slightly the wrong idea. In the interest of not reinventing + the wheel, we will refer you to the introduction to the functor + concept written by SGI as chapter of their STL, in + their + http://www.sgi.com/tech/stl/functors.html. +

        Prev Up Next
        Concept Checking Home Pairs
        diff --git a/libstdc++-v3/doc/html/manual/vector.html b/libstdc++-v3/doc/html/manual/vector.html deleted file mode 100644 index 8f554385943..00000000000 --- a/libstdc++-v3/doc/html/manual/vector.html +++ /dev/null @@ -1,13 +0,0 @@ - - -vector
        vector
        Prev Chapter 16. Sequences Next

        vector

        -

        Space Overhead Management

        - In this - message to the list, Daniel Kostecky announced work on an - alternate form of std::vector that would support - hints on the number of elements to be over-allocated. The design - was also described, along with possible implementation choices. -

        - The first two alpha releases were announced here - and here. -

        Prev Up Next
        Chapter 16. Sequences Home Chapter 17. Associative
        diff --git a/libstdc++-v3/doc/html/manual/verbose_termination.html b/libstdc++-v3/doc/html/manual/verbose_termination.html deleted file mode 100644 index 540e5a77577..00000000000 --- a/libstdc++-v3/doc/html/manual/verbose_termination.html +++ /dev/null @@ -1,79 +0,0 @@ - - -Verbose Terminate Handler
        Verbose Terminate Handler
        Prev Chapter 6. Termination Next

        Verbose Terminate Handler

        - If you are having difficulty with uncaught exceptions and want a - little bit of help debugging the causes of the core dumps, you can - make use of a GNU extension, the verbose terminate handler. - 

        -#include <exception>
-  
-int main()
-{
-  std::set_terminate(__gnu_cxx::__verbose_terminate_handler);
-  ...
-
-  throw anything;
-}
-

        - The __verbose_terminate_handler function - obtains the name of the current exception, attempts to demangle - it, and prints it to stderr. If the exception is derived from - exception then the output from - what() will be included. -

        - Any replacement termination function is required to kill the - program without returning; this one calls abort. -

        - For example: - 

        -#include <exception>
-#include <stdexcept>
-
-struct argument_error : public std::runtime_error
-{  
-  argument_error(const std::string& s): std::runtime_error(s) { }
-};
-
-int main(int argc)
-{
-  std::set_terminate(__gnu_cxx::__verbose_terminate_handler);
-  if (argc > 5)
-    throw argument_error(“argc is greater than 5!”);
-  else
-    throw argc;
-}
-

        - With the verbose terminate handler active, this gives: - 

        -   
-   % ./a.out
-   terminate called after throwing a `int'
-   Aborted
-   % ./a.out f f f f f f f f f f f
-   terminate called after throwing an instance of `argument_error'
-   what(): argc is greater than 5!
-   Aborted
-   
-

        - The 'Aborted' line comes from the call to - abort(), of course. -

        - This is the default termination handler; nothing need be done to - use it. To go back to the previous “silent death” - method, simply include exception and - cstdlib, and call - 

        -     std::set_terminate(std::abort);
-

        - After this, all calls to terminate will use - abort as the terminate handler. -

        - Note: the verbose terminate handler will attempt to write to - stderr. If your application closes stderr or redirects it to an - inappropriate location, - __verbose_terminate_handler will behave in - an unspecified manner. -

        Prev Up Next
        Chapter 6. Termination Home Part III.  - Diagnostics - -
        diff --git a/libstdc++-v3/doc/html/spine.html b/libstdc++-v3/doc/html/spine.html index edcf88aae34..585f7cdf1ea 100644 --- a/libstdc++-v3/doc/html/spine.html +++ b/libstdc++-v3/doc/html/spine.html @@ -5,43 +5,53 @@

        Table of Contents

        The GNU C++ Library
        I. Introduction -
        1. Status
        Implementation Status
        C++ 1998/2003
        C++ 200x
        C++ TR1
        C++ TR 24733
        License
        The Code: GPL
        The Documentation: GPL, FDL
        Bugs
        Implementation Bugs
        Standard Bugs
        2. Setup
        Prerequisites
        Configure
        Make
        3. Using
        Command Options
        Headers
        Header Files
        Mixing Headers
        The C Headers and namespace std
        Precompiled Headers
        Macros
        Namespaces
        Available Namespaces
        namespace std
        Using Namespace Composition
        Linking
        Almost Nothing
        Finding Dynamic or Shared Libraries
        Concurrency
        Prerequisites
        Thread Safety
        Atomics
        IO
        Containers
        Exceptions
        Exception Safety
        Exception Neutrality
        Doing without
        Compatibility
        Debugging Support
        Using g++
        Debug Versions of Library Binary Files
        Memory Leak Hunting
        Using gdb
        Tracking uncaught exceptions
        Debug Mode
        Compile Time Checking
        Profile-based Performance Analysis
        II. +
        1. Status
        Implementation Status
        C++ 1998/2003
        C++ 200x
        C++ TR1
        C++ TR 24733
        License
        The Code: GPL
        The Documentation: GPL, FDL
        Bugs
        Implementation Bugs
        Standard Bugs
        2. Setup
        Prerequisites
        Configure
        Make
        3. Using
        Command Options
        Headers
        Header Files
        Mixing Headers
        The C Headers and namespace std
        Precompiled Headers
        Macros
        Namespaces
        Available Namespaces
        namespace std
        Using Namespace Composition
        Linking
        Almost Nothing
        Finding Dynamic or Shared Libraries
        Concurrency
        Prerequisites
        Thread Safety
        Atomics
        IO
        Containers
        Exceptions
        Exception Safety
        Exception Neutrality
        Doing without
        Compatibility
        Debugging Support
        Using g++
        Debug Versions of Library Binary Files
        Memory Leak Hunting
        Using gdb
        Tracking uncaught exceptions
        Debug Mode
        Compile Time Checking
        Profile-based Performance Analysis
        II. + Standard Contents +
        4. Support -
        4. Types
        Fundamental Types
        Numeric Properties
        NULL
        5. Dynamic Memory
        6. Termination
        Termination Handlers
        Verbose Terminate Handler
        III. +
        Types
        Fundamental Types
        Numeric Properties
        NULL
        Dynamic Memory
        Termination
        Termination Handlers
        Verbose Terminate Handler
        5. Diagnostics -
        7. Exceptions
        Exception Classes
        Adding Data to Exceptions
        8. Concept Checking
        IV. +
        Exceptions
        API Reference
        Adding Data to exception
        Concept Checking
        6. Utilities -
        9. Functors
        10. Pairs
        11. Memory
        Allocators
        Requirements
        Design Issues
        Implementation
        Using a Specific Allocator
        Custom Allocators
        Extension Allocators
        auto_ptr
        Limitations
        Use in Containers
        shared_ptr
        Requirements
        Design Issues
        Implementation
        Use
        Acknowledgments
        12. Traits
        V. +
        Functors
        Pairs
        Memory
        Allocators
        auto_ptr
        shared_ptr
        Traits
        7. Strings -
        13. String Classes
        Simple Transformations
        Case Sensitivity
        Arbitrary Character Types
        Tokenizing
        Shrink to Fit
        CString (MFC)
        VI. +
        String Classes
        Simple Transformations
        Case Sensitivity
        Arbitrary Character Types
        Tokenizing
        Shrink to Fit
        CString (MFC)
        8. Localization -
        14. Locales
        locale
        Requirements
        Design
        Implementation
        Future
        15. Facets aka Categories
        ctype
        Implementation
        Future
        codecvt
        Requirements
        Design
        Implementation
        Use
        Future
        messages
        Requirements
        Design
        Implementation
        Use
        Future
        VII. +
        Locales
        locale
        Facets
        ctype
        codecvt
        messages
        9. Containers -
        16. Sequences
        list
        list::size() is O(n)
        vector
        Space Overhead Management
        17. Associative
        Insertion Hints
        bitset
        Size Variable
        Type String
        18. Interacting with C
        Containers vs. Arrays
        VIII. +
        Sequences
        list
        vector
        Associative
        Insertion Hints
        bitset
        Interacting with C
        Containers vs. Arrays
        10. Iterators -
        19. Predefined
        Iterators vs. Pointers
        One Past the End
        IX. +
        Predefined
        Iterators vs. Pointers
        One Past the End
        11. Algorithms -
        20. Mutating
        swap
        Specializations
        X. +
        Mutating
        swap
        12. Numerics -
        21. Complex
        complex Processing
        22. Generalized Operations
        23. Interacting with C
        Numerics vs. Arrays
        C99
        XI. +
        Complex
        complex Processing
        Generalized Operations
        Interacting with C
        Numerics vs. Arrays
        C99
        13. Input and Output -
        24. Iostream Objects
        25. Stream Buffers
        Derived streambuf Classes
        Buffering
        26. Memory Based Streams
        Compatibility With strstream
        27. File Based Streams
        Copying a File
        Binary Input and Output
        28. Interacting with C
        Using FILE* and file descriptors
        Performance
        XII. +
        Iostream Objects
        Stream Buffers
        Derived streambuf Classes
        Buffering
        Memory Based Streams
        Compatibility With strstream
        File Based Streams
        Copying a File
        Binary Input and Output
        Interacting with C
        Using FILE* and file descriptors
        Performance
        14. + Atomics + +
        API Reference
        15. + Concurrency + +
        API Reference
        III. Extensions -
        29. Compile Time Checks
        30. Debug Mode
        Intro
        Semantics
        Using
        Using the Debug Mode
        Using a Specific Debug Container
        Design
        Goals
        Methods
        Other Implementations
        31. Parallel Mode
        Intro
        Semantics
        Using
        Prerequisite Compiler Flags
        Using Parallel Mode
        Using Specific Parallel Components
        Design
        Interface Basics
        Configuration and Tuning
        Implementation Namespaces
        Testing
        Bibliography
        32. Profile Mode
        Intro
        Using the Profile Mode
        Tuning the Profile Mode
        Design
        Wrapper Model
        Instrumentation
        Run Time Behavior
        Analysis and Diagnostics
        Cost Model
        Reports
        Testing
        Extensions for Custom Containers
        Empirical Cost Model
        Implementation Issues
        Stack Traces
        Symbolization of Instruction Addresses
        Concurrency
        Using the Standard Library in the Instrumentation Implementation
        Malloc Hooks
        Construction and Destruction of Global Objects
        Developer Information
        Big Picture
        How To Add A Diagnostic
        Diagnostics
        Diagnostic Template
        Containers
        Algorithms
        Data Locality
        Multithreaded Data Access
        Statistics
        Bibliography
        33. Allocators
        mt_allocator
        Intro
        Design Issues
        Implementation
        Single Thread Example
        Multiple Thread Example
        bitmap_allocator
        Design
        Implementation
        34. Containers
        Policy Based Data Structures
        HP/SGI
        Deprecated HP/SGI
        35. Utilities
        36. Algorithms
        37. Numerics
        38. Iterators
        39. Input and Output
        Derived filebufs
        40. Demangling
        41. Concurrency
        Design
        Interface to Locks and Mutexes
        Interface to Atomic Functions
        Implementation
        Using Builtin Atomic Functions
        Thread Abstraction
        Use
        A. +
        16. Compile Time Checks
        17. Debug Mode
        Intro
        Semantics
        Using
        Using the Debug Mode
        Using a Specific Debug Container
        Design
        Goals
        Methods
        Other Implementations
        18. Parallel Mode
        Intro
        Semantics
        Using
        Prerequisite Compiler Flags
        Using Parallel Mode
        Using Specific Parallel Components
        Design
        Interface Basics
        Configuration and Tuning
        Implementation Namespaces
        Testing
        Bibliography
        19. Profile Mode
        Intro
        Using the Profile Mode
        Tuning the Profile Mode
        Design
        Wrapper Model
        Instrumentation
        Run Time Behavior
        Analysis and Diagnostics
        Cost Model
        Reports
        Testing
        Extensions for Custom Containers
        Empirical Cost Model
        Implementation Issues
        Stack Traces
        Symbolization of Instruction Addresses
        Concurrency
        Using the Standard Library in the Instrumentation Implementation
        Malloc Hooks
        Construction and Destruction of Global Objects
        Developer Information
        Big Picture
        How To Add A Diagnostic
        Diagnostics
        Diagnostic Template
        Containers
        Algorithms
        Data Locality
        Multithreaded Data Access
        Statistics
        Bibliography
        20. Allocators
        mt_allocator
        Intro
        Design Issues
        Implementation
        Single Thread Example
        Multiple Thread Example
        bitmap_allocator
        Design
        Implementation
        21. Containers
        Policy Based Data Structures
        HP/SGI
        Deprecated HP/SGI
        22. Utilities
        23. Algorithms
        24. Numerics
        25. Iterators
        26. Input and Output
        Derived filebufs
        27. Demangling
        28. Concurrency
        Design
        Interface to Locks and Mutexes
        Interface to Atomic Functions
        Implementation
        Using Builtin Atomic Functions
        Thread Abstraction
        Use
        IV. + Appendices +
        A. Contributing -
        Contributor Checklist
        Reading
        Assignment
        Getting Sources
        Submitting Patches
        Directory Layout and Source Conventions
        Coding Style
        Bad Identifiers
        By Example
        Documentation Style
        Doxygen
        Docbook
        Design Notes
        B. +
        Contributor Checklist
        Reading
        Assignment
        Getting Sources
        Submitting Patches
        Directory Layout and Source Conventions
        Coding Style
        Bad Identifiers
        By Example
        Documentation Style
        Doxygen
        Docbook
        Combines
        Design Notes
        B. Porting and Maintenance
        Configure and Build Hacking
        Prerequisites
        Overview: What Comes from Where
        Storing Information in non-AC files (like configure.host)
        Coding and Commenting Conventions
        The acinclude.m4 layout
        GLIBCXX_ENABLE, the --enable maker
        Porting to New Hardware or Operating Systems
        Operating System
        CPU
        Character Types
        Thread Safety
        Numeric Limits
        Libtool
        Test
        Organization
        Running the Testsuite
        Writing a new test case
        Test Harness and Utilities
        Special Topics
        ABI Policy and Guidelines
        The C++ Interface
        Versioning
        Allowed Changes
        Prohibited Changes
        Implementation
        Testing
        Outstanding Issues
        API Evolution and Deprecation History
        3.0
        3.1
        3.2
        3.3
        3.4
        4.0
        4.1
        4.2
        4.3
        4.4
        4.5
        Backwards Compatibility
        First
        Second
        Third
        C. @@ -49,4 +59,4 @@
        D. GNU General Public License version 3 -
        E. GNU Free Documentation License
        Index
        API and Source Level Documentation
        Frequently Asked Questions
           Next
           The GNU C++ Library
        +
        E. GNU Free Documentation License
        API Documentation
        Frequently Asked Questions
           Next
           The GNU C++ Library
        diff --git a/libstdc++-v3/doc/xml/faq.xml b/libstdc++-v3/doc/xml/faq.xml index 7a0953ccbe0..22d2e629010 100644 --- a/libstdc++-v3/doc/xml/faq.xml +++ b/libstdc++-v3/doc/xml/faq.xml @@ -387,6 +387,11 @@ linker has different names on different platforms but the man page is usually called something such as ld.so/rtld/dld.so. + + Using LD_LIBRARY_PATH is not always the best solution, Finding Dynamic or Shared + Libraries in the manual gives some alternatives. + @@ -895,8 +900,9 @@ More information, including how to optionally enable/disable the - checks, is available - here. + checks, is available in the + Diagnostics. + chapter of the manual. diff --git a/libstdc++-v3/doc/xml/manual/appendix_contributing.xml b/libstdc++-v3/doc/xml/manual/appendix_contributing.xml index 279e7038a9b..393b7f509c3 100644 --- a/libstdc++-v3/doc/xml/manual/appendix_contributing.xml +++ b/libstdc++-v3/doc/xml/manual/appendix_contributing.xml @@ -920,7 +920,7 @@ indicate a place that may require attention for multi-thread safety. Prerequisites - Prerequisite tools are Bash 2.x, + Prerequisite tools are Bash 2.0 or later, Doxygen, and the GNU coreutils. (GNU versions of find, xargs, and possibly diff --git a/libstdc++-v3/doc/xml/manual/prerequisites.xml b/libstdc++-v3/doc/xml/manual/prerequisites.xml index cdfe6ccccb1..d7a162c056a 100644 --- a/libstdc++-v3/doc/xml/manual/prerequisites.xml +++ b/libstdc++-v3/doc/xml/manual/prerequisites.xml @@ -40,6 +40,12 @@ features if the underlying support is present. + + To generate the API documentation from the sources you will need + Doxygen, see Documentation + Style in the appendix for full details. + + Finally, a few system-specific requirements: diff --git a/libstdc++-v3/doc/xml/manual/strings.xml b/libstdc++-v3/doc/xml/manual/strings.xml index 412484e8ef2..8eb9b49a1be 100644 --- a/libstdc++-v3/doc/xml/manual/strings.xml +++ b/libstdc++-v3/doc/xml/manual/strings.xml @@ -366,6 +366,10 @@ stringtok(Container &container, string const &in, entry) but the regular copy constructor cannot be used because libstdc++'s string is Copy-On-Write. + In C++0x mode you can call + s.shrink_to_fit() to achieve the same effect as + s.reserve(s.size()). + diff --git a/libstdc++-v3/doc/xml/manual/using.xml b/libstdc++-v3/doc/xml/manual/using.xml index e4863c2e4dc..bb6077c4e19 100644 --- a/libstdc++-v3/doc/xml/manual/using.xml +++ b/libstdc++-v3/doc/xml/manual/using.xml @@ -1176,22 +1176,42 @@ A quick read of the relevant part of the GCC - GNU ld (default on Linux):-Wl,--rpath,destdir/lib + GNU ld (default on Linux): + -Wl,-rpath,destdir/lib - IRIX ld: - -Wl,-rpath,destdir/lib + IRIX ld: + -Wl,-rpath,destdir/lib - Solaris ld:-Wl,-Rdestdir/lib + Solaris ld: + -Wl,-Rdestdir/lib + + + Some linkers allow you to specify the path to the library by + setting LD_RUN_PATH in your environment + when linking. + + + + + On some platforms the system administrator can configure the + dynamic linker to always look for libraries in + destdir/lib, for example + by using the ldconfig utility on Linux + or the crle utility on Solaris. This is a + system-wide change which can make the system unusable so if you + are unsure then use one of the other methods described above. + + Use the ldd utility on the linked executable