diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 602ebb1b6d5..aff975de1fc 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,9 @@ +2002-03-04 Craig Rodrigues + + * docs/html/17_intro/porting-howto.xml: Refer to + http://www.oasis-open.org for docbookx.dtd. + * docs/html/17_intro/porting-howto.html: Regenerated. + 2002-03-03 Phil Edwards PR libstdc++/3955 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 @@ Libstdc++-porting-howto - + -
+

Libstdc++-porting-howto

@@ -84,9 +84,7 @@
-

-Abstract -

+

Abstract

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 @@

1. Namespace std::
-
1.1.1. Using namespace - composition if the project uses a separate +
1.1.1. Using namespace + composition if the project uses a separate namespace
1.1.2. Defining an empty namespace std @@ -118,8 +116,8 @@
2. there is no ios::nocreate/ios::noreplace in ISO 14882
-
3. stream::attach(int - fd) is not in the standard any more +
3. stream::attach(int + fd) is not in the standard any more
4. The new headers
@@ -127,16 +125,16 @@
4.4.1. New headers replacing C-headers
4.4.2. - <fstream> does - not define std::cout, - std::cin etc. + <fstream> does + not define std::cout, + std::cin etc.
5. Iterators
6. - Libc-macros (i.e. isspace from - <cctype>) + Libc-macros (i.e. isspace from + <cctype>)
7. State of streams
@@ -161,29 +159,25 @@ libstdc++-implementations".

-

-1. Namespace std:: -

+

+Namespace std::

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: -

    -

  • -wrap your code in namespace std { +

      +

    • wrap your code in namespace std { ... } => This is not an option because only symbols from the standard c++-library are defined in namespace std::.

      • -

    • -put a kind of - using-declaration in your source (either +

    • put a kind of + using-declaration in your source (either using namespace std; or i.e. using std::string;) => works well for source-files, but cannot be used in header-files.

      • -

    • -use a fully qualified name for +

    • use a fully qualified name for each libstdc++-symbol (i.e. std::string, std::cout) => can always be used

      • @@ -210,17 +204,16 @@ that cannot ignore std::.

      -

      -1.1.1. Using namespace - composition if the project uses a separate - namespace -

      +

      +Using namespace + composition if the project uses a separate + namespace

      Gtk-- defines most of its classes in namespace Gtk::. Thus, it was possible to adapt Gtk-- to namespace std:: by using a C++-feature called - namespace composition. This is what happens if - you put a using-declaration into a + namespace composition. This is what happens if + you put a using-declaration into a namespace-definition: the imported symbol(s) gets imported into the currently active namespace(s). For example: 

      @@ -245,9 +238,8 @@
      -

      -1.1.2. Defining an empty namespace std -

      +

      +Defining an empty namespace std

      By defining an (empty) namespace std:: before using it, you avoid getting errors on systems where no part of the @@ -259,18 +251,16 @@

      -

      -1.1.3. Avoid to use fully qualified names - (i.e. std::string) -

      +

      +Avoid to use fully qualified names + (i.e. std::string)

      If some compilers complain about using std::string;, and if the "hack" for gtk-- mentioned above does not work, then I see two solutions: -

        +

        • - Define std:: as a macro if the compiler doesn't know about std::. 

          @@ -282,7 +272,6 @@
 	      gnu.gcc.help)

        • - 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 @@

        -

        -1.1.4. How some open-source-projects deal - with this -

        +

        +How some open-source-projects deal + with this

        This information was gathered around May 2000. It may not be correct by the time you read this.

        -

        -Table 1. Namespace std:: in Open-Source programs -

        +

        Table 1. Namespace std:: in Open-Source programs

        @@ -338,9 +324,7 @@
        -

        -Table 2. Notations for categories -

        +

        Table 2. Notations for categories

        @@ -368,15 +352,16 @@

        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 section on the gtkmm-hack). + (except for Gtk--: see the section on the gtkmm-hack).

        -

        -2. there is no ios::nocreate/ios::noreplace - in ISO 14882 -

        +

        +there is no ios::nocreate/ios::noreplace + in ISO 14882

        I have seen ios::nocreate being used for input-streams, most probably because the author thought it would be @@ -394,10 +379,9 @@

        -

        -3. stream::attach(int - fd) is not in the standard any more -

        +

        +stream::attach(int + fd) is not in the standard any more

        Phil Edwards <pedwards@disaster.jaj.com> writes: It was considered and rejected. Not all environments use file @@ -406,16 +390,14 @@

        When using libstdc++-v3, you can use -

        -

        -

        +      
        
+
         	  #include <fstream>
 	
        
 
        
 	    basic_filebuf<...>::basic_filebuf<...>
 	    
 	  (file, mode, size);
        __c_file_type* file;
        ios_base::open_mode mode;
        int size;
        
-
        
 
        
       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 @@
       std::streambuf (or
       std::basic_streambuf<..>) 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
+      fdstream example 
+      by Nicolai Josuttis.
        -

        -4. The new headers -

        +

        +The new headers

        All new headers can be seen in this source-code. @@ -443,9 +426,8 @@ a warning that you are using deprecated headers.

        -

        -4.4.1. New headers replacing C-headers -

        +

        +New headers replacing C-headers

        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 @@

        -

        -4.4.2. +

        + <fstream> does not define std::cout, - std::cin etc. -

        + std::cin etc.

        In earlier versions of the standard, <fstream.h>, @@ -494,42 +475,38 @@

        -

        -5. Iterators -

        +

        +Iterators

        The following are not proper uses of iterators, but may be working fixes for existing uses of iterators. -

          -

        • -you cannot do +

            +

          • you cannot do ostream::operator<<(iterator) to print the address of the iterator => use operator<< &*iterator instead ?

            • -

          • -you cannot clear an iterator's reference +

          • you cannot clear an iterator's reference (iterator = 0) => use iterator = iterator_type(); ?

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

        -

        -6. +

        + Libc-macros (i.e. isspace from - <cctype>) -

        + <cctype>)

        Glibc 2.0.x and 2.1.x define the <ctype.h> -functionality as macros (isspace, isalpha etc.). Libstdc++-v3 - "shadows" these macros as described in the section about + "shadows" these macros as described in the section about c-headers.

        @@ -577,18 +554,17 @@ The solution to this problem was posted to the libstdc++-v3 mailing-list: Benjamin Kosnik <bkoz@redhat.com> 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".

        -

        -7. State of streams -

        +

        +State of streams

        At least some older implementations don't have std::ios_base, so you should use @@ -598,9 +574,8 @@

        -

        -8. vector::at is missing (i.e. gcc 2.95.x) -

        +

        +vector::at is missing (i.e. gcc 2.95.x)

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

        @@ -630,9 +605,8 @@
        -

        -9. Using std::char_traits<char>::eof() -

        +

        +Using std::char_traits<char>::eof()

         	#ifdef HAVE_CHAR_TRAITS
@@ -644,9 +618,8 @@
        -

        -10. Using string::clear()/string::erase() -

        +

        +Using string::clear()/string::erase()

        There are two functions for deleting the contents of a string: clear and erase (the latter @@ -671,19 +644,17 @@

        -

        -11. GNU Extensions ostream::form and istream::scan -

        +

        +GNU Extensions ostream::form and istream::scan

        These are not supported any more - use - + stringstreams instead.

        -

        -12. Using stringstreams -

        +

        +Using stringstreams

        Libstdc++-v3 provides the new i/ostringstream-classes, (<sstream>), but for compatibility @@ -696,22 +667,18 @@ #include <strstream> #endif -

          -

        • - strstream is considered to be +

            +

          • strstream is considered to be deprecated

            • -

          • - strstream is limited to +

          • strstream is limited to char

            • -

          • - with ostringstream you don't +

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

            • -

          • - istringstream can be re-filled +

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

          @@ -789,9 +756,8 @@

        -

        -13. About... -

        +

        +About...

        Please send any experience, additions, corrections or questions to fnatter@gmx.net 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 @@ + "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd">