diff options
Diffstat (limited to 'libstdc++-v3/docs/html')
37 files changed, 6100 insertions, 3299 deletions
diff --git a/libstdc++-v3/docs/html/17_intro/C++STYLE b/libstdc++-v3/docs/html/17_intro/C++STYLE index 46fe3f3f160..f838b830124 100644 --- a/libstdc++-v3/docs/html/17_intro/C++STYLE +++ b/libstdc++-v3/docs/html/17_intro/C++STYLE @@ -173,7 +173,7 @@ Notable areas of divergence from what may be previous local practice int foo; 13. Spacing WRT return statements. - no extra spacing before returns + no extra spacing before returns, no parenthesis ie } @@ -184,6 +184,12 @@ Notable areas of divergence from what may be previous local practice return __ret; + -NOT- + + } + return (__ret); + + 14. Location of global variables. All global variables of class type, whether in the "user visable" space (e.g., cin) or the implementation namespace, must be defined @@ -264,7 +270,7 @@ namespace std int two_lines(const char* arg) - { return strchr(arg, 'a'); } + { return strchr(arg, 'a'); } inline int three_lines(); // inline, but defined below. @@ -360,7 +366,3 @@ namespace std } } // namespace std - - - - diff --git a/libstdc++-v3/docs/html/17_intro/RELEASE-NOTES b/libstdc++-v3/docs/html/17_intro/RELEASE-NOTES index 6e98a526f9e..79920407c21 100644 --- a/libstdc++-v3/docs/html/17_intro/RELEASE-NOTES +++ b/libstdc++-v3/docs/html/17_intro/RELEASE-NOTES @@ -1,4 +1,4 @@ -2002-02-01 +2002-05-02 Release Notes ------------- @@ -6,7 +6,7 @@ The Standard C++ Library, or libstdc++-v3, is an ongoing project to fully implement the ISO 14882 Standard C++ library as described in chapters 17 through 27 and annex D. -This is the thirteenth snapshot of the libstdc++ rewrite. It is still +This is the fifteenth snapshot of the libstdc++ rewrite. It still has some incomplet and incorrekt parts, but it's a lot less incomplete and incorrect than some of the earlier snapshots, and quite usable. @@ -22,21 +22,18 @@ URL: New: --- -- more doxygen documentation. -- extensions moved out of namespace std -- HPUX long long support -- more string optimizations -- support for NetBSD cross compiles -- concept_check merge from boost -- header simplification -- named locale bug shakeout -- thread testsuite +- more doxygen documentation +- more named locale fixups +- stdio_filebuf that takes fd, FILE +- io performance tuning +- allocation tuning, valgrind fixups +- __cxa_demangle now supported Bugs fixed: ----------- -5148, 3829, 2054, 5174, 2913, 4879, 3150, 5331, 5280, 5198, 5432 -- fix Darwin build issue with '~' in prefix +6533, 6513, 6501, 6511, 5820, 6414, 4150, 6360, 4164, 1072, 6124, +5180, 3457, 3139, 5268, 3983, 5542, 3129, 5207, 3719, 5734 + others. @@ -67,16 +64,20 @@ Obtain the library snapshot via ftp (including these release notes) from ftp://gcc.gnu.org/pub/libstdc++/ The library is maintained by Benjamin Kosnik, Gabriel -Dos Reis, Phil Edwards, and Ulrich Drepper. +Dos Reis, Phil Edwards, Ulrich Drepper, Loren James Rittle, +and Paolo Carlini. Development tools: ------------------ -You will need a recent version of gcc to compile the snapshot of -libstdc++. The use of CVS gcc, or gcc-3_0-branch is strongly -recommended, which may introduce additional dependencies for -up-to-date binutils. In addition, you may need up-to-date tools for -modifying Makefiles and regenerating configure scripts: automake -(version 1.4), autoconf (version 2.13 and higher), and libtool. +You will need a current version of gcc to compile this snapshot of +libstdc++. The use of the latest stable gcc-3.0.x release (3.0.4), CVS +gcc, or gcc-3_1-branch is strongly recommended, which may also +introduce additional dependencies for up-to-date binutils. In +particular, current binutils (2.12) is recommended so that symbol +versioning for the library is on by default. In addition, you may need +up-to-date tools for modifying Makefiles and regenerating configure +scripts: automake (version 1.4), autoconf (version 2.13 and higher), +and libtool. diff --git a/libstdc++-v3/docs/html/17_intro/TODO b/libstdc++-v3/docs/html/17_intro/TODO index 538a4078792..2ba36ad10a3 100644 --- a/libstdc++-v3/docs/html/17_intro/TODO +++ b/libstdc++-v3/docs/html/17_intro/TODO @@ -1,4 +1,8 @@ +- audit for places where __builtin_expect can be used. + - coordinate with "C" library people the "C" compatibility headers. + Explain why an ISO-14882-conformant solution is hopeless, with the current + twisted morass of "C" headers. - do more doxygen manpages @@ -13,7 +17,16 @@ executable speed. - benchmarking addition to the testsuite that does the above. -- implement symbol versioning for ELF targets. +- implement testing for symbol versioning for ELF targets. + +- review streambuf, filebuf, stringbuf to optimize data member +placement. Do pback bits need to be in streambuf? How about +_M_set_indeterminate, etc? + +- Think about naming all member data and member functions consistently +as per +funtions: _M_verb_adverb +data: _M_noun_adjective - exception specifications need to be reviewed for all parts of the library support and utility areas, particularly <new>. diff --git a/libstdc++-v3/docs/html/17_intro/contribute.html b/libstdc++-v3/docs/html/17_intro/contribute.html index 4f16b845d48..1ab24b92fb5 100644 --- a/libstdc++-v3/docs/html/17_intro/contribute.html +++ b/libstdc++-v3/docs/html/17_intro/contribute.html @@ -1,19 +1,18 @@ -<!--990301 slightly modified version of the GCC contribute.html file--> <html> <head> <title>How to contribute</title> </head> -<!--#include virtual="/include/header-subpages.html"--> +<!--990301 slightly modified version of the GCC contribute.html file--> +<!-- #include virtual="/include/header-subpages.html"--> +<body> <h2>How to contribute</h2> <p> The Standard C++ Library v3, or libstc++-2.90.x, follows an open development model. Active contributors are assigned maintainer-ship responsibility, and given write access to the CVS repository. First time submitors and all other potential contributors should follow this procedure: +</p> -<p> -<hr> +<hr /> <h4>ONE : read the documentation</h4> -<p> -<p> <ul> <li> Get and read the relevant sections of the C++ language specification. Copies of the full ISO 14882 standard are available on @@ -27,25 +26,30 @@ and their web-site is right <a href="http://www.ansi.org">here.</a> (And if you've already registered with them, clicking this link will take you to directly to the place where you can <a href="http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%2D1998">buy the standard on-line.)</a> +</li> <li> The library working group bugs, and known defects, can be obtained at these web sites: <a href="http://www.dkuug.dk/jtc1/sc22/wg21/">http://www.dkuug.dk/jtc1/sc22/wg21 </a> and <a href="http://www.comeaucomputing.com/iso/">http://www.comeaucomputing.com/iso/</a> +</li> <li> The newsgroup dedicated to standardization issues is comp.std.c++: this FAQ for this group is quite useful and can be found <a href="http://reality.sgi.com/austern_mti/std-c++/faq.html"> here </a>. +</li> <li> Peruse the <a href="http://www.gnu.ai.mit.edu/prep/standards_toc.html">GNU Coding Standards</a>, and chuckle when you hit the part about "Using Languages Other Than C." +</li> <li> Be familiar with the extensions that preceded these general GNU rules. These style issues for libstdc++ can be found in the file C++STYLE, located in the root level of the distribution, or <a href="C++STYLE"> here. </a> +</li> <li> And last but certainly not least, read the library-specific information found <a href="../documentation.html"> here.</a> +</li> </ul> -<p> -<hr> +<hr /> <h4>TWO : copyright assignment</h4> <p> Small changes can be accepted without a copyright assignment form on @@ -56,40 +60,43 @@ to fill out appropriate disclaimer forms as well. Here is the <a href="libstdc++ Please contact <a href="mailto:benjamin@cygnus.com">Benjamin Kosnik</a> if you are confused about the assignment or have general licensing questions. +</p> -<p> -<hr> +<hr /> <h4>THREE : submitting patches</h4> -<p> +<p> 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: -<p> +</p> + <ul> <li> A description of the bug and how your patch fixes this bug. For - new features a description of the feature and your implementation. + new features a description of the feature and your implementation. </li> <li> A ChangeLog entry as plaintext; see the various ChangeLog files for format and content. If using 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. + entry. See--magic! Similar functionality also exists for vi. </li> <li> A testsuite submission or sample program that will easily and - simply show the existing error or test new functionality. + simply show the existing error or test new functionality. </li> <li> The patch itself. If you are accessing the CVS repository at Cygnus, use "cvs update; cvs diff -c3p NEW"; else, use "diff -c3p OLD NEW" ... If your version of diff does not support these options, then - get the latest version of GNU diff. + get the latest version of GNU diff. </li> <li> 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++ mailinglist. +discussion should be sent to the libstdc++ mailinglist. </li> </ul> +</body> +</html> diff --git a/libstdc++-v3/docs/html/17_intro/howto.html b/libstdc++-v3/docs/html/17_intro/howto.html index 7aa7430abe7..a8cf3976e13 100644 --- a/libstdc++-v3/docs/html/17_intro/howto.html +++ b/libstdc++-v3/docs/html/17_intro/howto.html @@ -1,13 +1,12 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> <html> <head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> - <meta name="KEYWORDS" content="HOWTO, libstdc++, gcc, g++, libg++, STL"> - <meta name="DESCRIPTION" content="HOWTO for libstdc++ chapter 17."> - <meta name="GENERATOR" content="vi and eight fingers"> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> + <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> + <meta name="KEYWORDS" content="HOWTO, libstdc++, gcc, g++, libg++, STL" /> + <meta name="DESCRIPTION" content="HOWTO for libstdc++ chapter 17." /> + <meta name="GENERATOR" content="vi and eight fingers" /> <title>libstdc++-v3 HOWTO: Chapter 17</title> -<link rel="StyleSheet" href="../lib3styles.css"> +<link rel="StyleSheet" href="../lib3styles.css" /> </head> <body> @@ -21,17 +20,18 @@ <!-- ####################################################### --> -<hr> +<hr /> <h1>Contents</h1> <ul> - <li><a href="#2">The Standard C++ header files</a> - <li><a href="#3">The Standard C++ library and multithreading</a> - <li><a href="#4"><code><foo></code> vs <code><foo.h></code></a> - <li><a href="porting-howto.html">Porting HOWTO</a> - <li><a href="#5">Behavior specific to libstdc++-v3</a> + <li><a href="#2">The Standard C++ header files</a></li> + <li><a href="#3">The Standard C++ library and multithreading</a></li> + <li><a href="#4"><code><foo></code> vs <code><foo.h></code></a></li> + <li><a href="porting-howto.html">Porting HOWTO</a></li> + <li><a href="#5">Behavior specific to libstdc++-v3</a></li> + <li><a href="#6">Preprocessor macros controlling the library</a></li> </ul> -<hr> +<hr /> <!-- ####################################################### --> @@ -50,24 +50,24 @@ all compile and run. </p> -<hr> +<hr /> <h2><a name="3">The Standard C++ library and multithreading</a></h2> <p>This section discusses issues surrounding the proper compilation of multithreaded applications which use the Standard C++ - library. This information is gcc-specific since the C++ + library. This information is GCC-specific since the C++ standard does not address matters of multithreaded applications. Unless explicitly prefaced, all information in this section is - current as of the gcc 3.0 release and all later point releases. + current as of the GCC 3.0 release and all later point releases. </p> - <p>Earlier gcc releases had a somewhat different approach to - threading configuration and proper compilation. Before gcc 3.0, + <p>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 command-line options and macros (both of which were somewhat thread-implementation and port-specific). There were no guarantees related to being able to link code compiled with one - set of options and macro setting with another set. For gcc 3.0, + set of options and macro setting with another set. For GCC 3.0, configuration of the threading model used with libraries and - user-code is performed when gcc is configured and built using + user-code is performed when GCC is configured and built using the --enable-threads and --disable-threads options. The ABI is stable for symbol name-mangling and limited functional compatibility exists between code compiled under different @@ -83,9 +83,9 @@ with another thread model useful on the platform. Other mixes may or may not work but are not considered supported. (Thus, if you distribute a shared C++ library in binary form only, it may - be best to compile it with a gcc configured with + be best to compile it with a GCC configured with --enable-threads for maximal interchangeability and usefulness - with a user population that may have built gcc with either + with a user population that may have built GCC with either --enable-threads or --disable-threads.) </p> <p>When you link a multithreaded application, you will probably @@ -128,16 +128,17 @@ relevant message in the thread; from there you can use "Thread Next" to move down the thread. This farm is in latest-to-oldest order. + </p> <ul> <li>Our threading expert Loren gives a breakdown of <a href="http://gcc.gnu.org/ml/libstdc++/2001-10/msg00024.html">the - six situations involving threads</a> for the 3.0 release series. + six situations involving threads</a> for the 3.0 release series.</li> <li><a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html"> This message</a> inspired a recent updating of issues with threading and the SGI STL library. It also contains some example - POSIX-multithreaded STL code. + POSIX-multithreaded STL code.</li> </ul> - (A large selection of links to older messages has been removed; many + <p> (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 with work to restore them. Many of the points have been superseded anyhow.) @@ -149,7 +150,7 @@ <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="4"><code><foo></code> vs <code><foo.h></code></a></h2> <p>The new-style headers are fully supported in libstdc++-v3. The compiler itself fully supports namespaces, including <code>std::</code>. @@ -157,22 +158,24 @@ <p>For those of you new to ISO C++98, no, that isn't a typo, the headers really have new names. Marshall Cline's C++ FAQ Lite has a good explanation in -<a href="http://www.cerfnet.com/~mpcline/On-Line-C++-FAQ/coding-standards.html#[25.4]">item [25.4]</a>. +<a href="http://www.parashift.com/c++-faq-lite/coding-standards.html#faq-26.4">item [26.4]</a>. </p> <p>Return <a href="#top">to top of page</a> or <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="5">Behavior specific to libstdc++-v3</a></h2> <p>The ISO standard defines the following phrase: + </p> <blockquote><dl> - <dt><code>[1.3.5] implementation-defined behavior</code> + <dt><code>[1.3.5] implementation-defined behavior</code></dt> <dd>behavior, for a well-formed program construct and correct data, that depends on the implementation <strong>and that each implementation shall document</strong>. + </dd> </dl></blockquote> - We do so here, for the C++ library only. Behavior of the compiler, + <p>We do so here, for the C++ library only. Behavior of the compiler, linker, runtime loader, and other elements of "the implementation" are documented elsewhere. Everything listed in Annex B, Implemenation Qualities, are also part of the compiler, not @@ -195,16 +198,17 @@ sections, libstdc++-v3 has zero control over what the cleanup code hands back to the runtime loader. Talk to the compiler people. :-) </p> - <p><strong>[18.4.2.1]/5</strong> (bad_alloc),<br> - <strong>[18.5.2]/5</strong> (bad_cast),<br> - <strong>[18.5.3]/5</strong> (bad_typeid),<br> - <strong>[18.6.1]/8</strong> (exception),<br> + <p><strong>[18.4.2.1]/5</strong> (bad_alloc),<br /> + <strong>[18.5.2]/5</strong> (bad_cast),<br /> + <strong>[18.5.3]/5</strong> (bad_typeid),<br /> + <strong>[18.6.1]/8</strong> (exception),<br /> <strong>[18.6.2.1]/5</strong> (bad_exception): The <code>what()</code> member function of class <code>std::exception</code>, and these other classes publicly derived from it, simply returns the name of the class. But they are the <em>mangled</em> names; you will need to call <code>c++filt</code> and pass the names as command-line parameters to - demangle them. + demangle them, or call a + <a href="../18_support/howto.html#5">runtime demangler function</a>. (The classes in <code><stdexcept></code> have constructors which require an argument to use later for <code>what()</code> calls, so the question does not arise in most user-defined exceptions.) @@ -223,10 +227,10 @@ have any allocators which compare non-equal, so we can't describe how they behave. </p> - <p><strong>[21.1.3.1]/3,4</strong>,<br> - <strong>[21.1.3.2]/2</strong>,<br> - <strong>[23.*]'s foo::iterator</strong>,<br> - <strong>[27.*]'s foo::*_type</strong>,<br> + <p><strong>[21.1.3.1]/3,4</strong>,<br /> + <strong>[21.1.3.2]/2</strong>,<br /> + <strong>[23.*]'s foo::iterator</strong>,<br /> + <strong>[27.*]'s foo::*_type</strong>,<br /> <strong>others...</strong> Nope, these types are called implementation-defined because you shouldn't be taking advantage of their underlying types. Listing them @@ -255,7 +259,7 @@ than the minimum required. I don't think we're currently taking advantage of this yet. </p> - <p><strong>[27.7.1.3]/16</strong>,<br> + <p><strong>[27.7.1.3]/16</strong>,<br /> <strong>[27.8.1.4]/10</strong> The effects of <code>pubsetbuf/setbuf</code> are described <a href="../27_io/howto.html#2">in this chapter</a>. @@ -267,11 +271,76 @@ <a href="../faq/index.html">to the FAQ</a>. </p> +<hr /> +<h2><a name="6">Preprocessor macros controlling the library</a></h2> + <p>Some of the semantics of the libstdc++-v3 implementation are + controlled by preprocessor macros, both during build/installation and + during compilation of user code. Many of these choices are made when + the library is built and installed (actually, during + <a href="../configopts.html">the configuration step</a>, with the + various --enable/--disable choices being translated to #define/#undef). + </p> + <p>All library macros begin with <code>_GLIBCPP_</code>. The fact that + these symbols start with a leading underscore should give you a clue + that (by default) they aren't meant to be changed by the user. :-) + </p> + <p>These macros are all gathered in the file <code>c++config.h</code>, + which is generated during installation. <strong>You must assume that + these macros cannot be redefined by your own code</strong>, unless we + document otherwise here. Some of the choices control code which has + already been compiled (i.e., libstdc++.a/.so). If you explicitly + #define or #undef these macros, the <em>headers</em> may see different + code paths, but the <em>libraries</em> which you link against will not. + If you want to experiment with different values, you must change the + config headers before building/installing the library. + </p> + <p>Below are macros which, for 3.1 and later, you may change yourself, + in your own code with #define/#undef or with -D/-U compiler flags. + The default state of the symbol is listed. "Configurable" + (or "Not configurable") means that the symbol is initially + chosen (or not) based on --enable/--disable options at configure time. + </p> + <dl> + <dt><code>_GLIBCPP_DEPRECATED</code></dt> + <dd>Undefined by default. Not configurable. Turning this on enables + older ARM-style iostreams code, and other anachronisms. This may be + useful in updating old C++ programs which no longer meet the + requirements of the language. + </dd> + <!-- + Can this actually be turned off and still produce a working lib? Must + check. -pme + No, it can't. Hmmm. -pme + <dt><code>_GLIBCPP_RESOLVE_LIB_DEFECTS</code></dt> + <dd>Defined by default. Not configurable. The library follows + corrections and updates from the ISO committee, see + <a href="../faq/index.html#5_2">here</a> and + <a href="../ext/howto.html#5">here</a> for more on this feature. + If you have code which depends on the first version of the standard, + you might try undefining this macro. + </dd> + --> + <dt><code>_GLIBCPP_CONCEPT_CHECKS</code></dt> + <dd>Undefined by default. Configurable. 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 <a href="../19_diagnostics/howto.html#3">here</a>. + </dd> + <!-- + <dt><code></code></dt> + <dd> + </dd> + --> + </dl> + <p>Return <a href="#top">to top of page</a> or + <a href="../faq/index.html">to the FAQ</a>. + </p> + <!-- ####################################################### --> -<hr> +<hr /> <p class="fineprint"><em> See <a href="license.html">license.html</a> for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/17_intro/license.html b/libstdc++-v3/docs/html/17_intro/license.html index c3449b1ff2f..7db8aa5f240 100644 --- a/libstdc++-v3/docs/html/17_intro/license.html +++ b/libstdc++-v3/docs/html/17_intro/license.html @@ -1,13 +1,12 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> <html> <head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> - <meta name="KEYWORDS" content="libstdc++, license, licence"> - <meta name="DESCRIPTION" content="Copying restrictions for libstdc++."> - <meta name="GENERATOR" content="vi and eight fingers"> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> + <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> + <meta name="KEYWORDS" content="libstdc++, license, licence" /> + <meta name="DESCRIPTION" content="Copying restrictions for libstdc++." /> + <meta name="GENERATOR" content="vi and eight fingers" /> <title>libstdc++-v3 copying</title> -<link rel="StyleSheet" href="../lib3styles.css"> +<link rel="StyleSheet" href="../lib3styles.css" /> </head> <body> @@ -21,7 +20,7 @@ writing this page is a programmer, not a lawyer. </p> -<hr> +<hr /> <h2>The Code: Runtime GPL</h2> @@ -29,7 +28,8 @@ <a href="COPYING">GNU General Public License</a>, with the so-called "runtime exception," as follows (or see any header or implementation file): - <pre> +</p> +<pre> As a special exception, you may use this file as part of a free software library without restriction. Specifically, if other files instantiate templates or use macros or inline functions from this file, or you compile @@ -38,8 +38,7 @@ the GNU General Public License. This exception does not however invalidate any other reasons why the executable file might be covered by the GNU General Public License. - </pre> -</p> +</pre> <p>Hopefully that text is self-explanatory. If it isn't, you need to speak to your lawyer, or the Free Software Foundation. @@ -50,14 +49,14 @@ http://gcc.gnu.org/ml/libstdc++/2000-q2/subjects.html#00050 --> <p><strong>Q: So any program which uses libstdc++ falls under the GPL?</strong> - <br>A: <strong>No.</strong> The special exception permits use of the + <br />A: <strong>No.</strong> The special exception permits use of the library in proprietary applications. </p> <p><strong>Q: How is that different from the GNU {Lesser,Library} GPL?</strong> <!-- Quoting Jason Merrill from the thread above: --> - <br>A: The LGPL requires that users be able to replace the LGPL code with a + <br />A: The LGPL requires that users be able to replace the LGPL code with a modified version; this is trivial if the library in question is a C shared library. But there's no way to make that work with C++, where much of the library consists of inline functions and templates, which @@ -68,11 +67,11 @@ <p><strong>Q: I see. So, what restrictions <em>are</em> there on programs that use the library?</strong> - <br>A: None. We encourage such programs to be released as open source, + <br />A: None. We encourage such programs to be released as open source, but we won't punish you or sue you if you choose otherwise. </p> -<hr> +<hr /> <h2>The Docs: FDL</h2> @@ -92,7 +91,7 @@ <!-- ####################################################### --> -<hr> +<hr /> <p class="fineprint"><em> Comments and suggestions about this page are welcome, and may be sent to <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>. diff --git a/libstdc++-v3/docs/html/17_intro/porting-howto.html b/libstdc++-v3/docs/html/17_intro/porting-howto.html index c9a45c3bbfc..8e8ca99c46f 100644 --- a/libstdc++-v3/docs/html/17_intro/porting-howto.html +++ b/libstdc++-v3/docs/html/17_intro/porting-howto.html @@ -3,9 +3,9 @@ <head> <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"> <title>Libstdc++-porting-howto</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.29"> +<meta name="generator" content="DocBook XSL Stylesheets V1.48"> </head> -<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div id="libstdc++-porting-howto" class="article"> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article"> <div class="titlepage"> <div><h1 class="title"> <a name="libstdc++-porting-howto"></a>Libstdc++-porting-howto</h1></div> @@ -84,9 +84,7 @@ </td></tr> </table></div></div> <div><div class="abstract"> -<p> -<a name="id2697062"></a><b>Abstract</b> -</p> +<p><b>Abstract</b></p> <p> Some notes on porting applications from libstdc++-2.90 (or earlier versions) to libstdc++-v3. Not speaking in terms of the GNU libstdc++ @@ -102,8 +100,8 @@ <dt>1. <a href="#sec-nsstd">Namespace std::</a> </dt> <dd><dl> -<dt>1.1.1. <a href="#sec-gtkmm-hack">Using <i>namespace - composition</i> if the project uses a separate +<dt>1.1.1. <a href="#sec-gtkmm-hack">Using namespace + composition if the project uses a separate namespace</a> </dt> <dt>1.1.2. <a href="#sec-emptyns">Defining an empty namespace std</a> @@ -118,8 +116,8 @@ <dt>2. <a href="#sec-nocreate">there is no ios::nocreate/ios::noreplace in ISO 14882</a> </dt> -<dt>3. <a href="#sec-stream::attach"><b>stream::attach(int - fd)</b> is not in the standard any more</a> +<dt>3. <a href="#sec-stream::attach">stream::attach(int + fd) is not in the standard any more</a> </dt> <dt>4. <a href="#sec-headers">The new headers</a> </dt> @@ -127,16 +125,16 @@ <dt>4.4.1. <a href="#sec-cheaders">New headers replacing C-headers</a> </dt> <dt>4.4.2. <a href="#sec-fstream-header"> - <tt><fstream></tt> does - not define <b>std::cout</b>, - <b>std::cin</b> etc.</a> + <fstream> does + not define std::cout, + std::cin etc.</a> </dt> </dl></dd> <dt>5. <a href="#sec-iterators">Iterators</a> </dt> <dt>6. <a href="#sec-macros"> - Libc-macros (i.e. <b>isspace</b> from - <tt><cctype></tt>)</a> + Libc-macros (i.e. isspace from + <cctype>)</a> </dt> <dt>7. <a href="#sec-stream-state">State of streams</a> </dt> @@ -161,29 +159,25 @@ libstdc++-implementations". </p> <div class="section"> -<a name="sec-nsstd"></a><div class="titlepage"><div><h2 class="title" style="clear: all"> -<a name="sec-nsstd"></a><span class="label">1.</span> <span class="title">Namespace std::</span> -</h2></div></div> +<div class="titlepage"><div><h2 class="title" style="clear: both"> +<a name="sec-nsstd"></a>Namespace std::</h2></div></div> <p> The latest C++-standard (ISO-14882) requires that the standard C++-library is defined in namespace std::. Thus, in order to use classes from the standard C++-library, you can do one of three things: - <div class="itemizedlist"><ul> -<li><p> -<a name="id2697113"></a>wrap your code in <b>namespace std { + <div class="itemizedlist"><ul type="disc"> +<li><p>wrap your code in <b>namespace std { ... }</b> => This is not an option because only symbols from the standard c++-library are defined in namespace std::. </p></li> -<li><p> -<a name="id2697126"></a>put a kind of - <i>using-declaration</i> in your source (either +<li><p>put a kind of + <span class="emphasis"><i>using-declaration</i></span> in your source (either <b>using namespace std;</b> or i.e. <b>using std::string;</b>) => works well for source-files, but cannot be used in header-files. </p></li> -<li><p> -<a name="id2697047"></a>use a <i>fully qualified name</i> for +<li><p>use a <span class="emphasis"><i>fully qualified name</i></span> for each libstdc++-symbol (i.e. <b>std::string</b>, <b>std::cout</b>) => can always be used </p></li> @@ -210,17 +204,16 @@ that cannot ignore std::. </p> <div class="section"> -<a name="sec-gtkmm-hack"></a><div class="titlepage"><div><h3 class="title"> -<a name="sec-gtkmm-hack"></a><span class="label">1.1.1.</span> <span class="title">Using <i>namespace - composition</i> if the project uses a separate - namespace</span> -</h3></div></div> +<div class="titlepage"><div><h3 class="title"> +<a name="sec-gtkmm-hack"></a>Using <span class="emphasis"><i>namespace + composition</i></span> if the project uses a separate + namespace</h3></div></div> <p> <a href="http://gtkmm.sourceforge.net" target="_top">Gtk--</a> defines most of its classes in namespace Gtk::. Thus, it was possible to adapt Gtk-- to namespace std:: by using a C++-feature called - <i>namespace composition</i>. This is what happens if - you put a <i>using</i>-declaration into a + <span class="emphasis"><i>namespace composition</i></span>. This is what happens if + you put a <span class="emphasis"><i>using</i></span>-declaration into a namespace-definition: the imported symbol(s) gets imported into the currently active namespace(s). For example: <pre class="programlisting"> @@ -245,9 +238,8 @@ </p> </div> <div class="section"> -<a name="sec-emptyns"></a><div class="titlepage"><div><h3 class="title"> -<a name="sec-emptyns"></a><span class="label">1.1.2.</span> <span class="title">Defining an empty namespace std</span> -</h3></div></div> +<div class="titlepage"><div><h3 class="title"> +<a name="sec-emptyns"></a>Defining an empty namespace std</h3></div></div> <p> By defining an (empty) namespace <b>std::</b> before using it, you avoid getting errors on systems where no part of the @@ -259,18 +251,16 @@ </p> </div> <div class="section"> -<a name="sec-avoidfqn"></a><div class="titlepage"><div><h3 class="title"> -<a name="sec-avoidfqn"></a><span class="label">1.1.3.</span> <span class="title">Avoid to use fully qualified names - (i.e. std::string)</span> -</h3></div></div> +<div class="titlepage"><div><h3 class="title"> +<a name="sec-avoidfqn"></a>Avoid to use fully qualified names + (i.e. std::string)</h3></div></div> <p> If some compilers complain about <b>using std::string;</b>, and if the "hack" for gtk-- mentioned above does not work, then I see two solutions: - <div class="itemizedlist"><ul> + <div class="itemizedlist"><ul type="disc"> <li><p> -<a name="id2698648"></a> Define <b>std::</b> as a macro if the compiler doesn't know about <b>std::</b>. <pre class="programlisting"> @@ -282,7 +272,6 @@ gnu.gcc.help) </p></li> <li><p> -<a name="id2698680"></a> Define a macro NS_STD, which is defined to either "" or "std" based on an autoconf-test. Then you should be able to use @@ -295,18 +284,15 @@ </p> </div> <div class="section"> -<a name="sec-osprojects"></a><div class="titlepage"><div><h3 class="title"> -<a name="sec-osprojects"></a><span class="label">1.1.4.</span> <span class="title">How some open-source-projects deal - with this</span> -</h3></div></div> +<div class="titlepage"><div><h3 class="title"> +<a name="sec-osprojects"></a>How some open-source-projects deal + with this</h3></div></div> <p> This information was gathered around May 2000. It may not be correct by the time you read this. </p> <div class="table"> -<p> -<a name="id2698746"></a><b>Table 1. Namespace std:: in Open-Source programs</b> -</p> +<p><b>Table 1. Namespace std:: in Open-Source programs</b></p> <table summary="Namespace std:: in Open-Source programs" border="1"> <colgroup> <col> @@ -338,9 +324,7 @@ </table> </div> <div class="table"> -<p> -<a name="id2698876"></a><b>Table 2. Notations for categories</b> -</p> +<p><b>Table 2. Notations for categories</b></p> <table summary="Notations for categories" border="1"> <colgroup> <col> @@ -368,15 +352,16 @@ <p> As you can see, this currently lacks an example of a project which uses libstdc++-symbols in headers in a back-portable way - (except for Gtk--: see the <a href="#sec-gtkmm-hack">section on the gtkmm-hack</a>). + (except for Gtk--: see the <a href="#sec-gtkmm-hack" title="Using namespace + composition if the project uses a separate + namespace">section on the gtkmm-hack</a>). </p> </div> </div> <div class="section"> -<a name="sec-nocreate"></a><div class="titlepage"><div><h2 class="title" style="clear: all"> -<a name="sec-nocreate"></a><span class="label">2.</span> <span class="title">there is no ios::nocreate/ios::noreplace - in ISO 14882</span> -</h2></div></div> +<div class="titlepage"><div><h2 class="title" style="clear: both"> +<a name="sec-nocreate"></a>there is no ios::nocreate/ios::noreplace + in ISO 14882</h2></div></div> <p> I have seen <b>ios::nocreate</b> being used for input-streams, most probably because the author thought it would be @@ -394,10 +379,9 @@ </p> </div> <div class="section"> -<a name="sec-stream::attach"></a><div class="titlepage"><div><h2 class="title" style="clear: all"> -<a name="sec-stream::attach"></a><span class="label">3.</span> <span class="title"><b>stream::attach(int - fd)</b> is not in the standard any more</span> -</h2></div></div> +<div class="titlepage"><div><h2 class="title" style="clear: both"> +<a name="sec-stream::attach"></a><b>stream::attach(int + fd)</b> is not in the standard any more</h2></div></div> <p> Phil Edwards <tt><<a href="mailto:pedwards@disaster.jaj.com">pedwards@disaster.jaj.com</a>></tt> writes: It was considered and rejected. Not all environments use file @@ -406,16 +390,14 @@ </p> <p> When using libstdc++-v3, you can use - <div class="funcsynopsis" id="id2692860"> -<p> -<a name="id2692860"></a><pre class="funcsynopsisinfo"> + <div class="funcsynopsis"> +<pre class="funcsynopsisinfo"> #include <fstream> </pre> <p><code><code class="funcdef"> <b class="fsfunc">basic_filebuf<...>::basic_filebuf<...> </b> </code>(<var class="pdparam">file</var>, <var class="pdparam">mode</var>, <var class="pdparam">size</var>);<br>__c_file_type* <var class="pdparam">file</var>;<br>ios_base::open_mode <var class="pdparam">mode</var>;<br>int <var class="pdparam">size</var>;</code></p> -<p> </div> but the the signature of this constructor has changed often, and it might change again. For the current state of this, check @@ -427,13 +409,14 @@ <b>std::streambuf</b> (or <b>std::basic_streambuf<..></b>) which opens a file given a descriptor, and then pass an instance of this to the - stream-constructor (from the Josuttis-book). + stream-constructor. For an example of this, refer to + <a href="http://www.josuttis.com/cppcode/fdstream.html" target="_top">fdstream example</a> + by Nicolai Josuttis. </p> </div> <div class="section"> -<a name="sec-headers"></a><div class="titlepage"><div><h2 class="title" style="clear: all"> -<a name="sec-headers"></a><span class="label">4.</span> <span class="title">The new headers</span> -</h2></div></div> +<div class="titlepage"><div><h2 class="title" style="clear: both"> +<a name="sec-headers"></a>The new headers</h2></div></div> <p> All new headers can be seen in this <a href="headers_cc.txt" target="_top"> source-code</a>. @@ -443,9 +426,8 @@ a warning that you are using deprecated headers. </p> <div class="section"> -<a name="sec-cheaders"></a><div class="titlepage"><div><h3 class="title"> -<a name="sec-cheaders"></a><span class="label">4.4.1.</span> <span class="title">New headers replacing C-headers</span> -</h3></div></div> +<div class="titlepage"><div><h3 class="title"> +<a name="sec-cheaders"></a>New headers replacing C-headers</h3></div></div> <p> You should not use the C-headers (except for system-level headers) from C++ programs. Instead, you should use a set of @@ -474,12 +456,11 @@ </p> </div> <div class="section"> -<a name="sec-fstream-header"></a><div class="titlepage"><div><h3 class="title"> -<a name="sec-fstream-header"></a><span class="label">4.4.2.</span> <span class="title"> +<div class="titlepage"><div><h3 class="title"> +<a name="sec-fstream-header"></a> <tt><fstream></tt> does not define <b>std::cout</b>, - <b>std::cin</b> etc.</span> -</h3></div></div> + <b>std::cin</b> etc.</h3></div></div> <p> In earlier versions of the standard, <tt><fstream.h></tt>, @@ -494,42 +475,38 @@ </div> </div> <div class="section"> -<a name="sec-iterators"></a><div class="titlepage"><div><h2 class="title" style="clear: all"> -<a name="sec-iterators"></a><span class="label">5.</span> <span class="title">Iterators</span> -</h2></div></div> +<div class="titlepage"><div><h2 class="title" style="clear: both"> +<a name="sec-iterators"></a>Iterators</h2></div></div> <p> The following are not proper uses of iterators, but may be working fixes for existing uses of iterators. - <div class="itemizedlist"><ul> -<li><p> -<a name="id2693156"></a>you cannot do + <div class="itemizedlist"><ul type="disc"> +<li><p>you cannot do <b>ostream::operator<<(iterator)</b> to print the address of the iterator => use <b>operator<< &*iterator</b> instead ? </p></li> -<li><p> -<a name="id2693255"></a>you cannot clear an iterator's reference +<li><p>you cannot clear an iterator's reference (<b>iterator = 0</b>) => use <b>iterator = iterator_type();</b> ? </p></li> <li><p> -<a name="id2693277"></a><b>if (iterator)</b> won't work any +<b>if (iterator)</b> won't work any more => use <b>if (iterator != iterator_type())</b> ?</p></li> </ul></div> </p> </div> <div class="section"> -<a name="sec-macros"></a><div class="titlepage"><div><h2 class="title" style="clear: all"> -<a name="sec-macros"></a><span class="label">6.</span> <span class="title"> +<div class="titlepage"><div><h2 class="title" style="clear: both"> +<a name="sec-macros"></a> Libc-macros (i.e. <b>isspace</b> from - <tt><cctype></tt>)</span> -</h2></div></div> + <tt><cctype></tt>)</h2></div></div> <p> Glibc 2.0.x and 2.1.x define the <tt><ctype.h></tt> -functionality as macros (isspace, isalpha etc.). Libstdc++-v3 - "shadows" these macros as described in the <a href="#sec-cheaders">section about + "shadows" these macros as described in the <a href="#sec-cheaders" title="New headers replacing C-headers">section about c-headers</a>. </p> <p> @@ -577,18 +554,17 @@ The solution to this problem was posted to the libstdc++-v3 mailing-list: Benjamin Kosnik <tt><<a href="mailto:bkoz@redhat.com">bkoz@redhat.com</a>></tt> writes: - ` + ‘ --enable-cshadow-headers is currently broken. As a result, shadow headers are not being searched.... - ' + ’ This is now outdated, but gcc 3.0 still does not have fully compliant "shadow headers". </p> </div> <div class="section"> -<a name="sec-stream-state"></a><div class="titlepage"><div><h2 class="title" style="clear: all"> -<a name="sec-stream-state"></a><span class="label">7.</span> <span class="title">State of streams</span> -</h2></div></div> +<div class="titlepage"><div><h2 class="title" style="clear: both"> +<a name="sec-stream-state"></a>State of streams</h2></div></div> <p> At least some older implementations don't have <b>std::ios_base</b>, so you should use @@ -598,9 +574,8 @@ </p> </div> <div class="section"> -<a name="sec-vector-at"></a><div class="titlepage"><div><h2 class="title" style="clear: all"> -<a name="sec-vector-at"></a><span class="label">8.</span> <span class="title">vector::at is missing (i.e. gcc 2.95.x)</span> -</h2></div></div> +<div class="titlepage"><div><h2 class="title" style="clear: both"> +<a name="sec-vector-at"></a>vector::at is missing (i.e. gcc 2.95.x)</h2></div></div> <p> One solution is to add an autoconf-test for this: <pre class="programlisting"> @@ -630,9 +605,8 @@ </p> </div> <div class="section"> -<a name="sec-eof"></a><div class="titlepage"><div><h2 class="title" style="clear: all"> -<a name="sec-eof"></a><span class="label">9.</span> <span class="title">Using std::char_traits<char>::eof()</span> -</h2></div></div> +<div class="titlepage"><div><h2 class="title" style="clear: both"> +<a name="sec-eof"></a>Using std::char_traits<char>::eof()</h2></div></div> <p> <pre class="programlisting"> #ifdef HAVE_CHAR_TRAITS @@ -644,9 +618,8 @@ </p> </div> <div class="section"> -<a name="sec-string-clear"></a><div class="titlepage"><div><h2 class="title" style="clear: all"> -<a name="sec-string-clear"></a><span class="label">10.</span> <span class="title">Using string::clear()/string::erase()</span> -</h2></div></div> +<div class="titlepage"><div><h2 class="title" style="clear: both"> +<a name="sec-string-clear"></a>Using string::clear()/string::erase()</h2></div></div> <p> There are two functions for deleting the contents of a string: <b>clear</b> and <b>erase</b> (the latter @@ -671,19 +644,17 @@ </p> </div> <div class="section"> -<a name="sec-scan-form"></a><div class="titlepage"><div><h2 class="title" style="clear: all"> -<a name="sec-scan-form"></a><span class="label">11.</span> <span class="title">GNU Extensions ostream::form and istream::scan</span> -</h2></div></div> +<div class="titlepage"><div><h2 class="title" style="clear: both"> +<a name="sec-scan-form"></a>GNU Extensions ostream::form and istream::scan</h2></div></div> <p> These are not supported any more - use - <a href="#sec-stringstream"> + <a href="#sec-stringstream" title="Using stringstreams"> stringstreams</a> instead. </p> </div> <div class="section"> -<a name="sec-stringstream"></a><div class="titlepage"><div><h2 class="title" style="clear: all"> -<a name="sec-stringstream"></a><span class="label">12.</span> <span class="title">Using stringstreams</span> -</h2></div></div> +<div class="titlepage"><div><h2 class="title" style="clear: both"> +<a name="sec-stringstream"></a>Using stringstreams</h2></div></div> <p> Libstdc++-v3 provides the new <b>i/ostringstream</b>-classes, (<tt><sstream></tt>), but for compatibility @@ -696,22 +667,18 @@ #include <strstream> #endif </pre> - <div class="itemizedlist"><ul> -<li><p> -<a name="id2693683"></a> <b>strstream</b> is considered to be + <div class="itemizedlist"><ul type="disc"> +<li><p> <b>strstream</b> is considered to be deprecated </p></li> -<li><p> -<a name="id2693629"></a> <b>strstream</b> is limited to +<li><p> <b>strstream</b> is limited to <b>char</b> </p></li> -<li><p> -<a name="id2693718"></a> with <b>ostringstream</b> you don't +<li><p> with <b>ostringstream</b> you don't have to take care of terminating the string or freeing its memory </p></li> -<li><p> -<a name="id2693735"></a> <b>istringstream</b> can be re-filled +<li><p> <b>istringstream</b> can be re-filled (clear(); str(input);) </p></li> </ul></div> @@ -789,9 +756,8 @@ </p> </div> <div class="section"> -<a name="sec-about"></a><div class="titlepage"><div><h2 class="title" style="clear: all"> -<a name="sec-about"></a><span class="label">13.</span> <span class="title">About...</span> -</h2></div></div> +<div class="titlepage"><div><h2 class="title" style="clear: both"> +<a name="sec-about"></a>About...</h2></div></div> <p> Please send any experience, additions, corrections or questions to <a href="mailto:fnatter@gmx.net" target="_top">fnatter@gmx.net</a> or for diff --git a/libstdc++-v3/docs/html/17_intro/porting-howto.xml b/libstdc++-v3/docs/html/17_intro/porting-howto.xml index 946dd18ae6a..e146b871d77 100644 --- a/libstdc++-v3/docs/html/17_intro/porting-howto.xml +++ b/libstdc++-v3/docs/html/17_intro/porting-howto.xml @@ -1,7 +1,7 @@ <?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN" - "dtd/docbook-4/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"> <?xml-stylesheet type="text/xsl" href="docbook-xslt/docbook/html/docbook.xsl"?> diff --git a/libstdc++-v3/docs/html/17_intro/porting.html b/libstdc++-v3/docs/html/17_intro/porting.html index 344fb4f31b3..e791f92dc74 100644 --- a/libstdc++-v3/docs/html/17_intro/porting.html +++ b/libstdc++-v3/docs/html/17_intro/porting.html @@ -3,24 +3,27 @@ <title>Porting libstdc++-v3</title> <meta http-equiv="Content-Type" content="text/html"> <meta name=description content="Porting libstdc++-v3"> -<meta name=generator content="makeinfo 4.0b"> -<link href="http://texinfo.org/" rel=generator-home> +<meta name=generator content="makeinfo 4.2"> +<link href="http://www.gnu.org/software/texinfo/" rel=generator-home> </head> - <body> +<h1>Porting libstdc++-v3</h1> <p><hr> Node:<a name="Top">Top</a>, -Next:<a rel=next href="#Operating%20system">Operating system</a> +Next:<a rel=next accesskey=n href="#Operating%20system">Operating system</a>, +Up:<a rel=up accesskey=u href="#dir">(dir)</a> <br> -<h1>Porting libstdc++-v3</h1> +<h2>Porting libstdc++-v3</h2> <p>This document explains how to port libstdc++-v3 (the GNU C++ library) to a new target. <p>In order to make the GNU C++ library (libstdc++-v3) work with a new target, you must edit some configuration files and provide some new -header files. +header files. Unless this is done, libstdc++-v3 will use generic +settings which may not be correct for your target; even if they are +correct, they will likely be inefficient. <p>Before you get started, make sure that you have a working C library on your target. The C library need not precisely comply with any @@ -34,24 +37,25 @@ library, but you should at least try some minimal test cases. <p>Here are the primary steps required to port the library: <ul> -<li><a href="#Operating%20system">Operating system</a>: Configuring for your operating system. -<li><a href="#Character%20types">Character types</a>: Implementing character classification. -<li><a href="#Thread%20safety">Thread safety</a>: Implementing atomic operations. -<li><a href="#Numeric%20limits">Numeric limits</a>: Implementing numeric limits. -<li><a href="#Libtool">Libtool</a>: Using libtool. -<li><a href="#GNU%20Free%20Documentation%20License">GNU Free Documentation License</a>: How you can copy and share this manual. +<li><a accesskey=1 href="#Operating%20system">Operating system</a>: Configuring for your operating system. +<li><a accesskey=2 href="#CPU">CPU</a>: Configuring for your processor chip. +<li><a accesskey=3 href="#Character%20types">Character types</a>: Implementing character classification. +<li><a accesskey=4 href="#Thread%20safety">Thread safety</a>: Implementing atomic operations. +<li><a accesskey=5 href="#Numeric%20limits">Numeric limits</a>: Implementing numeric limits. +<li><a accesskey=6 href="#Libtool">Libtool</a>: Using libtool. +<li><a accesskey=7 href="#GNU%20Free%20Documentation%20License">GNU Free Documentation License</a>: How you can copy and share this manual. </ul> <p><hr> Node:<a name="Operating%20system">Operating system</a>, -Next:<a rel=next href="#Character%20types">Character types</a>, -Previous:<a rel=previous href="#Top">Top</a>, -Up:<a rel=up href="#Top">Top</a> +Next:<a rel=next accesskey=n href="#CPU">CPU</a>, +Previous:<a rel=previous accesskey=p href="#Top">Top</a>, +Up:<a rel=up accesskey=u href="#Top">Top</a> <br> -<h1>Operating system</h1> +<h2>Operating system</h2> -<p>If you are porting to a new operating-system (as opposed to a new chip +<p>If you are porting to a new operating system (as opposed to a new chip using an existing operating system), you will need to create a new directory in the <code>config/os</code> hierarchy. For example, the IRIX configuration files are all in <code>config/os/irix</code>. There is no set @@ -72,13 +76,13 @@ standard target triplet; e.g., the <code>solaris2.8</code> in <code>sparc-sun-solaris2.8</code>. <p>The first file to create in this directory, should be called -<code>bits/os_defines.h</code>. This file contains basic macro definitions +<code>os_defines.h</code>. This file contains basic macro definitions that are required to allow the C++ library to work with your C library. This file should provide macro definitions for <code>__off_t</code>, <code>__off64_t</code>, and <code>__ssize_t</code>. Typically, this just looks like: -<pre>#define __off_t off_t +<br><pre>#define __off_t off_t #define __off64_t off64_t #define __ssize_t ssize_t </pre> @@ -105,63 +109,87 @@ need to define. You will need to add them to the target. It will not work to simply define these macros in <code>os_defines.h</code>. -<p>At this time, there are two libstdc++-v3-specific macros which may be +<p>At this time, there is one libstdc++-v3-specific macro which may be defined. <code>_G_USING_THUNKS</code> may be defined to 0 to express that the port doesn't use thunks (although it is unclear that this is still useful since libio support isn't currently working and the g++ v3 ABI -invalidates the assumption that some ports don't use thunks). -<code>_GLIBCPP_AVOID_FSEEK</code> may be defined if seeking on an interactive -stream (or one hooked to a pipe) is not allowed by the OS. In this -case, getc()/ungetc() will be used at some key locations in the library -implementation instead of fseek(). Currently, the code path to avoid -fseek() is only enabled when the seek size is 1 character away from the -current stream position. This is known to improve *-unknown-freebsd*, -sparc-sun-solaris2.* and *-*-mingw32*. +invalidates the assumption that some ports don't use thunks). <p>Finally, you should bracket the entire file in an include-guard, like this: -<pre>#ifndef _GLIBCPP_OS_DEFINES +<br><pre>#ifndef _GLIBCPP_OS_DEFINES #define _GLIBCPP_OS_DEFINES ... #endif </pre> -<p>We recommend copying an existing <code>bits/os_defines.h</code> to use as a +<p>We recommend copying an existing <code>os_defines.h</code> to use as a starting point. <p><hr> +Node:<a name="CPU">CPU</a>, +Next:<a rel=next accesskey=n href="#Character%20types">Character types</a>, +Previous:<a rel=previous accesskey=p href="#Operating%20system">Operating system</a>, +Up:<a rel=up accesskey=u href="#Top">Top</a> +<br> + +<h2>CPU</h2> + +<p>If you are porting to a new chip (as opposed to a new operating system +running on an existing chip), you will need to create a new directory in the +<code>config/cpu</code> hierarchy. Much like the <a href="#Operating%20system">Operating system</a> setup, +there are no strict rules on how to organize the CPU configuration +directory, but careful naming choices will allow the configury to find your +setup files without explicit help. + +<p>We recommend that for a target triplet <code><CPU>-<vendor>-<OS></code>, you +name your configuration directory <code>config/cpu/<CPU></code>. If you do this, +the configury will find the directory itself. Otherwise you will need to +edit the <code>configure.target</code> file and, in the switch statement that sets +<code>cpu_include_dir</code>, add a pattern to handle your chip. + +<p>Note that some chip families share a single configuration directory, for +example, <code>alpha</code>, <code>alphaev5</code>, and <code>alphaev6</code> all use the +<code>config/cpu/alpha</code> directory, and there is an entry in the +<code>configure.target</code> switch statement to handle this. + +<p>The <code>cpu_include_dir</code> sets default locations for the files controlling +<a href="#Thread%20safety">Thread safety</a> and <a href="#Numeric%20limits">Numeric limits</a>, if the defaults are not +appropriate for your chip. + +<p><hr> Node:<a name="Character%20types">Character types</a>, -Next:<a rel=next href="#Thread%20safety">Thread safety</a>, -Previous:<a rel=previous href="#Operating%20system">Operating system</a>, -Up:<a rel=up href="#Top">Top</a> +Next:<a rel=next accesskey=n href="#Thread%20safety">Thread safety</a>, +Previous:<a rel=previous accesskey=p href="#CPU">CPU</a>, +Up:<a rel=up accesskey=u href="#Top">Top</a> <br> -<h1>Character types</h1> +<h2>Character types</h2> <p>The library requires that you provide three header files to implement character classification, analogous to that provided by the C libraries <code><ctype.h></code> header. You can model these on the files provided in -<code>config/os/generic/bits</code>. However, these files will almost +<code>config/os/generic</code>. However, these files will almost certainly need some modification. -<p>The first file to write is <code>bits/ctype_base.h</code>. This file provides +<p>The first file to write is <code>ctype_base.h</code>. This file provides some very basic information about character classification. The libstdc++-v3 library assumes that your C library implements <code><ctype.h></code> by using a table (indexed by character code) containing integers, where each of these integers is a bit-mask indicating whether the character is -upper-case, lower-case, alphabetic, etc. The <code>bits/ctype_base.h</code> +upper-case, lower-case, alphabetic, etc. The <code>ctype_base.h</code> file gives the type of the integer, and the values of the various bit masks. You will have to peer at your own <code><ctype.h></code> to figure out how to define the values required by this file. -<p>The <code>bits/ctype_base.h</code> header file does not need include guards. +<p>The <code>ctype_base.h</code> header file does not need include guards. It should contain a single <code>struct</code> definition called <code>ctype_base</code>. This <code>struct</code> should contain two type declarations, and one enumeration declaration, like this example, taken from the IRIX configuration: -<pre>struct ctype_base +<br><pre>struct ctype_base { typedef unsigned int mask; typedef int* __to_type; @@ -195,15 +223,15 @@ but you must still define the type. example, using the values from your native <code><ctype.h></code>. They can be given symbolically (as above), or numerically, if you prefer. You do not have to include <code><ctype.h></code> in this header; it will always be -included before <code>bits/ctype_base.h</code> is included. +included before <code>ctype_base.h</code> is included. -<p>The next file to write is <code>bits/ctype_noninline.h</code>, which also does +<p>The next file to write is <code>ctype_noninline.h</code>, which also does not require include guards. This file defines a few member functions that will be included in <code>include/bits/locale_facets.h</code>. The first function that must be written is the <code>ctype<char>::ctype</code> constructor. Here is the IRIX example: -<pre>ctype<char>::ctype(const mask* __table = 0, bool __del = false, +<br><pre>ctype<char>::ctype(const mask* __table = 0, bool __del = false, size_t __refs = 0) : _Ctype_nois<char>(__refs), _M_del(__table != 0 && __del), _M_toupper(NULL), @@ -227,7 +255,7 @@ vice versa, you should initialize <code>_M_toupper</code> and <p>Now, you have to write two functions to convert from upper-case to lower-case, and vice versa. Here are the IRIX versions: -<pre>char +<br><pre>char ctype<char>::do_toupper(char __c) const { return _toupper(__c); } @@ -245,7 +273,7 @@ of characters. The versions provided here will always work - but you could use specialized routines for greater performance if you have machinery to do that on your system: -<pre>const char* +<br><pre>const char* ctype<char>::do_toupper(char* __low, const char* __high) const { while (__low < __high) @@ -268,7 +296,7 @@ ctype<char>::do_tolower(char* __low, const char* __high) const } </pre> -<p>You must also provide the <code>bits/ctype_inline.h</code> file, which +<p>You must also provide the <code>ctype_inline.h</code> file, which contains a few more functions. On most systems, you can just copy <code>config/os/generic/ctype_inline.h</code> and use it on your system. @@ -278,7 +306,7 @@ properties; they are analogous to the functions like <code>isalpha</code> and <p>The first function is implemented like this on IRIX: -<pre>bool +<br><pre>bool ctype<char>:: is(mask __m, char __c) const throw() { return (_M_table)[(unsigned char)(__c)] & __m; } @@ -290,7 +318,7 @@ implementation here should work on all systems. <p>The next function is: -<pre>const char* +<br><pre>const char* ctype<char>:: is(const char* __low, const char* __high, mask* __vec) const throw() { @@ -306,7 +334,7 @@ from <code>__low</code> up until <code>__high</code> into the vector given by <p>The last two functions again are entirely generic: -<pre>const char* +<br><pre>const char* ctype<char>:: scan_is(mask __m, const char* __low, const char* __high) const throw() { @@ -327,12 +355,12 @@ scan_not(mask __m, const char* __low, const char* __high) const throw() <p><hr> Node:<a name="Thread%20safety">Thread safety</a>, -Next:<a rel=next href="#Numeric%20limits">Numeric limits</a>, -Previous:<a rel=previous href="#Character%20types">Character types</a>, -Up:<a rel=up href="#Top">Top</a> +Next:<a rel=next accesskey=n href="#Numeric%20limits">Numeric limits</a>, +Previous:<a rel=previous accesskey=p href="#Character%20types">Character types</a>, +Up:<a rel=up accesskey=u href="#Top">Top</a> <br> -<h1>Thread safety</h1> +<h2>Thread safety</h2> <p>The C++ library string functionality requires a couple of atomic operations to provide thread-safety. If you don't take any special @@ -344,23 +372,35 @@ multi-threaded. are two distinct approaches. One is to provide a version for your CPU, using assembly language constructs. The other is to use the thread-safety primitives in your operating system. In either case, you -make a file called <code>bits/atomicity.h</code>. +make a file called <code>atomicity.h</code>, and the variable +<code>ATOMICITYH</code> must point to this file. <p>If you are using the assembly-language approach, put this code in -<code>config/cpu/<chip>/bits/atomicity.h</code>, where chip is the name of -your processor. In that case, edit the switch statement in -<code>configure.target</code> to set the <code>cpu_include_dir</code>. In either -case, set the switch statement that sets <code>ATOMICITYH</code> to be the -directory containing <code>bits/atomicity.h</code>. +<code>config/cpu/<chip>/atomicity.h</code>, where chip is the name of +your processor (see <a href="#CPU">CPU</a>). No additional changes are necessary to +locate the file in this case; <code>ATOMICITYH</code> will be set by default. + +<p>If you are using the operating system thread-safety primitives approach, +you can also put this code in the same CPU directory, in which case no more +work is needed to locate the file. For examples of this approach, +see the <code>atomicity.h</code> file for IRIX or IA64. + +<p>Alternatively, if the primitives are more closely related to the OS +than they are to the CPU, you can put the <code>atomicity.h</code> file in +the <a href="#Operating%20system">Operating system</a> directory instead. In this case, you must +edit <code>configure.target</code>, and in the switch statement that handles +operating systems, override the <code>ATOMICITYH</code> variable to point to +the appropriate <code>os_include_dir</code>. For examples of this approach, +see the <code>atomicity.h</code> file for AIX. <p>With those bits out of the way, you have to actually write -<code>bits/atomicity.h</code> itself. This file should be wrapped in an +<code>atomicity.h</code> itself. This file should be wrapped in an include guard named <code>_BITS_ATOMICITY_H</code>. It should define one type, and two functions. <p>The type is <code>_Atomic_word</code>. Here is the version used on IRIX: -<pre>typedef long _Atomic_word; +<br><pre>typedef long _Atomic_word; </pre> <p>This type must be a signed integral type supporting atomic operations. @@ -371,7 +411,7 @@ primitives. <p>Then, you must provide two functions. The bodies of these functions must be equivalent to those provided here, but using atomic operations: -<pre>static inline _Atomic_word +<br><pre>static inline _Atomic_word __attribute__ ((__unused__)) __exchange_and_add (_Atomic_word* __mem, int __val) { @@ -390,12 +430,12 @@ __atomic_add (_Atomic_word* __mem, int __val) <p><hr> Node:<a name="Numeric%20limits">Numeric limits</a>, -Next:<a rel=next href="#Libtool">Libtool</a>, -Previous:<a rel=previous href="#Thread%20safety">Thread safety</a>, -Up:<a rel=up href="#Top">Top</a> +Next:<a rel=next accesskey=n href="#Libtool">Libtool</a>, +Previous:<a rel=previous accesskey=p href="#Thread%20safety">Thread safety</a>, +Up:<a rel=up accesskey=u href="#Top">Top</a> <br> -<h1>Numeric limits</h1> +<h2>Numeric limits</h2> <p>The C++ library requires information about the fundamental data types, such as the minimum and maximum representable values of each type. @@ -404,25 +444,21 @@ 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 <code>include/bits/std_limits.h</code>. -<p>If you need to define any macros, you can do so in -<code>os_defines.h</code>. 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. To take that approach, create a new file -called <code>limits.h</code> in your CPU configuration directory (e.g., -<code>config/cpu/i386/bits</code>) and then modify <code>configure.target</code> -so that <code>LIMITSH</code> is set to the CPU directory (e.g., -<code>config/cpu/i386</code>). Note that <code>LIMITSH</code> should not include -the <code>bits</code> part of the directory name. +<p>If you need to define any macros, you can do so in <code>os_defines.h</code>. +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. +To take that approach, create a new file called <code>cpu_limits.h</code> in +your CPU configuration directory (see <a href="#CPU">CPU</a>). <p><hr> Node:<a name="Libtool">Libtool</a>, -Next:<a rel=next href="#GNU%20Free%20Documentation%20License">GNU Free Documentation License</a>, -Previous:<a rel=previous href="#Numeric%20limits">Numeric limits</a>, -Up:<a rel=up href="#Top">Top</a> +Next:<a rel=next accesskey=n href="#GNU%20Free%20Documentation%20License">GNU Free Documentation License</a>, +Previous:<a rel=previous accesskey=p href="#Numeric%20limits">Numeric limits</a>, +Up:<a rel=up accesskey=u href="#Top">Top</a> <br> -<h1>Libtool</h1> +<h2>Libtool</h2> <p>The C++ library is compiled, archived and linked with libtool. Explaining the full workings of libtool is beyond the scope of this @@ -441,10 +477,10 @@ run as the library is loaded. Often, that requires linking in special object files when the C++ library is built as a shared library, or taking other system-specific actions. -<p>The libstdc++-v3 library is linked with the C version of libtool, even though it -is a C++ library. Therefore, the C version of libtool needs to ensure -that the run-time library initializers are run. The usual way to do -this is to build the library using <code>gcc -shared</code>. +<p>The libstdc++-v3 library is linked with the C version of libtool, even +though it is a C++ library. Therefore, the C version of libtool needs to +ensure that the run-time library initializers are run. The usual way to +do this is to build the library using <code>gcc -shared</code>. <p>If you need to change how the library is linked, look at <code>ltcf-c.sh</code> in the top-level directory. Find the switch statement @@ -453,14 +489,14 @@ operating system. <p><hr> Node:<a name="GNU%20Free%20Documentation%20License">GNU Free Documentation License</a>, -Previous:<a rel=previous href="#Libtool">Libtool</a>, -Up:<a rel=up href="#Top">Top</a> +Previous:<a rel=previous accesskey=p href="#Libtool">Libtool</a>, +Up:<a rel=up accesskey=u href="#Top">Top</a> <br> -<h1>GNU Free Documentation License</h1> +<h2>GNU Free Documentation License</h2> <div align="center">Version 1.1, March 2000</div> -<pre>Copyright © 2000 Free Software Foundation, Inc. +<br><pre>Copyright © 2000 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies @@ -796,13 +832,13 @@ number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. </ol> -<h2>ADDENDUM: How to use this License for your documents</h2> +<h3>ADDENDUM: How to use this License for your documents</h3> <p>To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: -<pre> Copyright (C) <var>year</var> <var>your name</var>. +<br><pre> Copyright (C) <var>year</var> <var>your name</var>. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; @@ -823,15 +859,24 @@ free software license, such as the GNU General Public License, to permit their use in free software. -<h1>Table of Contents</h1> +<h2>Table of Contents</h2> <ul> -<li><a href="#Top">Porting libstdc++-v3</a> -<li><a href="#Operating%20system">Operating system</a> -<li><a href="#Character%20types">Character types</a> -<li><a href="#Thread%20safety">Thread safety</a> -<li><a href="#Numeric%20limits">Numeric limits</a> -<li><a href="#Libtool">Libtool</a> -<li><a href="#GNU%20Free%20Documentation%20License">GNU Free Documentation License</a> +<li><a name="toc_Top"></a> + <a href="#Top">Porting libstdc++-v3</a> +<li><a name="toc_Operating%20system"></a> + <a href="#Operating%20system">Operating system</a> +<li><a name="toc_CPU"></a> + <a href="#CPU">CPU</a> +<li><a name="toc_Character%20types"></a> + <a href="#Character%20types">Character types</a> +<li><a name="toc_Thread%20safety"></a> + <a href="#Thread%20safety">Thread safety</a> +<li><a name="toc_Numeric%20limits"></a> + <a href="#Numeric%20limits">Numeric limits</a> +<li><a name="toc_Libtool"></a> + <a href="#Libtool">Libtool</a> +<li><a name="toc_GNU%20Free%20Documentation%20License"></a> + <a href="#GNU%20Free%20Documentation%20License">GNU Free Documentation License</a> <ul> <li><a href="#GNU%20Free%20Documentation%20License">ADDENDUM: How to use this License for your documents</a> </ul> diff --git a/libstdc++-v3/docs/html/17_intro/porting.texi b/libstdc++-v3/docs/html/17_intro/porting.texi index d5d32b4a2f4..142a354a032 100644 --- a/libstdc++-v3/docs/html/17_intro/porting.texi +++ b/libstdc++-v3/docs/html/17_intro/porting.texi @@ -12,7 +12,7 @@ This file explains how to port libstdc++-v3 (the GNU C++ library) to a new target. -Copyright (c) 2000, 2001 Free Software Foundation, Inc. +Copyright (c) 2000, 2001, 2002 Free Software Foundation, Inc. @end ifinfo @c --------------------------------------------------------------------- @@ -24,7 +24,7 @@ Copyright (c) 2000, 2001 Free Software Foundation, Inc. @author Mark Mitchell @page @vskip 0pt plus 1filll -Copyright @copyright{} 2000, 2001 Free Software Foundation, Inc. +Copyright @copyright{} 2000, 2001, 2002 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or @@ -57,7 +57,9 @@ a new target. In order to make the GNU C++ library (libstdc++-v3) work with a new target, you must edit some configuration files and provide some new -header files. +header files. Unless this is done, libstdc++-v3 will use generic +settings which may not be correct for your target; even if they are +correct, they will likely be inefficient. Before you get started, make sure that you have a working C library on your target. The C library need not precisely comply with any @@ -72,6 +74,7 @@ Here are the primary steps required to port the library: @menu * Operating system:: Configuring for your operating system. +* CPU:: Configuring for your processor chip. * Character types:: Implementing character classification. * Thread safety:: Implementing atomic operations. * Numeric limits:: Implementing numeric limits. @@ -86,7 +89,7 @@ Here are the primary steps required to port the library: @node Operating system @chapter Operating system -If you are porting to a new operating-system (as opposed to a new chip +If you are porting to a new operating system (as opposed to a new chip using an existing operating system), you will need to create a new directory in the @file{config/os} hierarchy. For example, the IRIX configuration files are all in @file{config/os/irix}. There is no set @@ -107,7 +110,7 @@ standard target triplet; e.g., the @code{solaris2.8} in @code{sparc-sun-solaris2.8}. The first file to create in this directory, should be called -@file{bits/os_defines.h}. This file contains basic macro definitions +@file{os_defines.h}. This file contains basic macro definitions that are required to allow the C++ library to work with your C library. This file should provide macro definitions for @code{__off_t}, @code{__off64_t}, and @code{__ssize_t}. Typically, this just looks @@ -142,18 +145,11 @@ need to define. You will need to add them to the target. It will not work to simply define these macros in @file{os_defines.h}. -At this time, there are two libstdc++-v3-specific macros which may be +At this time, there is one libstdc++-v3-specific macro which may be defined. @code{_G_USING_THUNKS} may be defined to 0 to express that the port doesn't use thunks (although it is unclear that this is still useful since libio support isn't currently working and the g++ v3 ABI invalidates the assumption that some ports don't use thunks). -@code{_GLIBCPP_AVOID_FSEEK} may be defined if seeking on an interactive -stream (or one hooked to a pipe) is not allowed by the OS. In this -case, getc()/ungetc() will be used at some key locations in the library -implementation instead of fseek(). Currently, the code path to avoid -fseek() is only enabled when the seek size is 1 character away from the -current stream position. This is known to improve *-unknown-freebsd*, -sparc-sun-solaris2.* and *-*-mingw32*. Finally, you should bracket the entire file in an include-guard, like this: @@ -165,10 +161,40 @@ this: #endif @end example -We recommend copying an existing @file{bits/os_defines.h} to use as a +We recommend copying an existing @file{os_defines.h} to use as a starting point. @c --------------------------------------------------------------------- +@c CPU +@c --------------------------------------------------------------------- + +@node CPU +@chapter CPU + +If you are porting to a new chip (as opposed to a new operating system +running on an existing chip), you will need to create a new directory in the +@file{config/cpu} hierarchy. Much like the @ref{Operating system} setup, +there are no strict rules on how to organize the CPU configuration +directory, but careful naming choices will allow the configury to find your +setup files without explicit help. + +We recommend that for a target triplet @code{<CPU>-<vendor>-<OS>}, you +name your configuration directory @file{config/cpu/<CPU>}. If you do this, +the configury will find the directory itself. Otherwise you will need to +edit the @file{configure.target} file and, in the switch statement that sets +@code{cpu_include_dir}, add a pattern to handle your chip. + +Note that some chip families share a single configuration directory, for +example, @code{alpha}, @code{alphaev5}, and @code{alphaev6} all use the +@file{config/cpu/alpha} directory, and there is an entry in the +@file{configure.target} switch statement to handle this. + +The @code{cpu_include_dir} sets default locations for the files controlling +@ref{Thread safety} and @ref{Numeric limits}, if the defaults are not +appropriate for your chip. + + +@c --------------------------------------------------------------------- @c Character types @c --------------------------------------------------------------------- @@ -178,20 +204,20 @@ starting point. The library requires that you provide three header files to implement character classification, analogous to that provided by the C libraries @file{<ctype.h>} header. You can model these on the files provided in -@file{config/os/generic/bits}. However, these files will almost +@file{config/os/generic}. However, these files will almost certainly need some modification. -The first file to write is @file{bits/ctype_base.h}. This file provides +The first file to write is @file{ctype_base.h}. This file provides some very basic information about character classification. The libstdc++-v3 library assumes that your C library implements @file{<ctype.h>} by using a table (indexed by character code) containing integers, where each of these integers is a bit-mask indicating whether the character is -upper-case, lower-case, alphabetic, etc. The @file{bits/ctype_base.h} +upper-case, lower-case, alphabetic, etc. The @file{ctype_base.h} file gives the type of the integer, and the values of the various bit masks. You will have to peer at your own @file{<ctype.h>} to figure out how to define the values required by this file. -The @file{bits/ctype_base.h} header file does not need include guards. +The @file{ctype_base.h} header file does not need include guards. It should contain a single @code{struct} definition called @code{ctype_base}. This @code{struct} should contain two type declarations, and one enumeration declaration, like this example, taken @@ -233,9 +259,9 @@ The enumeration should give definitions for all the values in the above example, using the values from your native @file{<ctype.h>}. They can be given symbolically (as above), or numerically, if you prefer. You do not have to include @file{<ctype.h>} in this header; it will always be -included before @file{bits/ctype_base.h} is included. +included before @file{ctype_base.h} is included. -The next file to write is @file{bits/ctype_noninline.h}, which also does +The next file to write is @file{ctype_noninline.h}, which also does not require include guards. This file defines a few member functions that will be included in @file{include/bits/locale_facets.h}. The first function that must be written is the @code{ctype<char>::ctype} @@ -311,7 +337,7 @@ ctype<char>::do_tolower(char* __low, const char* __high) const @} @end example -You must also provide the @file{bits/ctype_inline.h} file, which +You must also provide the @file{ctype_inline.h} file, which contains a few more functions. On most systems, you can just copy @file{config/os/generic/ctype_inline.h} and use it on your system. @@ -390,17 +416,29 @@ If you want to provide custom, safe, versions of these functions, there are two distinct approaches. One is to provide a version for your CPU, using assembly language constructs. The other is to use the thread-safety primitives in your operating system. In either case, you -make a file called @file{bits/atomicity.h}. +make a file called @file{atomicity.h}, and the variable +@code{ATOMICITYH} must point to this file. If you are using the assembly-language approach, put this code in -@file{config/cpu/<chip>/bits/atomicity.h}, where chip is the name of -your processor. In that case, edit the switch statement in -@file{configure.target} to set the @code{cpu_include_dir}. In either -case, set the switch statement that sets @code{ATOMICITYH} to be the -directory containing @file{bits/atomicity.h}. +@file{config/cpu/<chip>/atomicity.h}, where chip is the name of +your processor (@pxref{CPU}). No additional changes are necessary to +locate the file in this case; @code{ATOMICITYH} will be set by default. + +If you are using the operating system thread-safety primitives approach, +you can also put this code in the same CPU directory, in which case no more +work is needed to locate the file. For examples of this approach, +see the @file{atomicity.h} file for IRIX or IA64. + +Alternatively, if the primitives are more closely related to the OS +than they are to the CPU, you can put the @file{atomicity.h} file in +the @ref{Operating system} directory instead. In this case, you must +edit @file{configure.target}, and in the switch statement that handles +operating systems, override the @code{ATOMICITYH} variable to point to +the appropriate @code{os_include_dir}. For examples of this approach, +see the @file{atomicity.h} file for AIX. With those bits out of the way, you have to actually write -@file{bits/atomicity.h} itself. This file should be wrapped in an +@file{atomicity.h} itself. This file should be wrapped in an include guard named @code{_BITS_ATOMICITY_H}. It should define one type, and two functions. @@ -451,16 +489,12 @@ 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 @file{include/bits/std_limits.h}. -If you need to define any macros, you can do so in -@file{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. To take that approach, create a new file -called @file{limits.h} in your CPU configuration directory (e.g., -@file{config/cpu/i386/bits}) and then modify @file{configure.target} -so that @code{LIMITSH} is set to the CPU directory (e.g., -@file{config/cpu/i386}). Note that @code{LIMITSH} should not include -the @samp{bits} part of the directory name. +If you need to define any macros, you can do so in @file{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. +To take that approach, create a new file called @file{cpu_limits.h} in +your CPU configuration directory (@pxref{CPU}). @c --------------------------------------------------------------------- @c Libtool @@ -486,10 +520,10 @@ run as the library is loaded. Often, that requires linking in special object files when the C++ library is built as a shared library, or taking other system-specific actions. -The libstdc++-v3 library is linked with the C version of libtool, even though it -is a C++ library. Therefore, the C version of libtool needs to ensure -that the run-time library initializers are run. The usual way to do -this is to build the library using @code{gcc -shared}. +The libstdc++-v3 library is linked with the C version of libtool, even +though it is a C++ library. Therefore, the C version of libtool needs to +ensure that the run-time library initializers are run. The usual way to +do this is to build the library using @code{gcc -shared}. If you need to change how the library is linked, look at @file{ltcf-c.sh} in the top-level directory. Find the switch statement diff --git a/libstdc++-v3/docs/html/18_support/howto.html b/libstdc++-v3/docs/html/18_support/howto.html index 13adbfd56fc..c055f999bdc 100644 --- a/libstdc++-v3/docs/html/18_support/howto.html +++ b/libstdc++-v3/docs/html/18_support/howto.html @@ -1,13 +1,12 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> <html> <head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> - <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> - <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 18."> - <meta name="GENERATOR" content="vi and eight fingers"> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> + <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> + <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" /> + <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 18." /> + <meta name="GENERATOR" content="vi and eight fingers" /> <title>libstdc++-v3 HOWTO: Chapter 18</title> -<link rel="StyleSheet" href="../lib3styles.css"> +<link rel="StyleSheet" href="../lib3styles.css" /> </head> <body> @@ -24,16 +23,17 @@ <!-- ####################################################### --> -<hr> +<hr /> <h1>Contents</h1> <ul> - <li><a href="#1">Types</a> - <li><a href="#2">Implementation properties</a> - <li><a href="#3">Start and Termination</a> - <li><a href="#4">Dynamic memory management</a> + <li><a href="#1">Types</a></li> + <li><a href="#2">Implementation properties</a></li> + <li><a href="#3">Start and Termination</a></li> + <li><a href="#4">Dynamic memory management</a></li> + <li><a href="#5">RTTI, the ABI, and demangling</a></li> </ul> -<hr> +<hr /> <!-- ####################################################### --> @@ -54,12 +54,13 @@ always a pointer.) </p> <p>In his book - <a href="http://cseng.aw.com/bookdetail.qry?ISBN=0-201-92488-9&ptype=0"><em>Effective C++</em></a>, + <a href="http://cseng.aw.com/bookdetail.qry?ISBN=0-201-92488-9&ptype=0"><em>Effective C++</em></a>, 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: - <pre> + </p> + <pre> const // this is a const object... class { public: @@ -76,7 +77,8 @@ // taken (see Item 27)... } NULL; // and whose name is NULL - </pre>(Cribbed from the published version of + </pre> + <p>(Cribbed from the published version of <a href="http://www.awlonline.com/cseng/meyerscddemo/">the Effective C++ CD</a>, reproduced here with permission.) </p> @@ -92,7 +94,7 @@ print this stuff, it prompted him to run this code through current compilers to see what the state of the art is with respect to member template functions. He posted - <a href="http://www.deja.com/threadmsg_md.xp?AN=644660779.1&CONTEXT=964036823.871301239">an + <a href="http://www.deja.com/threadmsg_md.xp?AN=644660779.1&CONTEXT=964036823.871301239">an article to Usenet</a> after discovering that the code above is not valid! Even though it has no data members, it still needs a user-defined constructor (which means that the class needs a type name @@ -104,14 +106,14 @@ <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="2">Implementation properties</a></h2> - <p> <h3><code><limits></code></h3> - This header mainly defines traits classes to give access to various + <p>This header mainly defines traits classes to give access to various implementation defined-aspects of the fundamental types. The traits classes -- fourteen in total -- are all specilizations of the template class <code>numeric_limits</code> defined as follows: + </p> <pre> template<typename T> struct class { static const bool is_specialized; @@ -149,12 +151,11 @@ static const bool tinyness_before; static const float_round_style round_style; };</pre> - </p> <p>Return <a href="#top">to top of page</a> or <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="3">Start and Termination</a></h2> <p>Not many changes here to <code><cstdlib></code> (the old stdlib.h). You should note that the <code>abort()</code> function does not call @@ -165,11 +166,14 @@ </p> <p>The good old <code>exit()</code> function can be a bit funky, too, until you look closer. Basically, three points to remember are: + </p> <ol> <li>Static objects are destroyed in reverse order of their creation. + </li> <li>Functions registered with <code>atexit()</code> are called in reverse order of registration, once per registration call. (This isn't actually new.) + </li> <li>The previous two actions are "interleaved," that is, given this pseudocode: <pre> @@ -180,12 +184,13 @@ atexit(f1); static Thing obj2; atexit(f2); - </pre>then at a call of <code>exit()</code>, f2 will be called, then + </pre> + then at a call of <code>exit()</code>, 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. + </li> </ol> - </p> <p>Note also that <code>atexit()</code> 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 @@ -195,21 +200,22 @@ <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="4">Dynamic memory management</a></h2> <p>There are six flavors each of <code>new</code> and <code>delete</code>, so make certain that you're using the right ones! Here are quickie descriptions of <code>new</code>: - <ul> - <li>single object form, throwing a <code>bad_alloc</code> on errors; - this is what most people are used to using - <li>single object "nothrow" form, returning NULL on errors - <li>array new, throwing <code>bad_alloc</code> on errors - <li>array nothrow new, returning NULL on errors - <li>placement new, which does nothing (like it's supposed to) - <li>placement array new, which also does nothing - </ul> - They are distinguished by the parameters that you pass to them, like + </p> + <ul> + <li>single object form, throwing a <code>bad_alloc</code> on errors; + this is what most people are used to using</li> + <li>single object "nothrow" form, returning NULL on errors</li> + <li>array new, throwing <code>bad_alloc</code> on errors</li> + <li>array nothrow new, returning NULL on errors</li> + <li>placement new, which does nothing (like it's supposed to)</li> + <li>placement array new, which also does nothing</li> + </ul> + <p>They are distinguished by the parameters that you pass to them, like any other overloaded function. The six flavors of <code>delete</code> are distinguished the same way, but none of them are allowed to throw an exception under any circumstances anyhow. (They match up for @@ -224,7 +230,8 @@ <code>bad_alloc</code> exception (or, technically, some class derived from it). You can change this by writing your own function (called a new-handler) and then registering it with <code>set_new_handler()</code>: - <pre> + </p> + <pre> typedef void (*PFV)(void); static char* safety; @@ -246,8 +253,7 @@ old_handler = set_new_handler (&my_new_handler); ... } - </pre> - </p> + </pre> <p><code>bad_alloc</code> is derived from the base <code>exception</code> class defined in Chapter 19. </p> @@ -255,11 +261,75 @@ <a href="../faq/index.html">to the FAQ</a>. </p> +<hr /> +<h2><a name="5">RTTI, the ABI, and demangling</a></h2> + <p>If you have read the <a href="../documentation.html#4">source + documentation</a> for <code> namespace abi </code> then you are aware + of the cross-vendor C++ ABI which we use. One of the exposed + functions is the one which we use for demangling in programs like + <code>c++filt</code>, and you can use it yourself as well. + </p> + <p>(The function itself might use different demanglers, but that's the + whole point of abstract interfaces. If we change the implementation, + you won't notice.) + </p> + <p>Probably the only times you'll be interested in demangling at runtime + are when you're seeing <code>typeid</code> strings in RTTI, or when + you're handling the runtime-support exception classes. For example: + </p> + <pre> +#include <exception> +#include <iostream> +#include <cxxabi.h> + +struct empty { }; + +template <typename T, int N> + struct bar { }; + + +int main() +{ + int status; + char *realname; + + // exception classes not in <stdexcept>, thrown by the implementation + // instead of the user + std::bad_exception e; + realname = abi::__cxa_demangle(e.what(), 0, 0, &status); + std::cout << e.what() << "\t=> " << realname << "\t: " << status << '\n'; + free(realname); + + + // typeid + bar<empty,17> u; + const std::type_info &ti = typeid(u); + + realname = abi::__cxa_demangle(ti.name(), 0, 0, &status); + std::cout << ti.name() << "\t=> " << realname << "\t: " << status << '\n'; + free(realname); + + return 0; +}</pre> + <p>With GCC 3.1 and later, this prints + </p> + <pre> + St13bad_exception => std::bad_exception : 0 + 3barI5emptyLi17EE => bar<empty, 17> : 0 </pre> + <p>The demangler interface is described in the source documentation + linked to above. It is actually written in C, so you don't need to + 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.) + </p> + <p>Return <a href="#top">to top of page</a> or + <a href="../faq/index.html">to the FAQ</a>. + </p> <!-- ####################################################### --> -<hr> +<hr /> <p class="fineprint"><em> See <a href="../17_intro/license.html">license.html</a> for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/19_diagnostics/howto.html b/libstdc++-v3/docs/html/19_diagnostics/howto.html index 0d63e7fa6bf..07585bb8347 100644 --- a/libstdc++-v3/docs/html/19_diagnostics/howto.html +++ b/libstdc++-v3/docs/html/19_diagnostics/howto.html @@ -1,13 +1,12 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> <html> <head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> - <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> - <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 19."> - <meta name="GENERATOR" content="vi and eight fingers"> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> + <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> + <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" /> + <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 19." /> + <meta name="GENERATOR" content="vi and eight fingers" /> <title>libstdc++-v3 HOWTO: Chapter 19</title> -<link rel="StyleSheet" href="../lib3styles.css"> +<link rel="StyleSheet" href="../lib3styles.css" /> </head> <body> @@ -20,16 +19,16 @@ <!-- ####################################################### --> -<hr> +<hr /> <h1>Contents</h1> <ul> - <li><a href="#1">Adding data to exceptions</a> - <li><a href="#2">Exception class hierarchy diagram</a> - <li><a href="#3">Concept checkers -- <strong>new and improved!</strong></a> - <li><a href="#4">Verbose <code>terminate</code></a> + <li><a href="#1">Adding data to exceptions</a></li> + <li><a href="#2">Exception class hierarchy diagram</a></li> + <li><a href="#3">Concept checkers -- <strong>new and improved!</strong></a></li> + <li><a href="#4">Verbose <code>terminate</code></a></li> </ul> -<hr> +<hr /> <!-- ####################################################### --> @@ -56,7 +55,7 @@ <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="2">Exception class hierarchy diagram</a></h2> <p>At one point we were going to make up a PDF of the exceptions hierarchy, akin to the one done for the I/O class hierarchy. @@ -72,7 +71,7 @@ <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="3">Concept checkers -- <strong>new and improved!</strong></a></h2> <p>Better taste! Less fat! Literally!</p> <p>In 1999, SGI added <em>concept checkers</em> to their implementation @@ -89,7 +88,7 @@ were found in it on more than one occasion. </p> <p>The primary author of the checking code, Jeremy Siek, had already - started work on a replcement implementation. The new code has been + started work on a replacement implementation. The new code has been formally reviewed and accepted into <a href="http://www.boost.org/libs/concept_check/concept_check.htm">the Boost libraries</a>, and we are pleased to incorporate it into the @@ -102,27 +101,29 @@ <p>For GCC 3.0 and 3.1 they are off by default. They can be enabled at configure time with <a href="../configopts.html"><code>--enable-concept-checks</code></a>. + For 3.1 you can instead #define _GLIBCPP_CONCEPT_CHECKS to enable them + on a per-translation-unit basis. </p> <p>Return <a href="#top">to top of page</a> or <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="4">Verbose <code>terminate</code></a></h2> <p>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 in GCC 3.1 and later: - <pre> + </p> + <pre> #include <exception> int main() { - std::set_terminate (__gnu_cxx::verbose_terminate_handler); + std::set_terminate (__gnu_cxx::__verbose_terminate_handler); ... throw <em>anything</em>; }</pre> - </p> - <p>The <code> verbose_terminate_handler </code> function obtains the name + <p>The <code> __verbose_terminate_handler </code> function obtains the name of the current exception, attempts to demangle it, and prints it to stderr. If the exception is derived from <code> std::exception </code> then the output from <code>what()</code> will be included. @@ -131,7 +132,8 @@ without returning; this one calls abort. </p> <p>For example: - <pre> + </p> + <pre> #include <exception> #include <stdexcept> @@ -143,15 +145,15 @@ int main (int argc) { - std::set_terminate (__gnu_cxx::verbose_terminate_handler); + std::set_terminate (__gnu_cxx::__verbose_terminate_handler); if (argc > 5) throw BLARGH("argc is greater than 5!"); else throw argc; }</pre> - </p> <p>In GCC 3.1 and later, this gives - <pre> + </p> + <pre> % ./a.out terminate called after throwing a `int' Aborted @@ -160,7 +162,7 @@ what(): argc is greater than 5! Aborted %</pre> - The 'Aborted' line comes from the call to abort(), of course. + <p>The 'Aborted' line comes from the call to abort(), of course. </p> <p>Return <a href="#top">to top of page</a> or <a href="../faq/index.html">to the FAQ</a>. @@ -169,7 +171,7 @@ <!-- ####################################################### --> -<hr> +<hr /> <p class="fineprint"><em> See <a href="../17_intro/license.html">license.html</a> for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/20_util/howto.html b/libstdc++-v3/docs/html/20_util/howto.html index d90b5d6654a..7b7485ed837 100644 --- a/libstdc++-v3/docs/html/20_util/howto.html +++ b/libstdc++-v3/docs/html/20_util/howto.html @@ -1,13 +1,12 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> <html> <head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> - <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> - <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 20."> - <meta name="GENERATOR" content="vi and eight fingers"> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> + <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> + <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" /> + <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 20." /> + <meta name="GENERATOR" content="vi and eight fingers" /> <title>libstdc++-v3 HOWTO: Chapter 20</title> -<link rel="StyleSheet" href="../lib3styles.css"> +<link rel="StyleSheet" href="../lib3styles.css" /> </head> <body> @@ -19,16 +18,16 @@ <!-- ####################################################### --> -<hr> +<hr /> <h1>Contents</h1> <ul> - <li><a href="#1"><code>auto_ptr</code> is not omnipotent</a> - <li><a href="#2"><code>auto_ptr</code> inside container classes</a> - <li><a href="#3">Functors</a> - <li><a href="#4">Pairs</a> + <li><a href="#1"><code>auto_ptr</code> is not omnipotent</a></li> + <li><a href="#2"><code>auto_ptr</code> inside container classes</a></li> + <li><a href="#3">Functors</a></li> + <li><a href="#4">Pairs</a></li> </ul> -<hr> +<hr /> <!-- ####################################################### --> @@ -47,7 +46,8 @@ </p> <p>AP <em>is</em> meant to prevent nasty leaks in the presence of exceptions. That's <em>all</em>. This code is AP-friendly: - <pre> + </p> + <pre> // not a recommend naming scheme, but good for web-based FAQs typedef std::auto_ptr<MyClass> APMC; @@ -62,21 +62,24 @@ function_taking_MyClass_pointer (ap.get()); } - </pre>When an exception gets thrown, the instance of MyClass that's + </pre> + <p>When an exception gets thrown, the instance of MyClass that's been created on the heap will be <code>delete</code>'d as the stack is unwound past <code>func()</code>. </p> <p>Changing that code as follows is <em>not</em> AP-friendly: - <pre> + </p> + <pre> APMC ap (new MyClass[22]); - </pre>You will get the same problems as you would without the use + </pre> + <p>You will get the same problems as you would without the use of AP: - <pre> + </p> + <pre> char* array = new char[10]; // array new... ... delete array; // ...but single-object delete - </pre> - </p> + </pre> <p>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 @@ -87,18 +90,19 @@ <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="2"><code>auto_ptr</code> inside container classes</a></h2> <p>All of the <a href="../23_containers/howto.html">containers</a> described in the standard library require their contained types to have, among other things, a copy constructor like this: - <pre> + </p> + <pre> struct My_Type { My_Type (My_Type const&); }; - </pre> - Note the const keyword; the object being copied shouldn't change. + </pre> + <p>Note the const keyword; the object being copied shouldn't change. The template class <code>auto_ptr</code> (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 @@ -113,7 +117,8 @@ <a href="../19_diagnostics/howto.html#3">concept checks</a> built in to this implementation will issue an error if you try to compile code like this: - <pre> + </p> + <pre> #include <vector> #include <memory> @@ -121,27 +126,27 @@ { std::vector< std::auto_ptr<int> > vec_ap_int; } - </pre> - Should you try this with the checks enabled, you will see an error. + </pre> + <p>Should you try this with the checks enabled, you will see an error. </p> <p>Return <a href="#top">to top of page</a> or <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="3">Functors</a></h2> <p>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 - <a href="http://www.sgi.com/Technology/STL/functors.html">their - http://www.sgi.com/Technology/STL/functors.html</a>. + <a href="http://www.sgi.com/tech/stl/functors.html">their + http://www.sgi.com/tech/stl/functors.html</a>. </p> <p>Return <a href="#top">to top of page</a> or <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="4">Pairs</a></h2> <p>The <code>pair<T1,T2></code> is a simple and handy way to carry around a pair of objects. One is of type T1, and another of @@ -151,16 +156,20 @@ </p> <p>Construction is simple. The default ctor initializes each member with its respective default ctor. The other simple ctor, - <pre> + </p> + <pre> pair (const T1& x, const T2& y); - </pre>does what you think it does, <code>first</code> getting <code>x</code> + </pre> + <p>does what you think it does, <code>first</code> getting <code>x</code> and <code>second</code> getting <code>y</code>. </p> <p>There is a copy constructor, but it requires that your compiler handle member function templates: - <pre> + </p> + <pre> template <class U, class V> pain (const pair<U,V>& p); - </pre>The compiler will convert as necessary from U to T1 and from + </pre> + <p>The compiler will convert as necessary from U to T1 and from V to T2 in order to perform the respective initializations. </p> <p>The comparison operators are done for you. Equality @@ -170,24 +179,25 @@ <code>operator==</code> functions (for types like MyClass) or builtin comparisons (for types like int, char, etc). </p> - <a name="pairlt"> - <p>The less-than operator is a bit odd the first time you see it. It + <p><a name="pairlt"> + The less-than operator is a bit odd the first time you see it. It is defined as evaluating to: - <pre> + </a> + </p> + <pre> x.first < y.first || ( !(y.first < x.first) && x.second < y.second ) - </pre> - The other operators are not defined using the <code>rel_ops</code> + </pre> + <p>The other operators are not defined using the <code>rel_ops</code> functions above, but their semantics are the same. </p> - </a> <p>Finally, there is a template function called <code>make_pair</code> that takes two references-to-const objects and returns an instance of a pair instantiated on their respective types: - <pre> - pair<int,MyClass> p = make_pair(4,myobject); - </pre> </p> + <pre> + pair<int,MyClass> p = make_pair(4,myobject); + </pre> <p>Return <a href="#top">to top of page</a> or <a href="../faq/index.html">to the FAQ</a>. </p> @@ -197,7 +207,7 @@ <!-- ####################################################### --> -<hr> +<hr /> <p class="fineprint"><em> See <a href="../17_intro/license.html">license.html</a> for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/21_strings/howto.html b/libstdc++-v3/docs/html/21_strings/howto.html index 6acd357c959..e49a166c0c5 100644 --- a/libstdc++-v3/docs/html/21_strings/howto.html +++ b/libstdc++-v3/docs/html/21_strings/howto.html @@ -1,13 +1,12 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> <html> <head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> - <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> - <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 21."> - <meta name="GENERATOR" content="vi and eight fingers"> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> + <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> + <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" /> + <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 21." /> + <meta name="GENERATOR" content="vi and eight fingers" /> <title>libstdc++-v3 HOWTO: Chapter 21</title> -<link rel="StyleSheet" href="../lib3styles.css"> +<link rel="StyleSheet" href="../lib3styles.css" /> </head> <body> @@ -18,16 +17,17 @@ <!-- ####################################################### --> -<hr> +<hr /> <h1>Contents</h1> <ul> - <li><a href="#1">MFC's CString</a> - <li><a href="#2">A case-insensitive string class</a> - <li><a href="#3">Breaking a C++ string into tokens</a> - <li><a href="#4">Simple transformations</a> + <li><a href="#1">MFC's CString</a></li> + <li><a href="#2">A case-insensitive string class</a></li> + <li><a href="#3">Breaking a C++ string into tokens</a></li> + <li><a href="#4">Simple transformations</a></li> + <li><a href="#5">Making strings of arbitrary character types</a></li> </ul> -<hr> +<hr /> <!-- ####################################################### --> @@ -42,24 +42,29 @@ <p>Things are not as bad as they seem. In <a href="http://gcc.gnu.org/ml/gcc/1999-04n/msg00236.html">this message</a>, Joe Buck points out a few very important things: + </p> <ul> <li>The Standard <code>string</code> supports all the operations that CString does, with three exceptions. + </li> <li>Two of those exceptions (whitespace trimming and case conversion) are trivial to implement. In fact, we do so on this page. + </li> <li>The third is <code>CString::Format</code>, which allows formatting in the style of <code>sprintf</code>. This deserves some mention: + </li> </ul> - </p> - <a name="1.1internal"> <!-- Coming from Chapter 27 --> - <p>The old libg++ library had a function called form(), which did much + <p><a name="1.1internal"> <!-- Coming from Chapter 27 --> + 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: - <pre> + </a> + </p> + <pre> #include <iostream> #include <string> #include <sstream> @@ -79,10 +84,10 @@ return output_stream.str(); } </pre> - </p></a> <p>A serious problem with CString is a design bug in its memory allocation. Specifically, quoting from that same message: - <pre> + </p> + <pre> CString suffers from a common programming error that results in poor performance. Consider the following code: @@ -103,22 +108,25 @@ If you replace CString with string in the above function, the performance is O(n). - </pre> - </p> + </pre> <p>Joe Buck also pointed out some other things to keep in mind when comparing CString and the Standard string class: + </p> <ul> <li>CString permits access to its internal representation; coders who exploited that may have problems moving to <code>string</code>. + </li> <li>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. - <em><B>Note:</B> It looks like the 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.</em> + <em><strong>Note:</strong> It looks like the 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.</em> + </li> <li><code>string</code> operations like this have O(n) complexity <em>if the implementors do it correctly</em>. The libstdc++ implementors did it correctly. Other vendors might not. + </li> <li>While parts of the SGI STL are used in libstdc++-v3, their string class is not. The SGI <code>string</code> is essentially <code>vector<char></code> and does not do any reference @@ -128,13 +136,13 @@ 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?) + </li> </ul> - </p> <p>Return <a href="#top">to top of page</a> or <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="2">A case-insensitive string class</a></h2> <p>The well-known-and-if-it-isn't-well-known-it-ought-to-be <a href="http://www.peerdirect.com/resources/">Guru of the Week</a> @@ -143,7 +151,8 @@ is identical to the standard 'string' class, but is case-insensitive in the same way as the (common but nonstandard) C function stricmp():" - <pre> + </p> + <pre> ci_string s( "AbCdE" ); // case insensitive @@ -153,7 +162,6 @@ // still case-preserving, of course assert( strcmp( s.c_str(), "AbCdE" ) == 0 ); assert( strcmp( s.c_str(), "abcde" ) != 0 ); </pre> - </p> <p>The solution is surprisingly easy. The original answer pages on the GotW website were removed into cold storage, in @@ -188,7 +196,7 @@ <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="3">Breaking a C++ string into tokens</a></h2> <p>The Standard C (and C++) function <code>strtok()</code> leaves a lot to be desired in terms of user-friendliness. It's unintuitive, it @@ -209,21 +217,23 @@ comments on what kind of string it will accept). 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: - <pre> + </p> + <pre> 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"; - }</pre> - You would see this as output: - <pre> + } </pre> + <p>You would see this as output: + </p> + <pre> :this: :is: :a: - :test:</pre> - with all the whitespace removed. The original <code>s</code> is still + :test: </pre> + <p>with all the whitespace removed. The original <code>s</code> is still available for use, <code>ls</code> will clean up after itself, and <code>ls.size()</code> will return how many tokens there were. </p> @@ -247,7 +257,7 @@ <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="4">Simple transformations</a></h2> <p>Here are Standard, simple, and portable ways to perform common transformations on a <code>string</code> instance, such as "convert @@ -257,7 +267,8 @@ </p> <p>This code will go through some iterations (no pun). Here's the simplistic version usually seen on Usenet: - <pre> + </p> + <pre> #include <string> #include <algorithm> #include <cctype> // old <ctype.h> @@ -275,7 +286,7 @@ std::string capital_s; capital_s.reserve(s.size()); std::transform (s.begin(), s.end(), capital_s.begin(), tolower); </pre> - <span class="larger"><strong>Note</strong></span> that these calls all + <p><span class="larger"><strong>Note</strong></span> that these calls all involve the global C locale through the use of the C functions <code>toupper/tolower</code>. This is absolutely guaranteed to work -- but <em>only</em> if the string contains <em>only</em> characters @@ -286,12 +297,12 @@ characters (hahahahahaha), then you're done. </p> <p>At minimum, you can write short wrappers like - <pre> + </p> + <pre> char toLower (char c) { return tolower(static_cast<unsigned char>(c)); - }</pre> - </p> + } </pre> <p>The correct method is to use a facet for a particular locale and call its conversion functions. These are discussed more in Chapter 22; the specific part is @@ -303,7 +314,8 @@ like transformations, this task is trivial with the use of string's <code>find</code> family. These examples are broken into multiple statements for readability: - <pre> + </p> + <pre> std::string str (" \t blah blah blah \n "); // trim leading whitespace @@ -313,7 +325,7 @@ // trim trailing whitespace notwhite = str.find_last_not_of(" \t\n"); str.erase(notwhite+1); </pre> - Obviously, the calls to <code>find</code> could be inserted directly + <p>Obviously, the calls to <code>find</code> could be inserted directly into the calls to <code>erase</code>, in case your compiler does not optimize named temporaries out of existence. </p> @@ -321,11 +333,20 @@ <a href="../faq/index.html">to the FAQ</a>. </p> +<hr /> +<h2><a name="5">Making strings of arbitrary character types</a></h2> + <p>how to work with char_traits -- in the archives, just need to + go through and pull the examples together + </p> + <p>Return <a href="#top">to top of page</a> or + <a href="../faq/index.html">to the FAQ</a>. + </p> + <!-- ####################################################### --> -<hr> +<hr /> <p class="fineprint"><em> See <a href="../17_intro/license.html">license.html</a> for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/22_locale/codecvt.html b/libstdc++-v3/docs/html/22_locale/codecvt.html index 46147d90556..64f3856d479 100644 --- a/libstdc++-v3/docs/html/22_locale/codecvt.html +++ b/libstdc++-v3/docs/html/22_locale/codecvt.html @@ -1,14 +1,22 @@ <html> <head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> + <meta name="AUTHOR" content="bkoz@redhat.com (Benjamin Kosnik)" /> + <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" /> + <meta name="DESCRIPTION" content="Notes on the codecvt implementation." /> + <title>Notes on the codecvt implementation.</title> +<link rel="StyleSheet" href="../lib3styles.css" /> +</head> +<body> <h1> Notes on the codecvt implementation. </h1> -</head> -<I> +<p> +<em> prepared by Benjamin Kosnik (bkoz@redhat.com) on August 28, 2000 -</I> +</em> +</p> -<p> <h2> 1. Abstract </h2> @@ -28,26 +36,25 @@ wide and narrow characters and the implementation-provided extended functionality are given. </p> -<p> <h2> 2. What the standard says </h2> Around page 425 of the C++ Standard, this charming heading comes into view: -<BLOCKQUOTE> +<blockquote> 22.2.1.5 - Template class codecvt [lib.locale.codecvt] -</BLOCKQUOTE> +</blockquote> The text around the codecvt definition gives some clues: -<BLOCKQUOTE> -<I> +<blockquote> +<em> -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. -</I> -</BLOCKQUOTE> +</em> +</blockquote> <p> Hmm. So, in some unspecified way, Unicode encodings and @@ -55,18 +62,18 @@ translations between other character sets should be handled by this class. </p> -<BLOCKQUOTE> -<I> +<blockquote> +<em> -2- The stateT argument selects the pair of codesets being mapped between. -</I> -</BLOCKQUOTE> +</em> +</blockquote> <p> Ah ha! Another clue... </p> -<BLOCKQUOTE> -<I> +<blockquote> +<em> -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 @@ -78,11 +85,12 @@ 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. -</I> -</BLOCKQUOTE> +</em> +</blockquote> <p> At this point, a couple points become clear: +</p> <p> One: The standard clearly implies that attempts to add non-required @@ -95,7 +103,6 @@ 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.</p> -<p> <h2> 3. Some thoughts on what would be useful </h2> @@ -116,15 +123,19 @@ 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. +</p> <p> Thus, portable C++ code cannot assume a byte size (or endianness) either. +</p> <p> Getting back to the frequently asked question: What about Unicode strings? +</p> <p> What magic spell will do this conversion? +</p> <p> A couple of comments: @@ -142,7 +153,7 @@ includes: <ul> <li> -</p> +<p> 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 @@ -150,10 +161,12 @@ operating system allows bi-directional mapping between far more than the following tantalizing possibilities: </p> +<p> (An edited list taken from <code>`iconv --list`</code> on a Red Hat 6.2/Intel system: +</p> -<BLOCKQUOTE> -<PRE> +<blockquote> +<pre> 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, @@ -163,8 +176,8 @@ 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). -</PRE> -</BLOCKQUOTE> +</pre> +</blockquote> <p> For iconv-based implementations, string literals for each of the @@ -172,9 +185,12 @@ encodings (ie. "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. +</p> +</li> <li> Maximum length of the identifying string literal. +</li> <li> Some encodings are require explicit endian-ness. As such, some kind @@ -182,6 +198,7 @@ mechanism may be required. "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.) +</li> <li> Types representing the conversion state, for conversions involving @@ -189,24 +206,28 @@ mechanism may be required. conversions using iconv (such as the type iconv_t.) Note that the conversion descriptor encodes more information than a simple encoding state type. +</li> <li> Conversion descriptors for both directions of encoding. (ie, both UCS-2 to UTF-8 and UTF-8 to UCS-2.) +</li> <li> Something to indicate if the conversion requested if valid. +</li> <li> Something to represent if the conversion descriptors are valid. +</li> <li> 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. +</li> </ul> -<p> <h2> 4. Problems with "C" code conversions : thread safety, global locales, termination. @@ -219,11 +240,13 @@ when implemented using standard "C" functions. <p> Three problems arise, one big, one of medium importance, and one small. +</p> <p> 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. +</p> <p> Of medium concern, in the grand scope of things, is that the functions @@ -231,6 +254,7 @@ 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! +</p> <p> The last, and fundamental problem, is the assumption of a global @@ -242,14 +266,15 @@ 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++-v3 is trying to offer, as an option, a high-quality implementation, damn the additional complexity! +</p> <p> 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. +</p> -<p> <h2> 5. Design </h2> @@ -259,25 +284,30 @@ The two required specializations are implemented as follows: <code> codecvt<char, char, mbstate_t> </code> +</p> <p> This is a degenerate (ie, does nothing) specialization. Implementing this was a piece of cake. +</p> <p> <code> codecvt<char, wchar_t, mbstate_t> </code> +</p> <p> 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. +</p> <p> Neither of these two required specializations deals with Unicode characters. As such, libstdc++-v3 implements a partial specialization of the codecvt class with and iconv wrapper class, __enc_traits as the third template parameter. +</p> <p> This implementation should be standards conformant. First of all, the @@ -288,33 +318,40 @@ non-required conversions. Second of all, the standard says (in Chapter 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. +</p> <p> As such, the type __enc_traits 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. +</p> <p> There are two constructors for __enc_traits: +</p> <p> <code> __enc_traits() : __in_desc(0), __out_desc(0) </code> +</p> <p> This default constructor sets the internal encoding to some default (currently UCS4) and the external encoding to whatever is returned by nl_langinfo(CODESET). +</p> <p> <code> __enc_traits(const char* __int, const char* __ext) </code> +</p> <p> This constructor takes as parameters string literals that indicate the desired internal and external encoding. There are no defaults for either argument. +</p> <p> One of the issues with iconv is that the string literals identifying @@ -325,24 +362,28 @@ 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. +</p> <p> <code> void _M_init() </code> +</p> <p> Strangely enough, this member function attempts to open conversion descriptors for a given __enc_traits 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. +</p> <p> <code> bool _M_good() </code> +</p> <p> Provides a way to see if the given __enc_traits object has been properly initialized. If the string literals describing the desired @@ -351,57 +392,60 @@ 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. +</p> <p> <code> __enc_traits(const __enc_traits&) </code> +</p> <p> 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. +</p> <p> Definitions for all the required codecvt member functions are provided for this specialization, and usage of codecvt<internal character type, external character type, __enc_traits> is consistent with other codecvt usage. +</p> -<p> <h2> 6. Examples </h2> <ul> - <li> - a. conversions involving string literals + <li> + a. conversions involving string literals <pre> - typedef codecvt_base::result result; - typedef unsigned short unicode_t; - typedef unicode_t int_type; - typedef char ext_type; - typedef __enc_traits enc_type; - typedef codecvt<int_type, ext_type, enc_type> unicode_codecvt; - - const ext_type* e_lit = "black pearl jasmine tea"; - int size = strlen(e_lit); - int_type i_lit_base[24] = + typedef codecvt_base::result result; + typedef unsigned short unicode_t; + typedef unicode_t int_type; + typedef char ext_type; + typedef __enc_traits enc_type; + typedef codecvt<int_type, ext_type, enc_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 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; + 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); + 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); @@ -409,70 +453,80 @@ codecvt usage. 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); + 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 ); </pre> - <li> - b. conversions involving std::string - <li> - c. conversions involving std::filebuf and std::ostream + </li> + <li> + b. conversions involving std::string + </li> + <li> + c. conversions involving std::filebuf and std::ostream + </li> </ul> More information can be found in the following testcases: <ul> -<li> testsuite/22_locale/codecvt_char_char.cc -<li> testsuite/22_locale/codecvt_unicode_wchar_t.cc -<li> testsuite/22_locale/codecvt_unicode_char.cc -<li> testsuite/22_locale/codecvt_wchar_t_char.cc +<li> testsuite/22_locale/codecvt_char_char.cc </li> +<li> testsuite/22_locale/codecvt_unicode_wchar_t.cc </li> +<li> testsuite/22_locale/codecvt_unicode_char.cc </li> +<li> testsuite/22_locale/codecvt_wchar_t_char.cc </li> </ul> -<p> <h2> 7. Unresolved Issues </h2> <ul> <li> - 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? + 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? +</li> <li> - b. conversions involving std::string - - <ul> - <li> - how should operators != and == work for string of - different/same encoding? - - <li> - what is equal? A byte by byte comparison or an - encoding then byte comparison? - - <li> - conversions between narrow, wide, and unicode strings - </ul> + b. conversions involving std::string + + <ul> + <li> + how should operators != and == work for string of + different/same encoding? + </li> + + <li> + what is equal? A byte by byte comparison or an + encoding then byte comparison? + </li> + + <li> + conversions between narrow, wide, and unicode strings + </li> + </ul> +</li> <li> - c. conversions involving std::filebuf and std::ostream - <ul> - <li> - how to initialize the state object in a - standards-conformant manner? - - <li> - how to synchronize the "C" and "C++" - conversion information? - - <li> - wchar_t/char internal buffers and conversions between - internal/external buffers? - </ul> + c. conversions involving std::filebuf and std::ostream + <ul> + <li> + how to initialize the state object in a + standards-conformant manner? + </li> + + <li> + how to synchronize the "C" and "C++" + conversion information? + </li> + + <li> + wchar_t/char internal buffers and conversions between + internal/external buffers? + </li> + </ul> +</li> </ul> -<p> <h2> 8. Acknowledgments </h2> @@ -480,7 +534,6 @@ Ulrich Drepper for the iconv suggestions and patient answering of late-night questions, Jason Merrill for the template partial specialization hints, language clarification, and wchar_t fixes. -<p> <h2> 9. Bibliography / Referenced Documents </h2> @@ -489,34 +542,44 @@ Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters "6. C <p> Drepper, Ulrich, Numerous, late-night email correspondence +</p> <p> Feather, Clive, "A brief description of Normative Addendum 1," in particular the parts on Extended Character Sets http://www.lysator.liu.se/c/na1.html +</p> <p> Haible, Bruno, "The Unicode HOWTO" v0.18, 4 August 2000 ftp://ftp.ilog.fr/pub/Users/haible/utf8/Unicode-HOWTO.html +</p> <p> ISO/IEC 14882:1998 Programming languages - C++ +</p> <p> ISO/IEC 9899:1999 Programming languages - C +</p> <p> Khun, Markus, "UTF-8 and Unicode FAQ for Unix/Linux" http://www.cl.cam.ac.uk/~mgk25/unicode.html +</p> <p> Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000 +</p> <p> Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000 +</p> <p> System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x) The Open Group/The Institute of Electrical and Electronics Engineers, Inc. http://www.opennc.org/austin/docreg.html +</p> - +</body> +</html> diff --git a/libstdc++-v3/docs/html/22_locale/ctype.html b/libstdc++-v3/docs/html/22_locale/ctype.html index 3568145c92e..886f83d0739 100644 --- a/libstdc++-v3/docs/html/22_locale/ctype.html +++ b/libstdc++-v3/docs/html/22_locale/ctype.html @@ -1,14 +1,20 @@ <html> <head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> + <meta name="AUTHOR" content="bkoz@redhat.com (Benjamin Kosnik)" /> + <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" /> + <meta name="DESCRIPTION" content="Notes on the ctype implementation." /> + <title>Notes on the ctype implementation.</title> +<link rel="StyleSheet" href="../lib3styles.css" /> +</head> +<body> <h1> Notes on the ctype implementation. </h1> -</head> -<I> +<em> prepared by Benjamin Kosnik (bkoz@redhat.com) on August 30, 2000 -</I> +</em> -<p> <h2> 1. Abstract </h2> @@ -16,13 +22,11 @@ prepared by Benjamin Kosnik (bkoz@redhat.com) on August 30, 2000 Woe is me. </p> -<p> <h2> 2. What the standard says </h2> -<p> <h2> 3. Problems with "C" ctype : global locales, termination. </h2> @@ -32,8 +36,8 @@ 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. +</p> -<p> <h2> 4. Design </h2> @@ -43,80 +47,79 @@ The two required specializations are implemented as follows: <code> ctype<char> </code> +</p> <p> This is simple specialization. Implementing this was a piece of cake. +</p> <p> <code> ctype<wchar_t> </code> +</p> <p> 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. +</p> <p> Neither of these two required specializations deals with Unicode characters. As such, libstdc++-v3 implements +</p> - - -<p> <h2> 5. Examples </h2> <pre> - typedef ctype<char> cctype; + typedef ctype<char> cctype; </pre> More information can be found in the following testcases: <ul> -<li> testsuite/22_locale/ctype_char_members.cc -<li> testsuite/22_locale/ctype_wchar_t_members.cc +<li> testsuite/22_locale/ctype_char_members.cc </li> +<li> testsuite/22_locale/ctype_wchar_t_members.cc </li> </ul> -<p> <h2> 6. Unresolved Issues </h2> <ul> - <li> how to deal with the global locale issue? + <li> how to deal with the global locale issue? </li> - <li> how to deal with different types than char, wchar_t? + <li> how to deal with different types than char, wchar_t? </li> - <li> codecvt/ctype overlap: narrow/widen + <li> codecvt/ctype overlap: narrow/widen </li> - <li> mask typedef in codecvt_base, argument types in codecvt. - what is know about this type? + <li> mask typedef in codecvt_base, argument types in codecvt. + what is know about this type? </li> - <li> why mask* argument in codecvt? - - <li> 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? + <li> why mask* argument in codecvt? </li> + + <li> 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? </li> - <li> get the ctype<wchar_t>::mask stuff under control. Need to - make some kind of static table, and not do lookup evertime - somebody hits the do_is... functions. Too bad we can't just - redefine mask for ctype<wchar_t> - - <li> rename abstract base class. See if just smash-overriding - is a better approach. Clarify, add sanity to naming. + <li> get the ctype<wchar_t>::mask stuff under control. Need to + make some kind of static table, and not do lookup evertime + somebody hits the do_is... functions. Too bad we can't just + redefine mask for ctype<wchar_t> </li> + + <li> rename abstract base class. See if just smash-overriding + is a better approach. Clarify, add sanity to naming. </li> </ul> -<p> <h2> 7. Acknowledgments </h2> Ulrich Drepper for patient answering of late-night questions, skeletal examples, and C language expertise. -<p> <h2> 8. Bibliography / Referenced Documents </h2> @@ -125,22 +128,29 @@ Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters "6. C <p> Drepper, Ulrich, Numerous, late-night email correspondence +</p> <p> ISO/IEC 14882:1998 Programming languages - C++ +</p> <p> ISO/IEC 9899:1999 Programming languages - C +</p> <p> Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000 +</p> <p> Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000 +</p> <p> System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x) The Open Group/The Institute of Electrical and Electronics Engineers, Inc. http://www.opennc.org/austin/docreg.html +</p> - +</body> +</html> diff --git a/libstdc++-v3/docs/html/22_locale/howto.html b/libstdc++-v3/docs/html/22_locale/howto.html index d8ada0464b1..106662753d9 100644 --- a/libstdc++-v3/docs/html/22_locale/howto.html +++ b/libstdc++-v3/docs/html/22_locale/howto.html @@ -1,13 +1,12 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> <html> <head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> - <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> - <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 22."> - <meta name="GENERATOR" content="vi and eight fingers"> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> + <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> + <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" /> + <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 22." /> + <meta name="GENERATOR" content="vi and eight fingers" /> <title>libstdc++-v3 HOWTO: Chapter 22</title> -<link rel="StyleSheet" href="../lib3styles.css"> +<link rel="StyleSheet" href="../lib3styles.css" /> </head> <body> @@ -16,39 +15,40 @@ <p>Chapter 22 deals with the C++ localization facilities. </p> <!-- I wanted to write that sentence in something requiring an exotic font, - like Cryllic or Kanji. Probably more work than such cuteness is worth, + like Cyrllic or Kanji. Probably more work than such cuteness is worth, but I still think it'd be funny. --> <!-- ####################################################### --> -<hr> +<hr /> <h1>Contents</h1> <ul> - <li><a href="#1">class locale</a> - <li><a href="#2">class codecvt</a> - <li><a href="#3">class ctype</a> - <li><a href="#4">class messages</a> - <li><a href="#5">Bjarne Stroustrup on Locales</a> - <li><a href="#6">Nathan Myers on Locales</a> - <li><a href="#7">Correct Transformations</a> + <li><a href="#1">class locale</a></li> + <li><a href="#2">class codecvt</a></li> + <li><a href="#3">class ctype</a></li> + <li><a href="#4">class messages</a></li> + <li><a href="#5">Bjarne Stroustrup on Locales</a></li> + <li><a href="#6">Nathan Myers on Locales</a></li> + <li><a href="#7">Correct Transformations</a></li> </ul> <!-- ####################################################### --> -<hr> +<hr /> <h2><a name="1">class locale</a></h2> <p>Notes made during the implementation of locales can be found <a href="locale.html">here</a>. </p> -<hr> +<hr /> <h2><a name="2">class codecvt</a></h2> <p>Notes made during the implementation of codecvt can be found <a href="codecvt.html">here</a>. </p> <p>The following is the abstract from the implementation notes: + </p> <blockquote> The standard class codecvt attempts to address conversions between different character encoding schemes. In particular, the standard @@ -64,21 +64,20 @@ the required specializations for wide and narrow characters and the implementation-provided extended functionality are given. </blockquote> - </p> -<hr> +<hr /> <h2><a name="3">class ctype</a></h2> <p>Notes made during the implementation of ctype can be found <a href="ctype.html">here</a>. </p> -<hr> +<hr /> <h2><a name="4">class messages</a></h2> <p>Notes made during the implementation of messages can be found <a href="messages.html">here</a>. </p> -<hr> +<hr /> <h2><a name="5">Stroustrup on Locales</a></h2> <p>Dr. Bjarne Stroustrup has released a <a href="http://www.research.att.com/~bs/3rd_loc0.html">pointer</a> @@ -88,22 +87,22 @@ description of locales and how to use them. </p> <p>He also writes: + </p> <blockquote><em> Please note that I still consider this detailed description of locales beyond the needs of most C++ programmers. It is written with experienced programmers in mind and novices will do best to avoid it. </em></blockquote> - </p> -<hr> +<hr /> <h2><a name="6">Nathan Myers on Locales</a></h2> <p>An article entitled "The Standard C++ Locale" was published in Dr. Dobb's Journal and can be found <a href="http://www.cantrip.org/locale.html">here</a>. </p> -<hr> +<hr /> <h2><a name="7">Correct Transformations</a></h2> <!-- Jumping directly to here from chapter 21. --> <p>A very common question on newsgroups and mailing lists is, "How @@ -131,6 +130,7 @@ is created. Then member functions of that locale are called to perform minor tasks. Continuing the example from Chapter 21, we wish to use the following convenience functions: + </p> <pre> namespace std { template <class charT> @@ -140,6 +140,7 @@ charT tolower (charT c, const locale& loc) const; }</pre> + <p> This function extracts the appropriate "facet" from the locale <em>loc</em> and calls the appropriate member function of that facet, passing <em>c</em> as its argument. The resulting character @@ -154,6 +155,7 @@ parameter. So we write simple wrapper structs to handle that. </p> <p>The next-to-final version of the code started in Chapter 21 looks like: + </p> <pre> #include <iterator> // for back_inserter #include <locale> @@ -163,7 +165,7 @@ struct Toupper { - Toupper (std::locale const& l) : loc(l) {;} + Toupper(std::locale const& l) : loc(l) {;} char operator() (char c) { return std::toupper(c,loc); } private: std::locale const& loc; @@ -171,7 +173,7 @@ struct Tolower { - Tolower (std::locale const& l) : loc(l) {;} + Tolower(std::locale const& l) : loc(l) {;} char operator() (char c) { return std::tolower(c,loc); } private: std::locale const& loc; @@ -179,28 +181,22 @@ int main () { - std::string s ("Some Kind Of Initial Input Goes Here"); - Toupper up ( std::locale("C") ); - Tolower down ( std::locale("C") ); + std::string s("Some Kind Of Initial Input Goes Here"); + std::locale loc_c("C"); + Toupper up(loc_c); + Tolower down(loc_c); - // Change everything into upper case - std::transform (s.begin(), s.end(), s.begin(), - up - ); + // Change everything into upper case. + std::transform(s.begin(), s.end(), s.begin(), up); - // Change everything into lower case - std::transform (s.begin(), s.end(), s.begin(), - down - ); + // Change everything into lower case. + std::transform(s.begin(), s.end(), s.begin(), down); // Change everything back into upper case, but store the - // result in a different string + // result in a different string. std::string capital_s; - std::transform (s.begin(), s.end(), std::back_inserter(capital_s), - up - ); + std::transform(s.begin(), s.end(), std::back_inserter(capital_s), up); }</pre> - </p> <p>The final version of the code uses <code>bind2nd</code> to eliminate the wrapper structs, but the resulting code is tricky. I have not shown it here because no compilers currently available to me will @@ -210,7 +206,7 @@ <!-- ####################################################### --> -<hr> +<hr /> <p class="fineprint"><em> See <a href="../17_intro/license.html">license.html</a> for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/22_locale/locale.html b/libstdc++-v3/docs/html/22_locale/locale.html index 859050f23fa..6816204df8f 100644 --- a/libstdc++-v3/docs/html/22_locale/locale.html +++ b/libstdc++-v3/docs/html/22_locale/locale.html @@ -1,122 +1,504 @@ -<html> +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE html + PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> + <meta name="AUTHOR" content="bkoz@redhat.com (Benjamin Kosnik)" /> + <meta name="KEYWORDS" content="HOWTO, libstdc++, locale name LC_ALL" /> + <meta name="DESCRIPTION" content="Notes on the locale implementation." /> + <title>Notes on the locale implementation.</title> +<link rel="StyleSheet" href="../lib3styles.css" /> +</head> +<body> <h1> Notes on the locale implementation. </h1> -</head> -<I> -prepared by Benjamin Kosnik (bkoz@redhat.com) on August 8, 2001 -</I> +<em> +prepared by Benjamin Kosnik (bkoz@redhat.com) on October 14, 2002 +</em> -<p> <h2> -1. Abstract Describes the basic locale object, including nested -classes id, facet, and the reference-counted implementation object, -class _Impl. +1. Abstract </h2> <p> +Describes the basic locale object, including nested +classes id, facet, and the reference-counted implementation object, +class _Impl. </p> -<p> <h2> 2. What the standard says -See Chapter 22 of the standard. </h2> +Class locale is non-templatized and has two distinct types nested +inside of it: +<blockquote> +<em> +class facet +22.1.1.1.2 Class locale::facet +</em> +</blockquote> <p> -<h2> -3. Problems with "C" locales : global locales, termination. -</h2> +Facets actually implement locale functionality. For instance, a facet +called numpunct is the data objects that can be used to query for the +thousands separator is in the German locale. +</p> + +Literally, a facet is strictly defined: +<ul> + <li>containing the following public data member: + <p> + <code>static locale::id id;</code> + </p> + </li> + + <li>derived from another facet: + <p> + <code> class gnu_codecvt: public std::ctype<user-defined-type></code> + </p> + </li> +</ul> <p> -The major problem is fitting an object-orientated and non-global locale -design ontop of POSIX and other relevant stanards, which include the -Single Unix (nee X/Open.) +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. +</p> -Because POSIX falls down so completely, portibility is an issue. +<blockquote> +<em> +class id +22.1.1.1.3 - Class locale::id +</em> +</blockquote> + +<p> +Provides an index for looking up specific facets. <p> + <h2> -4. Design +3. Interacting with "C" locales. </h2> -Class locale in non-templatized and has three distinct types nested -inside of it: -class facet -22.1.1.1.2 Class locale::facet +<p> +Some help on determining the underlying support for locales on a system. +Note, this is specific to linux (and glibc-2.3.x) +</p> -Facets actually implement locale functionality. For instance, a facet -called numpunct is the data objects that can be used to query for the -thousands separator is in the German locale. +<ul> + <li> <code>`locale -a`</code> displays available locales. +<blockquote> +<pre> +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 +</pre> +</blockquote> +</li> + + <li> <code>`locale`</code> displays environmental variables + that impact how locale("") will be deduced. -Literally, a facet is strictly defined: - - containing -public: - static locale::id id; +<blockquote> +<pre> +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= +</pre> +</blockquote> +</li> +</ul> -- or derived from another facet +<p> +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: +</p> + <code>std::locale::global(std::locale(""));</code> -The only other thing of interest in this class is the memory -management of facets. Each constructor of a facet class takes a -std::size_t __refs argument: if __refs == 0, the facet is deleted when -no longer used. if __refs == 1, the facet is not destroyed, even when -it is no longer reference. +<p>affects the C functions as if the following call was made:</p> + <code>std::setlocale(LC_ALL, "");</code> -class id -Provides an index for looking up specific facets. +<p> +On the other hand, there is *no* viceversa, 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. +</p> -class _Impl + +<h2> +4. Design +</h2> + + +<p> +The major design challenge is fitting an object-orientated and +non-global locale design ontop of POSIX and other relevant stanards, +which include the Single Unix (nee X/Open.) +</p> <p> +Because POSIX falls down so completely, portibility is an issue. +</p> + +class _Impl +The internal representation of the std::locale object. + + <h2> 5. Examples </h2> -<pre> - typedef __locale_t locale; -</pre> - More information can be found in the following testcases: <ul> -<li> testsuite/22_locale/ctype_char_members.cc -<li> testsuite/22_locale/ctype_wchar_t_members.cc +<li> testsuite/22_locale/all </li> </ul> -<p> <h2> 6. Unresolved Issues </h2> <ul> - <li> locale -a displays available locales on linux - - <li> locale initialization: at what point does _S_classic, - _S_global get initialized? Can named locales assume this - initialization has already taken place? - - <li> document how named locales error check when filling data - members. Ie, a fr_FR locale that doesn't have - numpunct::truename(): does it use "true"? Or is it a blank - string? What's the convention? - - <li> 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"). - - <li> what should non-required facet instantiations do? If the - generic implemenation is provided, then how to end-users - provide specializations? + <li> locale initialization: at what point does _S_classic, + _S_global get initialized? Can named locales assume this + initialization has already taken place? </li> + + <li> document how named locales error check when filling data + members. Ie, a fr_FR locale that doesn't have + numpunct::truename(): does it use "true"? Or is it a blank + string? What's the convention? </li> + + <li> 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"). </li> + + <li> what should non-required facet instantiations do? If the + generic implemenation is provided, then how to end-users + provide specializations? </li> </ul> -<p> <h2> 7. Acknowledgments </h2> -<p> <h2> 8. Bibliography / Referenced Documents </h2> @@ -125,20 +507,31 @@ Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters "6. C <p> Drepper, Ulrich, Numerous, late-night email correspondence +</p> <p> ISO/IEC 14882:1998 Programming languages - C++ +</p> <p> ISO/IEC 9899:1999 Programming languages - C +</p> <p> Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000 +</p> <p> Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000 +</p> <p> System Interface Definitions, Issue 6 (IEEE Std. 1003.1-200x) The Open Group/The Institute of Electrical and Electronics Engineers, Inc. http://www.opennc.org/austin/docreg.html +</p> + +</body> +</html> + + diff --git a/libstdc++-v3/docs/html/22_locale/messages.html b/libstdc++-v3/docs/html/22_locale/messages.html index 371371fa63f..7497590bd88 100644 --- a/libstdc++-v3/docs/html/22_locale/messages.html +++ b/libstdc++-v3/docs/html/22_locale/messages.html @@ -1,14 +1,20 @@ <html> <head> - <h1> - Notes on the messages implementation. - </h1> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> + <meta name="AUTHOR" content="bkoz@redhat.com (Benjamin Kosnik)" /> + <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" /> + <meta name="DESCRIPTION" content="Notes on the messages implementation." /> + <title>Notes on the messages implementation.</title> +<link rel="StyleSheet" href="../lib3styles.css" /> </head> -<I> +<body> +<h1> +Notes on the messages implementation. +</h1> +<em> prepared by Benjamin Kosnik (bkoz@redhat.com) on August 8, 2001 -</I> +</em> -<p> <h2> 1. Abstract </h2> @@ -18,7 +24,6 @@ equivalent to Java's java.text.MessageFormat .using either GNU gettext or IEEE 1003.1-200 functions. </p> -<p> <h2> 2. What the standard says </h2> @@ -29,9 +34,9 @@ locale to the other. For instance, converting the "C" locale's <code>const char* c = "please"</code> to a German-localized <code>"bitte"</code> during program execution. -<BLOCKQUOTE> +<blockquote> 22.2.7.1 - Template class messages [lib.locale.messages] -</BLOCKQUOTE> +</blockquote> This class has three public member functions, which directly correspond to three protected virtual member functions. @@ -39,52 +44,58 @@ correspond to three protected virtual member functions. The public member functions are: <p> -<code>catalog open(const string&, const locale&) const</code> +<code>catalog open(const string&, const locale&) const</code> +</p> <p> -<code>string_type get(catalog, int, int, const string_type&) const</code> +<code>string_type get(catalog, int, int, const string_type&) const</code> +</p> <p> <code>void close(catalog) const</code> +</p> <p> While the virtual functions are: +</p> <p> -<code>catalog do_open(const string&, const locale&) const</code> -<BLOCKQUOTE> -<I> +<code>catalog do_open(const string&, const locale&) const</code> +</p> +<blockquote> +<em> -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. -</I> -</BLOCKQUOTE> +</em> +</blockquote> <p> -<code>string_type do_get(catalog, int, int, const string_type&) const</code> -<BLOCKQUOTE> -<I> +<code>string_type do_get(catalog, int, int, const string_type&) const</code> +</p> +<blockquote> +<em> -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. -</I> -</BLOCKQUOTE> +</em> +</blockquote> <p> <code>void do_close(catalog) const</code> -<BLOCKQUOTE> -<I> +</p> +<blockquote> +<em> -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. -</I> -</BLOCKQUOTE> +</em> +</blockquote> -<p> <h2> 3. Problems with "C" messages: thread safety, over-specification, and assumptions. @@ -96,37 +107,41 @@ First, why is <code>messages_base::catalog</code> specified as a typedef to int? This makes sense for implementations that use <code>catopen</code>, but not for others. Fortunately, it's not heavily used and so only a minor irritant. +</p> <p> Second, by making the member functions <code>const</code>, 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. +</p> <p> The 'open' member function in particular seems to be oddly designed. The signature seems quite peculiar. Why specify a <code>const -string& </code> argument, for instance, instead of just <code>const -char*</code>? Or, why specify a <code>const locale&</code> argument that is +string& </code> argument, for instance, instead of just <code>const +char*</code>? Or, why specify a <code>const locale&</code> 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. +</p> <p> 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. +</p> <p> 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. +</p> -<p> <h2> 4. Design and Implementation Details </h2> @@ -140,35 +155,39 @@ dependent on the capabilities of the underlying operating system. <p> Three different mechanisms have been provided, selectable via configure flags: +</p> <ul> - <li> generic - <p> - This model does very little, and is what is used by default. - </p> - - <li> gnu - <p> - 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 - <code>textdomain, bindtextdomain, gettext</code> - 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. - </p> - - <li> ieee_1003.1-200x - <p> - This is a complete, though untested, implementation based on - the IEEE standard. The functions - <code>catopen, catgets, catclose</code> - are used to retrieve locale-specific messages given the - appropriate message catalogs that have been constructed for - their use. Note, the script <code> po2msg.sed</code> that is part - of the gettext distribution can convert gettext catalogs into - catalogs that <code>catopen</code> can use. - </p> + <li> generic + <p> + This model does very little, and is what is used by default. + </p> + </li> + + <li> gnu + <p> + 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 + <code>textdomain, bindtextdomain, gettext</code> + 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. + </p> + </li> + + <li> ieee_1003.1-200x + <p> + This is a complete, though untested, implementation based on + the IEEE standard. The functions + <code>catopen, catgets, catclose</code> + are used to retrieve locale-specific messages given the + appropriate message catalogs that have been constructed for + their use. Note, the script <code> po2msg.sed</code> that is part + of the gettext distribution can convert gettext catalogs into + catalogs that <code>catopen</code> can use. + </p> + </li> </ul> <p> @@ -176,9 +195,11 @@ 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. +</p> <p> The rest of this document discusses details of the GNU model. +</p> <p> The messages facet, because it is retrieving and converting between @@ -188,165 +209,182 @@ necessary for more than just the <code>LC_MESSAGES</code> mask: <code>LC_CTYPE</code> is also necessary. To avoid any unpleasantness, all bits of the "C" mask (ie <code>LC_ALL</code>) are set before retrieving messages. +</p> <p> 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: +</p> <ul> - <LI > Make a source file with the required string literals - that need to be translated. See - <code>intl/string_literals.cc</code> for an example. - - <p> - <li> Make initial catalog (see "4 Making the PO Template File" - from the gettext docs). - <p> - <code> xgettext --c++ --debug string_literals.cc -o libstdc++.pot </code> - - <p> - <li> Make language and country-specific locale catalogs. - <p> - <code>cp libstdc++.pot fr_FR.po</code> - <p> - <code>cp libstdc++.pot de_DE.po</code> - - <p> - <li> Edit localized catalogs in emacs so that strings are - translated. - <p> - <code>emacs fr_FR.po</code> - - <p> - <li> Make the binary mo files. - <p> - <code>msgfmt fr_FR.po -o fr_FR.mo</code> - <p> - <code>msgfmt de_DE.po -o de_DE.mo</code> - - <p> - <li> Copy the binary files into the correct directory structure. - <p> - <code>cp fr_FR.mo (dir)/fr_FR/LC_MESSAGES/libstdc++-v3.mo</code> - <p> - <code>cp de_DE.mo (dir)/de_DE/LC_MESSAGES/libstdc++-v3.mo</code> - - <p> - <li> Use the new message catalogs. - <p> - <code>locale loc_de("de_DE");</code> - <p> - <code> - use_facet<messages<char> >(loc_de).open("libstdc++", locale(), dir); - </code> + <li> Make a source file with the required string literals + that need to be translated. See + <code>intl/string_literals.cc</code> for an example. + </li> + + <li> Make initial catalog (see "4 Making the PO Template File" + from the gettext docs). + <p> + <code> xgettext --c++ --debug string_literals.cc -o libstdc++.pot </code> + </p> + </li> + + <li> Make language and country-specific locale catalogs. + <p> + <code>cp libstdc++.pot fr_FR.po</code> + </p> + <p> + <code>cp libstdc++.pot de_DE.po</code> + </p> + </li> + + <li> Edit localized catalogs in emacs so that strings are + translated. + <p> + <code>emacs fr_FR.po</code> + </p> + </li> + + <li> Make the binary mo files. + <p> + <code>msgfmt fr_FR.po -o fr_FR.mo</code> + </p> + <p> + <code>msgfmt de_DE.po -o de_DE.mo</code> + </p> + </li> + + <li> Copy the binary files into the correct directory structure. + <p> + <code>cp fr_FR.mo (dir)/fr_FR/LC_MESSAGES/libstdc++-v3.mo</code> + </p> + <p> + <code>cp de_DE.mo (dir)/de_DE/LC_MESSAGES/libstdc++-v3.mo</code> + </p> + </li> + + <li> Use the new message catalogs. + <p> + <code>locale loc_de("de_DE");</code> + </p> + <p> + <code> + use_facet<messages<char> >(loc_de).open("libstdc++", locale(), dir); + </code> + </p> + </li> </ul> -<p> <h2> 5. Examples </h2> <ul> - <li> message converting, simple example using the GNU model. + <li> message converting, simple example using the GNU model. <pre> -#include <iostream> -#include <locale> +#include <iostream> +#include <locale> using namespace std; void test01() { - typedef messages<char>::catalog catalog; + typedef messages<char>::catalog catalog; const char* dir = "/mnt/egcs/build/i686-pc-linux-gnu/libstdc++-v3/po/share/locale"; const locale loc_de("de_DE"); - const messages<char>& mssg_de = use_facet<messages<char> >(loc_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'; + cout << "please in german:" << s01 << '\n'; + cout << "thank you in german:" << s02 << '\n'; mssg_de.close(cat_de); } </pre> + </li> </ul> More information can be found in the following testcases: <ul> -<li> testsuite/22_locale/messages.cc -<li> testsuite/22_locale/messages_byname.cc -<li> testsuite/22_locale/messages_char_members.cc +<li> testsuite/22_locale/messages.cc </li> +<li> testsuite/22_locale/messages_byname.cc </li> +<li> testsuite/22_locale/messages_char_members.cc </li> </ul> -<p> <h2> 6. Unresolved Issues </h2> <ul> -<li> Things that are sketchy, or remain unimplemented: - <ul> - <li>_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). - - <li> 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, ie glibc 2.3.x will - fix this, and the C++ library bits are already in - place. - </ul> - -<p> -<li> 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. -<p> +<li> Things that are sketchy, or remain unimplemented: + <ul> + <li>_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). + </li> + + <li> 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, ie glibc 2.3.x will + fix this, and the C++ library bits are already in + place. + </li> + </ul> +</li> + +<li> 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. +</li> <li> At some point in the near future, std::numpunct will probably use - std::messages facilities to implement truename/falename - 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. - -<p> -<li> The following member functions: - - <p> - <code> + std::messages facilities to implement truename/falename + 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. +</li> + +<li> The following member functions: + + <p> + <code> catalog - open(const basic_string<char>& __s, const locale& __loc) const - </code> - - <p> - <code> - catalog - open(const basic_string<char>&, const locale&, const char*) const; - </code> - - <p> - 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. + open(const basic_string<char>& __s, const locale& __loc) const + </code> + </p> + + <p> + <code> + catalog + open(const basic_string<char>&, const locale&, const char*) const; + </code> + </p> + + <p> + 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. + </p> +</li> </ul> -<p> <h2> 7. Acknowledgments </h2> @@ -354,7 +392,6 @@ Ulrich Drepper for the character set explanations, gettext details, and patient answering of late-night questions, Tom Tromey for the java details. -<p> <h2> 8. Bibliography / Referenced Documents </h2> @@ -366,36 +403,49 @@ Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters Drepper, Ulrich, Thread-Aware Locale Model, A proposal. This is a draft document describing the design of glibc 2.3 MT locale functionality. +</p> <p> Drepper, Ulrich, Numerous, late-night email correspondence +</p> <p> ISO/IEC 9899:1999 Programming languages - C +</p> <p> ISO/IEC 14882:1998 Programming languages - C++ +</p> <p> Java 2 Platform, Standard Edition, v 1.3.1 API Specification. In particular, java.util.Properties, java.text.MessageFormat, java.util.Locale, java.util.ResourceBundle. http://java.sun.com/j2se/1.3/docs/api +</p> <p> System Interface Definitions, Issue 7 (IEEE Std. 1003.1-200x) The Open Group/The Institute of Electrical and Electronics Engineers, Inc. In particular see lines 5268-5427. http://www.opennc.org/austin/docreg.html +</p> <p> GNU gettext tools, version 0.10.38, Native Language Support Library and Tools. http://sources.redhat.com/gettext +</p> <p> Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000. See page 725, Internationalized Messages. +</p> <p> Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000 +</p> + +</body> +</html> + diff --git a/libstdc++-v3/docs/html/23_containers/howto.html b/libstdc++-v3/docs/html/23_containers/howto.html index 101b636dd22..1c1e137b67c 100644 --- a/libstdc++-v3/docs/html/23_containers/howto.html +++ b/libstdc++-v3/docs/html/23_containers/howto.html @@ -1,13 +1,12 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> <html> <head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> - <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> - <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 23."> - <meta name="GENERATOR" content="vi and eight fingers"> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> + <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> + <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" /> + <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 23." /> + <meta name="GENERATOR" content="vi and eight fingers" /> <title>libstdc++-v3 HOWTO: Chapter 23</title> -<link rel="StyleSheet" href="../lib3styles.css"> +<link rel="StyleSheet" href="../lib3styles.css" /> </head> <body> @@ -18,18 +17,19 @@ <!-- ####################################################### --> -<hr> +<hr /> <h1>Contents</h1> <ul> - <li><a href="#1">Making code unaware of the container/array difference</a> - <li><a href="#2">Variable-sized bitmasks</a> - <li><a href="#3">Containers and multithreading</a> - <li><a href="#4">"Hinting" during insertion</a> - <li><a href="#5">Bitmasks and string arguments</a> - <li><a href="#6"><code>std::list::size()</code> is O(n)!</a> + <li><a href="#1">Making code unaware of the container/array difference</a></li> + <li><a href="#2">Variable-sized bitmasks</a></li> + <li><a href="#3">Containers and multithreading</a></li> + <li><a href="#4">"Hinting" during insertion</a></li> + <li><a href="#5">Bitmasks and string arguments</a></li> + <li><a href="#6"><code>std::list::size()</code> is O(n)!</a></li> + <li><a href="#7">Space overhead management for vectors</a></li> </ul> -<hr> +<hr /> <!-- ####################################################### --> @@ -64,9 +64,10 @@ code size or execution time. </p> <p>The result is that if all your algorithm calls look like - <pre> + </p> + <pre> std::transform(beginof(foo), endof(foo), beginof(foo), SomeFunction);</pre> - then the type of foo can change from an array of ints to a vector + <p>then the type of foo can change from an array of ints to a vector of ints to a deque of ints and back again, without ever changing any client code. </p> @@ -85,19 +86,21 @@ give the extra three lines and avoid confusion. </p> <p>Second, the line - <pre> + </p> + <pre> inline unsigned int lengthof (T (&)[sz]) { return sz; } </pre> - looks just weird! Hint: unused parameters can be left nameless. + <p>looks just weird! Hint: unused parameters can be left nameless. </p> <p>Return <a href="#top">to top of page</a> or <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="2">Variable-sized bitmasks</a></h2> <p>No, you cannot write code of the form + </p> <!-- Careful, the leading spaces in PRE show up directly. --> - <pre> + <pre> #include <bitset> void foo (size_t n) @@ -105,19 +108,19 @@ std::bitset<n> bits; .... } </pre> - because <code>n</code> must be known at compile time. Your compiler is + <p>because <code>n</code> must be known at compile time. Your compiler is correct; it is not a bug. That's the way templates work. (Yes, it <em>is</em> a feature.) </p> <p>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: + </p> <ul> - <li>A very large N in <code>bitset<N></code>. - <li>A container<bool>. - <li>Extremely weird solutions. + <li>A very large N in <code>bitset<N></code>.</li> + <li>A container<bool>.</li> + <li>Extremely weird solutions.</li> </ul> - </p> <p><strong>A very large N in <code>bitset<N></code>. </strong> It has been pointed out a few times in newsgroups that N bits only takes up @@ -191,7 +194,7 @@ <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="3">Containers and multithreading</a></h2> <p>This section discusses issues surrounding the design of multithreaded applications which use Standard C++ containers. @@ -203,14 +206,14 @@ multithreading as it relates to libstdc++, including details on the proper compilation of threaded code (and compatibility between threaded and non-threaded code), see Chapter 17. - </p> + </p> <p>Two excellent pages to read when working with the Standard C++ containers and threads are <a href="http://www.sgi.com/tech/stl/thread_safety.html">SGI's http://www.sgi.com/tech/stl/thread_safety.html</a> and <a href="http://www.sgi.com/tech/stl/Allocators.html">SGI's http://www.sgi.com/tech/stl/Allocators.html</a>. - </p> + </p> <p><em>However, please ignore all discussions about the user-level configuration of the lock implementation inside the STL container-memory allocator on those pages. For the sake of this @@ -222,7 +225,7 @@ STL. This is no longer required for any port and should no longer be done unless you really know what you are doing and assume all responsibility.</em> - </p> + </p> <p>Since the container implementation of libstdc++-v3 uses the SGI code, we use the same definition of thread safety as SGI when discussing design. A key point that beginners may miss is the @@ -234,7 +237,7 @@ element is constructed uses an internal lock obtained and released solely within libstdc++-v3 code (in fact, this is the reason STL requires any knowledge of the thread configuration). - </p> + </p> <p>For implementing a container which does its own locking, it is trivial to provide a wrapper class which obtains the lock (as SGI suggests), performs the container operation, and then @@ -248,7 +251,8 @@ you must change this on a global basis for your platform to better support multi-threading, then please consult all commentary in include/bits/stl_alloc.h and the allocators link below. - <blockquote> + </p> + <blockquote> <p>(Explicit warning since so many people get confused while attempting this:) </p> @@ -270,8 +274,8 @@ one-definition rule of C/C++ and you might cause yourself untold problems. </p> - </blockquote> - If you find any platform where gcc reports a + </blockquote> + <p>If you find any platform where gcc reports a threading model other than single, and where libstdc++-v3 builds a buggy container allocator when used with threads unless you define __USE_MALLOC, we want to hear about it ASAP. In the @@ -289,13 +293,14 @@ <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="4">"Hinting" during insertion</a></h2> <p>Section [23.1.2], Table 69, of the C++ standard lists this function for all of the associative containers (map, set, etc): - <pre> + </p> + <pre> a.insert(p,t);</pre> - where 'p' is an iterator into the container 'a', and 't' is the item + <p>where 'p' is an iterator into the container 'a', and 't' is the item to insert. The standard says that "iterator p is a hint pointing to where the insert should start to search," but specifies nothing more. (LWG Issue #233, currently in review, @@ -320,23 +325,26 @@ their new meanings in the next paragraph. *grin* </p> <p>If the <code>hint</code> parameter ('p' above) is equivalent to: + </p> <ul> <li><code>begin()</code>, then the item being inserted should have a key less than all the other keys in the container. The item will be inserted at the beginning of the container, becoming the new entry at <code>begin()</code>. + </li> <li><code>end()</code>, 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 at <code>end()</code>. + </li> <li>neither <code>begin()</code> nor <code>end()</code>, then: Let <code>h</code> be the entry in the container pointed to by <code>hint</code>, that is, <code>h = *hint</code>. Then the item being inserted should have a key less than that of <code>h</code>, and greater than that of the item preceding <code>h</code>. The new item will be inserted between <code>h</code> and <code>h</code>'s predecessor. + </li> </ul> - </p> <p>For <code>multimap</code> and <code>multiset</code>, the restrictions are slightly looser: "greater than" should be replaced by "not less than" and "less than" should be replaced @@ -371,7 +379,7 @@ <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="5">Bitmasks and string arguments</a></h2> <p>Bitmasks do not take char* nor const char* arguments in their constructors. This is something of an accident, but you can read @@ -382,6 +390,7 @@ </p> <p>For now you can simply make a temporary string object using the constructor expression: + </p> <pre> std::bitset<5> b ( std::string("10110") ); </pre> @@ -389,17 +398,17 @@ <pre> std::bitset<5> b ( "10110" ); // invalid </pre> - </p> <p>Return <a href="#top">to top of page</a> or <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="6"><code>std::list::size()</code> is O(n)!</a></h2> <p>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 <a href="http://www.sgi.com/tech/stl/FAQ.html">their FAQ</a>: - <blockquote> + </p> + <blockquote> <p>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 @@ -418,6 +427,7 @@ is supposed to do something unless there is a good reason not to. </p> <p>One implication of linear time size(): you should never write + </p> <pre> if (L.size() == 0) ...</pre> @@ -425,8 +435,27 @@ <pre> if (L.empty()) ...</pre> - </p> - </blockquote> + </blockquote> + <p>Return <a href="#top">to top of page</a> or + <a href="../faq/index.html">to the FAQ</a>. + </p> + +<hr /> +<h2><a name="7">Space overhead management for vectors</a></h2> + <p>In + <a href="http://gcc.gnu.org/ml/libstdc++/2002-04/msg00105.html">this + message to the list</a>, Daniel Kostecky announced work on an + alternate form of <code>std::vector</code> that would support hints + on the number of elements to be over-allocated. The design was also + described, along with possible implementation choices. + </p> + <p>The first two alpha releases were announced + <a href="http://gcc.gnu.org/ml/libstdc++/2002-07/msg00048.html">here</a> + and + <a href="http://gcc.gnu.org/ml/libstdc++/2002-07/msg00111.html">here</a>. + The releases themselves are available at + <a href="http://www.kotelna.sk/dk/sw/caphint/"> + http://www.kotelna.sk/dk/sw/caphint/</a>. </p> <p>Return <a href="#top">to top of page</a> or <a href="../faq/index.html">to the FAQ</a>. @@ -435,7 +464,7 @@ <!-- ####################################################### --> -<hr> +<hr /> <p class="fineprint"><em> See <a href="../17_intro/license.html">license.html</a> for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/24_iterators/howto.html b/libstdc++-v3/docs/html/24_iterators/howto.html index 90c53df18ac..4d48cffdcbd 100644 --- a/libstdc++-v3/docs/html/24_iterators/howto.html +++ b/libstdc++-v3/docs/html/24_iterators/howto.html @@ -1,13 +1,12 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> <html> <head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> - <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> - <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 24."> - <meta name="GENERATOR" content="vi and eight fingers"> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> + <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> + <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" /> + <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 24." /> + <meta name="GENERATOR" content="vi and eight fingers" /> <title>libstdc++-v3 HOWTO: Chapter 24</title> -<link rel="StyleSheet" href="../lib3styles.css"> +<link rel="StyleSheet" href="../lib3styles.css" /> </head> <body> @@ -19,14 +18,14 @@ <!-- ####################################################### --> -<hr> +<hr /> <h1>Contents</h1> <ul> - <li><a href="#1">They ain't pointers!</a> - <li><a href="#2">It ends <em>where?</em></a> + <li><a href="#1">They ain't pointers!</a></li> + <li><a href="#2">It ends <em>where?</em></a></li> </ul> -<hr> +<hr /> <!-- ####################################################### --> @@ -67,41 +66,46 @@ <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="2">It ends <em>where?</em></a></h2> <p>This starts off sounding complicated, but is actually very easy, especially towards the end. Trust me. - </p> + </p> <p>Beginners usually have a little trouble understand the whole 'past-the-end' thing, until they remember their early algebra classes - (see, they </em>told</em> you that stuff would come in handy!) and + (see, they <em>told</em> you that stuff would come in handy!) and the concept of half-open ranges. </p> <p>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: - <ol> - <li>You can point anywhere in the array, <em>or to the first element - past the end of the array</em>. 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. - <li>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. - <li>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. - </ol> - The reason this past-the-end addressing was allowed is to make it + </p> + <ol> + <li>You can point anywhere in the array, <em>or to the first element + past the end of the array</em>. 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. + </li> + <li>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. + </li> + <li>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. + </li> + </ol> + <p>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++);. </p> <p>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 <em>boundary markers</em>: - <pre> + </p> + <pre> beginning end | | @@ -121,8 +125,8 @@ | | dereference 'end'. beginning end - </pre> - See? Everything between the boundary markers is part of the array. + </pre> + <p>See? Everything between the boundary markers is part of the array. Simple. </p> <p>Now think back to your junior-high school algebra course, when you @@ -171,7 +175,7 @@ <!-- ####################################################### --> -<hr> +<hr /> <p class="fineprint"><em> See <a href="../17_intro/license.html">license.html</a> for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/25_algorithms/howto.html b/libstdc++-v3/docs/html/25_algorithms/howto.html index 8cdfe94a471..65403ca8159 100644 --- a/libstdc++-v3/docs/html/25_algorithms/howto.html +++ b/libstdc++-v3/docs/html/25_algorithms/howto.html @@ -1,13 +1,12 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> <html> <head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> - <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> - <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 25."> - <meta name="GENERATOR" content="vi and eight fingers"> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> + <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> + <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" /> + <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 25." /> + <meta name="GENERATOR" content="vi and eight fingers" /> <title>libstdc++-v3 HOWTO: Chapter 25</title> -<link rel="StyleSheet" href="../lib3styles.css"> +<link rel="StyleSheet" href="../lib3styles.css" /> </head> <body> @@ -19,14 +18,14 @@ <!-- ####################################################### --> -<hr> +<hr /> <h1>Contents</h1> <ul> - <li><a href="#1">Prerequisites</a> - <li><a href="#2">Special <code>swap</code>s</a> + <li><a href="#1">Prerequisites</a></li> + <li><a href="#2">Special <code>swap</code>s</a></li> </ul> -<hr> +<hr /> <!-- ####################################################### --> @@ -34,16 +33,18 @@ <p>The neatest accomplishment of the algorithms chapter is that all the work is done via iterators, not containers directly. This means two important things: - <ol> - <li>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. - <li>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. - </ol> </p> + <ol> + <li>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. + </li> + <li>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. + </li> + </ol> <p>Even strings can be fed through the algorithms here, although the string class has specialized versions of many of these functions (for example, <code>string::find()</code>). Most of the examples on this @@ -67,7 +68,7 @@ <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="2">Special <code>swap</code>s</a></h2> <p>If you call <code> std::swap(x,y); </code> where x and y are standard containers, then the call will automatically be replaced by a call to @@ -90,7 +91,7 @@ <!-- ####################################################### --> -<hr> +<hr /> <p class="fineprint"><em> See <a href="../17_intro/license.html">license.html</a> for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/26_numerics/howto.html b/libstdc++-v3/docs/html/26_numerics/howto.html index e15870f57bf..067f59dd0fd 100644 --- a/libstdc++-v3/docs/html/26_numerics/howto.html +++ b/libstdc++-v3/docs/html/26_numerics/howto.html @@ -1,13 +1,12 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> <html> <head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> - <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> - <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 26."> - <meta name="GENERATOR" content="vi and eight fingers"> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> + <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> + <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" /> + <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 26." /> + <meta name="GENERATOR" content="vi and eight fingers" /> <title>libstdc++-v3 HOWTO: Chapter 26</title> -<link rel="StyleSheet" href="../lib3styles.css"> +<link rel="StyleSheet" href="../lib3styles.css" /> </head> <body> @@ -15,29 +14,32 @@ <p>Chapter 26 deals with building block abstractions to aid in numerical computing: - <ul> - <li>Template data structures such as <code>valarray<></code> - and <code>complex<></code>. - <li>Template numerical functions such as <code>accumulate</code>, - <code>inner_product</code>, <code>partial_sum</code>, and - <code>adjacent_difference</code>. - </ul> - All of the Standard C math functions are of course included in C++, +</p> +<ul> + <li>Template data structures such as <code>valarray<></code> + and <code>complex<></code>. + </li> + <li>Template numerical functions such as <code>accumulate</code>, + <code>inner_product</code>, <code>partial_sum</code>, and + <code>adjacent_difference</code>. + </li> +</ul> +<p>All of the Standard C math functions are of course included in C++, and overloaded versions for <code>long</code>, <code>float</code>, and <code>long double</code> have been added for all of them. </p> <!-- ####################################################### --> -<hr> +<hr /> <h1>Contents</h1> <ul> - <li><a href="#1">Complex Number Processing</a> - <li><a href="#2">Array Processing</a> - <li><a href="#3">Numerical Functions</a> - <li><a href="#4">C99</a> + <li><a href="#1">Complex Number Processing</a></li> + <li><a href="#2">Array Processing</a></li> + <li><a href="#3">Numerical Functions</a></li> + <li><a href="#4">C99</a></li> </ul> -<hr> +<hr /> <!-- ####################################################### --> @@ -62,7 +64,7 @@ <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="2">Array Processing</a></h2> <p>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 @@ -87,22 +89,23 @@ <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="3">Numerical Functions</a></h2> <p>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: - <ul> - <li><code>accumulate</code> - <li><code>inner_product</code> - <li><code>partial_sum</code> - <li><code>adjacent_difference</code> - </ul> </p> + <ul> + <li><code>accumulate</code></li> + <li><code>inner_product</code></li> + <li><code>partial_sum</code></li> + <li><code>adjacent_difference</code></li> + </ul> <p>Here is a simple example of the two forms of <code>accumulate</code>. - <pre> + </p> + <pre> int ar[50]; int someval = somefunction(); @@ -111,8 +114,8 @@ int sum = std::accumulate(ar,ar+50,0); int sum_stuff = std::accumulate(ar,ar+50,someval); int product = std::accumulate(ar,ar+50,1,std::multiplies<int>()); - </pre> - The first call adds all the members of the array, using zero as an + </pre> + <p>The first call adds all the members of the array, using zero as an initial value for <code>sum</code>. The second does the same, but uses <code>someval</code> as the starting value (thus, <code>sum_stuff == sum + someval</code>). The final call uses the second of the two signatures, @@ -125,7 +128,7 @@ <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="4">C99</a></h2> <p>In addition to the other topics on this page, we'll note here some of the C99 features that appear in libstdc++-v3. @@ -151,7 +154,7 @@ <!-- ####################################################### --> -<hr> +<hr /> <p class="fineprint"><em> See <a href="../17_intro/license.html">license.html</a> for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/27_io/howto.html b/libstdc++-v3/docs/html/27_io/howto.html index 6e07310dff1..94b0e015fba 100644 --- a/libstdc++-v3/docs/html/27_io/howto.html +++ b/libstdc++-v3/docs/html/27_io/howto.html @@ -1,13 +1,12 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> <html> <head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> - <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> - <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 27."> - <meta name="GENERATOR" content="vi and eight fingers"> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> + <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> + <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" /> + <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 27." /> + <meta name="GENERATOR" content="vi and eight fingers" /> <title>libstdc++-v3 HOWTO: Chapter 27</title> -<link rel="StyleSheet" href="../lib3styles.css"> +<link rel="StyleSheet" href="../lib3styles.css" /> </head> <body> @@ -19,20 +18,20 @@ <!-- ####################################################### --> -<hr> +<hr /> <h1>Contents</h1> <ul> - <li><a href="#1">Copying a file</a> - <li><a href="#2">The buffering is screwing up my program!</a> - <li><a href="#3">Binary I/O</a> - <li><a href="#5">What is this <sstream>/stringstreams thing?</a> - <li><a href="#6">Deriving a stream buffer</a> - <li><a href="#7">More on binary I/O</a> - <li><a href="#8">Pathetic performance? Ditch C.</a> - <li><a href="#9">Threads and I/O</a> + <li><a href="#1">Copying a file</a></li> + <li><a href="#2">The buffering is screwing up my program!</a></li> + <li><a href="#3">Binary I/O</a></li> + <li><a href="#5">What is this <sstream>/stringstreams thing?</a></li> + <li><a href="#6">Deriving a stream buffer</a></li> + <li><a href="#7">More on binary I/O</a></li> + <li><a href="#8">Pathetic performance? Ditch C.</a></li> + <li><a href="#9">Threads and I/O</a></li> </ul> -<hr> +<hr /> <!-- ####################################################### --> @@ -40,27 +39,29 @@ <p>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): - <pre> + </p> + <pre> #include <fstream> std::ifstream IN ("input_file"); std::ofstream OUT ("output_file"); </pre> - </p> <p>Here's the easiest way to get it completely wrong: - <pre> + </p> + <pre> OUT << IN;</pre> - For those of you who don't already know why this doesn't work + <p>For those of you who don't already know why this doesn't work (probably from having done it before), I invite you to quickly create a simple text file called "input_file" containing the sentence + </p> <pre> - The quick brown fox jumped over the lazy dog.</pre> - surrounded by blank lines. Code it up and try it. The contents + The quick brown fox jumped over the lazy dog.</pre> + <p>surrounded by blank lines. Code it up and try it. The contents of "output_file" may surprise you. </p> <p>Seriously, go do it. Get surprised, then come back. It's worth it. </p> - <hr width="60%"> + <hr width="60%" /> <p>The thing to remember is that the <code>basic_[io]stream</code> classes handle formatting, nothing else. In particular, they break up on whitespace. The actual reading, writing, and storing of data is @@ -76,9 +77,9 @@ as well as the streams themselves. The pointer is easily retrieved using the <code>rdbuf()</code> member function. Therefore, the easiest way to copy the file is: - <pre> - OUT << IN.rdbuf();</pre> </p> + <pre> + OUT << IN.rdbuf();</pre> <p>So what <em>was</em> happening with OUT<<IN? Undefined behavior, since that particular << isn't defined by the Standard. I have seen instances where it is implemented, but the character @@ -89,7 +90,7 @@ file then contains a perfect text representation of a hexidecimal address (quite a big surprise). Others don't compile at all. </p> - <p>Also note that none of this is specific to o<B>*f*</B>streams. + <p>Also note that none of this is specific to o<b>*f*</b>streams. The operators shown above are all defined in the parent basic_ostream class and are therefore available with all possible descendents. @@ -98,7 +99,7 @@ <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="2">The buffering is screwing up my program!</a></h2> <!-- This is not written very well. I need to redo this section. @@ -122,35 +123,38 @@ 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: - <pre> + </p> + <pre> output << "a line of text" << endl; output << some_data_variable << endl; output << "another line of text" << endl; </pre> - The proper thing to do in this case to just write the data out + <p>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: - <pre> + </p> + <pre> output << "a line of text\n" << some_data_variable << '\n' << "another line of text\n"; </pre> - I have also joined the output statements into a single statement. + <p>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 thing line, for example. </p> <p>If you do need to flush the buffer above, you can send an <code>endl</code> if you also need a newline, or just flush the buffer yourself: - <pre> + </p> + <pre> output << ...... << flush; // can use std::flush manipulator output.flush(); // or call a member fn </pre> - </p> <p>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 <em>before any I/O operations at all</em> have been done, i.e., as soon as possible after opening: - <pre> + </p> + <pre> std::ofstream os ("/foo/bar/baz"); std::ifstream is ("/qux/quux/quuux"); int i; @@ -160,7 +164,6 @@ ... os << "this data is written immediately\n"; is >> i; // and this will probably cause a disk read </pre> - </p> <p>Since all aspects of buffering are handled by a streambuf-derived member, it is necessary to get at that member with <code>rdbuf()</code>. Then the public version of <code>setbuf</code> can be called. The @@ -189,7 +192,7 @@ <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="3">Binary I/O</a></h2> <p>The first and most important thing to remember about binary I/O is that opening a file with <code>ios::binary</code> is not, repeat @@ -234,25 +237,28 @@ of <em>formatting</em> functions and classes to perform something which <em>requires</em> that formatting not be done? There are a seemingly infinite number of solutions, and a few are listed here: - <ul> - <li>"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. - <li>"Build the file structure in memory, then <code>mmap()</code> - the file and copy the structure." Well, this is easy to - make work, and easy to break, and is pretty equivalent to - using <code>::read()</code> and <code>::write()</code> directly, and - makes no use of the iostream library at all... - <li>"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. - </ul> </p> + <ul> + <li>"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. + </li> + <li>"Build the file structure in memory, then <code>mmap()</code> + the file and copy the structure." Well, this is easy to + make work, and easy to break, and is pretty equivalent to + using <code>::read()</code> and <code>::write()</code> directly, and + makes no use of the iostream library at all... + </li> + <li>"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. + </li> + </ul> <p>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. @@ -287,7 +293,7 @@ made are good ones.) </p> -<hr> +<hr /> <h2><a name="5">What is this <sstream>/stringstreams thing?</a></h2> <p>Stringstreams (defined in the header <code><sstream></code>) are in this author's opinion one of the coolest things since @@ -311,7 +317,7 @@ <p>This only works if you've written your <code><<</code>/<code>>></code> functions correctly, though, and correctly means that they take istreams and ostreams as - parameters, not i<B>f</B>streams and o<B>f</B>streams. If they + parameters, not i<b>f</b>streams and o<b>f</b>streams. If they take the latter, then your I/O operators will work fine with file streams, but with nothing else -- including stringstreams. </p> @@ -324,7 +330,7 @@ support them, and 2) if you use them, people will laugh at you. </p> -<hr> +<hr /> <h2><a name="6">Deriving a stream buffer</a></h2> <p>Creating your own stream buffers for I/O can be remarkably easy. If you are interested in doing so, we highly recommend two very @@ -339,7 +345,8 @@ transforms everything sent through it to uppercase. This version assumes many things about the nature of the character type being used (for more information, read the books or the newsgroups): - <pre> + </p> + <pre> #include <iostream> #include <streambuf> #include <locale> @@ -377,10 +384,11 @@ return 0; } </pre> - Try it yourself! + <p>Try it yourself! More examples can be found in 3.1.x code, in + <code>include/ext/*_filebuf.h</code>. </p> -<hr> +<hr /> <h2><a name="7">More on binary I/O</a></h2> <p>Towards the beginning of February 2001, the subject of "binary" I/O was brought up in a couple of places at the @@ -405,22 +413,23 @@ a portable binary format. </p> -<hr> +<hr /> <h2><a name="8">Pathetic performance? Ditch C.</a></h2> <p>It sounds like a flame on C, but it isn't. Really. Calm down. I'm just saying it to get your attention. </p> <p>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: - <pre> + </p> + <pre> #include <iostream> #include <cstdio> std::cout << "Hel"; std::printf ("lo, worl"); std::cout << "d!\n"; - </pre> - This must do what you think it does. + </pre> + <p>This must do what you think it does. </p> <p>Alert members of the audience will immediately notice that buffering is going to make a hash of the output unless special steps are taken. @@ -432,22 +441,22 @@ The upside is that correctness is ensured. The downside is that writing through <code>cout</code> 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 are in the - works which should improve the situation for 3.1. + library (as it is for 3.0 by default). Some patches have been applied + which improve the situation for 3.1. </p> <p>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 - <pre> + </p> + <pre> #include <em>any of the I/O headers such as ios, iostream, etc</em> std::ios::sync_with_stdio(false); - </pre> - </p> + </pre> <p>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.0, this means that <code>cout</code> and + (unused) C streams. For GCC 3.x, this means that <code>cout</code> and company will become fully buffered on their own. </p> <p>Note, by the way, that the synchronization requirement only applies to @@ -458,7 +467,7 @@ buffered. </p> -<hr> +<hr /> <h2><a name="9">Threads and I/O</a></h2> <p>I'll assume that you have already read the <a href="../17_intro/howto.html#3">general notes on library threads</a>, @@ -547,7 +556,7 @@ <!-- ####################################################### --> -<hr> +<hr /> <p class="fineprint"><em> See <a href="../17_intro/license.html">license.html</a> for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/Makefile b/libstdc++-v3/docs/html/Makefile index df46f74d7a2..efc75bec86f 100644 --- a/libstdc++-v3/docs/html/Makefile +++ b/libstdc++-v3/docs/html/Makefile @@ -1,13 +1,37 @@ +PWD=$${PWDCMD-pwd} MAKEINFO=makeinfo INC=../../../gcc/doc/include -all: faq/index.txt 17_intro/porting.html +all: documentation.html \ + faq/index.txt \ + 17_intro/porting.html \ + 17_intro/porting-howto.html +# chock full of GNUism, probably +documentation.html: $(wildcard */howto.html) + sed -n '1,/beginlist/p' $@ > tmp.top + sed -n '/endlist/,$$p' $@ > tmp.bottom + echo ' <ul>' > tmp.middle + for i in [0-9]*/howto.html; do \ + title=`grep 'h1 ' $$i |\ + sed 's=.*\(Chapter [[:digit:]]*\):[[:space:]]*\(.*\)</a>.*=\2 (\1)='` ;\ + awk -v file=$$i -v "title=$$title" -f makedoc.awk $$i >> tmp.middle ;\ + done + awk -v file=ext/howto.html -v "title=Extensions to the Standard Library"\ + -f makedoc.awk ext/howto.html >> tmp.middle ;\ + echo ' </ul>' >> tmp.middle + cat tmp.top tmp.middle tmp.bottom > $@ + rm tmp.top tmp.middle tmp.bottom faq/index.txt: faq/index.html - lynx -dump $< | sed "s%file://localhost`pwd`%..%" > $@ + lynx -dump $< | sed "s%file://localhost`${PWD}`%..%" > $@ 17_intro/porting.html: 17_intro/porting.texi ${MAKEINFO} -I ${INC} --html --no-split $< -o $@ +# known to work under RH; this can be cleaned up later if needed +17_intro/porting-howto.html: 17_intro/porting-howto.xml + xltproc -o $@ /usr/share/xml/docbook/xsl-stylesheets-1.48-2/html/docbook.xsl $< + +# vim:noet ts=4 diff --git a/libstdc++-v3/docs/html/abi.txt b/libstdc++-v3/docs/html/abi.txt new file mode 100644 index 00000000000..73cb46c9c09 --- /dev/null +++ b/libstdc++-v3/docs/html/abi.txt @@ -0,0 +1,389 @@ + +2002-10-14 Benjamin Kosnik + +Description of the libstdc++ ABI. + +I. What is an ABI? What's covered? What's not? + +- scope of document, of use to system integrators. + +- What's the deal with C++? Why can't different compiler's object + files link with each other? Bug? Feature? + +- compilation includes and linked library binary must match up.. + +- shared library only, static is immutable. + +- What's an ABI? + +- library ABI, compiler ABI different issues, (but related) + +- GNU C++ does not have a compiler command line option to switch + between various different C++ ABIs. For instance, there is no way to + switch between the gcc-3.0.x ABI, gcc-3.1.x ABI, and the gcc-3.2.x + ABI during compilation. Other C++ compilers do allow this, and some + g++ command line options may change the ABI (-fno-exceptions, see + the complete list), but there is no version switch. Sorry. + + To use a specific C++ABI, one must use the corresponding GNU C++ + toolchain. + +- How can this complexity be managed? What does C++ versioning mean? + Because library and compiler changes often make binaries compiled + with one version of the GNU tools incompatible with binaries + compiled with other (either newer or older) versions of the same GNU + tools, specific techniques are used to make managing this complexity + easier. + + The following techniques are used: + + - Release versioning on the libgcc_s.so binary. + + It is versioned as follows: + gcc-3.0.0: libgcc_s.so.1 + gcc-3.0.1: libgcc_s.so.1 + gcc-3.0.2: libgcc_s.so.1 + gcc-3.0.3: libgcc_s.so.1 + gcc-3.0.4: libgcc_s.so.1 + gcc-3.1.0: libgcc_s.so.1 + gcc-3.1.1: libgcc_s.so.1 + gcc-3.2.0: libgcc_s.so.1 + + + - Release versioning on the libstdc++.so binary. + + It is versioned as follows: + gcc-3.0.0: libstdc++.so.3.0.0 + gcc-3.0.1: libstdc++.so.3.0.1 + gcc-3.0.2: libstdc++.so.3.0.2 + gcc-3.0.3: libstdc++.so.3.0.2 (Error, should be libstdc++.so.3.0.3) + gcc-3.0.4: libstdc++.so.3.0.4 + gcc-3.1.0: libstdc++.so.4.0.0 + gcc-3.1.1: libstdc++.so.4.0.1 + gcc-3.2.0: libstdc++.so.5.0.0 + + + - Symbol versioning on the libgcc_s.so binary. + + file: gcc/libgcc-std.ver + + It is versioned as follows: + gcc-3.0.0: GCC_3.0 + gcc-3.0.1: GCC_3.0 + gcc-3.0.2: GCC_3.0 + gcc-3.0.3: GCC_3.0 + gcc-3.0.4: GCC_3.0 + gcc-3.1.0: GCC_3.0 + gcc-3.1.1: GCC_3.0 + gcc-3.2.0: GCC_3.0 + + + - Symbol versioning on the libstdc++.so binary. + + It is versioned as follows: + gcc-3.0.0: (Error, unversioned) + gcc-3.0.1: (Error, unversioned) + gcc-3.0.2: (Error, unversioned) + gcc-3.0.3: (Error, unversioned) + gcc-3.0.4: (Error, unversioned) + gcc-3.1.0: GLIBCPP_3.1, CXXABI_1 + gcc-3.1.1: GLIBCPP_3.1, CXXABI_1 + gcc-3.2.0: GLIBCPP_3.2, CXXABI_1.2 + + file: libstdc++-v3/config/linker-map.gnu + + + - Incremental bumping of a compiler pre-defined macro, + __GXX_ABI_VERSION. This macro is defined as the version of the + compiler v3 ABI, with g++ 3.0.x being version 100. This macro will + be automatically defined whenever g++ is used (the curious can + test this by invoking g++ with the '-v' flag.) + + This macro is defined in the file "lang-specs.h" in the gcc/cp directory. + Later versions define it in "c-common.c" in the gcc directory. + + It is versioned as follows: + gcc-3.0.x: 100 + gcc-3.1.x: 100 (Error, should be 101) + gcc-3.2.x: 102 + + + - Incremental bumping of a library pre-defined macro, + __GLIBCPP__. This macro is defined as the date the library was + released, in compressed ISO date format, as an unsigned long. + + This macro is defined in the file "c++config" in the + "libstdc++-v3/include/bits" directory and is changed every night + by an automated script. + + It is versioned as follows: + gcc-3.0.0: 20010615 + gcc-3.0.1: 20010819 + gcc-3.0.2: 20011023 + gcc-3.0.3: 20011220 + gcc-3.0.4: 20020220 + gcc-3.1.0: 20020514 + gcc-3.1.1: 20020725 + gcc-3.2.0: 20020814 + + + - Incremental bumping of a library pre-defined macro, + _GLIBCPP_VERSION. This macro is defined as the released version of + the library, as a string literal. This is only implemented in + gcc-3.1.0 releases and higher. + + This macro is defined in the file "c++config" in the + "libstdc++-v3/include/bits" directory and is generated + automatically by autoconf as part of the configure-time generation + of config.h. + + It is versioned as follows: + gcc-3.0.0: "3.0.0" + gcc-3.0.1: "3.0.0" (Error, should be "3.0.1") + gcc-3.0.2: "3.0.0" (Error, should be "3.0.2") + gcc-3.0.3: "3.0.0" (Error, should be "3.0.3") + gcc-3.0.4: "3.0.0" (Error, should be "3.0.4") + gcc-3.1.0: "3.1.0" + gcc-3.1.1: "3.1.1" + gcc-3.2.0: "3.2" + + + - Matching each specific C++ compiler release to a specific set of + C++ include files. This is only implemented in gcc-3.1.1 releases + and higher. + + All C++ includes are installed in include/c++, then nest in a + directory hierarchy corresponding to the C++ compiler's released + version. This version corresponds to the variable "gcc_version" in + "libstdc++-v3/acinclude.m4," and more details can be found in that + file's macro GLIBCPP_CONFIGURE. + + C++ includes are versioned as follows: + gcc-3.0.0: include/g++-v3 + gcc-3.0.1: include/g++-v3 + gcc-3.0.2: include/g++-v3 + gcc-3.0.3: include/g++-v3 + gcc-3.0.4: include/g++-v3 + gcc-3.1.0: include/g++-v3 + gcc-3.1.1: include/c++/3.1.1 + gcc-3.2.0: include/c++/3.2 + + Taken together, these techniques can accurately specify interface + and implementation changes in the GNU C++ tools themselves. Used + properly, they allow both the GNU C++ tools implementation, and + programs using them, an evolving yet controlled development that + maintains backward compatibility. + +- Minimum environment that supports a versioned ABI: what's needed? A + supported dynamic linker, a GNU linker of sufficient vintage to + understand demangled C++ name globbing (ld), a shared executable + compiled with g++, and shared libraries (libgcc_s, libstdc++-v3) + compiled by a compiler (g++) with a compatible ABI. Phew. + + On top of all that, an additional constraint: libstdc++ did not + attempt to version symbols (or age gracefully, really) until version + 3.1.0. + + Most modern Linux and BSD versions, particularly ones using + gcc-3.1.x tools, will meet the requirements above. + +- What configure options impact symbol versioning? + + It turns out that most of the configure options that change default + behavior will impact the mangled names of exported symbols, and thus + impact versioning and compatibility. + + For more information on configure options, including ABI impacts, see: + http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html + + There is one flag that explicitly deals with symbol versioning: + --enable-symvers. + + In particular, libstdc++-v3/acinclude.m4 has a macro called + GLIBCPP_ENABLE_SYMVERS that defaults to yes (or the argument passed + in via --enable-symvers=foo). At that point, the macro attempts to + make sure that all the requirement for symbol versioning are in + place. For more information, please consult acinclude.m4. + +- How can I tell if symbol versioning is, indeed, active? + + When the GNU C++ library is being built with symbol versioning on, + you should see the following at configure time for libstdc++-v3: + + checking versioning on shared library symbols... gnu + + If you don't see this line in the configure output, or if this line + appears but the last word is 'no', then you are out of luck. + + If the compiler is pre-installed, a quick way to test is to compile + the following (or any) simple C++ file: + +#include <iostream> + +int main() +{ std::cout << "hello" << std::endl; return 0; } + +%g++ hello.cc -o hello.out +%nm hello.out + +If you see symbols in the resulting output with "GLIBCPP_3.x" as part +of the name, then the executable is versioned. Here's an example: + + U _ZNSt8ios_base4InitC1Ev@@GLIBCPP_3.1 + + +II. Library ABI changes + +The following will cause the library major version number to +increase, say from "libstdc++.so.3.0.4" to "libstdc++.so.4.0.0". + +- (anything) changing in the gcc/g++ compiler ABI + +- (anything) changing size of an exported symbol + +- (anything) changing alignment of an exported symbol + +- (anything) changing the layout of an exported symbol + +- (anything) changing mangling on an exported symbol + +- (anything) deleting an exported symbol + +- (anything) changing the size, alignment, or layout of types + specified in the C++ standard. These may not necessarily be + instantiated or otherwise exported in the library binary, and + include all the required locale facets, as well as things like + std::basic_streambuf, et al. + +Note: adding an exported symbol, if it's in a new and dependent +interface name, is ok. + +The following will cause the library revision version number to +increase, say from "libstdc++.so.5.0.0" to "libstdc++.so.5.0.1". + +- any release of the gcc toolchain. + + +III. Versioning + +- include files + + - versioning headers with version, why necessary + (need to control member/non-member functions, add delete files) + +- shared library binaries + + - release versions + + - libtool versions + + - when does so version get a bump? what are the options? + + - how is the link map used? + + - in an non-abi breaking minor release, how are symbols added? + removed? + + - in an abi-breaking major release, what happens? symbol fall back + + +IV. Testing ABI changes + +Testing for GNU C++ ABI changes is composed of two distinct areas: +testing the C++ compiler (g++) for compiler changes, and testing the +C++ library (libstdc++) for library changes. + +Testing the C++ compiler ABI can be done various ways. + +One. +Intel ABI checker. More information can be obtained +<a href="http://developer.intel.com/software/products/opensource/">here.</a> + +Two. +The second is yet unreleased, but has been announced on the gcc +mailing list. It is yet unspecified if these tools will be freely +available, and able to be included in a GNU project. Please contact +Mark Mitchell (mark@codesourcery.com) for more details, and current +status. + +Three. +Involves using the vlad.consistency test framework. This has also been +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 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++-v3 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 +good baseline. Currently, this baseline is keyed off of 3.2.0 +binaries, as this was the last time the .so number was incremented. In +addition, all exported names are demangled, and the exported objects +are checked to make sure they are the same size as the same object in +the baseline. + +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. + +Verifying compatible layouts of objects is not even attempted. It +should be possible to use sizeof, alignof, and offsetof to compute +offsets for each structure and type in the standard library, saving to +another datafile. Then, compute this in a similar way for new +binaries, and look for differences. + +Another approach might be to use the -fdump-class-hierarchy flag to +get information. However, currently this approach gives insufficient +data for use in library testing, as class data members, their offsets, +and other detailed data is not displayed with this flag. +(See g++/7470 on how this was used to find bugs.) + +Perhaps there are other C++ ABI checkers. If so, please notify +us. We'd like to know about them! + + +V. Issues not directly addressed, and possible suggestions + +- what to do about multi-ABI systems (nathan scenario)? + + - compatibility libs + + --enable-version-specific-runtime-libs + + - Alexandre Oliva proposal to have extended name attributes, modify ld + + - directory-level versioning + +- wrapping C++ API's in "C" to use the C ABI. + + +V. References + +ABIcheck, a vague idea of checking ABI compatibility +http://abicheck.sourceforge.net/ + +C++ ABI reference +http://www.codesourcery.com/cxx-abi/ + +Intel ABI documentation +"Intel® Compilers for Linux* -Compatibility with the GNU Compilers" +(included in icc 6.0) + +Sun Solaris 2.9 docs +Linker and Libraries Guide (document 816-1386) +C++ Migration Guide (document 816-2459) +http://docs.sun.com/db/prod/solaris.9 +http://docs.sun.com/?p=/doc/816-1386&a=load + +Ulrich Drepper, "ELF Symbol Versioning" +http://people.redhat.com/drepper/symbol-versioning + diff --git a/libstdc++-v3/docs/html/configopts.html b/libstdc++-v3/docs/html/configopts.html index 6c7374078c0..47eb4637fbe 100644 --- a/libstdc++-v3/docs/html/configopts.html +++ b/libstdc++-v3/docs/html/configopts.html @@ -1,12 +1,11 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> <html> <head> - <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> - <meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++"> - <meta name="DESCRIPTION" content="Configuration options for libstdc++-v3."> - <meta name="GENERATOR" content="vi and eight fingers"> + <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> + <meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++" /> + <meta name="DESCRIPTION" content="Configuration options for libstdc++-v3." /> + <meta name="GENERATOR" content="vi and eight fingers" /> <title>libstdc++-v3 configure options</title> -<link rel="StyleSheet" href="lib3styles.css"> +<link rel="StyleSheet" href="lib3styles.css" /> </head> <body> @@ -19,14 +18,14 @@ options</a></h1> </p> <p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>. - +</p> <!-- ####################################################### --> -<hr> +<hr /> <p>Here are some of the non-obvious options to libstdc++'s configure. Keep in mind that <!-- This SECnn should be the "Choosing Package Options" section. --> - <a href="http://sources.redhat.com/autoconf/autoconf.html#SEC74">they + <a href="http://www.gnu.org/manual/autoconf/html_node/Package-Options.html#Package%20Options">they all have opposite forms as well</a> (enable/disable and with/without). The defaults are for current development sources. @@ -34,34 +33,68 @@ options</a></h1> <p>The canonical way to find out the configure options that are available for a given set of libstdc++ sources is to go to the source directory and then type:<code> ./configure --help</code> +</p> <dl> - <dt><code>--enable-multilib </code>[default] + <dt><code>--enable-multilib </code>[default]</dt> <dd><p>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. </p> + </dd> + + <dt><code>--enable-sjlj-exceptions </code></dt> + <dd><p>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. + </p> + </dd> + + <dt><code>--enable-version-specific-runtime-libs </code></dt> + <dd><p>Specify that run-time libraries should be installed in the + compiler-specific subdirectory (i.e., + <code>${libdir}/gcc-lib/${target_alias}/${gcc_version}</code>) + instead of <code>${libdir}</code>. 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 + <code>${libdir}/gcc-lib/${target_alias}/${gcc_version}/include/g++</code>, + unless you also specify + <code>--with-gxx-include-dir=<em>dirname</em></code> during configuration. + </p> + </dd> + + <dt><code>--with-gxx-include-dir=<include-files dir></code></dt> + <dd><p>Adds support for named libstdc++ include directory. For instance, + the following puts all the libstdc++ headers into a directory + called "2.97-20001008" instead of the usual + "g++-v3". + </p> + <pre> + --with-gxx-include-dir=/foo/H-x86-gcc-3-c-gxx-inc/include/2.97-20001008</pre> </dd> - <dt><code>--enable-debug </code> + <dt><code>--enable-debug </code></dt> <dd><p>The configure script will automatically detect the highest - level of optimization that the compiler in use can use - (certain versions of g++ will ICE if given the <code>-O2</code> - option, but this is fixed in later versions of the compiler). + level of optimization that the compiler in use can use. This --enable flag will disable all optimizations and instruct the compiler to emit as much extra debugging information as it - can, for use inside GDB. Note this make command, executed in + can, for use inside GDB. Note this make command, executed in the build directory, will do much the same thing, without the - configuration difference:<code>make CXXFLAGS='-g -O0' all</code> + configuration difference: + <code>make CXXFLAGS='-g -O0' all</code> </p> + </dd> - <dt><code>--enable-cstdio </code> + <dt><code>--enable-cstdio </code></dt> <dd><p>This is an abbreviated form of <code>'--enable-cstdio=stdio'</code> - (described next). + (described next). This option can change the library ABI. </p> + </dd> - <dt><code>--enable-cstdio=LIB </code> + <dt><code>--enable-cstdio=OPTION </code></dt> <dd><p>Select a target-specific I/O package. As of libstdc++-v3 snapshot 3.0.96, the choices are 'libio' to specify the GNU I/O package (from @@ -70,103 +103,64 @@ options</a></h1> abstraction. The default is 'stdio'. A longer explanation is <a href="explanations.html#cstdio">here</a>. </p> + </dd> - <dt><code>--enable-sjlj-exceptions </code> - <dd><p>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. - </p> - - <dt><code>--enable-clocale </code> + <dt><code>--enable-clocale </code></dt> <dd><p>This is an abbreviated form of <code>'--enable-clocale=generic'</code> - (described next). + (described next). This option can change the library ABI. </p> + </dd> - <dt><code>--enable-clocale=MODEL </code> + <dt><code>--enable-clocale=OPTION </code></dt> <dd><p>Select a target-specific underlying locale package. The - choices are 'ieee_1003.1' to specify an X/Open, Standard Unix - (IEEE Std. 1003.1-200x) model based on langinfo/iconv/catgets, + 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 <A + library (langinfo/iconv/gettext) (from <a href="http://sources.redhat.com/glibc/">glibc</a>, the GNU C library), or 'generic' to use a generic "C" - abstraction which consists of "C" locale info. The - default is 'generic'. + abstraction which consists of "C" locale info. </p> - <dt><code>--enable-c99 </code> - <dd><p>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 <code>namespace - __gnu_cxx</code>, 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. - </p> - - <dt><code>--enable-long-long </code> - <dd><p>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). + <p>As part of the configuration process, the "C" library is + probed both for sufficient vintage, and installed locale + data. If either of these elements are not present, the C++ + locale model default to 'generic.' On glibc-based systems of + version 2.2.5 and above with installed locale files, 'gnu' is + automatically selected. </p> + </dd> - <dt><code>--enable-cheaders=OPTION </code> + <dt><code>--enable-cheaders=OPTION </code></dt> <dd><p>This allows the user to define what kind of C headers are used. Options are: c, c_std, and c_shadow. These correspond to the source directory's include/c, include/c_std, and include/c_shadow directories. The default is c_std. </p> + </dd> - <dt><code>--enable-threads </code> + <dt><code>--enable-threads </code></dt> <dd><p>This is an abbreviated form of <code>'--enable-threads=yes'</code> - (described next). + (described next). This option can change the library ABI. </p> + </dd> - <dt><code>--enable-threads=LIB </code> + <dt><code>--enable-threads=OPTION </code></dt> <dd><p>Select a threading library. A full description is given in the general <a href="http://gcc.gnu.org/install/configure.html">compiler configuration instructions</a>. </p> + </dd> - <dt><code>--enable-version-specific-runtime-libs </code> - <dd><p>Specify that run-time libraries should be installed in the - compiler-specific subdirectory (i.e., - <code>${libdir}/gcc-lib/${target_alias}/${gcc_version}</code>) - instead of <code>${libdir}</code>. 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 - <code>${libdir}/gcc-lib/${target_alias}/${gcc_version}/include/g++</code>, - unless you also specify - <code>--with-gxx-include-dir=<em>dirname</em></code> during configuration. - </p> - - <dt><code>--with-gxx-include-dir=<include-files dir></code> - <dd><p>Adds support for named libstdc++ include directory. For instance, - the following puts all the libstdc++ headers into a directory - called "2.97-20001008" instead of the usual - "g++-v3". - <pre> - --with-gxx-include-dir=/foo/H-x86-gcc-3-c-gxx-inc/include/2.97-20001008</pre> - </p> - - <dt><code>--enable-cxx-flags=FLAGS</code> + <dt><code>--enable-cxx-flags=FLAGS</code></dt> <dd><p>With this option, you can pass a string of -f (functionality) - flags to the compiler to use when building libstdc++. 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 + </p> <pre> --enable-cxx-flags='-fvtable-gc -fomit-frame-pointer -ansi'</pre> + <p> 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. @@ -177,33 +171,68 @@ options</a></h1> as well, so that everything matches. </p> <p>Fun flags to try might include combinations of + </p> <pre> -fstrict-aliasing -fno-exceptions -ffunction-sections -fvtable-gc</pre> - and opposite forms (-fno-) of the same. Tell us (the libstdc++ + <p>and opposite forms (-fno-) of the same. Tell us (the libstdc++ mailing list) if you discover more! </p> + </dd> + + <dt><code>--enable-c99 </code></dt> + <dd><p>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 <code>namespace + __gnu_cxx</code>, 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. + </p> + </dd> - <dt><code>--enable-c-mbchar </code>[default] + <dt><code>--enable-c-mbchar </code>[default]</dt> <dd><p>Certain template specializations are required for wide character conversion support. This is tricky and currently changing rapidly, and can cause problems on new platforms. Disabling wide character specializations is useful for initial porting steps, but builds only a subset of what is required by - ISO. By default, this option is on. + ISO. By default, this option is on. This option can change + the library ABI. + </p> + </dd> + + <dt><code>--enable-long-long </code></dt> + <dd><p>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. </p> + </dd> - <dt><code>--enable-concept-checks </code> + <dt><code>--enable-concept-checks </code></dt> <dd><p>This turns on additional compile-time checks for instantiated library templates, in the form of specialized templates, <a href="19_diagnostics/howto.html#3">described here</a>. They can help users discover when they break the rules of the STL, before their programs run. </p> + </dd> - <dt><code>--enable-symvers[=style] </code> + <dt><code>--enable-symvers[=style] </code></dt> <dd><p>In 3.1, tries to turn on symbol versioning in the shared library (if a shared library has been requested). The only 'style' currently supported is 'gnu' which requires that a recent version of the GNU @@ -211,8 +240,8 @@ options</a></h1> try to guess if the 'gnu' style can be used, and if so, will turn it on. Hopefully people will volunteer to do other 'style' options. </p> + </dd> </dl> -</p> <p>Return <a href="#top">to the top of the page</a> or <a href="http://gcc.gnu.org/libstdc++/">to the libstdc++ homepage</a>. </p> @@ -220,7 +249,7 @@ options</a></h1> <!-- ####################################################### --> -<hr> +<hr /> <p class="fineprint"><em> See <a href="17_intro/license.html">license.html</a> for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/documentation.html b/libstdc++-v3/docs/html/documentation.html index 321878bed1b..aba38723747 100644 --- a/libstdc++-v3/docs/html/documentation.html +++ b/libstdc++-v3/docs/html/documentation.html @@ -1,113 +1,248 @@ <html> <head> - <meta name="KEYWORDS" content="libstdc++, homepage, home, g++, libg++, STL"> - <title>Standard C++ Library v3</title> -<link rel="StyleSheet" href="lib3styles.css"> + <meta name="KEYWORDS" + content="libstdc++, homepage, home, C++, library, c++, std, g++, ABI, STL" /> + <title>GNU C++ Standard Library</title> +<link rel="StyleSheet" href="lib3styles.css" /> </head> <body> -<p><B>All of these documents</B> (in fact, this entire homepage set) are - bundled with the library source, under the <code>docs</code> subdirectory, - for releases and snapshots. The sole exception is the +<p><strong>All of these documents</strong> (in fact, this entire homepage set) + are bundled with the library source, under the <code>docs</code> + subdirectory, for releases and snapshots. The sole exception is the automatically-generated source documentation, available separately. </p> -<hr> -<h2><a name="4">Source Documentation</a></h2> -<p>In addition to the distribution documentation (these pages), we also - have a set of HTML documents generated from the sources themselves, - using the Doxygen tool. These are useful for examining the signatures - of public member functions for the library classes, etc. -</p> -<p>The collections are available in the libstdc++ snapshots directory at - <code><URL:ftp://gcc.gnu.org/pub/gcc/libstdc++/doxygen/></code>. - You will almost certainly need to use one of the - <a href="http://gcc.gnu.org/mirrors.html">mirror sites</a> to download - the tarball. After unpacking, simply load libstdc++-html-*/index.html - into a browser. Feedback (and additional documentation!) is welcome. -</p> -<p>The available user-level collections are also viewable online: - <ul> - <li><a href="libstdc++-doxygen-3.0/index.html">docs for the 3.0 release</a> - <li><a href="libstdc++-html-USERS-3.0.96/index.html">docs for the most - recent libstdc++ snapshot (3.0.96)</a> - <li><a href="latest-doxygen/index.html">"the latest collection"</a> - (snapshot collection or later; see the date on the first page) - </ul> - Other collections (man pages, maintainer docs) are only available on the - FTP sites. -</p> - -<p>Beginning with 3.0.95, an initial set of man pages are also available in - the same place as the HTML collections. Start with <code>Intro(3)</code>. -</p> - -<hr> -<h2><a name="2">Configuring, Building, Installing</a></h2> - <ul> - <li><a href="configopts.html">Configure options</a> - <li><a href="install.html">Getting started: configure, build, install</a><br> - </ul> - -<hr> -<h2><a name="1">Introductory notes for libstdc++</a></h2> - <p>This is a short list of text files pertaining to this - implementation of ISO 14882. A brief description follows the name - of the file. +<hr /> +<br /> +<h2><a name="1">Introduction</a></h2> + <p>This is a short list of text files pertaining to this implementation of + ISO 14882. A brief description may follow the name of the file. </p> - <p> <ul> - <li><a href="17_intro/BADNAMES">BADNAMES</a> - - names to avoid because of potential collisions - <li><a href="17_intro/BUGS">BUGS</a> - <li><a href="17_intro/C++STYLE">C++STYLE</a> - - coding style by example - <li><a href="17_intro/CHECKLIST">CHECKLIST</a> - - a list of required features and their status. - <li><a href="17_intro/COPYING">COPYING</a> - - GPL v2 license terms - <li><a href="17_intro/DESIGN">DESIGN</a> - - overview of the implementation plan - <li><a href="17_intro/HEADER_POLICY">HEADER_POLICY</a> - - header naming and sub-include structure + <li><a href="17_intro/COPYING">License</a> + - GPL v2 license terms</li> + <li><a href="abi.txt">ABI Policy and Guidelines</a></li> + <li><a href="17_intro/BUGS">BUGS</a></li> <li><a href="17_intro/PROBLEMS">PROBLEMS</a> + - target-specific known issues</li> <!-- Linking to "../README" doesn't work; we are at the top level of the web pages. Punt. --> - <li>README - directory structure + <li>README - directory structure</li> <li><a href="17_intro/RELEASE-NOTES">RELEASE-NOTES</a> - - instructions for building, using + - latest version info, recent changes and news</li> <li><a href="17_intro/TODO">TODO</a> - - tasks and known bugs - <li><a href="17_intro/organization">organization</a> - <li><a href="17_intro/contribute.html">Contributor checklist</a> - <li><a href="17_intro/libstdc++-assign.txt">Copyright assignment form for libstdc++-v3</a> + - tasks yet undone</li> </ul> - </p> -<hr> -<h2><a name="3">Chapter-Specific Information, Extensions, Notes and Advice</a></h2> - <ol> - <li><a href="17_intro/howto.html">Chapter 17 (Intro)</a> - <li><a href="18_support/howto.html">Chapter 18 (Library Support)</a> - <li><a href="19_diagnostics/howto.html">Chapter 19 (Diagnostics)</a> - <li><a href="20_util/howto.html">Chapter 20 (Utilities)</a> - <li><a href="21_strings/howto.html">Chapter 21 (Strings)</a> - <li><a href="22_locale/howto.html">Chapter 22 (Localization)</a> - <li><a href="23_containers/howto.html">Chapter 23 (Containers)</a> - <li><a href="24_iterators/howto.html">Chapter 24 (Iterators)</a> - <li><a href="25_algorithms/howto.html">Chapter 25 (Algorithms)</a> - <li><a href="26_numerics/howto.html">Chapter 26 (Numerics)</a> - <li><a href="27_io/howto.html">Chapter 27 (I/O)</a> - <li><a href="ext/howto.html">Extensions to the Standard Library</a> - </ol> +<hr /> +<br /> +<h2><a name="2">Configuring, Building, Installing</a></h2> +<ul> + <li><a href="configopts.html">Configure options</a></li> + <li><a href="install.html">Getting started: configure, build, install</a> + </li> +</ul> + + +<hr /> +<br /> +<h2><a name="4">Source-Level Documentation</a></h2> +<p>The 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. +</p> +<p>The Source-Level documentation can be viewed online:</p> +<ul> + <li><a href="libstdc++-html-USERS-3.1/index.html">for the 3.1 release</a> + </li> + <li><a href="libstdc++-html-USERS-3.2/index.html">for the 3.2 release</a> + </li> + <li><a href="latest-doxygen/index.html">"the latest collection"</a> + (for the snapshot or later; see the date on the first page) + </li> +</ul> +<p>This generated HTML collection, as above, is also available for download in + the libstdc++ snapshots directory at + <code><URL:ftp://gcc.gnu.org/pub/gcc/libstdc++/doxygen/></code>. + You will almost certainly need to use one of the <a + href="http://gcc.gnu.org/mirrors.html">mirror sites</a> to download + the tarball. After unpacking, simply load + libstdc++-html-*/index.html into a browser. Feedback (and + additional documentation!) is welcome. +</p> +<p> + In addition, an initial set of man pages are also available in the + same place as the HTML collections. Start with Intro(3). +</p> + + +<hr /> +<br /> +<h2><a name="3">Chapter-Specific Documentation</a></h2> +<p>Information, extensions, notes and advice on specific implementation + capabilites and/or liabilities broken down into chapter names based on the + C++ standard. +</p> +<!-- + The list below is automatically generated. To make changes in the text, + edit the appropriate HOWTO file and run "make" in this directory. In + those files, you may reorder entries as you like, but DO NOT change the + "#number"s in anchors, for they are used elsewhere and in bookmarks. +--> +<!-- beginlist --> + <ul> + <li>Library Introduction (Chapter 17) + <ul> + <li><a href="17_intro/howto.html#2">The Standard C++ header files</a></li> + <li><a href="17_intro/howto.html#3">The Standard C++ library and multithreading</a></li> + <li><a href="17_intro/howto.html#4"><code><foo></code> vs <code><foo.h></code></a></li> + <li><a href="17_intro/porting-howto.html">Porting HOWTO</a></li> + <li><a href="17_intro/howto.html#5">Behavior specific to libstdc++-v3</a></li> + <li><a href="17_intro/howto.html#6">Preprocessor macros controlling the library</a></li> + </ul> + </li> + + <li>Library Support (Chapter 18) + <ul> + <li><a href="18_support/howto.html#1">Types</a></li> + <li><a href="18_support/howto.html#2">Implementation properties</a></li> + <li><a href="18_support/howto.html#3">Start and Termination</a></li> + <li><a href="18_support/howto.html#4">Dynamic memory management</a></li> + <li><a href="18_support/howto.html#5">RTTI, the ABI, and demangling</a></li> + </ul> + </li> + + <li>Diagnostics (Chapter 19) + <ul> + <li><a href="19_diagnostics/howto.html#1">Adding data to exceptions</a></li> + <li><a href="19_diagnostics/howto.html#2">Exception class hierarchy diagram</a></li> + <li><a href="19_diagnostics/howto.html#3">Concept checkers -- <strong>new and improved!</strong></a></li> + <li><a href="19_diagnostics/howto.html#4">Verbose <code>terminate</code></a></li> + </ul> + </li> + + <li>General Utilities (Chapter 20) + <ul> + <li><a href="20_util/howto.html#1"><code>auto_ptr</code> is not omnipotent</a></li> + <li><a href="20_util/howto.html#2"><code>auto_ptr</code> inside container classes</a></li> + <li><a href="20_util/howto.html#3">Functors</a></li> + <li><a href="20_util/howto.html#4">Pairs</a></li> + </ul> + </li> + + <li>Strings (Chapter 21) + <ul> + <li><a href="21_strings/howto.html#1">MFC's CString</a></li> + <li><a href="21_strings/howto.html#2">A case-insensitive string class</a></li> + <li><a href="21_strings/howto.html#3">Breaking a C++ string into tokens</a></li> + <li><a href="21_strings/howto.html#4">Simple transformations</a></li> + <li><a href="21_strings/howto.html#5">Making strings of arbitrary character types</a></li> + </ul> + </li> + + <li>Localization (Chapter 22) + <ul> + <li><a href="22_locale/howto.html#1">class locale</a></li> + <li><a href="22_locale/howto.html#2">class codecvt</a></li> + <li><a href="22_locale/howto.html#3">class ctype</a></li> + <li><a href="22_locale/howto.html#4">class messages</a></li> + <li><a href="22_locale/howto.html#5">Bjarne Stroustrup on Locales</a></li> + <li><a href="22_locale/howto.html#6">Nathan Myers on Locales</a></li> + <li><a href="22_locale/howto.html#7">Correct Transformations</a></li> + </ul> + </li> + + <li>Containers (Chapter 23) + <ul> + <li><a href="23_containers/howto.html#1">Making code unaware of the container/array difference</a></li> + <li><a href="23_containers/howto.html#2">Variable-sized bitmasks</a></li> + <li><a href="23_containers/howto.html#3">Containers and multithreading</a></li> + <li><a href="23_containers/howto.html#4">"Hinting" during insertion</a></li> + <li><a href="23_containers/howto.html#5">Bitmasks and string arguments</a></li> + <li><a href="23_containers/howto.html#6"><code>std::list::size()</code> is O(n)!</a></li> + <li><a href="23_containers/howto.html#7">Space overhead management for vectors</a></li> + </ul> + </li> + + <li>Iterators (Chapter 24) + <ul> + <li><a href="24_iterators/howto.html#1">They ain't pointers!</a></li> + <li><a href="24_iterators/howto.html#2">It ends <em>where?</em></a></li> + </ul> + </li> + + <li>Algorithms (Chapter 25) + <ul> + <li><a href="25_algorithms/howto.html#1">Prerequisites</a></li> + <li><a href="25_algorithms/howto.html#2">Special <code>swap</code>s</a></li> + </ul> + </li> + + <li>Numerics (Chapter 26) + <ul> + <li><a href="26_numerics/howto.html#1">Complex Number Processing</a></li> + <li><a href="26_numerics/howto.html#2">Array Processing</a></li> + <li><a href="26_numerics/howto.html#3">Numerical Functions</a></li> + <li><a href="26_numerics/howto.html#4">C99</a></li> + </ul> + </li> + + <li>Input/Output (Chapter 27) + <ul> + <li><a href="27_io/howto.html#1">Copying a file</a></li> + <li><a href="27_io/howto.html#2">The buffering is screwing up my program!</a></li> + <li><a href="27_io/howto.html#3">Binary I/O</a></li> + <li><a href="27_io/howto.html#5">What is this <sstream>/stringstreams thing?</a></li> + <li><a href="27_io/howto.html#6">Deriving a stream buffer</a></li> + <li><a href="27_io/howto.html#7">More on binary I/O</a></li> + <li><a href="27_io/howto.html#8">Pathetic performance? Ditch C.</a></li> + <li><a href="27_io/howto.html#9">Threads and I/O</a></li> + </ul> + </li> + + <li>Extensions to the Standard Library + <ul> + <li><a href="ext/howto.html#1">Ropes and trees and hashes, oh my!</a></li> + <li><a href="ext/howto.html#2">Added members and types</a></li> + <li><a href="ext/howto.html#3">Allocators (versions 3.0, 3.1, 3.2)</a></li> + <li><a href="ext/howto.html#6">Allocators (version 3.3)</a></li> + <li><a href="ext/howto.html#4">Compile-time checks</a></li> + <li><a href="ext/howto.html#5">LWG Issues</a></li> + </ul> + </li> + + </ul> +<!-- endlist --> +<hr /> +<br /> +<h2><a name="5">Contributor-Specific Information</a></h2> +<ul> + <li><a href="17_intro/contribute.html">Contributor checklist</a></li> + <li><a href="17_intro/libstdc++-assign.txt">Copyright assignment form for libstdc++-v3</a></li> + <li><a href="17_intro/BADNAMES">BADNAMES</a> + - names to avoid because of potential collisions</li> + <li><a href="17_intro/C++STYLE">C++STYLE</a> + - coding style by example</li> + <li><a href="17_intro/CHECKLIST">CHECKLIST</a> + - a list of required features and their status.</li> + <li><a href="17_intro/DESIGN">DESIGN</a> + - overview of the implementation plan</li> + <li><a href="17_intro/HEADER_POLICY">HEADER_POLICY</a> + - header naming and sub-include structure</li> +</ul> <!-- ####################################################### --> <p>Return <a href="http://gcc.gnu.org/libstdc++/">to the libstdc++ homepage</a>.</p> -<hr> +<hr /> <p class="fineprint"><em> See <a href="17_intro/license.html">license.html</a> for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/explanations.html b/libstdc++-v3/docs/html/explanations.html index 164a5a1cf8e..7d8196ff84a 100644 --- a/libstdc++-v3/docs/html/explanations.html +++ b/libstdc++-v3/docs/html/explanations.html @@ -1,12 +1,11 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> <html> <head> - <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> - <meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++"> - <meta name="DESCRIPTION" content="Explanatory notes about libstdc++-v3."> - <meta name="GENERATOR" content="vi and eight fingers"> + <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> + <meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++" /> + <meta name="DESCRIPTION" content="Explanatory notes about libstdc++-v3." /> + <meta name="GENERATOR" content="vi and eight fingers" /> <title>Explanatory notes about libstdc++-v3 design</title> -<link rel="StyleSheet" href="lib3styles.css"> +<link rel="StyleSheet" href="lib3styles.css" /> </head> <body> @@ -19,11 +18,12 @@ design</a></h1> </p> <p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>. +</p> <!-- ####################################################### --> -<hr> -<a name="cstdio"><h3>"I/O packages", <code>--enable-cstdio</code></h3></a> +<hr /> +<h3><a name="cstdio">"I/O packages", <code>--enable-cstdio</code></a></h3> <p>In addition to all the nifty things which C++ can do for I/O, its library also includes all of the I/O capabilites of C. Making them work together can be a challenge, not only @@ -61,8 +61,8 @@ design</a></h1> </p> -<hr> -<a name="alloc"><h3>Internal Allocators</h3></a> +<hr /> +<h3><a name="alloc">Internal Allocators</a></h3> <p> </p> <p>Return <a href="#top">to the top of the page</a> or @@ -72,7 +72,7 @@ design</a></h1> <!-- ####################################################### --> -<hr> +<hr /> <p class="fineprint"><em> See <a href="17_intro/license.html">license.html</a> for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/ext/howto.html b/libstdc++-v3/docs/html/ext/howto.html index b883445de0b..b4f6dae6f14 100644 --- a/libstdc++-v3/docs/html/ext/howto.html +++ b/libstdc++-v3/docs/html/ext/howto.html @@ -1,13 +1,12 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> <html> <head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> - <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL"> - <meta name="DESCRIPTION" content="Notes for the libstdc++ extensions."> - <meta name="GENERATOR" content="vi and eight fingers"> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> + <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> + <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" /> + <meta name="DESCRIPTION" content="Notes for the libstdc++ extensions." /> + <meta name="GENERATOR" content="vi and eight fingers" /> <title>libstdc++-v3 HOWTO: Extensions</title> -<link rel="StyleSheet" href="../lib3styles.css"> +<link rel="StyleSheet" href="../lib3styles.css" /> </head> <body> @@ -18,44 +17,46 @@ and some just seemed to appear on the doorstep. </p> <p><strong>Before you leap in and use these</strong>, be aware of two things: - <ol> - <li>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++-v3 may not recognize these names, or - treat them differently, or... - <li>You should know how to <a href="../faq/index.html#5_4">access - these headers properly</a>. - </ol> </p> +<ol> + <li>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++-v3 may not recognize these names, or + treat them differently, or... </li> + <li>You should know how to <a href="../faq/index.html#5_4">access + these headers properly</a>. </li> +</ol> <!-- ####################################################### --> -<hr> +<hr /> <h1>Contents</h1> <ul> - <li><a href="#1">Ropes and trees and hashes, oh my!</a> - <li><a href="#2">Added members and types</a> - <li><a href="#3">Allocators</a> - <li><a href="#4">Compile-time checks</a> - <li><a href="#5">LWG Issues</a> + <li><a href="#1">Ropes and trees and hashes, oh my!</a></li> + <li><a href="#2">Added members and types</a></li> + <li><a href="#3">Allocators (versions 3.0, 3.1, 3.2)</a></li> + <li><a href="#6">Allocators (version 3.3)</a></li> + <li><a href="#4">Compile-time checks</a></li> + <li><a href="#5">LWG Issues</a></li> </ul> -<hr> +<hr /> <!-- ####################################################### --> <h2><a name="1">Ropes and trees and hashes, oh my!</a></h2> - <p>The SGI headers - <pre> + <p>The SGI headers</p> + <pre> <bvector> <hash_map> <hash_set> <rope> <slist> <tree> - </pre> are all here; <code><bvector></code> exposes the old bit_vector + </pre> + <p>are all here; <code><bvector></code> exposes the old bit_vector class that was used before specialization of vector<bool> was available (it's actually a typedef for the specialization now). <code><hash_map></code> and <code><hash_set></code> @@ -87,25 +88,25 @@ </p> <p>Why would you want to use a hashing class instead of the "normal" implementations? Matt Austern writes: - <blockquote><em>[W]ith a well chosen hash function, hash tables - generally provide much better average-case performance than binary - search trees, and much worse worst-case performance. So if your - implementation has hash_map, if you don't mind using nonstandard - components, and if you aren't scared about the possibility of - pathological cases, you'll probably get better performance from - hash_map.</em></blockquote> </p> + <blockquote><em>[W]ith a well chosen hash function, hash tables + generally provide much better average-case performance than binary + search trees, and much worse worst-case performance. So if your + implementation has hash_map, if you don't mind using nonstandard + components, and if you aren't scared about the possibility of + pathological cases, you'll probably get better performance from + hash_map.</em></blockquote> <p>(Side note: for those of you wondering, <strong>"Why wasn't a hash table included in the Standard in the first #!$@ place?"</strong> I'll give a quick answer: it was proposed, but too late and in too unorganized a fashion. Some sort of hashing will undoubtedly be - included in a future Standard. + included in a future Standard.) </p> <p>Return <a href="#top">to top of page</a> or <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="2">Added members and types</a></h2> <p>Some of the classes in the Standard Library have additional publicly-available members, and some classes are themselves not in @@ -113,29 +114,32 @@ for example, additional typedefs. Those won't be described here (or anywhere else). </p> - <p> - <ul> + <ul> <li>The extensions added by SGI are so numerous that they have <a href="sgiexts.html">their own page</a>. Since the SGI STL is no longer actively maintained, we will try and keep this code working ourselves.</li> - <li><code>filebuf</code>s have another ctor with this signature:<br> -<code>basic_filebuf(__c_file_type*, ios_base::openmode, int_type);</code> - <br>This comes in very handy in a number of places, such as + <li>3.0.x <code>filebuf</code>s have another ctor with this signature: + <br /> + <code>basic_filebuf(__c_file_type*, ios_base::openmode, int_type);</code> + <br />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: <ul> <li><code>__c_file_type* F </code> // the __c_file_type typedef usually boils down to stdio's FILE + </li> <li><code>ios_base::openmode M </code> // same as all the other uses of openmode + </li> <li><code>int_type B </code> // buffer size, defaults to BUFSIZ if not specified + </li> </ul> For those wanting to use file descriptors instead of FILE*'s, I invite you to contemplate the mysteries of C's <code>fdopen()</code>. - </li> + </li> <li>In library snapshot 3.0.95 and later, <code>filebuf</code>s bring back an old extension: the <code>fd()</code> member function. The integer returned from this function can be used for whatever file @@ -143,27 +147,35 @@ 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. - </ul> - </p> + </li> + <li>Beginning with 3.1, the extra <code>filebuf</code> constructor and + the <code>fd()</code> function were removed from the standard + filebuf. Instead, <code><ext/stdio_filebuf.h></code> contains + a derived class called <code>__gnu_cxx::stdio_filebuf</code>. + </li> + </ul> <p>Return <a href="#top">to top of page</a> or <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> -<h2><a name="3">Allocators</a></h2> +<hr /> +<h2><a name="3">Allocators (versions 3.0, 3.1, 3.2)</a></h2> <p>Thread-safety, space efficiency, high speed, portability... this is a mess. Where to begin? </p> <h3>The Rules</h3> <p>The C++ standard only gives a few directives in this area: - <ul> + </p> + <ul> <li>When you add elements to a container, and the container must allocate more memory to hold them, the container makes the request via its <code>Allocator</code> template parameter. This includes adding char's to the string class, which acts as a regular STL container in this respect. + </li> <li>The default <code>Allocator</code> of every container-of-T is <code>std::allocator<T></code>. + </li> <li>The interface of the <code>allocator<T></code> class is extremely simple. It has about 20 public declarations (nested typedefs, member functions, etc), but the two which concern us most @@ -175,13 +187,14 @@ The <code>"n"</code> arguments in both those functions is a <em>count</em> of the number of T's to allocate space for, <em>not their total size</em>. + </li> <li>"The storage is obtained by calling <code>::operator new(size_t)</code>, but it is unspecified when or how often this function is called. The use of <code>hint</code> is unspecified, but intended as an aid to locality if an implementation so desires." [20.4.1.1]/6 - </ul> - </p> + </li> + </ul> <h3>Problems and Possibilities</h3> <p>The easiest way of fulfilling the requirements is to call operator new each time a container needs memory, and to call operator delete each @@ -215,47 +228,54 @@ <p>Well then: </p> <h3>Available allocators in namespace std</h3> - <p>First I'll describe the situation as it exists for the code which will - be released in GCC 3.1. This situation is extremely fluid. Then I'll - describe the differences for 3.0.x, which will not change much in - this respect. + <p>First I'll describe the situation as it exists for the code which + was released in GCC 3.1 and 3.2. Then I'll describe the differences + for 3.0. The allocator classes also have source documentation, + which is described <a href="../documentation.html#4">here</a> (you + will need to retrieve the maintainer-level docs, as almost none of + these entities are in the ISO standard). </p> <p>As a general rule of thumb, users are not allowed to use names which begin with an underscore. This means that to be portable between compilers, none of the following may be used in your program directly. (If you decide to be unportable, then you're free do do what you want, but it's not our fault if stuff breaks.) They are presented here for - information for maintainers and contributors in addition to users, but - we will probably make them available for users in 3.1 somehow. + information for maintainers and contributors in addition to users. </p> <p>These classes are always available: - <ul> + </p> + <ul> <li><code>__new_alloc</code> simply wraps <code>::operator new</code> and <code>::operator delete</code>. + </li> <li><code>__malloc_alloc_template<int inst></code> simply wraps <code>malloc</code> and <code>free</code>. There is also a hook for an out-of-memory handler (for new/delete this is taken care of elsewhere). The <code>inst</code> parameter is described below. This class was called <code>malloc_alloc</code> in earlier versions. + </li> <li><code>allocator<T></code> has already been described; it is The Standard Allocator for instances of T. It uses the internal <code>__alloc</code> typedef (see below) to satisy its requests. + </li> <li><code>__simple_alloc<T,A></code> is a wrapper around another allocator, A, which itself is an allocator for instances of T. This is primarily used in an internal "allocator traits" class which helps encapsulate the different styles of allocators. + </li> <li><code>__debug_alloc<A></code> is also 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 to <code>deallocate()</code>, the stored size is checked, and assert() is used to guarantee they match. + </li> <li><code>__allocator<T,A></code> is an adaptor. Many of these allocator classes have a consistent yet non-standard interface. Such classes can be changed to a conforming interface with this wrapper: <code>__allocator<T, __alloc></code> is thus the same as <code>allocator<T></code>. - </ul> - </p> + </li> + </ul> <p>An internal typedef, <code> __mem_interface </code>, is defined to be <code>__new_alloc</code> by default. </p> @@ -291,15 +311,15 @@ <p>If you've already read <a href="../23_containers/howto.html#3">this advice</a> and decided to define this macro, then the situation changes thusly: - <ol> - <li><code>__mem_interface</code>, and - <li><code>__alloc</code>, and + </p> + <ol> + <li><code>__mem_interface</code>, and</li> + <li><code>__alloc</code>, and</li> <li><code>__single_client_alloc</code> are all typedef'd to - <code>__malloc_alloc_template</code>. + <code>__malloc_alloc_template</code>.</li> <li><code>__default_alloc_template</code> is no longer available. - At all. Anywhere. <!-- might change? --> - </ol> - </p> + At all. Anywhere.</li> + </ol> <h3>Writing your own allocators</h3> <p>Depending on your application (a specific program, a generic library, etc), allocator classes tend to be one of two styles: "SGI" @@ -320,12 +340,12 @@ (but nonportable) method of specifying that only malloc/free should be used instead of the default node allocator is: - <pre> + </p> + <pre> std::list <my_type, std::__malloc_alloc_template<0> > my_malloc_based_list;</pre> Likewise, a debugging form of whichever allocator is currently in use: <pre> std::deque <my_type, std::__debug_alloc<std::__alloc> > debug_deque;</pre> - </p> <h3><code>inst</code></h3> <p>The <code>__malloc_alloc_template</code> and <code>__default_alloc_template</code> classes take an integer parameter, @@ -333,11 +353,12 @@ </p> <p>The point of the number is to allow multiple instantiations of the classes without changing the semantics at all. All three of - <pre> + </p> + <pre> typedef __default_alloc_template<true,0> normal; typedef __default_alloc_template<true,1> private; typedef __default_alloc_template<true,42> also_private;</pre> - behave exactly the same way. However, the memory pool for each type + <p>behave exactly the same way. However, the memory pool for each type (and remember that different instantiations result in different types) remains separate. </p> @@ -355,13 +376,19 @@ can affect the 3.0.x allocators. Do not use them. Those macros have been completely removed for 3.1. </p> - <p>More notes as we remember them... + <p>Return <a href="#top">to top of page</a> or + <a href="../faq/index.html">to the FAQ</a>. + </p> + +<hr /> +<h2><a name="6">Allocators (version 3.3)</a></h2> + <p>Changes are coming... </p> <p>Return <a href="#top">to top of page</a> or <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="4">Compile-time checks</a></h2> <p>Currently libstdc++-v3 uses the concept checkers from the Boost library to perform <a href="../19_diagnostics/howto.html#3">optional @@ -372,7 +399,7 @@ <a href="../faq/index.html">to the FAQ</a>. </p> -<hr> +<hr /> <h2><a name="5">LWG Issues</a></h2> <p>Everybody's got issues. Even the C++ Standard Library. </p> @@ -406,141 +433,196 @@ examples of style. Note that we usually do not make changes to the code until an issue has reached <a href="lwg-active.html#DR">DR</a> status. </p> - <p><dl> + <dl> <dt><a href="lwg-defects.html#5">5</a>: <em>string::compare specification questionable</em> + </dt> <dd>This should be two overloaded functions rather than a single function. + </dd> <dt><a href="lwg-defects.html#17">17</a>: <em>Bad bool parsing</em> + </dt> <dd>Apparently extracting Boolean values was messed up... + </dd> <dt><a href="lwg-defects.html#22">22</a>: <em>Member open vs flags</em> + </dt> <dd>Re-opening a file stream does <em>not</em> clear the state flags. + </dd> <dt><a href="lwg-defects.html#25">25</a>: <em>String operator<< uses width() value wrong</em> + </dt> <dd>Padding issues. + </dd> <dt><a href="lwg-defects.html#48">48</a>: <em>Use of non-existent exception constructor</em> + </dt> <dd>An instance of <code>ios_base::failure</code> is constructed instead. + </dd> <dt><a href="lwg-defects.html#49">49</a>: <em>Underspecification of ios_base::sync_with_stdio</em> + </dt> <dd>The return type is the <em>previous</em> state of synchronization. + </dd> <dt><a href="lwg-defects.html#50">50</a>: <em>Copy constructor and assignment operator of ios_base</em> + </dt> <dd>These members functions are declared <code>private</code> and are thus inaccessible. Specifying the correct semantics of "copying stream state" was deemed too complicated. + </dd> <dt><a href="lwg-defects.html#68">68</a>: <em>Extractors for char* should store null at end</em> + </dt> <dd>And they do now. An editing glitch in the last item in the list of [27.6.1.2.3]/7. + </dd> <dt><a href="lwg-defects.html#74">74</a>: <em>Garbled text for codecvt::do_max_length</em> + </dt> <dd>The text of the standard was gibberish. Typos gone rampant. + </dd> <dt><a href="lwg-defects.html#83">83</a>: <em>string::npos vs. string::max_size()</em> + </dt> <dd>Safety checks on the size of the string should test against <code>max_size()</code> rather than <code>npos</code>. + </dd> <dt><a href="lwg-defects.html#109">109</a>: <em>Missing binders for non-const sequence elements</em> + </dt> <dd>The <code>binder1st</code> and <code>binder2nd</code> didn't have an <code>operator()</code> taking a non-const parameter. + </dd> <dt><a href="lwg-defects.html#110">110</a>: <em>istreambuf_iterator::equal not const</em> + </dt> <dd>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. + </dd> <dt><a href="lwg-defects.html#117">117</a>: <em>basic_ostream uses nonexistent num_put member functions</em> + </dt> <dd><code>num_put::put()</code> was overloaded on the wrong types. + </dd> <dt><a href="lwg-defects.html#118">118</a>: <em>basic_istream uses nonexistent num_get member functions</em> + </dt> <dd>Same as 117, but for <code>num_get::get()</code>. + </dd> <dt><a href="lwg-defects.html#129">129</a>: <em>Need error indication from seekp() and seekg()</em> + </dt> <dd>These functions set <code>failbit</code> on error now. + </dd> <dt><a href="lwg-defects.html#136">136</a>: <em>seekp, seekg setting wrong streams?</em> + </dt> <dd><code>seekp</code> should only set the output stream, and <code>seekg</code> should only set the input stream. + </dd> <!--<dt><a href="lwg-defects.html#159">159</a>: <em>Strange use of underflow()</em> + </dt> <dd>In fstream.tcc, the basic_filebuf<>::showmanyc() function - should probably not be calling <code>underflow()</code>.--> + should probably not be calling <code>underflow()</code>. + </dd> --> <dt><a href="lwg-active.html#167">167</a>: <em>Improper use of traits_type::length()</em> + </dt> <dd><code>op<<</code> with a <code>const char*</code> was calculating an incorrect number of characters to write. + </dd> <dt><a href="lwg-defects.html#181">181</a>: <em>make_pair() unintended behavior</em> + </dt> <dd>This function used to take its arguments as reference-to-const, now it copies them (pass by value). + </dd> <dt><a href="lwg-defects.html#195">195</a>: <em>Should basic_istream::sentry's constructor ever set eofbit?</em> + </dt> <dd>Yes, it can, specifically if EOF is reached while skipping whitespace. + </dd> <dt><a href="lwg-defects.html#211">211</a>: <em>operator>>(istream&, string&) doesn't set failbit</em> + </dt> <dd>If nothing is extracted into the string, <code>op>></code> now sets <code>failbit</code> (which can cause an exception, etc, etc). + </dd> <dt><a href="lwg-defects.html#214">214</a>: <em>set::find() missing const overload</em> + </dt> <dd>Both <code>set</code> and <code>multiset</code> were missing overloaded find, lower_bound, upper_bound, and equal_range functions for const instances. + </dd> <dt><a href="lwg-defects.html#251">251</a>: <em>basic_stringbuf missing allocator_type</em> + </dt> <dd>This nested typdef was originally not specified. + </dd> <dt><a href="lwg-defects.html#265">265</a>: <em>std::pair::pair() effects overly restrictive</em> + </dt> <dd>The default ctor would build its members from copies of temporaries; now it simply uses their respective default ctors. + </dd> <dt><a href="lwg-defects.html#266">266</a>: <em>bad_exception::~bad_exception() missing Effects clause</em> + </dt> <dd>The <code>bad_</code>* classes no longer have destructors (they are trivial), since no description of them was ever given. + </dd> <dt><a href="lwg-defects.html#275">275</a>: <em>Wrong type in num_get::get() overloads</em> + </dt> <dd>Similar to 118. + </dd> <!-- <dt><a href="lwg-defects.html#"></a>: <em></em> + </dt> <dd> + </dd> --> - </dl></p> + </dl> <p>Return <a href="#top">to top of page</a> or <a href="../faq/index.html">to the FAQ</a>. + </p> <!-- ####################################################### --> -<hr> +<hr /> <p class="fineprint"><em> See <a href="../17_intro/license.html">license.html</a> for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/ext/lwg-active.html b/libstdc++-v3/docs/html/ext/lwg-active.html index 977df966b5a..c8d33f36f4b 100644 --- a/libstdc++-v3/docs/html/ext/lwg-active.html +++ b/libstdc++-v3/docs/html/ext/lwg-active.html @@ -5,11 +5,11 @@ <table> <tr> <td align="left">Doc. no.</td> -<td align="left">J16/01-0052 = WG21 N1337</td> +<td align="left">J16/02-0027 = WG21 N1369</td> </tr> <tr> <td align="left">Date:</td> -<td align="left">09 Nov 2001</td> +<td align="left">10 May 2002</td> </tr> <tr> <td align="left">Project:</td> @@ -20,7 +20,7 @@ <td align="left">Matt Austern <austern@research.att.com></td> </tr> </table> -<h1>C++ Standard Library Active Issues List (Revision 20)</h1> +<h1>C++ Standard Library Active Issues List (Revision 22)</h1> <p>Reference ISO/IEC IS 14882:1998(E)</p> <p>Also see:</p> <ul> @@ -88,6 +88,12 @@ directory as the issues list files. </p> <h2>Revision History</h2> <ul> +<li>R22: +Post-Curaçao mailing. Added new issues <a href="lwg-active.html#362">362</a>-<a href="lwg-active.html#366">366</a>. +</li> +<li>R21: +Pre-Curaçao mailing. Added new issues <a href="lwg-closed.html#351">351</a>-<a href="lwg-active.html#361">361</a>. +</li> <li>R20: Post-Redmond mailing; reflects actions taken in Redmond. Added new issues <a href="lwg-active.html#336">336</a>-<a href="lwg-active.html#350">350</a>, of which issues @@ -95,19 +101,19 @@ new issues <a href="lwg-active.html#336">336</a>-<a href="lwg-active.html#350">3 not discussed at the meeting. All Ready issues were moved to DR status, with the exception of issues -<a href="lwg-active.html#284">284</a>, <a href="lwg-active.html#241">241</a>, and <a href="lwg-closed.html#267">267</a>. +<a href="lwg-defects.html#284">284</a>, <a href="lwg-active.html#241">241</a>, and <a href="lwg-closed.html#267">267</a>. Noteworthy issues discussed at Redmond include <a href="lwg-active.html#120">120</a> <a href="lwg-active.html#202">202</a>, <a href="lwg-active.html#226">226</a>, <a href="lwg-active.html#233">233</a>, -<a href="lwg-active.html#270">270</a>, <a href="lwg-active.html#253">253</a>, <a href="lwg-active.html#254">254</a>, <a href="lwg-active.html#323">323</a>. +<a href="lwg-defects.html#270">270</a>, <a href="lwg-active.html#253">253</a>, <a href="lwg-active.html#254">254</a>, <a href="lwg-active.html#323">323</a>. </li> <li>R19: Pre-Redmond mailing. Added new issues -<a href="lwg-active.html#323">323</a>-<a href="lwg-active.html#335">335</a>. +<a href="lwg-active.html#323">323</a>-<a href="lwg-defects.html#335">335</a>. </li> <li>R18: Post-Copenhagen mailing; reflects actions taken in Copenhagen. -Added new issues <a href="lwg-defects.html#312">312</a>-<a href="lwg-active.html#317">317</a>, and discussed +Added new issues <a href="lwg-defects.html#312">312</a>-<a href="lwg-defects.html#317">317</a>, and discussed new issues <a href="lwg-defects.html#271">271</a>-<a href="lwg-closed.html#314">314</a>. Changed status of issues @@ -126,7 +132,7 @@ Changed status of issues <a href="lwg-defects.html#238">238</a> <a href="lwg-active.html#241">241</a> <a href="lwg-defects.html#242">242</a> <a href="lwg-defects.html#250">250</a> <a href="lwg-defects.html#259">259</a> <a href="lwg-defects.html#264">264</a> <a href="lwg-defects.html#266">266</a> <a href="lwg-closed.html#267">267</a> <a href="lwg-defects.html#271">271</a> <a href="lwg-defects.html#272">272</a> <a href="lwg-defects.html#273">273</a> <a href="lwg-defects.html#275">275</a> -<a href="lwg-defects.html#281">281</a> <a href="lwg-active.html#284">284</a> <a href="lwg-defects.html#285">285</a> <a href="lwg-defects.html#286">286</a> +<a href="lwg-defects.html#281">281</a> <a href="lwg-defects.html#284">284</a> <a href="lwg-defects.html#285">285</a> <a href="lwg-defects.html#286">286</a> <a href="lwg-defects.html#288">288</a> <a href="lwg-defects.html#292">292</a> <a href="lwg-defects.html#295">295</a> <a href="lwg-defects.html#297">297</a> <a href="lwg-defects.html#298">298</a> <a href="lwg-defects.html#301">301</a> <a href="lwg-defects.html#303">303</a> <a href="lwg-defects.html#306">306</a> <a href="lwg-defects.html#307">307</a> <a href="lwg-defects.html#308">308</a> <a href="lwg-defects.html#312">312</a> @@ -141,8 +147,8 @@ as NAD. </li> <li>R17: Pre-Copenhagen mailing. Converted issues list to XML. Added proposed -resolutions for issues <a href="lwg-defects.html#49">49</a>, <a href="lwg-active.html#76">76</a>, <a href="lwg-active.html#91">91</a>, <a href="lwg-defects.html#235">235</a>, <a href="lwg-defects.html#250">250</a>, <a href="lwg-closed.html#267">267</a>. -Added new issues <a href="lwg-active.html#278">278</a>-<a href="lwg-active.html#311">311</a>. +resolutions for issues <a href="lwg-defects.html#49">49</a>, <a href="lwg-defects.html#76">76</a>, <a href="lwg-active.html#91">91</a>, <a href="lwg-defects.html#235">235</a>, <a href="lwg-defects.html#250">250</a>, <a href="lwg-closed.html#267">267</a>. +Added new issues <a href="lwg-active.html#278">278</a>-<a href="lwg-defects.html#311">311</a>. </li> <li>R16: post-Toronto mailing; reflects actions taken in Toronto. Added new @@ -188,7 +194,7 @@ of issue <a href="lwg-defects.html#29">29</a>. Add further rationale to issue post-Kona mailing: Updated to reflect LWG and full committee actions in Kona (99-0048/N1224). Note changed resolution of issues <a href="lwg-closed.html#4">4</a> and <a href="lwg-defects.html#38">38</a>. Added issues <a href="lwg-closed.html#196">196</a> -to <a href="lwg-active.html#198">198</a>. Closed issues list split into "defects" and +to <a href="lwg-defects.html#198">198</a>. Closed issues list split into "defects" and "closed" documents. Changed the proposed resolution of issue <a href="lwg-closed.html#4">4</a> to NAD, and changed the wording of proposed resolution of issue <a href="lwg-defects.html#38">38</a>. @@ -272,7 +278,7 @@ format, <a href="lwg-defects.html#64">64</a> title. (17 Sep 98) <p> <b><a name="Dup">Dup</a></b> - The LWG has reached consensus that the issue is a duplicate of another issue, and will not be further - dealt with. A <b>Rationale</b> identities the duplicated issue's + dealt with. A <b>Rationale</b> identifies the duplicated issue's issue number. </p> <p> @@ -439,121 +445,8 @@ review of clause 27 as the changes are context sensitive. ]</i></p> <hr> -<a name="76"><h3>76. Can a <tt>codecvt</tt> facet always convert one internal character at a time?</h3></a><p> -<b>Section:</b> 22.2.1.5 <a href="lib-locales.html#lib.locale.codecvt"> [lib.locale.codecvt]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Matt Austern <b>Date:</b> 25 Sep 1998</p> -<p>This issue concerns the requirements on classes derived from -<tt>codecvt</tt>, including user-defined classes. What are the -restrictions on the conversion from external characters -(e.g. <tt>char</tt>) to internal characters (e.g. <tt>wchar_t</tt>)? -Or, alternatively, what assumptions about <tt>codecvt</tt> facets can -the I/O library make? </p> - -<p>The question is whether it's possible to convert from internal -characters to external characters one internal character at a time, -and whether, given a valid sequence of external characters, it's -possible to pick off internal characters one at a time. Or, to put it -differently: given a sequence of external characters and the -corresponding sequence of internal characters, does a position in the -internal sequence correspond to some position in the external -sequence? </p> - -<p>To make this concrete, suppose that <tt>[first, last)</tt> is a -sequence of <i>M</i> external characters and that <tt>[ifirst, -ilast)</tt> is the corresponding sequence of <i>N</i> internal -characters, where <i>N > 1</i>. That is, <tt>my_encoding.in()</tt>, -applied to <tt>[first, last)</tt>, yields <tt>[ifirst, -ilast)</tt>. Now the question: does there necessarily exist a -subsequence of external characters, <tt>[first, last_1)</tt>, such -that the corresponding sequence of internal characters is the single -character <tt>*ifirst</tt>? -</p> - -<p>(What a "no" answer would mean is that -<tt>my_encoding</tt> translates sequences only as blocks. There's a -sequence of <i>M</i> external characters that maps to a sequence of -<i>N</i> internal characters, but that external sequence has no -subsequence that maps to <i>N-1</i> internal characters.) </p> - -<p>Some of the wording in the standard, such as the description of -<tt>codecvt::do_max_length</tt> (22.2.1.5.2 <a href="lib-locales.html#lib.locale.codecvt.virtuals"> [lib.locale.codecvt.virtuals]</a>, -paragraph 11) and <tt>basic_filebuf::underflow</tt> (27.8.1.4 <a href="lib-iostreams.html#lib.filebuf.virtuals"> [lib.filebuf.virtuals]</a>, paragraph 3) suggests that it must always be -possible to pick off internal characters one at a time from a sequence -of external characters. However, this is never explicitly stated one -way or the other. </p> - -<p>This issue seems (and is) quite technical, but it is important if -we expect users to provide their own encoding facets. This is an area -where the standard library calls user-supplied code, so a well-defined -set of requirements for the user-supplied code is crucial. Users must -be aware of the assumptions that the library makes. This issue affects -positioning operations on <tt>basic_filebuf</tt>, unbuffered input, -and several of <tt>codecvt</tt>'s member functions. </p> -<p><b>Proposed resolution:</b></p> -<p>Add the following text as a new paragraph, following 22.2.1.5.2 <a href="lib-locales.html#lib.locale.codecvt.virtuals"> [lib.locale.codecvt.virtuals]</a> paragraph 2:</p> - -<blockquote> -<p>A <tt>codecvt</tt> facet that is used by <tt>basic_filebuf</tt> -(27.8 <a href="lib-iostreams.html#lib.file.streams"> [lib.file.streams]</a>) must have the property that if</p> -<pre> - do_out(state, from, from_end, from_next, to, to_lim, to_next) -</pre> -would return <tt>ok</tt>, where <tt>from != from_end</tt>, then -<pre> - do_out(state, from, from + 1, from_next, to, to_end, to_next) -</pre> -must also return <tt>ok</tt>, and that if -<pre> - do_in(state, from, from_end, from_next, to, to_lim, to_next) -</pre> -would return <tt>ok</tt>, where <tt>to != to_lim</tt>, then -<pre> - do_in(state, from, from_end, from_next, to, to + 1, to_next) -</pre> -<p>must also return <tt>ok</tt>. [<i>Footnote:</i> Informally, this -means that <tt>basic_filebuf</tt> assumes that the mapping from -internal to external characters is 1 to N: a <tt>codecvt</tt> that is -used by <tt>basic_filebuf</tt> must be able to translate characters -one internal character at a time. <i>--End Footnote</i>]</p> -</blockquote> - -<p><i>[Redmond: Minor change in proposed resolution. Original -proposed resolution talked about "success", with a parenthetical -comment that success meant returning <tt>ok</tt>. New wording -removes all talk about "success", and just talks about the -return value.]</i></p> - -<p><b>Rationale:</b></p> - - <p>The proposed resoluion says that conversions can be performed one - internal character at a time. This rules out some encodings that - would otherwise be legal. The alternative answer would mean there - would be some internal positions that do not correspond to any - external file position.</p> - <p> - An example of an encoding that this rules out is one where the - <tt>internT</tt> and <tt>externT</tt> are of the same type, and - where the internal sequence <tt>c1 c2</tt> corresponds to the - external sequence <tt>c2 c1</tt>. - </p> - <p>It was generally agreed that <tt>basic_filebuf</tt> relies - on this property: it was designed under the assumption that - the external-to-internal mapping is N-to-1, and it is not clear - that <tt>basic_filebuf</tt> is implementable without that - restriction. - </p> - <p> - The proposed resolution is expressed as a restriction on - <tt>codecvt</tt> when used by <tt>basic_filebuf</tt>, rather - than a blanket restriction on all <tt>codecvt</tt> facets, - because <tt>basic_filebuf</tt> is the only other part of the - library that uses <tt>codecvt</tt>. If a user wants to define - a <tt>codecvt</tt> facet that implements a more general N-to-M - mapping, there is no reason to prohibit it, so long as the user - does not expect <tt>basic_filebuf</tt> to be able to use it. - </p> -<hr> <a name="91"><h3>91. Description of operator>> and getline() for string<> might cause endless loop</h3></a><p> -<b>Section:</b> 21.3.7.9 <a href="lib-strings.html#lib.string.io"> [lib.string.io]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Nico Josuttis <b>Date:</b> 29 Sep 1998</p> +<b>Section:</b> 21.3.7.9 <a href="lib-strings.html#lib.string.io"> [lib.string.io]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Nico Josuttis <b>Date:</b> 29 Sep 1998</p> <p>Operator >> and getline() for strings read until eof() in the input stream is true. However, this might never happen, if the stream can't read anymore without reaching EOF. So shouldn't it be @@ -604,6 +497,8 @@ should be a formatted input function, not an unformatted input function. there is no mechanism for <tt>gcount</tt> to be set except by one of <tt>basic_istream</tt>'s member functions.]</i></p> +<p><i>[Curaçao: Nico agrees with proposed resolution.]</i></p> + <p><b>Rationale:</b></p> <p>The real issue here is whether or not these string input functions get their characters from a streambuf, rather than by calling an @@ -725,6 +620,9 @@ multiple problems beyond the underlying problem of no definition of <p><i>[Post-Tokyo: Nico provided the above proposed resolutions.]</i></p> +<p><i>[Curaçao: Nico will provide wording to make options clearer: are +the exclusive, or is one a superset of the other?]</i></p> + <hr> <a name="96"><h3>96. Vector<bool> is not a container</h3></a><p> <b>Section:</b> 23.2.5 <a href="lib-containers.html#lib.vector.bool"> [lib.vector.bool]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> AFNOR <b>Date:</b> 7 Oct 1998</p> @@ -810,6 +708,9 @@ how many times a copy constructor is called, even if the copy constructor has observable behavior. (See issue <a href="lwg-active.html#334">334</a> for a similar problem.)</p> +<p><i>[Issue still isn't clear. Matt will try to explain it more +clearly at the next meeting.]</i></p> + <p><b>Proposed resolution:</b></p> <hr> <a name="120"><h3>120. Can an implementor add specializations?</h3></a><p> @@ -881,35 +782,43 @@ different explicit instantiations might be harmless.</p> </blockquote> </blockquote> -<p><i>[Copenhagen: LWG discussed three options. (A) Users may not +<p><i>[Copenhagen: LWG discussed three options. (1) Users may not explicitly instantiate standard library templates, except on user-defined types. Consequence: library implementors may freely -specialize or instantiate templates. (B) It is implementation defined -whether users may explicitly instantiate standard library templates on -non-user-defined types. Consequence: library implementors may freely -specialize or instantiate templates, but may need to document some or -all templates that have been explicitly instantiated. (C) Users may -explicitly instantiate any standard library template. +specialize or instantiate templates. (2) Users may explicitly +instantiate any standard library template. Consequence: if +implementors specialize or instantiate library templates, they may +need to take special steps to make sure users can do it too. (3) It +is implementation defined whether users may explicitly instantiate +standard library templates on non-user-defined types. Consequence: +library implementors may freely specialize or instantiate templates, +but may need to document some or all templates that have been +explicitly instantiated. ]</i></p> -<p><i>[Straw poll (first number is favor, second is strongly oppose): -A - 4, 0; B - 0, 9; C - 9, 1. Proposed resolution 1, above, is -option A. (It is the original proposed resolution.) Proposed -resolution 2, above, is option C. Because there was no support -for option B, no wording is provided.]</i></p> +<p><i>[Straw poll (first number is favor, second is strongly oppose): 1 +- 4, 0; 2 - 9, 1; 3 - 0, 9. (Proposed resolution 1 was the original +proposed resolution.) Because there was no support for option 3, no +wording is provided.]</i></p> <p><i>[Redmond: discussed again; straw poll had results similar to -those of Copenhagen (A - 1, 3; B - 6, 2; C - 8, 4). Most people said -they could live with any option. The only objection to option A is +those of Copenhagen (1 - 1, 3; 2 - 8, 4; 3 - 6, 2). Most people said +they could live with any option. The only objection to option 2 is potential implementation difficulty. Steve Clamage volunteered do a -survey to see if there are any popular platforms where option A would +survey to see if there are any popular platforms where option 2 would present a real problem for implementors. See his reflector message, c++std-lib-9002. ]</i></p> +<p><i>[Steve and Pete Becker will talk to Jonathan Caves. The +Microsoft linker might present a problem if there are multiple copies, +some of which have static data and some of which are in DLLs. There +may be similar problems with the Apple linker; Matt will clarify +that.]</i></p> + <hr> <a name="123"><h3>123. Should valarray helper arrays fill functions be const?</h3></a><p> -<b>Section:</b> 26.3.5.4 <a href="lib-numerics.html#lib.slice.arr.fill"> [lib.slice.arr.fill]</a>, 26.3.7.4 <a href="lib-numerics.html#lib.gslice.array.fill"> [lib.gslice.array.fill]</a>, 26.3.8.4 <a href="lib-numerics.html#lib.mask.array.fill"> [lib.mask.array.fill]</a>, 26.3.9.4 <a href="lib-numerics.html#lib.indirect.array.fill"> [lib.indirect.array.fill]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Judy Ward <b>Date:</b> 15 Dec 1998 </p> +<b>Section:</b> 26.3.5.4 <a href="lib-numerics.html#lib.slice.arr.fill"> [lib.slice.arr.fill]</a>, 26.3.7.4 <a href="lib-numerics.html#lib.gslice.array.fill"> [lib.gslice.array.fill]</a>, 26.3.8.4 <a href="lib-numerics.html#lib.mask.array.fill"> [lib.mask.array.fill]</a>, 26.3.9.4 <a href="lib-numerics.html#lib.indirect.array.fill"> [lib.indirect.array.fill]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Judy Ward <b>Date:</b> 15 Dec 1998 </p> <p>One of the operator= in the valarray helper arrays is const and one is not. For example, look at slice_array. This operator= in Section 26.3.5.2 <a href="lib-numerics.html#lib.slice.arr.assign"> [lib.slice.arr.assign]</a> is const: </p> @@ -1098,7 +1007,7 @@ text got garbled when the signed char/unsigned char specializations were removed. Dietmar will provide revised wording.]</i></p> <hr> <a name="179"><h3>179. Comparison of const_iterators to iterators doesn't work</h3></a><p> -<b>Section:</b> 23.1 <a href="lib-containers.html#lib.container.requirements"> [lib.container.requirements]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Judy Ward <b>Date:</b> 2 Jul 1998</p> +<b>Section:</b> 23.1 <a href="lib-containers.html#lib.container.requirements"> [lib.container.requirements]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Judy Ward <b>Date:</b> 2 Jul 1998</p> <p>Currently the following will not compile on two well-known standard library implementations:</p> @@ -1336,134 +1245,8 @@ function than as an allocator member function. For the latter, it is probably best thought of as an architectural limit. Nathan will provide new wording.]</i></p> <hr> -<a name="198"><h3>198. Validity of pointers and references unspecified after iterator destruction</h3></a><p> -<b>Section:</b> 24.1 <a href="lib-iterators.html#lib.iterator.requirements"> [lib.iterator.requirements]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Beman Dawes <b>Date:</b> 3 Nov 1999</p> -<p> -Is a pointer or reference obtained from an iterator still valid after -destruction of the iterator? -</p> -<p> -Is a pointer or reference obtained from an iterator still valid after the value -of the iterator changes? -</p> -<blockquote> -<pre> -#include <iostream> -#include <vector> -#include <iterator> - -int main() -{ - typedef std::vector<int> vec_t; - vec_t v; - v.push_back( 1 ); - - // Is a pointer or reference obtained from an iterator still - // valid after destruction of the iterator? - int * p = &*v.begin(); - std::cout << *p << '\n'; // OK? - - // Is a pointer or reference obtained from an iterator still - // valid after the value of the iterator changes? - vec_t::iterator iter( v.begin() ); - p = &*iter++; - std::cout << *p << '\n'; // OK? - - return 0; -} -</pre> -</blockquote> - -<p>The standard doesn't appear to directly address these -questions. The standard needs to be clarified. At least two real-world -cases have been reported where library implementors wasted -considerable effort because of the lack of clarity in the -standard. The question is important because requiring pointers and -references to remain valid has the effect for practical purposes of -prohibiting iterators from pointing to cached rather than actual -elements of containers.</p> - -<p>The standard itself assumes that pointers and references obtained -from an iterator are still valid after iterator destruction or -change. The definition of reverse_iterator::operator*(), 24.4.1.3.3 <a href="lib-iterators.html#lib.reverse.iter.op.star"> [lib.reverse.iter.op.star]</a>, which returns a reference, defines -effects:</p> - -<blockquote> - <pre>Iterator tmp = current; -return *--tmp;</pre> -</blockquote> -<p>The definition of reverse_iterator::operator->(), 24.4.1.3.4 <a href="lib-iterators.html#lib.reverse.iter.opref"> [lib.reverse.iter.opref]</a>, which returns a pointer, defines effects:</p> -<blockquote> - <pre>return &(operator*());</pre> -</blockquote> - -<p>Because the standard itself assumes pointers and references remain -valid after iterator destruction or change, the standard should say so -explicitly. This will also reduce the chance of user code breaking -unexpectedly when porting to a different standard library -implementation.</p> -<p><b>Proposed resolution:</b></p> -<p>Add a new paragraph to 24.1 <a href="lib-iterators.html#lib.iterator.requirements"> [lib.iterator.requirements]</a>:</p> -<blockquote> -Destruction of an iterator may invalidate pointers and references -previously obtained from that iterator. -</blockquote> - -<p>Replace paragraph 1 of 24.4.1.3.3 <a href="lib-iterators.html#lib.reverse.iter.op.star"> [lib.reverse.iter.op.star]</a> with:</p> - -<blockquote> -<p><b>Effects:</b></p> -<pre> - this->tmp = current; - --this->tmp; - return *this->tmp; -</pre> - -<p> -[<i>Note:</i> This operation must use an auxiliary member variable, -rather than a temporary variable, to avoid returning a reference that -persists beyond the lifetime of its associated iterator. (See -24.1 <a href="lib-iterators.html#lib.iterator.requirements"> [lib.iterator.requirements]</a>.) The name of this member variable is shown for -exposition only. <i>--end note</i>] -</p> -</blockquote> - -<p><i>[Post-Tokyo: The issue has been reformulated purely -in terms of iterators.]</i></p> - -<p><i>[Pre-Toronto: Steve Cleary pointed out the no-invalidation -assumption by reverse_iterator. The issue and proposed resolution was -reformulated yet again to reflect this reality.]</i></p> - -<p><i>[Copenhagen: Steve Cleary pointed out that reverse_iterator -assumes its underlying iterator has persistent pointers and -references. Andy Koenig pointed out that it is possible to rewrite -reverse_iterator so that it no longer makes such an assupmption. -However, this issue is related to issue <a href="lwg-active.html#299">299</a>. If we -decide it is intentional that <tt>p[n]</tt> may return by value -instead of reference when <tt>p</tt> is a Random Access Iterator, -other changes in reverse_iterator will be necessary.]</i></p> -<p><b>Rationale:</b></p> -<p>This issue has been discussed extensively. Note that it is -<i>not</i> an issue about the behavior of predefined iterators. It is -asking whether or not user-defined iterators are permitted to have -transient pointers and references. Several people presented examples -of useful user-defined iterators that have such a property; examples -include a B-tree iterator, and an "iota iterator" that doesn't point -to memory. Library implementors already seem to be able to cope with -such iterators: they take pains to avoid forming references to memory -that gets iterated past. The only place where this is a problem is -<tt>reverse_iterator</tt>, so this issue changes -<tt>reverse_iterator</tt> to make it work.</p> - -<p>This resolution does not weaken any guarantees provided by -predefined iterators like <tt>list<int>::iterator</tt>. -Clause 23 should be reviewed to make sure that guarantees for -predefined iterators are as strong as users expect.</p> - -<hr> <a name="200"><h3>200. Forward iterator requirements don't allow constant iterators</h3></a><p> -<b>Section:</b> 24.1.3 <a href="lib-iterators.html#lib.forward.iterators"> [lib.forward.iterators]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Matt Austern <b>Date:</b> 19 Nov 1999</p> +<b>Section:</b> 24.1.3 <a href="lib-iterators.html#lib.forward.iterators"> [lib.forward.iterators]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Matt Austern <b>Date:</b> 19 Nov 1999</p> <p> In table 74, the return type of the expression <tt>*a</tt> is given as <tt>T&</tt>, where <tt>T</tt> is the iterator's value type. @@ -1581,7 +1364,7 @@ clear how numeric_limits applies to each of those cases. A wholesale review of numeric_limits is needed. A paper would be welcome.]</i></p> <hr> <a name="202"><h3>202. unique() effects unclear when predicate not an equivalence relation</h3></a><p> -<b>Section:</b> 25.2.8 <a href="lib-algorithms.html#lib.alg.unique"> [lib.alg.unique]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Andrew Koenig <b>Date:</b> 13 Jan 2000</p> +<b>Section:</b> 25.2.8 <a href="lib-algorithms.html#lib.alg.unique"> [lib.alg.unique]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Andrew Koenig <b>Date:</b> 13 Jan 2000</p> <p> What should unique() do if you give it a predicate that is not an equivalence relation? There are at least two plausible answers: @@ -1652,7 +1435,7 @@ In fact, the SGI implementation of unique() does neither: It yields 1, <blockquote> For a nonempty range, eliminates all but the first element from every consecutive group of equivalent elements referred to by the iterator -<tt>i</tt> in the range (first, last) for which the following +<tt>i</tt> in the range [first+1, last) for which the following conditions hold: <tt>*(i-1) == *i</tt> or <tt>pred(*(i-1), *i) != false</tt>. </blockquote> @@ -1672,6 +1455,11 @@ pointed out that "i-1" is incorrect, since "i" can refer to iterator in the range. Matt provided wording to address this problem.]</i></p> +<p><i>[Curaçao: The LWG changed "... the range (first, +last)..." to "... the range [first+1, last)..." for +clarity. They considered this change close enough to editorial to not +require another round of review.]</i></p> + <p><b>Rationale:</b></p> <p>The LWG also considered an alternative resolution: change 25.2.8 <a href="lib-algorithms.html#lib.alg.unique"> [lib.alg.unique]</a> paragraph 1 to:</p> @@ -1795,6 +1583,13 @@ illegal, since, under certain circumstances, its semantics are not those specified in the standard. The standard's description of <tt>unique</tt> does not say that overloading <tt>adjacent_find</tt> should have any effect.]</i></p> + +<p><i>[Curaçao: An LWG-subgroup spent an afternoon working on issues +225, 226, and 229. Their conclusion was that the issues should be +separated into an LWG portion (Howard will write a proposal), and a +EWG portion (Dave will write a proposal). The LWG and EWG had +(separate) discussions of this plan the next day.]</i></p> + <hr> <a name="226"><h3>226. User supplied specializations or overloads of namespace std function templates</h3></a><p> <b>Section:</b> 17.4.3.1 <a href="lib-intro.html#lib.reserved.names"> [lib.reserved.names]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> Dave Abrahams <b>Date:</b> 01 Apr 2000</p> @@ -1867,6 +1662,19 @@ similar set of concerns was earlier raised on the boost.org mailing list and the ACCU-general mailing list. Also see library reflector message c++std-lib-7354.</p> +<p> +J. C. van Winkel points out (in c++std-lib-9565) another unexpected +fact: it's impossible to output a container of std::pair's using copy +and an ostream_iterator, as long as both pair-members are built-in or +std:: types. That's because a user-defined operator<< for (for +example) std::pair<const std::string, int> will not be found: +lookup for operator<< will be performed only in namespace std. +Opinions differed on whether or not this was a defect, and, if so, +whether the defect is that something is wrong with user-defined +functionality and std, or whether it's that the standard library does +not provide an operator<< for std::pair<>. +</p> + <p><b>Proposed resolution:</b></p> <p><i>[Tokyo: Summary, "There is no conforming way to extend @@ -1924,6 +1732,12 @@ unqualified call of <tt>swap</tt>. (And which other functions? Any?) A small group (Nathan, Howard, Jeremy, Dave, Matt, Walter, Marc) will try to put together a proposal before the next meeting.]</i></p> +<p><i>[Curaçao: An LWG-subgroup spent an afternoon working on issues +225, 226, and 229. Their conclusion was that the issues should be +separated into an LWG portion (Howard will write a proposal), and a +EWG portion (Dave will write a proposal). The LWG and EWG had +(separate) discussions of this plan the next day.]</i></p> + <hr> <a name="229"><h3>229. Unqualified references of other library entities</h3></a><p> <b>Section:</b> 17.4.1.1 <a href="lib-intro.html#lib.contents"> [lib.contents]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> Steve Clamage <b>Date:</b> 19 Apr 2000</p> @@ -1967,9 +1781,16 @@ are intended to be called by library code. Several LWG members are concerned that valarray appears to require argument-dependent lookup, but that the wording may not be clear enough to fall under "unless explicitly described otherwise".]</i></p> + +<p><i>[Curaçao: An LWG-subgroup spent an afternoon working on issues +225, 226, and 229. Their conclusion was that the issues should be +separated into an LWG portion (Howard will write a proposal), and a +EWG portion (Dave will write a proposal). The LWG and EWG had +(separate) discussions of this plan the next day.]</i></p> + <hr> <a name="231"><h3>231. Precision in iostream?</h3></a><p> -<b>Section:</b> 22.2.2.2.2 <a href="lib-locales.html#lib.facet.num.put.virtuals"> [lib.facet.num.put.virtuals]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> James Kanze, Stephen Clamage <b>Date:</b> 25 Apr 2000</p> +<b>Section:</b> 22.2.2.2.2 <a href="lib-locales.html#lib.facet.num.put.virtuals"> [lib.facet.num.put.virtuals]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> James Kanze, Stephen Clamage <b>Date:</b> 25 Apr 2000</p> <p>What is the following program supposed to output?</p> <pre>#include <iostream> @@ -2025,9 +1846,13 @@ for %f and %e, but not for %g: for %g, precision 0 is taken to be the same as precision 1.</p> <p>The proposed resolution has the effect that the output of the above program will be "1e+00".</p> + +<p><i>[Curaçao: Howard will send Matt improved wording dealing with +case not covered by current PR.]</i></p> + <hr> <a name="233"><h3>233. Insertion hints in associative containers</h3></a><p> -<b>Section:</b> 23.1.2 <a href="lib-containers.html#lib.associative.reqmts"> [lib.associative.reqmts]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Andrew Koenig <b>Date:</b> 30 Apr 2000</p> +<b>Section:</b> 23.1.2 <a href="lib-containers.html#lib.associative.reqmts"> [lib.associative.reqmts]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> Andrew Koenig <b>Date:</b> 30 Apr 2000</p> <p> If <tt>mm</tt> is a multimap and <tt>p</tt> is an iterator into the multimap, then <tt>mm.insert(p, x)</tt> inserts @@ -2095,18 +1920,21 @@ t is inserted adjacent to iterator p. <p><i>[Toronto: there was general agreement that this is a real defect: when inserting an element x into a multiset that already contains several copies of x, there is no way to know whether the hint will be -used. There was some support for an alternative resolution: we check -on both sides of the hint (both before and after, in that order). If -either is the correct location, the hint is used; otherwise it is not. -This would be different from the original proposed resolution, because -in the proposed resolution the hint will be used even if it is very -far from the insertion point. JC van Winkel supplied precise wording -for both options.]</i></p> - -<p><i>[Copenhagen: the LWG looked at both options, and preferred the -original. This preference is contingent on seeing a reference +used. The proposed resolution was that the new element should always +be inserted as close to the hint as possible. So, for example, if +there is a subsequence of equivalent values, then providing a.begin() +as the hint means that the new element should be inserted before the +subsequence even if a.begin() is far away. JC van Winkel supplied +precise wording for this proposed resolution, and also for an +alternative resolution in which hints are only used when they are +adjacent to the insertion point.]</i></p> + +<p><i>[Copenhagen: the LWG agreed to the original proposed resolution, +in which an insertion hint would be used even when it is far from the +insertion point. This was contingent on seeing a reference implementation showing that it is possible to implement this -requirement without loss of efficiency.]</i></p> +requirement without loss of efficiency. John Potter provided such a +reference implementation.]</i></p> <p><i>[Redmond: The LWG was reluctant to adopt the proposal that emerged from Copenhagen: it seemed excessively complicated, and went @@ -2117,92 +1945,12 @@ you can do it efficiently enough with a red-black tree, but there are other (perhaps better) balanced tree techniques that might differ enough to make the detailed semantics hard to satisfy."]</i></p> -<hr> -<a name="239"><h3>239. Complexity of unique() and/or unique_copy incorrect</h3></a><p> -<b>Section:</b> 25.2.8 <a href="lib-algorithms.html#lib.alg.unique"> [lib.alg.unique]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Angelika Langer <b>Date:</b> May 15 2000</p> -<p>The complexity of unique and unique_copy are inconsistent with each -other and inconsistent with the implementations. The standard -specifies:</p> - -<p>for unique():</p> - -<blockquote>-3- Complexity: If the range (last - first) is not empty, exactly -(last - first) - 1 applications of the corresponding predicate, otherwise -no applications of the predicate.</blockquote> - -<p>for unique_copy():</p> - -<blockquote>-7- Complexity: Exactly last - first applications of the corresponding -predicate.</blockquote> - -<p> -The implementations do it the other way round: unique() applies the -predicate last-first times and unique_copy() applies it last-first-1 -times.</p> - -<p>As both algorithms use the predicate for pair-wise comparison of -sequence elements I don't see a justification for unique_copy() -applying the predicate last-first times, especially since it is not -specified to which pair in the sequence the predicate is applied -twice.</p> -<p><b>Proposed resolution:</b></p> -<p>Change both complexity sections in 25.2.8 <a href="lib-algorithms.html#lib.alg.unique"> [lib.alg.unique]</a> to:</p> - -<blockquote>Complexity: For nonempty ranges, exactly last - first - 1 -applications of the corresponding predicate.</blockquote> - -<hr> -<a name="240"><h3>240. Complexity of adjacent_find() is meaningless</h3></a><p> -<b>Section:</b> 25.1.5 <a href="lib-algorithms.html#lib.alg.adjacent.find"> [lib.alg.adjacent.find]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Angelika Langer <b>Date:</b> May 15 2000</p> -<p>The complexity section of adjacent_find is defective:</p> - -<blockquote> -<pre> -template <class ForwardIterator> -ForwardIterator adjacent_find(ForwardIterator first, ForwardIterator last - BinaryPredicate pred); -</pre> - -<p>-1- Returns: The first iterator i such that both i and i + 1 are in -the range [first, last) for which the following corresponding -conditions hold: *i == *(i + 1), pred(*i, *(i + 1)) != false. Returns -last if no such iterator is found.</p> - -<p>-2- Complexity: Exactly find(first, last, value) - first applications -of the corresponding predicate. -</p> -</blockquote> - -<p>In the Complexity section, it is not defined what "value" -is supposed to mean. My best guess is that "value" means an -object for which one of the conditions pred(*i,value) or -pred(value,*i) is true, where i is the iterator defined in the Returns -section. However, the value type of the input sequence need not be -equality-comparable and for this reason the term find(first, last, -value) - first is meaningless.</p> - -<p>A term such as find_if(first, last, bind2nd(pred,*i)) - first or -find_if(first, last, bind1st(pred,*i)) - first might come closer to -the intended specification. Binders can only be applied to function -objects that have the function call operator declared const, which is -not required of predicates because they can have non-const data -members. For this reason, a specification using a binder could only be -an "as-if" specification.</p> -<p><b>Proposed resolution:</b></p> -<p>Change the complexity section in 25.1.5 <a href="lib-algorithms.html#lib.alg.adjacent.find"> [lib.alg.adjacent.find]</a> to:</p> -<blockquote> -For a nonempty range, exactly <tt>min((<i>i</i> - <i>first</i>) + 1, -(<i>last</i> - <i>first</i>) - 1)</tt> applications of the -corresponding predicate, where <i>i</i> is <tt>adjacent_find</tt>'s -return value. -</blockquote> - -<p><i>[Copenhagen: the original resolution specified an upper -bound. The LWG preferred an exact count.]</i></p> +<p><i>[Curaçao: Nathan should give us the alternative wording he +suggests so the LWG can decide between the two options.]</i></p> <hr> <a name="241"><h3>241. Does unique_copy() require CopyConstructible and Assignable?</h3></a><p> -<b>Section:</b> 25.2.8 <a href="lib-algorithms.html#lib.alg.unique"> [lib.alg.unique]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Angelika Langer <b>Date:</b> May 15 2000</p> +<b>Section:</b> 25.2.8 <a href="lib-algorithms.html#lib.alg.unique"> [lib.alg.unique]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Angelika Langer <b>Date:</b> May 15 2000</p> <p>Some popular implementations of unique_copy() create temporary copies of values in the input sequence, at least if the input iterator @@ -2231,11 +1979,12 @@ shall not overlap. <p>to:</p> <blockquote> --4- Requires: The ranges [first, last) and [result, result+(last-first)) -shall not overlap. The expression *result = *first must be valid. If -both InputIterator and OutputIterator do not meet the requirements of -forward iterator then the value type of InputIterator must be copy -constructible. Otherwise copy constructible is not required. + <p>-4- Requires: The ranges [first, last) and [result, + result+(last-first)) shall not overlap. The expression *result = + *first must be valid. If neither InputIterator nor OutputIterator + meets the requirements of forward iterator then the value type of + InputIterator must be copy constructible. Otherwise copy + constructible is not required. </p> </blockquote> <p><i>[Redmond: the original proposed resolution didn't impose an @@ -2247,6 +1996,13 @@ it might be possible to implement <tt>unique_copy</tt> without requiring assignability, although current implementations do impose that requirement. Howard provided new wording.]</i></p> +<p><i>[ +Curaçao: The LWG changed the PR editorially to specify +"neither...nor...meet..." as clearer than +"both...and...do not meet...". Change believed to be so +minor as not to require re-review. +]</i></p> + <hr> <a name="247"><h3>247. <tt>vector</tt>, <tt>deque::insert</tt> complexity</h3></a><p> <b>Section:</b> 23.2.4.3 <a href="lib-containers.html#lib.vector.modifiers"> [lib.vector.modifiers]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> Lisa Lippincott <b>Date:</b> 06 June 2000</p> @@ -2319,7 +2075,7 @@ complicated than a while loop whose body is a single-element insert.]</i></p> <hr> <a name="253"><h3>253. valarray helper functions are almost entirely useless</h3></a><p> -<b>Section:</b> 26.3.2.1 <a href="lib-numerics.html#lib.valarray.cons"> [lib.valarray.cons]</a>, 26.3.2.2 <a href="lib-numerics.html#lib.valarray.assign"> [lib.valarray.assign]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Robert Klarer <b>Date:</b> 31 Jul 2000</p> +<b>Section:</b> 26.3.2.1 <a href="lib-numerics.html#lib.valarray.cons"> [lib.valarray.cons]</a>, 26.3.2.2 <a href="lib-numerics.html#lib.valarray.assign"> [lib.valarray.assign]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Robert Klarer <b>Date:</b> 31 Jul 2000</p> <p>This discussion is adapted from message c++std-lib-7056 posted November 11, 1999. I don't think that anyone can reasonably claim that the problem described below is NAD.</p> @@ -2570,7 +2326,9 @@ copy constructor is potentially invoked during stack unwinding.</p> <p>The copy constructor is a more serious problem, becuase failure during stack unwinding invokes <tt>terminate</tt>. The copy -constructor must be nothrow.</p> +constructor must be nothrow. <i>Curaçao: Howard thinks this +requirement is already present.</i> +</p> <p>The fundamental problem is that it's difficult to get the nothrow requirement to work well with the requirement that the exception @@ -2607,6 +2365,8 @@ members thought there was a real defect lurking here. A small group (Herb, Kevlin, Howard, Martin, Dave) will try to make a recommendation.]</i></p> +<p><i>[Curaçao: Howard will nag the others to work on a recommendation.]</i></p> + <hr> <a name="258"><h3>258. Missing allocator requirement</h3></a><p> <b>Section:</b> 20.1.5 <a href="lib-utilities.html#lib.allocator.requirements"> [lib.allocator.requirements]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> Matt Austern <b>Date:</b> 22 Aug 2000</p> @@ -2678,457 +2438,8 @@ the second line from the bottom in table 32 already implies the desired property. This issue should be considered in light of other issues related to allocator instances.]</i></p> <hr> -<a name="270"><h3>270. Binary search requirements overly strict</h3></a><p> -<b>Section:</b> 25.3.3 <a href="lib-algorithms.html#lib.alg.binary.search"> [lib.alg.binary.search]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Matt Austern <b>Date:</b> 18 Oct 2000</p> -<p> -Each of the four binary search algorithms (lower_bound, upper_bound, -equal_range, binary_search) has a form that allows the user to pass a -comparison function object. According to 25.3, paragraph 2, that -comparison function object has to be a strict weak ordering. -</p> - -<p> -This requirement is slightly too strict. Suppose we are searching -through a sequence containing objects of type X, where X is some -large record with an integer key. We might reasonably want to look -up a record by key, in which case we would want to write something -like this: -</p> -<pre> - struct key_comp { - bool operator()(const X& x, int n) const { - return x.key() < n; - } - } - - std::lower_bound(first, last, 47, key_comp()); -</pre> - -<p> -key_comp is not a strict weak ordering, but there is no reason to -prohibit its use in lower_bound. -</p> - -<p> -There's no difficulty in implementing lower_bound so that it allows -the use of something like key_comp. (It will probably work unless an -implementor takes special pains to forbid it.) What's difficult is -formulating language in the standard to specify what kind of -comparison function is acceptable. We need a notion that's slightly -more general than that of a strict weak ordering, one that can encompass -a comparison function that involves different types. Expressing that -notion may be complicated. -</p> - -<p><i>Additional questions raised at the Toronto meeting:</i></p> -<ul> -<li> Do we really want to specify what ordering the implementor must - use when calling the function object? The standard gives - specific expressions when describing these algorithms, but it also - says that other expressions (with different argument order) are - equivalent.</li> -<li> If we are specifying ordering, note that the standard uses both - orderings when describing <tt>equal_range</tt>.</li> -<li> Are we talking about requiring these algorithms to work properly - when passed a binary function object whose two argument types - are not the same, or are we talking about requirements when - they are passed a binary function object with several overloaded - versions of <tt>operator()</tt>?</li> -<li> The definition of a strict weak ordering does not appear to give - any guidance on issues of overloading; it only discusses expressions, - and all of the values in these expressions are of the same type. - Some clarification would seem to be in order.</li> -</ul> - -<p><i>Additional discussion from Copenhagen:</i></p> -<ul> -<li>It was generally agreed that there is a real defect here: if -the predicate is merely required to be a Strict Weak Ordering, then -it's possible to pass in a function object with an overloaded -operator(), where the version that's actually called does something -completely inappropriate. (Such as returning a random value.)</li> - -<li>An alternative formulation was presented in a paper distributed by -David Abrahams at the meeting, "Binary Search with Heterogeneous -Comparison", J16-01/0027 = WG21 N1313: Instead of viewing the -predicate as a Strict Weak Ordering acting on a sorted sequence, view -the predicate/value pair as something that partitions a sequence. -This is almost equivalent to saying that we should view binary search -as if we are given a unary predicate and a sequence, such that f(*p) -is true for all p below a specific point and false for all p above it. -The proposed resolution is based on that alternative formulation.</li> -</ul> -<p><b>Proposed resolution:</b></p> - -<p>Change 25.3 [lib.alg.sorting] paragraph 3 from:</p> - -<blockquote> - 3 For all algorithms that take Compare, there is a version that uses - operator< instead. That is, comp(*i, *j) != false defaults to *i < - *j != false. For the algorithms to work correctly, comp has to - induce a strict weak ordering on the values. -</blockquote> - -<p>to:</p> - -<blockquote> - 3 For all algorithms that take Compare, there is a version that uses - operator< instead. That is, comp(*i, *j) != false defaults to *i - < *j != false. For algorithms other than those described in - lib.alg.binary.search (25.3.3) to work correctly, comp has to induce - a strict weak ordering on the values. -</blockquote> - -<p>Add the following paragraph after 25.3 [lib.alg.sorting] paragraph 5:</p> - -<blockquote> - -6- A sequence [start, finish) is partitioned with respect to an - expression f(e) if there exists an integer n such that - for all 0 <= i < distance(start, finish), f(*(begin+i)) is true if - and only if i < n. -</blockquote> - -<p>Change 25.3.3 [lib.alg.binary.search] paragraph 1 from:</p> - -<blockquote> - -1- All of the algorithms in this section are versions of binary - search and assume that the sequence being searched is in order - according to the implied or explicit comparison function. They work - on non-random access iterators minimizing the number of - comparisons, which will be logarithmic for all types of - iterators. They are especially appropriate for random access - iterators, because these algorithms do a logarithmic number of - steps through the data structure. For non-random access iterators - they execute a linear number of steps. -</blockquote> - -<p>to:</p> - -<blockquote> - -1- All of the algorithms in this section are versions of binary - search and assume that the sequence being searched is partitioned - with respect to an expression formed by binding the search key to - an argument of the implied or explicit comparison function. They - work on non-random access iterators minimizing the number of - comparisons, which will be logarithmic for all types of - iterators. They are especially appropriate for random access - iterators, because these algorithms do a logarithmic number of - steps through the data structure. For non-random access iterators - they execute a linear number of steps. -</blockquote> - -<p>Change 25.3.3.1 [lib.lower.bound] paragraph 1 from:</p> - -<blockquote> - -1- Requires: Type T is LessThanComparable - (lib.lessthancomparable). -</blockquote> - -<p>to:</p> - -<blockquote> - -1- Requires: The elements e of [first, last) are partitioned with - respect to the expression e < value or comp(e, value) -</blockquote> - - -<p>Remove 25.3.3.1 [lib.lower.bound] paragraph 2:</p> - -<blockquote> - -2- Effects: Finds the first position into which value can be - inserted without violating the ordering. -</blockquote> - -<p>Change 25.3.3.2 [lib.upper.bound] paragraph 1 from:</p> - -<blockquote> - -1- Requires: Type T is LessThanComparable (lib.lessthancomparable). -</blockquote> - -<p>to:</p> - -<blockquote> - -1- Requires: The elements e of [first, last) are partitioned with - respect to the expression !(value < e) or !comp(value, e) -</blockquote> - -<p>Remove 25.3.3.2 [lib.upper.bound] paragraph 2:</p> - -<blockquote> - -2- Effects: Finds the furthermost position into which value can be - inserted without violating the ordering. -</blockquote> - -<p>Change 25.3.3.3 [lib.equal.range] paragraph 1 from:</p> - -<blockquote> - -1- Requires: Type T is LessThanComparable - (lib.lessthancomparable). -</blockquote> - -<p>to:</p> - -<blockquote> - -1- Requires: The elements e of [first, last) are partitioned with - respect to the expressions e < value and !(value < e) or - comp(e, value) and !comp(value, e). Also, for all elements e of - [first, last), e < value implies !(value < e) or comp(e, - value) implies !comp(value, e) -</blockquote> - -<p>Change 25.3.3.3 [lib.equal.range] paragraph 2 from:</p> - -<blockquote> - -2- Effects: Finds the largest subrange [i, j) such that the value - can be inserted at any iterator k in it without violating the - ordering. k satisfies the corresponding conditions: !(*k < value) - && !(value < *k) or comp(*k, value) == false && comp(value, *k) == - false. -</blockquote> - -<p>to:</p> - -<pre> - -2- Returns: - make_pair(lower_bound(first, last, value), - upper_bound(first, last, value)) - or - make_pair(lower_bound(first, last, value, comp), - upper_bound(first, last, value, comp)) -</pre> - -<p>Change 25.3.3.3 [lib.binary.search] paragraph 1 from:</p> - -<blockquote> - -1- Requires: Type T is LessThanComparable - (lib.lessthancomparable). -</blockquote> - -<p>to:</p> - -<blockquote> - -1- Requires: The elements e of [first, last) are partitioned with - respect to the expressions e < value and !(value < e) or comp(e, - value) and !comp(value, e). Also, for all elements e of [first, - last), e < value implies !(value < e) or comp(e, value) implies - !comp(value, e) -</blockquote> - -<p><i>[Copenhagen: Dave Abrahams provided this wording]</i></p> - -<p><i>[Redmond: Minor changes in wording. (Removed "non-negative", and -changed the "other than those described in" wording.) Also, the LWG -decided to accept the "optional" part.]</i></p> - -<p><b>Rationale:</b></p> -<p>The proposed resolution reinterprets binary search. Instead of -thinking about searching for a value in a sorted range, we view that -as an important special case of a more general algorithm: searching -for the partition point in a partitioned range.</p> - -<p>We also add a guarantee that the old wording did not: we ensure -that the upper bound is no earlier than the lower bound, that -the pair returned by equal_range is a valid range, and that the first -part of that pair is the lower bound.</p> -<hr> -<a name="274"><h3>274. a missing/impossible allocator requirement</h3></a><p> -<b>Section:</b> 20.1.5 <a href="lib-utilities.html#lib.allocator.requirements"> [lib.allocator.requirements]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 02 Nov 2000</p> -<p> -I see that table 31 in 20.1.5, p3 allows T in std::allocator<T> to be of -any type. But the synopsis in 20.4.1 calls for allocator<>::address() to -be overloaded on reference and const_reference, which is ill-formed for -all T = const U. In other words, this won't work: -</p> - -<p> -template class std::allocator<const int>; -</p> - -<p> -The obvious solution is to disallow specializations of allocators on -const types. However, while containers' elements are required to be -assignable (which rules out specializations on const T's), I think that -allocators might perhaps be potentially useful for const values in other -contexts. So if allocators are to allow const types a partial -specialization of std::allocator<const T> would probably have to be -provided. -</p> -<p><b>Proposed resolution:</b></p> -<p>Change the text in row 1, column 2 of table 32 in 20.1.5, p3 from</p> - - <blockquote> - any type - </blockquote> - -<p>to</p> - <blockquote> - any non-const, non-reference type - </blockquote> - -<p><i>[Redmond: previous proposed resolution was "any non-const, -non-volatile, non-reference type". Got rid of the "non-volatile".]</i></p> - -<p><b>Rationale:</b></p> -<p> -Two resolutions were originally proposed: one that partially -specialized std::allocator for const types, and one that said an -allocator's value type may not be const. The LWG chose the second. -The first wouldn't be appropriate, because allocators are intended for -use by containers, and const value types don't work in containers. -Encouraging the use of allocators with const value types would only -lead to unsafe code. -</p> -<p> -The original text for proposed resolution 2 was modified so that it -also forbids volatile types and reference types. -</p> -<hr> -<a name="276"><h3>276. Assignable requirement for container value type overly strict</h3></a><p> -<b>Section:</b> 23.1 <a href="lib-containers.html#lib.container.requirements"> [lib.container.requirements]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Peter Dimov <b>Date:</b> 07 Nov 2000</p> -<p> -23.1/3 states that the objects stored in a container must be -Assignable. 23.3.1 <a href="lib-containers.html#lib.map"> [lib.map]</a>, paragraph 2, -states that map satisfies all requirements for a container, while in -the same time defining value_type as pair<const Key, T> - a type -that is not Assignable. -</p> - -<p> -It should be noted that there exists a valid and non-contradictory -interpretation of the current text. The wording in 23.1/3 avoids -mentioning value_type, referring instead to "objects stored in a -container." One might argue that map does not store objects of -type map::value_type, but of map::mapped_type instead, and that the -Assignable requirement applies to map::mapped_type, not -map::value_type. -</p> - -<p> -However, this makes map a special case (other containers store objects of -type value_type) and the Assignable requirement is needlessly restrictive in -general. -</p> - -<p> -For example, the proposed resolution of active library issue -<a href="lwg-defects.html#103">103</a> is to make set::iterator a constant iterator; this -means that no set operations can exploit the fact that the stored -objects are Assignable. -</p> - -<p> -This is related to, but slightly broader than, closed issue -<a href="lwg-closed.html#140">140</a>. -</p> -<p><b>Proposed resolution:</b></p> -<p>23.1/3: Strike the trailing part of the sentence:</p> - <blockquote> - , and the additional requirements of Assignable types from 23.1/3 - </blockquote> -<p>so that it reads:</p> - <blockquote> - -3- The type of objects stored in these components must meet the - requirements of CopyConstructible types (lib.copyconstructible). - </blockquote> - -<p>23.1/4: Modify to make clear that this requirement is not for all -containers. Change to:</p> - -<blockquote> --4- Table 64 defines the Assignable requirement. Some containers -require this property of the types to be stored in the container. T is -the type used to instantiate the container. t is a value of T, and u is -a value of (possibly const) T. -</blockquote> - -<p>23.1, Table 65: in the first row, change "T is Assignable" to "T is -CopyConstructible".</p> - -<p>23.2.1/2: Add sentence for Assignable requirement. Change to:</p> - -<blockquote> --2- A deque satisfies all of the requirements of a container and of a -reversible container (given in tables in lib.container.requirements) and -of a sequence, including the optional sequence requirements -(lib.sequence.reqmts). In addition to the requirements on the stored -object described in 23.1[lib.container.requirements], the stored object -must also meet the requirements of Assignable. Descriptions are -provided here only for operations on deque that are not described in one -of these tables or for operations where there is additional semantic -information. -</blockquote> - -<p>23.2.2/2: Add Assignable requirement to specific methods of list. -Change to:</p> - -<blockquote> -<p>-2- A list satisfies all of the requirements of a container and of a -reversible container (given in two tables in lib.container.requirements) -and of a sequence, including most of the the optional sequence -requirements (lib.sequence.reqmts). The exceptions are the operator[] -and at member functions, which are not provided. - -[Footnote: These member functions are only provided by containers whose -iterators are random access iterators. --- end foonote] -</p> - -<p>list does not require the stored type T to be Assignable unless the -following methods are instantiated: - -[Footnote: Implementors are permitted but not required to take advantage -of T's Assignable properties for these methods. -- end foonote] -</p> -<pre> - list<T,Allocator>& operator=(const list<T,Allocator>& x ); - template <class InputIterator> - void assign(InputIterator first, InputIterator last); - void assign(size_type n, const T& t); -</pre> - - -<p>Descriptions are provided here only for operations on list that are not -described in one of these tables or for operations where there is -additional semantic information.</p> -</blockquote> - -<p>23.2.4/2: Add sentence for Assignable requirement. Change to:</p> - -<blockquote> --2- A vector satisfies all of the requirements of a container and of a -reversible container (given in two tables in lib.container.requirements) -and of a sequence, including most of the optional sequence requirements -(lib.sequence.reqmts). The exceptions are the push_front and pop_front -member functions, which are not provided. In addition to the -requirements on the stored object described in -23.1[lib.container.requirements], the stored object must also meet the -requirements of Assignable. Descriptions are provided here only for -operations on vector that are not described in one of these tables or -for operations where there is additional semantic information. -</blockquote> -<p><b>Rationale:</b></p> -<p>list, set, multiset, map, multimap are able to store non-Assignables. -However, there is some concern about <tt>list<T></tt>: -although in general there's no reason for T to be Assignable, some -implementations of the member functions <tt>operator=</tt> and -<tt>assign</tt> do rely on that requirement. The LWG does not want -to forbid such implementations.</p> - -<p>Note that the type stored in a standard container must still satisfy -the requirements of the container's allocator; this rules out, for -example, such types as "const int". See issue <a href="lwg-active.html#274">274</a> -for more details. -</p> - -<p>In principle we could also relax the "Assignable" requirement for -individual <tt>vector</tt> member functions, such as -<tt>push_back</tt>. However, the LWG did not see great value in such -selective relaxation. Doing so would remove implementors' freedom to -implement <tt>vector::push_back</tt> in terms of -<tt>vector::insert</tt>.</p> - -<hr> <a name="278"><h3>278. What does iterator validity mean?</h3></a><p> -<b>Section:</b> 23.2.2.4 <a href="lib-containers.html#lib.list.ops"> [lib.list.ops]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> P.J. Plauger <b>Date:</b> 27 Nov 2000</p> +<b>Section:</b> 23.2.2.4 <a href="lib-containers.html#lib.list.ops"> [lib.list.ops]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> P.J. Plauger <b>Date:</b> 27 Nov 2000</p> <p> Section 23.2.2.4 [lib.list.ops] states that </p> @@ -3171,6 +2482,11 @@ has been invalidated is undefined.] <p><i>[Redmond: General agreement with the intent, some objections to the wording. Dave provided new wording.]</i></p> +<p><i>[Curaçao: The definition of "singular" is +contentious. The 278 resolution must be made consistent with +issue <a href="lwg-defects.html#208">208</a> and 24.1/5. Furthermore, a Rationale paragraph +is required.]</i></p> + <hr> <a name="280"><h3>280. Comparison of reverse_iterator to const reverse_iterator</h3></a><p> <b>Section:</b> 24.4.1 <a href="lib-iterators.html#lib.reverse.iterators"> [lib.reverse.iterators]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> Steve Cleary <b>Date:</b> 27 Nov 2000</p> @@ -3277,9 +2593,12 @@ floating-point input even though this is unambiguously required by the standard. ]</i></p> +<p><i>[Curaçao: Howard will email Bill and other implementors to try to +move the issue forward.]</i></p> + <hr> <a name="283"><h3>283. std::replace() requirement incorrect/insufficient</h3></a><p> -<b>Section:</b> 25.2.4 <a href="lib-algorithms.html#lib.alg.replace"> [lib.alg.replace]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 15 Dec 2000</p> +<b>Section:</b> 25.2.4 <a href="lib-algorithms.html#lib.alg.replace"> [lib.alg.replace]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 15 Dec 2000</p> <p> The requirements in 25.2.4 <a href="lib-algorithms.html#lib.alg.replace"> [lib.alg.replace]</a>, p1 that <tt>T</tt> to be <tt>Assignable</tt> (23.1 <a href="lib-containers.html#lib.container.requirements"> [lib.container.requirements]</a>) is not necessary or @@ -3526,53 +2845,10 @@ std::iterator_traits<ForwardIterator>::value_type must be Assignable (23.1 <a href="lib-containers.html#lib.container.requirements"> [lib.container.requirements]</a>). </blockquote> -<hr> -<a name="284"><h3>284. unportable example in 20.3.7, p6</h3></a><p> -<b>Section:</b> 20.3.7 <a href="lib-utilities.html#lib.function.pointer.adaptors"> [lib.function.pointer.adaptors]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 26 Dec 2000</p> -<p>The example in 20.3.7 <a href="lib-utilities.html#lib.function.pointer.adaptors"> [lib.function.pointer.adaptors]</a>, p6 shows how to use the C -library function <tt>strcmp()</tt> with the function pointer adapter -<tt>ptr_fun()</tt>. But since it's unspecified whether the C library -functions have <tt>extern "C"</tt> or <tt>extern -"C++"</tt> linkage [17.4.2.2 <a href="lib-intro.html#lib.using.linkage"> [lib.using.linkage]</a>], and since -function pointers with different the language linkage specifications -(7.5 <a href="dcl.html#dcl.link"> [dcl.link]</a>) are incompatible, whether this example is -well-formed is unspecified. -</p> -<p><b>Proposed resolution:</b></p> -<p>Change 20.3.7 <a href="lib-utilities.html#lib.function.pointer.adaptors"> [lib.function.pointer.adaptors]</a> paragraph 6 from:</p> -<blockquote> - <p>[<i>Example:</i> -</p> - <pre> - replace_if(v.begin(), v.end(), not1(bind2nd(ptr_fun(strcmp), "C")), "C++"); - </pre> - <p>replaces each <tt>C</tt> with <tt>C++</tt> in sequence <tt>v</tt>.</p> -</blockquote> - - -<p>to:</p> -<blockquote> - <p>[<i>Example:</i> -</p> - <pre> - int compare(const char*, const char*); - replace_if(v.begin(), v.end(), - not1(bind2nd(ptr_fun(compare), "abc")), "def"); - </pre> - <p>replaces each <tt>abc</tt> with <tt>def</tt> in sequence <tt>v</tt>.</p> -</blockquote> - -<p>Also, remove footnote 215 in that same paragraph.</p> - -<p><i>[Copenhagen: Minor change in the proposed resolution. Since this -issue deals in part with C and C++ linkage, it was believed to be too -confusing for the strings in the example to be "C" and "C++". -]</i></p> - -<p><i>[Redmond: More minor changes. Got rid of the footnote (which -seems to make a sweeping normative requirement, even though footnotes -aren't normative), and changed the sentence after the footnote so that -it corresponds to the new code fragment.]</i></p> +<p><i>[Curaçao: Jeremy reports he has run the changes through his +automated test tools. At the request of the LWG, Jeremy will reword +the PR in terms of valid expressions rather than "equality +operator".]</i></p> <hr> <a name="290"><h3>290. Requirements to for_each and its function object</h3></a><p> @@ -3621,7 +2897,7 @@ blanket statement in Clause 25, not just a special requirement for <hr> <a name="291"><h3>291. Underspecification of set algorithms</h3></a><p> -<b>Section:</b> 25.3.5 <a href="lib-algorithms.html#lib.alg.set.operations"> [lib.alg.set.operations]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> Matt Austern <b>Date:</b> 03 Jan 2001</p> +<b>Section:</b> 25.3.5 <a href="lib-algorithms.html#lib.alg.set.operations"> [lib.alg.set.operations]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Matt Austern <b>Date:</b> 03 Jan 2001</p> <p> The standard library contains four algorithms that compute set operations on sorted ranges: <tt>set_union</tt>, <tt>set_intersection</tt>, @@ -3671,8 +2947,50 @@ same way. </p> <p><b>Proposed resolution:</b></p> -<p><i>[The LWG agrees that the standard should answer these questions. -Matt will provide wording.]</i></p> + +<p>Add the following to the end of 25.3.5.2 <a href="lib-algorithms.html#lib.set.union"> [lib.set.union]</a> paragraph 5:</p> +<blockquote> +If [first1, last1) contains <i>m</i> elements that are equivalent to +each other and [first2, last2) contains <i>n</i> elements that are +equivalent to them, then max(<i>m</i>, <i>n</i>) of these elements +will be copied to the output range: all <i>m</i> of these elements +from [first1, last1), and the last max(<i>n-m</i>, 0) of them from +[first2, last2), in that order. +</blockquote> + +<p>Add the following to the end of 25.3.5.3 <a href="lib-algorithms.html#lib.set.intersection"> [lib.set.intersection]</a> paragraph 5:</p> +<blockquote> +If [first1, last1) contains <i>m</i> elements that are equivalent to each +other and [first2, last2) contains <i>n</i> elements that are +equivalent to them, the first min(<i>m</i>, <i>n</i>) of those +elements from [first1, last1) are copied to the output range. +</blockquote> + +<p>Add a new paragraph, <b>Notes</b>, after 25.3.5.4 <a href="lib-algorithms.html#lib.set.difference"> [lib.set.difference]</a> +paragraph 4:</p> +<blockquote> +If [first1, last1) contains <i>m</i> elements that are equivalent to each +other and [first2, last2) contains <i>n</i> elements that are +equivalent to them, the last max(<i>m-n</i>, 0) elements from +[first1, last1) are copied to the output range. +</blockquote> + +<p>Add a new paragraph, <b>Notes</b>, after 25.3.5.5 <a href="lib-algorithms.html#lib.set.symmetric.difference"> [lib.set.symmetric.difference]</a> +paragraph 4:</p> +<blockquote> +If [first1, last1) contains <i>m</i> elements that are equivalent to +each other and [first2, last2) contains <i>n</i> elements that are +equivalent to them, then |<i>m - n</i>| of those elements will be +copied to the output range: the last <i>m - n</i> of these elements +from [first1, last1) if <i>m</i> > <i>n</i>, and the last <i>n - +m</i> of these elements from [first2, last2) if <i>m</i> < <i>n</i>. +</blockquote> + +<p><i>[Curaçao: Missing Rationale and missing status comments from +Redmond made discussion difficult. For union, doesn't the standard +already say this? Howard, others think maybe so. Several thought the +PR may be "too complicated".]</i></p> + <hr> <a name="294"><h3>294. User defined macros and standard headers</h3></a><p> <b>Section:</b> 17.4.3.1.1 <a href="lib-intro.html#lib.macro.names"> [lib.macro.names]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> James Kanze <b>Date:</b> 11 Jan 2001</p> @@ -3768,6 +3086,8 @@ about issue 299 should keep this possibility in mind. <p>In section 24.1.5 <a href="lib-iterators.html#lib.random.access.iterators"> [lib.random.access.iterators]</a>, change the return type in table 76 from "convertible to T" to T&.</p> +<p><i>[Curaçao: Jeremy volunteered to work on this issue.]</i></p> + <hr> <a name="300"><h3>300. list::merge() specification incomplete</h3></a><p> <b>Section:</b> 23.2.2.4 <a href="lib-containers.html#lib.list.ops"> [lib.list.ops]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> John Pedretti <b>Date:</b> 23 Jan 2001</p> @@ -3794,6 +3114,8 @@ Changing p23, without changing the other two, appears to introduce contradictions. Additionally, "merges the argument list into the list" is excessively vague.]</i></p> +<p><i>[Curaçao: Robert Klarer volunteers to work on this issue.]</i></p> + <hr> <a name="304"><h3>304. Must <tt>*a</tt> return an lvalue when <tt>a</tt> is an input iterator?</h3></a><p> <b>Section:</b> 24.1 <a href="lib-iterators.html#lib.iterator.requirements"> [lib.iterator.requirements]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> Dave Abrahams <b>Date:</b> 5 Feb 2001</p> @@ -3834,7 +3156,7 @@ it has no <tt>operator-></tt>. A straw poll showed roughly equal support for the two options.]</i></p> <hr> <a name="305"><h3>305. Default behavior of codecvt<wchar_t, char, mbstate_t>::length()</h3></a><p> -<b>Section:</b> 22.2.1.5.2 <a href="lib-locales.html#lib.locale.codecvt.virtuals"> [lib.locale.codecvt.virtuals]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Howard Hinnant <b>Date:</b> 24 Jan 2001</p> +<b>Section:</b> 22.2.1.5.2 <a href="lib-locales.html#lib.locale.codecvt.virtuals"> [lib.locale.codecvt.virtuals]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Howard Hinnant <b>Date:</b> 24 Jan 2001</p> <p>22.2.1.5/3 introduces codecvt in part with:</p> <blockquote> @@ -3939,8 +3261,12 @@ would expect the default encoding to be whatever C uses in the default "C" locale. We could impose a guarantee like the one Nathan suggested (a character from the basic execution character set must map to a single external character), but this would rule out important -encodings that are in common use: it would rule out Shift-JIS, for +encodings that are in common use: it would rule out JIS, for example, and it would rule out a fixed-width encoding of UCS-4.</p> + +<p><i>[Curaçao: fixed rationale typo at the request of Ichiro Koshida; +"shift-JIS" changed to "JIS".]</i></p> + <hr> <a name="309"><h3>309. Does sentry catch exceptions?</h3></a><p> <b>Section:</b> 27.6 <a href="lib-iostreams.html#lib.iostream.format"> [lib.iostream.format]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 19 Mar 2001</p> @@ -4045,269 +3371,8 @@ the sentries. ]</i></p> <hr> -<a name="310"><h3>310. Is errno a macro?</h3></a><p> -<b>Section:</b> 17.4.1.2 <a href="lib-intro.html#lib.headers"> [lib.headers]</a>, 19.3 <a href="lib-diagnostics.html#lib.errno"> [lib.errno]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Steve Clamage <b>Date:</b> 21 Mar 2001</p> - <p> - Exactly how should errno be declared in a conforming C++ header? - </p> - - <p> - The C standard says in 7.1.4 that it is unspecified whether errno is a - macro or an identifier with external linkage. In some implementations - it can be either, depending on compile-time options. (E.g., on - Solaris in multi-threading mode, errno is a macro that expands to a - function call, but is an extern int otherwise. "Unspecified" allows - such variability.) - </p> - - <p>The C++ standard:</p> - <ul> - <li>17.4.1.2 says in a note that errno must be macro in C. (false)</li> - <li>17.4.3.1.3 footnote 166 says errno is reserved as an external - name (true), and implies that it is an identifier.</li> - <li>19.3 simply lists errno as a macro (by what reasoning?) and goes - on to say that the contents of of C++ <errno.h> are the - same as in C, begging the question.</li> - <li>C.2, table 95 lists errno as a macro, without comment.</li> - </ul> - - <p>I find no other references to errno.</p> - - <p>We should either explicitly say that errno must be a macro, even - though it need not be a macro in C, or else explicitly leave it - unspecified. We also need to say something about namespace std. - A user who includes <cerrno> needs to know whether to write - <tt>errno</tt>, or <tt>::errno</tt>, or <tt>std::errno</tt>, or - else <cerrno> is useless.</p> - - <p>Two acceptable fixes:</p> - <ul> - <li><p>errno must be a macro. This is trivially satisfied by adding<br> - #define errno (::std::errno)<br> - to the headers if errno is not already a macro. You then always - write errno without any scope qualification, and it always expands - to a correct reference. Since it is always a macro, you know to - avoid using errno as a local identifer.</p></li> - <li><p>errno is in the global namespace. This fix is inferior, because - ::errno is not guaranteed to be well-formed.</p></li> - </ul> - - <p><i>[ - This issue was first raised in 1999, but it slipped through - the cracks. - ]</i></p> -<p><b>Proposed resolution:</b></p> - <p>Change the Note in section 17.4.1.2p5 from</p> - - <blockquote> - Note: the names defined as macros in C include the following: - assert, errno, offsetof, setjmp, va_arg, va_end, and va_start. - </blockquote> - - <p>to</p> - - <blockquote> - Note: the names defined as macros in C include the following: - assert, offsetof, setjmp, va_arg, va_end, and va_start. - </blockquote> - - <p>In section 19.3, change paragraph 2 from</p> - - <blockquote> - The contents are the same as the Standard C library header - <errno.h>. - </blockquote> - - <p>to</p> - - <blockquote> - The contents are the same as the Standard C library header - <errno.h>, except that errno shall be defined as a macro. - </blockquote> -<p><b>Rationale:</b></p> -<p>C++ must not leave it up to the implementation to decide whether -or not a name is a macro; it must explicitly specify exactly which -names are required to be macros.</p> -<hr> -<a name="311"><h3>311. Incorrect wording in basic_ostream class synopsis</h3></a><p> -<b>Section:</b> 27.6.2.1 <a href="lib-iostreams.html#lib.ostream"> [lib.ostream]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Andy Sawyer <b>Date:</b> 21 Mar 2001</p> - -<p>In 27.6.2.1 <a href="lib-iostreams.html#lib.ostream"> [lib.ostream]</a>, the synopsis of class basic_ostream says:</p> - -<pre> - // partial specializationss - template<class traits> - basic_ostream<char,traits>& operator<<( basic_ostream<char,traits>&, - const char * ); -</pre> - -<p>Problems:</p> -<ul> -<li>Too many 's's at the end of "specializationss" </li> -<li>This is an overload, not a partial specialization</li> -</ul> - -<p><b>Proposed resolution:</b></p> -<p>In the synopsis in 27.6.2.1 <a href="lib-iostreams.html#lib.ostream"> [lib.ostream]</a>, remove the -<i>// partial specializationss</i> comment. Also remove the same -comment (correctly spelled, but still incorrect) from the synopsis in -27.6.2.5.4 <a href="lib-iostreams.html#lib.ostream.inserters.character"> [lib.ostream.inserters.character]</a>. -</p> - -<p><i>[ -Pre-Redmond: added 27.6.2.5.4 <a href="lib-iostreams.html#lib.ostream.inserters.character"> [lib.ostream.inserters.character]</a> because of Martin's -comment in c++std-lib-8939. -]</i></p> - -<hr> -<a name="315"><h3>315. Bad "range" in list::unique complexity</h3></a><p> -<b>Section:</b> 23.2.2.4 <a href="lib-containers.html#lib.list.ops"> [lib.list.ops]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Andy Sawyer <b>Date:</b> 1 May 2001</p> -<p> -23.2.2.4 <a href="lib-containers.html#lib.list.ops"> [lib.list.ops]</a>, Para 21 describes the complexity of -list::unique as: "If the range (last - first) is not empty, exactly -(last - first) -1 applications of the corresponding predicate, -otherwise no applications of the predicate)". -</p> - -<p> -"(last - first)" is not a range. -</p> -<p><b>Proposed resolution:</b></p> -<p> -Change the "range" from (last - first) to [first, last). -</p> -<hr> -<a name="316"><h3>316. Vague text in Table 69</h3></a><p> -<b>Section:</b> 23.1.2 <a href="lib-containers.html#lib.associative.reqmts"> [lib.associative.reqmts]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 4 May 2001</p> -<p>Table 69 says this about a_uniq.insert(t):</p> - -<blockquote> -inserts t if and only if there is no element in the container with key -equivalent to the key of t. The bool component of the returned pair -indicates whether the insertion takes place and the iterator component of the -pair points to the element with key equivalent to the key of t. -</blockquote> - -<p>The description should be more specific about exactly how the bool component -indicates whether the insertion takes place.</p> -<p><b>Proposed resolution:</b></p> -<p>Change the text in question to</p> - -<blockquote> -...The bool component of the returned pair is true if and only if the insertion -takes place... -</blockquote> -<hr> -<a name="317"><h3>317. Instantiation vs. specialization of facets</h3></a><p> -<b>Section:</b> 22 <a href="lib-locales.html#lib.localization"> [lib.localization]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 4 May 2001</p> -<p> -The localization section of the standard refers to specializations of -the facet templates as instantiations even though the required facets -are typically specialized rather than explicitly (or implicitly) -instantiated. In the case of ctype<char> and -ctype_byname<char> (and the wchar_t versions), these facets are -actually required to be specialized. The terminology should be -corrected to make it clear that the standard doesn't mandate explicit -instantiation (the term specialization encompasses both explicit -instantiations and specializations). -</p> -<p><b>Proposed resolution:</b></p> -<p> -In the following paragraphs, replace all occurrences of the word -instantiation or instantiations with specialization or specializations, -respectively: -</p> - -<blockquote> -22.1.1.1.1, p4, Table 52, 22.2.1.1, p2, 22.2.1.5, p3, 22.2.1.5.1, p5, -22.2.1.5.2, p10, 22.2.2, p2, 22.2.3.1, p1, 22.2.3.1.2, p1, p2 and p3, -22.2.4.1, p1, 22.2.4.1.2, p1, 22,2,5, p1, 22,2,6, p2, 22.2.6.3.2, p7, and -Footnote 242. -</blockquote> - -<p>And change the text in 22.1.1.1.1, p4 from</p> - -<blockquote> - An implementation is required to provide those instantiations - for facet templates identified as members of a category, and - for those shown in Table 52: -</blockquote> - -<p>to</p> - -<blockquote> - An implementation is required to provide those specializations... -</blockquote> - -<p><i>[Nathan will review these changes, and will look for places where -explicit specialization is necessary.]</i></p> - -<p><b>Rationale:</b></p> -<p>This is a simple matter of outdated language. The language to -describe templates was clarified during the standardization process, -but the wording in clause 22 was never updated to reflect that -change.</p> -<hr> -<a name="318"><h3>318. Misleading comment in definition of numpunct_byname</h3></a><p> -<b>Section:</b> 22.2.3.2 <a href="lib-locales.html#lib.locale.numpunct.byname"> [lib.locale.numpunct.byname]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 12 May 2001</p> -<p>The definition of the numpunct_byname template contains the following -comment:</p> - -<pre> - namespace std { - template <class charT> - class numpunct_byname : public numpunct<charT> { - // this class is specialized for char and wchar_t. - ... -</pre> - -<p>There is no documentation of the specializations and it seems -conceivable that an implementation will not explicitly specialize the -template at all, but simply provide the primary template.</p> -<p><b>Proposed resolution:</b></p> -<p>Remove the comment from the text in 22.2.3.2 and from the proposed -resolution of library issue <a href="lwg-defects.html#228">228</a>.</p> -<hr> -<a name="319"><h3>319. Storage allocation wording confuses "Required behavior", "Requires"</h3></a><p> -<b>Section:</b> 18.4.1.1 <a href="lib-support.html#lib.new.delete.single"> [lib.new.delete.single]</a>, 18.4.1.2 <a href="lib-support.html#lib.new.delete.array"> [lib.new.delete.array]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Beman Dawes <b>Date:</b> 15 May 2001</p> -<p>The standard specifies 17.3.1.3 <a href="lib-intro.html#lib.structure.specifications"> [lib.structure.specifications]</a> that "Required -behavior" elements describe "the semantics of a function definition -provided by either the implementation or a C++ program."</p> - -<p>The standard specifies 17.3.1.3 <a href="lib-intro.html#lib.structure.specifications"> [lib.structure.specifications]</a> that "Requires" -elements describe "the preconditions for calling the function."</p> - -<p>In the sections noted below, the current wording specifies -"Required Behavior" for what are actually preconditions, and thus -should be specified as "Requires".</p> - -<p><b>Proposed resolution:</b></p> - -<p>In 18.4.1.1 <a href="lib-support.html#lib.new.delete.single"> [lib.new.delete.single]</a> Para 12 Change:</p> -<blockquote> - <p>Required behavior: accept a value of ptr that is null or that was - returned by an earlier call ...</p> -</blockquote> -<p>to:</p> -<blockquote> - <p>Requires: the value of ptr is null or the value returned by an - earlier call ...</p> -</blockquote> - -<p>In 18.4.1.2 <a href="lib-support.html#lib.new.delete.array"> [lib.new.delete.array]</a> Para 11 Change:</p> -<blockquote> - <p>Required behavior: accept a value of ptr that is null or that was - returned by an earlier call ...</p> -</blockquote> -<p>to:</p> -<blockquote> - <p>Requires: the value of ptr is null or the value returned by an - earlier call ...</p> -</blockquote> - -<hr> <a name="320"><h3>320. list::assign overspecified</h3></a><p> -<b>Section:</b> 23.2.2.1 <a href="lib-containers.html#lib.list.cons"> [lib.list.cons]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Howard Hinnant <b>Date:</b> 17 May 2001</p> +<b>Section:</b> 23.2.2.1 <a href="lib-containers.html#lib.list.cons"> [lib.list.cons]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Howard Hinnant <b>Date:</b> 17 May 2001</p> <p> Section 23.2.2.1, paragraphs 6-8 specify that list assign (both forms) have the "effects" of a call to erase followed by a call to insert. @@ -4351,11 +3416,15 @@ Metrowerks and SGI recycle nodes, Dinkumware and Rogue Wave don't. </blockquote> <p>In 23.1.1 <a href="lib-containers.html#lib.sequence.reqmts"> [lib.sequence.reqmts]</a>, in Table 67 (sequence requirements), -add a new row:</p> +add two new rows:</p> <pre> a.assign(i,j) void pre: i,j are not iterators into a. - Replaces elements in a with copies - of elements in [i, j). + Replaces elements in a with a copy + of [i, j). + + a.assign(n,t) void pre: t is not a reference into a. + Replaces elements in a with n copies + of t. </pre> <p>Change 23.2.2.1/8 from:</p> @@ -4380,58 +3449,14 @@ Also, the change in the sequence requirements is new. Without that change, the proposed resolution would have required that assignment of a subrange would have to work. That too would have been overspecification; it would effectively mandate that assignment use a -temporary. +temporary. Howard provided wording. ]</i></p> -<hr> -<a name="321"><h3>321. Typo in num_get</h3></a><p> -<b>Section:</b> 22.2.2.1.2 <a href="lib-locales.html#lib.facet.num.get.virtuals"> [lib.facet.num.get.virtuals]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Kevin Djang <b>Date:</b> 17 May 2001</p> -<p> -Section 22.2.2.1.2 at p7 states that "A length specifier is added to -the conversion function, if needed, as indicated in Table 56." -However, Table 56 uses the term "length modifier", not "length -specifier". -</p> -<p><b>Proposed resolution:</b></p> -<p> -In 22.2.2.1.2 at p7, change the text "A length specifier is added ..." -to be "A length modifier is added ..." -</p> -<p><b>Rationale:</b></p> -<p>C uses the term "length modifier". We should be consistent.</p> -<hr> -<a name="322"><h3>322. iterator and const_iterator should have the same value type</h3></a><p> -<b>Section:</b> 23.1 <a href="lib-containers.html#lib.container.requirements"> [lib.container.requirements]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Matt Austern <b>Date:</b> 17 May 2001</p> -<p> -It's widely assumed that, if X is a container, -iterator_traits<X::iterator>::value_type and -iterator_traits<X::const_iterator>::value_type should both be -X::value_type. However, this is nowhere stated. The language in -Table 65 is not precise about the iterators' value types (it predates -iterator_traits), and could even be interpreted as saying that -iterator_traits<X::const_iterator>::value_type should be "const -X::value_type". -</p> +<p><i>[Curaçao: Made editorial improvement in wording; changed +"Replaces elements in a with copies of elements in [i, j)." +with "Replaces the elements of a with a copy of [i, j)." +Changes not deemed serious enough to requre rereview.]</i></p> -<p>Related issue: <a href="lwg-closed.html#279">279</a>.</p> -<p><b>Proposed resolution:</b></p> -<p>In Table 65 ("Container Requirements"), change the return type for -X::iterator to "iterator type whose value type is T". Change the -return type for X::const_iterator to "constant iterator type whose -value type is T".</p> -<p><b>Rationale:</b></p> -<p> -This belongs as a container requirement, rather than an iterator -requirement, because the whole notion of iterator/const_iterator -pairs is specific to containers' iterator. -</p> -<p> -It is existing practice that (for example) -iterator_traits<list<int>::const_iterator>::value_type -is "int", rather than "const int". This is consistent with -the way that const pointers are handled: the standard already -requires that iterator_traits<const int*>::value_type is int. -</p> <hr> <a name="323"><h3>323. abs() overloads in different headers</h3></a><p> <b>Section:</b> 26.5 <a href="lib-numerics.html#lib.c.math"> [lib.c.math]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> Dave Abrahams <b>Date:</b> 4 June 2001</p> @@ -4487,7 +3512,7 @@ defined in which headers. (See issue <a href="lwg-closed.html#343">343</a>)]</i> <hr> <a name="324"><h3>324. Do output iterators have value types?</h3></a><p> -<b>Section:</b> 24.1.2 <a href="lib-iterators.html#lib.output.iterators"> [lib.output.iterators]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Dave Abrahams <b>Date:</b> 7 June 2001</p> +<b>Section:</b> 24.1.2 <a href="lib-iterators.html#lib.output.iterators"> [lib.output.iterators]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Dave Abrahams <b>Date:</b> 7 June 2001</p> <p>Table 73 suggests that output iterators have value types. It requires the expression "*a = t". Additionally, although Table 73 @@ -4540,7 +3565,7 @@ output iterators' pointer and reference types?</p> <blockquote> <p>All iterators <tt>i</tt> support the expression <tt>*i</tt>, resulting in a value of some class, enumeration, or built-in type <tt>T</tt>, -called the value type of the itereator.</p> +called the value type of the iterator.</p> </blockquote> <p>to</p> @@ -4611,7 +3636,7 @@ and any language suggesting otherwise is simply a mistake.</p> decision.</p> <hr> <a name="325"><h3>325. Misleading text in moneypunct<>::do_grouping</h3></a><p> -<b>Section:</b> 22.2.6.3.2 <a href="lib-locales.html#lib.locale.moneypunct.virtuals"> [lib.locale.moneypunct.virtuals]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 02 Jul 2001</p> +<b>Section:</b> 22.2.6.3.2 <a href="lib-locales.html#lib.locale.moneypunct.virtuals"> [lib.locale.moneypunct.virtuals]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 02 Jul 2001</p> <p>The Returns clause in 22.2.6.3.2, p3 says about moneypunct<charT>::do_grouping() </p> @@ -4663,47 +3688,8 @@ locale. It is just a reminder that the values are interpreted as small integers, not ASCII characters. </p> <hr> -<a name="327"><h3>327. Typo in time_get facet in table 52</h3></a><p> -<b>Section:</b> 22.1.1.1.1 <a href="lib-locales.html#lib.locale.category"> [lib.locale.category]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Tiki Wan <b>Date:</b> 06 Jul 2001</p> -<p>The <tt>wchar_t</tt> versions of <tt>time_get</tt> and -<tt>time_get_byname</tt> are listed incorrectly in table 52, -required instantiations. In both cases the second template -parameter is given as OutputIterator. It should instead be -InputIterator, since these are input facets.</p> -<p><b>Proposed resolution:</b></p> -<p> -In table 52, required instantiations, in -22.1.1.1.1 <a href="lib-locales.html#lib.locale.category"> [lib.locale.category]</a>, change</p> -<pre> - time_get<wchar_t, OutputIterator> - time_get_byname<wchar_t, OutputIterator> -</pre> -<p>to</p> -<pre> - time_get<wchar_t, InputIterator> - time_get_byname<wchar_t, InputIterator> -</pre> - -<p><i>[Redmond: Very minor change in proposed resolution. Original had -a typo, wchart instead of wchar_t.]</i></p> - -<hr> -<a name="328"><h3>328. Bad sprintf format modifier in money_put<>::do_put()</h3></a><p> -<b>Section:</b> 22.2.6.2.2 <a href="lib-locales.html#lib.locale.money.put.virtuals"> [lib.locale.money.put.virtuals]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 07 Jul 2001</p> -<p>The sprintf format string , "%.01f" (that's the digit one), in the -description of the do_put() member functions of the money_put facet in -22.2.6.2.2, p1 is incorrect. First, the f format specifier is wrong -for values of type long double, and second, the precision of 01 -doesn't seem to make sense. What was most likely intended was -"%.0Lf"., that is a precision of zero followed by the L length -modifier.</p> -<p><b>Proposed resolution:</b></p> -<p>Change the format string to "%.0Lf".</p> -<p><b>Rationale:</b></p> -<p>Fixes an obvious typo</p> -<hr> <a name="329"><h3>329. vector capacity, reserve and reallocation</h3></a><p> -<b>Section:</b> 23.2.4.2 <a href="lib-containers.html#lib.vector.capacity"> [lib.vector.capacity]</a>, 23.2.4.3 <a href="lib-containers.html#lib.vector.modifiers"> [lib.vector.modifiers]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Anthony Williams <b>Date:</b> 13 Jul 2001</p> +<b>Section:</b> 23.2.4.2 <a href="lib-containers.html#lib.vector.capacity"> [lib.vector.capacity]</a>, 23.2.4.3 <a href="lib-containers.html#lib.vector.modifiers"> [lib.vector.modifiers]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Anthony Williams <b>Date:</b> 13 Jul 2001</p> <p> There is an apparent contradiction about which circumstances can cause a reallocation of a vector in Section 23.2.4.2 <a href="lib-containers.html#lib.vector.capacity"> [lib.vector.capacity]</a> and @@ -4784,45 +3770,8 @@ the argument to the first, the intent was for the second invocation to have no effect. Wording implying that such cases have an effect on reallocation guarantees was inadvertant.</p> <hr> -<a name="331"><h3>331. bad declaration of destructor for ios_base::failure</h3></a><p> -<b>Section:</b> 27.4.2.1.1 <a href="lib-iostreams.html#lib.ios::failure"> [lib.ios::failure]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> PremAnand M. Rao <b>Date:</b> 23 Aug 2001</p> -<p> -With the change in 17.4.4.8 <a href="lib-intro.html#lib.res.on.exception.handling"> [lib.res.on.exception.handling]</a> to state - "An implementation may strengthen the exception-specification for a - non-virtual function by removing listed exceptions." -(issue <a href="lwg-defects.html#119">119</a>) -and the following declaration of ~failure() in ios_base::failure -</p> -<pre> - namespace std { - class ios_base::failure : public exception { - public: - ... - virtual ~failure(); - ... - }; - } -</pre> -<p>the class failure cannot be implemented since in 18.6.1 <a href="lib-support.html#lib.exception"> [lib.exception]</a> the destructor of class exception has an empty -exception specification:</p> -<pre> - namespace std { - class exception { - public: - ... - virtual ~exception() throw(); - ... - }; - } -</pre> -<p><b>Proposed resolution:</b></p> -<p>Remove the declaration of ~failure().</p> -<p><b>Rationale:</b></p> -<p>The proposed resolution is consistent with the way that destructors -of other classes derived from <tt>exception</tt> are handled.</p> -<hr> <a name="333"><h3>333. does endl imply synchronization with the device?</h3></a><p> -<b>Section:</b> 27.6.2.7 <a href="lib-iostreams.html#lib.ostream.manip"> [lib.ostream.manip]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> PremAnand M. Rao <b>Date:</b> 27 Aug 2001</p> +<b>Section:</b> 27.6.2.7 <a href="lib-iostreams.html#lib.ostream.manip"> [lib.ostream.manip]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> PremAnand M. Rao <b>Date:</b> 27 Aug 2001</p> <p>A footnote in 27.6.2.7 <a href="lib-iostreams.html#lib.ostream.manip"> [lib.ostream.manip]</a> states:</p> <blockquote> [Footnote: The effect of executing cout << endl is to insert a @@ -4857,7 +3806,7 @@ because it appears to make promises about what <tt>flush</tt> does.</p> <hr> <a name="334"><h3>334. map::operator[] specification forces inefficient implementation</h3></a><p> -<b>Section:</b> 23.3.1.2 <a href="lib-containers.html#lib.map.access"> [lib.map.access]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Andrea Griffini <b>Date:</b> 02 Sep 2001</p> +<b>Section:</b> 23.3.1.2 <a href="lib-containers.html#lib.map.access"> [lib.map.access]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Andrea Griffini <b>Date:</b> 02 Sep 2001</p> <p> The current standard describes map::operator[] using a code example. That code example is however quite @@ -4957,49 +3906,15 @@ clause 17 saying that we do not intend the semantics of sample code fragments to be interpreted as specifing exactly how many copies are made. See issue <a href="lwg-active.html#98">98</a> for a similar problem.]</i></p> -<hr> -<a name="335"><h3>335. minor issue with char_traits, table 37</h3></a><p> -<b>Section:</b> 21.1.1 <a href="lib-strings.html#lib.char.traits.require"> [lib.char.traits.require]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Andy Sawyer <b>Date:</b> 06 Sep 2001</p> -<p> -Table 37, in 21.1.1 <a href="lib-strings.html#lib.char.traits.require"> [lib.char.traits.require]</a>, descibes char_traits::assign -as: -</p> -<pre> - X::assign(c,d) assigns c = d. -</pre> - -<p>And para 1 says:</p> - -<blockquote> - [...] c and d denote values of type CharT [...] -</blockquote> - +<p><b>Rationale:</b></p> <p> -Naturally, if c and d are <i>values</i>, then the assignment is -(effectively) meaningless. It's clearly intended that (in the case of -assign, at least), 'c' is intended to be a reference type. -</p> - -<p>I did a quick survey of the four implementations I happened to have -lying around, and sure enough they all have signatures:</p> -<pre> - assign( charT&, const charT& ); -</pre> - -<p>(or the equivalent). It's also described this way in Nico's book. -(Not to mention the synopses of char_traits<char> in 21.1.3.1 -and char_traits<wchar_t> in 21.1.3.2...) +This is the second solution described above; as noted, it is +consistent with existing practice. </p> -<p><b>Proposed resolution:</b></p> -<p>Add the following to 21.1.1 para 1:</p> -<blockquote> - r denotes an lvalue of CharT -</blockquote> -<p>and change the description of assign in the table to:</p> -<pre> - X::assign(r,d) assigns r = d -</pre> +<p>Note that we now need to specify the complexity explicitly, because +we are no longer defining <tt>operator[]</tt> in terms of +<tt>insert</tt>.</p> <hr> <a name="336"><h3>336. Clause 17 lack of references to deprecated headers</h3></a><p> <b>Section:</b> 17 <a href="lib-intro.html#lib.library"> [lib.library]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> Detlef Vollmann <b>Date:</b> 05 Sep 2001</p> @@ -5017,22 +3932,13 @@ library (though a deprecated one).</p> to table 11. A review is needed to determine whether there are any other places in clause 17 where clause D material should be referred to. Beman will review clause 17.]</i></p> -<hr> -<a name="337"><h3>337. replace_copy_if's template parameter should be InputIterator</h3></a><p> -<b>Section:</b> 25.2.4 <a href="lib-algorithms.html#lib.alg.replace"> [lib.alg.replace]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Detlef Vollmann <b>Date:</b> 07 Sep 2001</p> -<p>From c++std-edit-876:</p> -<p> -In section 25.2.4 <a href="lib-algorithms.html#lib.alg.replace"> [lib.alg.replace]</a> before p4: The name of the first -parameter of template replace_copy_if should be "InputIterator" -instead of "Iterator". According to 17.3.2.1 <a href="lib-intro.html#lib.type.descriptions"> [lib.type.descriptions]</a> p1 the -parameter name conveys real normative meaning. -</p> -<p><b>Proposed resolution:</b></p> -<p>Change <tt>Iterator</tt> to <tt>InputIterator</tt>.</p> +<p><i>[Curaçao: Beman emailed wording to Matt, but not in time for the +pre-meeting mailing.]</i></p> + <hr> <a name="338"><h3>338. is whitespace allowed between `-' and a digit?</h3></a><p> -<b>Section:</b> 22.2 <a href="lib-locales.html#lib.locale.categories"> [lib.locale.categories]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 17 Sep 2001</p> +<b>Section:</b> 22.2 <a href="lib-locales.html#lib.locale.categories"> [lib.locale.categories]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 17 Sep 2001</p> <p> From Stage 2 processing in 22.2.2.1.2 <a href="lib-locales.html#lib.facet.num.get.virtuals"> [lib.facet.num.get.virtuals]</a>, p8 and 9 (the original text or the text corrected by the proposed resolution of @@ -5094,7 +4000,7 @@ numeric processing in 22.2.2.1.2 <a href="lib-locales.html#lib.facet.num.get.vir resolution removes all mention of "whitespace" from that format.</p> <hr> <a name="339"><h3>339. definition of bitmask type restricted to clause 27</h3></a><p> -<b>Section:</b> 22.2.1 <a href="lib-locales.html#lib.category.ctype"> [lib.category.ctype]</a>, 17.3.2.1.2 <a href="lib-intro.html#lib.bitmask.types"> [lib.bitmask.types]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 17 September 2001</p> +<b>Section:</b> 22.2.1 <a href="lib-locales.html#lib.category.ctype"> [lib.category.ctype]</a>, 17.3.2.1.2 <a href="lib-intro.html#lib.bitmask.types"> [lib.bitmask.types]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 17 September 2001</p> <p> The ctype_category::mask type is declared to be an enum in 22.2.1 <a href="lib-locales.html#lib.category.ctype"> [lib.category.ctype]</a> with p1 then stating that it is a bitmask type, most likely referring to the definition of bitmask type in 17.3.2.1.2 <a href="lib-intro.html#lib.bitmask.types"> [lib.bitmask.types]</a>, p1. However, the said definition only applies to @@ -5128,7 +4034,7 @@ following (note, in particluar, the cross-reference to 17.3.2.1.2 in namespace std { class ctype_base { public: - typedef T mask; + typedef <b><i>T</i></b> mask; // numeric values are for exposition only. static const mask space = 1 << 0; @@ -5149,10 +4055,13 @@ namespace std { <p>The type <tt>mask</tt> is a bitmask type (17.3.2.1.2 <a href="lib-intro.html#lib.bitmask.types"> [lib.bitmask.types]</a>).</p> </blockquote> +<p><i>[Curaçao: The LWG notes that T above should be bold-italics to be +consistent with the rest of the standard.]</i></p> + <hr> <a name="340"><h3>340. interpretation of <tt>has_facet<Facet>(loc)</tt> </h3></a><p> -<b>Section:</b> 22.1.1.1.1 <a href="lib-locales.html#lib.locale.category"> [lib.locale.category]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 18 Sep 2001</p> +<b>Section:</b> 22.1.1.1.1 <a href="lib-locales.html#lib.locale.category"> [lib.locale.category]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 18 Sep 2001</p> <p> It's unclear whether 22.1.1.1.1, p3 says that <tt>has_facet<Facet>(loc)</tt> returns true for any <tt>Facet</tt> @@ -5210,7 +4119,7 @@ OutputIterator must be supported. Table 51 already contains a complete list of the ones we need.</p> <hr> <a name="341"><h3>341. Vector reallocation and swap</h3></a><p> -<b>Section:</b> 23.2.4.2 <a href="lib-containers.html#lib.vector.capacity"> [lib.vector.capacity]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Anthony Williams <b>Date:</b> 27 Sep 2001</p> +<b>Section:</b> 23.2.4.2 <a href="lib-containers.html#lib.vector.capacity"> [lib.vector.capacity]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Anthony Williams <b>Date:</b> 27 Sep 2001</p> <p>It is a common idiom to reduce the capacity of a vector by swapping it with an empty one:</p> <pre> @@ -5272,7 +4181,6 @@ containers.]</i></p> swap should be constant time. The clear intent is that it should just do pointer twiddling, and that it should exchange all properties of the two vectors, including their reallocation guarantees. -ay be useful. </p> <hr> <a name="342"><h3>342. seek and eofbit</h3></a><p> @@ -5349,63 +4257,8 @@ examined by the user to determine why something failed.</p> places where we have a problem, where the difference between <tt>fail()</tt> and <tt>!good()</tt> is important.]</i></p> <hr> -<a name="345"><h3>345. type tm in <cwchar></h3></a><p> -<b>Section:</b> 21.4 <a href="lib-strings.html#lib.c.strings"> [lib.c.strings]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Clark Nelson <b>Date:</b> 19 Oct 2001</p> -<p> -C99, and presumably amendment 1 to C90, specify that <wchar.h> -declares struct tm as an incomplete type. However, table 48 in 21.4 <a href="lib-strings.html#lib.c.strings"> [lib.c.strings]</a> does not mention the type tm as being declared in -<cwchar>. Is this omission intentional or accidental? -</p> -<p><b>Proposed resolution:</b></p> -<p>In section 21.4 <a href="lib-strings.html#lib.c.strings"> [lib.c.strings]</a>, add "tm" to table 48.</p> -<hr> -<a name="346"><h3>346. Some iterator member functions should be const</h3></a><p> -<b>Section:</b> 24.1 <a href="lib-iterators.html#lib.iterator.requirements"> [lib.iterator.requirements]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Jeremy Siek <b>Date:</b> 20 Oct 2001</p> -<p>Iterator member functions and operators that do not change the state -of the iterator should be defined as const member functions or as -functions that take iterators either by const reference or by -value. The standard does not explicitly state which functions should -be const. Since this a fairly common mistake, the following changes -are suggested to make this explicit.</p> - -<p>The tables almost indicate constness properly through naming: r -for non-const and a,b for const iterators. The following changes -make this more explicit and also fix a couple problems.</p> -<p><b>Proposed resolution:</b></p> -<p>In 24.1 <a href="lib-iterators.html#lib.iterator.requirements"> [lib.iterator.requirements]</a> Change the first section of p9 from -"In the following sections, a and b denote values of X..." to -"In the following sections, a and b denote values of type const X...".</p> - -<p>In Table 73, change</p> -<pre> - a->m U& ... -</pre> - -<p>to</p> - -<pre> - a->m const U& ... - r->m U& ... -</pre> - -<p>In Table 73 expression column, change</p> - -<pre> - *a = t -</pre> - -<p>to</p> - -<pre> - *r = t -</pre> - -<p><i>[Redmond: The container requirements should be reviewed to see if -the same problem appears there.]</i></p> - -<hr> <a name="347"><h3>347. locale::category and bitmask requirements</h3></a><p> -<b>Section:</b> 22.1.1.1.1 <a href="lib-locales.html#lib.locale.category"> [lib.locale.category]</a> <b>Status:</b> <a href="lwg-active.html#New">New</a> <b>Submitter:</b> P.J. Plauger, Nathan Myers <b>Date:</b> 23 Oct 2001</p> +<b>Section:</b> 22.1.1.1.1 <a href="lib-locales.html#lib.locale.category"> [lib.locale.category]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> P.J. Plauger, Nathan Myers <b>Date:</b> 23 Oct 2001</p> <p> In 22.1.1.1.1 <a href="lib-locales.html#lib.locale.category"> [lib.locale.category]</a> paragraph 1, the category members are described as bitmask elements. In fact, the bitmask requirements @@ -5485,9 +4338,11 @@ of the other enumerated values; implementations may add extra categories.] </p> </blockquote> +<p><i>[Curaçao: need input from locale experts.]</i></p> + <hr> <a name="348"><h3>348. Minor issue with std::pair operator<</h3></a><p> -<b>Section:</b> 20.2.2 <a href="lib-utilities.html#lib.pairs"> [lib.pairs]</a> <b>Status:</b> <a href="lwg-active.html#New">New</a> <b>Submitter:</b> Andy Sawyer <b>Date:</b> 23 Oct 2001</p> +<b>Section:</b> 20.2.2 <a href="lib-utilities.html#lib.pairs"> [lib.pairs]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> Andy Sawyer <b>Date:</b> 23 Oct 2001</p> <p> The current wording of 20.2.2 [lib.pairs] p6 precludes the use of operator< on any pair type which contains a pointer. @@ -5504,9 +4359,18 @@ operator< on any pair type which contains a pointer. (!std::less<T1>()( y.first, x.first) && std::less<T2>()( x.second, y.second ) ) </pre> + +<p><i>[Curaçao: LWG leaning toward NAD. In favor of the PR is +that it removes a trap for users. Concerns: 1) will break some +small amount of existing code (which define less and operator < +with different behavior), 2) don't have any indication of rationale +for current design (and unwilling to change without knowing +rationale), 3) consistency; pairs of ptrs would behave differenly from +individual pointers.]</i></p> + <hr> <a name="349"><h3>349. Minor typographical error in ostream_iterator</h3></a><p> -<b>Section:</b> 24.5.2 <a href="lib-iterators.html#lib.ostream.iterator"> [lib.ostream.iterator]</a> <b>Status:</b> <a href="lwg-active.html#New">New</a> <b>Submitter:</b> Andy Sawyer <b>Date:</b> 24 Oct 2001</p> +<b>Section:</b> 24.5.2 <a href="lib-iterators.html#lib.ostream.iterator"> [lib.ostream.iterator]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Andy Sawyer <b>Date:</b> 24 Oct 2001</p> <p>24.5.2 [lib.ostream.iterator] states:</p> <pre> [...] @@ -5525,7 +4389,7 @@ In 24.5.2 <a href="lib-iterators.html#lib.ostream.iterator"> [lib.ostream.iterat </p> <hr> <a name="350"><h3>350. allocator<>::address</h3></a><p> -<b>Section:</b> 20.4.1.1 <a href="lib-utilities.html#lib.allocator.members"> [lib.allocator.members]</a>, 20.1.5 <a href="lib-utilities.html#lib.allocator.requirements"> [lib.allocator.requirements]</a>, 17.4.1.1 <a href="lib-intro.html#lib.contents"> [lib.contents]</a> <b>Status:</b> <a href="lwg-active.html#New">New</a> <b>Submitter:</b> Nathan Myers <b>Date:</b> 25 Oct 2001</p> +<b>Section:</b> 20.4.1.1 <a href="lib-utilities.html#lib.allocator.members"> [lib.allocator.members]</a>, 20.1.5 <a href="lib-utilities.html#lib.allocator.requirements"> [lib.allocator.requirements]</a>, 17.4.1.1 <a href="lib-intro.html#lib.contents"> [lib.contents]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> Nathan Myers <b>Date:</b> 25 Oct 2001</p> <p>See c++std-lib-9006 and c++std-lib-9007. This issue is taken verbatim from -9007.</p> @@ -5550,6 +4414,14 @@ no semantics at all for member address(), and allocator<>::address is defined in terms of unadorned operator &. </p> +<p><i>[Curaçao: The LWG believes both examples are ill-formed. +The contained type is required to be CopyConstructible (20.1.3), and +that includes the requirement that &t return the usual types and +values. Since the CopyConstructible requirements appear to have been +written to deal with the concerns of this issue, the LWG feels it is +NAD unless someone can come up with a well-formed example exhibiting a +problem.]</i></p> + <p><b>Proposed resolution:</b></p> <p> In 20.4.1.1, Change the definition of allocator<>::address from:</p> @@ -5581,6 +4453,9 @@ a.address(s) lines, respectively: operator& may be overloaded. </blockquote> +<p><i>[Curaçao: If the issues isn't NAD, suggest changing "if not +overloaded" to "ignoring all overloads".]</i></p> + <p><b>Rationale:</b></p> <p>The obvious implementations for std::allocator<>::address are</p> <pre> @@ -5598,6 +4473,816 @@ but to define them formally in terms of reinterpret_cast<> seems to introduce semantic difficulties best avoided. Using a.address() should not introduce unspecified or implementation-defined semantics into a user program.</p> +<hr> +<a name="352"><h3>352. missing fpos requirements</h3></a><p> +<b>Section:</b> 21.1.2 <a href="lib-strings.html#lib.char.traits.typedefs"> [lib.char.traits.typedefs]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 2 Dec 2001</p> +<p> +<i>(1)</i> +There are no requirements on the <tt>stateT</tt> template parameter of +<tt>fpos</tt> listed in 27.4.3. The interface appears to require that +the type be at least Assignable and CopyConstructible (27.4.3.1, p1), +and I think also DefaultConstructible (to implement the operations in +Table 88). +</p> +<p> +21.1.2, p3, however, only requires that +<tt>char_traits<charT>::state_type</tt> meet the requirements of +CopyConstructible types. +</p> +<p> +<i>(2)</i> +Additionally, the <tt>stateT</tt> template argument has no +corresponding typedef in fpos which might make it difficult to use in +generic code. +</p> +<p><b>Proposed resolution:</b></p> +<p> +Modify 21.1.2, p4 from +</p> +<p> + Requires: <tt>state_type</tt> shall meet the requirements of + CopyConstructible types (20.1.3). +</p> +<p> + Requires: state_type shall meet the requirements of Assignable + (23.1, p4), CopyConstructible (20.1.3), and + DefaultConstructible (20.1.4) types. +</p> +<p> +Add to the definition of the fpos class template the following member: +</p> +<pre> + typedef stateT state_type; +</pre> +<p> +and add to 27.4.3.1 a paragraph with the following text: +</p> +<pre> + typedef stateT state_type; +</pre> +<p> + Requires: <tt>state_type</tt> shall meet the requirements of + Assignable (23.1, p4), CopyConstructible (20.1.3), and + DefaultConstructible (20.1.4) types. +</p> + +<p><i>[Curaçao: The LWG feels this is two issues, as indicated +above. The first is a defect; more I/O experts need to review +the PR. The second is questionable; who would use it? Unless +motivation is provided, the second should be considered NAD.]</i></p> + +<hr> +<a name="354"><h3>354. Associative container lower/upper bound requirements</h3></a><p> +<b>Section:</b> 23.1.2 <a href="lib-containers.html#lib.associative.reqmts"> [lib.associative.reqmts]</a> <b>Status:</b> <a href="lwg-active.html#Ready">Ready</a> <b>Submitter:</b> Hans Aberg <b>Date:</b> 17 Dec 2001</p> +<p> +Discussions in the thread "Associative container lower/upper bound +requirements" on comp.std.c++ suggests that there is a defect in the +C++ standard, Table 69 of section 23.1.2, "Associative containers", +[lib.associative.reqmts]. It currently says:</p> + +<blockquote> +<p> +a.find(k): returns an iterator pointing to an element with the key equivalent to +k, or a.end() if such an element is not found. +</p> + +<p> +a.lower_bound(k): returns an iterator pointing to the first element with +key not less than k. +</p> + +<p> +a.upper_bound(k): returns an iterator pointing to the first element with +key greater than k. +</p> +</blockquote> + +<p> +We have "or a.end() if such an element is not found" for +<tt>find</tt>, but not for <tt>upper_bound</tt> or +<tt>lower_bound</tt>. As the text stands, one would be forced to +insert a new element into the container and return an iterator to that +in case the sought iterator does not exist, which does not seem to be +the intention (and not possible with the "const" versions). +</p> +<p><b>Proposed resolution:</b></p> + +<p>Change Table 69 of section 23.1.2 <a href="lib-containers.html#lib.associative.reqmts"> [lib.associative.reqmts]</a> indicated entries +to:</p> + +<blockquote> +<p> +a.lower_bound(k): returns an iterator pointing to the first element with +key not less than k, or a.end() if such an element is not found. +</p> + +<p> +a.upper_bound(k): returns an iterator pointing to the first element with +key greater than k, or a.end() if such an element is not found. +</p> +</blockquote> + +<p><i>[Curaçao: LWG reviewed PR.]</i></p> + +<hr> +<a name="355"><h3>355. Operational semantics for a.back()</h3></a><p> +<b>Section:</b> 23.1.1 <a href="lib-containers.html#lib.sequence.reqmts"> [lib.sequence.reqmts]</a> <b>Status:</b> <a href="lwg-active.html#Review">Review</a> <b>Submitter:</b> Yaroslav Mironov <b>Date:</b> 23 Jan 2002</p> + +<p>Table 68 "Optional Sequence Operations" in 23.1.1/12 +specifies operational semantics for "a.back()" as +"*--a.end()", which may be ill-formed <i>[because calling +operator-- on a temporary (the return) of a built-in type is +ill-formed]</i>, provided a.end() returns a simple pointer rvalue +(this is almost always the case for std::vector::end(), for +example). Thus, the specification is not only incorrect, it +demonstrates a dangerous construct: "--a.end()" may +successfully compile and run as intended, but after changing the type +of the container or the mode of compilation it may produce +compile-time error. </p> + +<p><b>Proposed resolution:</b></p> +<p>Change the specification in table 68 "Optional Sequence +Operations" in 23.1.1/12 for "a.back()" from</p> + + +<blockquote> +*--a.end() +</blockquote> + +<p>to</p> + +<blockquote> + <p>*a.rbegin()</p> +</blockquote> + +<p>and the specification for "a.pop_back()" from</p> + +<blockquote> +a.erase(--a.end()) +</blockquote> + +<p>to</p> + +<blockquote> + <p>a.erase(rbegin())</p> +</blockquote> + +<p><i>[Curaçao: LWG changed PR from "{ X::iterator tmp = +a.end(); return *--tmp; }" to "*a.rbegin()", and from +"{ X::iterator tmp = a.end(); a.erase(--tmp); }" to +"a.erase(rbegin())".]</i></p> + +<p><i>[There is a second possible defect; table 68 "Optional +Sequence Operations" in the "Operational Semantics" +column uses operations present only in the "Reversible +Container" requirements, yet there is no stated dependency +between these separate requirements tables. Ask in Santa Cruz if the +LWG would like a new issue opened.]</i></p> + +<hr> +<a name="356"><h3>356. Meaning of ctype_base::mask enumerators</h3></a><p> +<b>Section:</b> 22.2.1 <a href="lib-locales.html#lib.category.ctype"> [lib.category.ctype]</a> <b>Status:</b> <a href="lwg-active.html#New">New</a> <b>Submitter:</b> Matt Austern <b>Date:</b> 23 Jan 2002</p> + +<p>What should the following program print?</p> + +<pre> + #include <locale> + #include <iostream> + + class my_ctype : public std::ctype<char> + { + typedef std::ctype<char> base; + public: + my_ctype(std::size_t refs = 0) : base(my_table, false, refs) + { + std::copy(base::classic_table(), base::classic_table() + base::table_size, + my_table); + my_table[(unsigned char) '_'] = (base::mask) (base::print | base::space); + } + private: + mask my_table[base::table_size]; + }; + + int main() + { + my_ctype ct; + std::cout << "isspace: " << ct.is(std::ctype_base::space, '_') << " " + << "isalpha: " << ct.is(std::ctype_base::alpha, '_') << std::endl; + } +</pre> + +<p>The goal is to create a facet where '_' is treated as whitespace.</p> + +<p>On gcc 3.0, this program prints "isspace: 1 isalpha: 0". On +Microsoft C++ it prints "isspace: 1 isalpha: 1".</p> + +<p> +I believe that both implementations are legal, and the standard does not +give enough guidance for users to be able to use std::ctype's +protected interface portably.</p> + +<p> +The above program assumes that ctype_base::mask enumerators like +<tt>space</tt> and <tt>print</tt> are disjoint, and that the way to +say that a character is both a space and a printing character is to or +those two enumerators together. This is suggested by the "exposition +only" values in 22.2.1 <a href="lib-locales.html#lib.category.ctype"> [lib.category.ctype]</a>, but it is nowhere specified in +normative text. An alternative interpretation is that the more +specific categories subsume the less specific. The above program +gives the results it does on the Microsoft compiler because, on that +compiler, <tt>print</tt> has all the bits set for each specific +printing character class. +</p> + +<p>From the point of view of std::ctype's public interface, there's no +important difference between these two techniques. From the point of +view of the protected interface, there is. If I'm defining a facet +that inherits from std::ctype<char>, I'm the one who defines the +value that table()['a'] returns. I need to know what combination of +mask values I should use. This isn't so very esoteric: it's exactly +why std::ctype has a protected interface. If we care about users +being able to write their own ctype facets, we have to give them a +portable way to do it. +</p> + +<p> +Related reflector messages: +lib-9224, lib-9226, lib-9229, lib-9270, lib-9272, lib-9273, lib-9274, +lib-9277, lib-9279. +</p> + +<p>Issue <a href="lwg-active.html#339">339</a> is related, but not identical. The +proposed resolution if issue <a href="lwg-active.html#339">339</a> says that +ctype_base::mask must be a bitmask type. It does not say that the +ctype_base::mask elements are bitmask elements, so it doesn't +directly affect this issue.</p> + +<p><b>Proposed resolution:</b></p> +<p>Informally, we have three choices:</p> +<ol> +<li>Require that the enumerators are disjoint (except for alnum and +graph)</li> +<li>Require that the enumerators are not disjoint, and specify which +of them subsume which others. (e.g. mandate that lower includes alpha +and print)</li> +<li>Explicitly leave this unspecified, which the result that the above +program is not portable.</li> +</ol> + +<p>Either of the first two options is just as good from the standpoint +of portability. Either one will require some implementations to +change.</p> + +<hr> +<a name="357"><h3>357. <cmath> float functions cannot return HUGE_VAL</h3></a><p> +<b>Section:</b> 26.5 <a href="lib-numerics.html#lib.c.math"> [lib.c.math]</a> <b>Status:</b> <a href="lwg-active.html#Open">Open</a> <b>Submitter:</b> Ray Lischner <b>Date:</b> 26 Feb 2002</p> +<p> +The float versions of the math functions have no meaningful value to return +for a range error. The long double versions have a value they can return, +but it isn't necessarily the most reasonable value. +</p> + +<p> +Section 26.5 [lib.c.math], paragraph 5, says that C++ "adds float and long +double overloaded versions of these functions, with the same semantics," +referring to the math functions from the C90 standard. +</p> + +<p> +The C90 standard, in section 7.5.1, paragraph 3, says that functions return +"the value of the macro HUGE_VAL" when they encounter a range error. +Section 7.5, paragraph 2, defines HUGE_VAL as a macro that "expands to a +positive double expression, not necessarily representable as a float." +</p> + +<p> +Therefore, the float versions of the math functions have no way to +signal a range error. <i>[Curaçao: The LWG notes that this isn't +strictly correct, since errno is set.]</i> The semantics require that they +return HUGE_VAL, but they cannot because HUGE_VAL might not be +representable as a float. +</p> + +<p> +The problem with long double functions is less severe because HUGE_VAL is +representable as a long double. On the other hand, it might not be a "huge" +long double value, and might fall well within the range of normal return +values for a long double function. Therefore, it does not make sense for a +long double function to return a double (HUGE_VAL) for a range error. +</p> +<p><b>Proposed resolution:</b></p> +<p>Curaçao: C99 was faced with a similar problem, which they fixed by +adding HUGE_VALF and HUGE_VALL in addition to HUGE_VAL.</p> + +<p>C++ must also fix, but it should be done in the context of the +general C99 based changes to C++, not via DR. Thus the LWG in Curaçao +felt the resolution should be NAD, FUTURE, but the issue is being held +open for one more meeting to ensure LWG members not present during the +discussion concur.</p> +<hr> +<a name="358"><h3>358. interpreting <tt>thousands_sep</tt> after a <tt>decimal_point</tt> +</h3></a><p> +<b>Section:</b> 22.2.2.1.2 <a href="lib-locales.html#lib.facet.num.get.virtuals"> [lib.facet.num.get.virtuals]</a> <b>Status:</b> <a href="lwg-active.html#New">New</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 12 Mar 2002</p> +<p> +I don't think <tt>thousands_sep</tt> is being treated correctly after +decimal_point has been seen. Since grouping applies only to the +integral part of the number, the first such occurrence should, IMO, +terminate Stage 2. (If it does not terminate it, then 22.2.2.1.2, p12 +and 22.2.3.1.2, p3 need to explain how <tt>thousands_sep</tt> is to be +interpreted in the fractional part of a number.) +</p> + +<p> +The easiest change I can think of that resolves this issue would be +something like below. +</p> +<p><b>Proposed resolution:</b></p> +<p> +Change the first sentence of 22.2.2.1.2, p9 from +</p> + +<blockquote> + If discard is true then the position of the character is + remembered, but the character is otherwise ignored. If it is not + discarded, then a check is made to determine if c is allowed as + the next character of an input field of the conversion specifier + returned by stage 1. If so it is accumulated. +</blockquote> + +<p>to</p> + +<blockquote> + If <tt>discard</tt> is true, then if <tt>'.'</tt> has not yet been + accumulated, then the position of the character is remembered, but + the character is otherwise ignored. Otherwise, if <tt>'.'</tt> has + already been accumulated, the character is discarded and Stage 2 + terminates. ... +</blockquote> + +<hr> +<a name="359"><h3>359. num_put<>::do_put (..., bool) undocumented</h3></a><p> +<b>Section:</b> 22.2.2.2.1 <a href="lib-locales.html#lib.facet.num.put.members"> [lib.facet.num.put.members]</a> <b>Status:</b> <a href="lwg-active.html#New">New</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 12 Mar 2002</p> +<p>22.2.2.2.1, p1:</p> + + <pre> + iter_type put (iter_type out, ios_base& str, char_type fill, + bool val) const; + ... + + 1 Returns: do_put (out, str, fill, val). + </pre> + +<p>AFAICS, the behavior of do_put (..., bool) is not documented anywhere, +however, 22.2.2.2.2, p23:</p> + +<blockquote> +<pre> +iter_type put (iter_type out, ios_base& str, char_type fill, + bool val) const; +</pre> + + + Effects: If (str.flags() & ios_base::boolalpha) == 0 then do + out = do_put(out, str, fill, (int)val) + Otherwise do +<pre> + string_type s = + val ? use_facet<ctype<charT> >(loc).truename() + : use_facet<ctype<charT> >(loc).falsename(); +</pre> + and then insert the characters of s into out. <i>out</i>. +</blockquote> + +<p> +This means that the bool overload of <tt>do_put()</tt> will never be called, +which contradicts the first paragraph. Perhaps the declaration +should read <tt>do_put()</tt>, and not <tt>put()</tt>? +</p> + +<p> +Note also that there is no <b>Returns</b> clause for this function, which +should probably be corrected, just as should the second occurrence +of <i>"out."</i> in the text. +</p> + +<p> +I think the least invasive change to fix it would be something like +the following: +</p> +<p><b>Proposed resolution:</b></p> +<p> +In 22.2.2.2.2, p23, make the following changes +</p> + +<blockquote> + Replace <tt>put()</tt> with <tt>do_put()</tt> in the declaration + of the member function. +</blockquote> + +<blockquote> + Change the <b>Effects</b> clause to a <b>Returns</b> clause (to + avoid the requirement to call <tt>do_put(..., int)</tt> from <tt> + do_put (..., bool))</tt> + like so: +</blockquote> + +<blockquote> + 23 <b>Returns</b>: If <tt>(str.flags() & + ios_base::boolalpha) == 0</tt> then + <tt>do_put (out, str, fill, (int)val)</tt> + Otherwise the function obtains a string <tt>s</tt> as if by +<pre> + string_type s = + val ? use_facet<ctype<charT> >(loc).truename() + : use_facet<ctype<charT> >(loc).falsename(); +</pre> + and then inserts each character <tt>c</tt> of s into out via + <tt>*out++ = c</tt> + and returns <tt>out</tt>. +</blockquote> + +<hr> +<a name="360"><h3>360. locale mandates inefficient implementation</h3></a><p> +<b>Section:</b> 22.1.1 <a href="lib-locales.html#lib.locale"> [lib.locale]</a> <b>Status:</b> <a href="lwg-active.html#New">New</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 12 Mar 2002</p> +<p> +22.1.1, p7 (copied below) allows iostream formatters and extractors +to make assumptions about the values returned from facet members. +However, such assumptions are apparently not guaranteed to hold +in other cases (e.g., when the facet members are being called directly +rather than as a result of iostream calls, or between successive +calls to the same iostream functions with no interevening calls to +<tt>imbue()</tt>, or even when the facet member functions are called +from other member functions of other facets). This restriction +prevents locale from being implemented efficiently. +</p> +<p><b>Proposed resolution:</b></p> +<p>Change the first sentence in 22.1.1, p7 from</p> +<blockquote> + In successive calls to a locale facet member function during + a call to an iostream inserter or extractor or a streambuf member + function, the returned result shall be identical. [Note: This + implies that such results may safely be reused without calling + the locale facet member function again, and that member functions + of iostream classes cannot safely call <tt>imbue()</tt> + themselves, except as specified elsewhere. --end note] +</blockquote> + +<p>to</p> + +<blockquote> + In successive calls to a locale facet member function on a facet + object installed in the same locale, the returned result shall be + identical. ... +</blockquote> + +<hr> +<a name="361"><h3>361. num_get<>::do_get (..., void*&) checks grouping</h3></a><p> +<b>Section:</b> 22.2.2.2.2 <a href="lib-locales.html#lib.facet.num.put.virtuals"> [lib.facet.num.put.virtuals]</a> <b>Status:</b> <a href="lwg-active.html#New">New</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 12 Mar 2002</p> +<p> +22.2.2.2.2, p12 specifies that <tt>thousands_sep</tt> is to be inserted only +for integral types (issue 282 suggests that this should be done for +all arithmetic types). +</p> + +<p> +22.2.2.1.2, p12 requires that grouping be checked for all extractors +including that for <tt>void*</tt>. +</p> + +<p> +I don't think that's right. <tt>void*</tt> values should not be checked for +grouping, should they? (Although if they should, then <tt>num_put</tt> needs +to write them out, otherwise their extraction will fail.) +</p> +<p><b>Proposed resolution:</b></p> +<p> +Change the first sentence of 22.2.2.2.2, p12 from +</p> +<blockquote> + Digit grouping is checked. That is, the positions of discarded + separators is examined for consistency with + use_facet<numpunct<charT> >(loc).grouping(). + If they are not consistent then ios_base::failbit is assigned + to err. +</blockquote> + +<p>to</p> +<blockquote> + Except for conversions to void*, digit grouping is checked... +</blockquote> + +<hr> +<a name="362"><h3>362. bind1st/bind2nd type safety</h3></a><p> +<b>Section:</b> 20.3.6.2 <a href="lib-utilities.html#lib.bind.1st"> [lib.bind.1st]</a> <b>Status:</b> <a href="lwg-active.html#New">New</a> <b>Submitter:</b> Andrew Demkin <b>Date:</b> 26 Apr 2002</p> +<p> +The definition of bind1st() (20.3.6.2 <a href="lib-utilities.html#lib.bind.1st"> [lib.bind.1st]</a>) can result in +the construction of an unsafe binding between incompatible pointer +types. For example, given a function whose first parameter type is +'pointer to T', it's possible without error to bind an argument of +type 'pointer to U' when U does not derive from T: +</p> +<pre> + foo(T*, int); + + struct T {}; + struct U {}; + + U u; + + int* p; + int* q; + + for_each(p, q, bind1st(ptr_fun(foo), &u)); // unsafe binding +</pre> + +<p> +The definition of bind1st() includes a functional-style conversion to +map its argument to the expected argument type of the bound function +(see below): +</p> +<pre> + typename Operation::first_argument_type(x) +</pre> + +<p> +A functional-style conversion (5.2.3 <a href="expr.html#expr.type.conv"> [expr.type.conv]</a>) is defined to be +semantically equivalent to an explicit cast expression (5.4 <a href="expr.html#expr.cast"> [expr.cast]</a>), which may (according to 5.4, paragraph 5) be interpreted +as a reinterpret_cast, thus masking the error. +</p> + +<p>The problem and proposed change also apply to 20.3.6.4 <a href="lib-utilities.html#lib.bind.2nd"> [lib.bind.2nd]</a>.</p> +<p><b>Proposed resolution:</b></p> +<p> +The simplest and most localized change to prevent such errors is to +require bind1st() use a static_cast expression rather than the +functional-style conversion; that is, have bind1st() return: +</p> +<pre> + binder1st<Operation>( op, + static_cast<typename Operation::first_argument_type>(x)). +</pre> + +<p> +A more agressive solution is to change the semantics of +functional-style conversions to not permit a reinterpret_cast. For +contexts that require the semantics of reinterpret_cast, the language +may want to require the use of an explicit cast expression such as +'(T) x' or 'reinterpret_cast<T>(x)' and limit the behavior of +the functional notation to match statically-checked and standard +conversions (as defined by 5.2.9 and 4.10, etc.). Although changing +the semantics of functional-style conversions may seem drastic and +does have language-wide ramifications, it has the benefit of better +unifying the conversion rules for user defined types and built-in +types, which can be especially important for generic template +programming. +</p> +<hr> +<a name="363"><h3>363. Missing exception specification in 27.4.2.1.1</h3></a><p> +<b>Section:</b> 27.4.2.1.1 <a href="lib-iostreams.html#lib.ios::failure"> [lib.ios::failure]</a> <b>Status:</b> <a href="lwg-active.html#New">New</a> <b>Submitter:</b> Walter Brown <b>Date:</b> 20 May 2002</p> +<p> +The destructor of ios_base::failure should have an empty throw +specification, because the destructor of its base class, exception, is +declared in this way. +</p> +<p><b>Proposed resolution:</b></p> +<p>Change the destructor to</p> +<pre> + virtual ~failure() throw(); +</pre> +<hr> +<a name="364"><h3>364. Inconsistent wording in 27.5.2.4.2</h3></a><p> +<b>Section:</b> 27.5.2.4.2 <a href="lib-iostreams.html#lib.streambuf.virt.buffer"> [lib.streambuf.virt.buffer]</a> <b>Status:</b> <a href="lwg-active.html#New">New</a> <b>Submitter:</b> Walter Brown <b>Date:</b> 10 May 2002</p> +<p> +27.5.2.4.2 <a href="lib-iostreams.html#lib.streambuf.virt.buffer"> [lib.streambuf.virt.buffer]</a> paragraph 1 is inconsistent with the Effects +clause for seekoff. +</p> +<p><b>Proposed resolution:</b></p> +<p> +Make this paragraph, the Effects clause for setbuf, consistent in wording +with the Effects clause for seekoff in paragraph 3 by amending paragraph 1 +to indicate the purpose of setbuf: +</p> + +<p>Original text:</p> + +<blockquote> +1 Effects: Performs an operation that is defined separately for each +class derived from basic_streambuf in this clause (27.7.1.3, 27.8.1.4). +</blockquote> + +<p>Proposed text:</p> + +<blockquote> +1 Effects: Influences stream buffering in a way that is defined separately +for each class derived from basic_streambuf in this clause +(27.7.1.3, 27.8.1.4). +</blockquote> + +<hr> +<a name="365"><h3>365. Lack of const-qualification in clause 27</h3></a><p> +<b>Section:</b> 27 <a href="lib-iostreams.html#lib.input.output"> [lib.input.output]</a> <b>Status:</b> <a href="lwg-active.html#New">New</a> <b>Submitter:</b> Walter Brown <b>Date:</b> 10 May 2002</p> +<p> +None of the following member functions are declared const, but we +believe each should be. See document N1360 for details and rationale. +</p> +<p><b>Proposed resolution:</b></p> +<p>In 27.5.2 and 27.5.2.2.3</p> +<p>Replace</p> +<pre> + streamsize in_avail(); +</pre> +<p>with</p> +<pre> + streamsize in_avail() const; +</pre> + +<p>In 27.5.2 and 27.5.2.4.3, and 27.8.1.1 and 27.8.1.4</p> +<p>Replace</p> +<pre> + virtual streamsize showmanyc(); +</pre> +<p>with</p> +<pre> + virtual streamsize showmanyc() const; +</pre> + +<p>In 27.6.1.1 and 27.6.1.3</p> +<p>Replace</p> +<pre> + pos_type tellg(); +</pre> +<p>with</p> +<pre> + pos_type tellg() const; +</pre> + +<p>This requires additional change, because paragraph 37 describes the +return value in terms of calls to non-const member functions. Either of +the two following solutions would allow tellg to be declared const.</p> + +<p>Option 1: Implementers may cast away const-ness, to allow calling the +non-const rdbuf.</p> +<p>In paragraph 37, replace:</p> +<pre> + .... rdbuf() + ->pubseekoff(0, cur, in). +</pre> +<p>by</p> +<pre> + .... const_cast<basic_istream<charT, traits>*>(this)->rdbuf() + ->pubseekoff(0, cur, in). +</pre> + +<p>Option 2: Provide const member functions to do the job. The proposals in +a later section (specifically, the modifications concerning rdbuf +throughout the iostream library) meet most of this need; we would also +need the following addition to basic_streambuf:</p> + +<blockquote> +<pre> +basic_streambuf<charT,traits>::pos_type +basic_streambuf<charT,traits>::position(ios_base::openmode mode = + ios_base::in|ios_base::out) + const; +</pre> +<p>Effects: same as calling basic_streambuf::pubseekoff(0, ios base::cur, mode)</p> +</blockquote> + +<p>In 27.6.2.1 and 27.6.2.4</p> +<p>Replace</p> +<pre> + pos_type tellp(); +</pre> +<p>with</p> +<pre> + pos_type tell() const; +</pre> + +<p>This requires additional change; see the discussion for tellg() above.</p> + +<p>In 27.8.1.5, 27.8.1.7, 27.8.1.8, 27.8.1.10, 27.8.1.11, and 27.8.1.13</p> +<p>Replace</p> +<pre> + bool is_open(); +</pre> +<p>with</p> +<pre> + bool is_open() const; +</pre> +<hr> +<a name="366"><h3>366. Excessive const-qualification</h3></a><p> +<b>Section:</b> 27 <a href="lib-iostreams.html#lib.input.output"> [lib.input.output]</a> <b>Status:</b> <a href="lwg-active.html#New">New</a> <b>Submitter:</b> Walter Brown <b>Date:</b> 10 May 2002</p> +<p> +The following member functions are declared const, yet return non-const +pointers. We believe they are should be changed, because they allow code +that may surprise the user. See document N1360 for details and +rationale. +</p> +<p><b>Proposed resolution:</b></p> +<p>In 27.4.4 and 27.4.4.2</p> +<p>Replace</p> +<pre> + basic_ostream<charT,traits>* tie() const; +</pre> +<p>with</p> +<pre> + basic_ostream<charT,traits>* tie(); + const basic_ostream<charT,traits>* tie() const; +</pre> + +<p>and replace</p> +<pre> + basic_streambuf<charT,traits>* rdbuf() const; +</pre> +<p>with</p> +<pre> + basic_streambuf<charT,traits>* rdbuf(); + const basic_streambuf<charT,traits>* rdbuf() const; +</pre> + +<p>In 27.5.2 and 27.5.2.3.1</p> +<p>Replace</p> +<pre> + char_type* eback() const; +</pre> +<p>with</p> +<pre> + char_type* eback(); + const char_type* eback() const; +</pre> + +<p>Replace</p> +<pre> + char_type gptr() const; +</pre> +<p>with</p> +<pre> + char_type* gptr(); + const char_type* gptr() const; +</pre> + +<p>Replace</p> +<pre> + char_type* egptr() const; +</pre> +<p>with</p> +<pre> + char_type* egptr(); + const char_type* egptr() const; +</pre> + +<p>In 27.5.2 and 27.5.2.3.2</p> +<p>Replace</p> +<pre> + char_type* pbase() const; +</pre> +<p>with</p> +<pre> + char_type* pbase(); + const char_type* pbase() const; +</pre> + +<p>Replace</p> +<pre> + char_type* pptr() const; +</pre> +<p>with</p> +<pre> + char_type* pptr(); + const char_type* pptr() const; +</pre> + +<p>Replace</p> +<pre> + char_type* epptr() const; +</pre> +<p>with</p> +<pre> + char_type* epptr(); + const char_type* epptr() const; +</pre> + +<p>In 27.7.2, 27.7.2.2, 27.7.3 27.7.3.2, 27.7.4, and 27.7.6</p> +<p>Replace</p> +<pre> + basic_stringbuf<charT,traits,Allocator>* rdbuf() const; +</pre> +<p>with</p> +<pre> + basic_stringbuf<charT,traits,Allocator>* rdbuf(); + const basic_stringbuf<charT,traits,Allocator>* rdbuf() const; +</pre> + +<p>In 27.8.1.5, 27.8.1.7, 27.8.1.8, 27.8.1.10, 27.8.1.11, and 27.8.1.13</p> +<p>Replace</p> +<pre> + basic_filebuf<charT,traits>* rdbuf() const; +</pre> +<p>with</p> +<pre> + basic_filebuf<charT,traits>* rdbuf(); + const basic_filebuf<charT,traits>* rdbuf() const; +</pre> <p>----- End of document -----</p> </body> </html> diff --git a/libstdc++-v3/docs/html/ext/lwg-defects.html b/libstdc++-v3/docs/html/ext/lwg-defects.html index bd3af811383..eea548b8db7 100644 --- a/libstdc++-v3/docs/html/ext/lwg-defects.html +++ b/libstdc++-v3/docs/html/ext/lwg-defects.html @@ -5,11 +5,11 @@ <table> <tr> <td align="left">Doc. no.</td> -<td align="left">J16/01-0053 = WG21 N1338</td> +<td align="left">J16/02-0028 = WG21 N1370</td> </tr> <tr> <td align="left">Date:</td> -<td align="left">09 Nov 2001</td> +<td align="left">10 May 2002</td> </tr> <tr> <td align="left">Project:</td> @@ -20,7 +20,7 @@ <td align="left">Matt Austern <austern@research.att.com></td> </tr> </table> -<h1>C++ Standard Library Defect Report List (Revision 20)</h1> +<h1>C++ Standard Library Defect Report List (Revision 22)</h1> <p>Reference ISO/IEC IS 14882:1998(E)</p> <p>Also see:</p> <ul> @@ -42,6 +42,12 @@ document.</p> <h2>Revision History</h2> <ul> +<li>R22: +Post-Curaçao mailing. Added new issues <a href="lwg-active.html#362">362</a>-<a href="lwg-active.html#366">366</a>. +</li> +<li>R21: +Pre-Curaçao mailing. Added new issues <a href="lwg-closed.html#351">351</a>-<a href="lwg-active.html#361">361</a>. +</li> <li>R20: Post-Redmond mailing; reflects actions taken in Redmond. Added new issues <a href="lwg-active.html#336">336</a>-<a href="lwg-active.html#350">350</a>, of which issues @@ -49,19 +55,19 @@ new issues <a href="lwg-active.html#336">336</a>-<a href="lwg-active.html#350">3 not discussed at the meeting. All Ready issues were moved to DR status, with the exception of issues -<a href="lwg-active.html#284">284</a>, <a href="lwg-active.html#241">241</a>, and <a href="lwg-closed.html#267">267</a>. +<a href="lwg-defects.html#284">284</a>, <a href="lwg-active.html#241">241</a>, and <a href="lwg-closed.html#267">267</a>. Noteworthy issues discussed at Redmond include <a href="lwg-active.html#120">120</a> <a href="lwg-active.html#202">202</a>, <a href="lwg-active.html#226">226</a>, <a href="lwg-active.html#233">233</a>, -<a href="lwg-active.html#270">270</a>, <a href="lwg-active.html#253">253</a>, <a href="lwg-active.html#254">254</a>, <a href="lwg-active.html#323">323</a>. +<a href="lwg-defects.html#270">270</a>, <a href="lwg-active.html#253">253</a>, <a href="lwg-active.html#254">254</a>, <a href="lwg-active.html#323">323</a>. </li> <li>R19: Pre-Redmond mailing. Added new issues -<a href="lwg-active.html#323">323</a>-<a href="lwg-active.html#335">335</a>. +<a href="lwg-active.html#323">323</a>-<a href="lwg-defects.html#335">335</a>. </li> <li>R18: Post-Copenhagen mailing; reflects actions taken in Copenhagen. -Added new issues <a href="lwg-defects.html#312">312</a>-<a href="lwg-active.html#317">317</a>, and discussed +Added new issues <a href="lwg-defects.html#312">312</a>-<a href="lwg-defects.html#317">317</a>, and discussed new issues <a href="lwg-defects.html#271">271</a>-<a href="lwg-closed.html#314">314</a>. Changed status of issues @@ -80,7 +86,7 @@ Changed status of issues <a href="lwg-defects.html#238">238</a> <a href="lwg-active.html#241">241</a> <a href="lwg-defects.html#242">242</a> <a href="lwg-defects.html#250">250</a> <a href="lwg-defects.html#259">259</a> <a href="lwg-defects.html#264">264</a> <a href="lwg-defects.html#266">266</a> <a href="lwg-closed.html#267">267</a> <a href="lwg-defects.html#271">271</a> <a href="lwg-defects.html#272">272</a> <a href="lwg-defects.html#273">273</a> <a href="lwg-defects.html#275">275</a> -<a href="lwg-defects.html#281">281</a> <a href="lwg-active.html#284">284</a> <a href="lwg-defects.html#285">285</a> <a href="lwg-defects.html#286">286</a> +<a href="lwg-defects.html#281">281</a> <a href="lwg-defects.html#284">284</a> <a href="lwg-defects.html#285">285</a> <a href="lwg-defects.html#286">286</a> <a href="lwg-defects.html#288">288</a> <a href="lwg-defects.html#292">292</a> <a href="lwg-defects.html#295">295</a> <a href="lwg-defects.html#297">297</a> <a href="lwg-defects.html#298">298</a> <a href="lwg-defects.html#301">301</a> <a href="lwg-defects.html#303">303</a> <a href="lwg-defects.html#306">306</a> <a href="lwg-defects.html#307">307</a> <a href="lwg-defects.html#308">308</a> <a href="lwg-defects.html#312">312</a> @@ -95,8 +101,8 @@ as NAD. </li> <li>R17: Pre-Copenhagen mailing. Converted issues list to XML. Added proposed -resolutions for issues <a href="lwg-defects.html#49">49</a>, <a href="lwg-active.html#76">76</a>, <a href="lwg-active.html#91">91</a>, <a href="lwg-defects.html#235">235</a>, <a href="lwg-defects.html#250">250</a>, <a href="lwg-closed.html#267">267</a>. -Added new issues <a href="lwg-active.html#278">278</a>-<a href="lwg-active.html#311">311</a>. +resolutions for issues <a href="lwg-defects.html#49">49</a>, <a href="lwg-defects.html#76">76</a>, <a href="lwg-active.html#91">91</a>, <a href="lwg-defects.html#235">235</a>, <a href="lwg-defects.html#250">250</a>, <a href="lwg-closed.html#267">267</a>. +Added new issues <a href="lwg-active.html#278">278</a>-<a href="lwg-defects.html#311">311</a>. </li> <li>R16: post-Toronto mailing; reflects actions taken in Toronto. Added new @@ -142,7 +148,7 @@ of issue <a href="lwg-defects.html#29">29</a>. Add further rationale to issue post-Kona mailing: Updated to reflect LWG and full committee actions in Kona (99-0048/N1224). Note changed resolution of issues <a href="lwg-closed.html#4">4</a> and <a href="lwg-defects.html#38">38</a>. Added issues <a href="lwg-closed.html#196">196</a> -to <a href="lwg-active.html#198">198</a>. Closed issues list split into "defects" and +to <a href="lwg-defects.html#198">198</a>. Closed issues list split into "defects" and "closed" documents. Changed the proposed resolution of issue <a href="lwg-closed.html#4">4</a> to NAD, and changed the wording of proposed resolution of issue <a href="lwg-defects.html#38">38</a>. @@ -2229,6 +2235,119 @@ change the <tt>stateT</tt> argument type on both member <tt>max</tt> elements.</p> </blockquote> <hr> +<a name="76"><h3>76. Can a <tt>codecvt</tt> facet always convert one internal character at a time?</h3></a><p> +<b>Section:</b> 22.2.1.5 <a href="lib-locales.html#lib.locale.codecvt"> [lib.locale.codecvt]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Matt Austern <b>Date:</b> 25 Sep 1998</p> +<p>This issue concerns the requirements on classes derived from +<tt>codecvt</tt>, including user-defined classes. What are the +restrictions on the conversion from external characters +(e.g. <tt>char</tt>) to internal characters (e.g. <tt>wchar_t</tt>)? +Or, alternatively, what assumptions about <tt>codecvt</tt> facets can +the I/O library make? </p> + +<p>The question is whether it's possible to convert from internal +characters to external characters one internal character at a time, +and whether, given a valid sequence of external characters, it's +possible to pick off internal characters one at a time. Or, to put it +differently: given a sequence of external characters and the +corresponding sequence of internal characters, does a position in the +internal sequence correspond to some position in the external +sequence? </p> + +<p>To make this concrete, suppose that <tt>[first, last)</tt> is a +sequence of <i>M</i> external characters and that <tt>[ifirst, +ilast)</tt> is the corresponding sequence of <i>N</i> internal +characters, where <i>N > 1</i>. That is, <tt>my_encoding.in()</tt>, +applied to <tt>[first, last)</tt>, yields <tt>[ifirst, +ilast)</tt>. Now the question: does there necessarily exist a +subsequence of external characters, <tt>[first, last_1)</tt>, such +that the corresponding sequence of internal characters is the single +character <tt>*ifirst</tt>? +</p> + +<p>(What a "no" answer would mean is that +<tt>my_encoding</tt> translates sequences only as blocks. There's a +sequence of <i>M</i> external characters that maps to a sequence of +<i>N</i> internal characters, but that external sequence has no +subsequence that maps to <i>N-1</i> internal characters.) </p> + +<p>Some of the wording in the standard, such as the description of +<tt>codecvt::do_max_length</tt> (22.2.1.5.2 <a href="lib-locales.html#lib.locale.codecvt.virtuals"> [lib.locale.codecvt.virtuals]</a>, +paragraph 11) and <tt>basic_filebuf::underflow</tt> (27.8.1.4 <a href="lib-iostreams.html#lib.filebuf.virtuals"> [lib.filebuf.virtuals]</a>, paragraph 3) suggests that it must always be +possible to pick off internal characters one at a time from a sequence +of external characters. However, this is never explicitly stated one +way or the other. </p> + +<p>This issue seems (and is) quite technical, but it is important if +we expect users to provide their own encoding facets. This is an area +where the standard library calls user-supplied code, so a well-defined +set of requirements for the user-supplied code is crucial. Users must +be aware of the assumptions that the library makes. This issue affects +positioning operations on <tt>basic_filebuf</tt>, unbuffered input, +and several of <tt>codecvt</tt>'s member functions. </p> +<p><b>Proposed resolution:</b></p> +<p>Add the following text as a new paragraph, following 22.2.1.5.2 <a href="lib-locales.html#lib.locale.codecvt.virtuals"> [lib.locale.codecvt.virtuals]</a> paragraph 2:</p> + +<blockquote> +<p>A <tt>codecvt</tt> facet that is used by <tt>basic_filebuf</tt> +(27.8 <a href="lib-iostreams.html#lib.file.streams"> [lib.file.streams]</a>) must have the property that if</p> +<pre> + do_out(state, from, from_end, from_next, to, to_lim, to_next) +</pre> +would return <tt>ok</tt>, where <tt>from != from_end</tt>, then +<pre> + do_out(state, from, from + 1, from_next, to, to_end, to_next) +</pre> +must also return <tt>ok</tt>, and that if +<pre> + do_in(state, from, from_end, from_next, to, to_lim, to_next) +</pre> +would return <tt>ok</tt>, where <tt>to != to_lim</tt>, then +<pre> + do_in(state, from, from_end, from_next, to, to + 1, to_next) +</pre> +<p>must also return <tt>ok</tt>. [<i>Footnote:</i> Informally, this +means that <tt>basic_filebuf</tt> assumes that the mapping from +internal to external characters is 1 to N: a <tt>codecvt</tt> that is +used by <tt>basic_filebuf</tt> must be able to translate characters +one internal character at a time. <i>--End Footnote</i>]</p> +</blockquote> + +<p><i>[Redmond: Minor change in proposed resolution. Original +proposed resolution talked about "success", with a parenthetical +comment that success meant returning <tt>ok</tt>. New wording +removes all talk about "success", and just talks about the +return value.]</i></p> + +<p><b>Rationale:</b></p> + + <p>The proposed resoluion says that conversions can be performed one + internal character at a time. This rules out some encodings that + would otherwise be legal. The alternative answer would mean there + would be some internal positions that do not correspond to any + external file position.</p> + <p> + An example of an encoding that this rules out is one where the + <tt>internT</tt> and <tt>externT</tt> are of the same type, and + where the internal sequence <tt>c1 c2</tt> corresponds to the + external sequence <tt>c2 c1</tt>. + </p> + <p>It was generally agreed that <tt>basic_filebuf</tt> relies + on this property: it was designed under the assumption that + the external-to-internal mapping is N-to-1, and it is not clear + that <tt>basic_filebuf</tt> is implementable without that + restriction. + </p> + <p> + The proposed resolution is expressed as a restriction on + <tt>codecvt</tt> when used by <tt>basic_filebuf</tt>, rather + than a blanket restriction on all <tt>codecvt</tt> facets, + because <tt>basic_filebuf</tt> is the only other part of the + library that uses <tt>codecvt</tt>. If a user wants to define + a <tt>codecvt</tt> facet that implements a more general N-to-M + mapping, there is no reason to prohibit it, so long as the user + does not expect <tt>basic_filebuf</tt> to be able to use it. + </p> +<hr> <a name="78"><h3>78. Typo: event_call_back</h3></a><p> <b>Section:</b> 27.4.2 <a href="lib-iostreams.html#lib.ios.base"> [lib.ios.base]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Nico Josuttis <b>Date:</b> 29 Sep 1998</p> <p>typo: event_call_back should be event_callback </p> @@ -3210,7 +3329,7 @@ with:</p> <p>Sections 21.3.6.4 paragraph 1 and 21.3.6.6 paragraph 1 surely have misprints where they say:<br> <br> -— <tt>xpos <= pos</tt> and <tt>pos < size();</tt> +— <tt>xpos <= pos</tt> and <tt>pos < size();</tt> </p> <p>Surely the document meant to say ``<tt>xpos < size()</tt>'' in both places.</p> @@ -3220,11 +3339,11 @@ proposed resolution.]</i></p> <p><b>Proposed resolution:</b></p> <p>Change Sections 21.3.6.4 paragraph 1 and 21.3.6.6 paragraph 1, the line which says:<br> <br> -— <tt>xpos <= pos</tt> and <tt>pos < size();<br> +— <tt>xpos <= pos</tt> and <tt>pos < size();<br> <br> </tt>to:<br> <tt><br> -</tt>— <tt>xpos <= pos</tt> and <tt>xpos < size();</tt> +</tt>— <tt>xpos <= pos</tt> and <tt>xpos < size();</tt> </p> <hr> <a name="142"><h3>142. lexicographical_compare complexity wrong</h3></a><p> @@ -3989,10 +4108,10 @@ proposed resolution passed their test suites.</p> omit the <tt> std::</tt> namespace qualification.</p> <p>For example, 17.4.3.4 <a href="lib-intro.html#lib.replacement.functions"> [lib.replacement.functions]</a> paragraph 2:</p> <blockquote> -<pre>— operator new(size_t) -— operator new(size_t, const std::nothrow_t&) -— operator new[](size_t) -— operator new[](size_t, const std::nothrow_t&)</pre> +<pre>— operator new(size_t) +— operator new(size_t, const std::nothrow_t&) +— operator new[](size_t) +— operator new[](size_t, const std::nothrow_t&)</pre> </blockquote> <p><b>Proposed resolution:</b></p> <p> In 17.4.3.4 <a href="lib-intro.html#lib.replacement.functions"> [lib.replacement.functions]</a> paragraph 2: replace:</p> @@ -4522,6 +4641,132 @@ returns <tt>traits::eof()</tt>, the function calls </p> </blockquote> <hr> +<a name="198"><h3>198. Validity of pointers and references unspecified after iterator destruction</h3></a><p> +<b>Section:</b> 24.1 <a href="lib-iterators.html#lib.iterator.requirements"> [lib.iterator.requirements]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Beman Dawes <b>Date:</b> 3 Nov 1999</p> +<p> +Is a pointer or reference obtained from an iterator still valid after +destruction of the iterator? +</p> +<p> +Is a pointer or reference obtained from an iterator still valid after the value +of the iterator changes? +</p> +<blockquote> +<pre> +#include <iostream> +#include <vector> +#include <iterator> + +int main() +{ + typedef std::vector<int> vec_t; + vec_t v; + v.push_back( 1 ); + + // Is a pointer or reference obtained from an iterator still + // valid after destruction of the iterator? + int * p = &*v.begin(); + std::cout << *p << '\n'; // OK? + + // Is a pointer or reference obtained from an iterator still + // valid after the value of the iterator changes? + vec_t::iterator iter( v.begin() ); + p = &*iter++; + std::cout << *p << '\n'; // OK? + + return 0; +} +</pre> +</blockquote> + +<p>The standard doesn't appear to directly address these +questions. The standard needs to be clarified. At least two real-world +cases have been reported where library implementors wasted +considerable effort because of the lack of clarity in the +standard. The question is important because requiring pointers and +references to remain valid has the effect for practical purposes of +prohibiting iterators from pointing to cached rather than actual +elements of containers.</p> + +<p>The standard itself assumes that pointers and references obtained +from an iterator are still valid after iterator destruction or +change. The definition of reverse_iterator::operator*(), 24.4.1.3.3 <a href="lib-iterators.html#lib.reverse.iter.op.star"> [lib.reverse.iter.op.star]</a>, which returns a reference, defines +effects:</p> + +<blockquote> + <pre>Iterator tmp = current; +return *--tmp;</pre> +</blockquote> +<p>The definition of reverse_iterator::operator->(), 24.4.1.3.4 <a href="lib-iterators.html#lib.reverse.iter.opref"> [lib.reverse.iter.opref]</a>, which returns a pointer, defines effects:</p> +<blockquote> + <pre>return &(operator*());</pre> +</blockquote> + +<p>Because the standard itself assumes pointers and references remain +valid after iterator destruction or change, the standard should say so +explicitly. This will also reduce the chance of user code breaking +unexpectedly when porting to a different standard library +implementation.</p> +<p><b>Proposed resolution:</b></p> +<p>Add a new paragraph to 24.1 <a href="lib-iterators.html#lib.iterator.requirements"> [lib.iterator.requirements]</a>:</p> +<blockquote> +Destruction of an iterator may invalidate pointers and references +previously obtained from that iterator. +</blockquote> + +<p>Replace paragraph 1 of 24.4.1.3.3 <a href="lib-iterators.html#lib.reverse.iter.op.star"> [lib.reverse.iter.op.star]</a> with:</p> + +<blockquote> +<p><b>Effects:</b></p> +<pre> + this->tmp = current; + --this->tmp; + return *this->tmp; +</pre> + +<p> +[<i>Note:</i> This operation must use an auxiliary member variable, +rather than a temporary variable, to avoid returning a reference that +persists beyond the lifetime of its associated iterator. (See +24.1 <a href="lib-iterators.html#lib.iterator.requirements"> [lib.iterator.requirements]</a>.) The name of this member variable is shown for +exposition only. <i>--end note</i>] +</p> +</blockquote> + +<p><i>[Post-Tokyo: The issue has been reformulated purely +in terms of iterators.]</i></p> + +<p><i>[Pre-Toronto: Steve Cleary pointed out the no-invalidation +assumption by reverse_iterator. The issue and proposed resolution was +reformulated yet again to reflect this reality.]</i></p> + +<p><i>[Copenhagen: Steve Cleary pointed out that reverse_iterator +assumes its underlying iterator has persistent pointers and +references. Andy Koenig pointed out that it is possible to rewrite +reverse_iterator so that it no longer makes such an assupmption. +However, this issue is related to issue <a href="lwg-active.html#299">299</a>. If we +decide it is intentional that <tt>p[n]</tt> may return by value +instead of reference when <tt>p</tt> is a Random Access Iterator, +other changes in reverse_iterator will be necessary.]</i></p> +<p><b>Rationale:</b></p> +<p>This issue has been discussed extensively. Note that it is +<i>not</i> an issue about the behavior of predefined iterators. It is +asking whether or not user-defined iterators are permitted to have +transient pointers and references. Several people presented examples +of useful user-defined iterators that have such a property; examples +include a B-tree iterator, and an "iota iterator" that doesn't point +to memory. Library implementors already seem to be able to cope with +such iterators: they take pains to avoid forming references to memory +that gets iterated past. The only place where this is a problem is +<tt>reverse_iterator</tt>, so this issue changes +<tt>reverse_iterator</tt> to make it work.</p> + +<p>This resolution does not weaken any guarantees provided by +predefined iterators like <tt>list<int>::iterator</tt>. +Clause 23 should be reviewed to make sure that guarantees for +predefined iterators are as strong as users expect.</p> + +<hr> <a name="199"><h3>199. What does <tt>allocate(0)</tt> return?</h3></a><p> <b>Section:</b> 20.1.5 <a href="lib-utilities.html#lib.allocator.requirements"> [lib.allocator.requirements]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Matt Austern <b>Date:</b> 19 Nov 1999</p> <p> @@ -5218,6 +5463,89 @@ defined to be <tt>basic_string<cT>()</tt>.</p> we fixed it, it would say just the same thing as text that's already in the standard.</p> <hr> +<a name="239"><h3>239. Complexity of unique() and/or unique_copy incorrect</h3></a><p> +<b>Section:</b> 25.2.8 <a href="lib-algorithms.html#lib.alg.unique"> [lib.alg.unique]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Angelika Langer <b>Date:</b> May 15 2000</p> +<p>The complexity of unique and unique_copy are inconsistent with each +other and inconsistent with the implementations. The standard +specifies:</p> + +<p>for unique():</p> + +<blockquote>-3- Complexity: If the range (last - first) is not empty, exactly +(last - first) - 1 applications of the corresponding predicate, otherwise +no applications of the predicate.</blockquote> + +<p>for unique_copy():</p> + +<blockquote>-7- Complexity: Exactly last - first applications of the corresponding +predicate.</blockquote> + +<p> +The implementations do it the other way round: unique() applies the +predicate last-first times and unique_copy() applies it last-first-1 +times.</p> + +<p>As both algorithms use the predicate for pair-wise comparison of +sequence elements I don't see a justification for unique_copy() +applying the predicate last-first times, especially since it is not +specified to which pair in the sequence the predicate is applied +twice.</p> +<p><b>Proposed resolution:</b></p> +<p>Change both complexity sections in 25.2.8 <a href="lib-algorithms.html#lib.alg.unique"> [lib.alg.unique]</a> to:</p> + +<blockquote>Complexity: For nonempty ranges, exactly last - first - 1 +applications of the corresponding predicate.</blockquote> + +<hr> +<a name="240"><h3>240. Complexity of adjacent_find() is meaningless</h3></a><p> +<b>Section:</b> 25.1.5 <a href="lib-algorithms.html#lib.alg.adjacent.find"> [lib.alg.adjacent.find]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Angelika Langer <b>Date:</b> May 15 2000</p> +<p>The complexity section of adjacent_find is defective:</p> + +<blockquote> +<pre> +template <class ForwardIterator> +ForwardIterator adjacent_find(ForwardIterator first, ForwardIterator last + BinaryPredicate pred); +</pre> + +<p>-1- Returns: The first iterator i such that both i and i + 1 are in +the range [first, last) for which the following corresponding +conditions hold: *i == *(i + 1), pred(*i, *(i + 1)) != false. Returns +last if no such iterator is found.</p> + +<p>-2- Complexity: Exactly find(first, last, value) - first applications +of the corresponding predicate. +</p> +</blockquote> + +<p>In the Complexity section, it is not defined what "value" +is supposed to mean. My best guess is that "value" means an +object for which one of the conditions pred(*i,value) or +pred(value,*i) is true, where i is the iterator defined in the Returns +section. However, the value type of the input sequence need not be +equality-comparable and for this reason the term find(first, last, +value) - first is meaningless.</p> + +<p>A term such as find_if(first, last, bind2nd(pred,*i)) - first or +find_if(first, last, bind1st(pred,*i)) - first might come closer to +the intended specification. Binders can only be applied to function +objects that have the function call operator declared const, which is +not required of predicates because they can have non-const data +members. For this reason, a specification using a binder could only be +an "as-if" specification.</p> +<p><b>Proposed resolution:</b></p> +<p>Change the complexity section in 25.1.5 <a href="lib-algorithms.html#lib.alg.adjacent.find"> [lib.alg.adjacent.find]</a> to:</p> +<blockquote> +For a nonempty range, exactly <tt>min((<i>i</i> - <i>first</i>) + 1, +(<i>last</i> - <i>first</i>) - 1)</tt> applications of the +corresponding predicate, where <i>i</i> is <tt>adjacent_find</tt>'s +return value. +</blockquote> + +<p><i>[Copenhagen: the original resolution specified an upper +bound. The LWG preferred an exact count.]</i></p> + +<hr> <a name="242"><h3>242. Side effects of function objects</h3></a><p> <b>Section:</b> 25.2.3 <a href="lib-algorithms.html#lib.alg.transform"> [lib.alg.transform]</a>, 26.4 <a href="lib-numerics.html#lib.numeric.ops"> [lib.numeric.ops]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Angelika Langer <b>Date:</b> May 15 2000</p> <p>The algorithms transform(), accumulate(), inner_product(), @@ -5894,6 +6222,259 @@ are missing.</p> locale(const locale& other) throw(); </pre> <hr> +<a name="270"><h3>270. Binary search requirements overly strict</h3></a><p> +<b>Section:</b> 25.3.3 <a href="lib-algorithms.html#lib.alg.binary.search"> [lib.alg.binary.search]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Matt Austern <b>Date:</b> 18 Oct 2000</p> +<p> +Each of the four binary search algorithms (lower_bound, upper_bound, +equal_range, binary_search) has a form that allows the user to pass a +comparison function object. According to 25.3, paragraph 2, that +comparison function object has to be a strict weak ordering. +</p> + +<p> +This requirement is slightly too strict. Suppose we are searching +through a sequence containing objects of type X, where X is some +large record with an integer key. We might reasonably want to look +up a record by key, in which case we would want to write something +like this: +</p> +<pre> + struct key_comp { + bool operator()(const X& x, int n) const { + return x.key() < n; + } + } + + std::lower_bound(first, last, 47, key_comp()); +</pre> + +<p> +key_comp is not a strict weak ordering, but there is no reason to +prohibit its use in lower_bound. +</p> + +<p> +There's no difficulty in implementing lower_bound so that it allows +the use of something like key_comp. (It will probably work unless an +implementor takes special pains to forbid it.) What's difficult is +formulating language in the standard to specify what kind of +comparison function is acceptable. We need a notion that's slightly +more general than that of a strict weak ordering, one that can encompass +a comparison function that involves different types. Expressing that +notion may be complicated. +</p> + +<p><i>Additional questions raised at the Toronto meeting:</i></p> +<ul> +<li> Do we really want to specify what ordering the implementor must + use when calling the function object? The standard gives + specific expressions when describing these algorithms, but it also + says that other expressions (with different argument order) are + equivalent.</li> +<li> If we are specifying ordering, note that the standard uses both + orderings when describing <tt>equal_range</tt>.</li> +<li> Are we talking about requiring these algorithms to work properly + when passed a binary function object whose two argument types + are not the same, or are we talking about requirements when + they are passed a binary function object with several overloaded + versions of <tt>operator()</tt>?</li> +<li> The definition of a strict weak ordering does not appear to give + any guidance on issues of overloading; it only discusses expressions, + and all of the values in these expressions are of the same type. + Some clarification would seem to be in order.</li> +</ul> + +<p><i>Additional discussion from Copenhagen:</i></p> +<ul> +<li>It was generally agreed that there is a real defect here: if +the predicate is merely required to be a Strict Weak Ordering, then +it's possible to pass in a function object with an overloaded +operator(), where the version that's actually called does something +completely inappropriate. (Such as returning a random value.)</li> + +<li>An alternative formulation was presented in a paper distributed by +David Abrahams at the meeting, "Binary Search with Heterogeneous +Comparison", J16-01/0027 = WG21 N1313: Instead of viewing the +predicate as a Strict Weak Ordering acting on a sorted sequence, view +the predicate/value pair as something that partitions a sequence. +This is almost equivalent to saying that we should view binary search +as if we are given a unary predicate and a sequence, such that f(*p) +is true for all p below a specific point and false for all p above it. +The proposed resolution is based on that alternative formulation.</li> +</ul> +<p><b>Proposed resolution:</b></p> + +<p>Change 25.3 [lib.alg.sorting] paragraph 3 from:</p> + +<blockquote> + 3 For all algorithms that take Compare, there is a version that uses + operator< instead. That is, comp(*i, *j) != false defaults to *i < + *j != false. For the algorithms to work correctly, comp has to + induce a strict weak ordering on the values. +</blockquote> + +<p>to:</p> + +<blockquote> + 3 For all algorithms that take Compare, there is a version that uses + operator< instead. That is, comp(*i, *j) != false defaults to *i + < *j != false. For algorithms other than those described in + lib.alg.binary.search (25.3.3) to work correctly, comp has to induce + a strict weak ordering on the values. +</blockquote> + +<p>Add the following paragraph after 25.3 [lib.alg.sorting] paragraph 5:</p> + +<blockquote> + -6- A sequence [start, finish) is partitioned with respect to an + expression f(e) if there exists an integer n such that + for all 0 <= i < distance(start, finish), f(*(begin+i)) is true if + and only if i < n. +</blockquote> + +<p>Change 25.3.3 [lib.alg.binary.search] paragraph 1 from:</p> + +<blockquote> + -1- All of the algorithms in this section are versions of binary + search and assume that the sequence being searched is in order + according to the implied or explicit comparison function. They work + on non-random access iterators minimizing the number of + comparisons, which will be logarithmic for all types of + iterators. They are especially appropriate for random access + iterators, because these algorithms do a logarithmic number of + steps through the data structure. For non-random access iterators + they execute a linear number of steps. +</blockquote> + +<p>to:</p> + +<blockquote> + -1- All of the algorithms in this section are versions of binary + search and assume that the sequence being searched is partitioned + with respect to an expression formed by binding the search key to + an argument of the implied or explicit comparison function. They + work on non-random access iterators minimizing the number of + comparisons, which will be logarithmic for all types of + iterators. They are especially appropriate for random access + iterators, because these algorithms do a logarithmic number of + steps through the data structure. For non-random access iterators + they execute a linear number of steps. +</blockquote> + +<p>Change 25.3.3.1 [lib.lower.bound] paragraph 1 from:</p> + +<blockquote> + -1- Requires: Type T is LessThanComparable + (lib.lessthancomparable). +</blockquote> + +<p>to:</p> + +<blockquote> + -1- Requires: The elements e of [first, last) are partitioned with + respect to the expression e < value or comp(e, value) +</blockquote> + + +<p>Remove 25.3.3.1 [lib.lower.bound] paragraph 2:</p> + +<blockquote> + -2- Effects: Finds the first position into which value can be + inserted without violating the ordering. +</blockquote> + +<p>Change 25.3.3.2 [lib.upper.bound] paragraph 1 from:</p> + +<blockquote> + -1- Requires: Type T is LessThanComparable (lib.lessthancomparable). +</blockquote> + +<p>to:</p> + +<blockquote> + -1- Requires: The elements e of [first, last) are partitioned with + respect to the expression !(value < e) or !comp(value, e) +</blockquote> + +<p>Remove 25.3.3.2 [lib.upper.bound] paragraph 2:</p> + +<blockquote> + -2- Effects: Finds the furthermost position into which value can be + inserted without violating the ordering. +</blockquote> + +<p>Change 25.3.3.3 [lib.equal.range] paragraph 1 from:</p> + +<blockquote> + -1- Requires: Type T is LessThanComparable + (lib.lessthancomparable). +</blockquote> + +<p>to:</p> + +<blockquote> + -1- Requires: The elements e of [first, last) are partitioned with + respect to the expressions e < value and !(value < e) or + comp(e, value) and !comp(value, e). Also, for all elements e of + [first, last), e < value implies !(value < e) or comp(e, + value) implies !comp(value, e) +</blockquote> + +<p>Change 25.3.3.3 [lib.equal.range] paragraph 2 from:</p> + +<blockquote> + -2- Effects: Finds the largest subrange [i, j) such that the value + can be inserted at any iterator k in it without violating the + ordering. k satisfies the corresponding conditions: !(*k < value) + && !(value < *k) or comp(*k, value) == false && comp(value, *k) == + false. +</blockquote> + +<p>to:</p> + +<pre> + -2- Returns: + make_pair(lower_bound(first, last, value), + upper_bound(first, last, value)) + or + make_pair(lower_bound(first, last, value, comp), + upper_bound(first, last, value, comp)) +</pre> + +<p>Change 25.3.3.3 [lib.binary.search] paragraph 1 from:</p> + +<blockquote> + -1- Requires: Type T is LessThanComparable + (lib.lessthancomparable). +</blockquote> + +<p>to:</p> + +<blockquote> + -1- Requires: The elements e of [first, last) are partitioned with + respect to the expressions e < value and !(value < e) or comp(e, + value) and !comp(value, e). Also, for all elements e of [first, + last), e < value implies !(value < e) or comp(e, value) implies + !comp(value, e) +</blockquote> + +<p><i>[Copenhagen: Dave Abrahams provided this wording]</i></p> + +<p><i>[Redmond: Minor changes in wording. (Removed "non-negative", and +changed the "other than those described in" wording.) Also, the LWG +decided to accept the "optional" part.]</i></p> + +<p><b>Rationale:</b></p> +<p>The proposed resolution reinterprets binary search. Instead of +thinking about searching for a value in a sorted range, we view that +as an important special case of a more general algorithm: searching +for the partition point in a partitioned range.</p> + +<p>We also add a guarantee that the old wording did not: we ensure +that the upper bound is no earlier than the lower bound, that +the pair returned by equal_range is a valid range, and that the first +part of that pair is the lower bound.</p> +<hr> <a name="271"><h3>271. basic_iostream missing typedefs</h3></a><p> <b>Section:</b> 27.6.1.5 <a href="lib-iostreams.html#lib.iostreamclass"> [lib.iostreamclass]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 02 Nov 2000</p> <p> @@ -5943,6 +6524,62 @@ class (14.6.2 [temp.dep]) and thus not visible.</p> <p>Qualify the names with the name of the class of which they are members, i.e., ios_base.</p> <hr> +<a name="274"><h3>274. a missing/impossible allocator requirement</h3></a><p> +<b>Section:</b> 20.1.5 <a href="lib-utilities.html#lib.allocator.requirements"> [lib.allocator.requirements]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 02 Nov 2000</p> +<p> +I see that table 31 in 20.1.5, p3 allows T in std::allocator<T> to be of +any type. But the synopsis in 20.4.1 calls for allocator<>::address() to +be overloaded on reference and const_reference, which is ill-formed for +all T = const U. In other words, this won't work: +</p> + +<p> +template class std::allocator<const int>; +</p> + +<p> +The obvious solution is to disallow specializations of allocators on +const types. However, while containers' elements are required to be +assignable (which rules out specializations on const T's), I think that +allocators might perhaps be potentially useful for const values in other +contexts. So if allocators are to allow const types a partial +specialization of std::allocator<const T> would probably have to be +provided. +</p> +<p><b>Proposed resolution:</b></p> +<p>Change the text in row 1, column 2 of table 32 in 20.1.5, p3 from</p> + + <blockquote> + any type + </blockquote> + +<p>to</p> + <blockquote> + any non-const, non-reference type + </blockquote> + +<p><i>[Redmond: previous proposed resolution was "any non-const, +non-volatile, non-reference type". Got rid of the "non-volatile".]</i></p> + +<p><b>Rationale:</b></p> +<p> +Two resolutions were originally proposed: one that partially +specialized std::allocator for const types, and one that said an +allocator's value type may not be const. The LWG chose the second. +The first wouldn't be appropriate, because allocators are intended for +use by containers, and const value types don't work in containers. +Encouraging the use of allocators with const value types would only +lead to unsafe code. +</p> +<p> +The original text for proposed resolution 2 was modified so that it +also forbids volatile types and reference types. +</p> + +<p><i>[Curaçao: LWG double checked and believes volatile is correctly +excluded from the PR.]</i></p> + +<hr> <a name="275"><h3>275. Wrong type in num_get::get() overloads</h3></a><p> <b>Section:</b> 22.2.2.1.1 <a href="lib-locales.html#lib.facet.num.get.members"> [lib.facet.num.get.members]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Matt Austern <b>Date:</b> 02 Nov 2000</p> <p> @@ -5994,6 +6631,150 @@ the arguments it was given. ios_base::iostate& err, float& val) const; </pre> <hr> +<a name="276"><h3>276. Assignable requirement for container value type overly strict</h3></a><p> +<b>Section:</b> 23.1 <a href="lib-containers.html#lib.container.requirements"> [lib.container.requirements]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Peter Dimov <b>Date:</b> 07 Nov 2000</p> +<p> +23.1/3 states that the objects stored in a container must be +Assignable. 23.3.1 <a href="lib-containers.html#lib.map"> [lib.map]</a>, paragraph 2, +states that map satisfies all requirements for a container, while in +the same time defining value_type as pair<const Key, T> - a type +that is not Assignable. +</p> + +<p> +It should be noted that there exists a valid and non-contradictory +interpretation of the current text. The wording in 23.1/3 avoids +mentioning value_type, referring instead to "objects stored in a +container." One might argue that map does not store objects of +type map::value_type, but of map::mapped_type instead, and that the +Assignable requirement applies to map::mapped_type, not +map::value_type. +</p> + +<p> +However, this makes map a special case (other containers store objects of +type value_type) and the Assignable requirement is needlessly restrictive in +general. +</p> + +<p> +For example, the proposed resolution of active library issue +<a href="lwg-defects.html#103">103</a> is to make set::iterator a constant iterator; this +means that no set operations can exploit the fact that the stored +objects are Assignable. +</p> + +<p> +This is related to, but slightly broader than, closed issue +<a href="lwg-closed.html#140">140</a>. +</p> +<p><b>Proposed resolution:</b></p> +<p>23.1/3: Strike the trailing part of the sentence:</p> + <blockquote> + , and the additional requirements of Assignable types from 23.1/3 + </blockquote> +<p>so that it reads:</p> + <blockquote> + -3- The type of objects stored in these components must meet the + requirements of CopyConstructible types (lib.copyconstructible). + </blockquote> + +<p>23.1/4: Modify to make clear that this requirement is not for all +containers. Change to:</p> + +<blockquote> +-4- Table 64 defines the Assignable requirement. Some containers +require this property of the types to be stored in the container. T is +the type used to instantiate the container. t is a value of T, and u is +a value of (possibly const) T. +</blockquote> + +<p>23.1, Table 65: in the first row, change "T is Assignable" to "T is +CopyConstructible".</p> + +<p>23.2.1/2: Add sentence for Assignable requirement. Change to:</p> + +<blockquote> +-2- A deque satisfies all of the requirements of a container and of a +reversible container (given in tables in lib.container.requirements) and +of a sequence, including the optional sequence requirements +(lib.sequence.reqmts). In addition to the requirements on the stored +object described in 23.1[lib.container.requirements], the stored object +must also meet the requirements of Assignable. Descriptions are +provided here only for operations on deque that are not described in one +of these tables or for operations where there is additional semantic +information. +</blockquote> + +<p>23.2.2/2: Add Assignable requirement to specific methods of list. +Change to:</p> + +<blockquote> +<p>-2- A list satisfies all of the requirements of a container and of a +reversible container (given in two tables in lib.container.requirements) +and of a sequence, including most of the the optional sequence +requirements (lib.sequence.reqmts). The exceptions are the operator[] +and at member functions, which are not provided. + +[Footnote: These member functions are only provided by containers whose +iterators are random access iterators. --- end foonote] +</p> + +<p>list does not require the stored type T to be Assignable unless the +following methods are instantiated: + +[Footnote: Implementors are permitted but not required to take advantage +of T's Assignable properties for these methods. -- end foonote] +</p> +<pre> + list<T,Allocator>& operator=(const list<T,Allocator>& x ); + template <class InputIterator> + void assign(InputIterator first, InputIterator last); + void assign(size_type n, const T& t); +</pre> + + +<p>Descriptions are provided here only for operations on list that are not +described in one of these tables or for operations where there is +additional semantic information.</p> +</blockquote> + +<p>23.2.4/2: Add sentence for Assignable requirement. Change to:</p> + +<blockquote> +-2- A vector satisfies all of the requirements of a container and of a +reversible container (given in two tables in lib.container.requirements) +and of a sequence, including most of the optional sequence requirements +(lib.sequence.reqmts). The exceptions are the push_front and pop_front +member functions, which are not provided. In addition to the +requirements on the stored object described in +23.1[lib.container.requirements], the stored object must also meet the +requirements of Assignable. Descriptions are provided here only for +operations on vector that are not described in one of these tables or +for operations where there is additional semantic information. +</blockquote> +<p><b>Rationale:</b></p> +<p>list, set, multiset, map, multimap are able to store non-Assignables. +However, there is some concern about <tt>list<T></tt>: +although in general there's no reason for T to be Assignable, some +implementations of the member functions <tt>operator=</tt> and +<tt>assign</tt> do rely on that requirement. The LWG does not want +to forbid such implementations.</p> + +<p>Note that the type stored in a standard container must still satisfy +the requirements of the container's allocator; this rules out, for +example, such types as "const int". See issue <a href="lwg-defects.html#274">274</a> +for more details. +</p> + +<p>In principle we could also relax the "Assignable" requirement for +individual <tt>vector</tt> member functions, such as +<tt>push_back</tt>. However, the LWG did not see great value in such +selective relaxation. Doing so would remove implementors' freedom to +implement <tt>vector::push_back</tt> in terms of +<tt>vector::insert</tt>.</p> + +<hr> <a name="281"><h3>281. std::min() and max() requirements overly restrictive</h3></a><p> <b>Section:</b> 25.3.7 <a href="lib-algorithms.html#lib.alg.min.max"> [lib.alg.min.max]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 02 Dec 2000</p> <p>The requirements in 25.3.7, p1 and 4 call for T to satisfy the @@ -6016,6 +6797,54 @@ is unnecessary. (20.1.2 <a href="lib-utilities.html#lib.lessthancomparable"> [lib.lessthancomparable]</a>). </p> <hr> +<a name="284"><h3>284. unportable example in 20.3.7, p6</h3></a><p> +<b>Section:</b> 20.3.7 <a href="lib-utilities.html#lib.function.pointer.adaptors"> [lib.function.pointer.adaptors]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 26 Dec 2000</p> +<p>The example in 20.3.7 <a href="lib-utilities.html#lib.function.pointer.adaptors"> [lib.function.pointer.adaptors]</a>, p6 shows how to use the C +library function <tt>strcmp()</tt> with the function pointer adapter +<tt>ptr_fun()</tt>. But since it's unspecified whether the C library +functions have <tt>extern "C"</tt> or <tt>extern +"C++"</tt> linkage [17.4.2.2 <a href="lib-intro.html#lib.using.linkage"> [lib.using.linkage]</a>], and since +function pointers with different the language linkage specifications +(7.5 <a href="dcl.html#dcl.link"> [dcl.link]</a>) are incompatible, whether this example is +well-formed is unspecified. +</p> +<p><b>Proposed resolution:</b></p> +<p>Change 20.3.7 <a href="lib-utilities.html#lib.function.pointer.adaptors"> [lib.function.pointer.adaptors]</a> paragraph 6 from:</p> +<blockquote> + <p>[<i>Example:</i> +</p> + <pre> + replace_if(v.begin(), v.end(), not1(bind2nd(ptr_fun(strcmp), "C")), "C++"); + </pre> + <p>replaces each <tt>C</tt> with <tt>C++</tt> in sequence <tt>v</tt>.</p> +</blockquote> + + +<p>to:</p> +<blockquote> + <p>[<i>Example:</i> +</p> + <pre> + int compare(const char*, const char*); + replace_if(v.begin(), v.end(), + not1(bind2nd(ptr_fun(compare), "abc")), "def"); + </pre> + <p>replaces each <tt>abc</tt> with <tt>def</tt> in sequence <tt>v</tt>.</p> +</blockquote> + +<p>Also, remove footnote 215 in that same paragraph.</p> + +<p><i>[Copenhagen: Minor change in the proposed resolution. Since this +issue deals in part with C and C++ linkage, it was believed to be too +confusing for the strings in the example to be "C" and "C++". +]</i></p> + +<p><i>[Redmond: More minor changes. Got rid of the footnote (which +seems to make a sweeping normative requirement, even though footnotes +aren't normative), and changed the sentence after the footnote so that +it corresponds to the new code fragment.]</i></p> + +<hr> <a name="285"><h3>285. minor editorial errors in fstream ctors</h3></a><p> <b>Section:</b> 27.8.1.6 <a href="lib-iostreams.html#lib.ifstream.cons"> [lib.ifstream.cons]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 31 Dec 2000</p> <p>27.8.1.6 <a href="lib-iostreams.html#lib.ifstream.cons"> [lib.ifstream.cons]</a>, p2, 27.8.1.9 <a href="lib-iostreams.html#lib.ofstream.cons"> [lib.ofstream.cons]</a>, p2, and @@ -6695,6 +7524,125 @@ Table 82. However, <cstdio> is mentioned several times within section 27.8 <a href="lib-iostreams.html#lib.file.streams"> [lib.file.streams]</a>, including 27.8.2 <a href="lib-iostreams.html#lib.c.files"> [lib.c.files]</a>.]</i></p> <hr> +<a name="310"><h3>310. Is errno a macro?</h3></a><p> +<b>Section:</b> 17.4.1.2 <a href="lib-intro.html#lib.headers"> [lib.headers]</a>, 19.3 <a href="lib-diagnostics.html#lib.errno"> [lib.errno]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Steve Clamage <b>Date:</b> 21 Mar 2001</p> + <p> + Exactly how should errno be declared in a conforming C++ header? + </p> + + <p> + The C standard says in 7.1.4 that it is unspecified whether errno is a + macro or an identifier with external linkage. In some implementations + it can be either, depending on compile-time options. (E.g., on + Solaris in multi-threading mode, errno is a macro that expands to a + function call, but is an extern int otherwise. "Unspecified" allows + such variability.) + </p> + + <p>The C++ standard:</p> + <ul> + <li>17.4.1.2 says in a note that errno must be macro in C. (false)</li> + <li>17.4.3.1.3 footnote 166 says errno is reserved as an external + name (true), and implies that it is an identifier.</li> + <li>19.3 simply lists errno as a macro (by what reasoning?) and goes + on to say that the contents of of C++ <errno.h> are the + same as in C, begging the question.</li> + <li>C.2, table 95 lists errno as a macro, without comment.</li> + </ul> + + <p>I find no other references to errno.</p> + + <p>We should either explicitly say that errno must be a macro, even + though it need not be a macro in C, or else explicitly leave it + unspecified. We also need to say something about namespace std. + A user who includes <cerrno> needs to know whether to write + <tt>errno</tt>, or <tt>::errno</tt>, or <tt>std::errno</tt>, or + else <cerrno> is useless.</p> + + <p>Two acceptable fixes:</p> + <ul> + <li><p>errno must be a macro. This is trivially satisfied by adding<br> + #define errno (::std::errno)<br> + to the headers if errno is not already a macro. You then always + write errno without any scope qualification, and it always expands + to a correct reference. Since it is always a macro, you know to + avoid using errno as a local identifer.</p></li> + <li><p>errno is in the global namespace. This fix is inferior, because + ::errno is not guaranteed to be well-formed.</p></li> + </ul> + + <p><i>[ + This issue was first raised in 1999, but it slipped through + the cracks. + ]</i></p> +<p><b>Proposed resolution:</b></p> + <p>Change the Note in section 17.4.1.2p5 from</p> + + <blockquote> + Note: the names defined as macros in C include the following: + assert, errno, offsetof, setjmp, va_arg, va_end, and va_start. + </blockquote> + + <p>to</p> + + <blockquote> + Note: the names defined as macros in C include the following: + assert, offsetof, setjmp, va_arg, va_end, and va_start. + </blockquote> + + <p>In section 19.3, change paragraph 2 from</p> + + <blockquote> + The contents are the same as the Standard C library header + <errno.h>. + </blockquote> + + <p>to</p> + + <blockquote> + The contents are the same as the Standard C library header + <errno.h>, except that errno shall be defined as a macro. + </blockquote> +<p><b>Rationale:</b></p> +<p>C++ must not leave it up to the implementation to decide whether or +not a name is a macro; it must explicitly specify exactly which names +are required to be macros. The only one that really works is for it +to be a macro.</p> + +<p><i>[Curaçao: additional rationale added.]</i></p> + +<hr> +<a name="311"><h3>311. Incorrect wording in basic_ostream class synopsis</h3></a><p> +<b>Section:</b> 27.6.2.1 <a href="lib-iostreams.html#lib.ostream"> [lib.ostream]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Andy Sawyer <b>Date:</b> 21 Mar 2001</p> + +<p>In 27.6.2.1 <a href="lib-iostreams.html#lib.ostream"> [lib.ostream]</a>, the synopsis of class basic_ostream says:</p> + +<pre> + // partial specializationss + template<class traits> + basic_ostream<char,traits>& operator<<( basic_ostream<char,traits>&, + const char * ); +</pre> + +<p>Problems:</p> +<ul> +<li>Too many 's's at the end of "specializationss" </li> +<li>This is an overload, not a partial specialization</li> +</ul> + +<p><b>Proposed resolution:</b></p> +<p>In the synopsis in 27.6.2.1 <a href="lib-iostreams.html#lib.ostream"> [lib.ostream]</a>, remove the +<i>// partial specializationss</i> comment. Also remove the same +comment (correctly spelled, but still incorrect) from the synopsis in +27.6.2.5.4 <a href="lib-iostreams.html#lib.ostream.inserters.character"> [lib.ostream.inserters.character]</a>. +</p> + +<p><i>[ +Pre-Redmond: added 27.6.2.5.4 <a href="lib-iostreams.html#lib.ostream.inserters.character"> [lib.ostream.inserters.character]</a> because of Martin's +comment in c++std-lib-8939. +]</i></p> + +<hr> <a name="312"><h3>312. Table 27 is missing headers</h3></a><p> <b>Section:</b> 20 <a href="lib-utilities.html#lib.utilities"> [lib.utilities]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 29 Mar 2001</p> <p>Table 27 in section 20 lists the header <memory> (only) for @@ -6703,6 +7651,388 @@ Memory (lib.memory) but neglects to mention the headers <p><b>Proposed resolution:</b></p> <p>Add <cstdlib> and <cstring> to Table 27, in the same row as <memory>.</p> +<hr> +<a name="315"><h3>315. Bad "range" in list::unique complexity</h3></a><p> +<b>Section:</b> 23.2.2.4 <a href="lib-containers.html#lib.list.ops"> [lib.list.ops]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Andy Sawyer <b>Date:</b> 1 May 2001</p> +<p> +23.2.2.4 <a href="lib-containers.html#lib.list.ops"> [lib.list.ops]</a>, Para 21 describes the complexity of +list::unique as: "If the range (last - first) is not empty, exactly +(last - first) -1 applications of the corresponding predicate, +otherwise no applications of the predicate)". +</p> + +<p> +"(last - first)" is not a range. +</p> +<p><b>Proposed resolution:</b></p> +<p> +Change the "range" from (last - first) to [first, last). +</p> +<hr> +<a name="316"><h3>316. Vague text in Table 69</h3></a><p> +<b>Section:</b> 23.1.2 <a href="lib-containers.html#lib.associative.reqmts"> [lib.associative.reqmts]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 4 May 2001</p> +<p>Table 69 says this about a_uniq.insert(t):</p> + +<blockquote> +inserts t if and only if there is no element in the container with key +equivalent to the key of t. The bool component of the returned pair +indicates whether the insertion takes place and the iterator component of the +pair points to the element with key equivalent to the key of t. +</blockquote> + +<p>The description should be more specific about exactly how the bool component +indicates whether the insertion takes place.</p> +<p><b>Proposed resolution:</b></p> +<p>Change the text in question to</p> + +<blockquote> +...The bool component of the returned pair is true if and only if the insertion +takes place... +</blockquote> +<hr> +<a name="317"><h3>317. Instantiation vs. specialization of facets</h3></a><p> +<b>Section:</b> 22 <a href="lib-locales.html#lib.localization"> [lib.localization]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 4 May 2001</p> +<p> +The localization section of the standard refers to specializations of +the facet templates as instantiations even though the required facets +are typically specialized rather than explicitly (or implicitly) +instantiated. In the case of ctype<char> and +ctype_byname<char> (and the wchar_t versions), these facets are +actually required to be specialized. The terminology should be +corrected to make it clear that the standard doesn't mandate explicit +instantiation (the term specialization encompasses both explicit +instantiations and specializations). +</p> +<p><b>Proposed resolution:</b></p> +<p> +In the following paragraphs, replace all occurrences of the word +instantiation or instantiations with specialization or specializations, +respectively: +</p> + +<blockquote> +22.1.1.1.1, p4, Table 52, 22.2.1.1, p2, 22.2.1.5, p3, 22.2.1.5.1, p5, +22.2.1.5.2, p10, 22.2.2, p2, 22.2.3.1, p1, 22.2.3.1.2, p1, p2 and p3, +22.2.4.1, p1, 22.2.4.1.2, p1, 22,2,5, p1, 22,2,6, p2, 22.2.6.3.2, p7, and +Footnote 242. +</blockquote> + +<p>And change the text in 22.1.1.1.1, p4 from</p> + +<blockquote> + An implementation is required to provide those instantiations + for facet templates identified as members of a category, and + for those shown in Table 52: +</blockquote> + +<p>to</p> + +<blockquote> + An implementation is required to provide those specializations... +</blockquote> + +<p><i>[Nathan will review these changes, and will look for places where +explicit specialization is necessary.]</i></p> + +<p><b>Rationale:</b></p> +<p>This is a simple matter of outdated language. The language to +describe templates was clarified during the standardization process, +but the wording in clause 22 was never updated to reflect that +change.</p> +<hr> +<a name="318"><h3>318. Misleading comment in definition of numpunct_byname</h3></a><p> +<b>Section:</b> 22.2.3.2 <a href="lib-locales.html#lib.locale.numpunct.byname"> [lib.locale.numpunct.byname]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 12 May 2001</p> +<p>The definition of the numpunct_byname template contains the following +comment:</p> + +<pre> + namespace std { + template <class charT> + class numpunct_byname : public numpunct<charT> { + // this class is specialized for char and wchar_t. + ... +</pre> + +<p>There is no documentation of the specializations and it seems +conceivable that an implementation will not explicitly specialize the +template at all, but simply provide the primary template.</p> +<p><b>Proposed resolution:</b></p> +<p>Remove the comment from the text in 22.2.3.2 and from the proposed +resolution of library issue <a href="lwg-defects.html#228">228</a>.</p> +<hr> +<a name="319"><h3>319. Storage allocation wording confuses "Required behavior", "Requires"</h3></a><p> +<b>Section:</b> 18.4.1.1 <a href="lib-support.html#lib.new.delete.single"> [lib.new.delete.single]</a>, 18.4.1.2 <a href="lib-support.html#lib.new.delete.array"> [lib.new.delete.array]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Beman Dawes <b>Date:</b> 15 May 2001</p> +<p>The standard specifies 17.3.1.3 <a href="lib-intro.html#lib.structure.specifications"> [lib.structure.specifications]</a> that "Required +behavior" elements describe "the semantics of a function definition +provided by either the implementation or a C++ program."</p> + +<p>The standard specifies 17.3.1.3 <a href="lib-intro.html#lib.structure.specifications"> [lib.structure.specifications]</a> that "Requires" +elements describe "the preconditions for calling the function."</p> + +<p>In the sections noted below, the current wording specifies +"Required Behavior" for what are actually preconditions, and thus +should be specified as "Requires".</p> + +<p><b>Proposed resolution:</b></p> + +<p>In 18.4.1.1 <a href="lib-support.html#lib.new.delete.single"> [lib.new.delete.single]</a> Para 12 Change:</p> +<blockquote> + <p>Required behavior: accept a value of ptr that is null or that was + returned by an earlier call ...</p> +</blockquote> +<p>to:</p> +<blockquote> + <p>Requires: the value of ptr is null or the value returned by an + earlier call ...</p> +</blockquote> + +<p>In 18.4.1.2 <a href="lib-support.html#lib.new.delete.array"> [lib.new.delete.array]</a> Para 11 Change:</p> +<blockquote> + <p>Required behavior: accept a value of ptr that is null or that was + returned by an earlier call ...</p> +</blockquote> +<p>to:</p> +<blockquote> + <p>Requires: the value of ptr is null or the value returned by an + earlier call ...</p> +</blockquote> + +<hr> +<a name="321"><h3>321. Typo in num_get</h3></a><p> +<b>Section:</b> 22.2.2.1.2 <a href="lib-locales.html#lib.facet.num.get.virtuals"> [lib.facet.num.get.virtuals]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Kevin Djang <b>Date:</b> 17 May 2001</p> +<p> +Section 22.2.2.1.2 at p7 states that "A length specifier is added to +the conversion function, if needed, as indicated in Table 56." +However, Table 56 uses the term "length modifier", not "length +specifier". +</p> +<p><b>Proposed resolution:</b></p> +<p> +In 22.2.2.1.2 at p7, change the text "A length specifier is added ..." +to be "A length modifier is added ..." +</p> +<p><b>Rationale:</b></p> +<p>C uses the term "length modifier". We should be consistent.</p> +<hr> +<a name="322"><h3>322. iterator and const_iterator should have the same value type</h3></a><p> +<b>Section:</b> 23.1 <a href="lib-containers.html#lib.container.requirements"> [lib.container.requirements]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Matt Austern <b>Date:</b> 17 May 2001</p> +<p> +It's widely assumed that, if X is a container, +iterator_traits<X::iterator>::value_type and +iterator_traits<X::const_iterator>::value_type should both be +X::value_type. However, this is nowhere stated. The language in +Table 65 is not precise about the iterators' value types (it predates +iterator_traits), and could even be interpreted as saying that +iterator_traits<X::const_iterator>::value_type should be "const +X::value_type". +</p> + +<p>Related issue: <a href="lwg-closed.html#279">279</a>.</p> +<p><b>Proposed resolution:</b></p> +<p>In Table 65 ("Container Requirements"), change the return type for +X::iterator to "iterator type whose value type is T". Change the +return type for X::const_iterator to "constant iterator type whose +value type is T".</p> +<p><b>Rationale:</b></p> +<p> +This belongs as a container requirement, rather than an iterator +requirement, because the whole notion of iterator/const_iterator +pairs is specific to containers' iterator. +</p> +<p> +It is existing practice that (for example) +iterator_traits<list<int>::const_iterator>::value_type +is "int", rather than "const int". This is consistent with +the way that const pointers are handled: the standard already +requires that iterator_traits<const int*>::value_type is int. +</p> +<hr> +<a name="327"><h3>327. Typo in time_get facet in table 52</h3></a><p> +<b>Section:</b> 22.1.1.1.1 <a href="lib-locales.html#lib.locale.category"> [lib.locale.category]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Tiki Wan <b>Date:</b> 06 Jul 2001</p> +<p>The <tt>wchar_t</tt> versions of <tt>time_get</tt> and +<tt>time_get_byname</tt> are listed incorrectly in table 52, +required instantiations. In both cases the second template +parameter is given as OutputIterator. It should instead be +InputIterator, since these are input facets.</p> +<p><b>Proposed resolution:</b></p> +<p> +In table 52, required instantiations, in +22.1.1.1.1 <a href="lib-locales.html#lib.locale.category"> [lib.locale.category]</a>, change</p> +<pre> + time_get<wchar_t, OutputIterator> + time_get_byname<wchar_t, OutputIterator> +</pre> +<p>to</p> +<pre> + time_get<wchar_t, InputIterator> + time_get_byname<wchar_t, InputIterator> +</pre> + +<p><i>[Redmond: Very minor change in proposed resolution. Original had +a typo, wchart instead of wchar_t.]</i></p> + +<hr> +<a name="328"><h3>328. Bad sprintf format modifier in money_put<>::do_put()</h3></a><p> +<b>Section:</b> 22.2.6.2.2 <a href="lib-locales.html#lib.locale.money.put.virtuals"> [lib.locale.money.put.virtuals]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Martin Sebor <b>Date:</b> 07 Jul 2001</p> +<p>The sprintf format string , "%.01f" (that's the digit one), in the +description of the do_put() member functions of the money_put facet in +22.2.6.2.2, p1 is incorrect. First, the f format specifier is wrong +for values of type long double, and second, the precision of 01 +doesn't seem to make sense. What was most likely intended was +"%.0Lf"., that is a precision of zero followed by the L length +modifier.</p> +<p><b>Proposed resolution:</b></p> +<p>Change the format string to "%.0Lf".</p> +<p><b>Rationale:</b></p> +<p>Fixes an obvious typo</p> +<hr> +<a name="331"><h3>331. bad declaration of destructor for ios_base::failure</h3></a><p> +<b>Section:</b> 27.4.2.1.1 <a href="lib-iostreams.html#lib.ios::failure"> [lib.ios::failure]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> PremAnand M. Rao <b>Date:</b> 23 Aug 2001</p> +<p> +With the change in 17.4.4.8 <a href="lib-intro.html#lib.res.on.exception.handling"> [lib.res.on.exception.handling]</a> to state + "An implementation may strengthen the exception-specification for a + non-virtual function by removing listed exceptions." +(issue <a href="lwg-defects.html#119">119</a>) +and the following declaration of ~failure() in ios_base::failure +</p> +<pre> + namespace std { + class ios_base::failure : public exception { + public: + ... + virtual ~failure(); + ... + }; + } +</pre> +<p>the class failure cannot be implemented since in 18.6.1 <a href="lib-support.html#lib.exception"> [lib.exception]</a> the destructor of class exception has an empty +exception specification:</p> +<pre> + namespace std { + class exception { + public: + ... + virtual ~exception() throw(); + ... + }; + } +</pre> +<p><b>Proposed resolution:</b></p> +<p>Remove the declaration of ~failure().</p> +<p><b>Rationale:</b></p> +<p>The proposed resolution is consistent with the way that destructors +of other classes derived from <tt>exception</tt> are handled.</p> +<hr> +<a name="335"><h3>335. minor issue with char_traits, table 37</h3></a><p> +<b>Section:</b> 21.1.1 <a href="lib-strings.html#lib.char.traits.require"> [lib.char.traits.require]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Andy Sawyer <b>Date:</b> 06 Sep 2001</p> +<p> +Table 37, in 21.1.1 <a href="lib-strings.html#lib.char.traits.require"> [lib.char.traits.require]</a>, descibes char_traits::assign +as: +</p> +<pre> + X::assign(c,d) assigns c = d. +</pre> + +<p>And para 1 says:</p> + +<blockquote> + [...] c and d denote values of type CharT [...] +</blockquote> + +<p> +Naturally, if c and d are <i>values</i>, then the assignment is +(effectively) meaningless. It's clearly intended that (in the case of +assign, at least), 'c' is intended to be a reference type. +</p> + +<p>I did a quick survey of the four implementations I happened to have +lying around, and sure enough they all have signatures:</p> +<pre> + assign( charT&, const charT& ); +</pre> + +<p>(or the equivalent). It's also described this way in Nico's book. +(Not to mention the synopses of char_traits<char> in 21.1.3.1 +and char_traits<wchar_t> in 21.1.3.2...) +</p> +<p><b>Proposed resolution:</b></p> +<p>Add the following to 21.1.1 para 1:</p> +<blockquote> + r denotes an lvalue of CharT +</blockquote> + +<p>and change the description of assign in the table to:</p> +<pre> + X::assign(r,d) assigns r = d +</pre> +<hr> +<a name="337"><h3>337. replace_copy_if's template parameter should be InputIterator</h3></a><p> +<b>Section:</b> 25.2.4 <a href="lib-algorithms.html#lib.alg.replace"> [lib.alg.replace]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Detlef Vollmann <b>Date:</b> 07 Sep 2001</p> +<p>From c++std-edit-876:</p> + +<p> +In section 25.2.4 <a href="lib-algorithms.html#lib.alg.replace"> [lib.alg.replace]</a> before p4: The name of the first +parameter of template replace_copy_if should be "InputIterator" +instead of "Iterator". According to 17.3.2.1 <a href="lib-intro.html#lib.type.descriptions"> [lib.type.descriptions]</a> p1 the +parameter name conveys real normative meaning. +</p> +<p><b>Proposed resolution:</b></p> +<p>Change <tt>Iterator</tt> to <tt>InputIterator</tt>.</p> +<hr> +<a name="345"><h3>345. type tm in <cwchar></h3></a><p> +<b>Section:</b> 21.4 <a href="lib-strings.html#lib.c.strings"> [lib.c.strings]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Clark Nelson <b>Date:</b> 19 Oct 2001</p> +<p> +C99, and presumably amendment 1 to C90, specify that <wchar.h> +declares struct tm as an incomplete type. However, table 48 in 21.4 <a href="lib-strings.html#lib.c.strings"> [lib.c.strings]</a> does not mention the type tm as being declared in +<cwchar>. Is this omission intentional or accidental? +</p> +<p><b>Proposed resolution:</b></p> +<p>In section 21.4 <a href="lib-strings.html#lib.c.strings"> [lib.c.strings]</a>, add "tm" to table 48.</p> +<hr> +<a name="346"><h3>346. Some iterator member functions should be const</h3></a><p> +<b>Section:</b> 24.1 <a href="lib-iterators.html#lib.iterator.requirements"> [lib.iterator.requirements]</a> <b>Status:</b> <a href="lwg-active.html#DR">DR</a> <b>Submitter:</b> Jeremy Siek <b>Date:</b> 20 Oct 2001</p> +<p>Iterator member functions and operators that do not change the state +of the iterator should be defined as const member functions or as +functions that take iterators either by const reference or by +value. The standard does not explicitly state which functions should +be const. Since this a fairly common mistake, the following changes +are suggested to make this explicit.</p> + +<p>The tables almost indicate constness properly through naming: r +for non-const and a,b for const iterators. The following changes +make this more explicit and also fix a couple problems.</p> +<p><b>Proposed resolution:</b></p> +<p>In 24.1 <a href="lib-iterators.html#lib.iterator.requirements"> [lib.iterator.requirements]</a> Change the first section of p9 from +"In the following sections, a and b denote values of X..." to +"In the following sections, a and b denote values of type const X...".</p> + +<p>In Table 73, change</p> +<pre> + a->m U& ... +</pre> + +<p>to</p> + +<pre> + a->m const U& ... + r->m U& ... +</pre> + +<p>In Table 73 expression column, change</p> + +<pre> + *a = t +</pre> + +<p>to</p> + +<pre> + *r = t +</pre> + +<p><i>[Redmond: The container requirements should be reviewed to see if +the same problem appears there.]</i></p> + <p>----- End of document -----</p> </body> </html> diff --git a/libstdc++-v3/docs/html/ext/sgiexts.html b/libstdc++-v3/docs/html/ext/sgiexts.html index 674ffacc766..9bb04622038 100644 --- a/libstdc++-v3/docs/html/ext/sgiexts.html +++ b/libstdc++-v3/docs/html/ext/sgiexts.html @@ -1,12 +1,11 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> <html> <head> - <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> - <meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++, STL, SGI"> - <meta name="DESCRIPTION" content="SGI extensions preserved in libstdc++-v3."> - <meta name="GENERATOR" content="vi and eight fingers"> + <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> + <meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++, STL, SGI" /> + <meta name="DESCRIPTION" content="SGI extensions preserved in libstdc++-v3." /> + <meta name="GENERATOR" content="vi and eight fingers" /> <title>SGI extensions to the library in libstdc++-v3</title> -<link rel="StyleSheet" href="lib3styles.css"> +<link rel="StyleSheet" href="lib3styles.css" /> </head> <body> @@ -25,7 +24,7 @@ libstdc++-v3</a></h1> for a description). Not every chapter may have extensions, and the extensions may come and go. Also, this page is incomplete because the author is pressed for time. Check back often; the latest change was on - $Date: 2001/11/23 16:29:01 $ (UTC). + $Date: 2002/09/05 15:47:53 $ (UTC). </p> <p>Descriptions range from the scanty to the verbose. You should also check @@ -36,30 +35,33 @@ libstdc++-v3</a></h1> </p> <p>Back to the <a href="howto.html">libstdc++-v3 extensions</a>. +</p> <!-- ####################################################### --> -<hr> -<a name="ch20"><h3>Chapter 20</h3></a> +<hr /> +<h3><a name="ch20">Chapter 20</a></h3> <p>The <functional> header contains many additional functors and helper functions, extending section 20.3. They are implemented in the file stl_function.h: - <ul> - <li><code>identity_element</code> for addition and multiplication. * - <li>The functor <code>identity</code>, whose op() returns the argument - unchanged. * +</p> +<ul> + <li><code>identity_element</code> for addition and multiplication. * </li> + <li>The functor <code>identity</code>, whose <code>operator()</code> + returns the argument unchanged. * </li> <li>Composition functors <code>unary_function</code> and <code>binary_function</code>, and their helpers <code>compose1</code> - and <code>compose2</code>. * - <li><code>select1st</code> and <code>select2nd</code>, to strip pairs. * - <li><code>project1st</code> and <code>project2nd</code>. * + and <code>compose2</code>. * </li> + <li><code>select1st</code> and <code>select2nd</code>, to strip pairs. * </li> + <li><code>project1st</code> and <code>project2nd</code>. * </li> <li>A set of functors/functions which always return the same result. They - are <code>constant_void_fun, constant_binary_fun, constant_unary_fun, - constant0, constant1, and constant2. * - <li>The class <code>subtractive_rng</code>. * - <li>mem_fun adaptor helpers mem_fun1 and mem_fun1_ref are provided for - backwards compatibility. -</ul></p> + are <code>constant_void_fun</code>, <code>constant_binary_fun</code>, + <code>constant_unary_fun</code>, <code>constant0</code>, + <code>constant1</code>, and <code>constant2</code>. * </li> + <li>The class <code>subtractive_rng</code>. * </li> + <li>mem_fun adaptor helpers <code>mem_fun1</code> and + <code>mem_fun1_ref</code> are provided for backwards compatibility. </li> +</ul> <p>20.4.1 can use several different allocators; they are described on the main extensions page. </p> @@ -68,12 +70,12 @@ libstdc++-v3</a></h1> is a pointer, which is ignored, but can be used to specify the template type (instead of using explicit function template arguments like the standard version does). That is, in addition to +</p> <pre> get_temporary_buffer<int>(5);</pre> you can also use <pre> get_temporary_buffer(5, (int*)0);</pre> -</p> <p>A class <code>temporary_buffer</code> is given in stl_tempbuf.h. * </p> <p>The specialized algorithms of section 20.4.4 are extended with @@ -84,8 +86,8 @@ libstdc++-v3</a></h1> </p> -<hr> -<a name="ch23"><h3>Chapter 23</h3></a> +<hr /> +<h3><a name="ch23">Chapter 23</a></h3> <p>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: @@ -105,18 +107,18 @@ libstdc++-v3</a></h1> versions of single-bit test, set, reset, and flip member functions which do no range-checking. If we call them member functions of an instantiation of "bitset<N>," then their names and signatures are: +</p> <pre> bitset<N>& _Unchecked_set (size_t pos); bitset<N>& _Unchecked_set (size_t pos, int val); bitset<N>& _Unchecked_reset (size_t pos); bitset<N>& _Unchecked_flip (size_t pos); bool _Unchecked_test (size_t pos);</pre> - Note that these may in fact be removed in the future, although we have +<p>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). </p> -<p> - The semantics of member function <code>operator[]</code> are not specified +<p>The semantics of member function <code>operator[]</code> are not specified in the C++ standard. A long-standing defect report calls for sensible obvious semantics, which are already implemented here: <code>op[]</code> on a const bitset returns a bool, and for a non-const bitset returns a @@ -128,30 +130,31 @@ libstdc++-v3</a></h1> <p>Finally, two additional searching functions have been added. They return the index of the first "on" bit, and the index of the first "on" bit that is after <code>prev</code>, respectively: +</p> <pre> size_t _Find_first() const; size_t _Find_next (size_t prev) const;</pre> - The same caveat given for the _Unchecked_* functions applies here also. +<p>The same caveat given for the _Unchecked_* functions applies here also. </p> <p>Return <a href="howto.html">to the main extensions page</a> or <a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>. </p> -<hr> -<a name="ch24"><h3>Chapter 24</h3></a> +<hr /> +<h3><a name="ch24">Chapter 24</a></h3> <p>24.3.2 describes <code>struct iterator</code>, 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: +</p> <ul> - <li>input_iterator - <li>output_iterator - <li>forward_iterator - <li>bidirectional_iterator - <li>random_access_iterator + <li>input_iterator</li> + <li>output_iterator</li> + <li>forward_iterator</li> + <li>bidirectional_iterator</li> + <li>random_access_iterator</li> </ul> -</p> <p>24.3.4 describes iterator operation <code>distance</code>, which takes 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 @@ -162,50 +165,53 @@ libstdc++-v3</a></h1> </p> -<hr> -<a name="ch25"><h3>Chapter 25</h3></a> +<hr /> +<h3><a name="ch25">Chapter 25</a></h3> <p>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., +</p> <pre> void count (first, last, value, n);</pre> -</p> <p>25.2 (mutating algorithms) is extended with two families of signatures, random_sample and random_sample_n. </p> <p>25.2.1 (copy) is extended with +</p> <pre> copy_n (_InputIter first, _Size count, _OutputIter result);</pre> - which copies the first 'count' elements at 'first' into 'result'. +<p>which copies the first 'count' elements at 'first' into 'result'. </p> <p>25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper predicates. Look in the doxygen-generated pages for notes on these. +</p> <ul> - <li><code>is_heap</code> tests whether or not a range is a heap. + <li><code>is_heap</code> tests whether or not a range is a heap.</li> <li><code>is_sorted</code> tests whether or not a range is sorted in - nondescending order. + nondescending order.</li> </ul> -</p> <p>25.3.8 (lexigraphical_compare) is extended with +</p> <pre> lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1, _InputIter2 first2, _InputIter2 last2)</pre> - which does... what? +<p>which does... what? </p> <p>Return <a href="howto.html">to the main extensions page</a> or <a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>. </p> -<hr> -<a name="ch26"><h3>Chapter 26</h3></a> +<hr /> +<h3><a name="ch26">Chapter 26</a></h3> <p>26.4, the generalized numeric operations such as accumulate, are extended with the following functions: +</p> <pre> power (x, n); power (x, n, moniod_operation);</pre> - Returns, in FORTRAN syntax, "x ** n" where n>=0. In the +<p>Returns, in FORTRAN syntax, "x ** n" where n>=0. In the case of n == 0, returns the <a href="#ch20">identity element</a> for the monoid operation. The two-argument signature uses multiplication (for a true "power" implementation), but addition is supported as well. @@ -215,9 +221,9 @@ libstdc++-v3</a></h1> Coolest Name. It "assigns sequentially increasing values to a range. That is, it assigns value to *first, value + 1 to *(first + 1) and so on." Quoted from SGI documentation. +</p> <pre> void iota(_ForwardIter first, _ForwardIter last, _Tp value);</pre> -</p> <p>Return <a href="howto.html">to the main extensions page</a> or <a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>. </p> @@ -225,7 +231,7 @@ libstdc++-v3</a></h1> <!-- ####################################################### --> -<hr> +<hr /> <p class="fineprint"><em> See <a href="../17_intro/license.html">license.html</a> for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/faq/index.html b/libstdc++-v3/docs/html/faq/index.html index 7030e476d92..6d42ebc7ecf 100644 --- a/libstdc++-v3/docs/html/faq/index.html +++ b/libstdc++-v3/docs/html/faq/index.html @@ -1,10 +1,10 @@ <html> <head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++, libg++, STL"> - <meta name="DESCRIPTION" content="FAQ for the GNU libstdc++ effort."> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> + <meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++, libg++, STL" /> + <meta name="DESCRIPTION" content="FAQ for the GNU libstdc++ effort." /> <title>libstdc++-v3 FAQ</title> -<link rel="StyleSheet" href="../lib3styles.css"> +<link rel="StyleSheet" href="../lib3styles.css" /> <!-- ** Locations of "the most recent snapshot is the Nth" text are ** answers 1_1, 1_4, 4_1. @@ -23,80 +23,92 @@ </p> <p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>. +</p> <!-- ####################################################### --> -<hr> +<hr /> <h1>Questions</h1> <ol> <li><a href="#1_0">General Information</a> <!-- I suspect these will mostly be links to/into existing documents. --> <ol> - <li><a href="#1_1">What is libstdc++-v3?</a> - <li><a href="#1_2">Why should I use libstdc++?</a> - <li><a href="#1_3">Who's in charge of it?</a> - <li><a href="#1_4">How do I get libstdc++?</a> - <li><a href="#1_5">When is libstdc++ going to be finished?</a> - <li><a href="#1_6">How do I contribute to the effort?</a> - <li><a href="#1_7">What happened to libg++? I need that!</a> - <li><a href="#1_8">What if I have more questions?</a> - <li><a href="#1_9">What are the license terms for libstdc++-v3?</a> + <li><a href="#1_1">What is libstdc++-v3?</a> </li> + <li><a href="#1_2">Why should I use libstdc++?</a> </li> + <li><a href="#1_3">Who's in charge of it?</a> </li> + <li><a href="#1_4">How do I get libstdc++?</a> </li> + <li><a href="#1_5">When is libstdc++ going to be finished?</a> </li> + <li><a href="#1_6">How do I contribute to the effort?</a> </li> + <li><a href="#1_7">What happened to libg++? I need that!</a> </li> + <li><a href="#1_8">What if I have more questions?</a> </li> + <li><a href="#1_9">What are the license terms for libstdc++-v3?</a> </li> </ol> + </li> <li><a href="#2_0">Installation</a> <ol> - <li><a href="#2_1">How do I install libstdc++-v3?</a> - <li><a href="#2_2">[removed]</a> + <li><a href="#2_1">How do I install libstdc++-v3?</a> </li> + <li><a href="#2_2">[removed]</a> </li> <li><a href="#2_3">What is this CVS thing that you keep - mentioning?</a> - <li><a href="#2_4">How do I know if it works?</a> - <li><a href="#2_5">This library is HUGE! And what's libsupc++?</a> + mentioning?</a> </li> + <li><a href="#2_4">How do I know if it works?</a> </li> + <li><a href="#2_5">This library is HUGE! And what's libsupc++?</a> </li> </ol> + </li> <li><a href="#3_0">Platform-Specific Issues</a> <ol> <li><a href="#3_1">Can libstdc++-v3 be used with <my - favorite compiler>?</a> - <li><a href="#3_2">[removed]</a> - <li><a href="#3_3">[removed]</a> - <li><a href="#3_4">I can't use 'long long' on Solaris</a> + favorite compiler>?</a> </li> + <li><a href="#3_2">[removed]</a> </li> + <li><a href="#3_3">[removed]</a> </li> + <li><a href="#3_4">I can't use 'long long' on Solaris</a> </li> + <li><a href="#3_5"><code>_XOPEN_SOURCE</code> / + <code>_GNU_SOURCE</code> / etc is always defined</a> + </li> + <li><a href="#3_6">OS X ctype.h is broken! How can I hack it?</a> </li> </ol> + </li> <li><a href="#4_0">Known Bugs and Non-Bugs</a> <ol> - <li><a href="#4_1">What works already?</a> - <li><a href="#4_2">Bugs in gcc/g++ (not libstdc++-v3)</a> - <li><a href="#4_3">Bugs in the C++ language/lib specification</a> - <li><a href="#4_4">Things in libstdc++ that look like bugs</a> - <ul> - <li><a href="#4_4_iostreamclear">reopening a stream fails</a> - <li><a href="#4_4_Weff">-Weffc++ complains too much</a> - <li><a href="#4_4_rel_ops">"ambiguous overloads" - after including an old-style header</a> - <li><a href="#4_4_interface">The g++-3 headers are - <strong>not ours</strong></a> - <li><a href="#4_4_glibc">compilation errors from streambuf.h</a> - <li><a href="#4_4_checks">errors about <em>*Cconcept</em> and - <em>constraints</em> in the STL...</a> - </ul> - <li><a href="#4_5">Aw, that's easy to fix!</a> + <li><a href="#4_1">What works already?</a> </li> + <li><a href="#4_2">Bugs in gcc/g++ (not libstdc++-v3)</a> </li> + <li><a href="#4_3">Bugs in the C++ language/lib specification</a> </li> + <li><a href="#4_4">Things in libstdc++ that only look like bugs</a><ul> + <li><a href="#4_4_iostreamclear">reopening a stream fails</a> </li> + <li><a href="#4_4_Weff">-Weffc++ complains too much</a> </li> + <li><a href="#4_4_rel_ops">"ambiguous overloads" + after including an old-style header</a> </li> + <li><a href="#4_4_interface">The g++-3 headers are + <strong>not ours</strong></a> </li> + <li><a href="#4_4_glibc">compilation errors from streambuf.h</a> </li> + <li><a href="#4_4_checks">errors about <em>*Concept</em> and + <em>constraints</em> in the STL...</a> </li> + <li><a href="#4_4_dlsym">program crashes when using library code + in a dynamically-loaded library</a> </li> + </ul> + </li> + <li><a href="#4_5">Aw, that's easy to fix!</a> </li> </ol> + </li> <li><a href="#5_0">Miscellaneous</a> <ol> <li><a href="#5_1">string::iterator is not char*; - vector<T>::iterator is not T*</a> - <li><a href="#5_2">What's next after libstdc++-v3?</a> - <li><a href="#5_3">What about the STL from SGI?</a> - <li><a href="#5_4">Extensions and Backward Compatibility</a> - <li><a href="#5_5">[removed]</a> - <li><a href="#5_6">Is libstdc++-v3 thread-safe?</a> - <li><a href="#5_7">How do I get a copy of the ISO C++ Standard?</a> - <li><a href="#5_8">What's an ABI and why is it so messy?</a> + vector<T>::iterator is not T*</a> </li> + <li><a href="#5_2">What's next after libstdc++-v3?</a> </li> + <li><a href="#5_3">What about the STL from SGI?</a> </li> + <li><a href="#5_4">Extensions and Backward Compatibility</a> </li> + <li><a href="#5_5">[removed]</a> </li> + <li><a href="#5_6">Is libstdc++-v3 thread-safe?</a> </li> + <li><a href="#5_7">How do I get a copy of the ISO C++ Standard?</a> </li> + <li><a href="#5_8">What's an ABI and why is it so messy?</a> </li> </ol> + </li> </ol> -<hr> +<hr /> <!-- ####################################################### --> @@ -108,8 +120,8 @@ as described in chapters 17 through 27 and annex D. As the library reaches stable plateaus, it is captured in a snapshot and released. The current release is - <a href="http://gcc.gnu.org/libstdc++/download.html">the - thirteenth snapshot</a>. For those who want to see exactly how + <a href="http://gcc.gnu.org/libstdc++/index.html#download">the + fourteenth snapshot</a>. For those who want to see exactly how far the project has come, or just want the latest bleeding-edge code, the up-to-date source is available over anonymous CVS, and can even be browsed over the Web (see below). @@ -123,7 +135,7 @@ official <a href="../17_intro/DESIGN">design document</a>. </p> -<hr> +<hr /> <h2><a name="1_2">1.2 Why should I use libstdc++?</a></h2> <p>The completion of the ISO C++ standardization gave the C++ community a powerful set of reuseable tools in the form @@ -138,7 +150,7 @@ has recently been taken over by the <a href="http://gcc.gnu.org/">GCC team</a>. All of the rapid development and near-legendary - <a href="http://gcc.gnu.org/gcc-2.95/buildstat.html">portability</a> + <a href="http://gcc.gnu.org/gcc-3.0/buildstat.html">portability</a> that are the hallmarks of an open-source project are being applied to libstdc++. </p> @@ -149,12 +161,13 @@ nor be worried about platform-specific incompatibilities. </p> -<hr> +<hr /> <h2><a name="1_3">1.3 Who's in charge of it?</a></h2> <p>The libstdc++ project is contributed to by several developers all over the world, in the same way as GCC or Linux. - Benjamin Kosnik, Gabriel Dos Reis, Phil Edwards, and Ulrich - Drepper are the lead maintainers of the CVS archive. + Benjamin Kosnik, Gabriel Dos Reis, Phil Edwards, Ulrich Drepper, + Loren James Rittle, and Paolo Carlini are the lead maintainers of + the CVS archive. </p> <p>Development and discussion is held on the libstdc++ mailing list. Subscribing to the list, or searching the list @@ -163,11 +176,11 @@ If you have questions, ideas, code, or are just curious, sign up! </p> -<hr> +<hr /> <h2><a name="1_4">1.4 How do I get libstdc++?</a></h2> - <p>The thirteenth (and latest) snapshot of libstdc++-v3 is - <a href="http://gcc.gnu.org/libstdc++/download.html">available via - ftp</a>. + <p>The fourteenth (and latest) snapshot of libstdc++-v3 is + <a href="http://gcc.gnu.org/libstdc++/index.html#download">available + via ftp</a>. </p> <p>The <a href="http://gcc.gnu.org/libstdc++/">homepage</a> has instructions for retrieving the latest CVS sources, and for @@ -178,9 +191,9 @@ of the SGI STL. </p> -<hr> +<hr /> <h2><a name="1_5">1.5 When is libstdc++ going to be finished?</a></h2> -<!-- <p>Nathan Myers gave the best of all possible answers in <A +<!-- <p>Nathan Myers gave the best of all possible answers in <a href="http://www.deja.com/getdoc.xp?AN=469581698&fmt=text">a Usenet article</a>.</p> which is no longer available, thanks deja...--> @@ -188,7 +201,7 @@ which is no longer available, thanks deja...--> Usenet article asking this question: <em>Sooner, if you help.</em> </p> -<hr> +<hr /> <h2><a name="1_6">1.6 How do I contribute to the effort?</a></h2> <p>Here is <a href="../17_intro/contribute.html">a page devoted to this topic</a>. Subscribing to the mailing @@ -200,7 +213,7 @@ which is no longer available, thanks deja...--> we all thought was working, is more than welcome! </p> -<hr> +<hr /> <h2><a name="1_7">1.7 What happened to libg++? I need that!</a></h2> <p>The most recent libg++ README states that libg++ is no longer being actively maintained. It should not be used for new @@ -239,7 +252,7 @@ which is no longer available, thanks deja...--> describes where to find the last libg++ source. </p> -<hr> +<hr /> <h2><a name="1_8">1.8 What if I have more questions?</a></h2> <p>If you have read the README and RELEASE-NOTES files, and your question remains unanswered, then just ask the mailing list. @@ -255,13 +268,13 @@ which is no longer available, thanks deja...--> or <a href="mailto:gdr@gcc.gnu.org">Gabriel Dos Reis</a>. </p> -<hr> +<hr /> <h2><a name="1_9">1.9 What are the license terms for libstdc++-v3?</a></h2> <p>See <a href="../17_intro/license.html">our license description</a> for these and related questions. </p> -<hr> +<hr /> <h1><a name="2_0">2.0 Installation</a></h1> <h2><a name="2_1">2.1 How do I install libstdc++-v3?</a></h2> <p>Complete instructions are not given here (this is a FAQ, not @@ -272,9 +285,12 @@ which is no longer available, thanks deja...--> easier and more automated than building the GCC 2.[78] series was. If you are using GCC 2.95, you can still build earlier snapshots of libstdc++. + </li> <li> GNU Make is recommended, but should not be required. + </li> <li> The GNU Autotools are needed if you are messing with the configury or makefiles. + </li> </ul> <p>The file <a href="../documentation.html">documentation.html</a> provides a good overview of the steps necessary to build, install, @@ -290,18 +306,18 @@ which is no longer available, thanks deja...--> ".../docs/17_intro/" directory of the distribution. </p> -<hr> +<hr /> <h2><a name="2_2">2.2 [removed]</a></h2> <p>This question has become moot and has been removed. The stub is here to preserve numbering (and hence links/bookmarks). </p> -<hr> +<hr /> <h2><a name="2_3">2.3 What is this CVS thing that you keep mentioning?</a></h2> <p>The <em>Concurrent Versions System</em> is one of several revision control packages. It was selected for GNU projects because it's - free (speech), free (beer), and very high quality. The <A + free (speech), free (beer), and very high quality. The <a href="http://www.gnu.org/software/cvs/cvs.html">CVS entry in the GNU software catalogue</a> has a better description as well as a @@ -316,7 +332,7 @@ which is no longer available, thanks deja...--> <!-- wonder how long that'll live --> </p> -<hr> +<hr /> <h2><a name="2_4">2.4 How do I know if it works?</a></h2> <p>libstdc++-v3 comes with its own testsuite. You do not need to actually install the library ("<code>make @@ -332,7 +348,7 @@ which is no longer available, thanks deja...--> <strong>please</strong> write up your idea and send it to the list! </p> -<hr> +<hr /> <h2><a name="2_5">2.4 This library is HUGE! And what's libsupc++?</a></h2> <p>Usually the size of libraries on disk isn't noticeable. When a link editor (or simply "linker") pulls things from a @@ -382,7 +398,7 @@ which is no longer available, thanks deja...--> when building the library. </p> -<hr> +<hr /> <h1><a name="3_0">3.0 Platform-Specific Issues</a></h1> <h2><a name="3_1">3.1 Can libstdc++-v3 be used with <my favorite compiler>?</a></h2> @@ -404,19 +420,19 @@ which is no longer available, thanks deja...--> GCC/g++, however. </p> -<hr> +<hr /> <h2><a name="3_2">3.2 [removed]</a></h2> <p>This question has become moot and has been removed. The stub is here to preserve numbering (and hence links/bookmarks). </p> -<hr> +<hr /> <h2><a name="3_3">3.3 [removed]</a></h2> <p>This question has become moot and has been removed. The stub is here to preserve numbering (and hence links/bookmarks). </p> -<hr> +<hr /> <h2><a name="3_4">3.4 I can't use 'long long' on Solaris</a></h2> <p>By default we try to support the C99 <code>long long</code> type. This requires that certain functions from your C library be present. @@ -428,7 +444,53 @@ which is no longer available, thanks deja...--> <p>This has been fixed for 3.0.3 and onwards. </p> -<hr> +<hr /> + <h2><a name="3_5">3.5 <code>_XOPEN_SOURCE</code> / <code>_GNU_SOURCE</code> + / etc is always defined</a></h2> + <p>On Solaris, g++ (but not gcc) always defines the preprocessor + macro <code>_XOPEN_SOURCE</code>. On GNU/Linux, the same happens + with <code>_GNU_SOURCE</code>. (This is not an exhaustive list; + other macros and other platforms are also affected.) + </p> + <p>These macros are typically used in C library headers, guarding new + versions of functions from their older versions. The C++ standard + library includes the C standard library, but it requires the C90 + version, which for backwards-compatability reasons is often not the + default for many vendors. + </p> + <p>More to the point, the C++ standard requires behavior which is only + available on certain platforms after certain symbols are defined. + Usually the issue involves I/O-related typedefs. In order to + ensure correctness, the compiler simply predefines those symbols. + </p> + <p>Note that it's not enough to #define them only when the library is + being built (during installation). Since we don't have an 'export' + keyword, much of the library exists as headers, which means that + the symbols must also be defined as your programs are parsed and + compiled. + </p> + <p>To see which symbols are defined, look for CPLUSPLUS_CPP_SPEC in + the gcc config headers for your target (and try changing them to + see what happens when building complicated code). You can also run + <code>"g++ -E -dM - < /dev/null"</code> to display + a list of predefined macros for any particular installation. + </p> + <p>This has been discussed on the mailing lists + <a href="http://gcc.gnu.org/cgi-bin/htsearch?method=and&format=builtin-long&sort=score&words=_XOPEN_SOURCE+Solaris">quite a bit</a>. + </p> + <p>This method is something of a wart. We'd like to find a cleaner + solution, but nobody yet has contributed the time. + </p> + +<hr /> + <h2><a name="3_6">3.6 OS X ctype.h is broken! How can I hack it?</a></h2> + <p>This is a long-standing bug in the OS X support. Fortunately, + the patch is quite simple, and well-known. + <a href="http://gcc.gnu.org/ml/gcc/2002-03/msg00817.html"> Here's a + link to the solution.</a> + </p> + +<hr /> <h1><a name="4_0">4.0 Known Bugs and Non-Bugs</a></h1> <em>Note that this section can get rapdily outdated -- such is the nature of an open-source project. For the latest information, join @@ -437,9 +499,7 @@ which is no longer available, thanks deja...--> <p>For 3.0.1, the most common "bug" is an apparently missing "<code>../</code>" in include/Makefile, resulting in files - like gthr.h and gthr-single.h not being found. - </p> - <p>Please read + like gthr.h and gthr-single.h not being found. Please read <a href="http://gcc.gnu.org/install/configure.html">the configuration instructions for GCC</a>, specifically the part about configuring in a separate build directory, @@ -447,6 +507,18 @@ which is no longer available, thanks deja...--> is fragile, is rarely tested, and tends to break, as in this case. This was fixed for 3.0.2. </p> + + <p>For 3.1, the most common "bug" is a parse error when using + <code><fstream></code>, ending with a message, + "<code>bits/basic_file.h:52: parse error before `{' + token</code>." Please read + <a href="http://gcc.gnu.org/install/">the installation instructions for + GCC</a>, specifically the part about not installing newer versions on + top of older versions. If you install 3.1 over a 3.0.x release, then + the wrong basic_file.h header will be found (its location changed + between releases). + </p> + <p><strong>Please do not report these as bugs. We know about them.</strong> Reporting this -- or any other problem that's already been fixed -- hinders the development of GCC, because we have to take time to @@ -462,8 +534,22 @@ which is no longer available, thanks deja...--> <!-- Yeah, I meant that "verbatim clip" thing literally... :-) --> <pre> -New in 3.0.96: +New: --- +(post 3.0.97) +- more doxygen documentation +- more named locale fixups +- stdio_filebuf that takes fd, FILE +- io performance tuning +- allocation tuning, valgrind fixups +- __cxa_demangle now supported +(3.0.97) +- more doxygen documentation. +- more named locale bug fixes +- support for symbol versioning when using GNU ld >= 2.12 +- wide-io +- tuning for executable size +(3.0.96) - more doxygen documentation. - extensions moved out of namespace std - HPUX long long support @@ -473,9 +559,7 @@ New in 3.0.96: - header simplification - named locale bug shakeout - thread testsuite - -New in 3.0.95: ---- +(3.0.95) - add S390, m68k, x86-64 support. - doxygen documentation has been extended, including man pages. - verbose terminate handling has been added. @@ -494,11 +578,11 @@ New in 3.0.95: - update -fno-exceptions code, verify it works. - full named locale support fpr all facets, choice of gnu, ieee_1003.1-200x (POSIX 2), or generic models. Full support depends - on target OS and underlying "C" library support. + on target OS and underlying "C" library support. </pre> -<hr> +<hr /> <h2><a name="4_2">4.2 Bugs in gcc/g++ (not libstdc++-v3)</a></h2> <p>This is by no means meant to be complete nor exhaustive, but mentions some problems that users may encounter when building @@ -523,7 +607,7 @@ New in 3.0.95: experiences. :-)</li> </ul> -<hr> +<hr /> <h2><a name="4_3">4.3 Bugs in the C++ language/lib specification</a></h2> <p>Yes, unfortunately, there are some. In a <a href="http://gcc.gnu.org/ml/libstdc++/1998/msg00006.html">message @@ -542,28 +626,26 @@ New in 3.0.95: Some of these have resulted in <a href="#5_2">code changes</a>. </p> -<hr> - <h2><a name="4_4">4.4 Things in libstdc++ that look like bugs</a></h2> +<hr /> + <h2><a name="4_4">4.4 Things in libstdc++ that only look like bugs</a></h2> <p>There are things which are not bugs in the compiler (4.2) nor the language specification (4.3), but aren't really bugs in libstdc++, either. Really! Please do not report these as bugs. </p> - <a name="4_4_Weff"> - <p><strong>-Weffc++</strong> - The biggest of these is the quadzillions of warnings about the - library headers emitted when <code>-Weffc++</code> is used. Making - libstdc++ "-Weffc++-clean" is not a goal of the project, - for a few reasons. Mainly, that option tries to enforce - object-oriented programming, while the Standard Library isn't - necessarily trying to be OO. - </p> - </a> - <a name="4_4_iostreamclear"> - <p><strong>reopening a stream fails</strong> - Did I just say that -Weffc++ was our biggest false-bug report? I - lied. (It used to be.) Today it seems to be reports that after - executing a sequence like - <pre> + <p><a name="4_4_Weff"><strong>-Weffc++</strong></a> + The biggest of these is the quadzillions of warnings about the + library headers emitted when <code>-Weffc++</code> is used. Making + libstdc++ "-Weffc++-clean" is not a goal of the project, + for a few reasons. Mainly, that option tries to enforce + object-oriented programming, while the Standard Library isn't + necessarily trying to be OO. + </p> + <p><a name="4_4_iostreamclear"><strong>reopening a stream fails</strong> + </a> Did I just say that -Weffc++ was our biggest false-bug report? + I lied. (It used to be.) Today it seems to be reports that after + executing a sequence like + </p> + <pre> #include <fstream> ... std::fstream fs("a_file"); @@ -572,58 +654,54 @@ New in 3.0.95: // . fs.close(); fs.open("a_new_file");</pre> - all operations on the re-opened <code>fs</code> will fail, or at - least act very strangely. Yes, they often will, especially if - <code>fs</code> reached the EOF state on the previous file. The - reason is that the state flags are <strong>not</strong> cleared - on a successful call to open(). The standard unfortunately did - not specify behavior in this case, and to everybody's great sorrow, - the <a href="../ext/howto.html#5">proposed LWG resolution</a> (see - DR #22) is to leave the flags unchanged. You must insert a call - to <code>fs.clear()</code> between the calls to close() and open(), - and then everything will work like we all expect it to work. - </p> - </a> - <a name="4_4_rel_ops"> - <p><strong>rel_ops</strong> - Another is the <code>rel_ops</code> namespace and the template - comparison operator functions contained therein. If they become - visible in the same namespace as other comparison functions - (e.g., '<code>using</code>' them and the <iterator> header), - then you will suddenly be faced with huge numbers of ambiguity - errors. This was discussed on the -v3 list; Nathan Myers - <a href="http://gcc.gnu.org/ml/libstdc++/2001-01/msg00247.html">sums - things up here</a>. - </p> - </a> - <a name="4_4_interface"><h3>The g++-3 headers are - <em>not ours</em></h3> - <p>If you have found an extremely broken header file which is - causing problems for you, look carefully before submitting a - "high" priority bug report (which you probably shouldn't - do anyhow; see the last paragraph of the page describing + <p>all operations on the re-opened <code>fs</code> will fail, or at + least act very strangely. Yes, they often will, especially if + <code>fs</code> reached the EOF state on the previous file. The + reason is that the state flags are <strong>not</strong> cleared + on a successful call to open(). The standard unfortunately did + not specify behavior in this case, and to everybody's great sorrow, + the <a href="../ext/howto.html#5">proposed LWG resolution</a> (see + DR #22) is to leave the flags unchanged. You must insert a call + to <code>fs.clear()</code> between the calls to close() and open(), + and then everything will work like we all expect it to work. + </p> + <p><a name="4_4_rel_ops"><strong>rel_ops</strong></a> + Another is the <code>rel_ops</code> namespace and the template + comparison operator functions contained therein. If they become + visible in the same namespace as other comparison functions + (e.g., '<code>using</code>' them and the <iterator> header), + then you will suddenly be faced with huge numbers of ambiguity + errors. This was discussed on the -v3 list; Nathan Myers + <a href="http://gcc.gnu.org/ml/libstdc++/2001-01/msg00247.html">sums + things up here</a>. The collisions with vector/string iterator + types have been fixed for 3.1. <!-- more links to email here --> + </p> + <h3><a name="4_4_interface">The g++-3 headers are <em>not ours</em></a></h3> + <p>If you have found an extremely broken header file which is + causing problems for you, look carefully before submitting a + "high" priority bug report (which you probably shouldn't + do anyhow; see the last paragraph of the page describing <a href="http://gcc.gnu.org/gnatswrite.html">the GCC bug database</a>). - </p> - <p>If the headers are in <code>${prefix}/include/g++-3</code>, or if - the installed library's name looks like <code>libstdc++-2.10.a</code> - or <code>libstdc++-libc6-2.10.so</code>, - then you are using the old libstdc++-v2 library, which is nonstandard - and unmaintained. Do not report problems with -v2 to the -v3 - mailing list. - </p> - <p>Currently our header files are installed in - <code>${prefix}/include/g++-v3</code> (see the 'v'?). This may - change with the next release of GCC, as it may be too confusing, - but <a href="http://gcc.gnu.org/ml/gcc/2000-10/msg00732.html">the - question has not yet been decided</a>. - </p> - </a> - <a name="4_4_glibc"> - <p><strong>glibc</strong> - If you're on a GNU/Linux system and have just upgraded to - glibc 2.2, but are still using gcc 2.95.2, then you should have - read the glibc FAQ, specifically 2.34: - <pre> + </p> + <p>If the headers are in <code>${prefix}/include/g++-3</code>, or if + the installed library's name looks like <code>libstdc++-2.10.a</code> + or <code>libstdc++-libc6-2.10.so</code>, + then you are using the old libstdc++-v2 library, which is nonstandard + and unmaintained. Do not report problems with -v2 to the -v3 + mailing list. + </p> + <p>Currently our header files are installed in + <code>${prefix}/include/g++-v3</code> (see the 'v'?). This may + change with the next release of GCC, as it may be too confusing, + but <a href="http://gcc.gnu.org/ml/gcc/2000-10/msg00732.html">the + question has not yet been decided</a>. + </p> + <p><a name="4_4_glibc"><strong>glibc</strong></a> + If you're on a GNU/Linux system and have just upgraded to + glibc 2.2, but are still using gcc 2.95.2, then you should have + read the glibc FAQ, specifically 2.34: + </p> + <pre> 2.34. When compiling C++ programs, I get a compilation error in streambuf.h. {BH} You are using g++ 2.95.2? After upgrading to glibc 2.2, you need to @@ -631,30 +709,44 @@ apply a patch to the include files in /usr/include/g++, because the fpos_t type has changed in glibc 2.2. The patch is at http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff </pre> - Note that 2.95.x shipped with the - <a href="#4_4_interface">old v2 library</a> which is no longer - maintained. Also note that gcc 2.95.3 fixes this problem, but - requires a separate patch for libstdc++-v3. - </p> - </a> - <a name="4_4_checks"> - <p><strong>concept checks</strong> - If you see compilation errors containing messages about - <code> <em>foo</em>Concept </code>and a<code> constraints </code> - member function, then most likely you have violated one of the - requirements for types used during instantiation of template - containers and functions. For example, EqualityComparableConcept - appears if your types must be comparable with == and you have not - provided this capability (a typo, or wrong visibility, or you - just plain forgot, etc). - </p> - <p>More information, including how to optionally enable/disable the - checks, is available - <a href="../19_diagnostics/howto.html#3">here</a>. - </p> - </a> - -<hr> + <p>Note that 2.95.x shipped with the + <a href="#4_4_interface">old v2 library</a> which is no longer + maintained. Also note that gcc 2.95.3 fixes this problem, but + requires a separate patch for libstdc++-v3. + </p> + <p><a name="4_4_checks"><strong>concept checks</strong></a> + If you see compilation errors containing messages about + <code> <em>foo</em>Concept </code>and a<code> constraints </code> + member function, then most likely you have violated one of the + requirements for types used during instantiation of template + containers and functions. For example, EqualityComparableConcept + appears if your types must be comparable with == and you have not + provided this capability (a typo, or wrong visibility, or you + just plain forgot, etc). + </p> + <p>More information, including how to optionally enable/disable the + checks, is available + <a href="../19_diagnostics/howto.html#3">here</a>. + </p> + <p><a name="4_4_dlsym"><strong>dlopen/dlsym</strong></a> + If you are using the C++ library across dynamically-loaded + objects, make certain that you are passing the correct options + when compiling and linking: + </p> + <pre> + // compile the library components + g++ -fPIC -c a.cc + g++ -fPIC -c b.cc + ... + g++ -fPIC -c z.cc + + // create the library + g++ -fPIC -shared -rdynamic -o libfoo.so a.o b.o ... z.o + + // link the executable + g++ -fPIC -rdynamic -o foo ... -L. -lfoo -ldl</pre> + +<hr /> <h2><a name="4_5">4.5 Aw, that's easy to fix!</a></h2> <p>If you have found a bug in the library and you think you have a working fix, then send it in! The main GCC site has a page @@ -673,7 +765,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff <a href="#2_4">testsuite</a> -- but only if such a test exists. </p> -<hr> +<hr /> <h1><a name="5_0">5.0 Miscellaneous</a></h1> <h2><a name="5_1">5.1 string::iterator is not char*; vector<T>::iterator is not T*</a></h2> @@ -694,7 +786,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff vector<> (but not for basic_string<>). </p> -<hr> +<hr /> <h2><a name="5_2">5.2 What's next after libstdc++-v3?</a></h2> <p>Hopefully, not much. The goal of libstdc++-v3 is to produce a fully-compliant, fully-portable Standard Library. After that, @@ -710,16 +802,16 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff we add code to the library based on what the current proposed resolution specifies. Those additions are listed in <a href="../ext/howto.html#5">the extensions page</a>. - </p> + </p></li> <li><p>Performance tuning. Lots of performance tuning. This too is already underway for post-3.0 releases, starting with memory expansion in container classes and buffer usage in synchronized stream objects. - </p> - <li><p>An ABI for libstdc++ will eventually be developed, so that + </p></li> + <li><p>An ABI for libstdc++ is being developed, so that multiple binary-incompatible copies of the library can be replaced with a single backwards-compatible library, like libgcc_s.so is. - </p> + </p></li> <li><p>The current libstdc++ contains extensions to the Library which must be explicitly requested by client code (for example, the hash tables from SGI). Other extensions may be added to @@ -727,7 +819,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff (For example, the "long long" type from C99.) Bugfixes and rewrites (to improve or fix thread safety, for instance) will of course be a continuing task. - </p> + </p></li> </ol> <p><a href="http://gcc.gnu.org/ml/libstdc++/1999/msg00080.html">This question</a> about the next libstdc++ prompted some brief but @@ -735,7 +827,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff <a href="http://gcc.gnu.org/ml/libstdc++/1999/msg00084.html">speculation</a>. </p> -<hr> +<hr /> <h2><a name="5_3">5.3 What about the STL from SGI?</a></h2> <p>The <a href="http://www.sgi.com/Technology/STL/">STL from SGI</a>, version 3.3, was the most recent merge of the STL codebase. The @@ -752,27 +844,30 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff recommended reading. </p> -<hr> +<hr /> <h2><a name="5_4">5.4 Extensions and Backward Compatibility</a></h2> - <p>Although you can specify <code>-I</code> options to make the - preprocessor search the g++-v3/ext and /backward directories, - it is better to refer to files there by their path, as in: + <p>Headers in the <code>ext</code> and <code>backward</code> + subdirectories should be referred to by their relative paths: <!-- Careful, the leading spaces in PRE show up directly. --> </p> - <pre> - #include <ext/hash_map> - </pre> + <pre> + #include <ext/hash_map> </pre> + <p>rather than using <code>-I</code> or other options. This is more + portable and forward-compatible. (The situation is the same as + that of other headers whose directories are not searched directly, + e.g., <code><sys/stat.h></code>, <code><X11/Xlib.h></code>. + </p> <p>Extensions to the library have <a href="../ext/howto.html">their own page</a>. </p> -<hr> +<hr /> <h2><a name="5_5">5.5 [removed]</a></h2> <p>This question has become moot and has been removed. The stub is here to preserve numbering (and hence links/bookmarks). </p> -<hr> +<hr /> <h2><a name="5_6">5.6 Is libstdc++-v3 thread-safe?</a></h2> <p>When the system's libc is itself thread-safe, a non-generic implementation of atomicity.h exists for the architecture, and gcc @@ -783,7 +878,8 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff what object locks must be held based on the objects referenced in a method call. Without getting into great detail, here is an example which requires user-level locks: - <pre> + </p> + <pre> library_class_a shared_object_a; thread_main () { @@ -793,18 +889,17 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff } // Multiple copies of thread_main() are started in independent threads.</pre> - </p> <p>Under the assumption that object_a and object_b are never exposed to another thread, here is an example that should not require any user-level locks: - <pre> + </p> + <pre> thread_main () { library_class_a object_a; library_class_b *object_b = new library_class_b; object_a.add_b (object_b); object_a.mutate (); } </pre> - </p> <p>All library objects are safe to use in a multithreaded program as long as each thread carefully locks out access by any other thread while it uses any object visible to another thread. In general, @@ -819,7 +914,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff more information. </p> -<hr> +<hr /> <h2><a name="5_7">5.7 How do I get a copy of the ISO C++ Standard?</a></h2> <p>Copies of the full ISO 14882 standard are available on line via the ISO mirror site for committee members. Non-members, or those who @@ -837,7 +932,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff <a href="http://www.iso.ch/">ISO homepage</a> and find out! </p> -<hr> +<hr /> <h2><a name="5_8">5.8 What's an ABI and why is it so messy?</a></h2> <p>"ABI" stands for "Application Binary Interface." Conventionally, it refers to a great mass of details about how @@ -886,7 +981,7 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff <!-- ####################################################### --> -<hr> +<hr /> <p class="fineprint"><em> See <a href="../17_intro/license.html">license.html</a> for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/faq/index.txt b/libstdc++-v3/docs/html/faq/index.txt index c2b42c40945..59632af35d4 100644 --- a/libstdc++-v3/docs/html/faq/index.txt +++ b/libstdc++-v3/docs/html/faq/index.txt @@ -32,29 +32,33 @@ 2. [22][removed] 3. [23][removed] 4. [24]I can't use 'long long' on Solaris - 4. [25]Known Bugs and Non-Bugs - 1. [26]What works already? - 2. [27]Bugs in gcc/g++ (not libstdc++-v3) - 3. [28]Bugs in the C++ language/lib specification - 4. [29]Things in libstdc++ that look like bugs - o [30]reopening a stream fails - o [31]-Weffc++ complains too much - o [32]"ambiguous overloads" after including an old-style + 5. [25]_XOPEN_SOURCE / _GNU_SOURCE / etc is always defined + 6. [26]OS X ctype.h is broken! How can I hack it? + 4. [27]Known Bugs and Non-Bugs + 1. [28]What works already? + 2. [29]Bugs in gcc/g++ (not libstdc++-v3) + 3. [30]Bugs in the C++ language/lib specification + 4. [31]Things in libstdc++ that only look like bugs + o [32]reopening a stream fails + o [33]-Weffc++ complains too much + o [34]"ambiguous overloads" after including an old-style header - o [33]The g++-3 headers are not ours - o [34]compilation errors from streambuf.h - o [35]errors about *Cconcept and constraints in the STL... - 5. [36]Aw, that's easy to fix! - 5. [37]Miscellaneous - 1. [38]string::iterator is not char*; vector<T>::iterator is not + o [35]The g++-3 headers are not ours + o [36]compilation errors from streambuf.h + o [37]errors about *Concept and constraints in the STL... + o [38]program crashes when using library code in a + dynamically-loaded library + 5. [39]Aw, that's easy to fix! + 5. [40]Miscellaneous + 1. [41]string::iterator is not char*; vector<T>::iterator is not T* - 2. [39]What's next after libstdc++-v3? - 3. [40]What about the STL from SGI? - 4. [41]Extensions and Backward Compatibility - 5. [42][removed] - 6. [43]Is libstdc++-v3 thread-safe? - 7. [44]How do I get a copy of the ISO C++ Standard? - 8. [45]What's an ABI and why is it so messy? + 2. [42]What's next after libstdc++-v3? + 3. [43]What about the STL from SGI? + 4. [44]Extensions and Backward Compatibility + 5. [45][removed] + 6. [46]Is libstdc++-v3 thread-safe? + 7. [47]How do I get a copy of the ISO C++ Standard? + 8. [48]What's an ABI and why is it so messy? _________________________________________________________________ 1.0 General Information @@ -64,18 +68,18 @@ The GNU Standard C++ Library v3 is an ongoing project to implement the ISO 14882 Standard C++ library as described in chapters 17 through 27 and annex D. As the library reaches stable plateaus, it is captured in - a snapshot and released. The current release is [46]the thirteenth + a snapshot and released. The current release is [49]the fourteenth snapshot. For those who want to see exactly how far the project has come, or just want the latest bleeding-edge code, the up-to-date source is available over anonymous CVS, and can even be browsed over the Web (see below). The older libstdc++-v2 project is no longer maintained; the code has - been completely replaced and rewritten. [47]If you are using V2, then + been completely replaced and rewritten. [50]If you are using V2, then you need to report bugs to your system vendor, not to the V3 list. A more formal description of the V3 goals can be found in the official - [48]design document. + [51]design document. _________________________________________________________________ 1.2 Why should I use libstdc++? @@ -88,8 +92,8 @@ The GNU C/C++/FORTRAN/<pick-a-language> compiler (gcc, g++, etc) is widely considered to be one of the leading compilers in the world. Its - development has recently been taken over by the [49]GCC team. All of - the rapid development and near-legendary [50]portability that are the + development has recently been taken over by the [52]GCC team. All of + the rapid development and near-legendary [53]portability that are the hallmarks of an open-source project are being applied to libstdc++. That means that all of the Standard classes and functions (such as @@ -102,21 +106,21 @@ The libstdc++ project is contributed to by several developers all over the world, in the same way as GCC or Linux. Benjamin Kosnik, Gabriel - Dos Reis, Phil Edwards, and Ulrich Drepper are the lead maintainers of - the CVS archive. + Dos Reis, Phil Edwards, Ulrich Drepper, Loren James Rittle, and Paolo + Carlini are the lead maintainers of the CVS archive. Development and discussion is held on the libstdc++ mailing list. Subscribing to the list, or searching the list archives, is open to - everyone. You can read instructions for doing so on the [51]homepage. + everyone. You can read instructions for doing so on the [54]homepage. If you have questions, ideas, code, or are just curious, sign up! _________________________________________________________________ 1.4 How do I get libstdc++? - The thirteenth (and latest) snapshot of libstdc++-v3 is [52]available + The fourteenth (and latest) snapshot of libstdc++-v3 is [55]available via ftp. - The [53]homepage has instructions for retrieving the latest CVS + The [56]homepage has instructions for retrieving the latest CVS sources, and for browsing the CVS sources over the web. The subset commonly known as the Standard Template Library (chapters @@ -132,7 +136,7 @@ 1.6 How do I contribute to the effort? - Here is [54]a page devoted to this topic. Subscribing to the mailing + Here is [57]a page devoted to this topic. Subscribing to the mailing list (see above, or the homepage) is a very good idea if you have something to contribute, or if you have spare time and want to help. Contributions don't have to be in the form of source code; anybody who @@ -167,11 +171,11 @@ extracted into an updated utilities library, but nobody has stated such a project yet. - (The [55]Boost site houses free C++ libraries that do varying things, + (The [58]Boost site houses free C++ libraries that do varying things, and happened to be started by members of the Standards Committee. Certain "useful stuff" classes will probably migrate there.) - For the bold and/or desperate, the [56]GCC FAQ describes where to find + For the bold and/or desperate, the [59]GCC FAQ describes where to find the last libg++ source. _________________________________________________________________ @@ -181,16 +185,16 @@ remains unanswered, then just ask the mailing list. At present, you do not need to be subscribed to the list to send a message to it. More information is available on the homepage (including how to browse the - list archives); to send to the list, use [57]libstdc++@gcc.gnu.org. + list archives); to send to the list, use [60]libstdc++@gcc.gnu.org. If you have a question that you think should be included here, or if - you have a question about a question/answer here, contact [58]Phil - Edwards or [59]Gabriel Dos Reis. + you have a question about a question/answer here, contact [61]Phil + Edwards or [62]Gabriel Dos Reis. _________________________________________________________________ 1.9 What are the license terms for libstdc++-v3? - See [60]our license description for these and related questions. + See [63]our license description for these and related questions. _________________________________________________________________ 2.0 Installation @@ -207,13 +211,13 @@ * The GNU Autotools are needed if you are messing with the configury or makefiles. - The file [61]documentation.html provides a good overview of the steps + The file [64]documentation.html provides a good overview of the steps necessary to build, install, and use the library. Instructions for configuring the library with new flags such as --enable-threads are there also, as well as patches and instructions for working with GCC 2.95. - The top-level install.html and [62]RELEASE-NOTES files contain the + The top-level install.html and [65]RELEASE-NOTES files contain the exact build and installation instructions. You may wish to browse those files over CVSweb ahead of time to get a feel for what's required. RELEASE-NOTES is located in the ".../docs/17_intro/" @@ -230,8 +234,8 @@ The Concurrent Versions System is one of several revision control packages. It was selected for GNU projects because it's free (speech), - free (beer), and very high quality. The [63]CVS entry in the GNU - software catalogue has a better description as well as a [64]link to + free (beer), and very high quality. The [66]CVS entry in the GNU + software catalogue has a better description as well as a [67]link to the makers of CVS. The "anonymous client checkout" feature of CVS is similar to anonymous @@ -282,7 +286,7 @@ people don't like it, so here are two pseudo-solutions: If the only functions from libstdc++.a which you need are language - support functions (those listed in [65]clause 18 of the standard, + support functions (those listed in [68]clause 18 of the standard, e.g., new and delete), then try linking against libsupc++.a (usually specifying -lsupc++ when calling g++ for the final link step will do it). This library contains only those support routines, one per object @@ -348,6 +352,48 @@ This has been fixed for 3.0.3 and onwards. _________________________________________________________________ +3.5 _XOPEN_SOURCE / _GNU_SOURCE / etc is always defined + + On Solaris, g++ (but not gcc) always defines the preprocessor macro + _XOPEN_SOURCE. On GNU/Linux, the same happens with _GNU_SOURCE. (This + is not an exhaustive list; other macros and other platforms are also + affected.) + + These macros are typically used in C library headers, guarding new + versions of functions from their older versions. The C++ standard + library includes the C standard library, but it requires the C90 + version, which for backwards-compatability reasons is often not the + default for many vendors. + + More to the point, the C++ standard requires behavior which is only + available on certain platforms after certain symbols are defined. + Usually the issue involves I/O-related typedefs. In order to ensure + correctness, the compiler simply predefines those symbols. + + Note that it's not enough to #define them only when the library is + being built (during installation). Since we don't have an 'export' + keyword, much of the library exists as headers, which means that the + symbols must also be defined as your programs are parsed and compiled. + + To see which symbols are defined, look for CPLUSPLUS_CPP_SPEC in the + gcc config headers for your target (and try changing them to see what + happens when building complicated code). You can also run "g++ -E -dM + - < /dev/null" to display a list of predefined macros for any + particular installation. + + This has been discussed on the mailing lists [69]quite a bit. + + This method is something of a wart. We'd like to find a cleaner + solution, but nobody yet has contributed the time. + _________________________________________________________________ + +3.6 OS X ctype.h is broken! How can I hack it? + + This is a long-standing bug in the OS X support. Fortunately, the + patch is quite simple, and well-known. [70]Here's a link to the + solution. + _________________________________________________________________ + 4.0 Known Bugs and Non-Bugs Note that this section can get rapdily outdated -- such is the nature @@ -357,13 +403,19 @@ For 3.0.1, the most common "bug" is an apparently missing "../" in include/Makefile, resulting in files like gthr.h and gthr-single.h not - being found. - - Please read [66]the configuration instructions for GCC, specifically - the part about configuring in a separate build directory, and how - strongly recommended it is. Building in the source directory is - fragile, is rarely tested, and tends to break, as in this case. This - was fixed for 3.0.2. + being found. Please read [71]the configuration instructions for GCC, + specifically the part about configuring in a separate build directory, + and how strongly recommended it is. Building in the source directory + is fragile, is rarely tested, and tends to break, as in this case. + This was fixed for 3.0.2. + + For 3.1, the most common "bug" is a parse error when using <fstream>, + ending with a message, "bits/basic_file.h:52: parse error before `{' + token." Please read [72]the installation instructions for GCC, + specifically the part about not installing newer versions on top of + older versions. If you install 3.1 over a 3.0.x release, then the + wrong basic_file.h header will be found (its location changed between + releases). Please do not report these as bugs. We know about them. Reporting this -- or any other problem that's already been fixed -- hinders the @@ -374,8 +426,22 @@ This is a verbatim clip from the "Status" section of the RELEASE-NOTES for the latest snapshot. For a list of fixed bugs, see that file. -New in 3.0.96: +New: --- +(post 3.0.97) +- more doxygen documentation +- more named locale fixups +- stdio_filebuf that takes fd, FILE +- io performance tuning +- allocation tuning, valgrind fixups +- __cxa_demangle now supported +(3.0.97) +- more doxygen documentation. +- more named locale bug fixes +- support for symbol versioning when using GNU ld >= 2.12 +- wide-io +- tuning for executable size +(3.0.96) - more doxygen documentation. - extensions moved out of namespace std - HPUX long long support @@ -385,9 +451,7 @@ New in 3.0.96: - header simplification - named locale bug shakeout - thread testsuite - -New in 3.0.95: ---- +(3.0.95) - add S390, m68k, x86-64 support. - doxygen documentation has been extended, including man pages. - verbose terminate handling has been added. @@ -416,33 +480,33 @@ New in 3.0.95: libstdc++. If you are experiencing one of these problems, you can find more information on the libstdc++ and the GCC mailing lists. - Before reporting a bug, examine the [67]bugs database with the + Before reporting a bug, examine the [73]bugs database with the category set to "libstdc++". The BUGS file in the source tree also tracks known serious problems. * Debugging is problematic, due to bugs in line-number generation (mostly fixed in the compiler) and gdb lagging behind the compiler (lack of personnel). We recommend configuring the compiler using --with-dwarf2 if the DWARF2 debugging format is not already the - default on your platform. Also, [68]changing your GDB settings can + default on your platform. Also, [74]changing your GDB settings can have a profound effect on your C++ debugging experiences. :-) _________________________________________________________________ 4.3 Bugs in the C++ language/lib specification - Yes, unfortunately, there are some. In a [69]message to the list, + Yes, unfortunately, there are some. In a [75]message to the list, Nathan Myers announced that he has started a list of problems in the ISO C++ Standard itself, especially with regard to the chapters that - concern the library. The list itself is [70]posted on his website. + concern the library. The list itself is [76]posted on his website. Developers who are having problems interpreting the Standard may wish to consult his notes. For those people who are not part of the ISO Library Group (i.e., nearly all of us needing to read this page in the first place :-), a - public list of the library defects is occasionally published [71]here. - Some of these have resulted in [72]code changes. + public list of the library defects is occasionally published [77]here. + Some of these have resulted in [78]code changes. _________________________________________________________________ -4.4 Things in libstdc++ that look like bugs +4.4 Things in libstdc++ that only look like bugs There are things which are not bugs in the compiler (4.2) nor the language specification (4.3), but aren't really bugs in libstdc++, @@ -471,7 +535,7 @@ New in 3.0.95: state on the previous file. The reason is that the state flags are not cleared on a successful call to open(). The standard unfortunately did not specify behavior in this case, and to everybody's great sorrow, - the [73]proposed LWG resolution (see DR #22) is to leave the flags + the [79]proposed LWG resolution (see DR #22) is to leave the flags unchanged. You must insert a call to fs.clear() between the calls to close() and open(), and then everything will work like we all expect it to work. @@ -481,14 +545,15 @@ New in 3.0.95: same namespace as other comparison functions (e.g., 'using' them and the <iterator> header), then you will suddenly be faced with huge numbers of ambiguity errors. This was discussed on the -v3 list; - Nathan Myers [74]sums things up here. + Nathan Myers [80]sums things up here. The collisions with + vector/string iterator types have been fixed for 3.1. The g++-3 headers are not ours If you have found an extremely broken header file which is causing problems for you, look carefully before submitting a "high" priority bug report (which you probably shouldn't do anyhow; see the last - paragraph of the page describing [75]the GCC bug database). + paragraph of the page describing [81]the GCC bug database). If the headers are in ${prefix}/include/g++-3, or if the installed library's name looks like libstdc++-2.10.a or libstdc++-libc6-2.10.so, @@ -498,7 +563,7 @@ New in 3.0.95: Currently our header files are installed in ${prefix}/include/g++-v3 (see the 'v'?). This may change with the next release of GCC, as it - may be too confusing, but [76]the question has not yet been decided. + may be too confusing, but [82]the question has not yet been decided. glibc If you're on a GNU/Linux system and have just upgraded to glibc 2.2, but are still using gcc 2.95.2, then you should have read the @@ -511,7 +576,7 @@ type has changed in glibc 2.2. The patch is at http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff - Note that 2.95.x shipped with the [77]old v2 library which is no + Note that 2.95.x shipped with the [83]old v2 library which is no longer maintained. Also note that gcc 2.95.3 fixes this problem, but requires a separate patch for libstdc++-v3. @@ -524,23 +589,38 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff visibility, or you just plain forgot, etc). More information, including how to optionally enable/disable the - checks, is available [78]here. + checks, is available [84]here. + + dlopen/dlsym If you are using the C++ library across + dynamically-loaded objects, make certain that you are passing the + correct options when compiling and linking: + // compile the library components + g++ -fPIC -c a.cc + g++ -fPIC -c b.cc + ... + g++ -fPIC -c z.cc + + // create the library + g++ -fPIC -shared -rdynamic -o libfoo.so a.o b.o ... z.o + + // link the executable + g++ -fPIC -rdynamic -o foo ... -L. -lfoo -ldl _________________________________________________________________ 4.5 Aw, that's easy to fix! If you have found a bug in the library and you think you have a working fix, then send it in! The main GCC site has a page on - [79]submitting patches that covers the procedure, but for libstdc++ + [85]submitting patches that covers the procedure, but for libstdc++ you should also send the patch to our mailing list in addition to the - GCC patches mailing list. The libstdc++ [80]contributors' page also + GCC patches mailing list. The libstdc++ [86]contributors' page also talks about how to submit patches. In addition to the description, the patch, and the ChangeLog entry, it is a Good Thing if you can additionally create a small test program to test for the presence of the bug that your patch fixes. Bugs have a way of being reintroduced; if an old bug creeps back in, it will be - caught immediately by the [81]testsuite -- but only if such a test + caught immediately by the [87]testsuite -- but only if such a test exists. _________________________________________________________________ @@ -574,15 +654,15 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff libstdc++. Some of that is already happening, see 4.2. Some of those changes are being predicted by the library maintainers, and we add code to the library based on what the current proposed - resolution specifies. Those additions are listed in [82]the + resolution specifies. Those additions are listed in [88]the extensions page. 2. Performance tuning. Lots of performance tuning. This too is already underway for post-3.0 releases, starting with memory expansion in container classes and buffer usage in synchronized stream objects. - 3. An ABI for libstdc++ will eventually be developed, so that - multiple binary-incompatible copies of the library can be replaced - with a single backwards-compatible library, like libgcc_s.so is. + 3. An ABI for libstdc++ is being developed, so that multiple + binary-incompatible copies of the library can be replaced with a + single backwards-compatible library, like libgcc_s.so is. 4. The current libstdc++ contains extensions to the Library which must be explicitly requested by client code (for example, the hash tables from SGI). Other extensions may be added to libstdc++-v3 if @@ -590,13 +670,13 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff type from C99.) Bugfixes and rewrites (to improve or fix thread safety, for instance) will of course be a continuing task. - [83]This question about the next libstdc++ prompted some brief but - interesting [84]speculation. + [89]This question about the next libstdc++ prompted some brief but + interesting [90]speculation. _________________________________________________________________ 5.3 What about the STL from SGI? - The [85]STL from SGI, version 3.3, was the most recent merge of the + The [91]STL from SGI, version 3.3, was the most recent merge of the STL codebase. The code in libstdc++ contains many fixes and changes, and it is very likely that the SGI code is no longer under active development. We expect that no future merges will take place. @@ -611,13 +691,16 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff 5.4 Extensions and Backward Compatibility - Although you can specify -I options to make the preprocessor search - the g++-v3/ext and /backward directories, it is better to refer to - files there by their path, as in: - #include <ext/hash_map> + Headers in the ext and backward subdirectories should be referred to + by their relative paths: + #include <ext/hash_map> + rather than using -I or other options. This is more portable and + forward-compatible. (The situation is the same as that of other + headers whose directories are not searched directly, e.g., + <sys/stat.h>, <X11/Xlib.h>. - Extensions to the library have [86]their own page. + Extensions to the library have [92]their own page. _________________________________________________________________ 5.5 [removed] @@ -666,8 +749,8 @@ a otherwise documented as safe, do not assume that two threads may access a shared standard library object at the same time. - See chapters [87]17 (library introduction), [88]23 (containers), and - [89]27 (I/O) for more information. + See chapters [93]17 (library introduction), [94]23 (containers), and + [95]27 (I/O) for more information. _________________________________________________________________ 5.7 How do I get a copy of the ISO C++ Standard? @@ -678,11 +761,11 @@ a their two-meeting commitment for voting rights, may get a copy of the standard from their respective national standards organization. In the USA, this national standards organization is ANSI and their website is - right [90]here. (And if you've already registered with them, clicking - this link will take you to directly to the place where you can [91]buy + right [96]here. (And if you've already registered with them, clicking + this link will take you to directly to the place where you can [97]buy the standard on-line. - Who is your country's member body? Visit the [92]ISO homepage and find + Who is your country's member body? Visit the [98]ISO homepage and find out! _________________________________________________________________ @@ -733,8 +816,8 @@ a encompasses the standard library. _________________________________________________________________ - See [93]license.html for copying conditions. Comments and suggestions - are welcome, and may be sent to [94]the libstdc++ mailing list. + See [99]license.html for copying conditions. Comments and suggestions + are welcome, and may be sent to [100]the libstdc++ mailing list. References @@ -762,73 +845,79 @@ References 22. ../faq/index.html#3_2 23. ../faq/index.html#3_3 24. ../faq/index.html#3_4 - 25. ../faq/index.html#4_0 - 26. ../faq/index.html#4_1 - 27. ../faq/index.html#4_2 - 28. ../faq/index.html#4_3 - 29. ../faq/index.html#4_4 - 30. ../faq/index.html#4_4_iostreamclear - 31. ../faq/index.html#4_4_Weff - 32. ../faq/index.html#4_4_rel_ops - 33. ../faq/index.html#4_4_interface - 34. ../faq/index.html#4_4_glibc - 35. ../faq/index.html#4_4_checks - 36. ../faq/index.html#4_5 - 37. ../faq/index.html#5_0 - 38. ../faq/index.html#5_1 - 39. ../faq/index.html#5_2 - 40. ../faq/index.html#5_3 - 41. ../faq/index.html#5_4 - 42. ../faq/index.html#5_5 - 43. ../faq/index.html#5_6 - 44. ../faq/index.html#5_7 - 45. ../faq/index.html#5_8 - 46. http://gcc.gnu.org/libstdc++/download.html - 47. ../faq/index.html#4_4_interface - 48. ../17_intro/DESIGN - 49. http://gcc.gnu.org/ - 50. http://gcc.gnu.org/gcc-2.95/buildstat.html - 51. http://gcc.gnu.org/libstdc++/ - 52. http://gcc.gnu.org/libstdc++/download.html - 53. http://gcc.gnu.org/libstdc++/ - 54. ../17_intro/contribute.html - 55. http://www.boost.org/ - 56. http://gcc.gnu.org/fom_serv/cache/33.html - 57. mailto:libstdc++@gcc.gnu.org - 58. mailto:pme@gcc.gnu.org - 59. mailto:gdr@gcc.gnu.org - 60. ../17_intro/license.html - 61. ../documentation.html - 62. ../17_intro/RELEASE-NOTES - 63. http://www.gnu.org/software/cvs/cvs.html - 64. http://www.cvshome.org/ - 65. ../18_support/howto.html - 66. http://gcc.gnu.org/install/configure.html - 67. http://gcc.gnu.org/bugs.html - 68. http://gcc.gnu.org/ml/libstdc++/2002-02/msg00034.html - 69. http://gcc.gnu.org/ml/libstdc++/1998/msg00006.html - 70. http://www.cantrip.org/draft-bugs.txt - 71. http://anubis.dkuug.dk/jtc1/sc22/wg21/ - 72. ../faq/index.html#5_2 - 73. ../ext/howto.html#5 - 74. http://gcc.gnu.org/ml/libstdc++/2001-01/msg00247.html - 75. http://gcc.gnu.org/gnatswrite.html - 76. http://gcc.gnu.org/ml/gcc/2000-10/msg00732.html - 77. ../faq/index.html#4_4_interface - 78. ../19_diagnostics/howto.html#3 - 79. http://gcc.gnu.org/contribute.html - 80. ../17_intro/contribute.html - 81. ../faq/index.html#2_4 - 82. ../ext/howto.html#5 - 83. http://gcc.gnu.org/ml/libstdc++/1999/msg00080.html - 84. http://gcc.gnu.org/ml/libstdc++/1999/msg00084.html - 85. http://www.sgi.com/Technology/STL/ - 86. ../ext/howto.html - 87. ../17_intro/howto.html#3 - 88. ../23_containers/howto.html#3 - 89. ../27_io/howto.html#9 - 90. http://www.ansi.org/ - 91. http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%2D1998 - 92. http://www.iso.ch/ - 93. ../17_intro/license.html - 94. mailto:libstdc++@gcc.gnu.org + 25. ../faq/index.html#3_5 + 26. ../faq/index.html#3_6 + 27. ../faq/index.html#4_0 + 28. ../faq/index.html#4_1 + 29. ../faq/index.html#4_2 + 30. ../faq/index.html#4_3 + 31. ../faq/index.html#4_4 + 32. ../faq/index.html#4_4_iostreamclear + 33. ../faq/index.html#4_4_Weff + 34. ../faq/index.html#4_4_rel_ops + 35. ../faq/index.html#4_4_interface + 36. ../faq/index.html#4_4_glibc + 37. ../faq/index.html#4_4_checks + 38. ../faq/index.html#4_4_dlsym + 39. ../faq/index.html#4_5 + 40. ../faq/index.html#5_0 + 41. ../faq/index.html#5_1 + 42. ../faq/index.html#5_2 + 43. ../faq/index.html#5_3 + 44. ../faq/index.html#5_4 + 45. ../faq/index.html#5_5 + 46. ../faq/index.html#5_6 + 47. ../faq/index.html#5_7 + 48. ../faq/index.html#5_8 + 49. http://gcc.gnu.org/libstdc++/index.html#download + 50. ../faq/index.html#4_4_interface + 51. ../17_intro/DESIGN + 52. http://gcc.gnu.org/ + 53. http://gcc.gnu.org/gcc-3.0/buildstat.html + 54. http://gcc.gnu.org/libstdc++/ + 55. http://gcc.gnu.org/libstdc++/index.html#download + 56. http://gcc.gnu.org/libstdc++/ + 57. ../17_intro/contribute.html + 58. http://www.boost.org/ + 59. http://gcc.gnu.org/fom_serv/cache/33.html + 60. mailto:libstdc++@gcc.gnu.org + 61. mailto:pme@gcc.gnu.org + 62. mailto:gdr@gcc.gnu.org + 63. ../17_intro/license.html + 64. ../documentation.html + 65. ../17_intro/RELEASE-NOTES + 66. http://www.gnu.org/software/cvs/cvs.html + 67. http://www.cvshome.org/ + 68. ../18_support/howto.html + 69. http://gcc.gnu.org/cgi-bin/htsearch?method=and&format=builtin-long&sort=score&words=_XOPEN_SOURCE+Solaris + 70. http://gcc.gnu.org/ml/gcc/2002-03/msg00817.html + 71. http://gcc.gnu.org/install/configure.html + 72. http://gcc.gnu.org/install/ + 73. http://gcc.gnu.org/bugs.html + 74. http://gcc.gnu.org/ml/libstdc++/2002-02/msg00034.html + 75. http://gcc.gnu.org/ml/libstdc++/1998/msg00006.html + 76. http://www.cantrip.org/draft-bugs.txt + 77. http://anubis.dkuug.dk/jtc1/sc22/wg21/ + 78. ../faq/index.html#5_2 + 79. ../ext/howto.html#5 + 80. http://gcc.gnu.org/ml/libstdc++/2001-01/msg00247.html + 81. http://gcc.gnu.org/gnatswrite.html + 82. http://gcc.gnu.org/ml/gcc/2000-10/msg00732.html + 83. ../faq/index.html#4_4_interface + 84. ../19_diagnostics/howto.html#3 + 85. http://gcc.gnu.org/contribute.html + 86. ../17_intro/contribute.html + 87. ../faq/index.html#2_4 + 88. ../ext/howto.html#5 + 89. http://gcc.gnu.org/ml/libstdc++/1999/msg00080.html + 90. http://gcc.gnu.org/ml/libstdc++/1999/msg00084.html + 91. http://www.sgi.com/Technology/STL/ + 92. ../ext/howto.html + 93. ../17_intro/howto.html#3 + 94. ../23_containers/howto.html#3 + 95. ../27_io/howto.html#9 + 96. http://www.ansi.org/ + 97. http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%2D1998 + 98. http://www.iso.ch/ + 99. ../17_intro/license.html + 100. mailto:libstdc++@gcc.gnu.org diff --git a/libstdc++-v3/docs/html/install.html b/libstdc++-v3/docs/html/install.html index 38d1c1d5e94..f91e6c7f2d7 100644 --- a/libstdc++-v3/docs/html/install.html +++ b/libstdc++-v3/docs/html/install.html @@ -1,12 +1,11 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> <html> <head> - <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)"> - <meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++"> - <meta name="DESCRIPTION" content="README for the GNU libstdc++ effort."> - <meta name="GENERATOR" content="vi and eight fingers"> + <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> + <meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++" /> + <meta name="DESCRIPTION" content="README for the GNU libstdc++ effort." /> + <meta name="GENERATOR" content="vi and eight fingers" /> <title>libstdc++-v3 Installation Instructions</title> -<link rel="StyleSheet" href="lib3styles.css"> +<link rel="StyleSheet" href="lib3styles.css" /> </head> <body> @@ -18,21 +17,22 @@ </p> <p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>. +</p> <!-- ####################################################### --> -<hr> +<hr /> <h2>Contents</h2> <ul> - <li><a href="#prereqs">Tools you will need beforehand</a> - <li><a href="#srcsetup">Setting up the source directories</a> - <li><a href="#config">Configuring</a> - <li><a href="#install">Building and installing the library</a> - <li><a href="#postinstall">Post-installation</a> - <li><a href="#usage">Using the library</a> + <li><a href="#prereqs">Tools you will need beforehand</a></li> + <li><a href="#srcsetup">Setting up the source directories</a></li> + <li><a href="#config">Configuring</a></li> + <li><a href="#install">Building and installing the library</a></li> + <li><a href="#postinstall">Post-installation</a></li> + <li><a href="#usage">Using the library</a></li> </ul> -<hr> +<hr /> <!-- ####################################################### --> @@ -67,85 +67,137 @@ <p>As of June 19, 2000, libstdc++ attempts to use tricky and space-saving features of the GNU toolchain, enabled with - <code>-ffunction-sections -fdata-sections -Wl,--gc-sections</code>. - To obtain maximum benefit from this, binutils after this date - should also be used (bugs were fixed with C++ exception handling - related to this change in libstdc++-v3). The version of these - tools should be <code>2.10.90</code>, and you can get snapshots (as + <code>-ffunction-sections -fdata-sections + -Wl,--gc-sections</code>. To obtain maximum benefit from this, + binutils after this date should also be used (bugs were fixed + with C++ exception handling related to this change in + libstdc++-v3). The version of these tools should be + <code>2.10.90</code>, or later, and you can get snapshots (as well as releases) of binutils - <a href="ftp://sources.redhat.com/pub/binutils">here</a>. + <a href="ftp://sources.redhat.com/pub/binutils">here</a>. The + configure process will automatically detect and use these + features if the underlying support is present. </p> - - <!-- Commented until some system-specific requirements appear. - <p>Finally, a few system-specific requirements: - <dl> - <dt>Cygwin - <dd>If you are using Cygwin to compile libstdc++-v3 on Win32, you'll - [snip] - - </dl> + + <p>If you are using a 3.1-series libstdc++ snapshot, then the + requirements are slightly more stringent: the compiler sources + must also be 3.1 or later (for both technical and licensing + reasons), and your binutils must be 2.11.95 or later if you want + to use symbol versioning in shared libraries. Again, the + configure process will automatically detect and use these + features if the underlying support is present. </p> ---> -<hr> + <p>Finally, a few system-specific requirements: </p> + <dl> + <dt> linux </dt> + + <dd>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 C++ + named locale support. + + <p> + The configure option --enable-clocale can be used force a + particular behavior. + </p> + + <p> + If the 'gnu' locale model is being used, the following locales + are used and tested in the libstdc++ testsuites: en_HK, en_US, + fr_FR, fr_FR@euro, de_DE, de_DE@euro, ja_JP.eucjp, es_MX, en_PH, + and it_IT. Failure to have the underlying "C" library locale + information installed will mean that C++ named locales for the + above regions will not work: because of this, the libstdc++ + testsuite will not pass the named locale tests. If this isn't an + issue, don't worry about it. If named locales are needed, the + underlying locale information must be installed. Note that + rebuilding libstdc++ after the "C" locales are installed is not + necessary. + </p> + + <p> To install + support for locales, do only one of the following: </p> + <ul> + <li> install all locales + <p> <code> export LC_ALL=C </code> </p> + <p> <code> rpm -e glibc-common --nodeps </code> </p> + <p> <code> rpm -i --define "_install_langs all" + glibc-common-2.2.5-34.i386.rpm </code> </p> + </li> + <li> install just the necessary locales + <p> <code> localedef -i de_DE -f ISO-8859-1 de_DE </code> </p> + </li> + </ul> + </dd> + </dl> + +<hr /> <h2><a name="srcsetup">Setting up the source directories</a></h2> <p>The following definitions will be used throughout the rest of this document: + </p> <ul> <li><em>gccsrcdir</em>: The directory holding the source of the compiler. It should have several subdirectories like - <em>gccsrcdir</em>/libio and <em>gccsrcdir</em>/gcc. + <em>gccsrcdir</em>/libiberty and <em>gccsrcdir</em>/gcc. + </li> <li><em>libsrcdir</em>: The directory holding the source of the C++ library. + </li> <li><em>gccbuilddir</em>: The build directory for the compiler in <em>gccsrcdir</em>. GCC requires that it be built in a different directory than its sources. + </li> <li><em>libbuilddir</em>: The build directory for libstdc++. + </li> <li><em>destdir</em>: The eventual installation directory for the compiler/libraries, set with the --prefix option to the configure script. + </li> </ul> - Note: + <p> Note: </p> <ol> <li>The 3.0 version and following are intended to replace the library that comes with the compiler, so <em>libsrcdir</em> and <em>libbuilddir</em> must be contained under <em>gccsrcdir</em> and <em>gccbuilddir</em>, respectively. + </li> <li>The source, build, and installation directories should not be parents of one another; i.e., these should all be separate directories. Please don't build out of the source directory. + </li> </ol> - </p> <p>Check out or download the GCC sources: the resulting source directory (<code>gcc</code> or <code>gcc-3.0.3</code>, for example) is <em>gccsrcdir</em>. Once in <em>gccsrcdir</em>, you'll need to rename or delete the libstdc++-v3 directory which comes with that snapshot: - <pre> + </p> + <pre> mv libstdc++-v3 libstdc++-v3-previous <strong>[OR]</strong> rm -r libstdc++-v3</pre> - </p> <p>Next, unpack the libstdc++-v3 library tarball into this <em>gccsrcdir</em> directory; it will create a <em>libsrcdir</em> called <code>libstdc++-<em>version</em></code>: - <pre> - gzip -dc libstdc++-version.tar.gz | tar xf -</pre> </p> + <pre> + gzip -dc libstdc++-version.tar.gz | tar xf -</pre> <p>Finally, rename <em>libsrcdir</em> to <code>libstdc++-v3</code> so that gcc's configure flags will be able to deal with the new library. - <pre> - mv <em>libsrcdir</em> libstdc++-v3</pre> </p> + <pre> + mv <em>libsrcdir</em> libstdc++-v3</pre> -<hr> +<hr /> <h2><a name="config">Configuring</a></h2> <p>If you have never done this before, you should read the basic <a href="http://gcc.gnu.org/install/">GCC Installation - Instructions</a> first. Read <em>all of them</em>. Twice. + Instructions</a> first. Read <em>all of them</em>. + <strong>Twice.</strong> </p> <p>When building libstdc++-v3 you'll have to configure the entire <em>gccsrcdir</em> directory. The full list of libstdc++-v3 @@ -156,13 +208,12 @@ building the C++ language parts. </p> - <p><pre> + <pre> cd <em>gccbuilddir</em> <em>gccsrcdir</em>/configure --prefix=<em>destdir</em> --other-opts...</pre> - </p> -<hr> +<hr /> <h2><a name="install">Building and installing the library</a></h2> <p>Now you have a few options:</p> <h3>[re]building <em>everything</em></h3> @@ -177,9 +228,10 @@ </p> <h3>[re]building only libstdc++</h3> - <p>To rebuild just libstdc++, use: - <pre> - make all-target-<em>libstdc++-v3</em></pre> + <p>To rebuild just libstdc++, use: </p> + <pre> + make all-target-libstdc++-v3</pre> + <p> This will configure and build the C++ library in the <em>gccbuilddir/cpu-vendor-os/</em>libstdc++ directory. </p> @@ -192,45 +244,64 @@ information is causing problems, you can delete it entirely, or simply edit it and remove lines. </p> - <p>You're done. Now install the rebuilt pieces with - <pre> + <p>You're done. Now install the rebuilt pieces with</p> + <pre> make install</pre> - or - <pre> + <p>or</p> + <pre> make install-gcc make install-target-libstdc++-v3</pre> - </p> -<hr> +<hr /> <h2><a name="postinstall">Post-installation</a></h2> <p>Installation will create the <em>destdir</em> directory and populate it with subdirectories: - <pre> + </p> + <pre> lib/ - include/g++-v3/ + include/c++/<em>gcc-version</em> backward/ bits/ <em>cpu-vendor-os</em>/bits/ ext/</pre> + <p>If you used the version-specific-libs configure option, then most of + the headers and library files will be moved under + <code>lib/gcc-lib/</code> instead. </p> - <p>You can check the status of the build without installing it using - <pre> + <p>You can check the status of the build without installing it using</p> + <pre> make check</pre> - or you can check the status of the installed library using - <pre> + <p>or you can check the status of the installed library using</p> + <pre> make check-install</pre> - in the <em>libbuilddir</em> directory. + <p>in the <em>libbuilddir</em> directory. These commands will create a 'testsuite' directory underneath <em>libbuilddir</em> containing the results of the tests. We are interested in any strange failures of the testsuite; please see <a href="faq/index.html#2_4">FAQ 2.4</a> for which files to examine. </p> + <p> In addition, there are some testing options that are mostly of + interest to library maintainers and system integrators. As such, + these tests may not work on all cpu and host combinations. These + options include, but are not necessarily limited to, the following: -<hr> + <p>The library ABI can be tested using</p> + <pre> + make check-abi</pre> + + <p>The library can also be tested using a bash script, instead of + the default dejagnu test harness</p> + <pre> + make check-script</pre> + or + <pre> + make check-script-install</pre> + +<hr /> <h2><a name="usage">Using the library</a></h2> - <li><B>Find the new library at runtime (shared linking only)</B> + <h3>Find the new library at runtime (shared linking only)</h3> <p>If you only built a static library (libstdc++.a), or if you specified static linking, you don't have to worry about this. But if you built a shared library (libstdc++.so) and linked @@ -240,24 +311,26 @@ <p>Methods vary for different platforms and different styles, but the usual ones are printed to the screen during installation. They include: - <ul> + </p> + <ul> <li>At runtime set LD_LIBRARY_PATH in your environment correctly, so that the shared library for libstdc++ can be found and loaded. Be certain that you understand all of the other implications and behavior of LD_LIBRARY_PATH first (few people do, and they get into trouble). + </li> <li>Compile the path to find the library at runtime into the program. This can be done by passing certain options to g++, which will in turn pass them on to the linker. The exact format of the options is dependent on which linker you use: <ul> - <li>GNU ld (default on Linux):<code> -Wl,--rpath,<em>destdir</em>/lib</code> - <li>IRIX ld:<code> -Wl,-rpath,<em>destdir</em>/lib</code> - <li>Solaris ld:<code> -Wl,-R<em>destdir</em>/lib</code> - <li>More...? + <li>GNU ld (default on Linux):<code> -Wl,--rpath,<em>destdir</em>/lib</code></li> + <li>IRIX ld:<code> -Wl,-rpath,<em>destdir</em>/lib</code></li> + <li>Solaris ld:<code> -Wl,-R<em>destdir</em>/lib</code></li> + <li>More...? Let us know!</li> </ul> - </ul> - </p> + </li> + </ul> <p>Use the <code>ldd(1)</code> utility to show which library the system thinks it will get at runtime. </p> @@ -265,12 +338,10 @@ you use Libtool to create your executables, these details are taken care of for you. </p> - </ol> - </p> <!-- -<hr> +<hr /> <h2><a name=""></a></h2> <p> </p> @@ -279,7 +350,7 @@ <!-- ####################################################### --> -<hr> +<hr /> <p class="fineprint"><em> See <a href="17_intro/license.html">license.html</a> for copying conditions. Comments and suggestions are welcome, and may be sent to diff --git a/libstdc++-v3/docs/html/makedoc.awk b/libstdc++-v3/docs/html/makedoc.awk new file mode 100644 index 00000000000..9da77d9c1a1 --- /dev/null +++ b/libstdc++-v3/docs/html/makedoc.awk @@ -0,0 +1,69 @@ +# Take apart bits of HTML and puts them back together again in new and +# fascinating ways. Copyright (C) 2002 Free Software Foundation, Inc. +# Contributed by Phil Edwards <pme@gcc.gnu.org>. Simple two-state automaton +# inspired by Richard Henderson's gcc/mkmap-symver.awk. + +# 'file' is the name of the file on stdin +# 'title' is the text to print at the start of the list + +BEGIN { + state = "looking"; + entries = 0; + printf (" <li>%s\n", title); + printf (" <ul>\n"); +} + +# Searching for the little table of contents at the top. +state == "looking" && /^<h1>Contents/ { + state = "entries"; + next; +} + +# Ignore everything else up to that point. +state == "looking" { + next; +} + +# An entry in the table of contents. Pull that line apart. +state == "entries" && /<li>/ { + extract_info($0); + next; +} + +# End of the list. Don't bother reading the rest of the file. (It could +# also contain more <li>'s, so that would be incorrect as well as wasteful.) +state == "entries" && /^<\/ul>/ { + exit; +} + +END { + for (i = 0; i < entries; i++) + printf (" %s\n", entry[i]); + printf (" </ul>\n </li>\n\n"); +} + +function extract_info(line) { + # thistarget will be things like "#5" or "elsewhere.html" + match(line,"href=\".*\""); + thistarget = substr(line,RSTART+6,RLENGTH-7); + + # take apart the filename + split(file,X,"/"); + if (thistarget ~ /^#/) { + # local name, use directory and filename + target = file thistarget + } else { + # different file, only use directory + target = X[1] "/" thistarget + } + + # visible text + gsub("</a></li>","",line); + start = index(line,"\">") + 2; + thistext = substr(line,start); + + # Assemble and store the HTML for later output. + entry[entries++] = "<li><a href=\"" target "\">" thistext "</a></li>" +} + +# vim:sw=2 |