# Introduction

Introduction
ISO C++ library

## Status

### Implementation Status

### License

There are two licenses affecting GNU libstdc++: one for the code, and one for the documentation.

There is a license section in the FAQ regarding common questions. If you have more questions, ask the FSF or the gcc mailing list.

#### The Code: GPL

The source code is distributed under the GNU General Public License version 3, with the addition under section 7 of an exception described in the GCC Runtime Library Exception, version 3.1 as follows (or see the file COPYING.RUNTIME):

    GCC RUNTIME LIBRARY EXCEPTION

    Version 3.1, 31 March 2009

    Copyright (C) 2009 Free Software Foundation, Inc.

    Everyone is permitted to copy and distribute verbatim copies of this
    license document, but changing it is not allowed.

    This GCC Runtime Library Exception ("Exception") is an additional
    permission under section 7 of the GNU General Public License, version
    3 ("GPLv3"). It applies to a given file (the "Runtime Library") that
    bears a notice placed by the copyright holder of the file stating that
    the file is governed by GPLv3 along with this Exception.

    When you use GCC to compile a program, GCC may combine portions of
    certain GCC header files and runtime libraries with the compiled
    program. The purpose of this Exception is to allow compilation of
    non-GPL (including proprietary) programs to use, in this way, the
    header files and runtime libraries covered by this Exception.

    0. Definitions.

    A file is an "Independent Module" if it either requires the Runtime
    Library for execution after a Compilation Process, or makes use of an
    interface provided by the Runtime Library, but is not otherwise based
    on the Runtime Library.

    "GCC" means a version of the GNU Compiler Collection, with or without
    modifications, governed by version 3 (or a specified later version) of
    the GNU General Public License (GPL) with the option of using any
    subsequent versions published by the FSF.

    "GPL-compatible Software" is software whose conditions of propagation,
    modification and use would permit combination with GCC in accord with
    the license of GCC.

    "Target Code" refers to output from any compiler for a real or virtual
    target processor architecture, in executable form or suitable for
    input to an assembler, loader, linker and/or execution
    phase. Notwithstanding that, Target Code does not include data in any
    format that is used as a compiler intermediate representation, or used
    for producing a compiler intermediate representation.

    The "Compilation Process" transforms code entirely represented in
    non-intermediate languages designed for human-written code, and/or in
    Java Virtual Machine byte code, into Target Code. Thus, for example,
    use of source code generators and preprocessors need not be considered
    part of the Compilation Process, since the Compilation Process can be
    understood as starting with the output of the generators or
    preprocessors.

    A Compilation Process is "Eligible" if it is done using GCC, alone or
    with other GPL-compatible software, or if it is done without using any
    work based on GCC. For example, using non-GPL-compatible Software to
    optimize any GCC intermediate representations would not qualify as an
    Eligible Compilation Process.

    1. Grant of Additional Permission.

    You have permission to propagate a work of Target Code formed by
    combining the Runtime Library with Independent Modules, even if such
    propagation would otherwise violate the terms of GPLv3, provided that
    all Target Code was generated by Eligible Compilation Processes. You
    may then convey such a combination under terms of your choice,
    consistent with the licensing of the Independent Modules.

    2. No Weakening of GCC Copyleft.

    The availability of this Exception does not imply any general
    presumption that third-party software is unaffected by the copyleft
    requirements of the license of GCC.

Hopefully that text is self-explanatory. If it isn't, you need to speak to your lawyer, or the Free Software Foundation.

#### The Documentation: GPL, FDL

The documentation shipped with the library and made available over the web, excluding the pages generated from source comments, are copyrighted by the Free Software Foundation, and placed under the GNU Free Documentation License version 1.3. There are no Front-Cover Texts, no Back-Cover Texts, and no Invariant Sections.

For documentation generated by doxygen or other automated tools via processing source code comments and markup, the original source code license applies to the generated files. Thus, the doxygen documents are licensed GPL.

If you plan on making copies of the documentation, please let us know. We can probably offer suggestions.

### Bugs

#### Implementation Bugs

Information on known bugs, details on efforts to fix them, and fixed bugs are all available as part of the GCC bug tracking system, with the category set to `libstdc++`.

#### Standard Bugs

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.

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.

23: Num_get overflow result

  Implement the proposed resolution.

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.

130: Return type of container::erase(iterator) differs for associative containers

  Make member `erase` return iterator for `set`, `multiset`, `map`, `multimap`.

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 a helper for forward_iterator/output_iterator, fix the existing one for input_iterator/output_iterator to not 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`.

387: std::complex over-encapsulated

  Add the `real(T)` and `imag(T)` members; in C++11 mode, also adjust the existing `real()` and `imag()` members and free functions.

389: Const overload of valarray::operator[] returns by value

  Change it to return a `const T&`.

396: what are characters zero and one

  Implement the proposed resolution.

402: Wrong new expression in [some_]allocator::construct

  Replace "new" with "::new".

408: Is vector<reverse_iterator<char*> > forbidden?

  Tweak the debug-mode checks in _Safe_iterator.

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

438: Ambiguity in the "do the right thing" clause

  Implement the resolution, basically cast less.

445: iterator_traits::reference unspecified for some iterator categories

  Change `istreambuf_iterator::reference` in C++11 mode.

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

467: char_traits::lt(), compare(), and memcmp()

  Change `lt`.

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.

526: Is it undefined if a function in the standard changes in parameters?

  Use &value.

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.

539: partial_sum and adjacent_difference should mention requirements

  We were almost doing the right thing, just use std::move in adjacent_difference.

541: shared_ptr template assignment and void

  Add an auto_ptr<void> specialization.

543: valarray slice default constructor

  Follow the straightforward proposed resolution.

550: What should the return type of pow(float,int) be?

  In C++11 mode, remove the pow(float,int), etc., signatures.

586: string inserter not a formatted function

  Change it to be a formatted output function (i.e. catch exceptions).

596: 27.8.1.3 Table 112 omits "a+" and "a+b" modes

  Add the missing modes to fopen_mode.

630: arrays of valarray

  Implement the simple resolution.

660: Missing bitwise operations

  Add the missing operations.

691: const_local_iterator cbegin, cend missing from TR1

  In C++11 mode add cbegin(size_type) and cend(size_type) to the unordered containers.

693: std::bitset::all() missing

  Add it, consistently with the discussion.

695: ctype<char>::classic_table() not accessible

  Make the member functions table and classic_table public.

696: istream::operator>>(int&) broken

  Implement the straightforward resolution.

761: unordered_map needs an at() member function

  In C++11 mode, add at() and at() const.

775: Tuple indexing should be unsigned?

  Implement the int -> size_t replacements.

776: Undescribed assign function of std::array

  In C++11 mode, remove assign, add fill.

781: std::complex should add missing C99 functions

  In C++11 mode, add std::proj.

809: std::swap should be overloaded for array types

  Add the overload.

853: to_string needs updating with zero and one

  Update / add the signatures.

865: More algorithms that throw away information

  The traditional HP / SGI return type and value is blessed by the resolution of the DR.

1339: uninitialized_fill_n should return the end of its range

  Return the end of the filled range.

2021: Further incorrect uses of `result_of`

  Correctly decay types in signature of `std::async`.

2049: `is_destructible` underspecified

  Handle non-object types.

2056: future_errc enums start with value 0 (invalid value for broken_promise)

  Reorder enumerators.

2059: C++0x ambiguity problem with map::erase

  Add additional overloads.

2063: Contradictory requirements for string move assignment

  Respect propagation trait for move assignment.

2064: More noexcept issues in basic_string

  Add noexcept to the comparison operators.

2067: packaged_task should have deleted copy c'tor with const parameter

  Fix signatures.

2101: Some transformation types can produce impossible types

  Use the referenceable type concept.

2106: move_iterator wrapping iterators returning prvalues

  Change the `reference` type.

2108: No way to identify allocator types that always compare equal

  Define and use `is_always_equal` even for C++11.

2118: `unique_ptr` for array does not support cv qualification conversion of actual argument

  Adjust constraints to allow safe conversions.

2132: `std::function` ambiguity

  Constrain the constructor to only accept callable types.

2141: `common_type` trait produces reference types

  Use `decay` for the result type.

2144: Missing `noexcept` specification in `type_index`

  Add `noexcept`

2145: `error_category` default constructor

  Declare a public constexpr constructor.

2162: `allocator_traits::max_size` missing `noexcept`

  Add `noexcept`.

2187: `vector<bool>` is missing `emplace` and `emplace_back` member functions

  Add `emplace` and `emplace_back` member functions.

2196: Specification of `is_*[copy/move]_[constructible/assignable]` unclear for non-referencable types

  Use the referenceable type concept.

2313: `tuple_size` should always derive from `integral_constant<size_t, N>`

  Update definitions of the partial specializations for const and volatile types.

2329: `regex_match()/regex_search()` with `match_results` should forbid temporary strings

  Add deleted overloads for rvalue strings.

2332: `regex_iterator/regex_token_iterator` should forbid temporary regexes

  Add deleted constructors.

2399: `shared_ptr`'s constructor from `unique_ptr` should be constrained

  Constrain the constructor to require convertibility.

2400: `shared_ptr`'s `get_deleter()` should use `addressof()`

  Use `addressof`.

2401: `std::function` needs more `noexcept`

  Add `noexcept` to the assignment and comparisons.

2407: `packaged_task(allocator_arg_t, const Allocator&, F&&)` should neither be constrained nor `explicit`

  Remove `explicit` from the constructor.

2415: Inconsistency between `unique_ptr` and `shared_ptr`

  Create empty an `shared_ptr` from an empty `unique_ptr`.

2418: `apply` does not work with member pointers

  Use `mem_fn` for member pointers.

2440: `seed_seq::size()` should be `noexcept`

  Add `noexcept`.

2454: Add `raw_storage_iterator::base()` member

  Add the `base()` member function.

2455: Allocator default construction should be allowed to throw

  Make `noexcept` specifications conditional.

2459: `std::polar` should require a non-negative rho

  Add debug mode assertion.

2466: `allocator_traits::max_size()` default behavior is incorrect

  Divide by the object type.

## Setup

To transform libstdc++ sources into installed include files and properly built binaries useful for linking to other software is a multi-step process. Steps include getting the sources, configuring and building the sources, testing, and installation.

The general outline of commands is something like:

       get gcc sources
       extract into gccsrcdir
       mkdir gccbuilddir
       cd gccbuilddir
       gccsrcdir/configure --prefix=destdir --other-opts...
       make
       make check
       make install

Each step is described in more detail in the following sections.

### Make

If you have never done this before, you should read the basic GCC Installation Instructions first. Read all of them. Twice.

Then type: `make`, and congratulations, you've started to build.