SeqAn3  3.0.1
The Modern C++ library for sequence analysis.
Classes
Views
Range

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...
 

General purpose views

const auto seqan3::views::as_const
 A view that provides only const & to elements of the underlying range. More...
 
constexpr auto seqan3::views::async_input_buffer
 A view adapter that returns a concurrent-queue-like view over the underlying range. More...
 
template<typename out_t >
const auto seqan3::views::convert
 A view that converts each element in the input range (implicitly or via static_cast). More...
 
constexpr auto seqan3::views::drop
 A view adaptor that returns all elements after n from the underlying range (or an empty range if the underlying range is shorter). More...
 
constexpr auto seqan3::views::enforce_random_access
 A view adaptor that converts a pseudo random access range to a std::random_access_range. More...
 
template<auto index>
const auto seqan3::views::get
 A view calling std::get on each element in a range. More...
 
constexpr auto seqan3::views::interleave
 A view that interleaves a given range into another range at regular intervals. More...
 
constexpr auto seqan3::views::istreambuf
 A view factory that returns a view over the stream buffer of an input stream. More...
 
const auto seqan3::views::move
 A view that turns lvalue-references into rvalue-references. More...
 
constexpr auto seqan3::views::pairwise_combine
 A view adaptor that generates all pairwise combinations of the elements of the underlying range. More...
 
constexpr auto seqan3::views::persist
 A view adaptor that wraps rvalue references of non-views. More...
 
constexpr detail::repeat_fn seqan3::views::repeat
 A view factory that repeats a given value infinitely. More...
 
constexpr auto seqan3::views::repeat_n
 A view factory that repeats a given value n times. More...
 
constexpr auto seqan3::views::single_pass_input
 A view adapter that decays most of the range properties and adds single pass behavior. More...
 
constexpr auto seqan3::views::slice
 A view adaptor that returns a half-open interval on the underlying range. More...
 
constexpr auto seqan3::views::take
 A view adaptor that returns the first size elements from the underlying range (or less if the underlying range is shorter). More...
 
constexpr auto seqan3::views::take_exactly
 A view adaptor that returns the first size elements from the underlying range (or less if the underlying range is shorter); also provides size information. More...
 
constexpr auto seqan3::views::take_exactly_or_throw
 A view adaptor that returns the first size elements from the underlying range and also exposes size information; throws if the underlying range is smaller than size. More...
 
constexpr auto seqan3::views::take_line = views::take_until_and_consume(is_char<'\r'> || is_char<'\n'>)
 A view adaptor that returns a single line from the underlying range or the full range if there is no newline. More...
 
constexpr auto seqan3::views::take_line_or_throw = views::take_until_or_throw_and_consume(is_char<'\r'> || is_char<'\n'>)
 A view adaptor that returns a single line from the underlying range (throws if there is no end-of-line). More...
 
constexpr auto seqan3::views::take_until
 A view adaptor that returns elements from the underlying range until the functor evaluates to true (or the end of the underlying range is reached). More...
 
constexpr auto seqan3::views::take_until_or_throw
 A view adaptor that returns elements from the underlying range until the functor evaluates to true (throws if the end of the underlying range is reached). More...
 
constexpr auto seqan3::views::take_until_and_consume
 A view adaptor that returns elements from the underlying range until the functor evaluates to true (or the end of the underlying range is reached; consumes end in single-pass ranges). More...
 
constexpr auto seqan3::views::take_until_or_throw_and_consume
 A view adaptor that returns elements from the underlying range until the functor evaluates to true (throws if the end of the underlying range is reached; consumes end in single-pass ranges). More...
 
const auto seqan3::views::to_lower
 A view that calls seqan3::to_lower() on each element in the input range. More...
 
const auto seqan3::views::to_upper
 A view that calls seqan3::to_upper() on each element in the input range. More...
 
constexpr auto seqan3::views::type_reduce
 A view adaptor that behaves like std::views::all, but type erases certain ranges. More...
 

Alphabet related views

template<alphabet alphabet_type>
const auto seqan3::views::char_to
 A view over an alphabet, given a range of characters. More...
 
const auto seqan3::views::complement
 A view that converts a range of nucleotides to their complement. More...
 
constexpr auto seqan3::views::kmer_hash
 Computes hash values for each position of a range via a given shape. More...
 
template<typename alphabet_type >
const auto seqan3::views::rank_to
 A view over an alphabet, given a range of ranks. More...
 
const auto seqan3::views::to_char
 A view that calls seqan3::to_char() on each element in the input range. More...
 
const auto seqan3::views::to_rank
 A view that calls seqan3::to_rank() on each element in the input range. More...
 
constexpr auto seqan3::views::translate_single
 A view that translates nucleotide into aminoacid alphabet for one of the six frames. More...
 
constexpr auto seqan3::views::translate
 A view that translates nucleotide into aminoacid alphabet with 1, 2, 3 or 6 frames. More...
 
constexpr auto seqan3::views::translate_join
 A view that translates nucleotide into aminoacid alphabet with 1, 2, 3 or 6 frames. Input and output range are always two-dimensional. More...
 
constexpr auto seqan3::views::trim
 A view that does quality-threshold trimming on a range of seqan3::quality_alphabet. More...
 

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 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

Example

Functional and pipe notations:

#include <seqan3/alphabet/nucleotide/dna4.hpp>
#include <seqan3/range/views/complement.hpp>
int main()
{
using seqan3::operator""_dna4;
seqan3::dna4_vector vec{"ACGGTC"_dna4};
// these are synonymous:
auto vec_view1 = vec | seqan3::views::complement;
auto vec_view2 = seqan3::views::complement(vec);
// both views "behave" like a collection of the elements 'T', 'G', 'C', 'C', 'A', 'G'
// but can be copied cheaply et cetera
}

Re-transform into a distinct container:

#include <seqan3/alphabet/nucleotide/dna4.hpp>
#include <seqan3/range/views/complement.hpp>
#include <seqan3/range/views/to.hpp>
#include <seqan3/std/ranges>
int main()
{
using seqan3::operator""_dna4;
seqan3::dna4_vector vec{"ACGGTC"_dna4};
auto vec_view2 = seqan3::views::complement(vec);
// re-convert to container
seqan3::dna4_vector complemented = vec_view2 | seqan3::views::to<seqan3::dna4_vector>;
assert(complemented == "TGCCAG"_dna4);
// also possible in one step
seqan3::dna4_vector reversed = vec | std::views::reverse | seqan3::views::to<seqan3::dna4_vector>;
assert(reversed == "CTGGCA"_dna4);
}

Composability:

#include <seqan3/alphabet/nucleotide/dna4.hpp>
#include <seqan3/range/views/complement.hpp>
#include <seqan3/std/ranges>
int main()
{
using seqan3::operator""_dna4;
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"
}

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 views::reverse and 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 fulfills 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::single, ranges::view::concat and std::views::ints. These views are marked as "source-only" and have no urng_t column in the second table.

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).

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.

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). A prominent exception to the latter is views::persist that exists exactly for this purpose. 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 also add properties not present on the input range, e.g. the range returned by std::views::take_exactly meets std::ranges::sized_range, independent of whether this was met by the input range.

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_check). 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 "seqan3::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 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://ericniebler.github.io/range-v3/index.html#range-views

Variable Documentation

◆ as_const

const auto seqan3::views::as_const
inline

A view that provides only const & to elements of the underlying range.

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
Returns
A range of const-protected elements.

Header File

#include <seqan3/range/views/as_const.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 lost
seqan3::const_iterable_range preserved
std::semiregular preserved
std::ranges::range_reference_t t & -> t const & but t -> t

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

Example

#include <string>
#include <seqan3/range/views/as_const.hpp>
#include <seqan3/std/ranges>
template <std::ranges::random_access_range rng_t>
void foobar(rng_t const & range)
{
range[0] = 'A';
}
int main()
{
std::string s{"CCC"};
auto v0 = std::views::all(s);
foobar(v0); // this is valid and will update s to "ACC"
// because const-ness of view does not protect elements
auto v1 = seqan3::views::as_const(s);
// foobar(v1); // this is invalid, views::as_const protects elements
}

◆ async_input_buffer

constexpr auto seqan3::views::async_input_buffer
inlineconstexpr

A view adapter that returns a concurrent-queue-like view over the underlying range.

Template Parameters
urng_tThe type of the range being processed. See below for requirements.
Parameters
[in,out]urangeThe range being processed.
[in]buffer_sizeSize of the buffer. Choose the size (> 0) depending on the expected work per element.
Returns
A view that pre-fetches elements from the underlying range and provides a thread-safe interface. See below for the properties of the returned range.

Header

#include <seqan3/range/views/async_input_buffer.hpp>

Summary

This view spawns a background thread that pre-fetches elements from the underlying range and stores them in a concurrent queue. Iterating over this view then pops elements out of the queue and returns them. This is primarily useful if dereferencing/incrementing the iterator of the underlying range is expensive, e.g. with SeqAn files which lazily perform I/O.

Another advantage of this view is that multiple iterators can be created that are safe to iterate individually, even from different threads, i.e. you can use multiple threads to iterate safely over a single-pass input view with the added benefit of background pre-fetching.

In technical terms: this view facilitates a single-producer, multi-consumer design; it's a range interface over a concurrent queue.

Size of the buffer

The buffer_size parameter should be chosen depending on the expected work per element, e.g. if the underlying range is an input file over short reads, a buffer size of 100 or 1000 could be beneficial; if on the other hand the file contains genome-sized sequences, it would be better to buffer only a single sequence (buffering 100 sequences would result in the entire file being preloaded and likely consuming significant memory).

Range consumption

This view always moves elements from the underlying range into its buffer which means that the elements in the underlying range will be invalidated! For underlying ranges that are single-pass, this makes no difference, but it might be unexpected for multi-pass ranges (std::ranges::forward_range).

Typically this adaptor is used when you want to consume the entire underlying range. Destructing this view before all elements have been read will also stop the thread that moves object from the underlying range. In general, it is not safe to access the underlying range in other contexts once it has been passed to seqan3::views::async_input_buffer.

Note that in addition to the buffer of the view, every iterator has its own one-element-buffer. Dereferencing the iterator returns a reference to the element in the buffer, usually you will want to move this element out of the buffer with std::move std::ranges::iter_move. Incrementing the iterator refills the buffer from the queue inside the view (which in turn is then refilled from the underlying range).

View properties

concepts and reference type 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
seqan3::const_iterable_range lost
std::ranges::range_reference_t seqan3::value_type_t<urng_t> &
std::iterator_traits ::iterator_category none

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

Thread safety

The following operations are thread-safe:

  • calling .begin() and .end() on the view returned by this adaptor;
  • calling operators on the different iterator objects.

Calling operators on the same iterator object from different threads is not safe, i.e. you can pass the view to different threads by reference, and have each of those threads call begin() on the view and then perform operations (dereference, increment...) on that iterator from the respective thread; but you cannot call begin() in a parent thread, pass the iterator to different threads and operate on that concurrently.

Example

#include <cstdlib> // std::rand
#include <future> // std::async
#include <string> // std::string
#include <seqan3/core/debug_stream.hpp> // seqan3::debug_stream
#include <seqan3/io/sequence_file/input.hpp> // seqan3::sequence_file_input
#include <seqan3/range/views/async_input_buffer.hpp> // seqan3::views::async_input_buffer
std::string fasta_file =
R"(> seq1
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq2
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq3
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq4
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq5
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq6
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq7
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq8
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq9
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq10
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq11
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
> seq12
ACGACTACGACGATCATCGATCGATCGATCGATCGATCGATCGATCGTACTACGATCGATCG
)";
int main()
{
// initialise random number generator, only needed for demonstration purposes
std::srand(std::time(nullptr));
// create an input file from the string above
seqan3::sequence_file_input fin{std::istringstream{fasta_file}, seqan3::format_fasta{}};
// create the async buffer around the input file
// spawns a background thread that tries to keep four records in the buffer
auto v = fin | seqan3::views::async_input_buffer(4);
// create a lambda function that iterates over the async buffer when called
// (the buffer gets dynamically refilled as soon as possible)
auto worker = [&v] ()
{
for (auto & record : v)
{
// pretend we are doing some work
std::this_thread::sleep_for(std::chrono::milliseconds(std::rand() % 1000));
// print current thread and sequence ID
seqan3::debug_stream << "Thread: " << std::this_thread::get_id() << '\t'
<< "Seq: " << seqan3::get<seqan3::field::id>(record) << '\n';
}
};
// launch two threads and pass the lambda function to both
auto f0 = std::async(std::launch::async, worker);
auto f1 = std::async(std::launch::async, worker);
}

Running the snippet could yield the following output:

Thread: 0x80116bf00 Seq: seq2
Thread: 0x80116bf00 Seq: seq3
Thread: 0x80116ba00 Seq: seq1
Thread: 0x80116bf00 Seq: seq4
Thread: 0x80116bf00 Seq: seq6
Thread: 0x80116ba00 Seq: seq5
Thread: 0x80116bf00 Seq: seq7
Thread: 0x80116ba00 Seq: seq8
Thread: 0x80116bf00 Seq: seq9
Thread: 0x80116bf00 Seq: seq11
Thread: 0x80116bf00 Seq: seq12
Thread: 0x80116ba00 Seq: seq10

This shows that indeed elements from the underlying range are processed non-sequentially, that there are two threads and that work is "balanced" between them (one thread processed more element than the other, because its "work" per item happened to be smaller).

Note that you might encounter jumbled output if by chance two threads write to the stream at the exact same time.

If you remove the line starting with auto f1 = ... you will get sequential processing:

Thread: 0x80116aa00 Seq: seq1
Thread: 0x80116aa00 Seq: seq2
Thread: 0x80116aa00 Seq: seq3
Thread: 0x80116aa00 Seq: seq4
Thread: 0x80116aa00 Seq: seq5
Thread: 0x80116aa00 Seq: seq6
Thread: 0x80116aa00 Seq: seq7
Thread: 0x80116aa00 Seq: seq8
Thread: 0x80116aa00 Seq: seq9
Thread: 0x80116aa00 Seq: seq10
Thread: 0x80116aa00 Seq: seq11
Thread: 0x80116aa00 Seq: seq12

Note that even if you have a single processing thread, using this view can still improve performance measurably, because loading of the elements into the buffer (which reads input from disk) happens in a background thread.

◆ char_to

template<alphabet alphabet_type>
const auto seqan3::views::char_to
inline

A view over an alphabet, given a range of characters.

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
alphabet_tThe alphabet to convert to; must satisfy seqan3::alphabet.
Parameters
[in]urangeThe 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/range/views/char_to.hpp>

View properties

This view is a deep view Given a range-of-range as input (as opposed to just a range), it will apply the transformation on the innermost range (instead of the outermost range).

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::alphabet_char_t<alphabet_t> alphabet_t

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

Example

#include <string>
#include <seqan3/alphabet/nucleotide/dna4.hpp>
#include <seqan3/alphabet/nucleotide/dna5.hpp>
#include <seqan3/range/views/char_to.hpp>
int main()
{
std::string s{"ACTTTGATAN"};
auto v1 = s | seqan3::views::char_to<seqan3::dna4>; // == "ACTTTGATAA"_dna4
auto v2 = s | seqan3::views::char_to<seqan3::dna5>; // == "ACTTTGATAN"_dna5
}

◆ complement

const auto seqan3::views::complement
inline

A view that converts a range of nucleotides to their complement.

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe 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/range/views/complement.hpp>

Calls seqan3::nucleotide_alphabet::complement() on every element of the input range.

View properties

This view is a deep view Given a range-of-range as input (as opposed to just a range), it will apply the transformation on the innermost range (instead of the outermost range).

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::nucleotide_alphabet std::remove_reference_t<seqan3::reference_t<urng_t>>

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

Example

#include <seqan3/alphabet/nucleotide/dna5.hpp>
#include <seqan3/range/views/complement.hpp>
#include <seqan3/std/ranges>
int main()
{
using seqan3::operator""_dna5;
seqan3::dna5_vector foo{"ACGTA"_dna5};
// pipe notation
auto v = foo | seqan3::views::complement; // == "TGCAT"
// function notation
auto v2(seqan3::views::complement(foo)); // == "TGCAT"
// generate the reverse complement:
auto v3 = foo | seqan3::views::complement | std::views::reverse; // == "TACGT"
}

◆ convert

template<typename out_t >
const auto seqan3::views::convert

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

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe 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/range/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:

#include <vector>
#include <seqan3/alphabet/nucleotide/dna15.hpp>
#include <seqan3/alphabet/nucleotide/dna5.hpp>
#include <seqan3/range/views/convert.hpp>
#include <seqan3/range/views/to.hpp>
#include <seqan3/std/ranges>
int main()
{
// convert from int to bool
std::vector<int> vec{7, 5, 0, 5, 0, 0, 4, 8, -3};
// pipe notation
auto v = vec | seqan3::views::convert<bool>; // == [1, 1, 0, 1, 0, 0, 1, 1, 1];
// function notation and immediate conversion to vector again
auto v2 = seqan3::views::convert<bool>(vec) | seqan3::views::to<std::vector<bool>>;
// combinability
auto v3 = vec | seqan3::views::convert<bool> | std::views::reverse; // == [1, 1, 1, 0, 0, 1, 0, 1, 1];
}

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

#include <seqan3/alphabet/nucleotide/dna15.hpp>
#include <seqan3/alphabet/nucleotide/dna5.hpp>
#include <seqan3/range/views/convert.hpp>
int main()
{
using seqan3::operator""_dna15;
seqan3::dna15_vector vec2{"ACYGTN"_dna15};
auto v4 = vec2 | seqan3::views::convert<seqan3::dna5>; // == "ACNGTN"_dna5
}

◆ drop

constexpr auto seqan3::views::drop
inlineconstexpr

A view adaptor that returns all elements after n from the underlying range (or an empty range if the underlying range is shorter).

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
[in]drop_sizeThe number of elements to drop from the beginning.
Returns
All elements of the underlying range after the first drop_size.

Header File

#include <seqan3/range/views/drop.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 seqan3::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::basic_string const & or std::basic_string_view std::basic_string_view
seqan3::forwarding_range && std::ranges::sized_range && std::ranges::contiguous_range std::span
seqan3::forwarding_range && std::ranges::sized_range && std::ranges::random_access_range std::ranges::subrange
else implementation defined type

The adaptor is different from std::views::drop in that it performs type erasure for some underlying ranges. It returns exactly the type specified above.

Complexity

Construction time of the returned view is in $ O(1) $ if the underlying range models at least std::ranges::random_access_range and std::ranges::sized_range; otherwise in $ O(drop\_size) $.

Example

#include <string>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/views/drop.hpp> // provides views::drop
#include <seqan3/std/ranges> // provides std::views::reverse
int main()
{
std::string s{"foobar"};
auto v = s | seqan3::views::drop(3);
seqan3::debug_stream << v << '\n'; // "bar"
auto v2 = s | std::views::reverse | seqan3::views::drop(3);
seqan3::debug_stream << v2 << '\n'; // "oof"
}

◆ enforce_random_access

constexpr auto seqan3::views::enforce_random_access
inlineconstexpr

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

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
Returns
A std::ranges::random_access_range over the given range.

Header File

#include <seqan3/range/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
seqan3::reference_t seqan3::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

#include <string>
#include <seqan3/alphabet/nucleotide/dna4.hpp>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/decorator/gap_decorator.hpp>
#include <seqan3/range/views/enforce_random_access.hpp>
int main()
{
using seqan3::operator""_dna4;
// 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 fulfil random access semantics because it does not allow constant time access to aribtrary
// 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"
}

Complexity

Construction of the returned view is in $ O(1) $.

◆ get

template<auto index>
const auto seqan3::views::get
inline

A view calling std::get on each element in a range.

Template Parameters
size_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
indexThe index to get.
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
Returns
A range of elements where every element is the result of calling std::get<index> on the underlying element. See below for the properties of the returned range.

Header File

#include <seqan3/range/views/get.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 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, seqan3::reference_t<urng_t>>

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

Example

#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/core/debug_stream.hpp>
#include <seqan3/range/views/get.hpp>
#include <seqan3/range/views/to_char.hpp>
int main()
{
using seqan3::operator""_dna4;
using seqan3::operator""_phred42;
// 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::get<0> | seqan3::views::to_char) << '\n'; // Prints [A,C,G,T]
seqan3::debug_stream << (qv | seqan3::views::get<1> | seqan3::views::to_char) << '\n'; // Prints [!,",#,$]
}

◆ interleave

constexpr auto seqan3::views::interleave
inlineconstexpr

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

Template Parameters
urng_tThe type of the range being processed.
inserted_rng_tThe type of the range being inserted.
Parameters
[in]urangeThe range being processed.
[in]inserted_rangeThe range being inserted.
[in]step_sizeA 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/range/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) | views::join(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 seqan3::reference_t<urng_t>

If above requirements are not met, this adaptor forwards to | ranges::view::chunk(step_size) | views::join(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 seqan3::value_type_t<urng_t>
  • urng_t is the type of the range modified by this view (input).
  • rrng_type is the type of the range returned by this view.
  • for more details, see Views.

Example

#include <string>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/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
}

◆ istreambuf

constexpr auto seqan3::views::istreambuf
inlineconstexpr

A view factory that returns a view over the stream buffer of an input stream.

Template Parameters
istreambuf_tThe type of the stream(buffer); must be std::basic_streambuf or model seqan3::input_stream.
Parameters
[in]istreambufThe stream buffer or an input stream of whome the buffer is retrieved.
Returns

Header File

#include <seqan3/range/views/istreambuf.hpp>

View properties

This is a source-only view adaptor, also known as a range factory; you cannot pipe anything into it.

Concepts and traits rrng_t (returned range type)
std::ranges::input_range guaranteed
std::ranges::forward_range
std::ranges::bidirectional_range
std::ranges::random_access_range
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
seqan3::const_iterable_range guaranteed
std::ranges::range_reference_t istream_t::char_type

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

This adaptor is different from std::ranges::istream_range in that it operates directly on the buffer. It further uses a custom streambuf_iterator (not std::istreambuf_iterator) that performs less virtual function calls.

◆ kmer_hash

constexpr auto seqan3::views::kmer_hash
inlineconstexpr

Computes hash values for each position of a range via a given shape.

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
[in]shapeThe seqan3::shape that determines how to compute the hash value.
Returns
A range of std::size_t where each value is the hash of the resp. k-mer. See below for the properties of the returned range.

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 lost
std::ranges::output_range lost
seqan3::const_iterable_range preserved
std::ranges::range_reference_t seqan3::semialphabet std::size_t

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

Attention
For the alphabet size $\sigma$ of the alphabet of urange and the shape size $s$ of shape it must hold that $s>\frac{64}{\log_2\sigma}$, i.e. hashes resulting from the shape/alphabet combination can be represented in an uint64_t.

Example

#include <seqan3/alphabet/nucleotide/dna4.hpp>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/views/kmer_hash.hpp>
using seqan3::operator""_dna4;
using seqan3::operator""_shape;
int main()
{
std::vector<seqan3::dna4> text{"ACGTAGC"_dna4};
auto hashes = text | seqan3::views::kmer_hash(seqan3::shape{seqan3::ungapped{3}});
seqan3::debug_stream << hashes << '\n'; // [6,27,44,50,9]
seqan3::debug_stream << (text | seqan3::views::kmer_hash(seqan3::ungapped{3})) << '\n'; // [6,27,44,50,9]
seqan3::debug_stream << (text | seqan3::views::kmer_hash(0b101_shape)) << '\n'; // [2,7,8,14,1]
}

◆ move

const auto seqan3::views::move
inline

A view that turns lvalue-references into rvalue-references.

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
Returns
A range whose elements will be moved from.

Header File

#include <seqan3/range/views/move.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 lost
seqan3::const_iterable_range preserved
std::semiregular preserved
std::ranges::range_reference_t t & -> t && but t -> t

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

Example

This is a slightly more verbose version of calling std::ranges::move on the range.

#include <string>
#include <seqan3/range/views/move.hpp>
#include <seqan3/std/ranges>
int main()
{
std::vector<std::string> vec_in{"ABC", "DEF", "GEH"};
std::vector<std::string> vec_out0{};
vec_out0.resize(3);
std::ranges::copy(vec_in, // copies strings from in to out
vec_out0.begin());
std::vector<std::string> vec_out1{};
vec_out1.resize(3);
std::ranges::copy(vec_in | seqan3::views::move, // moves strings from in to out
vec_out1.begin());
}

A more useful example can be found in the tutorial .

◆ pairwise_combine

constexpr auto seqan3::views::pairwise_combine
inlineconstexpr

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

Template Parameters
urng_tThe type of the range being processed. See below for requirements.
Parameters
[in]urangeThe 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/range/views/pairwise_combine.hpp>

This view generates two-element tuples representing all unique 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<seqan3::reference_t<urng_t>, seqan3::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

#include <vector>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/views/pairwise_combine.hpp>
int main()
{
std::vector vec{'a', 'b', 'c', 'd'};
for (auto res : vec | seqan3::views::pairwise_combine)
{
seqan3::debug_stream << res << "\n";
}
}
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.

◆ persist

constexpr auto seqan3::views::persist
inlineconstexpr

A view adaptor that wraps rvalue references of non-views.

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
Returns
A range wrapped in a view (even if it doesn't model std::ranges::viewable_range).

Header File

#include <seqan3/range/views/persist.hpp>

For ranges that model std::ranges::viewable_range, this adaptor just returns std::views::all. However this adaptor can also take ranges that are not "viewable", e.g. temporaries of containers. It wraps them in a shared pointer internally so all view requirements like constant copy are satisfied. However construction and copying might be slightly slower, because of reference counting.

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 not 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 seqan3::reference_t<urng_t>

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

Example

#include <seqan3/alphabet/nucleotide/dna4.hpp>
#include <seqan3/range/views/persist.hpp>
#include <seqan3/range/views/to_char.hpp>
int main()
{
using seqan3::operator""_dna4;
// explicitly create an l-value of our dna vector:
auto vec = "ACGT"_dna4;
auto v = vec | seqan3::views::to_char;
// using seqan3::views::persist you can bind the temporary directly:
auto v2 = "ACGT"_dna4 | seqan3::views::persist | seqan3::views::to_char;
// note that seqan3::views::persist must follow immediately after the temporary,
// thus the function notation might be more intuitive:
auto v3 = seqan3::views::persist("ACGT"_dna4) | seqan3::views::to_char;
}

◆ rank_to

template<typename alphabet_type >
const auto seqan3::views::rank_to
inline

A view over an alphabet, given a range of ranks.

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
alphabet_tThe alphabet to convert to; must satisfy seqan3::writable_semialphabet.
Parameters
[in]urangeThe 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/range/views/rank_to.hpp>

View properties

This view is a deep view Given a range-of-range as input (as opposed to just a range), it will apply the transformation on the innermost range (instead of the outermost range).

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::alphabet_rank_t<alphabet_t> alphabet_t

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

Example

#include <vector>
#include <seqan3/alphabet/nucleotide/dna4.hpp>
#include <seqan3/alphabet/nucleotide/dna5.hpp>
#include <seqan3/range/views/rank_to.hpp>
int main()
{
std::vector<int> vec{0, 1, 3, 3, 3, 2, 0, 3, 0};
auto v1 = vec | seqan3::views::rank_to<seqan3::dna4>; // == "ACTTTGATA"_dna4
auto v2 = vec | seqan3::views::rank_to<seqan3::dna5>; // == "ACTTTGATA"_dna5
}

◆ repeat

constexpr detail::repeat_fn seqan3::views::repeat
inlineconstexpr

A view factory that repeats a given value infinitely.

Template Parameters
value_tThe type of value to repeat wrapped in a std::views::single; must model std::copy_constructible.
Parameters
[in]valueThe value to repeat.
Returns
An infinite range over value.

Header File

#include <seqan3/range/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

#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/views/repeat.hpp>
#include <seqan3/std/ranges>
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'
}

◆ repeat_n

constexpr auto seqan3::views::repeat_n
inlineconstexpr

A view factory that repeats a given value n times.

Template Parameters
value_tThe type of value to repeat; must be std::copy_constructible.
Parameters
[in]valueThe value to repeat.
[in]countThe number of times to repeat value.
Returns
A range of size count, where each element equals value.

Header File

#include <seqan3/range/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

#include <string>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/views/repeat_n.hpp>
#include <seqan3/std/ranges>
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
}

◆ single_pass_input

constexpr auto seqan3::views::single_pass_input
inlineconstexpr

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

Template Parameters
urng_tThe type of the range being processed. See below for requirements.
Parameters
[in]urangeThe range being processed.
Returns
A range with single pass input behavior. See below for the properties of the returned range.

Header File

#include <seqan3/range/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 preserved
seqan3::const_iterable_range lost
std::ranges::range_reference_t seqan3::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

#include <string>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/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'
}

◆ slice

constexpr auto seqan3::views::slice
inlineconstexpr

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

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
[in]begin_posThe beginning of the interval (index of first element returned).
[in]end_posThe 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_argumentIf end_pos < begin_pos.

Header File

#include <seqan3/range/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 seqan3::reference_t<urng_t>

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

This adaptor is a combination of seqan3::views::drop and seqan3::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
seqan3::forwarding_range && std::ranges::sized_range && std::ranges::contiguous_range std::span
seqan3::forwarding_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 $ O(begin\_pos) $ for some views, see seqan3::views::drop.

Example

#include <string>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/views/slice.hpp> // provides views::slice
#include <seqan3/std/ranges> // provides std::views::reverse
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"
}

◆ take

constexpr auto seqan3::views::take
inlineconstexpr

A view adaptor that returns the first size elements from the underlying range (or less if the underlying range is shorter).

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
[in]sizeThe target size of the view.
Returns
Up to size elements of the underlying range.

Header File

#include <seqan3/range/views/take.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 seqan3::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::basic_string const & or std::basic_string_view std::basic_string_view
seqan3::forwarding_range && std::ranges::sized_range && std::ranges::contiguous_range std::span
seqan3::forwarding_range && std::ranges::sized_range && std::ranges::random_access_range std::ranges::subrange
else implementation defined type

This adaptor is different from std::views::take in that it performs type erasure for some underlying ranges. It returns exactly the type specified above.

Some benchmarks have shown that it is also faster than std::views::take for pure forward and input ranges.

Example

#include <string>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/views/take.hpp>
#include <seqan3/std/ranges>
int main()
{
std::string vec{"foobar"};
auto v = vec | seqan3::views::take(3);
seqan3::debug_stream << v << '\n'; // [f,o,o]
auto v2 = vec | std::views::reverse | seqan3::views::take(3);
seqan3::debug_stream << v2 << '\n'; // [r,a,b]
}

◆ take_exactly

constexpr auto seqan3::views::take_exactly
inlineconstexpr

A view adaptor that returns the first size elements from the underlying range (or less if the underlying range is shorter); also provides size information.

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
[in]sizeThe target size of the view.
Returns
Up to size elements of the underlying range.

Header File

#include <seqan3/range/views/take_exactly.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 guaranteed
std::ranges::common_range preserved
std::ranges::output_range preserved except if urng_t is std::basic_string
seqan3::const_iterable_range preserved
std::ranges::range_reference_t seqan3::reference_t<urng_t>

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

The difference to seqan3::views::take is that this view always exposes size information – even if the underlying range is not sized. You should only use this if you know that the underlying range will always be at least size long.

For seqan3::views::take_exactly if the underlying range is shorter than size, the behaviour is undefined. seqan3::views::take_exactly_or_throw is a safer alternative, because it throws an exception when an iterator before the size-th one compares equal to the end sentinel; and it also throws on construction if it knows that the underlying range is smaller.

Example

#include <string>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/views/take_exactly.hpp> // provides views::take_exactly and views::take_exactly_or_throw
int main()
{
std::string vec{"foobar"};
auto v = vec | seqan3::views::take_exactly(3); // or seqan3::views::take_exactly_or_throw
seqan3::debug_stream << v << '\n'; // "foo"
seqan3::debug_stream << std::ranges::size(v) << '\n'; // 3
auto v2 = vec | seqan3::views::take_exactly(9);
seqan3::debug_stream << std::ranges::size(v2) << '\n'; // 9 <- here be dragons!
}

◆ take_exactly_or_throw

constexpr auto seqan3::views::take_exactly_or_throw
inlineconstexpr

A view adaptor that returns the first size elements from the underlying range and also exposes size information; throws if the underlying range is smaller than size.

Exceptions
seqan3::unexpected_end_of_inputIf the underlying range is smaller than size.
Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
[in]sizeThe target size of the view.
Returns
Up to size elements of the underlying range.

Header File

#include <seqan3/range/views/take_exactly.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 guaranteed
std::ranges::common_range preserved
std::ranges::output_range preserved except if urng_t is std::basic_string
seqan3::const_iterable_range preserved
std::ranges::range_reference_t seqan3::reference_t<urng_t>

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

The difference to seqan3::views::take is that this view always exposes size information – even if the underlying range is not sized. You should only use this if you know that the underlying range will always be at least size long.

For seqan3::views::take_exactly if the underlying range is shorter than size, the behaviour is undefined. seqan3::views::take_exactly_or_throw is a safer alternative, because it throws an exception when an iterator before the size-th one compares equal to the end sentinel; and it also throws on construction if it knows that the underlying range is smaller.

Example

#include <string>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/views/take_exactly.hpp> // provides views::take_exactly and views::take_exactly_or_throw
int main()
{
std::string vec{"foobar"};
auto v = vec | seqan3::views::take_exactly(3); // or seqan3::views::take_exactly_or_throw
seqan3::debug_stream << v << '\n'; // "foo"
seqan3::debug_stream << std::ranges::size(v) << '\n'; // 3
auto v2 = vec | seqan3::views::take_exactly(9);
seqan3::debug_stream << std::ranges::size(v2) << '\n'; // 9 <- here be dragons!
}

◆ take_line

constexpr auto seqan3::views::take_line = views::take_until_and_consume(is_char<'\r'> || is_char<'\n'>)
inlineconstexpr

A view adaptor that returns a single line from the underlying range or the full range if there is no newline.

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
Returns
All characters of the underlying range up until, but excluding a unix or windows end-line (\n or \r\n). See below for the properties of the returned range.

Header File

#include <seqan3/range/views/take_line.hpp>

This adaptor returns a single line excluding the end-line character(s), but moving the cursor behind them for single-pass ranges. I.e. for all ranges that satisfy std::ranges::forward_range this is the same as calling std::views::take_while:

std::views::take_while([] (auto const & l) { return (l != '\r') && (l != '\n'); });

but for single pass input ranges this means that any endline characters after the returned range are also consumed (this potentially includes multiple newline characters).

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 lost
std::ranges::common_range lost
std::ranges::output_range preserved
seqan3::const_iterable_range preserved
std::ranges::range_reference_t std::common_reference_with<char> seqan3::reference_t<urng_t>

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

Example

Behaviour on std::ranges::forward_range:

#include <string>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/views/take_line.hpp>
int main()
{
std::string vec{"foo\nbar"};
auto v = vec | seqan3::views::take_line;
seqan3::debug_stream << v << '\n'; // [f,o,o]
auto v2 = vec | std::views::reverse | seqan3::views::take_line;
seqan3::debug_stream << v2 << '\n'; // [r,a,b]
seqan3::debug_stream << v2 << '\n'; // [r,a,b] (parsing it again gives us the same result)
}

On single pass std::ranges::input_range it can be used to tokenise the input stream line-wise:

#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/views/take_line.hpp>
#include <seqan3/range/views/single_pass_input.hpp>
int main()
{
std::string vec{"foo\nbar"};
auto v = vec | seqan3::views::single_pass_input | seqan3::views::take_line;
seqan3::debug_stream << v << '\n'; // [f,o,o]
seqan3::debug_stream << v << '\n'; // [b,a,r] (parsing it again gives us the next line)
}

◆ take_line_or_throw

constexpr auto seqan3::views::take_line_or_throw = views::take_until_or_throw_and_consume(is_char<'\r'> || is_char<'\n'>)
inlineconstexpr

A view adaptor that returns a single line from the underlying range (throws if there is no end-of-line).

Exceptions
seqan3::unexpected_end_of_inputIf the underlying range contains no end-of-line marker.
Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
Returns
All characters of the underlying range up until, but excluding a unix or windows end-line (\n or \r\n). See below for the properties of the returned range.

Header File

#include <seqan3/range/views/take_line.hpp>

This adaptor returns a single line excluding the end-line character(s), but moving the cursor behind them for single-pass ranges. I.e. for all ranges that satisfy std::ranges::forward_range this is the same as calling std::views::take_while:

std::views::take_while([] (auto const & l) { return (l != '\r') && (l != '\n'); });

but for single pass input ranges this means that any endline characters after the returned range are also consumed (this potentially includes multiple newline characters).

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 lost
std::ranges::common_range lost
std::ranges::output_range preserved
seqan3::const_iterable_range preserved
std::ranges::range_reference_t std::common_reference_with<char> seqan3::reference_t<urng_t>

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

Example

Behaviour on std::ranges::forward_range:

#include <string>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/views/take_line.hpp>
int main()
{
std::string vec{"foo\nbar"};
auto v = vec | seqan3::views::take_line;
seqan3::debug_stream << v << '\n'; // [f,o,o]
auto v2 = vec | std::views::reverse | seqan3::views::take_line;
seqan3::debug_stream << v2 << '\n'; // [r,a,b]
seqan3::debug_stream << v2 << '\n'; // [r,a,b] (parsing it again gives us the same result)
}

On single pass std::ranges::input_range it can be used to tokenise the input stream line-wise:

#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/views/take_line.hpp>
#include <seqan3/range/views/single_pass_input.hpp>
int main()
{
std::string vec{"foo\nbar"};
auto v = vec | seqan3::views::single_pass_input | seqan3::views::take_line;
seqan3::debug_stream << v << '\n'; // [f,o,o]
seqan3::debug_stream << v << '\n'; // [b,a,r] (parsing it again gives us the next line)
}

◆ take_until

constexpr auto seqan3::views::take_until
inlineconstexpr

A view adaptor that returns elements from the underlying range until the functor evaluates to true (or the end of the underlying range is reached).

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
fun_tThe type of the functor; must model std::invocable with seqan3::reference_t<urng_t> and return a type convertible to bool.
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
[in]funThe functor.
Returns
All elements of the underlying range up until (but excluding) the element that evaluates the functor to true.

Header File

#include <seqan3/range/views/take_until.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 lost
std::ranges::common_range lost
std::ranges::output_range preserved
seqan3::const_iterable_range *preserved*¹
std::ranges::range_reference_t seqan3::reference_t<urng_t>

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

¹ The marked properties are only preserved if the specified functor models std::regular_invocable<fun_t, reference_t<urng_t>, i.e. applying the functor doesn't change the functor. If the functor only models std::invocable and not std::regular_invocable these concepts are lost.

Throwing: seqan3::views::take_until_or_throw and seqan3::views::take_until_or_throw_and_consume throw an exception if the end of the underlying range is reached before their own termination criterium is met. This is useful if you want a "strict" evaluation of the functor.

Consuming: seqan3::views::take_until_and_consume and seqan3::views::take_until_or_throw_and_consume behave the same as their non-consuming counter-parts if the underlying range models at least std::forward_range. If, however, the underlying range is a pure std::input_range, the view will keep moving the underlying iterator forward as long as the termination criterium holds and the underlying range is not at end. This is useful for string tokenisation among other things.

Example

#include <string>
#include <seqan3/core/char_operations/predicate.hpp> // for is_char
#include <seqan3/core/debug_stream.hpp> // for debug_stream
#include <seqan3/range/views/single_pass_input.hpp> // for views::single_pass_input
#include <seqan3/range/views/take_until.hpp> // for views::take_until*
#include <seqan3/std/ranges> // for std::views::reverse
int main()
{
// regular usage
std::string vec{"foo\nbar"};
auto v = vec | seqan3::views::take_until(seqan3::is_char<'\n'>); // or use a lambda
seqan3::debug_stream << v << '\n'; // "foo"
auto v2 = vec | std::views::reverse | seqan3::views::take_until(seqan3::is_char<'\n'>);
seqan3::debug_stream << v2 << '\n'; // "rab"
// consuming behaviour
std::string vec2{"foo bar"}; // ← multiple spaces
auto vin = vec2 | seqan3::views::single_pass_input;
auto v3 = vin | seqan3::views::take_until_and_consume(seqan3::is_blank);
seqan3::debug_stream << v3 << '\n'; // "foo"
seqan3::debug_stream << *std::ranges::begin(vin) << '\n'; // "b", the spaces where skipped
}

◆ take_until_and_consume

constexpr auto seqan3::views::take_until_and_consume
inlineconstexpr

A view adaptor that returns elements from the underlying range until the functor evaluates to true (or the end of the underlying range is reached; consumes end in single-pass ranges).

Exceptions
seqan3::unexpected_end_of_inputIf the underlying range contains no element that satisfies the functor.
Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
fun_tThe type of the functor; must model std::invocable with seqan3::reference_t<urng_t> and return a type convertible to bool.
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
[in]funThe functor.
Returns
All elements of the underlying range up until (but excluding) the element that evaluates the functor to true.

Header File

#include <seqan3/range/views/take_until.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 lost
std::ranges::common_range lost
std::ranges::output_range preserved
seqan3::const_iterable_range *preserved*¹
std::ranges::range_reference_t seqan3::reference_t<urng_t>

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

¹ The marked properties are only preserved if the specified functor models std::regular_invocable<fun_t, reference_t<urng_t>, i.e. applying the functor doesn't change the functor. If the functor only models std::invocable and not std::regular_invocable these concepts are lost.

Throwing: seqan3::views::take_until_or_throw and seqan3::views::take_until_or_throw_and_consume throw an exception if the end of the underlying range is reached before their own termination criterium is met. This is useful if you want a "strict" evaluation of the functor.

Consuming: seqan3::views::take_until_and_consume and seqan3::views::take_until_or_throw_and_consume behave the same as their non-consuming counter-parts if the underlying range models at least std::forward_range. If, however, the underlying range is a pure std::input_range, the view will keep moving the underlying iterator forward as long as the termination criterium holds and the underlying range is not at end. This is useful for string tokenisation among other things.

Example

#include <string>
#include <seqan3/core/char_operations/predicate.hpp> // for is_char
#include <seqan3/core/debug_stream.hpp> // for debug_stream
#include <seqan3/range/views/single_pass_input.hpp> // for views::single_pass_input
#include <seqan3/range/views/take_until.hpp> // for views::take_until*
#include <seqan3/std/ranges> // for std::views::reverse
int main()
{
// regular usage
std::string vec{"foo\nbar"};
auto v = vec | seqan3::views::take_until(seqan3::is_char<'\n'>); // or use a lambda
seqan3::debug_stream << v << '\n'; // "foo"
auto v2 = vec | std::views::reverse | seqan3::views::take_until(seqan3::is_char<'\n'>);
seqan3::debug_stream << v2 << '\n'; // "rab"
// consuming behaviour
std::string vec2{"foo bar"}; // ← multiple spaces
auto vin = vec2 | seqan3::views::single_pass_input;
auto v3 = vin | seqan3::views::take_until_and_consume(seqan3::is_blank);
seqan3::debug_stream << v3 << '\n'; // "foo"
seqan3::debug_stream << *std::ranges::begin(vin) << '\n'; // "b", the spaces where skipped
}

◆ take_until_or_throw

constexpr auto seqan3::views::take_until_or_throw
inlineconstexpr

A view adaptor that returns elements from the underlying range until the functor evaluates to true (throws if the end of the underlying range is reached).

Exceptions
seqan3::unexpected_end_of_inputIf the underlying range contains no element that satisfies the functor.
Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
fun_tThe type of the functor; must model std::invocable with seqan3::reference_t<urng_t> and return a type convertible to bool.
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
[in]funThe functor.
Returns
All elements of the underlying range up until (but excluding) the element that evaluates the functor to true.

Header File

#include <seqan3/range/views/take_until.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 lost
std::ranges::common_range lost
std::ranges::output_range preserved
seqan3::const_iterable_range *preserved*¹
std::ranges::range_reference_t seqan3::reference_t<urng_t>

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

¹ The marked properties are only preserved if the specified functor models std::regular_invocable<fun_t, reference_t<urng_t>, i.e. applying the functor doesn't change the functor. If the functor only models std::invocable and not std::regular_invocable these concepts are lost.

Throwing: seqan3::views::take_until_or_throw and seqan3::views::take_until_or_throw_and_consume throw an exception if the end of the underlying range is reached before their own termination criterium is met. This is useful if you want a "strict" evaluation of the functor.

Consuming: seqan3::views::take_until_and_consume and seqan3::views::take_until_or_throw_and_consume behave the same as their non-consuming counter-parts if the underlying range models at least std::forward_range. If, however, the underlying range is a pure std::input_range, the view will keep moving the underlying iterator forward as long as the termination criterium holds and the underlying range is not at end. This is useful for string tokenisation among other things.

Example

#include <string>
#include <seqan3/core/char_operations/predicate.hpp> // for is_char
#include <seqan3/core/debug_stream.hpp> // for debug_stream
#include <seqan3/range/views/single_pass_input.hpp> // for views::single_pass_input
#include <seqan3/range/views/take_until.hpp> // for views::take_until*
#include <seqan3/std/ranges> // for std::views::reverse
int main()
{
// regular usage
std::string vec{"foo\nbar"};
auto v = vec | seqan3::views::take_until(seqan3::is_char<'\n'>); // or use a lambda
seqan3::debug_stream << v << '\n'; // "foo"
auto v2 = vec | std::views::reverse | seqan3::views::take_until(seqan3::is_char<'\n'>);
seqan3::debug_stream << v2 << '\n'; // "rab"
// consuming behaviour
std::string vec2{"foo bar"}; // ← multiple spaces
auto vin = vec2 | seqan3::views::single_pass_input;
auto v3 = vin | seqan3::views::take_until_and_consume(seqan3::is_blank);
seqan3::debug_stream << v3 << '\n'; // "foo"
seqan3::debug_stream << *std::ranges::begin(vin) << '\n'; // "b", the spaces where skipped
}

◆ take_until_or_throw_and_consume

constexpr auto seqan3::views::take_until_or_throw_and_consume
inlineconstexpr

A view adaptor that returns elements from the underlying range until the functor evaluates to true (throws if the end of the underlying range is reached; consumes end in single-pass ranges).

Exceptions
seqan3::unexpected_end_of_inputIf the underlying range contains no element that satisfies the functor.
Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
fun_tThe type of the functor; must model std::invocable with seqan3::reference_t<urng_t> and return a type convertible to bool.
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
[in]funThe functor.
Returns
All elements of the underlying range up until (but excluding) the element that evaluates the functor to true.

Header File

#include <seqan3/range/views/take_until.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 lost
std::ranges::common_range lost
std::ranges::output_range preserved
seqan3::const_iterable_range *preserved*¹
std::ranges::range_reference_t seqan3::reference_t<urng_t>

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

¹ The marked properties are only preserved if the specified functor models std::regular_invocable<fun_t, reference_t<urng_t>, i.e. applying the functor doesn't change the functor. If the functor only models std::invocable and not std::regular_invocable these concepts are lost.

Throwing: seqan3::views::take_until_or_throw and seqan3::views::take_until_or_throw_and_consume throw an exception if the end of the underlying range is reached before their own termination criterium is met. This is useful if you want a "strict" evaluation of the functor.

Consuming: seqan3::views::take_until_and_consume and seqan3::views::take_until_or_throw_and_consume behave the same as their non-consuming counter-parts if the underlying range models at least std::forward_range. If, however, the underlying range is a pure std::input_range, the view will keep moving the underlying iterator forward as long as the termination criterium holds and the underlying range is not at end. This is useful for string tokenisation among other things.

Example

#include <string>
#include <seqan3/core/char_operations/predicate.hpp> // for is_char
#include <seqan3/core/debug_stream.hpp> // for debug_stream
#include <seqan3/range/views/single_pass_input.hpp> // for views::single_pass_input
#include <seqan3/range/views/take_until.hpp> // for views::take_until*
#include <seqan3/std/ranges> // for std::views::reverse
int main()
{
// regular usage
std::string vec{"foo\nbar"};
auto v = vec | seqan3::views::take_until(seqan3::is_char<'\n'>); // or use a lambda
seqan3::debug_stream << v << '\n'; // "foo"
auto v2 = vec | std::views::reverse | seqan3::views::take_until(seqan3::is_char<'\n'>);
seqan3::debug_stream << v2 << '\n'; // "rab"
// consuming behaviour
std::string vec2{"foo bar"}; // ← multiple spaces
auto vin = vec2 | seqan3::views::single_pass_input;
auto v3 = vin | seqan3::views::take_until_and_consume(seqan3::is_blank);
seqan3::debug_stream << v3 << '\n'; // "foo"
seqan3::debug_stream << *std::ranges::begin(vin) << '\n'; // "b", the spaces where skipped
}

◆ to_char

const auto seqan3::views::to_char
inline

A view that calls seqan3::to_char() on each element in the input range.

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe 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/range/views/to_char.hpp>

View properties

This view is a deep view Given a range-of-range as input (as opposed to just a range), it will apply the transformation on the innermost range (instead of the outermost range).

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::alphabet seqan3::alphabet_char_t<seqan3::value_type_t<urng_t>>

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

Example

#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/core/debug_stream.hpp>
#include <seqan3/range/views/to_char.hpp>
int main()
{
using seqan3::operator""_dna4;
seqan3::dna4_vector vec = "ACTTTGATA"_dna4;
auto v = vec | seqan3::views::to_char;
seqan3::debug_stream << v << '\n'; // [A,C,T,T,T,G,A,T,A]
std::vector<seqan3::phred42> qvec{{0}, {7}, {5}, {3}, {7}, {4}, {30}, {16}, {23}};
auto v3 = qvec | seqan3::views::to_char;
seqan3::debug_stream << v3 << '\n'; // [!,(,&,$,(,%,?,1,8]
std::vector<seqan3::dna4q> qcvec{{'C'_dna4, seqan3::phred42{0}}, {'A'_dna4, seqan3::phred42{7}},
{'G'_dna4, seqan3::phred42{5}}, {'T'_dna4, seqan3::phred42{3}},
{'G'_dna4, seqan3::phred42{7}}, {'A'_dna4, seqan3::phred42{4}},
{'C'_dna4, seqan3::phred42{30}}, {'T'_dna4, seqan3::phred42{16}},
{'A'_dna4, seqan3::phred42{23}}};
auto v4 = qcvec | seqan3::views::to_char;
seqan3::debug_stream << v4 << '\n'; // [C,A,G,T,G,A,C,T,A]
}

◆ to_lower

const auto seqan3::views::to_lower
inline

A view that calls seqan3::to_lower() on each element in the input range.

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe 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/range/views/to_lower.hpp>

View properties

This view is a deep view Given a range-of-range as input (as opposed to just a range), it will apply the transformation on the innermost range (instead of the outermost range).

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::builtin_character seqan3::remove_reference_t<seqan3::reference_t<urngt_>>

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

Example

#include <string>
#include <vector>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/views/to_lower.hpp>
int main()
{
std::string s{"CHanGED!"};
std::vector<std::string> sv{"CHANGED", "unchanged!"};
auto v1 = s | seqan3::views::to_lower;
auto v2 = sv | seqan3::views::to_lower;
seqan3::debug_stream << v1 << '\n'; // => "changed!"
seqan3::debug_stream << v2 << '\n'; // => ["changed", "unchanged!"]
}

◆ to_rank

const auto seqan3::views::to_rank
inline

A view that calls seqan3::to_rank() on each element in the input range.

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe 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/range/views/to_rank.hpp>

View properties

This view is a deep view Given a range-of-range as input (as opposed to just a range), it will apply the transformation on the innermost range (instead of the outermost range).

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::alphabet seqan3::alphabet_rank_t<seqan3::value_type_t<urng_t>>

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

Example

#include <vector>
#include <seqan3/alphabet/nucleotide/dna4.hpp>
#include <seqan3/alphabet/quality/phred42.hpp>
#include <seqan3/alphabet/quality/aliases.hpp>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/views/to_rank.hpp>
#include <seqan3/range/views/convert.hpp>
int main()
{
using seqan3::operator""_dna4;
seqan3::dna4_vector vec = "ACTTTGATA"_dna4;
auto v = vec | seqan3::views::to_rank | seqan3::views::convert<unsigned>;
seqan3::debug_stream << v << '\n'; // [0,1,3,3,3,2,0,3,0]
std::vector<seqan3::phred42> qvec{{0}, {7}, {5}, {3}, {7}, {4}, {30}, {16}, {23}};
auto v3 = qvec | seqan3::views::to_rank | seqan3::views::convert<unsigned>;
seqan3::debug_stream << v3 << '\n'; // [0,7,5,3,7,4,30,16,23]
std::vector<seqan3::dna4q> qcvec{{'C'_dna4, seqan3::phred42{0}}, {'A'_dna4, seqan3::phred42{7}},
{'G'_dna4, seqan3::phred42{5}}, {'T'_dna4, seqan3::phred42{3}},
{'G'_dna4, seqan3::phred42{7}}, {'A'_dna4, seqan3::phred42{4}},
{'C'_dna4, seqan3::phred42{30}}, {'T'_dna4, seqan3::phred42{16}},
{'A'_dna4, seqan3::phred42{23}}};
auto v4 = qcvec | seqan3::views::to_rank | seqan3::views::convert<unsigned>;
seqan3::debug_stream << v4 << '\n'; // [1,28,22,15,30,16,121,67,92]
}

We also convert to unsigned here, because the seqan3::alphabet_rank_t is often uint8_t which is often implemented as unsigned char and thus will not be printed as a number by default.

◆ to_upper

const auto seqan3::views::to_upper
inline

A view that calls seqan3::to_upper() on each element in the input range.

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe 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/range/views/to_upper.hpp>

View properties

This view is a deep view Given a range-of-range as input (as opposed to just a range), it will apply the transformation on the innermost range (instead of the outermost range).

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::builtin_character seqan3::remove_reference_t<seqan3::reference_t<urngt_>>

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

Example

#include <string>
#include <vector>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/views/to_upper.hpp>
int main()
{
std::string s{"CHanGED!"};
std::vector<std::string> sv{"changed", "UNCHANGED!"};
auto v1 = s | seqan3::views::to_upper;
auto v2 = sv | seqan3::views::to_upper;
seqan3::debug_stream << v1 << '\n'; // => "CHANGED!"
seqan3::debug_stream << v2 << '\n'; // => ["CHANGED", "UNCHANGED!"]
}

◆ translate

constexpr auto seqan3::views::translate
inlineconstexpr

A view that translates nucleotide into aminoacid alphabet with 1, 2, 3 or 6 frames.

Template Parameters
urng_tThe type of the range being processed.
Parameters
[in]urangeThe range being processed.
[in]tfA value of seqan3::tanslation_frames that indicates the desired frames.
Returns
A range of ranges containing frames with aminoacid sequence. See below for the properties of the returned range.

Header File

#include <seqan3/range/views/translate.hpp>

This view can be used to translate nucleotide sequences into aminoacid sequences (see translation_frames for possible combination of frames).

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 guaranteed
std::ranges::output_range lost
seqan3::const_iterable_range required preserved
std::ranges::range_reference_t seqan3::nucleotide_alphabet std::ranges::view && std::ranges::random_access_range && std::ranges::sized_range
  • urng_t is the type of the range modified by this view (input).
  • rrng_type is the type of the range returned by this view.
  • for more details, see Views.

Example

Operating on a range of seqan3::dna5:

#include <seqan3/alphabet/nucleotide/dna5.hpp>
#include <seqan3/range/views/complement.hpp>
#include <seqan3/range/views/translate.hpp>
int main()
{
using seqan3::operator""_dna5;
seqan3::dna5_vector vec{"ACGTACGTACGTA"_dna5};
// default frame translation
auto v1 = vec | seqan3::views::translate;
// == [[T,Y,V,R],[R,T,Y,V],[V,R,T],[Y,V,R,T],[T,Y,V,R],[R,T,Y]]
// single frame translation
auto v2 = vec | seqan3::views::translate(seqan3::translation_frames::FWD_FRAME_0);
// == [[T,Y,V,R]]
// reverse translation
auto v3 = vec | seqan3::views::translate(seqan3::translation_frames::FWD_REV_0);
// == [[T,Y,V,R],[Y,V,R,T]]
// forward frames translation
auto v4 = vec | seqan3::views::translate(seqan3::translation_frames::FWD);
// == [[T,Y,V,R],[R,T,Y,V],[V,R,T]]
// six frame translation
auto v5 = vec | seqan3::views::translate(seqan3::translation_frames::SIX_FRAME);
// == [[T,Y,V,R],[R,T,Y,V],[V,R,T],[Y,V,R,T],[T,Y,V,R],[R,T,Y]]
// function syntax
auto v6 = seqan3::views::translate(vec, seqan3::translation_frames::FWD_REV_0);
// == [[T,Y,V,R],[Y,V,R,T]]
// combinability
auto v7 = vec | seqan3::views::complement | seqan3::views::translate(seqan3::translation_frames::FWD_REV_0);
// == [[C,M,H,A],[M,H,A,C]]
}

◆ translate_join

constexpr auto seqan3::views::translate_join
inlineconstexpr

A view that translates nucleotide into aminoacid alphabet with 1, 2, 3 or 6 frames. Input and output range are always two-dimensional.

Template Parameters
urng_tThe type of the range being processed.
Parameters
[in]urangeThe range being processed. Needs to be a range of ranges (two-dimensional).
[in]tfA value of seqan3::tanslation_frames that indicates the desired frames.
Returns
A range of ranges containing frames with aminoacid sequence. See below for the properties of the returned range.

Header File

#include <seqan3/range/views/translate_join.hpp>

This view can be used to translate nucleotide sequences into aminoacid sequences (see translation_frames for possible combination of frames). This view only operates on two-dimensional input (range of ranges) and outputs a range of ranges no matter the number of input sequences or the number of translation frames given. Therefore, it has the same capabilities as the standard view_translate but concatenates the different frames of the different input sequences rather than having a separate range for each input sequence containing the translated frames. In the output, frames are ordered in a way, that all requested frames are listed per sequence directly after each other in the order of input sequences. improved and efficient downstream post-processing if needed. However, the index of a frame for a specific sequence needs to be calculated via modulo operations in this case. The i-th frame of the j-th sequence can be calculated by n = (i * s) + j, where s is the number of frames used for translation (index starting at zero).

In short, this views behaves the same as:

std::vector<std::vector<dna5>> vec {...};
auto v = vec | views::translate | views::join;
Except that the performance is better and the returned range still models std::ranges::random_access_range and std::ranges::sized_range.

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 guaranteed
std::ranges::output_range lost
seqan3::const_iterable_range required preserved
std::ranges::range_reference_t seqan3::nucleotide_alphabet std::ranges::view && std::ranges::random_access_range && std::ranges::sized_range
  • 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.
  • for more details, see Views.

Example

Operating on a range of seqan3::dna5:

#include <iostream>
#include <seqan3/alphabet/nucleotide/dna4.hpp>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/views/char_to.hpp>
#include <seqan3/range/views/translate_join.hpp>
using seqan3::operator""_dna4;
int main()
{
// Input range needs to be two-dimensional
std::vector<std::vector<seqan3::dna4> > vec{"ACGTACGTACGTA"_dna4, "TCGAGAGCTTTAGC"_dna4};
// Translation with default parameters
auto v1 = vec | seqan3::views::translate_join;
seqan3::debug_stream << v1 << "\n"; // [TYVR,RTYV,VRT,YVRT,TYVR,RTY,SRAL,REL*,ESFS,AKAL,LKLS,*SSR]
// Access the third forward frame (index_frame 2) of the second input sequence (index_seq 1)
// Required frames per sequence s = 6
// n = (index_seq * s) + j
// = 1 * 6 + 2
// = 8
auto third_frame_second_seq = v1[1 * 6 + 2];
seqan3::debug_stream << third_frame_second_seq << "\n"; // ESFS
// Translation with custom translation frame
auto v2 = vec | seqan3::views::translate_join(seqan3::translation_frames::FWD_FRAME_0);
seqan3::debug_stream << v2 << "\n"; // [TYVR,SRAL]
return 0;
}

◆ translate_single

constexpr auto seqan3::views::translate_single
inlineconstexpr

A view that translates nucleotide into aminoacid alphabet for one of the six frames.

Template Parameters
urng_tThe type of the range being processed.
Parameters
[in]urangeThe range being processed.
[in]tfA value of seqan3::translation_frames that indicates the desired frames.
Returns
A range containing frames with aminoacid sequence. See below for the properties of the returned range.

Header File

#include <seqan3/range/views/translate.hpp>

This view can be used to translate nucleotide sequences into aminoacid sequences (see translation_frames for possible combination of frames).

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 guaranteed
std::ranges::output_range lost
seqan3::const_iterable_range required preserved
std::ranges::range_reference_t seqan3::nucleotide_alphabet seqan3::aa27
  • urng_t is the type of the range modified by this view (input).
  • rrng_type is the type of the range returned by this view.
  • for more details, see Views.

Example

Operating on a range of seqan3::dna5:

#include <seqan3/alphabet/nucleotide/dna5.hpp>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/views/complement.hpp>
#include <seqan3/range/views/translate.hpp>
int main()
{
using seqan3::operator""_dna5;
seqan3::dna5_vector vec{"ACGTACGTACGTA"_dna5};
// Default (first forward frame)
auto v1 = vec | seqan3::views::translate_single;
// == [T,Y,V,R]
seqan3::debug_stream << v1[1] << '\n';
// First forward frame
auto v2 = vec | seqan3::views::translate_single(seqan3::translation_frames::FWD_FRAME_0);
// == [T,Y,V,R]
// First reverse frame
auto v3 = vec | seqan3::views::translate_single(seqan3::translation_frames::REV_FRAME_0);
// == [Y,V,R,T]
// Second forward frame
auto v4 = vec | seqan3::views::translate_single(seqan3::translation_frames::FWD_FRAME_1);
// == [R,T,Y,V]
// Second reverse frame
auto v5 = vec | seqan3::views::translate_single(seqan3::translation_frames::REV_FRAME_1);
// == [T,Y,V,R]
// Third forward frame
auto v6 = vec | seqan3::views::translate_single(seqan3::translation_frames::FWD_FRAME_2);
// == [V,R,T]
// Third reverse frame
auto v7 = vec | seqan3::views::translate_single(seqan3::translation_frames::REV_FRAME_2);
// == [R,T,Y]
// function syntax
auto v8 = seqan3::views::translate_single(vec, seqan3::translation_frames::FWD_FRAME_0);
// == [T,Y,V,R]
// combinability
auto v9 = vec | seqan3::views::complement | seqan3::views::translate_single(seqan3::translation_frames::REV_FRAME_0);
// == [M,H,A,C]
// combinability with default parameter
auto v10 = vec | seqan3::views::complement | seqan3::views::translate_single;
// == [C,M,H,A]
// combinability with default parameter
auto v11 = vec | seqan3::views::complement | seqan3::views::translate_single();
// == [C,M,H,A]
}

◆ trim

constexpr auto seqan3::views::trim
inlineconstexpr

A view that does quality-threshold trimming on a range of seqan3::quality_alphabet.

Template Parameters
urng_tThe type of the range being processed. See below for requirements.
threshold_tEither seqan3::value_type_t<urng_t> or seqan3::alphabet_phred_t<seqan3::value_type_t<urng_t>>.
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
[in]thresholdThe minimum quality.
Returns
A trimmed range. See below for the properties of the returned range.

Header File

#include <seqan3/range/views/trim.hpp>

This view can be used to do easy quality based trimming of sequences.

View properties

This view is a deep view Given a range-of-range as input (as opposed to just a range), it will apply the transformation on the innermost range (instead of the outermost range).

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::view guaranteed
std::ranges::sized_range lost
std::ranges::common_range lost
std::ranges::output_range preserved
seqan3::const_iterable_range preserved
std::ranges::range_reference_t seqan3::quality_alphabet seqan3::reference_t<urng_t>

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

Example

Operating on a range of seqan3::phred42:

#include <string>
#include <vector>
#include <seqan3/alphabet/quality/phred42.hpp>
#include <seqan3/range/views/trim.hpp>
#include <seqan3/range/views/to_char.hpp>
int main()
{
std::vector<seqan3::phred42> vec{seqan3::phred42{40}, seqan3::phred42{40}, seqan3::phred42{30},
seqan3::phred42{20}, seqan3::phred42{10}};
// trim by phred_value
auto v1 = vec | seqan3::views::trim(20u); // == ['I','I','?','5']
// trim by quality character
auto v2 = vec | seqan3::views::trim(seqan3::phred42{40}); // == ['I','I']
// function syntax
auto v3 = seqan3::views::trim(vec, 20u); // == ['I','I','?','5']
// combinability
auto v4 = seqan3::views::trim(vec, 20u) | seqan3::views::to_char; // == "II?5"
}

Or operating on a range of seqan3::dna5q:

#include <string>
#include <vector>
#include <seqan3/alphabet/nucleotide/dna5.hpp>
#include <seqan3/alphabet/quality/aliases.hpp>
#include <seqan3/alphabet/quality/phred42.hpp>
#include <seqan3/range/views/trim.hpp>
#include <seqan3/range/views/to_char.hpp>
#include <seqan3/range/views/to.hpp>
int main()
{
using seqan3::operator""_dna5;
using seqan3::operator""_phred42;
std::vector<seqan3::dna5q> vec{{'A'_dna5, 'I'_phred42},
{'G'_dna5, 'I'_phred42},
{'G'_dna5, '?'_phred42},
{'A'_dna5, '5'_phred42},
{'T'_dna5, '+'_phred42}};
std::vector<seqan3::dna5q> cmp{{'A'_dna5, 'I'_phred42},
{'G'_dna5, 'I'_phred42},
{'G'_dna5, '?'_phred42},
{'A'_dna5, '5'_phred42}};
// trim by phred_value
auto v1 = vec | seqan3::views::trim(20u);
assert((v1 | seqan3::views::to<std::vector>) == cmp);
// trim by quality character; in this case the nucleotide part of the character is irrelevant
auto v2 = vec | seqan3::views::trim(seqan3::dna5q{'C'_dna5, '5'_phred42});
assert((v2 | seqan3::views::to<std::vector>) == cmp);
// combinability
auto v3 = seqan3::views::trim(vec, 20u) | seqan3::views::to_char;
assert(std::ranges::equal(std::string{"AGGA"}, v3 | seqan3::views::to<std::string>));
}

◆ type_reduce

constexpr auto seqan3::views::type_reduce
inlineconstexpr

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

Template Parameters
urng_tThe type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
Parameters
[in]urangeThe range being processed. [parameter is omitted in pipe notation]
Returns
The range turned into a view.

Header File

#include <seqan3/range/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 seqan3::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
seqan3::forwarding_range && std::ranges::sized_range && std::ranges::contiguous_range std::span
seqan3::forwarding_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

#include <string>
#include <vector>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/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::translation_frames::FWD_REV_0
The first forward and first reverse frame.
debug_stream.hpp
Provides seqan3::debug_stream and related types.
seqan3::translation_frames::FWD_FRAME_2
The third forward frame starting at position 2.
as_const.hpp
Provides seqan3::views::as_const.
std::srand
T srand(T... args)
std::vector::resize
T resize(T... args)
std::this_thread::sleep_for
T sleep_for(T... args)
seqan3::translation_frames::SIX_FRAME
All frames.
seqan3::views::take_until_and_consume
constexpr auto take_until_and_consume
A view adaptor that returns elements from the underlying range until the functor evaluates to true (o...
Definition: take_until.hpp:613
single_pass_input.hpp
Provides seqan3::single_pass_input_view.
take_until.hpp
Provides seqan3::views::take_until and seqan3::views::take_until_or_throw.
dna4.hpp
Provides seqan3::dna4, container aliases and string literals.
seqan3::views::to_char
const auto to_char
A view that calls seqan3::to_char() on each element in the input range.
Definition: to_char.hpp:65
drop.hpp
Provides seqan3::views::drop.
std::string
seqan3::views::interleave
constexpr auto interleave
A view that interleaves a given range into another range at regular intervals.
Definition: interleave.hpp:385
seqan3::views::kmer_hash
constexpr auto kmer_hash
Computes hash values for each position of a range via a given shape.
Definition: kmer_hash.hpp:705
dna15.hpp
Provides seqan3::dna15, container aliases and string literals.
seqan3::shape
A class that defines what positions of a pattern to hash.
Definition: shape.hpp:57
seqan3::views::translate_join
constexpr auto translate_join
A view that translates nucleotide into aminoacid alphabet with 1, 2, 3 or 6 frames....
Definition: translate_join.hpp:391
repeat.hpp
Provides the views::repeat_view.
gap_decorator.hpp
Provides seqan3::gap_decorator.
vector
seqan3::ungapped
A strong type of underlying type uint8_t that represents the ungapped shape size.
Definition: shape.hpp:24
std::chrono::milliseconds
convert.hpp
Provides seqan3::views::convert.
std::istringstream
seqan3::views::move
const auto move
A view that turns lvalue-references into rvalue-references.
Definition: move.hpp:68
seqan3::views::to_rank
const auto to_rank
A view that calls seqan3::to_rank() on each element in the input range.
Definition: to_rank.hpp:67
rank_to.hpp
Provides seqan3::views::rank_to.
input.hpp
Provides seqan3::sequence_file_input and corresponding traits classes.
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:158
seqan3::translation_frames::REV_FRAME_1
The second reverse frame starting at position 1.
seqan3::format_fasta
The FastA format.
Definition: format_fasta.hpp:80
complement.hpp
Provides seqan3::views::complement.
iostream
seqan3::views::trim
constexpr auto trim
A view that does quality-threshold trimming on a range of seqan3::quality_alphabet.
Definition: trim.hpp:128
future
seqan3::views::persist
constexpr auto persist
A view adaptor that wraps rvalue references of non-views.
Definition: persist.hpp:248
std::this_thread::get_id
T get_id(T... args)
seqan3::seq
constexpr sequenced_policy seq
Global execution policy object for sequenced execution policy.
Definition: execution.hpp:54
translate.hpp
Provides seqan3::views::translate and seqan3::views::translate_single.
pairwise_combine.hpp
Provides seqan3::views::pairwise_combine.
slice.hpp
Provides seqan3::views::slice.
seqan3::views::translate
constexpr auto translate
A view that translates nucleotide into aminoacid alphabet with 1, 2, 3 or 6 frames.
Definition: translate.hpp:805
repeat_n.hpp
Provides seqan3::views::repeat_n.
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:732
seqan3::translation_frames::FWD_FRAME_1
The second forward frame starting at position 1.
to.hpp
Provides seqan3::views::to.
seqan3::views::take_exactly
constexpr auto take_exactly
A view adaptor that returns the first size elements from the underlying range (or less if the underly...
Definition: take_exactly.hpp:77
seqan3::views::to_lower
const auto to_lower
A view that calls seqan3::to_lower() on each element in the input range.
Definition: to_lower.hpp:66
type_reduce.hpp
Provides seqan3::views::type_reduce.
seqan3::views::to_upper
const auto to_upper
A view that calls seqan3::to_upper() on each element in the input range.
Definition: to_upper.hpp:66
dna5.hpp
Provides seqan3::dna5, container aliases and string literals.
trim.hpp
Provides seqan3::views::trim.
seqan3::views::enforce_random_access
constexpr auto enforce_random_access
A view adaptor that converts a pseudo random access range to a std::random_access_range.
Definition: enforce_random_access.hpp:388
seqan3::views::async_input_buffer
constexpr auto async_input_buffer
A view adapter that returns a concurrent-queue-like view over the underlying range.
Definition: async_input_buffer.hpp:495
seqan3::views::take_until
constexpr auto take_until
A view adaptor that returns elements from the underlying range until the functor evaluates to true (o...
Definition: take_until.hpp:585
persist.hpp
Provides seqan3::views::persist.
to_lower.hpp
Provides seqan3::views::to_lower.
seqan3::views::complement
const auto complement
A view that converts a range of nucleotides to their complement.
Definition: complement.hpp:69
seqan3::phred42
Quality type for traditional Sanger and modern Illumina Phred scores (typical range).
Definition: phred42.hpp:43
seqan3::views::take
constexpr auto take
A view adaptor that returns the first size elements from the underlying range (or less if the underly...
Definition: take.hpp:624
std::rand
T rand(T... args)
seqan3::search_cfg::all
constexpr detail::search_mode_all all
Configuration element to receive all hits within the error bounds.
Definition: mode.hpp:43
seqan3::pack_traits::size
constexpr size_t size
The size of a type pack.
Definition: traits.hpp:116
to_char.hpp
Provides seqan3::views::to_char.
seqan3::translation_frames::FWD
All forward frames.
take.hpp
Provides seqan3::views::take.
ranges
Adaptations of concepts from the Ranges TS.
seqan3::views::drop
constexpr auto drop
A view adaptor that returns all elements after n from the underlying range (or an empty range if the ...
Definition: drop.hpp:168
cstdlib
seqan3::sequence_file_input
A class for reading sequence files, e.g. FASTA, FASTQ ...
Definition: input.hpp:320
enforce_random_access.hpp
Provides seqan3::views::enforce_random_access.
take_exactly.hpp
Provides seqan3::views::take_exactly and seqan3::views::take_exactly_or_throw.
std::ranges::begin
T begin(T... args)
predicate.hpp
Provides character predicates for tokenisation.
async_input_buffer.hpp
Provides seqan3::views::async_input_buffer.
seqan3::views::slice
constexpr auto slice
A view adaptor that returns a half-open interval on the underlying range.
Definition: slice.hpp:141
seqan3::qualified
Joins an arbitrary alphabet with a quality alphabet.
Definition: qualified.hpp:55
seqan3::views::take_line
constexpr auto take_line
A view adaptor that returns a single line from the underlying range or the full range if there is no ...
Definition: take_line.hpp:78
aliases.hpp
Provides aliases for qualified.
seqan3::views::repeat
constexpr detail::repeat_fn repeat
A view factory that repeats a given value infinitely.
Definition: repeat.hpp:350
seqan3::debug_stream
debug_stream_type debug_stream
A global instance of seqan3::debug_stream_type.
Definition: debug_stream.hpp:39
seqan3::views::repeat_n
constexpr auto repeat_n
A view factory that repeats a given value n times.
Definition: repeat_n.hpp:94
std::time
T time(T... args)
seqan3::gap_decorator
A gap decorator allows the annotation of sequences with gap symbols while leaving the underlying sequ...
Definition: gap_decorator.hpp:84
to_upper.hpp
Provides seqan3::views::to_upper.
take_line.hpp
Provides seqan3::views::take_line and seqan3::views::take_line_or_throw.
seqan3::translation_frames::FWD_FRAME_0
The first forward frame starting at position 0.
seqan3::is_blank
constexpr auto is_blank
Checks whether c is a blank character.
Definition: predicate.hpp:163
phred42.hpp
Provides seqan3::phred42 quality scores.
move.hpp
Provides seqan3::views::move.
interleave.hpp
Provides seqan3::views::interleave.
seqan3::views::as_const
const auto as_const
A view that provides only const & to elements of the underlying range.
Definition: as_const.hpp:87
char_to.hpp
Provides seqan3::views::char_to.
seqan3::views::translate_single
constexpr auto translate_single
A view that translates nucleotide into aminoacid alphabet for one of the six frames.
Definition: translate.hpp:504
seqan3::translation_frames::REV_FRAME_0
The first reverse frame starting at position 0.
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:378
get.hpp
Provides seqan3::views::get.
translate_join.hpp
Provides seqan3::views::translate_join.
std::async
T async(T... args)
seqan3::translation_frames::REV_FRAME_2
The third reverse frame starting at position 2.
kmer_hash.hpp
Provides seqan3::views::kmer_hash.
to_rank.hpp
Provides seqan3::views::to_rank.
string