From 222bb619fbdc3775767cde2d500c92d58ce1d499 Mon Sep 17 00:00:00 2001 From: Phil Edwards Date: Wed, 7 Feb 2001 00:03:21 +0000 Subject: [PATCH] configopts.html: Fix HTML markup. 2001-02-06 Phil Edwards * docs/html/configopts.html: Fix HTML markup. * docs/html/install.html: Bring up to date. * docs/html/17_intro/C++STYLE: Add global variable conventions. * docs/html/21_strings/howto.html: More notes. * docs/html/22_locale/howto.html: Fix HTML markup. * docs/html/27_io/howto.html: More notes. * docs/html/27_io/binary_iostreams_kanze.txt: New file. * docs/html/27_io/binary_iostreams_kuehl.txt: New file. From-SVN: r39503 --- libstdc++-v3/ChangeLog | 11 +++ libstdc++-v3/docs/html/17_intro/C++STYLE | 14 ++- libstdc++-v3/docs/html/21_strings/howto.html | 11 ++- libstdc++-v3/docs/html/22_locale/howto.html | 18 ++-- .../html/27_io/binary_iostreams_kanze.txt | 51 +++++++++++ .../html/27_io/binary_iostreams_kuehl.txt | 89 +++++++++++++++++++ libstdc++-v3/docs/html/27_io/howto.html | 38 ++++++-- libstdc++-v3/docs/html/configopts.html | 9 +- libstdc++-v3/docs/html/install.html | 67 ++++---------- 9 files changed, 233 insertions(+), 75 deletions(-) create mode 100644 libstdc++-v3/docs/html/27_io/binary_iostreams_kanze.txt create mode 100644 libstdc++-v3/docs/html/27_io/binary_iostreams_kuehl.txt diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index e050bfa6838..c8ad4a7b9f5 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,14 @@ +2001-02-06 Phil Edwards + + * docs/html/configopts.html: Fix HTML markup. + * docs/html/install.html: Bring up to date. + * docs/html/17_intro/C++STYLE: Add global variable conventions. + * docs/html/21_strings/howto.html: More notes. + * docs/html/22_locale/howto.html: Fix HTML markup. + * docs/html/27_io/howto.html: More notes. + * docs/html/27_io/binary_iostreams_kanze.txt: New file. + * docs/html/27_io/binary_iostreams_kuehl.txt: New file. + 2001-02-06 Jeffrey Oldham * src/misc-inst.cc (_S_pad_char): Modify declaration's parameters diff --git a/libstdc++-v3/docs/html/17_intro/C++STYLE b/libstdc++-v3/docs/html/17_intro/C++STYLE index 3d4ab171c3e..c162a1f6ad4 100644 --- a/libstdc++-v3/docs/html/17_intro/C++STYLE +++ b/libstdc++-v3/docs/html/17_intro/C++STYLE @@ -6,7 +6,7 @@ This library is written to appropriate C++ coding standards. As such, it is intended to precede the recommendations of the GNU Coding Standard, which can be referenced here: -http://www.gnu.ai.mit.edu/prep/standards_toc.html +http://www.gnu.org/prep/standards_toc.html ChangeLog entries for member functions should use the classname::member function name syntax as follows: @@ -27,7 +27,7 @@ Notable areas of divergence from what may be previous local practice char &c = *p; // wrong Reason: In C++, definitions are mixed with executable code. Here, - p is being initialized, not *p. This is near-universal + p is being initialized, not *p. This is near-universal practice among C++ programmers; it is normal for C hackers to switch spontaneously as they gain experience. @@ -184,6 +184,16 @@ Notable areas of divergence from what may be previous local practice 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 + as a character array with the appropriate alignment and then later + re-initialized to the correct value. + + This is due to startup issues on certain platforms, such as AIX. + For more explanation and examples, see src/globals.cc. All such + variables should be contained in that file, for simplicity. + The library currently has a mixture of GNU-C and modern C++ coding diff --git a/libstdc++-v3/docs/html/21_strings/howto.html b/libstdc++-v3/docs/html/21_strings/howto.html index 7318084f3ad..cdc83685965 100644 --- a/libstdc++-v3/docs/html/21_strings/howto.html +++ b/libstdc++-v3/docs/html/21_strings/howto.html @@ -8,7 +8,7 @@ libstdc++-v3 HOWTO: Chapter 21 - + @@ -236,6 +236,13 @@ with reading the new function names, this version is recommended as an example.

+

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

Return to top of page or to the FAQ.

@@ -324,7 +331,7 @@ Comments and suggestions are welcome, and may be sent to Phil Edwards or Gabriel Dos Reis. -
$Id: howto.html,v 1.7 2000/12/03 23:47:47 jsm28 Exp $ +
$Id: howto.html,v 1.1 2000/12/10 04:04:55 pme Exp $

diff --git a/libstdc++-v3/docs/html/22_locale/howto.html b/libstdc++-v3/docs/html/22_locale/howto.html index 6c76a5cef22..cbf1daf61d3 100644 --- a/libstdc++-v3/docs/html/22_locale/howto.html +++ b/libstdc++-v3/docs/html/22_locale/howto.html @@ -8,7 +8,7 @@ libstdc++-v3 HOWTO: Chapter 22 - + @@ -56,9 +56,9 @@

Nathan Myers on Locales

-

An article entitled "The Standard C++ Locale" was published in - Dr. Dobb's Journal and can be found - here +

An article entitled "The Standard C++ Locale" was + published in Dr. Dobb's Journal and can be found + here.

Return to top of page or to the FAQ. @@ -67,7 +67,7 @@

class locale

Notes made during the implementation of locales can be found - here. + here.

Return to top of page or to the FAQ. @@ -76,7 +76,7 @@

class codecvt

Notes made during the implementation of codecvt can be found - here. + here.

The following is the abstract from the implementation notes: @@ -104,7 +104,7 @@ functionality are given.

class ctype

Notes made during the implementation of ctype can be found - here. + here.

Return to top of page or to the FAQ. @@ -114,7 +114,7 @@ functionality are given.

Correct Transformations

A very common question on newsgroups and mailing lists is, "How - do I do <foo> to a character string?" where <foo> is + do I do <foo> to a character string?" where <foo> is a task such as changing all the letters to uppercase, to lowercase, testing for digits, etc. A skilled and conscientious programmer will follow the question with another, "And how do I make the @@ -227,7 +227,7 @@ functionality are given. Comments and suggestions are welcome, and may be sent to Phil Edwards or Gabriel Dos Reis. -
$Id: howto.html,v 1.8 2000/12/03 23:47:47 jsm28 Exp $ +
$Id: howto.html,v 1.1 2000/12/10 04:04:55 pme Exp $

diff --git a/libstdc++-v3/docs/html/27_io/binary_iostreams_kanze.txt b/libstdc++-v3/docs/html/27_io/binary_iostreams_kanze.txt new file mode 100644 index 00000000000..65d79c996c5 --- /dev/null +++ b/libstdc++-v3/docs/html/27_io/binary_iostreams_kanze.txt @@ -0,0 +1,51 @@ + +From: James Kanze +Newsgroups: comp.lang.c++.moderated +Subject: Re: binary iostreams ? +Date: 3 Feb 2001 14:28:19 -0500 +Message-ID: <86lmro86qp.fsf@alex.gabi-soft.de> + +"Plinio Conti" writes: + +|> Why std c++ library stream classes are only text-oriented? + +Because that is the only universally recognized format. + +|> I mean, if I want to write an int, a float, etc. AS IT IS I can't +|> use streams, because they write and read a human readable text +|> format of numbers. + +Correct. + +|> Does anyone know how to solve the problem? + +It depends on what you really want to do. If you are just dumping a +block of memory to disk, in order to free up memory, and will reread it +later in the same run of the same program, ostream::write and +istream::read are what you need. Note, however, that this ony works 1) +in the same run of the same program, and 2) for PODs without pointers. + +If you are writing something that will be read by another program, or a +later run of the same program, you'll have to define a specific format +to use, and implement streams to input and output that. If you are +writing something that will be read by an existing program, or be +transmitted over a network to another machine, you will have to find out +what protocol is expected, and adher to it. + +|> Any public library? + +Not that I know of. I think that there is a library somewhere that +outputs in format RPC, or maybe some Internet format. + +|> What do you think about this choice? + +What other choice is possible? It's not reasonable to ask the standard +to support all binary formats, and it's not reasonable for it to favor +any one of them. Given that, what else can you do. + +-- +James Kanze mailto:kanze@gabi-soft.de +Conseils en informatique orientée objet/ + Beratung in objektorientierter Datenverarbeitung +Ziegelhüttenweg 17a, 60598 Frankfurt, Germany Tel. +49(069)63198627 + diff --git a/libstdc++-v3/docs/html/27_io/binary_iostreams_kuehl.txt b/libstdc++-v3/docs/html/27_io/binary_iostreams_kuehl.txt new file mode 100644 index 00000000000..901701ff480 --- /dev/null +++ b/libstdc++-v3/docs/html/27_io/binary_iostreams_kuehl.txt @@ -0,0 +1,89 @@ + +From: kuehl@ramsen.informatik.uni-konstanz.de (Dietmar Kuehl) +Newsgroups: comp.std.c++ +Subject: Re: binary iostreams ? +Date: Sat, 3 Feb 2001 17:17:49 GMT +Message-ID: <95hctq$suu$2@news.BelWue.DE> + +Hi, +Plinio Conti (plinio.contiNO@SPAMMINGmclink.it) wrote: +: Why std c++ library stream classes are only text-oriented? + +There is only a text oriented front end to stream buffers because text +input and output does not vary between platforms. This is very +different for binary output. For example, binary output has to consider + +- word sizes: Is an 'int' two, four, or eight bytes long? The same + questions arise for all other built-in types. + +- what is the bit pattern of a value? I think that at least implicitly + in the standard a binary representation for integer types is required. + I don't think that it is required to use two's complement. In any + case, the floating point representations do differ, eg. in their + number of bytes used. + +- what "endianess" is to be used? + +Basically it is possible to decide a format for each of those. This, +however, implies inefficient implementations on platforms where the +format does not match the internal representation. + +What many people asking for binary I/O forget is that binary I/O also +requires some form of formatting! Assuming that just writing data and +then reading it in will work is asking for problems, eg. when the +compiler version changes and they decided to use a 32 bit integer +rather than a 16 bit integer: It is not even necessary to switch +platforms to run into problems! + +: I mean, if I want to write an int, a float, etc. AS IT IS I can't use +: streams, because they write and read a human readable text format of +: numbers. + +Which is for most I/O a reasonable approach. If it is not for you, you +might want to consider a data base: File I/O is not really useful as a +persistance mechanism. It is fine eg. for user interaction (text I/O), +logging (text I/O), cross platfrom program interaction (formatted I/O), +and data exchange (formatted I/O). In all these cases, the I/O is +formatted, although possible using a binary format. For persistance, +data bases are used. Depending on your needs, a relational or an object +oriented one may be better suited. + +That said, it is worth to mention that it is easy to create a hierarchy +similar to IOStreams built on top of stream buffers but doing binary +formatting. A somewhat aged example is found at +. +This uses XDR formatting of the binary data (well, if I remmeber +correctly, it is easy to plug in a different binary formatting). + +: Does anyone know how to solve the problem? + +Use a data base, text formatting, or binary formatting. With the +details you have given it is impossible to tell which of those is the +right approach because you haven't told *why* you want a binary format +and *what* you want to do. That basically means that you came up with +solution and you want us to confirm that it is the right one without +telling us what problem is solved! Until I have seen the problem I +doubt that binary I/O is the right approach... + +... and, BTW, using 'std::istream::read()' and 'std::ostream::write()' +is almost certainly the *wrong* approach! These functions are an +historical mistake which should have been corrected in the standard: +It is my understanding that these methods were present in the IOStream +version predating the rework from Jerry Schwartz and were left in to +be compatible with the earlier stuff although they were not necessary: +You could get binary I/O from the stream buffer level. The original +IOStream library (maybe you remember using ) did not have +stream buffers and thus basic support for binary I/O was also present +on the streams level. + +: What do you think about this choice? + +When I wrote the above paragraph about confirming your choice, I haven't +read this question! As I said above: You told us what solution you have +choosen without stating what problem is solved. We cannot determine +whether your choice is the right one. Actually, I'm pretty sure it is +the wrong one but without seen the details I can't be certain. +-- + +Phaidros eaSE - Easy Software Engineering: + diff --git a/libstdc++-v3/docs/html/27_io/howto.html b/libstdc++-v3/docs/html/27_io/howto.html index 1c47a2bbf1d..a6aa045781c 100644 --- a/libstdc++-v3/docs/html/27_io/howto.html +++ b/libstdc++-v3/docs/html/27_io/howto.html @@ -8,7 +8,7 @@ libstdc++-v3 HOWTO: Chapter 27 - + @@ -29,6 +29,7 @@
  • Iostreams class hierarchy diagram
  • What is this <sstream>/stringstreams thing?
  • Deriving a stream buffer +
  • More on binary I/O
    @@ -196,9 +197,9 @@

    Sorry. Them's the breaks.

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

    First, ios::binary has exactly one defined effect, no more and no less. Normal text mode has to be concerned with the newline @@ -224,7 +225,7 @@

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

    Notice how all the problems here are due to the inappropriate use of formatting functions and classes to perform something @@ -383,6 +384,31 @@ Try it yourself!

    +
    +

    More on binary I/O

    +

    Towards the beginning of February 2001, the subject of + "binary" I/O was brought up in a couple of places at the + same time. One notable place was Usenet, where James Kanze and + Dietmar Kühl separately posted articles on why attempting + generic binary I/O was not a good idea. (Here are copies of + Kanze's article and + Kühl's article.) +

    +

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

    +

    The entire Usenet thread is instructive, and took place under the + subject heading "binary iostreams" on both comp.std.c++ + and comp.lang.c++.moderated in parallel. Also in that thread, + Dietmar Kühl mentioned that he had written a pair of stream + classes that would read and write XDR, which is a good step towards + a portable binary format. +

    + @@ -391,7 +417,7 @@ Comments and suggestions are welcome, and may be sent to Phil Edwards or Gabriel Dos Reis. -
    $Id: howto.html,v 1.1 2000/12/10 04:04:56 pme Exp $ +
    $Id: howto.html,v 1.2 2001/01/23 17:02:27 pme Exp $

    diff --git a/libstdc++-v3/docs/html/configopts.html b/libstdc++-v3/docs/html/configopts.html index cf9ded1e690..78572aa902e 100644 --- a/libstdc++-v3/docs/html/configopts.html +++ b/libstdc++-v3/docs/html/configopts.html @@ -7,7 +7,7 @@ libstdc++-v3 configure options - + @@ -80,8 +80,8 @@ options model based on langinfo/iconv (from glibc, 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. + The default is 'generic'.

    --enable-long-long @@ -137,7 +137,6 @@ options --with-gxx-include-dir=_dirname_ during configuration.

    -
    --with-gxx-include-dir=<include-files dir>

    Adds support for named libstdc++ include directory. For instance, the following puts all the libstdc++ headers into a directory @@ -193,7 +192,7 @@ options

    -$Id: configopts.html,v 1.4 2001/01/21 09:36:09 pme Exp $ +$Id: configopts.html,v 1.5 2001/01/30 09:18:50 bkoz Exp $

    diff --git a/libstdc++-v3/docs/html/install.html b/libstdc++-v3/docs/html/install.html index be50063b8a1..fcc0c0dcdce 100644 --- a/libstdc++-v3/docs/html/install.html +++ b/libstdc++-v3/docs/html/install.html @@ -7,7 +7,7 @@ libstdc++-v3 Installation Instructions - + @@ -58,7 +58,8 @@

    If you don't have bash, and want to run 'make check' to test your build, you'll need to get bash 2.x. Also recommended is GNU Make, since it is the only 'make' that will parse these - makefiles correctly. + makefiles correctly. We are moving to DejaGNU, so you'll + probably want to get that.

    As of June 19, 2000, libstdc++ attempts to use tricky and @@ -151,10 +152,11 @@

    ...with a gcc-2.9[67] snapshot

    Unpack the gccsrcdir and go into that directory. For instance, gcc-2.95.2 is a valid gccsrcdir. - Once in gccsrcdir, you'll need to rename the libstdc++-v3 - directory which comes with that snapshot: + Once in gccsrcdir, you'll need to rename or delete + the libstdc++-v3 directory which comes with that snapshot: 

    -   mv libstdc++-v3 libstdc++-v3-previous
    + mv libstdc++-v3 libstdc++-v3-previous [OR] + rm -r libstdc++-v3

    Next, unpack the libstdc++-v3 library tarball into the gccsrcdir directory; it will create a @@ -173,9 +175,11 @@

    ...with CVS gcc

    Check out or download the gcc sources: the resulting source directory is gccsrcdir. Once in gccsrcdir, - you'll need to rename the libstdc++-v3 directory which comes - with that snapshot: - mv libstdc++-v3 libstdc++-v3-previous + you'll need to rename or delete the libstdc++-v3 directory + which comes with that snapshot: + 

    +   mv libstdc++-v3 libstdc++-v3-previous  [OR]
+   rm -r libstdc++-v3

    Next, unpack the libstdc++-v3 library tarball into this gccsrcdir directory; it will create a @@ -208,13 +212,7 @@ 

        cd gccbuilddir
-   gccsrcdir/configure --prefix=destdir --enable-libstdcxx-v3
    -

    - -

    Adding --enable-libstdcxx-v3 automatically selects libstdc++-v3 - as the C++ library to be used alongside the C++ compiler being built, - and also enables -fhonor-std by default. This option is not available - with gcc-2.95.2. + gccsrcdir/configure --prefix=destdir --other-opts...

    @@ -239,10 +237,6 @@ This will configure and build the C++ library in the gccbuilddir/cpu-vendor-OS/libstdc++ directory.

    -

    If the build fails with a "warning: can't inline call" - message when compiling stringMAIN.cc, see the - resolution at the end of this document. -

    If you are rebuilding from a previous build [attempt], some information is kept in a cache file. This is stored in gccbuilddir/cpu-vendor-OS/ if you are building with @@ -258,7 +252,7 @@ or 

        make install-gcc
-   make install-target-libstdc++-rule
    + make install-target-libstdc++-v3

    @@ -271,7 +265,7 @@ include/g++-v3/ bits/ ext/ - cpu-vendor-OS/include/g++-v3/ + CPU-vendor-OS/include/g++-v3/ bits/ ext/

    @@ -326,35 +320,6 @@

    -
    -

    warning: can't inline call to...

    -

    When building the .8 snapshot with g++ 2.95.2, compilation may halt - with this warning message. The "problem" is the -Werror - flag being passed to the compiler, which says to treat warnings as - errors. (This plus a high warning level makes us track down bugs - quickly.) The compiler can't inline a certain call, prints - a warning, and dies. -

    -

    The workaround is to edit either libsrcdir/src/Makefile.in - (before configuring) or bld-libstdc++/src/Makefile - (after configuring). There's one line that reads - 

    -   WERROR = -Werror
    - Delete the flag itself, so that the line reads - 
    -   WERROR =
    - Then the compiler will still print a warning, but it won't die. -

    -

    For the curious, this "problem" is actually a symptom - of something else. The compiler in CVS could inline more than what - 2.95.2 does, and the libstdc++ changes were made with that - compiler. One of the libstdc++ maintainers explains this -here. -

    -

    This has been patched in current CVS sources. -

    - -