libstdc++-v3 HOWTO: Extensions
Author: pme@gcc.gnu.org (Phil Edwards)
Description: Notes for the libstdc++ extensions.
Keywords: HOWTO, libstdc++, GCC, g++, libg++, STL

# Extensions

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 these, be aware of two things:

1. 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...
2. You should know how to access these headers properly.

# Contents

- Ropes and trees and hashes, oh my!
- Added members and types
- `__mt_alloc`
- Compile-time checks
- LWG Issues
- Demangling

## Ropes and trees and hashes, oh my!

The SGI headers

         <bvector>
         <hash_map>
         <hash_set>
         <rope>
         <slist>
         <tree>

are all here; `<bvector>` 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). `<hash_map>` and `<hash_set>` are discussed further below. `<rope>` is the SGI specialization for large strings ("rope," "large strings," get it? love those SGI folks). `<slist>` is a singly-linked list, for when the doubly-linked `list<>` is too much space overhead, and `<tree>` exposes the red-black tree classes used in the implementation of the standard maps and sets.

Okay, about those hashing classes... I'm going to foist most of the work off onto SGI's own site.

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 "normal" implementations? 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.

(Side note: for those of you wondering, "Why wasn't a hash table included in the Standard in the first #!$@ place?" 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.)

Return to top of page or to the FAQ.

## Added members and types

Some of the classes in the Standard Library have additional publicly-available members, and some classes are themselves not in the standard. Of those, some are intended purely for the implementors, for example, additional typedefs. Those won't be described here (or anywhere else).

- The extensions added by SGI are so numerous that they have their own page. Since the SGI STL is no longer actively maintained, we will try and keep this code working ourselves.
- Extensions allowing `filebuf`s to be constructed from stdio types are described in the chapter 27 notes.

Return to top of page or to the FAQ.

## Compile-time checks

Currently libstdc++-v3 uses the concept checkers from the Boost library to perform optional compile-time checking of template instantiations of the standard containers. They are described in the linked-to page.

Return to top of page or to the FAQ.

## LWG Issues

Everybody's got issues. Even the C++ Standard Library.

The Library Working Group, or LWG, is the ISO subcommittee responsible for making changes to the library. They periodically publish an Issues List containing problems and possible solutions. As they reach a consensus on proposed solutions, we often incorporate the solution into libstdc++-v3.

Here are the issues which have resulted in code changes to the library. The links are to the specific defect reports from a partial copy of the Issues List. You can read the full version online at the ISO C++ Committee homepage, linked to on the GCC "Readings" page. If you spend a lot of time reading the issues, we recommend downloading the ZIP file and reading them locally.

(NB: partial copy means that not all links within the lwg-*.html pages will work. Specifically, links to defect reports that have not been accorded full DR status will probably break. Rather than trying to mirror the entire issues list on our overworked web server, we recommend you go to the LWG homepage instead.)

If a DR is not listed here, we may simply not have gotten to it yet; feel free to submit a patch. Search the include/bits and src directories for appearances of _GLIBCXX_RESOLVE_LIB_DEFECTS for examples of style. Note that we usually do not make changes to the code until an issue has reached DR status.

5: string::compare specification questionable
  This should be two overloaded functions rather than a single function.
17: Bad bool parsing
  Apparently extracting Boolean values was messed up...
19: "Noconv" definition too vague
  If `codecvt::do_in` returns `noconv` there are no changes to the values in `[to, to_limit)`.
22: Member open vs flags
  Re-opening a file stream does not clear the state flags.
25: String operator<< uses width() value wrong
  Padding issues.
48: Use of non-existent exception constructor
  An instance of `ios_base::failure` is constructed instead.
49: Underspecification of ios_base::sync_with_stdio
  The return type is the previous state of synchronization.
50: Copy constructor and assignment operator of ios_base
  These members functions are declared `private` and are thus inaccessible. Specifying the correct semantics of "copying stream state" was deemed too complicated.
60: What is a formatted input function?
  This DR made many widespread changes to `basic_istream` and `basic_ostream` all of which have been implemented.
63: Exception-handling policy for unformatted output
  Make the policy consistent with that of formatted input, unformatted input, and formatted output.
68: Extractors for char* should store null at end
  And they do now. An editing glitch in the last item in the list of [27.6.1.2.3]/7.
74: Garbled text for codecvt::do_max_length
  The text of the standard was gibberish. Typos gone rampant.
75: Contradiction in codecvt::length's argument types
  Change the first parameter to `stateT&` and implement the new effects paragraph.
83: string::npos vs. string::max_size()
  Safety checks on the size of the string should test against `max_size()` rather than `npos`.
90: Incorrect description of operator>> for strings
  The effect contain `isspace(c,getloc())` which must be replaced by `isspace(c,is.getloc())`.
91: Description of operator>> and getline() for string<> might cause endless loop
  They behave as a formatted input function and as an unformatted input function, respectively (except that `getline` is not required to set `gcount`).
103: set::iterator is required to be modifiable, but this allows modification of keys.
  For associative containers where the value type is the same as the key type, both `iterator` and `const_iterator` are constant iterators.
109: Missing binders for non-const sequence elements
  The `binder1st` and `binder2nd` didn't have an `operator()` taking a non-const parameter.
110: istreambuf_iterator::equal not const
  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.
117: basic_ostream uses nonexistent num_put member functions
  `num_put::put()` was overloaded on the wrong types.
118: basic_istream uses nonexistent num_get member functions
  Same as 117, but for `num_get::get()`.
129: Need error indication from seekp() and seekg()
  These functions set `failbit` on error now.
136: seekp, seekg setting wrong streams?
  `seekp` should only set the output stream, and `seekg` should only set the input stream.
167: Improper use of traits_type::length()
  `op<<` with a `const char*` was calculating an incorrect number of characters to write.
169: Bad efficiency of overflow() mandated
  Grow efficiently the internal array object.
171: Strange seekpos() semantics due to joint position
  Quite complex to summarize...
181: make_pair() unintended behavior
  This function used to take its arguments as reference-to-const, now it copies them (pass by value).
195: Should basic_istream::sentry's constructor ever set eofbit?
  Yes, it can, specifically if EOF is reached while skipping whitespace.
211: operator>>(istream&, string&) doesn't set failbit
  If nothing is extracted into the string, `op>>` now sets `failbit` (which can cause an exception, etc., etc.).
214: set::find() missing const overload
  Both `set` and `multiset` were missing overloaded find, lower_bound, upper_bound, and equal_range functions for const instances.
231: Precision in iostream?
  For conversion from a floating-point type, `str.precision()` is specified in the conversion specification.
233: Insertion hints in associative containers
  Implement N1780, first check before then check after, insert as close to hint as possible.
235: No specification of default ctor for reverse_iterator
  The declaration of `reverse_iterator` lists a default constructor. However, no specification is given what this constructor should do.
241: Does unique_copy() require CopyConstructible and Assignable?
  Add an helper for forward_iterator/output_iterator, fix the existing one for input_iterator/output_iterator not to rely on Assignability.
243: get and getline when sentry reports failure
  Store a null character only if the character array has a non-zero size.
251: basic_stringbuf missing allocator_type
  This nested typedef was originally not specified.
253: valarray helper functions are almost entirely useless
  Make the copy constructor and copy-assignment operator declarations public in gslice_array, indirect_array, mask_array, slice_array; provide definitions.
265: std::pair::pair() effects overly restrictive
  The default ctor would build its members from copies of temporaries; now it simply uses their respective default ctors.
266: bad_exception::~bad_exception() missing Effects clause
  The `bad_`* classes no longer have destructors (they are trivial), since no description of them was ever given.
271: basic_iostream missing typedefs
  The typedefs it inherits from its base classes can't be used, since (for example) `basic_iostream<T>::traits_type` is ambiguous.
275: Wrong type in num_get::get() overloads
  Similar to 118.
280: Comparison of reverse_iterator to const reverse_iterator
  Add global functions with two template parameters. (NB: not added for now a templated assignment operator)
292: Effects of a.copyfmt (a)
  If `(this == &rhs)` do nothing.
300: List::merge() specification incomplete
  If `(this == &x)` do nothing.
303: Bitset input operator underspecified
  Basically, compare the input character to `is.widen(0)` and `is.widen(1)`.
305: Default behavior of codecvt<wchar_t, char, mbstate_t>::length()
  Do not specify what `codecvt<wchar_t, char, mbstate_t>::do_length` must return.
328: Bad sprintf format modifier in money_put<>::do_put()
  Change the format string to "%.0Lf".
365: Lack of const-qualification in clause 27
  Add const overloads of `is_open`.
389: Const overload of valarray::operator[] returns by value
  Change it to return a `const T&`.
402: Wrong new expression in [some_]allocator::construct
  Replace "new" with "::new".
409: Closing an fstream should clear the error state
  Have `open` clear the error flags.
431: Swapping containers with unequal allocators
  Implement Option 3, as per N1599.
432: 432. stringbuf::overflow() makes only one write position available
  Implement the resolution, beyond DR 169.
434: bitset::to_string() hard to use
  Add three overloads, taking fewer template arguments.
453: basic_stringbuf::seekoff need not always fail for an empty stream
  Don't fail if the next pointer is null and newoff is zero.
455: cerr::tie() and wcerr::tie() are overspecified
  Initialize cerr tied to cout and wcerr tied to wcout.
464: Suggestion for new member functions in standard containers
  Add `data()` to `std::vector` and `at(const key_type&)` to `std::map`.
508: Bad parameters for ranlux64_base_01
  Fix the parameters.
512: Seeding subtract_with_carry_01 from a single unsigned long
  Construct a `linear_congruential` engine and seed with it.
538: 241 again: Does unique_copy() require CopyConstructible and Assignable?
  In case of input_iterator/output_iterator rely on Assignability of input_iterator' value_type.
586: string inserter not a formatted function
  Change it to be a formatted output function (i.e. catch exceptions).

Return to top of page or to the FAQ.

See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to the libstdc++ mailing list.