Subversion Repositories openrisc_me

 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"

[ ]>

      ISO C++

      library

  Here we will make an attempt at describing the non-Standard extensions to

  the library.  Some of these are from SGI's STL, some of these are GNU's,

  and some just seemed to appear on the doorstep.

Before you leap in and use any of these

extensions, be aware of two things:

     Non-Standard means exactly that.

       The behavior, and the very

       existence, of these extensions may change with little or no

       warning.  (Ideally, the really good ones will appear in the next

       revision of C++.)  Also, other platforms, other compilers, other

       versions of g++ or libstdc++ may not recognize these names, or

       treat them differently, or...

       You should know how to access these headers properly.

    Also known as concept checking.

   In 1999, SGI added concept checkers to their implementation

      of the STL:  code which checked the template parameters of

      instantiated pieces of the STL, in order to insure that the parameters

      being used met the requirements of the standard.  For example,

      the Standard requires that types passed as template parameters to

      vector be Assignable (which means what you think

      it means).  The checking was done during compilation, and none of

      the code was executed at runtime.

   Unfortunately, the size of the compiler files grew significantly

      as a result.  The checking code itself was cumbersome.  And bugs

      were found in it on more than one occasion.

   The primary author of the checking code, Jeremy Siek, had already

      started work on a replacement implementation.  The new code has been

      formally reviewed and accepted into

      the

      Boost libraries, and we are pleased to incorporate it into the

      GNU C++ library.

   The new version imposes a much smaller space overhead on the generated

      object file.  The checks are also cleaner and easier to read and

      understand.

   They are off by default for all versions of GCC from 3.0 to 3.4 (the

      latest release at the time of writing).

      They can be enabled at configure time with

      --enable-concept-checks.

      You can enable them on a per-translation-unit basis with

      #define _GLIBCXX_CONCEPT_CHECKS for GCC 3.4 and higher

      (or with #define _GLIBCPP_CONCEPT_CHECKS for versions

      3.1, 3.2 and 3.3).

   Please note that the upcoming C++ standard has first-class

   support for template parameter constraints based on concepts in the core

   language. This will obviate the need for the library-simulated concept

   checking described above.

            parse="xml" href="debug_mode.xml">

            parse="xml" href="parallel_mode.xml">

            parse="xml" href="profile_mode.xml">

              parse="xml" href="mt_allocator.xml">

              parse="xml" href="bitmap_allocator.xml">

      url="http://gcc.gnu.org/onlinedocs/libstdc++/ext/pb_ds/index.html">More details here.

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:

The old pre-standard bit_vector class is present for

   backwards compatibility.  It is simply a typedef for the

   vector<bool> specialization.

The bitset class has a number of extensions, described in the

   rest of this item.  First, we'll mention that this implementation of

   bitset<N> is specialized for cases where N number of

   bits will fit into a single word of storage.  If your choice of N is

   within that range (<=32 on i686-pc-linux-gnu, for example), then all

   of the operations will be faster.

There are

   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:

   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);

   Note that these may in fact be removed in the future, although we have

   no present plans to do so (and there doesn't seem to be any immediate

   reason to).

The semantics of member function operator[] are not specified

   in the C++ standard.  A long-standing defect report calls for sensible

   obvious semantics, which are already implemented here:  op[]

   on a const bitset returns a bool, and for a non-const bitset returns a

   reference (a nested type).  However, this implementation does

   no range-checking on the index argument, which is in keeping with other

   containers' op[] requirements.  The defect report's proposed

   resolution calls for range-checking to be done.  We'll just wait and see...

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 prev, respectively:

   size_t _Find_first() const;

   size_t _Find_next (size_t prev) const;

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

     The SGI hashing classes hash_set and

     hash_set have been deprecated by the

     unordered_set, unordered_multiset, unordered_map,

     unordered_multimap containers in TR1 and the upcoming C++0x, and

     may be removed in future releases.

   The SGI headers

     <hash_map>

     <hash_set>

     <rope>

     <slist>

     <rb_tree>

   are all here;

      <hash_map> and <hash_set>

      are deprecated but available as backwards-compatible extensions,

      as discussed further below.  <rope> is the

      SGI specialization for large strings ("rope,"

      "large strings," get it? Love that geeky humor.)

      <slist> is a singly-linked list, for when the

      doubly-linked list<> is too much space

      overhead, and <rb_tree> exposes the red-black

      tree classes used in the implementation of the standard maps and

      sets.

   Each of the associative containers map, multimap, set, and multiset

      have a counterpart which uses a

      hashing

      function to do the arranging, instead of a strict weak ordering

      function.  The classes take as one of their template parameters a

      function object that will return the hash value; by default, an

      instantiation of

      hash.

      You should specialize this functor for your class, or define your own,

      before trying to use one of the hashing classes.

   The hashing classes support all the usual associative container

      functions, as well as some extra constructors specifying the number

      of buckets, etc.

   Why would you want to use a hashing class instead of the

      normalimplementations?  Matt Austern writes:

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

    The <functional> header contains many additional functors

    and helper functions, extending section 20.3.  They are

    implemented in the file stl_function.h:

  identity_element for addition and multiplication. *

    The functor identity, whose operator()

      returns the argument unchanged. *

    Composition functors unary_function and

      binary_function, and their helpers compose1

      and compose2. *

  select1st and select2nd, to strip pairs. *

  project1st and project2nd. * 

  A set of functors/functions which always return the same result.  They

      are constant_void_fun, constant_binary_fun,

      constant_unary_fun, constant0,

      constant1, and constant2. * 

  The class subtractive_rng. * 

  mem_fun adaptor helpers mem_fun1 and

      mem_fun1_ref are provided for backwards compatibility. 

  20.4.1 can use several different allocators; they are described on the

   main extensions page.

  20.4.3 is extended with a special version of

  get_temporary_buffer taking a second argument.  The

  argument 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

get_temporary_buffer<int>(5);

you can also use

get_temporary_buffer(5, (int*)0);

  A class temporary_buffer is given in stl_tempbuf.h. *

  The specialized algorithms of section 20.4.4 are extended with

  uninitialized_copy_n. *

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

   void count (first, last, value, n);

25.2 (mutating algorithms) is extended with two families of signatures,

   random_sample and random_sample_n.

25.2.1 (copy) is extended with

   copy_n (_InputIter first, _Size count, _OutputIter result);

which copies the first 'count' elements at 'first' into 'result'.

25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper

   predicates.  Look in the doxygen-generated pages for notes on these.

    is_heap tests whether or not a range is a heap.

    is_sorted tests whether or not a range is sorted in

        nondescending order.

25.3.8 (lexicographical_compare) is extended with

   lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1,

                                 _InputIter2 first2, _InputIter2 last2)

which does... what?

26.4, the generalized numeric operations such as accumulate, are extended

   with the following functions:

   power (x, n);

   power (x, n, moniod_operation);

Returns, in FORTRAN syntax, "x ** n" where n>=0.  In the

   case of n == 0, returns the identity element for the

   monoid operation.  The two-argument signature uses multiplication (for

   a true "power" implementation), but addition is supported as well.

   The operation functor must be associative.

The iota function wins the award for Extension With the

   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.

   void iota(_ForwardIter first, _ForwardIter last, _Tp value);

24.3.2 describes struct iterator, which didn't exist in the

   original HP STL implementation (the language wasn't rich enough at the

   time).  For backwards compatibility, base classes are provided which

   declare the same nested typedefs:

    input_iterator

    output_iterator

    forward_iterator

    bidirectional_iterator

    random_access_iterator

24.3.4 describes iterator operation distance, 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

   modified, and the function returns nothing.

    Extensions allowing filebufs to be constructed from

    "C" types like  FILE*s and file descriptors.

   The v2 library included non-standard extensions to construct

      std::filebufs from C stdio types such as

      FILE*s and POSIX file descriptors.

      Today the recommended way to use stdio types with libstdc++

      IOStreams is via the stdio_filebuf class (see below),

      but earlier releases provided slightly different mechanisms.

     3.0.x filebufs have another ctor with this signature:

        basic_filebuf(__c_file_type*, ios_base::openmode, int_type);

         This comes in very handy in a number of places, such as

         attaching Unix sockets, pipes, and anything else which uses file

         descriptors, into the IOStream buffering classes.  The three

         arguments are as follows:

          __c_file_type*      F   

              // the __c_file_type typedef usually boils down to stdio's FILE

          ios_base::openmode  M   

              // same as all the other uses of openmode

          int_type            B   

              // buffer size, defaults to BUFSIZ if not specified

         For those wanting to use file descriptors instead of FILE*'s, I

         invite you to contemplate the mysteries of C's fdopen().

     In library snapshot 3.0.95 and later, filebufs bring

         back an old extension:  the fd() member function.  The

         integer returned from this function can be used for whatever file

         descriptors can be used for on your platform.  Naturally, the

         library cannot track what you do on your own with a file descriptor,

         so if you perform any I/O directly, don't expect the library to be

         aware of it.

     Beginning with 3.1, the extra filebuf constructor and

         the fd() function were removed from the standard

         filebuf.  Instead, <ext/stdio_filebuf.h> contains

         a derived class called

         __gnu_cxx::stdio_filebuf.

         This class can be constructed from a C FILE* or a file

         descriptor, and provides the fd() function.

   If you want to access a filebuf's file descriptor to

      implement file locking (e.g. using the fcntl() system

      call) then you might be interested in Henry Suter's RWLock class.

    Transforming C++ ABI identifiers (like RTTI symbols) into the

    original C++ source identifiers is called

    demangling.

    If you have read the 

    url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a01115.html">source

    documentation for namespace abi then you are

    aware of the cross-vendor C++ ABI in use by GCC.  One of the

    exposed functions is used for demangling,

    abi::__cxa_demangle.

    In programs like c++filt, the linker, and other tools

    have the ability to decode C++ ABI names, and now so can you.

    (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.)

    Probably the only times you'll be interested in demangling at runtime

    are when you're seeing typeid strings in RTTI, or when

    you're handling the runtime-support exception classes.  For example:

#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;

}

     This prints

      St13bad_exception       => std::bad_exception   : 0

      3barI5emptyLi17EE       => bar<empty, 17>       : 0

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

            parse="xml" href="concurrency_extensions.xml">