Loading...
Searching...
No Matches
Views
Utility

Views are "lazy range combinators" that offer modified views onto other ranges. More...

Collaboration diagram for Views:

## Classes

class | seqan3::views::deep< underlying_adaptor_t >
| A wrapper type around an existing view adaptor that enables "deep view" behaviour for that view. More...

## Typedefs

using | seqan3::views::chunk = seqan::stl::views::chunk

A view adaptor that divides a range into chunks.

This entity is not part of the SeqAn API. Do not rely on it in your applications. This is a implementation of the C++23 chunk_view. It will be replaced with std::views::chunk.

.

using | seqan3::views::join_with = seqan::stl::views::join_with

A view adaptor that represents view consisting of the sequence obtained from flattening a view of ranges, with every element of the delimiter inserted in between elements of the view. The delimiter can be a single element or a view of elements.

This entity is not part of the SeqAn API. Do not rely on it in your applications. This is a implementation of the C++23 join_with_view. It will be replaced with ::std::views::join_with.

.

using | seqan3::views::zip = seqan::stl::views::zip

A view adaptor that takes several views and returns tuple-like values from every i-th element of each view.

This entity is not part of the SeqAn API. Do not rely on it in your applications. This is a implementation of the C++23 zip_view. It will be replaced with std::views::zip.

.

## Variables

template<typename out_t>
constexpr auto | seqan3::views::convert
| A view that converts each element in the input range (implicitly or via static_cast).
template<auto index>
constexpr auto | seqan3::views::elements
| A view calling get on each element in a range.
constexpr auto | seqan3::views::enforce_random_access
| A view adaptor that converts a pseudo random access range to a std::ranges::random_access_range.
constexpr auto | seqan3::views::interleave
| A view that interleaves a given range into another range at regular intervals.
constexpr auto | seqan3::views::pairwise_combine
| A view adaptor that generates all pairwise combinations of the elements of the underlying range.
constexpr detail::repeat_fn | seqan3::views::repeat
| A view factory that repeats a given value infinitely.
constexpr auto | seqan3::views::repeat_n
| A view factory that repeats a given value n times.
constexpr auto | seqan3::views::single_pass_input
| A view adapter that decays most of the range properties and adds single pass behavior.
constexpr auto | seqan3::views::slice
| A view adaptor that returns a half-open interval on the underlying range.
constexpr auto | seqan3::views::type_reduce
| A view adaptor that behaves like std::views::all, but type erases certain ranges.

## Detailed Description

Views are "lazy range combinators" that offer modified views onto other ranges.

SeqAn makes heavy use of views as defined in the Ranges Technical Specification. From the original documentation: "A view is a lightweight wrapper that presents a view of an underlying sequence of elements in some custom way without mutating or copying it. Views are cheap to create and copy, and have non-owning reference semantics. [...] The big advantage of ranges over iterators is their composability. They permit a functional style of programming where data is manipulated by passing it through a series of combinators. In addition, the combinators can be lazy, only doing work when the answer is requested, and purely functional, without mutating the original data. This makes it easier to reason about your code, especially when writing concurrent programs."

See the range module for how views relate to containers and decorators.

Most views provided by SeqAn are specific to biological operations, like seqan3::views::trim_quality which trims sequences based on the quality or seqan3::views::complement which generates the complement of a nucleotide sequence. But SeqAn also provides some general purpose views.

### Namespaces

- All views from the std libary are available in the namespace std::ranges::views or in the namespace alias std::views.
- All SeqAn views are available in the namespace seqan3::views.

### Example

Functional and pipe notations:

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <algorithm>
#include <iostream>
#include <seqan3/alphabet/nucleotide/dna4.hpp>
#include <seqan3/alphabet/views/complement.hpp>
int main()
{
using namespace seqan3::literals;
seqan3::dna4_vector vec{"ACGGTC"_dna4};
// these are synonymous:
auto vec_view1 = vec | seqan3::views::complement;
auto vec_view2 = seqan3::views::complement(vec);
std::cout << std::boolalpha << (std::ranges::equal(vec_view1, vec_view2)) << '\n'; // true
// both views "behave" like a collection of the elements 'T', 'G', 'C', 'C', 'A', 'G'
// but can be copied cheaply et cetera
}
algorithm
std::boolalpha
T boolalpha(T... args)
complement.hpp
Provides seqan3::views::complement.
std::cout
dna4.hpp
Provides seqan3::dna4, container aliases and string literals.
seqan3::views::complement
auto const complement
A view that converts a range of nucleotides to their complement.
Definition complement.hpp:64
iostream
seqan3::literals
The SeqAn namespace for literals.

Re-transform into a distinct container:

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <ranges>
#include <seqan3/alphabet/nucleotide/dna4.hpp>
#include <seqan3/alphabet/views/complement.hpp>
#include <seqan3/utility/range/to.hpp>
int main()
{
using namespace seqan3::literals;
seqan3::dna4_vector vec{"ACGGTC"_dna4};
auto vec_view2 = seqan3::views::complement(vec);
// re-convert to container
seqan3::dna4_vector complemented = vec_view2 | seqan3::ranges::to<seqan3::dna4_vector>();
assert(complemented == "TGCCAG"_dna4);
// also possible in one step
seqan3::dna4_vector reversed = vec | std::views::reverse | seqan3::ranges::to<seqan3::dna4_vector>();
assert(reversed == "CTGGCA"_dna4);
}
seqan3::ranges::to
seqan::stl::ranges::to to
Converts a range to a container. <dl class="no-api">This entity is not part of the SeqAn API....
Definition to.hpp:23
to.hpp
Provides seqan3::ranges::to.

Composability:

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <ranges>
#include <seqan3/alphabet/nucleotide/dna4.hpp>
#include <seqan3/alphabet/views/complement.hpp>
#include <seqan3/core/debug_stream.hpp>
int main()
{
using namespace seqan3::literals;
seqan3::dna4_vector vec{"ACGGTC"_dna4};
// views can be composed iteratively
auto vec_view3 = vec | std::views::reverse;
auto vec_view4 = vec_view3 | seqan3::views::complement;
// or in one line similar to the unix command line
auto vec_view5 = vec | seqan3::views::complement | std::views::reverse;
// vec_view4 and vec_view5 are the reverse complement of "ACGGTC": "GACCGT"
seqan3::debug_stream << vec_view4 << '\n'; // GACCGT
seqan3::debug_stream << vec_view5 << '\n'; // GACCGT
}
debug_stream.hpp
Provides seqan3::debug_stream and related types.
seqan3::debug_stream
debug_stream_type debug_stream
A global instance of seqan3::debug_stream_type.
Definition debug_stream.hpp:38

### Views vs view adaptors

When talking about views, two different entities are often conflated:

1. the view (this is the type that is a range and meets std::ranges::view; it is what we refer to with auto vec_view above)
2. the view adaptor (this is the functor that returns the actual view based on it's parameters, including the underlying range; in the above example std::views::reverse and seqan3::views::complement are view adaptors)

The view adaptor also facilitates the piping behaviour. It is the only entity that is publicly documented and the actual view type (the range type returned by the adaptor) is considered implementation defined. The properties of the returned range are however specified and documented as part of the adaptor, see below.

An exception to this rule are views that don't work on an underlying range and can only be placed at the beginning of a pipe of operations; they do not need an adaptor, because their constructor is sufficient. This is not relevant for the documentation, though, we always document views::foo, independent of whether views::foo is the adaptor that returns the "foo type" or whether views::foo is the "foo type".

### View properties

There are three view properties that are documented for a view, only if that view fulfils them:

Source-only views: Most views operate on an underlying range and return a (modified) range, i.e. they can be placed at the beginning, middle or end of a "pipe" of view operations. However, some views are limited to being at the front ("source"), e.g. std::views::empty, std::view::single and std::views::iota. These views are marked as "source-only" and have no urng_t column in the second table. The C++ standard calls these Range factories, which are utilities to create a view.

Sink-only views: The opposite of a source-only view. It can only be placed at the end of a pipe, i.e. it operates on views, but does not actually return a range (has no rrng_t column in the second table). The C++20 standard doesn't have this concept.

Deep views: Some views are declared as "deeps views". This means, that in case they are given a range-of-range as input (as opposed to just a range), they will apply their transformation on the innermost range (instead of the outermost range which would be default). Most alphabet-based transformations are defined as deep, but you can use seqan3::views::deep to make any view (adaptor) deep. See seqan3::views::deep for more details. The C++20 standard doesn't have this concept.

For all views the following are documented:

Concepts and traits | urng_t (underlying range type) | rrng_t (returned range type)
--- | --- | ---
std::ranges::input_range | [required] (usually) | [preserved|lost|guaranteed] (usually preserved)
std::ranges::forward_range | [required] (or not) | [preserved|lost|guaranteed]
std::ranges::bidirectional_range | [required] (or not) | [preserved|lost|guaranteed]
std::ranges::random_access_range | [required] (or not) | [preserved|lost|guaranteed]
std::ranges::contiguous_range | [required] (or not) | [preserved|lost|guaranteed] (usually lost)
std::ranges::viewable_range | [required] (usually) | [preserved|lost|guaranteed] (usually guaranteed)
std::ranges::view | [required] (or not) | [preserved|lost|guaranteed] (usually guaranteed)
std::ranges::sized_range | [required] (or not) | [preserved|lost|guaranteed]
std::ranges::common_range | [required] (or not) | [preserved|lost|guaranteed]
std::ranges::output_range | [required] (or not) | [preserved|lost|guaranteed]
seqan3::const_iterable_range | [required] (or not) | [preserved|lost]
std::ranges::range_reference_t | optionally a type or concept | optionally a type or concept

Underlying range requirements: All view adaptors that are not source-only make certain assumptions about their underlying range. The most basic assumption is that the range satisfies std::ranges::input_range, but many have stronger requirements, e.g. std::ranges::random_access_range. The concepts in the first block all build up on each other, i.e. requiring one implies requiring those above; the other concepts are mostly independent of each other. Most views also require that the underlying range satisfy std::ranges::viewable_range which means they don't accept temporary range objects other than views (because they are cheap to copy). Note that these being requirements means that they are the minimal set of properties assumed. Views may very well make use of stronger properties if available.

Return range guarantees: All view adaptors that are not sink-only return a range that meets at least std::ranges::input_range and also std::ranges::view (and conversely also std::ranges::viewable_range, because all views are viewable). Most views also preserve stronger properties, e.g. std::ranges::random_access_range, but this depends on the view. Some views may add properties not present on the input range.

- preserved in this context means that the returned range satisfies this concept if it is also satisfied by the underlying range.
- lost means that this concept is never satisfied by the returned range, independent of whether the underlying range supports it.
- guaranteed means that this concept is always satisfied by the returned range, independent of whether the underlying range supports it.

Underlying range's reference type: The reference type is the type the elements of the underlying range are accessed by (since dereferencing an iterator or calling operator[] returns the reference type). The reference type may or may not actually contain a & (see below). For many SeqAn specific views additional concept requirements are defined for the input range's reference type, e.g. seqan3::views::complement can only operate on ranges whose elements are nucleotides (meet seqan3::nucleotide_alphabet). In some case the type may even be a specific type or the result of a type trait.

Returned range's reference type: Conversely certain views make guarantees on the concepts satisfied by the return range's reference type or even always have a fixed type, e.g. seqan3::views::complement operates on nucleotides and of course also returns nucleotides and "std::ranges::range_reference_t<urng_t>" would imply that the reference type is the same. However, and this is important to note, the reference type of seqan3::views::complement has any actual & removed from the underlying ranges' reference type (if originally present), this goes hand-in-hand with std::ranges::output_range being lost → original elements cannot be written to through this view. This is because new elements are being generated. Other views like std::views::reverse also preserve the & (if originally present), because the elements in the return view still point to the elements in the original range (just in different order). This has the effect that through some combinations of views you can modify the elements in the original range (if all views in the pipe preserve std::ranges::output_range), but through others you can't.

See also
  https://en.cppreference.com/w/cpp/ranges

## Typedef Documentation

## chunk

using seqan3::views::chunk = seqan::stl::views::chunk

A view adaptor that divides a range into chunks.

This entity is not part of the SeqAn API. Do not rely on it in your applications. This is a implementation of the C++23 chunk_view. It will be replaced with std::views::chunk.

.

See also
  https://en.cppreference.com/w/cpp/ranges/chunk_view

## join_with

using seqan3::views::join_with = seqan::stl::views::join_with

A view adaptor that represents view consisting of the sequence obtained from flattening a view of ranges, with every element of the delimiter inserted in between elements of the view. The delimiter can be a single element or a view of elements.

This entity is not part of the SeqAn API. Do not rely on it in your applications. This is a implementation of the C++23 join_with_view. It will be replaced with ::std::views::join_with.

.

See also
  https://en.cppreference.com/w/cpp/ranges/join_with_view

## zip

using seqan3::views::zip = seqan::stl::views::zip

A view adaptor that takes several views and returns tuple-like values from every i-th element of each view.

This entity is not part of the SeqAn API. Do not rely on it in your applications. This is a implementation of the C++23 zip_view. It will be replaced with std::views::zip.

.

See also
  https://en.cppreference.com/w/cpp/ranges/zip_view

## Variable Documentation

## convert

template<typename out_t>

auto seqan3::views::convert

inline constexpr

A view that converts each element in the input range (implicitly or via static_cast).

Template Parameters

  urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]

Parameters

  [in] | urange | The range being processed. [parameter is omitted in pipe notation]

Returns
  A range of converted elements. See below for the properties of the returned range.

Header File

`#include <seqan3/utility/views/convert.hpp>`

### View properties

Concepts and traits | urng_t (underlying range type) | rrng_t (returned range type)
--- | --- | ---
std::ranges::input_range | required | preserved
std::ranges::forward_range |  | preserved
std::ranges::bidirectional_range |  | preserved
std::ranges::random_access_range |  | preserved
std::ranges::contiguous_range |  | lost¹
std::ranges::viewable_range | required | guaranteed
std::ranges::view |  | guaranteed
std::ranges::sized_range |  | preserved
std::ranges::common_range |  | preserved
std::ranges::output_range |  | lost¹
seqan3::const_iterable_range |  | preserved
std::ranges::range_reference_t | seqan3::convertible_to<out_t> | out_t

¹ These are preserved if out_t is the same as std::ranges::range_reference_t<urng_t>, i.e. no conversion takes place.

See the views submodule documentation for detailed descriptions of the view properties.

### Example

Convert from int to bool:

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <ranges>
#include <vector>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/utility/range/to.hpp>
#include <seqan3/utility/views/convert.hpp>
int main()
{
// convert from int to bool
std::vector<int> vec{7, 5, 0, 5, 0, 0, 4, 8, -3};
// pipe notation
seqan3::debug_stream << (vec | seqan3::views::convert<bool>) << '\n'; // [1,1,0,1,0,0,1,1,1]
// combinability
seqan3::debug_stream << (vec | seqan3::views::convert<bool> | std::views::reverse) << '\n'; // [1,1,1,0,0,1,0,1,1]
// function notation and immediate conversion to vector again
auto bool_vec = seqan3::views::convert<bool>(vec) | seqan3::ranges::to<std::vector<bool>>();
seqan3::debug_stream << std::boolalpha << (bool_vec == std::vector<bool>{1, 1, 0, 1, 0, 0, 1, 1, 1})
<< '\n'; // true
}
seqan3::views::convert
constexpr auto convert
A view that converts each element in the input range (implicitly or via static_cast).
Definition utility/views/convert.hpp:66
convert.hpp
Provides seqan3::views::convert.
vector

Convert from seqan3::dna15 to seqan3::dna5:

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <seqan3/alphabet/nucleotide/dna15.hpp>
#include <seqan3/alphabet/nucleotide/dna5.hpp>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/utility/views/convert.hpp>
int main()
{
using namespace seqan3::literals;
seqan3::dna15_vector vec2{"ACYGTN"_dna15};
seqan3::debug_stream << (vec2 | seqan3::views::convert<seqan3::dna5>) << '\n'; // ACNGTN
}
dna15.hpp
Provides seqan3::dna15, container aliases and string literals.
dna5.hpp
Provides seqan3::dna5, container aliases and string literals.

This entity is not part of the SeqAn API. Do not rely on it in your applications.

## elements

template<auto index>

auto seqan3::views::elements

inline constexpr

A view calling get on each element in a range.

Template Parameters

  size_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
  index | The index to get.

Parameters

  [in] | urange | The range being processed. [parameter is omitted in pipe notation]

Returns
  A range of elements where every element is the result of calling get<index> on the underlying element. See below for the properties of the returned range.

See also
  https://en.cppreference.com/w/cpp/ranges/elements_view

Header File

`#include <seqan3/utility/views/elements.hpp>`

This view may be used instead of std::view::elements when the underlying range contains seqan3 types, e.g. seqan3::qualified.

### View properties

Concepts and traits | urng_t (underlying range type) | rrng_t (returned range type)
--- | --- | ---
std::ranges::input_range | required | preserved
std::ranges::forward_range |  | preserved
std::ranges::bidirectional_range |  | preserved
std::ranges::random_access_range |  | preserved
std::ranges::contiguous_range |  | lost
std::ranges::viewable_range | required | preserved
std::ranges::view |  | preserved
std::ranges::sized_range |  | preserved
std::ranges::common_range |  | preserved
std::ranges::output_range |  | preserved
seqan3::const_iterable_range |  | preserved
std::ranges::range_reference_t | seqan3::tuple_like | std::tuple_element_t<index, std::ranges::range_reference_t<urng_t>>

See the views submodule documentation for detailed descriptions of the view properties.

### Example

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <vector>
#include <seqan3/alphabet/nucleotide/dna4.hpp>
#include <seqan3/alphabet/quality/aliases.hpp> // includes seqan3::dna4q
#include <seqan3/alphabet/quality/phred42.hpp>
#include <seqan3/alphabet/views/to_char.hpp>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/utility/views/elements.hpp>
int main()
{
using namespace seqan3::literals;
// Create a vector of dna4 quality composite alphabet.
std::vector<seqan3::dna4q> qv{{'A'_dna4, '0'_phred42},
{'C'_dna4, '1'_phred42},
{'G'_dna4, '2'_phred42},
{'T'_dna4, '3'_phred42}};
seqan3::debug_stream << (qv | seqan3::views::elements<0> | seqan3::views::to_char) << '\n'; // Prints [A,C,G,T]
seqan3::debug_stream << (qv | seqan3::views::elements<1> | seqan3::views::to_char) << '\n'; // Prints [!,",#,$]
}
aliases.hpp
Provides aliases for qualified.
elements.hpp
Provides seqan3::views::elements.
seqan3::views::to_char
auto const to_char
A view that calls seqan3::to_char() on each element in the input range.
Definition to_char.hpp:60
seqan3::views::elements
constexpr auto elements
A view calling get on each element in a range.
Definition elements.hpp:77
phred42.hpp
Provides seqan3::phred42 quality scores.
to_char.hpp
Provides seqan3::views::to_char.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## enforce_random_access

auto seqan3::views::enforce_random_access

inline constexpr

A view adaptor that converts a pseudo random access range to a std::ranges::random_access_range.

Template Parameters

  urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]

Parameters

  [in] | urange | The range being processed. [parameter is omitted in pipe notation]

Returns
  A std::ranges::random_access_range over the given range.

Header File

`#include <seqan3/utility/views/enforce_random_access.hpp>`

A pseudo random access range is a range whose iterator typically defines all the interfaces necessary to allow random access, but cannot guarantee accessing an arbitrary element in constant time. Thus, the highest category it can support by default is std::ranges::bidirectional_range. However, for many of these pseudo random access ranges better algorithms and data structures with sub-linear runtime complexities can be used (for example logarithmic time complexity). To enforce the faster behaviour of the range in a generic range-based context you can use this range adaptor, which will return a range that models std::ranges::random_access_range. Note, that this does not mean that the complexity of accessing an arbitrary element of the adapted range improves to constant time, but merely all syntactical requirements are fulfilled including the iterator tag.

### View properties

range concepts and reference_t | urng_t (underlying range type) | rrng_t (returned range type)
--- | --- | ---
std::ranges::input_range | required | guaranteed
std::ranges::forward_range | required | guaranteed
std::ranges::bidirectional_range |  | guaranteed
std::ranges::random_access_range |  | guaranteed
std::ranges::contiguous_range |  | preserved
std::ranges::viewable_range | required | guaranteed
std::ranges::view |  | guaranteed
std::ranges::sized_range |  | preserved
std::ranges::common_range |  | preserved
std::ranges::output_range |  | preserved
seqan3::const_iterable_range |  | preserved
std::ranges::range_reference_t |  | std::ranges::range_reference_t<urng_t>

See the views submodule documentation for detailed descriptions of the view properties.

This adaptor requires that the underlying range models either std::ranges::random_access_range or seqan3::pseudo_random_access_range.

### Return type

urng_t (underlying range type) | rrng_t (returned range type)
--- | ---
std::ranges::random_access_range | std::ranges::ref_view<urng_t>
seqan3::pseudo_random_access_range | seqan3::detail::view_enforce_random_access

The adaptor returns exactly the type specified above. In the second case a view is returned whose iterator wraps the iterator of the underlying range and adapts all of its functionality but overwrites the iterator category to be std::random_access_iterator_tag.

### Example

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <string>
#include <seqan3/alignment/decorator/gap_decorator.hpp>
#include <seqan3/alphabet/nucleotide/dna4.hpp>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/utility/views/enforce_random_access.hpp>
int main()
{
using namespace seqan3::literals;
// A gap decorator is a pseudo random access range using logarithmic time complexity internally.
auto seq = "ACGTACGACT"_dna4;
seqan3::gap_decorator aligned_seq{seq};
// It does not fulfill random access semantics because it does not allow constant time access to arbitrary
// elements in the range. Thus, it is only a bidirectional range by default.
static_assert(std::ranges::bidirectional_range<decltype(aligned_seq)>);
static_assert(!std::ranges::random_access_range<decltype(aligned_seq)>);
// The default interface models at most std::bidirectional_range.
auto it = std::ranges::begin(aligned_seq); // Returned iterator models std::bidirectional_iterator.
std::ranges::advance(it, 3); // Advancing the iterator takes linear time.
seqan3::debug_stream << *it << '\n'; // "T"
// After adapting it with enforce_random_access, the returned range models std::random_access_range.
auto aligned_seq_ra = aligned_seq | seqan3::views::enforce_random_access;
// The pesudo_random_access wrapper returns a view that enforces random_access.
// Note that this does not mean that the semantic requirements have been changed. Only all syntactical
// interfaces for the std::ranges::random_access_range are modeled now by the returned view.
// Access time still depends on the underlying range.
static_assert(std::ranges::random_access_range<decltype(aligned_seq_ra)>);
auto it_ra = std::ranges::begin(aligned_seq_ra); // Returned iterator models std::random_access_iterator.
std::ranges::advance(it_ra, 3); // Advancing the iterator takes now logarithmic time instead linear.
seqan3::debug_stream << *it_ra << '\n'; // "T"
}
seqan3::gap_decorator
A gap decorator allows the annotation of sequences with gap symbols while leaving the underlying sequ...
Definition gap_decorator.hpp:78
enforce_random_access.hpp
Provides seqan3::views::enforce_random_access.
gap_decorator.hpp
Provides seqan3::gap_decorator.
seqan3::field::seq
@ seq
The "sequence", usually a range of nucleotides or amino acids.
Definition record.hpp:62
seqan3::views::enforce_random_access
constexpr auto enforce_random_access
A view adaptor that converts a pseudo random access range to a std::ranges::random_access_range.
Definition enforce_random_access.hpp:351
string

### Complexity

Construction of the returned view is in .

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## interleave

auto seqan3::views::interleave

inline constexpr

A view that interleaves a given range into another range at regular intervals.

Template Parameters

  urng_t | The type of the range being processed.
  inserted_rng_t | The type of the range being inserted.

Parameters

  [in] | urange | The range being processed.
  [in] | inserted_range | The range being inserted.
  [in] | step_size | A value of size_type which indicates the interval to insert the inserted_range.

Returns
  A range with the second range inserted at regular intervals. See below for properties of said range.

Header File

`#include <seqan3/utility/views/interleave.hpp>`

This view can be used to insert one range into another range at regular intervals. It behaves essentially like | std::views::chunk(step_size) | seqan3::views::join_with(inserted_range) except that for input that models std::ranges::random_access_range and std::ranges::sized_range a more efficient data structure is returned (otherwise it returns exactly the above combination of views).

### View properties

Concepts and traits | urng_t (underlying range type) | rrng_t (returned range type)
--- | --- | ---
std::ranges::input_range | required | preserved
std::ranges::forward_range | required | preserved
std::ranges::bidirectional_range | required | preserved
std::ranges::random_access_range | required | preserved
std::ranges::contiguous_range |  | lost
std::ranges::viewable_range | required | guaranteed
std::ranges::view |  | guaranteed
std::ranges::sized_range | required | preserved
std::ranges::common_range |  | preserved
std::ranges::output_range |  | preserved
seqan3::const_iterable_range |  | preserved
std::ranges::range_reference_t |  | std::ranges::range_reference_t<urng_t>

If above requirements are not met, this adaptor forwards to | seqan3::views::chunk(step_size) | seqan3::views::join_with(inserted_range) which returns a view with the following properties:

Concepts and traits | urng_t (underlying range type) | rrng_t (returned range type)
--- | --- | ---
std::ranges::input_range | required | preserved
std::ranges::forward_range | required | lost
std::ranges::bidirectional_range |  | lost
std::ranges::random_access_range |  | lost
std::ranges::contiguous_range |  | lost
std::ranges::viewable_range | required | guaranteed
std::ranges::view |  | guaranteed
std::ranges::sized_range |  | lost
std::ranges::common_range |  | lost
std::ranges::output_range |  | lost
seqan3::const_iterable_range |  | lost
std::ranges::range_reference_t |  | std::ranges::range_value_t<urng_t>

- urng_t is the type of the range modified by this view (input).
- rrng_t is the type of the range returned by this view.

See the views submodule documentation for detailed descriptions of the view properties.

### Example

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <string>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/utility/views/interleave.hpp>
int main()
{
std::string u{"FOOBARBAXBAT"};
std::string i{"in"};
size_t s = 3;
auto v = u | seqan3::views::interleave(s, i);
seqan3::debug_stream << v << '\n'; // prints FOOinBARinBAXinBAT
}
std::string
seqan3::views::interleave
constexpr auto interleave
A view that interleaves a given range into another range at regular intervals.
Definition interleave.hpp:374
interleave.hpp
Provides seqan3::views::interleave.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## pairwise_combine

auto seqan3::views::pairwise_combine

inline constexpr

A view adaptor that generates all pairwise combinations of the elements of the underlying range.

Template Parameters

  urng_t | The type of the range being processed. See below for requirements.

Parameters

  [in] | urange | The range being processed.

Returns
  A view over all pairwise combinations of the elements of the underlying range. See below for the properties of the returned range.

Header File

`#include <seqan3/utility/views/pairwise_combine.hpp>`

This view generates two-element tuples representing all combinations of the elements of the underlying range (the order of the elements is undefined). If the underlying range has less than two elements the returned range is empty, otherwise the size of the returned range corresponds to the binomial coefficient n choose 2, where n is the size of the underlying range. The reference type of this range is a tuple over the reference type of the underlying range. In order to receive the end iterator in constant time an iterator pointing to the last element of the underlying range will be cached upon construction of this view. This construction takes linear time for underlying ranges that do not model std::ranges::bidirectional_range.

### Iterator

The returned iterator from begin does not model Cpp17Iterator since it does not return a reference to the represented type but a prvalue. Thus this iterator might not be usable within some legacy algorithms of the STL. But it is guaranteed to work with the ranges algorithms.

### View properties

Concepts and traits | urng_t (underlying range type) | rrng_t (returned range type)
--- | --- | ---
std::ranges::input_range | required | preserved
std::ranges::forward_range | required | preserved
std::ranges::bidirectional_range |  | preserved
std::ranges::random_access_range |  | preserved
std::ranges::contiguous_range |  | lost
std::ranges::viewable_range | required | guaranteed
std::ranges::view |  | guaranteed
std::ranges::sized_range |  | preserved
std::ranges::common_range | required | guaranteed
std::ranges::output_range |  | preserved
seqan3::const_iterable_range |  | preserved
std::ranges::range_reference_t |  | common_tuple<std::ranges::range_reference_t<urng_t>, std::ranges::range_reference_t<urng_t>>

See the views submodule documentation for detailed descriptions of the view properties.

### Thread safety

Concurrent access to this view, e.g. while iterating over it, is thread-safe and must not be protected externally.

### Example

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <vector>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/utility/views/pairwise_combine.hpp>
int main()
{
std::vector vec{'a', 'b', 'c', 'a'};
for (auto res : vec | seqan3::views::pairwise_combine)
{
seqan3::debug_stream << res << '\n';
}
// Possible Output:
// (a,b)
// (a,c)
// (a,a)
// (b,c)
// (b,a)
// (c,a)
}
seqan3::views::pairwise_combine
constexpr auto pairwise_combine
A view adaptor that generates all pairwise combinations of the elements of the underlying range.
Definition pairwise_combine.hpp:647
pairwise_combine.hpp
Provides seqan3::views::pairwise_combine.

Attention
  This view cannot be chained immediately with an infinite range, because upon construction it will take forever to reach the last element of the view.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

## repeat

detail::repeat_fn seqan3::views::repeat

inline constexpr

A view factory that repeats a given value infinitely.

Template Parameters

  value_t | The type of value to repeat wrapped in a std::views::single; must model std::copy_constructible.

Parameters

  [in] | value | The value to repeat.

Returns
  An infinite range over value.

Header File

`#include <seqan3/utility/views/repeat.hpp>`

### View properties

This view is source-only, it can only be at the beginning of a pipe of range transformations.

Concepts and traits | rrng_t (returned range type)
--- | ---
std::ranges::input_range | guaranteed
std::ranges::forward_range | guaranteed
std::ranges::bidirectional_range | guaranteed
std::ranges::random_access_range | guaranteed
std::ranges::contiguous_range |
std::ranges::viewable_range | guaranteed
std::ranges::view | guaranteed
std::ranges::sized_range |
std::ranges::common_range |
std::ranges::output_range | guaranteed
seqan3::const_iterable_range | guaranteed
std::ranges::range_reference_t | std::remove_reference_t<value_t> &

See the views submodule documentation for detailed descriptions of the view properties.

Attention
  The given value to repeat is always copied into the range.

### Example

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <ranges>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/utility/views/repeat.hpp>
int main()
{
auto v = seqan3::views::repeat('A');
seqan3::debug_stream << *std::ranges::begin(v) << '\n'; // prints 'A'
seqan3::debug_stream << v[12355] << '\n'; // also prints 'A'. It always prints 'A'
v[1345] = 'C';
// Now it always prints 'C'
seqan3::debug_stream << *std::ranges::begin(v) << '\n'; // prints 'C'
seqan3::debug_stream << v[12355] << '\n'; // prints 'C'
}
seqan3::views::repeat
constexpr detail::repeat_fn repeat
A view factory that repeats a given value infinitely.
Definition repeat.hpp:344
repeat.hpp
Provides the seqan3::views::repeat.

## repeat_n

auto seqan3::views::repeat_n

inline constexpr

A view factory that repeats a given value n times.

Template Parameters

  value_t | The type of value to repeat; must be std::copy_constructible.

Parameters

  [in] | value | The value to repeat.
  [in] | count | The number of times to repeat value.

Returns
  A range of size count, where each element equals value.

Header File

`#include <seqan3/utility/views/repeat_n.hpp>`

### View properties

This view is source-only, it can only be at the beginning of a pipe of range transformations.

Concepts and traits | rrng_t (returned range type)
--- | ---
std::ranges::input_range | guaranteed
std::ranges::forward_range | guaranteed
std::ranges::bidirectional_range | guaranteed
std::ranges::random_access_range | guaranteed
std::ranges::contiguous_range |
std::ranges::viewable_range | guaranteed
std::ranges::view | guaranteed
std::ranges::sized_range | guaranteed
std::ranges::common_range |
std::ranges::output_range | guaranteed
seqan3::const_iterable_range | guaranteed
std::ranges::range_reference_t | std::remove_reference_t<value_t> &

See the views submodule documentation for detailed descriptions of the view properties.

Attention
  The given value to repeat is always copied into the range.

### Example

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <ranges>
#include <string>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/utility/views/repeat_n.hpp>
int main()
{
auto v = seqan3::views::repeat_n(std::string{"foo"}, 5);
seqan3::debug_stream << v.size() << '\n'; // prints 5
seqan3::debug_stream << v << '\n'; // prints ["foo", "foo", "foo", "foo", "foo"]
v[0] = std::string{"foobar"};
// Now it always prints "foobar"
seqan3::debug_stream << *std::ranges::begin(v) << '\n'; // prints "foobar"
seqan3::debug_stream << v.size() << '\n'; // prints 5; Note: the size cannot be changed anymore
}
seqan3::views::repeat_n
constexpr auto repeat_n
A view factory that repeats a given value n times.
Definition repeat_n.hpp:88
repeat_n.hpp
Provides seqan3::views::repeat_n.

## single_pass_input

auto seqan3::views::single_pass_input

inline constexpr

A view adapter that decays most of the range properties and adds single pass behavior.

Template Parameters

  urng_t | The type of the range being processed. See below for requirements.

Parameters

  [in] | urange | The range being processed.

Returns
  A range with single pass input behavior. See below for the properties of the returned range.

Header File

`#include <seqan3/utility/views/single_pass_input.hpp>`

This view adds single-pass semantics to any input view. This means, that begin always returns the iterator to the current location in the underlying range after k elements have been already consumed and not to the begin of the underlying range, i.e. it mirrors the behavior of an input stream. Note, the view updates an internal state after moving the associated iterator. Thus, the const begin and const end are explicitly deleted.

### View properties

Concepts and traits | urng_t (underlying range type) | rrng_t (returned range type)
--- | --- | ---
std::ranges::input_range | required | preserved
std::ranges::forward_range |  | lost
std::ranges::bidirectional_range |  | lost
std::ranges::random_access_range |  | lost
std::ranges::contiguous_range |  | lost
std::ranges::viewable_range | required | guaranteed
std::ranges::view |  | guaranteed
std::ranges::sized_range |  | lost
std::ranges::common_range |  | lost
std::ranges::output_range |  | lost
std::ranges::borrowed_range |  | preserved
seqan3::const_iterable_range |  | lost
std::ranges::range_reference_t |  | std::ranges::range_reference_t<urng_t>

See the views submodule documentation for detailed descriptions of the view properties.

### Thread safety

Concurrent access to this view, e.g. while iterating over it, is not thread-safe and must be protected externally.

### Example

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <string>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/utility/views/single_pass_input.hpp>
int main()
{
std::string str{"hello"};
auto v = str | seqan3::views::single_pass_input;
auto b = v.begin();
seqan3::debug_stream << *b << '\n'; // prints 'h'
seqan3::debug_stream << *(++b) << '\n'; // prints 'e'
seqan3::debug_stream << *(++b) << '\n'; // prints 'l'
seqan3::debug_stream << *(++b) << '\n'; // prints 'l'
seqan3::debug_stream << *(++b) << '\n'; // prints 'o'
}
seqan3::views::single_pass_input
constexpr auto single_pass_input
A view adapter that decays most of the range properties and adds single pass behavior.
Definition single_pass_input.hpp:346
single_pass_input.hpp
Provides seqan3::views::single_pass_input.

## slice

auto seqan3::views::slice

inline constexpr

A view adaptor that returns a half-open interval on the underlying range.

Template Parameters

  urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]

Parameters

  [in] | urange | The range being processed. [parameter is omitted in pipe notation]
  [in] | begin_pos | The beginning of the interval (index of first element returned).
  [in] | end_pos | The end of the interval (index behind the last element returned).

Returns
  Up to end_pos - begin_pos elements of the underlying range.

Exceptions

  std::invalid_argument | If end_pos < begin_pos.

Header File

`#include <seqan3/utility/views/slice.hpp>`

### View properties

Concepts and traits | urng_t (underlying range type) | rrng_t (returned range type)
--- | --- | ---
std::ranges::input_range | required | preserved
std::ranges::forward_range |  | preserved
std::ranges::bidirectional_range |  | preserved
std::ranges::random_access_range |  | preserved
std::ranges::contiguous_range |  | preserved
std::ranges::viewable_range | required | guaranteed
std::ranges::view |  | guaranteed
std::ranges::sized_range |  | preserved
std::ranges::common_range |  | preserved
std::ranges::output_range |  | preserved
seqan3::const_iterable_range |  | preserved
std::ranges::range_reference_t |  | std::ranges::range_reference_t<urng_t>

See the views submodule documentation for detailed descriptions of the view properties.

This adaptor is a combination of std::views::drop and std::views::take.

If begin_pos is larger than the size of the underlying range an empty range is returned. If end_pos is larger than the size of the underlying range less elements are returned.

If end_pos < begin_pos an exception of type std::invalid_argument is thrown.

### Return type

urng_t (underlying range type) | rrng_t (returned range type)
--- | ---
std::basic_string const & or std::basic_string_view | std::basic_string_view
std::ranges::borrowed_range && std::ranges::sized_range && std::ranges::contiguous_range | std::span
std::ranges::borrowed_range && std::ranges::sized_range && std::ranges::random_access_range | std::ranges::subrange
else | implementation defined type

The adaptor returns exactly the type specified above.

### Complexity

Construction of the returned view is in for some views, see std::views::drop.

### Example

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <ranges> // provides std::views::reverse
#include <string>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/utility/views/slice.hpp> // provides views::slice
int main()
{
std::string s{"foobar"};
auto v = s | seqan3::views::slice(1, 4);
seqan3::debug_stream << v << '\n'; // "oob"
auto v2 = s | std::views::reverse | seqan3::views::slice(1, 4);
seqan3::debug_stream << v2 << '\n'; // "abo"
}
seqan3::views::slice
constexpr auto slice
A view adaptor that returns a half-open interval on the underlying range.
Definition slice.hpp:137
slice.hpp
Provides seqan3::views::slice.

## type_reduce

auto seqan3::views::type_reduce

inline constexpr

A view adaptor that behaves like std::views::all, but type erases certain ranges.

Template Parameters

  urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]

Parameters

  [in] | urange | The range being processed. [parameter is omitted in pipe notation]

Returns
  The range turned into a view.

Header File

`#include <seqan3/utility/views/view_type_reduce.hpp>`

### View properties

Concepts and traits | urng_t (underlying range type) | rrng_t (returned range type)
--- | --- | ---
std::ranges::input_range | required | preserved
std::ranges::forward_range |  | preserved
std::ranges::bidirectional_range |  | preserved
std::ranges::random_access_range |  | preserved
std::ranges::contiguous_range |  | preserved
std::ranges::viewable_range | required | guaranteed
std::ranges::view |  | guaranteed
std::ranges::sized_range |  | preserved
std::ranges::common_range |  | preserved
std::ranges::output_range |  | preserved
seqan3::const_iterable_range |  | preserved
std::ranges::range_reference_t |  | std::ranges::range_reference_t<urng_t>

See the views submodule documentation for detailed descriptions of the view properties.

### Return type

urng_t (underlying range type) | rrng_t (returned range type)
--- | ---
std::ranges::view | urng_t
std::basic_string const & or std::basic_string_view | std::basic_string_view
std::ranges::borrowed_range && std::ranges::sized_range && std::ranges::contiguous_range | std::span
std::ranges::borrowed_range && std::ranges::sized_range && std::ranges::random_access_range | std::ranges::subrange
else | std::ranges::ref_view<urng_t>

This adaptor is different from std::views::all in that it performs type erasure for some underlying ranges; std::views::all always returns std::ranges::ref_view<urng_t> or the type itself if it already is a view.

### Example

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <string>
#include <vector>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/utility/views/type_reduce.hpp>
int main()
{
std::string const vec{"foobar"};
auto v = vec | seqan3::views::type_reduce; // pipe notation; v is of type std::string_view
seqan3::debug_stream << v << '\n'; // "foobar"
std::vector vec2{1, 2, 3};
auto v2 = seqan3::views::type_reduce(vec2); // functional notation; v2 is of type std::span
seqan3::debug_stream << v2 << '\n'; // "[1, 2, 3]"
}
seqan3::views::type_reduce
constexpr auto type_reduce
A view adaptor that behaves like std::views::all, but type erases certain ranges.
Definition type_reduce.hpp:147
type_reduce.hpp
Provides seqan3::views::type_reduce.

This entity is experimental and subject to change in the future. Experimental since version 3.1.

Hide me