C++ named requirements: BinaryPredicate

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Diagnostics library

Memory management library

Metaprogramming library (C++11)

General utilities library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Strings library

Text processing library

Numerics library

Date and time library

Input/output library

Filesystem library (C++17)

Concurrency support library (C++11)

Execution control library (C++26)

Technical specifications

Symbols index

External libraries

 

C++ named requirements

Basic DefaultConstructible MoveConstructible (C++11) CopyConstructible CopyAssignable MoveAssignable (C++11) Destructible Type properties ScalarType PODType TriviallyCopyable (C++11) TrivialType (C++11) StandardLayoutType (C++11)   ImplicitLifetimeType Library-wide BooleanTestable EqualityComparable LessThanComparable Swappable ValueSwappable (C++11) NullablePointer (C++11) Hash (C++11) Allocator FunctionObject Callable Predicate BinaryPredicate Compare

Container Container ReversibleContainer AllocatorAwareContainer SequenceContainer ContiguousContainer (C++17) AssociativeContainer UnorderedAssociativeContainer (C++11)   Container element DefaultInsertable (C++11) CopyInsertable (C++11) MoveInsertable (C++11) EmplaceConstructible (C++11) Erasable (C++11) Iterator LegacyIterator LegacyInputIterator LegacyOutputIterator LegacyForwardIterator LegacyBidirectionalIterator LegacyRandomAccessIterator LegacyContiguousIterator (C++17) ConstexprIterator (C++20) Stream I/O FormattedInputFunction UnformattedInputFunction FormattedOutputFunction UnformattedOutputFunction Formatters BasicFormatter (C++20) Formatter (C++20)

Random Numbers SeedSequence (C++11) RandomNumberEngine (C++11) RandomNumberDistribution (C++11) UniformRandomBitGenerator (C++11) RandomNumberEngineAdaptor (C++11) Concurrency BasicLockable (C++11) Lockable (C++11) TimedLockable (C++11) SharedLockable (C++14) SharedTimedLockable (C++14) Mutex (C++11) TimedMutex (C++11) SharedMutex (C++17) SharedTimedMutex (C++14) Ranges RangeAdaptorObject (C++20) RangeAdaptorClosureObject (C++20) Multidimensional View LayoutMapping (C++23) LayoutMappingPolicy (C++23) AccessorPolicy (C++23) Other CharTraits RegexTraits (C++11)   BitmaskType LiteralType (C++11) NumericType UnaryTypeTrait (C++11) BinaryTypeTrait (C++11) TransformationTrait (C++11) Clock (C++11) TrivialClock (C++11)

 

Certain standard library functions take a BinaryPredicate parameter, called either with elements of two corresponding iterators or one iterator and a value whose type is part of the function signature.

Given BinaryPredicate pred, corresponding iterators it0 and it1, and value value, let elem0 designate the object *it0 and elem1 designate the object *it1, it is required that:

• pred is a FunctionObject
• pred does not apply a non-constant function on its arguments
• pred returns a BooleanTestable value
• If pred(*it0, *it1) is called, then pred(elem0, elem1), pred(elem0, *it1) and pred(*it0, elem1) are all valid and equal to pred(*it0, *it1), regardless of whether elem0 and elem1 are const or not, regardless of whether elem0 and elem1 are lvalues or xvalues(since C++11), respectively
• If pred(*it0, value) is called, then pred(elem0, value) is valid and equal to pred(*it0, value), regardless of whether elem0 is const or not, regardless of whether elem0 is an lvalue or xvalue(since C++11)

The most straight-forward way of achieving that last requirement is for pred to take its parameters by const lvalue reference. pred may take its parameters by value only if construction doesn't modify the source object; namely, if pred's first parameter and *it0 both have type T, or pred's second parameter and *it1 both have type T, then T must not have move semantics.

Standard library

The following standard library facilities expect a BinaryPredicate which isn't a Compare type.

find_end	finds the last sequence of elements in a certain range (function template & algorithm function object)
ranges::find_end (C++20)
find_first_of	searches for any one of a set of elements (function template & algorithm function object)
ranges::find_first_of (C++20)
adjacent_find	finds the first two adjacent items that are equal (or satisfy a given predicate) (function template & algorithm function object)
ranges::adjacent_find (C++20)
mismatch	finds the first position where two ranges differ (function template & algorithm function object)
ranges::mismatch (C++20)
equal	determines if two sets of elements are the same (function template & algorithm function object)
ranges::equal (C++20)
is_permutation (C++11)	determines if a sequence is a permutation of another sequence (function template & algorithm function object)
ranges::is_permutation (C++20)
search	searches for the first occurrence of a range of elements (function template & algorithm function object)
ranges::search (C++20)
search_n	searches for the first occurrence of a number consecutive copies of an element in a range (function template & algorithm function object)
ranges::search_n (C++20)
unique	removes consecutive duplicate elements in a range (function template & algorithm function object)
ranges::unique (C++20)
unique_copy	creates a copy of some range of elements that contains no consecutive duplicates (function template & algorithm function object)
ranges::unique_copy (C++20)
not2 (deprecated in C++17)(removed in C++20)	constructs custom std::binary_negate object (function template)
unique	removes consecutive duplicate elements (public member function of std::forward_list<T,Allocator>)
unique	removes consecutive duplicate elements (public member function of std::list<T,Allocator>)
unique	removes consecutive duplicate elements (public member function of std::hive<T,Allocator>)
unordered_set (C++11)	collection of unique keys, hashed by keys (class template)
unordered_map (C++11)	collection of key-value pairs, hashed by keys, keys are unique (class template)
unordered_multiset (C++11)	collection of keys, hashed by keys (class template)
unordered_multimap (C++11)	collection of key-value pairs, hashed by keys (class template)

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR	Applied to	Behavior as published	Correct behavior
LWG 2114 (P2167R3)	C++98	convertibility of return types to bool was too weak to reflect the expectation of implementations	requirements strengthened
LWG 3031	C++98	requirements on const values were insufficient	requirements strengthened

See also

Predicate
predicate (C++20)	specifies that a callable type is a Boolean predicate (concept)