Iterators

Thrust provides a rich collection of iterators that extend beyond the C++ standard library.

Important

Many Thrust iterators have direct replacements in libcu++, which are newer and thus fix some of the shortcomings of Thrust’s iterators. They should generally be preferred. See Fancy Iterators for more.

Fancy iterators

Thrust provides the following fancy iterators:

• thrust::make_transform_input_output_iterator
• thrust::make_constant_iterator
• thrust::make_counting_iterator
• thrust::make_permutation_iterator
• thrust::make_tabulate_output_iterator
• thrust::make_strided_iterator
• thrust::make_transform_output_iterator
• thrust::make_discard_iterator
• thrust::make_zip_iterator
• thrust::make_transform_iterator
• thrust::make_shuffle_iterator

Iterator traits

Thrust offers the following traits to inspect iterators:

• thrust::iterator_traversal_t
• thrust::iterator_system_t
• thrust::iterator_reference_t
• thrust::iterator_pointer_t
• thrust::iterator_traits
• thrust::iterator_difference_t
• thrust::iterator_value_t

Iterator tags

Thrust provides the following iterator category tags:

• thrust::bidirectional_host_iterator_tag
• thrust::random_access_host_iterator_tag
• thrust::output_host_iterator_tag
• thrust::input_host_iterator_tag
• thrust::forward_host_iterator_tag

Additionally, the following utilities for working with iterator category tags are provided:

• thrust::retag
• thrust::reinterpret_tag

Thrust provides the following iterator traversal tags:

• thrust::bidirectional_traversal_tag
• thrust::forward_traversal_tag
• thrust::incrementable_traversal_tag
• thrust::no_traversal_tag
• thrust::random_access_traversal_tag
• thrust::single_pass_traversal_tag

Iterator model

Thrust’s iterators extend the C++ standard library iterator model and were inspired by Boost.Iterator. In the C++ standard library, iterators are mostly distinguished by their iterator category (before C++20), and their iterator concept (since C++20). This is governed by the nested iterator_category and iterator_concept types, respectively, which in standard C++ are one of:

• input_iterator_tag

• output_iterator_tag

• forward_iterator_tag

• bidirectional_iterator_tag

• random_access_iterator_tag

• contiguous_iterator_tag (since C++20)

Thrust extends this model by introducing the notion of an iterator traversal and an iterator system. In order to fit into the existing schema of iterators, it encodes this additional information into the iterator_category, which is no longer one of the standard tags listed above, but a templated type carrying the iterator tag, iterator traversal and iterator system. This information can be extracted using the thrust::iterator_traversal and thrust::iterator_system traits.