Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/utility"

From cppreference.com
< cpp
 
m
 
(131 intermediate revisions by 26 users not shown)
Line 1: Line 1:
 
{{title|Utility library}}
 
{{title|Utility library}}
−
{{cpp/utility/sidebar}}
+
{{cpp/utility/navbar}}
−
==Language support==
+
  
−
===Basic types and their properties===
+
C++ includes a variety of utility libraries that provide functionality ranging from [[cpp/utility/bitset|bit-counting]] to [[cpp/utility/functional/bind|partial function application]]. These libraries can be broadly divided into two groups:
  
−
{{small|See [[cpp/language/types | this ]] for additional information about fundamental types implicitly defined by the language}}
+
* language support libraries, and
 +
* general-purpose libraries.
  
−
Various headers define some {{rl|types | basic types}} that are used throughout the library.
+
==Language support==
−
 
+
Language support libraries provide classes and functions that interact closely with language features and support common language idioms.
−
To enhance portability, several {{rl|types/integer | fixed width integer types}} are defined {{mark c++0x feature}}
+
−
 
+
−
The {{rlt|types/numeric_limits | numeric_limits}} class template provides an interface to query properties of all fundamental types.
+
−
 
+
−
Lot of {{rl|types/climits | macros}} define properties of the fundamental types {{small|this is deprecated in favour of {{rlt | types/numeric_limits | numeric_limits}} interface}}
+
−
 
+
−
===Dynamic memory allocation===
+
−
 
+
−
Several [[cpp/memory/ | memory utilities]] provide both low and high level support for managing memory dynamically.
+
−
 
+
−
===Error handling===
+
−
 
+
−
Several [[cpp/error/ | error handling utilities]] provide both low and high level error handling primitives.
+
  
−
===Runtime type identification===
+
===[[cpp/types|Type support]]===
 +
Basic types (e.g. {{lc|std::size_t}}, {{lc|std::nullptr_t}}), RTTI (e.g. {{lc|std::type_info}})
  
−
Language builtin [[cpp/language/typeid | typeid]] operator allows to query object type on either on runtime or compile-time depending on the information available to the compiler. Several [[cpp/utility/rtti | support classes]] are defined, which provide convenient interface with the feature.
+
===[[cpp/meta|Metaprogramming]]===
 +
Type traits (e.g. {{lc|std::is_integral}}, {{lc|std::rank}}), compile-time constants (e.g. {{lc|std::integer_sequence}}, {{lc|std::ratio}})
  
−
===Initializer lists===
+
===Constant evaluation context===
 +
{{dsc begin}}
 +
{{dsc header|type_traits}}
 +
{{dsc inc|cpp/types/dsc is_constant_evaluated}}
 +
{{dsc inc|cpp/types/dsc is_within_lifetime}}
 +
{{dsc end}}
  
−
Class template {{rlt|initializer_list}} allows to use [[cpp/language/initializer_list | initializer list]] syntax to initialize non Plain-old-data types {{mark c++0x}}
+
===[[cpp/utility/feature_test|Implementation properties]]===
 +
{{rrev|since=c++20|
 +
The header {{header|version}} supplies implementation-dependent information about the C++ standard library (such as the version number and release date). It also defines the [[cpp/utility/feature test|library feature-test macros]].
 +
}}
  
−
==General utilities==
+
===[[cpp/utility/program|Program utilities]]===
 +
Termination (e.g. {{lc|std::abort}}, {{lc|std::atexit}}), environment (e.g. {{lc|std::system}}), signals (e.g. {{lc|std::raise}})
  
−
===Program utilities===
+
===[[cpp/memory|Dynamic memory management]]===
 +
Smart pointers (e.g. {{lc|std::shared_ptr}}), allocators (e.g. {{lc|std::allocator}} or {{lc|std::pmr::memory_resource}}), C-style memory management (e.g. {{lc|std::malloc}})
  
−
Several [[cpp/utility/program | program utilities]] are defined, which implement program termination and communication with the environment primitives, as well as signal handling and non-local jumps.
+
===[[cpp/error|Error handling]]===
 +
Exceptions (e.g. {{lc|std::exception}}, {{lc|std::terminate}}), assertions (e.g. {{lc|assert}})
  
−
===Compile time rational arithmetic===
+
===[[cpp/utility/source_location|Source code information capture]]===
 +
{{dsc begin}}
 +
{{dsc header|source_location}}
 +
{{dsc inc|cpp/utility/dsc source_location}}
 +
{{dsc end}}
  
−
Several {{rl|ratio | classes and functions}} provide compile time rational arithmetic support. {{mark c++0x}}
+
===[[cpp/utility/initializer_list|Initializer lists]]===
 +
{{dsc begin}}
 +
{{dsc header|initializer_list}}
 +
{{dsc inc|cpp/utility/dsc initializer_list}}
 +
{{dsc end}}
  
−
===Date and time===
+
===Three-way comparison===
 +
{{dsc begin}}
 +
{{dsc header|compare}}
 +
{{dsc inc|cpp/utility/compare/dsc three_way_comparable}}
 +
{{dsc inc|cpp/utility/compare/dsc partial_ordering}}
 +
{{dsc inc|cpp/utility/compare/dsc weak_ordering}}
 +
{{dsc inc|cpp/utility/compare/dsc strong_ordering}}
 +
{{dsc inc|cpp/utility/compare/dsc named_comparison_functions}}
 +
{{dsc inc|cpp/utility/compare/dsc compare_three_way}}
 +
{{dsc inc|cpp/utility/compare/dsc compare_three_way_result}}
 +
{{dsc inc|cpp/utility/compare/dsc common_comparison_category}}
 +
{{dsc inc|cpp/utility/compare/dsc strong_order}}
 +
{{dsc inc|cpp/utility/compare/dsc weak_order}}
 +
{{dsc inc|cpp/utility/compare/dsc partial_order}}
 +
{{dsc inc|cpp/utility/compare/dsc compare_strong_order_fallback}}
 +
{{dsc inc|cpp/utility/compare/dsc compare_weak_order_fallback}}
 +
{{dsc inc|cpp/utility/compare/dsc compare_partial_order_fallback}}
 +
{{dsc end}}
  
−
Several [[cpp/chrono | classes and functions]] provide minimal time and date support.
+
===[[cpp/coroutine|Coroutine support]]===
 +
{{rrev|since=c++20|
 +
Types for coroutine support, e.g. {{lc|std::coroutine_traits}}, {{lc|std::coroutine_handle}}.
 +
}}
  
−
===Bitset===
+
===[[cpp/utility/variadic|Variadic functions]]===
 +
Support for functions that take an arbitrary number of parameters (via e.g. {{lc|va_start}}, {{lc|va_arg}}, {{lc|va_end}}).
  
−
Class {{rlt|bitset}} implements constant length bit array
+
==General-purpose utilities==
 +
===Swap===
 +
{{dsc begin}}
 +
{{dsc header|utility}}
 +
{{dsc inc|cpp/algorithm/dsc swap}}
 +
{{dsc inc|cpp/utility/dsc exchange}}
 +
{{dsc header|concepts}}
 +
{{dsc inc|cpp/utility/ranges/dsc swap}}
 +
{{dsc end}}
  
−
===Function objects===
+
===Type operations===
 +
{{dsc begin}}
 +
{{dsc header|utility}}
 +
{{dsc inc|cpp/utility/dsc forward}}
 +
{{dsc inc|cpp/utility/dsc forward_like}}
 +
{{dsc inc|cpp/utility/dsc move}}
 +
{{dsc inc|cpp/utility/dsc move_if_noexcept}}
 +
{{dsc inc|cpp/utility/dsc as_const}}
 +
{{dsc inc|cpp/utility/dsc declval}}
 +
{{dsc inc|cpp/utility/dsc to_underlying}}
 +
{{dsc end}}
  
−
Several useful {{rl|functional | function objects}} performing simple operations are provided
+
===Integer comparison functions===
 +
{{dsc begin}}
 +
{{dsc header|utility}}
 +
{{dsc inc|cpp/utility/dsc intcmp}}
 +
{{dsc inc|cpp/utility/dsc in_range}}
 +
{{dsc end}}
  
−
===Type traits===
+
===Relational operators===
 +
{{dsc begin}}
 +
{{dsc header|utility}}
 +
{{dsc namespace|std::rel_ops}}
 +
{{dsc inc|cpp/utility/rel_ops/dsc operator_cmp}}
 +
{{dsc end}}
  
−
Several specially crafted {{rl|type_traits | class templates}} implement compile-time interface to query and set various properties of types.
+
===Construction tags===
 +
{{dsc begin}}
 +
{{dsc header|utility}}
 +
{{dsc inc|cpp/utility/dsc piecewise_construct}}
 +
{{dsc inc|cpp/utility/dsc in_place}}
 +
{{dsc inc|cpp/utility/dsc nontype}}
 +
{{dsc end}}
  
−
===Pairs and tuples===
+
===[[cpp/utility/pair|Pairs]] and [[cpp/utility/tuple|tuples]]===
 +
{{dsc begin}}
 +
{{dsc header|utility}}
 +
{{dsc inc|cpp/utility/dsc pair}}
 +
{{dsc header|tuple}}
 +
{{dsc inc|cpp/utility/dsc tuple}}
 +
{{dsc inc|cpp/utility/dsc apply}}
 +
{{dsc inc|cpp/utility/dsc make_from_tuple}}
 +
{{dsc h2|[[cpp/utility/tuple/tuple-like|Tuple protocol]]}}
 +
{{dsc header|tuple}}
 +
{{dsc header|utility}}
 +
{{dsc header|array}}
 +
{{dsc header|ranges}}
 +
{{dsc header|complex}}
 +
{{dsc inc|cpp/utility/dsc tuple_size}}
 +
{{dsc inc|cpp/utility/dsc tuple_element}}
 +
{{dsc end}}
  
−
Class template {{rlt|tuple}} implements fixed size container, which holds elements of possibly different types {{mark c++0x}}
+
===Sum types and type erased wrappers===
 +
{{dsc begin}}
 +
{{dsc header|optional}}
 +
{{dsc inc|cpp/utility/dsc optional}}
 +
{{dsc sep}}
 +
{{dsc header|expected}}
 +
{{dsc inc|cpp/utility/dsc expected}}
 +
{{dsc sep}}
 +
{{dsc header|variant}}
 +
{{dsc inc|cpp/utility/dsc variant}}
 +
{{dsc sep}}
 +
{{dsc header|any}}
 +
{{dsc inc|cpp/utility/dsc any}}
 +
{{dsc end}}
  
−
Class template {{rlt|pair}} implements binary tuple, i.e. a pair of values.
+
===[[cpp/utility/bitset|Bitset]]===
 +
{{dsc begin}}
 +
{{dsc header|bitset}}
 +
{{dsc inc|cpp/utility/dsc bitset}}
 +
{{dsc end}}
  
−
===Swap, forward and move===
+
===[[cpp/utility/functional|Function objects]]===
 +
Partial function application (e.g. {{lc|std::bind}}) and related utilities: utilities for binding such as {{lc|std::ref}}  and {{lc|std::placeholders}}, polymorphic function wrappers: {{lc|std::function}}, predefined functors (e.g. {{lc|std::plus}}, {{lc|std::equal_to}}), pointer-to-member to function converters {{lc|std::mem_fn}}.
  
−
{{dcl list begin}}
+
===[[cpp/utility/hash|Hash support]]===
−
{{dcl list item | {{member | swap}} | {{todo}}}}
+
{{dsc begin}}
−
{{dcl list item | {{member | forward}} | {{todo}}}}
+
{{dsc header|functional}}
−
{{dcl list item | {{member | move}} | {{todo}}}}
+
{{dsc inc|cpp/utility/dsc hash}}
−
{{dcl list item | {{member | move_if_noexcept}} | {{todo}}}}
+
{{dsc end}}
−
{{dcl list end}}
+
  
−
===Operators===
+
===[[cpp/chrono|Date and time]]===
 +
Time tracking (e.g. {{lc|std::chrono::time_point}}, {{lc|std::chrono::duration}}), C-style date and time (e.g. {{lc|std::time}}, {{lc|std::clock}})
  
−
{{tt|rel_ops}}
+
===Primitive string conversions===
 +
In addition to sophisticated locale-dependent parsers and formatters provided by the [[cpp/io|C++ I/O]] library, the [[cpp/io/c|C I/O]] library, [[cpp/string/basic_string#Numeric conversions|C++ string converters]], and [[cpp/string/byte#Conversions to numeric formats|C string converters]], the header {{header|charconv}} provides light-weight, locale-independent, non-allocating, non-throwing parsers and formatters for arithmetic types.
 +
{{dsc begin}}
 +
{{dsc header|charconv}}
 +
{{dsc inc|cpp/utility/dsc to_chars}}
 +
{{dsc inc|cpp/utility/dsc to_chars_result}}
 +
{{dsc inc|cpp/utility/dsc from_chars}}
 +
{{dsc inc|cpp/utility/dsc from_chars_result}}
 +
{{dsc inc|cpp/utility/dsc chars_format}}
 +
{{dsc end}}
  
−
{{todo}}
+
===[[cpp/utility/format|Formatting library]]===
 +
Facilities for type-safe string formatting.
 +
{{dsc begin}}
 +
{{dsc header|format}}
 +
{{dsc inc|cpp/utility/format/dsc format}}
 +
{{dsc inc|cpp/utility/format/dsc format_to}}
 +
{{dsc inc|cpp/utility/format/dsc format_to_n}}
 +
{{dsc inc|cpp/utility/format/dsc formatted_size}}
 +
{{dsc inc|cpp/utility/format/dsc vformat}}
 +
{{dsc inc|cpp/utility/format/dsc vformat_to}}
 +
{{dsc inc|cpp/utility/format/dsc formatter}}
 +
{{dsc inc|cpp/utility/format/dsc format_error}}
 +
{{dsc end}}
  
−
==Old==
+
===See also===
 +
{{dsc begin}}
 +
{{dsc see c|c/utility|Utility library|nomono=true}}
 +
{{dsc end}}
  
−
{{dcl list begin}}
+
{{langlinks|ar|cs|de|es|fr|it|ja|ko|pl|pt|ru|tr|zh}}
−
{{dcl list item | {{member|pair}} |definition of a pair of values}}
+
−
{{dcl list item | {{member|make_pair}} | create a pair}}
+
−
{{dcl list end}}
+

Latest revision as of 01:42, 14 November 2024

 
C++
 
Utilities library
General utilities
Relational operators (deprecated in C++20)
 

C++ includes a variety of utility libraries that provide functionality ranging from bit-counting to partial function application. These libraries can be broadly divided into two groups:

  • language support libraries, and
  • general-purpose libraries.

Contents

[edit] Language support

Language support libraries provide classes and functions that interact closely with language features and support common language idioms.

[edit] Type support

Basic types (e.g. std::size_t, std::nullptr_t), RTTI (e.g. std::type_info)

[edit] Metaprogramming

Type traits (e.g. std::is_integral, std::rank), compile-time constants (e.g. std::integer_sequence, std::ratio)

[edit] Constant evaluation context

Defined in header <type_traits>
(C++20)
 detects whether the call occurs within a constant-evaluated context
(function) [edit]
(C++26)
 checks whether a pointer is within the object's lifetime at compile time
(function) [edit]

[edit] Implementation properties

The header <version> supplies implementation-dependent information about the C++ standard library (such as the version number and release date). It also defines the library feature-test macros.

(since C++20)

[edit] Program utilities

Termination (e.g. std::abort, std::atexit), environment (e.g. std::system), signals (e.g. std::raise)

[edit] Dynamic memory management

Smart pointers (e.g. std::shared_ptr), allocators (e.g. std::allocator or std::pmr::memory_resource), C-style memory management (e.g. std::malloc)

[edit] Error handling

Exceptions (e.g. std::exception, std::terminate), assertions (e.g. assert)

[edit] Source code information capture

Defined in header <source_location>
(C++20)
 a class representing information about the source code, such as file names, line numbers, and function names
(class) [edit]

[edit] Initializer lists

Defined in header <initializer_list>
(C++11)
 references a temporary array created in list-initialization
(class template) [edit]

[edit] Three-way comparison

Defined in header <compare>
(C++20)
 specifies that operator <=> produces consistent result on given types
(concept) [edit]
(C++20)
 the result type of 3-way comparison that supports all 6 operators, is not substitutable, and allows incomparable values
(class) [edit]
(C++20)
 the result type of 3-way comparison that supports all 6 operators and is not substitutable
(class) [edit]
(C++20)
 the result type of 3-way comparison that supports all 6 operators and is substitutable
(class) [edit]
(C++20)
 named comparison functions
(function) [edit]
(C++20)
 constrained function object implementing x <=> y
(class) [edit]
(C++20)
 obtains the result type of the three-way comparison operator <=> on given types
(class template) [edit]
(C++20)
 the strongest comparison category to which all of the given types can be converted
(class template) [edit]
(C++20)
 performs 3-way comparison and produces a result of type std::strong_ordering
(customization point object)[edit]
(C++20)
 performs 3-way comparison and produces a result of type std::weak_ordering
(customization point object)[edit]
(C++20)
 performs 3-way comparison and produces a result of type std::partial_ordering
(customization point object)[edit]
(C++20)
 performs 3-way comparison and produces a result of type std::strong_ordering, even if operator<=> is unavailable
(customization point object)[edit]
(C++20)
 performs 3-way comparison and produces a result of type std::weak_ordering, even if operator<=> is unavailable
(customization point object)[edit]
(C++20)
 performs 3-way comparison and produces a result of type std::partial_ordering, even if operator<=> is unavailable
(customization point object)[edit]

[edit] Coroutine support

Types for coroutine support, e.g. std::coroutine_traits, std::coroutine_handle.

(since C++20)

[edit] Variadic functions

Support for functions that take an arbitrary number of parameters (via e.g. va_start, va_arg, va_end).

[edit] General-purpose utilities

[edit] Swap

Defined in header <utility>
swaps the values of two objects
(function template) [edit]
(C++14)
 replaces the argument with a new value and returns its previous value
(function template) [edit]
Defined in header <concepts>
(C++20)
 swaps the values of two objects
(customization point object)[edit]

[edit] Type operations

Defined in header <utility>
(C++11)
 forwards a function argument and use the type template argument to preserve its value category
(function template) [edit]
(C++23)
 forwards a function argument as if casting it to the value category and constness of the expression of specified type template argument
(function template) [edit]
(C++11)
 converts the argument to an xvalue
(function template) [edit]
(C++11)
 converts the argument to an xvalue if the move constructor does not throw
(function template) [edit]
(C++17)
 obtains a reference to const to its argument
(function template) [edit]
(C++11)
 obtains a reference to an object of the template type argument for use in an unevaluated context
(function template) [edit]
(C++23)
 converts an enumeration to its underlying type
(function template) [edit]

[edit] Integer comparison functions

Defined in header <utility>
(C++20)
 compares two integer values, ensuring that signed negative numbers are less than unsigned numbers
(function template) [edit]
(C++20)
 checks if an integer value is in the range of a given integer type
(function template) [edit]

[edit] Relational operators

Defined in header <utility>
Defined in namespace std::rel_ops
(deprecated in C++20)
 automatically generates comparison operators based on user-defined operator== and operator<
(function template) [edit]

[edit] Construction tags

Defined in header <utility>
(C++11)
 piecewise construction tag
(tag)[edit]
(C++17)
 in-place construction tag
(tag)[edit]
(C++26)
 value construction tag
(tag)[edit]

[edit] Pairs and tuples

Defined in header <utility>
implements binary tuple, i.e. a pair of values
(class template) [edit]
Defined in header <tuple>
(C++11)
 implements fixed size container, which holds elements of possibly different types
(class template) [edit]
(C++17)
 calls a function with a tuple of arguments
(function template) [edit]
(C++17)
 construct an object with a tuple of arguments
(function template) [edit]
Tuple protocol
Defined in header <tuple>
Defined in header <utility>
Defined in header <array>
Defined in header <ranges>
Defined in header <complex>
(C++11)
 obtains the number of elements of a tuple-like type
(class template) [edit]
(C++11)
 obtains the element types of a tuple-like type
(class template) [edit]

[edit] Sum types and type erased wrappers

Defined in header <optional>
(C++17)
 a wrapper that may or may not hold an object
(class template) [edit]
 
Defined in header <expected>
(C++23)
 a wrapper that contains either an expected or error value
(class template) [edit]
 
Defined in header <variant>
(C++17)
 a type-safe discriminated union
(class template) [edit]
 
Defined in header <any>
(C++17)
 objects that hold instances of any CopyConstructible type
(class) [edit]

[edit] Bitset

Defined in header <bitset>
implements constant length bit array
(class template) [edit]

[edit] Function objects

Partial function application (e.g. std::bind) and related utilities: utilities for binding such as std::ref and std::placeholders, polymorphic function wrappers: std::function, predefined functors (e.g. std::plus, std::equal_to), pointer-to-member to function converters std::mem_fn.

[edit] Hash support

Defined in header <functional>
(C++11)
 hash function object
(class template) [edit]

[edit] Date and time

Time tracking (e.g. std::chrono::time_point, std::chrono::duration), C-style date and time (e.g. std::time, std::clock)

[edit] Primitive string conversions

In addition to sophisticated locale-dependent parsers and formatters provided by the C++ I/O library, the C I/O library, C++ string converters, and C string converters, the header <charconv> provides light-weight, locale-independent, non-allocating, non-throwing parsers and formatters for arithmetic types.

Defined in header <charconv>
(C++17)
 converts an integer or floating-point value to a character sequence
(function) [edit]
(C++17)
 the return type of std::to_chars
(class) [edit]
(C++17)
 converts a character sequence to an integer or floating-point value
(function) [edit]
(C++17)
 the return type of std::from_chars
(class) [edit]
(C++17)
 specifies formatting for std::to_chars and std::from_chars
(enum) [edit]

[edit] Formatting library

Facilities for type-safe string formatting.

Defined in header <format>
(C++20)
 stores formatted representation of the arguments in a new string
(function template) [edit]
(C++20)
 writes out formatted representation of its arguments through an output iterator
(function template) [edit]
(C++20)
 writes out formatted representation of its arguments through an output iterator, not exceeding specified size
(function template) [edit]
(C++20)
 determines the number of characters necessary to store the formatted representation of its arguments
(function template) [edit]
(C++20)
 non-template variant of std::format using type-erased argument representation
(function) [edit]
(C++20)
 non-template variant of std::format_to using type-erased argument representation
(function template) [edit]
(C++20)
 defines formatting rules for a given type
(class template) [edit]
(C++20)
 exception type thrown on formatting errors
(class) [edit]

[edit] See also

C documentation for Utility library
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/utility&oldid=177660"