std::ranges::views::filter, std::ranges::filter_view

std::ranges::filter_view is the concrete view type that exposes only elements satisfying a predicate.

std::ranges::views::filter is the range adaptor object used in pipelines and direct adaptor calls to produce a filter_view.

# Declarations

template< ranges::input_range V,
std::indirect_unary_predicate<ranges::iterator_t<V>> Pred >
requires ranges::view<V> && std::is_object_v<Pred>
class filter_view
: public ranges::view_interface<filter_view<V, Pred>>

(since C++20)

namespace views {
inline constexpr /* unspecified */ filter = /* unspecified */;
}

(since C++20)

# Adaptor call signatures

template< ranges::viewable_range R, class Pred >
requires /* see below */
constexpr ranges::view auto filter( R&& r, Pred&& pred );

(since C++20)

template< class Pred >
constexpr /* range adaptor closure */ filter( Pred&& pred );

(since C++20)

# Example

#include <iostream>
#include <ranges>
 
int main()
{
    auto even = [](int i) { return 0 == i % 2; };
    auto square = [](int i) { return i * i; };
 
    for (int i : std::views::iota(0, 6)
               | std::views::filter(even)
               | std::views::transform(square))
        std::cout << i << ' ';
    std::cout << '\n';
}

# Semantic model

filter_view performs lazy filtering: elements are tested against the predicate as iteration advances, and failing elements are skipped.

The adaptor stores a view of the underlying range plus a predicate object. A pipeline such as r | std::views::filter(pred) is equivalent in intent to constructing a filter_view over views::all(r) with pred.

The predicate is part of the view object’s state. Mutating external state captured by the predicate affects later iterations through the same view.

# Traversal and iterator notes

filter_view always models input_range. It models forward_range, bidirectional_range, and common_range when the underlying view models those concepts.

It does not provide random-access traversal because advancing requires predicate checks and possible skipping.

For forward underlying ranges, implementations may cache the first matching position to make repeated begin() calls efficient.

# Reference map

# Defect reports

# See also

• ranges::take_while_view, views::take_while
• ranges::transform_view, views::transform
• view

This hub groups the ranges library by user task rather than by raw reference tree shape. View types and adaptor objects are presented as the same conceptual item.