Libstdc++-porting-howto

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

Because there are many compilers which still use an implementation that does not have the standard C++-library in namespace std::, some care is required to support these as well.

Namespace back-portability-issues are generally not a problem with g++, because versions of g++ that do not have libstdc++ in std:: use -fno-honor-std (ignore std::, :: = std::) by default. That is, the responsibility for enabling or disabling std:: is on the user; the maintainer does not have to care about it. This probably applies to some other compilers as well.

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

		  namespace Gtk {
		  using std::string;
		  class Window { ... }
		  }
		

		  namespace std { }
		  using namespace std;
		

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

I have seen ios::nocreate being used for input-streams, most probably because the authors thought it would be more correct to specify nocreate "explicitly". So you can simply leave it out for input-streams.

For output streams, "nocreate" is probably the default, unless you specify std::ios::trunc ? To be safe, you can open the file for reading, check if it has been opened, and then decide whether you want to create/replace or not. To my knowledge, even older implementations support app, ate and trunc (except for app ?).

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

When using libstdc++-v3, you can use

		  #include <fstream>
		

4. The new headers

All new headers can be seen in this source-code.

I think it is a problem for libstdc++-v3 to add links or wrappers for the old headers, because the implementation has changed, and the header name-changes indicate this. It might be preferable to use the new headers and tell users of old compilers that they should create links (which is what they will have to do sometime anyway).

5. Iterators

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

6. Libc-macros (i.e. isspace from <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 .

Older implementations of libstdc++ (g++-2 for egcs 1.x and g++-3 for gcc 2.95.2), however, keep these functions as macros, and so it is not back-portable to use fully qualified names. For example:

		#include <cctype>
		int main() { std::isspace('X'); }
	  

		std:: (__ctype_b[(int) ( ( 'X' ) )] & (unsigned short int)
		_ISspace )  ;
	  

One solution I can think of is to test for -v3 using autoconf-macros, and define macros for each of the C-functions (maybe that is possible with one "wrapper" macro as well ?).

Another solution which would fix g++ is to tell the user to modify a header-file so that g++-2 (egcs 1.x) and g++-3 (gcc 2.95.2) define a macro which tells <ctype.h> to define functions instead of macros:

		// This keeps isalnum, et al from being propagated as macros.
		#if __linux__
		#define __NO_CTYPE 1
		#endif

		[ now include <ctype.h> ]
	  

Another problem arises if you put a using namespace std; declaration at the top, and include <ctype.h>. This will result in ambiguities between the definitions in the global namespace (<ctype.h>) and the definitions in namespace std:: (<cctype>).

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.... "

7. State of streams

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

8. vector::at is missing (i.e. gcc 2.95.2)

For my use, I added it to prefix/include/g++-3/stl_vector.h:

  reference operator[](size_type __n) { return *(begin() + __n); }
  reference at(size_type __n) {
    if (begin() + __n >= end())
      throw out_of_range("vector::at");
    return *(begin() + __n);
  }
  const_reference operator[](size_type __n) const { return *(begin() + __n); }
  const_reference at(size_type __n) const {
    if (begin() + __n >= end())
      throw out_of_range("vector::at");
    return *(begin() + __n);
  }
	  

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

		#ifdef HAVE_CHAR_TRAITS
		#define CPP_EOF std::char_traits<char>::eof()
		#else
		#define CPP_EOF EOF
		#endif
	  

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

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

		void 
		clear() { _M_mutate(0, this->size(), 0); }
	  

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

11. Using stringstream's

Libstdc++-v3 includes the new i/ostringstream-classes, (<sstream>), but with older implementations you still have to use i/ostrstream (<strstream>):

		#ifdef HAVE_SSTREAM
		#include <sstream>
		#else
		#include <strstream>
		#endif
	  

You can then use output-stringstreams like this:

		#ifdef HAVE_SSTREAM
		std::ostringstream oss;
		#else
		std::ostrstream oss;
		#endif
		oss << "Name=" << m_name << ", number=" << m_number << std::endl;
		...
		#ifndef HAVE_SSTREAM
		oss << std::ends; // terminate the char*-string
		#endif
		// str() returns char* for ostrstream and a string for ostringstream
		// this also causes ostrstream to think that the buffer's memory
		// is yours
		m_label.set_text(oss.str());
		#ifndef HAVE_SSTREAM
		// let the ostrstream take care of freeing the memory
		oss.freeze(false);
		#endif
	  

Input-stringstreams can be used similarly:

		std::string input;
		...
		#ifdef HAVE_SSTREAM
		std::istringstream iss(input);
		#else
		std::istrstream iss(input.c_str());
		#endif
		int i;
		iss >> i; 
	  

		std::istringstream iss(numerator);
		iss >> m_num;
		// this is not possible with istrstream
		iss.clear();
		iss.str(denominator);
		iss >> m_den;
	  

		template <class X>
		void fromString(const string& input, X& any)
		{
		#ifdef HAVE_SSTREAM
		std::istringstream iss(input);
		#else
		std::istrstream iss(input.c_str());
		#endif
		X temp;
		iss >> temp;
		if (iss.fail())
		   throw runtime_error(..)
		any = temp;
		}
	  

I have read the Josuttis book on Standard C++, so some information comes from there. Additionally, there is information in "info iostream", which covers the old implementation that gcc 2.95.2 uses.

12. About...

Please send any experience, additions, corrections or questions to fnatter@gmx.net or for discussion to the libstdc++-v3-mailing-list.