Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/named req"

From cppreference.com
< cpp
(+ BooleanTestable)
 
(85 intermediate revisions by 22 users not shown)
Line 1: Line 1:
{{title|Concepts}}
+
{{title|Named Requirements}}
{{cpp/concept/sidebar}}
+
{{cpp/named req/navbar}}
  
Concept is a term that describes a set of characteristics of a type. Concepts are a more convenient way to specify both what properties are expected from a type, and what properties a type has.
+
The ''named requirements'' listed on this page are the named requirements used in the normative text of the C++ standard to define the expectations of the standard library.
  
There was [http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1758.pdf a proposal to include formal specification of concepts into C++11] so that the compiler could check the type requirements ''before'' template instantiation and in turn could produce much more sensible error messages in case a type did not fulfill the template requirements. This proposal was later dropped for various reasons. However, there are unofficial plans to add concepts to a future revision of the C++ language.
+
The burden to ensure that library templates are instantiated with template arguments that satisfy these requirements is on the programmer. Failure to do so may result in very complex compiler diagnostics.
  
C++03 and C++11 define behavior in terms of '''requirements''', which are similar to concepts, and are listed below.
+
Some of these requirements are formalized in C++20 using the [[cpp/language/constraints|concepts]] language feature.
  
{{dcl list begin}}
+
{{dsc begin}}
{{dcl list h1 | Basic}}
+
{{dsc h1|Basic}}
{{dcl list concept | cpp/concept/DefaultConstructible | specifies that type has default constructor}}
+
{{dsc named req|cpp/named req/DefaultConstructible|specifies that an object of the type can be default constructed}}
{{dcl list concept | cpp/concept/MoveConstructible | specifies that type has move constructor | notes={{mark c++11}}}}
+
{{dsc named req|cpp/named req/MoveConstructible|specifies that an object of the type can be constructed from rvalue|notes={{mark c++11}}}}
{{dcl list concept | cpp/concept/CopyConstructible | specifies that type has copy constructor}}
+
{{dsc named req|cpp/named req/CopyConstructible|specifies that an object of the type can be constructed from lvalue}}
{{dcl list concept | cpp/concept/MoveAssignable | specifies that type can move assignment operator | notes={{mark c++11}}}}
+
{{dsc named req|cpp/named req/MoveAssignable|specifies that an object of the type can be assigned from rvalue|notes={{mark c++11}}}}
{{dcl list concept | cpp/concept/CopyAssignable | specifies that type has copy assignment operator}}
+
{{dsc named req|cpp/named req/CopyAssignable|specifies that an object of the type can be assigned from lvalue}}
{{dcl list concept | cpp/concept/Destructible | type has a destructor that clears all memory}}
+
{{dsc named req|cpp/named req/Destructible|specifies that an object of the type can be destroyed}}
  
{{dcl list h1 | Library-wide}}
+
{{dsc h1|Type properties}}
{{dcl list concept | cpp/concept/EqualityComparable | has a working {{tt|operator{{==}}}} that is an equivalence relation}}
+
{{dsc|Note: the standard does not define named requirements with names specified in this subcategory. <br>These are type categories defined by the core language. They are included here as named requirements only for consistency.}}
{{dcl list concept | cpp/concept/LessThanComparable | {{tt|operator<}} is a strict weak ordering relation}}
+
{{dsc named req|cpp/named req/ScalarType|object types that are not array types or class types}}
{{dcl list concept | cpp/concept/Swappable| can be used as argument of {{cpp|std::swap}} | notes={{mark c++11}} }}
+
{{dsc named req|cpp/named req/PODType|POD (Plain Old Data) types, compatible with C {{c|struct}}|notes={{mark deprecated c++20}}}}
{{dcl list concept | cpp/concept/ValueSwappable| Pointer-like type that when dereferenced can be passed to {{cpp|std::swap}} | notes={{mark c++11}} }}
+
{{dsc named req|cpp/named req/TriviallyCopyable|objects of these types can maintain their values after copying their underlying bytes|notes={{mark c++11}}}}
{{dcl list concept | cpp/concept/NullablePointer| Pointer-like type supporting a null value | notes={{mark c++11}} }}
+
{{dsc named req|cpp/named req/TrivialType|objects of these types can be trivially constructed and copied|notes={{mark c++11}}}}
{{dcl list concept | cpp/concept/Hash | notes={{mark c++11}} }}
+
{{dsc named req|cpp/named req/StandardLayoutType|these types are useful for communicating with code written in other programming languages|notes={{mark c++11}}}}
{{dcl list concept | cpp/concept/Allocator| Class type that contains allocation information}}
+
{{dsc named req|cpp/named req/ImplicitLifetimeType|objects of these types can be implicitly created, and their lifetimes can be implicitly started}}
  
{{dcl list h1 | Container}}
+
{{dsc h1|Library-wide}}
{{dcl list concept | cpp/concept/Container | data structure that allows element access using iterators }}
+
{{dsc named req|cpp/named req/BooleanTestable<!-- LWG2114, P2167R3 -->|boolean operations ({{c/core|operator&&}}, {{c/core|operator{{!!}}}}, and {{c/core|operator!}}) have usual semantics}}
{{dcl list concept | cpp/concept/ReversibleContainer | container using bidirectional iterators }}
+
{{dsc named req|cpp/named req/EqualityComparable|{{tt|operator{{==}}}} is an equivalence relation}}
{{dcl list concept | cpp/concept/AllocatorAwareContainer | container using an allocator | notes={{mark c++11}} }}
+
{{dsc named req|cpp/named req/LessThanComparable|{{tt|operator<}} is a strict weak ordering relation}}
{{dcl list concept | cpp/concept/SequenceContainer | container with elements stored linearly }}
+
{{dsc named req|cpp/named req/Swappable|can be swapped with an unqualified non-member function call {{c|swap()}}}}
{{dcl list concept | cpp/concept/AssociativeContainer | container that stores elements by associating them to keys }}
+
{{dsc named req|cpp/named req/ValueSwappable|a {{named req|Iterator}} that dereferences to a {{named req|Swappable}} type|notes={{mark c++11}}}}
{{dcl list concept | cpp/concept/UnorderedAssociativeContainer | container that stores elements stored in buckets by associating them to keys | notes={{mark c++11}} }}
+
{{dsc named req|cpp/named req/NullablePointer|a pointer-like type supporting a null value|notes={{mark c++11}}}}
{{dcl list h2 | Container element}}
+
{{dsc named req|cpp/named req/Hash|a {{named req|FunctionObject}} that for inputs with different values has a low probability of giving the same output|notes={{mark c++11}}}}
{{dcl list concept | cpp/concept/CopyInsertable| notes={{mark c++11}} }}
+
{{dsc named req|cpp/named req/Allocator|a class type that contains allocation information}}
{{dcl list concept | cpp/concept/MoveInsertable| notes={{mark c++11}} }}
+
{{dsc named req|cpp/named req/FunctionObject|an object that can be called with the function call syntax}}
{{dcl list concept | cpp/concept/EmplaceConstructible| notes={{mark c++11}} }}
+
{{dsc named req|cpp/named req/Callable|a type for which the invoke operation is defined}}
 +
{{dsc named req|cpp/named req/Predicate|a {{named req|FunctionObject}} that returns a value convertible to {{c|bool}} for one argument without modifying it}}
 +
{{dsc named req|cpp/named req/BinaryPredicate|a {{named req|FunctionObject}} that returns a value convertible to {{c|bool}} for two arguments without modifying them}}
 +
{{dsc named req|cpp/named req/Compare|a {{named req|BinaryPredicate}} that establishes an ordering relation}}
 +
{{dsc end}}
  
{{dcl list h1 | Iterator}}
+
{{dsc begin}}
{{dcl list concept | cpp/concept/Iterator | general concept to access data within some data structure }}
+
{{dsc h1|Container}}
{{dcl list concept | cpp/concept/InputIterator | iterator that can be used to read data }}
+
{{dsc named req|cpp/named req/Container|data structure that allows element access using iterators}}
{{dcl list concept | cpp/concept/OutputIterator | iterator that can be used to write data }}
+
{{dsc named req|cpp/named req/ReversibleContainer|container using bidirectional iterators}}
{{dcl list concept | cpp/concept/ForwardIterator | iterator that can be used to read data multiple times}}
+
{{dsc named req|cpp/named req/AllocatorAwareContainer|container using an allocator|notes={{mark c++11}}}}
{{dcl list concept | cpp/concept/BidirectionalIterator | iterator that can be both incremented and decremented }}
+
{{dsc named req|cpp/named req/SequenceContainer|container with elements stored linearly}}
{{dcl list concept | cpp/concept/RandomAccessIterator | iterator that can be advanced in constant time }}
+
{{dsc named req|cpp/named req/ContiguousContainer|container with elements stored at adjacent memory addresses|notes={{mark c++17}}}}
 +
{{dsc named req|cpp/named req/AssociativeContainer|container that stores elements by associating them to keys}}
 +
{{dsc named req|cpp/named req/UnorderedAssociativeContainer|container that stores elements stored in buckets by associating them to keys|notes={{mark c++11}}}}
 +
{{dsc h2|Container element}}
 +
{{dsc named req|cpp/named req/DefaultInsertable|element can be default-constructed in uninitialized storage|notes={{mark c++11}}}}
 +
{{dsc named req|cpp/named req/CopyInsertable|element can be copy-constructed in uninitialized storage|notes={{mark c++11}}}}
 +
{{dsc named req|cpp/named req/MoveInsertable|element can be move-constructed in uninitialized storage|notes={{mark c++11}}}}
 +
{{dsc named req|cpp/named req/EmplaceConstructible|element can be constructed in uninitialized storage|notes={{mark c++11}}}}
 +
{{dsc named req|cpp/named req/Erasable|element can be destroyed using an allocator|notes={{mark c++11}}}}
  
{{dcl list h1 | Random Number Generation}}
+
{{dsc h1|Iterator}}
{{dcl list concept | cpp/concept/SeedSequence | notes={{mark c++11}} }}
+
{{dsc named req|cpp/named req/Iterator|title=LegacyIterator|general concept to access data within some data structure}}
{{dcl list concept | cpp/concept/UniformRandomNumberGenerator | notes={{mark c++11}} }}
+
{{dsc named req|cpp/named req/InputIterator|title=LegacyInputIterator|iterator that can be used to read data}}
{{dcl list concept | cpp/concept/RandomNumberEngine | notes={{mark c++11}} }}
+
{{dsc named req|cpp/named req/OutputIterator|title=LegacyOutputIterator|iterator that can be used to write data}}
{{dcl list concept | cpp/concept/RandomNumberEngineAdaptor | notes={{mark c++11}} }}
+
{{dsc named req|cpp/named req/ForwardIterator|title=LegacyForwardIterator|iterator that can be used to read data multiple times}}
{{dcl list concept | cpp/concept/RandomNumberDistribution | notes={{mark c++11}} }}
+
{{dsc named req|cpp/named req/BidirectionalIterator|title=LegacyBidirectionalIterator|iterator that can be both incremented and decremented}}
 +
{{dsc named req|cpp/named req/RandomAccessIterator|title=LegacyRandomAccessIterator|iterator that can be advanced in constant time}}
 +
{{dsc named req|cpp/named req/ContiguousIterator|title=LegacyContiguousIterator|iterator to contiguously-allocated elements|notes={{mark c++17}}}}
 +
{{dsc named req|cpp/named req/ConstexprIterator|iterator that can be used during constant expression evaluation|notes={{mark c++20}}}}
  
{{dcl list h1 | Concurrency}}
+
{{dsc h1|Stream I/O functions}}
{{dcl list concept | cpp/concept/BasicLockable | notes={{mark c++11}} }}
+
<!--27.7.2.3[istream.unformatted]/1-->
{{dcl list concept | cpp/concept/Lockable | notes={{mark c++11}} }}
+
{{dsc named req|cpp/named req/UnformattedInputFunction|a stream input function that does not skip leading whitespace and counts the processed characters}}
{{dcl list concept | cpp/concept/TimedLockable | notes={{mark c++11}} }}
+
<!--27.7.2.2.1[istream.formatted.reqmts]-->
{{dcl list concept | cpp/concept/Mutex | notes={{mark c++11}} }}
+
{{dsc named req|cpp/named req/FormattedInputFunction|a stream input function that skips leading whitespace}}
{{dcl list concept | cpp/concept/TimedMutex | notes={{mark c++11}} }}
+
<!--27.7.3.7[ostream.unformatted]/1-->
 +
{{dsc named req|cpp/named req/UnformattedOutputFunction|a basic stream output function}}
 +
<!--27.7.3.6.1[ostream.formatted.reqmts]-->
 +
{{dsc named req|cpp/named req/FormattedOutputFunction|a stream output function that sets failbit on errors and returns a reference to the stream}}
  
{{dcl list h1 | Other}}
+
{{dsc h1|Formatters}}
{{dcl list concept | cpp/concept/UnaryTypeTrait | notes={{mark c++11}} }}
+
{{dsc named req|cpp/named req/BasicFormatter|abstracts formatting operations for a given formatting argument type and character type|notes={{mark c++20}}}}
{{dcl list concept | cpp/concept/BinaryTypeTrait | notes={{mark c++11}} }}
+
{{dsc named req|cpp/named req/Formatter|defines functions used by the [[cpp/utility/format|formatting library]]|notes={{mark c++20}}}}
{{dcl list concept | cpp/concept/TransformationTrait | notes={{mark c++11}} }}
+
{{dcl list concept | cpp/concept/Clock | notes={{mark c++11}} }}
+
{{dcl list concept | cpp/concept/TrivialClock | notes={{mark c++11}} }}
+
{{dcl list concept | cpp/concept/CharTraits}}
+
{{dcl list concept | cpp/concept/pos_type}}
+
{{dcl list concept | cpp/concept/off_type}}
+
{{dcl list concept | cpp/concept/Predicate}}
+
{{dcl list concept | cpp/concept/BinaryPredicate}}
+
  
{{dcl list end}}
+
{{dsc h1|Random Number Generation}}
 +
{{dsc named req|cpp/named req/SeedSequence|consumes a sequence of integers and produces a sequence of 32-bit unsigned values|notes={{mark c++11}}}}
 +
{{dsc named req|cpp/named req/UniformRandomBitGenerator|returns uniformly distributed random unsigned integers|notes={{mark c++11}}}}
 +
{{dsc named req|cpp/named req/RandomNumberEngine|a deterministic {{named req|UniformRandomBitGenerator}}, defined by the seed|notes={{mark c++11}}}}
 +
{{dsc named req|cpp/named req/RandomNumberEngineAdaptor|a {{named req|RandomNumberEngine}} that transforms the output of another {{named req|RandomNumberEngine}}|notes={{mark c++11}}}}
 +
{{dsc named req|cpp/named req/RandomNumberDistribution|returns random numbers distributed according to a given mathematical probability density function|notes={{mark c++11}}}}
  
 +
{{dsc h1|Concurrency}}
 +
{{dsc named req|cpp/named req/BasicLockable|provides exclusive ownership semantics for execution agents (i.e. threads)|notes={{mark c++11}}}}
 +
{{dsc named req|cpp/named req/Lockable|a {{named req|BasicLockable}} that supports attempted lock acquisition|notes={{mark c++11}}}}
 +
{{dsc named req|cpp/named req/TimedLockable|a {{named req|Lockable}} that supports timed lock acquisition|notes={{mark c++11}}}}
 +
{{dsc named req|cpp/named req/SharedLockable|provides shared ownership semantics for execution agents (i.e. threads)|notes={{mark c++14}}<!--P2160R1-->}}
 +
{{dsc named req|cpp/named req/SharedTimedLockable|a {{named req|SharedLockable}} that supports timed lock acquisition|notes={{mark c++14}}<!--P2160R1-->}}
 +
{{dsc named req|cpp/named req/Mutex|a {{named req|Lockable}} that protects against data races and sequentially consistent synchronization|notes={{mark c++11}}}}
 +
{{dsc named req|cpp/named req/TimedMutex|a {{named req|TimedLockable}} that protects against data races and sequentially consistent synchronization|notes={{mark c++11}}}}
 +
{{dsc named req|cpp/named req/SharedMutex|a {{named req|Mutex}} that supports shared ownership semantics|notes={{mark c++17}}}}
 +
{{dsc named req|cpp/named req/SharedTimedMutex|a {{named req|TimedMutex}} that supports shared ownership semantics|notes={{mark c++14}}}}
  
{{todo|Any other missing concept?}}
+
{{dsc h1|Ranges}}
 +
{{dsc named req|cpp/named req/RangeAdaptorObject|a {{named req|FunctionObject}} that creates a [[cpp/ranges#Range adaptors|range adaptor]] from a {{lconcept|viewable_range}} and additional arguments|notes={{mark c++20}}}}
 +
{{dsc named req|cpp/named req/RangeAdaptorClosureObject|a {{named req|FunctionObject}} that supports the pipe operator|notes={{mark c++20}}}}
 +
 
 +
{{dsc h1|Multidimensional View Customization}}
 +
{{dsc named req|cpp/named req/LayoutMapping|controls the mapping of multidimensional index in {{lc|mdspan}}|notes={{mark c++23}}}}
 +
{{dsc named req|cpp/named req/LayoutMappingPolicy|a policy that holds {{named req|LayoutMapping}} requirements|notes={{mark c++23}}}}
 +
{{dsc named req|cpp/named req/AccessorPolicy|a policy that controls access to data handle in {{lc|mdspan}}|notes={{mark c++23}}}}
 +
 
 +
{{dsc h1|Other}}
 +
{{dsc named req|cpp/named req/UnaryTypeTrait|describes a property of a type|notes={{mark c++11}}}}
 +
{{dsc named req|cpp/named req/BinaryTypeTrait|describes a relationship between two types|notes={{mark c++11}}}}
 +
{{dsc named req|cpp/named req/TransformationTrait|modifies a property of a type|notes={{mark c++11}}}}
 +
{{dsc named req|cpp/named req/Clock|aggregates a duration, a time point, and a function to get the current time point|notes={{mark c++11}}}}
 +
{{dsc named req|cpp/named req/TrivialClock|a {{named req|Clock}} that does not throw exceptions|notes={{mark c++11}}}}
 +
{{dsc named req|cpp/named req/CharTraits|defines types and functions for a character type}}
 +
{{dsc named req|cpp/named req/BitmaskType|bitset, integer, or enumeration}}<!--$17.5.2.1.3[bitmask types]-->
 +
{{dsc named req|cpp/named req/NumericType|a type for which initialization is effectively equal to assignment}}<!--C++98/03 §26.1[lib.numeric.requirements], C++11/14 §26.2[numeric.requirements]-->
 +
{{dsc named req|cpp/named req/RegexTraits|defines types and functions used by the [[cpp/regex|regular expressions library]]|notes={{mark c++11}}}}<!--C++11/14 §28.3[re.req]-->
 +
{{dsc named req|cpp/named req/LiteralType|a type with constexpr constructor|notes={{mark c++11}}}}
 +
{{dsc end}}
 +
 
 +
{{todo|Any other missing requirement?}}
 +
 
 +
{{langlinks|ar|de|es|fr|it|ja|pt|ru|zh}}

Latest revision as of 22:51, 7 September 2024

 
 
C++ named requirements
 

The named requirements listed on this page are the named requirements used in the normative text of the C++ standard to define the expectations of the standard library.

The burden to ensure that library templates are instantiated with template arguments that satisfy these requirements is on the programmer. Failure to do so may result in very complex compiler diagnostics.

Some of these requirements are formalized in C++20 using the concepts language feature.

Contents

Basic

specifies that an object of the type can be default constructed
(named requirement)
specifies that an object of the type can be constructed from rvalue
(named requirement)
specifies that an object of the type can be constructed from lvalue
(named requirement)
specifies that an object of the type can be assigned from rvalue
(named requirement)
specifies that an object of the type can be assigned from lvalue
(named requirement)
specifies that an object of the type can be destroyed
(named requirement)

Type properties

Note: the standard does not define named requirements with names specified in this subcategory.
These are type categories defined by the core language. They are included here as named requirements only for consistency.
object types that are not array types or class types
(named requirement)
(deprecated in C++20)
POD (Plain Old Data) types, compatible with C struct
(named requirement)
objects of these types can maintain their values after copying their underlying bytes
(named requirement)
objects of these types can be trivially constructed and copied
(named requirement)
these types are useful for communicating with code written in other programming languages
(named requirement)
objects of these types can be implicitly created, and their lifetimes can be implicitly started
(named requirement)

Library-wide

boolean operations (operator&&, operator||, and operator!) have usual semantics
(named requirement)
operator== is an equivalence relation
(named requirement)
operator< is a strict weak ordering relation
(named requirement)
can be swapped with an unqualified non-member function call swap()
(named requirement)
a LegacyIterator that dereferences to a Swappable type
(named requirement)
a pointer-like type supporting a null value
(named requirement)
(C++11)
a FunctionObject that for inputs with different values has a low probability of giving the same output
(named requirement)
a class type that contains allocation information
(named requirement)
an object that can be called with the function call syntax
(named requirement)
a type for which the invoke operation is defined
(named requirement)
a FunctionObject that returns a value convertible to bool for one argument without modifying it
(named requirement)
a FunctionObject that returns a value convertible to bool for two arguments without modifying them
(named requirement)
a BinaryPredicate that establishes an ordering relation
(named requirement)

Container

data structure that allows element access using iterators
(named requirement)
container using bidirectional iterators
(named requirement)
container using an allocator
(named requirement)
container with elements stored linearly
(named requirement)
container with elements stored at adjacent memory addresses
(named requirement)
container that stores elements by associating them to keys
(named requirement)
container that stores elements stored in buckets by associating them to keys
(named requirement)
Container element
element can be default-constructed in uninitialized storage
(named requirement)
element can be copy-constructed in uninitialized storage
(named requirement)
element can be move-constructed in uninitialized storage
(named requirement)
element can be constructed in uninitialized storage
(named requirement)
(C++11)
element can be destroyed using an allocator
(named requirement)

Iterator

general concept to access data within some data structure
(named requirement)
iterator that can be used to read data
(named requirement)
iterator that can be used to write data
(named requirement)
iterator that can be used to read data multiple times
(named requirement)
iterator that can be both incremented and decremented
(named requirement)
iterator that can be advanced in constant time
(named requirement)
iterator to contiguously-allocated elements
(named requirement)
iterator that can be used during constant expression evaluation
(named requirement)

Stream I/O functions

a stream input function that does not skip leading whitespace and counts the processed characters
(named requirement)
a stream input function that skips leading whitespace
(named requirement)
a basic stream output function
(named requirement)
a stream output function that sets failbit on errors and returns a reference to the stream
(named requirement)

Formatters

abstracts formatting operations for a given formatting argument type and character type
(named requirement)
(C++20)
defines functions used by the formatting library
(named requirement)

Random Number Generation

consumes a sequence of integers and produces a sequence of 32-bit unsigned values
(named requirement)
returns uniformly distributed random unsigned integers
(named requirement)
a deterministic UniformRandomBitGenerator, defined by the seed
(named requirement)
a RandomNumberEngine that transforms the output of another RandomNumberEngine
(named requirement)
returns random numbers distributed according to a given mathematical probability density function
(named requirement)

Concurrency

provides exclusive ownership semantics for execution agents (i.e. threads)
(named requirement)
(C++11)
a BasicLockable that supports attempted lock acquisition
(named requirement)
a Lockable that supports timed lock acquisition
(named requirement)
provides shared ownership semantics for execution agents (i.e. threads)
(named requirement)
a SharedLockable that supports timed lock acquisition
(named requirement)
(C++11)
a Lockable that protects against data races and sequentially consistent synchronization
(named requirement)
(C++11)
a TimedLockable that protects against data races and sequentially consistent synchronization
(named requirement)
a Mutex that supports shared ownership semantics
(named requirement)
a TimedMutex that supports shared ownership semantics
(named requirement)

Ranges

a FunctionObject that creates a range adaptor from a viewable_range and additional arguments
(named requirement)
a FunctionObject that supports the pipe operator
(named requirement)

Multidimensional View Customization

controls the mapping of multidimensional index in mdspan
(named requirement)
a policy that holds LayoutMapping requirements
(named requirement)
a policy that controls access to data handle in mdspan
(named requirement)

Other

describes a property of a type
(named requirement)
describes a relationship between two types
(named requirement)
modifies a property of a type
(named requirement)
(C++11)
aggregates a duration, a time point, and a function to get the current time point
(named requirement)
a Clock that does not throw exceptions
(named requirement)
defines types and functions for a character type
(named requirement)
bitset, integer, or enumeration
(named requirement)
a type for which initialization is effectively equal to assignment
(named requirement)
defines types and functions used by the regular expressions library
(named requirement)
a type with constexpr constructor
(named requirement)