cpp/standard library: Difference between revisions

{{cpp/navbar}}

The [[cpp/memory|memory management library]] provides components for memory management, including [[cpp/memory#Smart pointers|smart pointers]]{{rev inl|since=c++11| and [[cpp/memory/scoped_allocator_adaptor|scoped allocator]]}}.

The [[cpp/meta|metaprogramming library]] describes facilities for use in [[cpp/language/templates|templates]] and during constant evaluation, including [[cpp/meta#Type traits|type traits]]{{rev inl|since=c++14|, [[cpp/utility/integer_sequence|integer sequence]],}} and [[cpp/numeric/ratio|rational arithmetic]].

The [[cpp/utility#General-purpose utilities|general utilities library]] includes components used by other library elements, such as a [[cpp/memory#Allocators|predefined storage allocator]] for dynamic storage management, and components used as infrastructure in C++ programs, such as{{rev inl|since=c++11| [[cpp/utility/tuple|tuples]] and}} [[cpp/utility/functional|function wrappers]].

The [[cpp/string|strings library]] provides support for manipulating text represented as homogeneous sequences of following types: {{tt|char}}{{rev inl|since=c++20|, {{tt|char8_t}}}}{{rev inl|since=c++11|, {{tt|char16_t}}, {{tt|char32_t}}}}, {{tt|wchar_t}}, and any other character-like types.

The [[cpp/container|containers]], [[cpp/iterator|iterators]]{{rev inl|since=c++20|, [[cpp/ranges|ranges]]}}, and [[cpp/algorithm|algorithms]] libraries provide a C++ program with access to a subset of the most widely used algorithms and data structures.

The [[cpp/numeric|numerics library]] provides [[cpp/numeric#Numeric algorithms|numeric algorithms]] and [[cpp/numeric/complex|complex number]] components that extend support for numeric processing. The [[cpp/numeric/valarray|valarray]] component provides support for n-at-a-time processing, potentially implemented as parallel operations on platforms that support such processing.{{rev inl|since=c++11| The [[cpp/numeric/random|random number component]] provides facilities for generating pseudo-random numbers.}}

 

The[[cpp/io|input/output library]] provides the [[cpp/io#Stream-based I/O|iostream components]] that are the primary mechanism for C++ program input and output. They can be used with other elements of the library, particularly strings, locales, and iterators.

All library entities except {{c|operator new}} and {{c|operator delete}} are defined within the namespace {{c|std}} or [[cpp/language/namespace|namespaces]] nested within namespace {{c|std}} (except the entities for the C standard library facilities, see below).{{rev inl|since=c++11| It is unspecified whether names declared in a specific namespace are declared directly in that namespace or in an [[cpp/language/namespace#Inline namespaces|inline namespace]] inside that namespace.}}

Each element of the C++ standard library is declared or defined (as appropriate) in a ''header'' . A header is not necessarily a source file, nor are the sequences delimited by < and > in header names necessarily valid source file names.

The C++ standard library provides the ''C++ library headers'' and additional C++ headers for C library facilities (see '[[cpp/headers|headers]]' page for descriptions):

|-style="text-align:center; font-size:16px; line-height:16px;"

|{{ltt|cpp/header/algorithm|<algorithm>}}

|{{ltt|cpp/header/iomanip|<iomanip>}}

|{{ltt|cpp/header/list|<list>}}

|{{ltt|cpp/header/queue|<queue>}}

|{{ltt|cpp/header/string|<string>}}

|{{ltt|cpp/header/bitset|<bitset>}}

|{{ltt|cpp/header/ios|<ios>}}

|{{ltt|cpp/header/locale|<locale>}}

|{{ltt|cpp/header/set|<set>}}

|{{ltt|cpp/header/strstream|<strstream>}}

|{{ltt|cpp/header/complex|<complex>}}

|{{ltt|cpp/header/iosfwd|<iosfwd>}}

|{{ltt|cpp/header/map|<map>}}

|{{ltt|cpp/header/sstream|<sstream>}}

|{{ltt|cpp/header/typeinfo|<typeinfo>}}

|{{ltt|cpp/header/deque|<deque>}}

|{{ltt|cpp/header/iostream|<iostream>}}

|{{ltt|cpp/header/memory|<memory>}}

|{{ltt|cpp/header/stack|<stack>}}

|{{ltt|cpp/header/utility|<utility>}}

|{{ltt|cpp/header/exception|<exception>}}

|{{ltt|cpp/header/istream|<istream>}}

|{{ltt|cpp/header/new|<new>}}

|{{ltt|cpp/header/stdexcept|<stdexcept>}}

|{{ltt|cpp/header/valarray|<valarray>}}

|{{ltt|cpp/header/fstream|<fstream>}}

|{{ltt|cpp/header/iterator|<iterator>}}

|{{ltt|cpp/header/numeric|<numeric>}}

|{{ltt|cpp/header/streambuf|<streambuf>}}

|{{ltt|cpp/header/vector|<vector>}}

|{{ltt|cpp/header/functional|<functional>}}

|{{ltt|cpp/header/limits|<limits>}}

|{{ltt|cpp/header/ostream|<ostream>}}

|{{ltt|cpp/header/array|<array>}}

|{{ltt|cpp/header/condition_variable|<condition_variable>}}

|{{ltt|cpp/header/mutex|<mutex>}}

|{{ltt|cpp/header/scoped_allocator|<scoped_allocator>}}

|{{ltt|cpp/header/type_traits|<type_traits>}}

|{{ltt|cpp/header/atomic|<atomic>}}

|{{ltt|cpp/header/forward_list|<forward_list>}}

|{{ltt|cpp/header/random|<random>}}

|{{ltt|cpp/header/system_error|<system_error>}}

|{{ltt|cpp/header/typeindex|<typeindex>}}

|{{ltt|cpp/header/chrono|<chrono>}}

|{{ltt|cpp/header/future|<future>}}

|{{ltt|cpp/header/ratio|<ratio>}}

|{{ltt|cpp/header/thread|<thread>}}

|{{ltt|cpp/header/any|<any>}}

|{{ltt|cpp/header/filesystem|<filesystem>}}

|{{ltt|cpp/header/optional|<optional>}}

|{{ltt|cpp/header/string_view|<string_view>}}

|{{ltt|cpp/header/variant|<variant>}}

|{{ltt|cpp/header/execution|<execution>}}

|{{ltt|cpp/header/memory_resource|<memory_resource>}}

|{{ltt|cpp/header/shared_mutex|<shared_mutex>}}

|{{ltt|cpp/header/barrier|<barrier>}}

|{{ltt|cpp/header/compare|<compare>}}

|{{ltt|cpp/header/format|<format>}}

|{{ltt|cpp/header/ranges|<ranges>}}

|{{ltt|cpp/header/span|&lt;span>}}

|{{ltt|cpp/header/bit|<bit>}}

|{{ltt|cpp/header/concepts|<concepts>}}

|{{ltt|cpp/header/latch|<latch>}}

|{{ltt|cpp/header/semaphore|<semaphore>}}

|{{ltt|cpp/header/stop_token|<stop_token>}}

|{{ltt|cpp/header/charconv|<charconv>}}

|{{ltt|cpp/header/coroutine|<coroutine>}}

|{{ltt|cpp/header/numbers|<numbers>}}

|{{ltt|cpp/header/source_location|<source_location>}}

|{{ltt|cpp/header/syncstream|<syncstream>}}

|{{ltt|cpp/header/expected|<expected>}}

|{{ltt|cpp/header/flat_set|<flat_set>}}

|{{ltt|cpp/header/mdspan|<mdspan>}}

|{{ltt|cpp/header/spanstream|<spanstream>}}

|{{ltt|cpp/header/stdfloat|<stdfloat>}}

|{{ltt|cpp/header/flat_map|<flat_map>}}

|{{ltt|cpp/header/generator|<generator>}}

|{{ltt|cpp/header/print|<print>}}

|{{ltt|cpp/header/stacktrace|<stacktrace>}}

! colspan="4" | C++ headers for C library facilities

|{{ltt|cpp/header/cassert|<cassert>}}

|{{ltt|cpp/header/clocale|<clocale>}}

|{{ltt|cpp/header/cstdarg|<cstdarg>}}

|{{ltt|cpp/header/cstring|<cstring>}}

|{{ltt|cpp/header/cctype|<cctype>}}

|{{ltt|cpp/header/cmath|<cmath>}}

|{{ltt|cpp/header/cstddef|<cstddef>}}

|{{ltt|cpp/header/ctime|<ctime>}}

|{{ltt|cpp/header/cerrno|<cerrno>}}

|{{ltt|cpp/header/csetjmp|<csetjmp>}}

|{{ltt|cpp/header/cstdio|<cstdio>}}

|{{ltt|cpp/header/cwchar|<cwchar>}}

|{{ltt|cpp/header/cfloat|<cfloat>}}

|{{ltt|cpp/header/csignal|<csignal>}}

|{{ltt|cpp/header/cstdlib|<cstdlib>}}

|{{ltt|cpp/header/cwctype|<cwctype>}}

|{{ltt|cpp/header/climits|<climits>}}

!colspan="4"|Headers removed in C++20

|{{ltt|cpp/header/ciso646|<ciso646>}}

|

|

|

|-style="text-align:center"

!colspan="4"|Headers added in C++11

|{{ltt|cpp/header/cfenv|<cfenv>}}

|{{ltt|cpp/header/cuchar|<cuchar>}}

|-style="text-align:center"

!colspan="4"|Headers added in C++11, deprecated in C++17, and removed in C++20

|{{ltt|cpp/header/ccomplex|<ccomplex>}}

|{{ltt|cpp/header/cstdalign|<cstdalign>}}

|{{ltt|cpp/header/cstdbool|<cstdbool>}}

|{{ltt|cpp/header/ctgmath|<ctgmath>}}

In some cases, the signatures specified in standard C++ may be different from the signatures in the C standard library, and additional overloads may be declared, but the behavior and the preconditions are the same unless otherwise stated.

Except otherwise noted, the contents of each header {{c|cXXXX}} is the same as that of the corresponding header {{c|XXXX.h}} as specified in the [[c/header|C standard library]]. In the C++ standard library, however, the declarations (except for names which are defined as macros in C) are within namespace scope of the namespace {{c|std}}. It is unspecified whether these names (including any overloads added) are first declared within the global namespace scope and are then injected into namespace {{c|std}} by explicit [[cpp/language/namespace#Using-declarations|using-declarations]].

Names which are defined as macros in C ({{ltt|cpp/error/assert|assert}}, {{ltt|cpp/types/offsetof|offsetof}}, {{ltt|cpp/utility/program/setjmp|setjmp}}, {{ltt|cpp/utility/variadic/va_arg|va_arg}}, {{ltt|cpp/utility/variadic/va_end|va_end}} and {{ltt|cpp/utility/variadic/va_start|va_start}}) must be defined as macros in the C++ standard library, even if C grants license for implementation as functions.

|{{tt|abort_handler_s}}

|{{tt|mbstowcs_s}}

|{{tt|strncat_s}}

|{{tt|vswscanf_s}}

|{{tt|asctime_s}}

|{{tt|memcpy_s}}

|{{tt|strncpy_s}}

|{{tt|vwprintf_s}}

|{{tt|bsearch_s}}

|{{tt|memmove_s}}

|{{tt|strtok_s}}

|{{tt|vwscanf_s}}

|{{tt|constraint_handler_t}}

|{{tt|memset_s}}

|{{tt|swprintf_s}}

|{{tt|wcrtomb_s}}

|{{tt|ctime_s}}

|{{tt|printf_s}}

|{{tt|swscanf_s}}

|{{tt|wcscat_s}}

|{{tt|errno_t}}

|{{tt|qsort_s}}

|{{tt|tmpfile_s}}

|{{tt|wcscpy_s}}

|{{tt|fopen_s}}

|{{tt|RSIZE_MAX}}

|{{tt|TMP_MAX_S}}

|{{tt|wcsncat_s}}

|{{tt|fprintf_s}}

|{{tt|rsize_t}}

|{{tt|tmpnam_s}}

|{{tt|wcsncpy_s}}

|{{tt|freopen_s}}

|{{tt|scanf_s}}

|{{tt|vfprintf_s}}

|{{tt|wcsnlen_s}}

|{{tt|fscanf_s}}

|{{tt|set_constraint_handler_s}}

|{{tt|vfscanf_s}}

|{{tt|wcsrtombs_s}}

|{{tt|fwprintf_s}}

|{{tt|snprintf_s}}

|{{tt|vfwprintf_s}}

|{{tt|wcstok_s}}

|{{tt|fwscanf_s}}

|{{tt|snwprintf_s}}

|{{tt|vfwscanf_s}}

|{{tt|wcstombs_s}}

|{{tt|gets_s}}

|{{tt|sscanf_s}}

|{{tt|vscanf_s}}

|{{tt|wmemcpy_s}}

|{{tt|gmtime_s}}

|{{tt|mbstowcs_s}}

|{{tt|strncat_s}}

|{{tt|vswscanf_s}}

|{{tt|abort_handler_s}}

|{{tt|strcat_s}}

|{{tt|vsnprintf_s}}

|{{tt|wmemmove_s}}

|{{tt|ignore_handler_s}}

|{{tt|strcpy_s}}

|{{tt|vsnwprintf_s}}

|{{tt|wprintf_s}}

|{{tt|localtime_s}}

|{{tt|strerrorlen_s}}

|{{tt|vsprintf_s}}

|{{tt|wscanf_s}}

|{{tt|L_tmpnam_s}}

|{{tt|strerror_s}}

|{{tt|vsscanf_s}}

|{{tt|mbsrtowcs_s}}

|{{tt|strlen_s}}

|{{tt|vswprintf_s}}

A translation unit may include library headers in any order. Each may be included more than once, with no effect different from being included exactly once, except that the effect of including either {{ltt|cpp/header/cassert|<cassert>}} or {{ltt|cpp/header/cassert|<assert.h>}} depends each time on the lexically current definition of {{c|NDEBUG}}.

In [[cpp/language/modules|module units]], headers can only be included in [[cpp/language/modules#Global module fragment|global module fragments]].

 

{{rrev|since=c++20|

The [[#Headers|C++ library headers]], or, for a freestanding implementation, the subset of such headers that are provided by the implementation, are collectively known as the ''importable C++ library headers'' .

 

{{rrev|since=c++23|

The C++ standard library provides the following ''C++ library modules'' :

* The [[cpp/language/modules#Module declarations|named module]] {{c|std}} exports declarations in namespace {{tt|std}} that are provided by the importable C++ library headers and the [[#Headers|C++ headers for C library facilities]]. It additionally exports declarations in the global namespace for the storage [[cpp/memory/new/operator new|allocation]] and [[cpp/memory/new/operator delete|deallocation]] functions that are provided by {{ltt|cpp/header/new|<new>}}.

* The named module {{c|std.compat}} exports the same declarations as the named module {{c|std}}, and additionally exports declarations in the global namespace corresponding to the declarations in namespace {{tt|std}} that are provided by the C++ headers for C library facilities.

Entities in the C++ standard library have [[cpp/language/storage duration#external linkage|external linkage]]. Unless otherwise specified, objects and functions have the default {{c|extern "C++"}} [[cpp/language/language linkage|linkage]].

Whether a name from the C standard library declared with external linkage has {{c|extern "C"}} or {{c|extern "C++"}} linkage is implementation-defined. The C++ standard recommends using {{c|extern "C++"}} in this case.

A C++ header must provide [[cpp/language/declarations|declarations]] and [[cpp/language/definition|definitions]] that appear in

Unless otherwise specified, all [[cpp/preprocessor/replace#Object-like macros|object-like macros]] defined by the C standard library that expand to integral [[cpp/language/constant expression|constant expressions]] can be used in [[cpp/preprocessor/conditional|{{tt|#if}}]] preprocessing directives.

Non-member function signatures are never declared with additional [[cpp/language/default arguments|default arguments]].

Unless otherwise specified, calls made by functions in the standard library to non-operator, non-member functions do not use functions from another [[cpp/language/namespace|namespace]] which are found through [[cpp/language/adl|argument-dependent name lookup]].

Standard library function signatures can only be declared as {{c|constexpr}} if they are required to be [[cpp/language/constexpr|constexpr]] (libstdc++ cmath [https://gcc.gnu.org/bugzilla/show_bug.cgi?id=102916 is notably non-conforming] here). If a header provides any non-defining declarations of constexpr functions or constructors, the corresponding definitions should also be provided within that header.

* A C++ standard library function cannot access objects indirectly accessible via its arguments or via elements of its [[cpp/container|container]] arguments except by invoking functions required by its specification on those container elements.

* An operation on [[cpp/iterator|iterators]] obtained by calling a standard library container or string member function can access, but not modify, the underlying container.

* the base class must be [[cpp/language/derived class#Virtual base classes|virtual]] if it is specified as {{c|virtual}},

* the base class cannot be virtual if it is not specified as {{c|virtual}}, and

Unless otherwise specified, all types specified in the C++ standard library are non-[[cpp/language/final|final]] types.

Functions from the C standard library can only throw exceptions when such a function calls a program-supplied function that throws an exception ({{ltt|cpp/algorithm/qsort|qsort()}} and {{ltt|cpp/algorithm/bsearch|bsearch()}} meet this condition).

If a function in the C++ standard library report errors via a {{lc|std::error_code}} object, that object's {{ltt|cpp/error/error_code/category|category()}} member must return {{lc|std::system_category()}} for errors originating from the operating system, or a reference to an implementation-defined {{lc|std::error_category}} object for errors originating elsewhere. The possible values of {{ltt|cpp/error/error_code/value|value()}} for each of these error categories should be defined.

It is unspecified whether any member or non-member functions in the C++ standard library are defined as [[cpp/language/inline|inline]].

For a non-[[cpp/language/virtual|virtual]] C++ standard library member function, a different set of member function signatures can be declared, provided that any call to that member function that would select an overload from the given set of declarations behaves as if that overload was selected. This allows, for instance: