View

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

Collaboration diagram for View:

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

Alphabet related views
template<Alphabet alphabet_type>
auto const	seqan3::view::char_to
	A view over an alphabet, given a range of characters. More...
auto const	seqan3::view::complement
	A view that converts a range of nucleotides to their complement. More...
auto constexpr	seqan3::view::kmer_hash
	A view that calls std::hash on each substring of length k in the input range. More...
template<typename alphabet_type >
auto const	seqan3::view::rank_to
	A view over an alphabet, given a range of ranks. More...
auto const	seqan3::view::to_char
	A view that calls seqan3::to_char() on each element in the input range. More...
auto const	seqan3::view::to_rank
	A view that calls seqan3::to_rank() on each element in the input range. More...
constexpr auto	seqan3::view::translate_single
	A view that translates nucleotide into aminoacid alphabet for one of the six frames. More...
constexpr auto	seqan3::view::translate
	A view that translates nucleotide into aminoacid alphabet with 1, 2, 3 or 6 frames. More...
constexpr auto	seqan3::view::trim
	A view that does quality-threshold trimming on a range of seqan3::QualityAlphabet. More...

General purpose views
template<typename out_t >
auto const	seqan3::view::convert
	A view that converts each element in the input range (implicitly or via static_cast). More...
constexpr auto	seqan3::view::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...
template<auto index>
auto const	seqan3::view::get
	A view calling std::get on each element in a range. More...
constexpr auto	seqan3::view::interleave
	A view that interleaves a given range into another range at regular intervals. More...
constexpr auto	seqan3::view::istreambuf
	A view factory that returns a view over the stream buffer of an input stream. More...
constexpr auto	seqan3::view::pairwise_combine
	A view adaptor that generates all pairwise combinations of the elements of the underlying range. More...
auto constexpr	seqan3::view::persist
	A view adaptor that wraps rvalue references of non-views. More...
constexpr detail::repeat_fn	seqan3::view::repeat
	A view factory that repeats a given value infinitely. More...
constexpr auto	seqan3::view::repeat_n
	A view factory that repeats a given value n times. More...
constexpr auto	seqan3::view::single_pass_input
	A view adapter that decays most of the range properties and adds single pass behavior. More...
constexpr auto	seqan3::view::slice
	A view adaptor that returns a half-open interval on the underlying range. More...
auto constexpr	seqan3::view::take
	A view adaptor that returns the first size elements from the underlying range (or less if the underlying range is shorter). More...
auto constexpr	seqan3::view::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...
auto constexpr	seqan3::view::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...
auto constexpr	seqan3::view::take_line = view::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...
auto constexpr	seqan3::view::take_line_or_throw = view::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...
auto constexpr	seqan3::view::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...
auto constexpr	seqan3::view::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...
auto constexpr	seqan3::view::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...
auto constexpr	seqan3::view::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...
auto const	seqan3::view::to_lower
	A view that calls seqan3::to_lower() on each element in the input range. More...
auto const	seqan3::view::to_upper
	A view that calls seqan3::to_upper() on each element in the input range. More...
constexpr auto	seqan3::view::all
	A view adaptor that behaves like std::view:all, but type erases contiguous ranges. More...

Detailed Description

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

SeqAn3 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 SeqAn3 are specific to biological operations, like seqan3::view::trim which trims sequences based on the quality or seqan3::view::complement which generates the complement of a nucleotide sequence. But SeqAn3 also provides some general purpose views.

Namespaces

• All views from the range-v3 libary are available in the namespace ranges::view.
• All SeqAn views are available in the namespace seqan3::view.

Example

Functional and pipe notations:

dna4_vector vec{"ACGGTC"_dna4};

// these are synonymous:
auto vec_view1 = vec | view::complement;
auto vec_view2 = view::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:

// just re-assign to a container
dna4_vector complemented = vec_view2;
assert(complemented == "TGCCAG"_dna4);

// or immediately create on container
dna4_vector reversed = vec | std::view::reverse;
assert(reversed == "CTGGCA"_dna4);

Composability:

// views can be composed iteratively
auto vec_view3 = vec | std::view::reverse;
auto vec_view4 = vec_view3 | view::complement;

// or in one line similar to the unix command line
auto vec_view5 = vec | view::complement | std::view::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 view::reverse and view::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 view::foo, independent of whether view::foo is the adaptor that returns the "foo type" or whether view::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::view::single, ranges::view::concat and ranges::view::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::view::deep to make any view (adaptor) deep. See seqan3::view::deep for more details.

For all views the following are documented:

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	[required] (usually)	[preserved|lost|guaranteed] (usually preserved)
std::ranges::ForwardRange	[required] (or not)	[preserved|lost|guaranteed]
std::ranges::BidirectionalRange	[required] (or not)	[preserved|lost|guaranteed]
std::ranges::RandomAccessRange	[required] (or not)	[preserved|lost|guaranteed]
std::ranges::ContiguousRange	[required] (or not)	[preserved|lost|guaranteed] (usually lost)
std::ranges::ViewableRange	[required] (usually)	[preserved|lost|guaranteed] (usually guaranteed)
std::ranges::View	[required] (or not)	[preserved|lost|guaranteed] (usually guaranteed)
std::ranges::SizedRange	[required] (or not)	[preserved|lost|guaranteed]
std::ranges::CommonRange	[required] (or not)	[preserved|lost|guaranteed]
std::ranges::OutputRange	[required] (or not)	[preserved|lost|guaranteed]
seqan3::ConstIterableRange	[required] (or not)	[preserved|lost]
seqan3::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::InputRange, but many have stronger requirements, e.g. std::ranges::RandomAccessRange. 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::ViewableRange 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 view::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::InputRange and also std::ranges::View (and conversely also std::ranges::ViewableRange, because all views are viewable). Most views also preserve stronger properties, e.g. std::ranges::RandomAccessRange, but this depends on the view. Some views also add properties not present on the input range, e.g. the range returned by ranges::view::take_exactly meets std::ranges::SizedRange, independent of whether this was met by the input range.

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

Underlying range's reference type: The reference type is the type the elements of the underlying range are accessed by (since dereferencing an iterator or calling operator[] returns the reference type). The reference type may or may not actually contain a & (see below). For many SeqAn specific views additional concept requirements are defined for the input range's reference type, e.g. seqan3::view::complement can only operate on ranges whose elements are nucleotides (meet seqan3::NucleotideAlphabet_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::view::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::view::complement has any actual & removed from the underlying ranges' reference type (if originally present), this goes hand-in-hand with std::ranges::OutputRange being lost → original elements cannot be written to through this view. This is because new elements are being generated. Other views like view::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::OutputRange), but through others you can't.

See also

https://ericniebler.github.io/range-v3/index.html#range-views

Variable Documentation

all

constexpr auto seqan3::view::all

inline

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

Template Parameters

urng_t

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

Parameters

[in]

urange

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

Returns

Either std::basic_string_view{urange}, or std::span{urange}, or std::view::all(urange).

Header

#include <seqan3/range/view/view_all.hpp>

View properties

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved
std::ranges::BidirectionalRange		preserved
std::ranges::RandomAccessRange		preserved
std::ranges::ContiguousRange		preserved
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		preserved
std::ranges::CommonRange		preserved
std::ranges::OutputRange		preserved
seqan3::ConstIterableRange		preserved
seqan3::reference_t		seqan3::reference_t<urng_t>

See the view 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::ForwardingRange && std::ranges::SizedRange && std::ranges::ContiguousRange	std::span
seqan3::ForwardingRange && std::ranges::SizedRange && std::ranges::RandomAccessRange	std::ranges::subrange
else	implementation defined type

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

Example

#include <string>
#include <vector>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/view/view_all.hpp>       // provides view::all, attention not <seqan3/range/view/all.hpp>!

using namespace seqan3;

int main()
{
    std::string vec{"foobar"};
    auto v = vec | view::all;   // pipe notation; v is of type std::string_view
    debug_stream << v << '\n';  // "foobar"

    std::vector vec2{1, 2, 3};
    auto v2 = view::all(vec2);  // functional notation; v is of type std::span
    debug_stream << v2 << '\n'; // "[1, 2, 3]"
}

char_to

template<Alphabet alphabet_type>

auto const seqan3::view::char_to

inline

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

Template Parameters

urng_t	The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
alphabet_t	The alphabet to convert to; must satisfy seqan3::Alphabet.

Parameters

[in]

urange

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

Returns

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

Header

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

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved
std::ranges::BidirectionalRange		preserved
std::ranges::RandomAccessRange		preserved
std::ranges::ContiguousRange		lost
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		preserved
std::ranges::CommonRange		preserved
std::ranges::OutputRange		lost
seqan3::ConstIterableRange		preserved
seqan3::reference_t	seqan3::alphabet_char_t<alphabet_t>	alphabet_t

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

Example

std::string s{"ACTTTGATAN"};
auto v1 = s | view::char_to<dna4>; // == "ACTTTGATAA"_dna4
auto v2 = s | view::char_to<dna5>; // == "ACTTTGATAN"_dna5

complement

auto const seqan3::view::complement

inline

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

Template Parameters

urng_t

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

Parameters

[in]

urange

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

Returns

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

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

Header

#include <seqan3/range/view/complement.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).

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved
std::ranges::BidirectionalRange		preserved
std::ranges::RandomAccessRange		preserved
std::ranges::ContiguousRange		lost
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		preserved
std::ranges::CommonRange		preserved
std::ranges::OutputRange		lost
seqan3::ConstIterableRange		preserved
seqan3::reference_t	seqan3::NucleotideAlphabet	std::remove_reference_t<seqan3::reference_t<urng_t>>

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

Example

dna5_vector foo{"ACGTA"_dna5};

// pipe notation
auto v = foo | view::complement;                                  // == "TGCAT"

// function notation
dna5_vector v2(view::complement(foo));                            // == "TGCAT"

// generate the reverse complement:
dna5_vector v3 = foo | view::complement | std::view::reverse;          // == "TACGT"

convert

template<typename out_t >

auto const seqan3::view::convert

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

Template Parameters

urng_t

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

Parameters

[in]

urange

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

Returns

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

Header

#include <seqan3/range/view/convert.hpp>

View properties

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved
std::ranges::BidirectionalRange		preserved
std::ranges::RandomAccessRange		preserved
std::ranges::View		guaranteed
std::ranges::SizedRange		preserved
std::ranges::CommonRange		preserved
std::ranges::OutputRange		lost
seqan3::ConstIterableRange		preserved
seqan3::reference_t	seqan3::ConvertibleTo<out_t>	out_t

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

Example

Convert from int to bool:

// convert from int to bool
std::vector<int>  vec{7, 5, 0, 5, 0, 0, 4, 8, -3};

// pipe notation
auto v = vec | view::convert<bool>; // == [1, 1, 0, 1, 0, 0, 1, 1, 1];

// function notation and immediate conversion to vector again
std::vector<bool> v2(view::convert<bool>(vec));

// combinability
auto v3 = vec | view::convert<bool> | std::view::reverse; // == [1, 1, 1, 0, 0, 1, 0, 1, 1];

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

dna15_vector vec2{"ACYGTN"_dna15};
auto v4 = vec2 | view::convert<dna5>; // == "ACNGTN"_dna5

drop

constexpr auto seqan3::view::drop

inline

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_t

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

Parameters

[in]	urange	The range being processed. [parameter is omitted in pipe notation]
[in]	drop_size	The number of elements to drop from the beginning.

Returns

All elements of the underlying range after the first drop_size.

Header

#include <seqan3/range/view/drop.hpp>

View properties

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved
std::ranges::BidirectionalRange		preserved
std::ranges::RandomAccessRange		preserved
std::ranges::ContiguousRange		preserved
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		preserved
std::ranges::CommonRange		preserved
std::ranges::OutputRange		preserved
seqan3::ConstIterableRange		preserved
seqan3::reference_t		seqan3::reference_t<urng_t>

See the view 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::ForwardingRange && std::ranges::SizedRange && std::ranges::ContiguousRange	std::span
seqan3::ForwardingRange && std::ranges::SizedRange && std::ranges::RandomAccessRange	std::ranges::subrange
else	implementation defined type

The adaptor is different from std::view::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 if the underlying range models at least std::ranges::RandomAccessRange and std::ranges::SizedRange; otherwise in .

Example

#include <string>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/view/drop.hpp>               // provides view::drop
#include <seqan3/std/ranges>                        // provides std::view::reverse

using namespace seqan3;

int main()
{
    std::string s{"foobar"};
    auto v = s | view::drop(3);
    debug_stream << v << '\n';          // "bar"

    auto v2 = s | std::view::reverse | view::drop(3);
    debug_stream << v2 << '\n';         // "oof"
}

get

template<auto index>

auto const seqan3::view::get

inline

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

Template Parameters

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

Parameters

[in]

urange

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

Returns

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

Header

#include <seqan3/range/view/get.hpp>

View properties

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved
std::ranges::BidirectionalRange		preserved
std::ranges::RandomAccessRange		preserved
std::ranges::ContiguousRange		lost
std::ranges::ViewableRange	required	preserved
std::ranges::View		preserved
std::ranges::SizedRange		preserved
std::ranges::CommonRange		preserved
std::ranges::OutputRange		preserved
seqan3::ConstIterableRange		preserved
seqan3::reference_t	seqan3::TupleLike	std::tuple_element_t<index, seqan3::reference_t<urng_t>>

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

Example

// Create a vector of dna4 quality composite alphabet.
std::vector<dna4q> qv{{'A'_dna4, phred42{0}}, {'C'_dna4, phred42{1}}, {'G'_dna4, phred42{2}}, {'T'_dna4, phred42{3}}};

debug_stream << (qv | view::get<0> | view::to_char) << std::endl; // Prints [A,C,G,T]
debug_stream << (qv | view::get<1> | view::to_char) << std::endl; // Prints [!,",#,$]

interleave

constexpr auto seqan3::view::interleave

inline

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

Template Parameters

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

Parameters

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

Returns

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

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

Header

#include <seqan3/range/view/interleave.hpp>

View properties

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange	required	preserved
std::ranges::BidirectionalRange	required	preserved
std::ranges::RandomAccessRange	required	preserved
std::ranges::ContiguousRange		lost
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange	required	preserved
std::ranges::CommonRange		preserved
std::ranges::OutputRange		preserved
seqan3::ConstIterableRange		preserved
seqan3::reference_t		seqan3::reference_t<urng_t>

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

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange	required	lost
std::ranges::BidirectionalRange		lost
std::ranges::RandomAccessRange		lost
std::ranges::ContiguousRange		lost
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		lost
std::ranges::CommonRange		lost
std::ranges::OutputRange		lost
seqan3::ConstIterableRange		lost
seqan3::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 View.

Example

#include <range/v3/algorithm/equal.hpp>

#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/view/interleave.hpp>

int main()
{
    std::string u{"FOOBARBAXBAT"};
    std::string i{"in"};
    size_t s = 3;

    auto v = u | seqan3::view::interleave(s, i);

    seqan3::debug_stream << v << '\n'; // prints FOOinBARinBAXinBAT
}

istreambuf

constexpr auto seqan3::view::istreambuf

inline

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

Template Parameters

istreambuf_t

The type of the stream(buffer); must be std::basic_streambuf or model seqan3::IStream2.

Parameters

[in]

istreambuf

The stream buffer or an input stream of whome the buffer is retrieved.

Returns

Header

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

View properties

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

range concepts and reference_t	rrng_t (returned range type)
std::ranges::InputRange	guaranteed
std::ranges::ForwardRange
std::ranges::BidirectionalRange
std::ranges::RandomAccessRange
std::ranges::ContiguousRange
std::ranges::ViewableRange	guaranteed
std::ranges::View	guaranteed
std::ranges::SizedRange
std::ranges::CommonRange
std::ranges::OutputRange
seqan3::ConstIterableRange	guaranteed
seqan3::reference_t	istream_t::char_type

See the view 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

auto constexpr seqan3::view::kmer_hash

inline

A view that calls std::hash on each substring of length k in the input range.

Template Parameters

urng_t

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

Parameters

[in]

urange

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

Returns

A range of unsigned integral values where each value is the hash of the resp. k-mer. See below for the properties of the returned range.

Header

#include <seqan3/range/view/kmer_hash.hpp>

View properties

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange	required	preserved
std::ranges::BidirectionalRange		preserved
std::ranges::RandomAccessRange		preserved
std::ranges::ContiguousRange		lost
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		preserved
std::ranges::CommonRange		preserved
std::ranges::OutputRange		lost
seqan3::ConstIterableRange		preserved
seqan3::reference_t	seqan3::Semialphabet	std::size_t

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

Example

#include <seqan3/alphabet/nucleotide/dna4.hpp>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/view/kmer_hash.hpp>

using namespace seqan3;

int main()
{
    std::vector<dna4> text{"ACGTAGC"_dna4};
    std::vector<size_t> hashes = text | view::kmer_hash(3);
    debug_stream << hashes << '\n'; // [6,27,44,50,9]
}

pairwise_combine

constexpr auto seqan3::view::pairwise_combine

inline

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

Template Parameters

urng_t

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

Parameters

[in]

urange

The range being processed.

Returns

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

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

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.

Header

#include <seqan3/range/view/pairwise_combine.hpp>

View properties

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange	required	preserved
std::ranges::BidirectionalRange		preserved
std::ranges::RandomAccessRange		preserved
std::ranges::ContiguousRange		lost
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		preserved
std::ranges::CommonRange	required	guaranteed
std::ranges::OutputRange		lost
seqan3::ConstIterableRange		preserved
seqan3::reference_t		std::tuple<seqan3::reference_t<urng_t>, seqan3::reference_t<urng_t>>

See the view 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/view/pairwise_combine.hpp>

using namespace seqan3;

int main()
{
    std::vector vec{'a', 'b', 'c', 'd'};
    for (auto res : vec | view::pairwise_combine)
    {
        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

auto constexpr seqan3::view::persist

inline

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

Template Parameters

urng_t

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

Parameters

[in]

urange

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

Returns

A range wrapped in a view (even if it doesn't model std::ranges::ViewableRange).

For ranges that model std::ranges::ViewableRange, this adaptor just returns std::view::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.

Header

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

View properties

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved
std::ranges::BidirectionalRange		preserved
std::ranges::RandomAccessRange		preserved
std::ranges::ContiguousRange		preserved
std::ranges::ViewableRange	not required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		preserved
std::ranges::CommonRange		preserved
std::ranges::OutputRange		preserved
seqan3::ConstIterableRange		preserved
seqan3::reference_t		seqan3::reference_t<urng_t>

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

Example

// this doesn't work:
//auto v = "ACGT"_dna4 | view::to_char;

// this works, because we explicitly create an l-value of our dna vector:
auto vec = "ACGT"_dna4;
auto v = vec | view::to_char;

// using view::persist you can bind the temporary directly:
auto v2 = "ACGT"_dna4 | view::persist | view::to_char;

// note that view::persist must follow immediately after the temporary, the following does not work:
//auto v3 = "ACGT"_dna4 | view::to_char | view::persist;

// thus the function notation might be more intuitive:
auto v3 = view::persist("ACGT"_dna4) | view::to_char;

rank_to

template<typename alphabet_type >

auto const seqan3::view::rank_to

inline

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

Template Parameters

urng_t	The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
alphabet_t	The alphabet to convert to; must satisfy seqan3::WritableSemialphabet.

Parameters

[in]

urange

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

Returns

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

Header

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

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved
std::ranges::BidirectionalRange		preserved
std::ranges::RandomAccessRange		preserved
std::ranges::ContiguousRange		lost
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		preserved
std::ranges::CommonRange		preserved
std::ranges::OutputRange		lost
seqan3::ConstIterableRange		preserved
seqan3::reference_t	seqan3::alphabet_rank_t<alphabet_t>	alphabet_t

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

Example

std::vector<int> vec{0, 1, 3, 3, 3, 2, 0, 3, 0};
auto v1 = vec | view::rank_to<dna4>; // == "ACTTTGATA"_dna4
auto v2 = vec | view::rank_to<dna5>; // == "ACTTTGATA"_dna5

repeat

constexpr detail::repeat_fn seqan3::view::repeat

inline

A view factory that repeats a given value infinitely.

Template Parameters

value_t

The type of value to repeat wrapped in a std::view::single; must model std::CopyConstructible.

Parameters

[in]

value

The value to repeat.

Returns

An infinite range over value.

Header

#include <seqan3/range/view/repeat.hpp>

View properties

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

range concepts and reference_t	rrng_t (returned range type)
std::ranges::InputRange	guaranteed
std::ranges::ForwardRange	guaranteed
std::ranges::BidirectionalRange	guaranteed
std::ranges::RandomAccessRange	guaranteed
std::ranges::ContiguousRange
std::ranges::ViewableRange	guaranteed
std::ranges::View	guaranteed
std::ranges::SizedRange
std::ranges::CommonRange
std::ranges::OutputRange	guaranteed
seqan3::ConstIterableRange	guaranteed
seqan3::reference_t	std::remove_reference_t<value_t> &

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

Attention

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

Example

#include <iostream>

#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/view/repeat.hpp>
#include <seqan3/std/ranges>

using namespace seqan3;

int main()
{
    auto v = view::repeat('A');

    debug_stream << *std::ranges::begin(v) << std::endl; // prints 'A'
    debug_stream << v[12355] << std::endl;               // also prints 'A'. It always prints 'A'

    v[1345] = 'C';

    // Now it always prints 'C'
    debug_stream << *std::ranges::begin(v) << std::endl; // prints 'C'
    debug_stream << v[12355] << std::endl;               // prints 'C'
}

repeat_n

constexpr auto seqan3::view::repeat_n

inline

A view factory that repeats a given value n times.

Template Parameters

value_t

The type of value to repeat; must be std::CopyConstructible.

Parameters

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

Returns

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

Header

#include <seqan3/range/view/repeat_n.hpp>

View properties

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

range concepts and reference_t	rrng_t (returned range type)
std::ranges::InputRange	guaranteed
std::ranges::ForwardRange	guaranteed
std::ranges::BidirectionalRange	guaranteed
std::ranges::RandomAccessRange	guaranteed
std::ranges::ContiguousRange
std::ranges::ViewableRange	guaranteed
std::ranges::View	guaranteed
std::ranges::SizedRange	guaranteed
std::ranges::CommonRange
std::ranges::OutputRange	guaranteed
seqan3::ConstIterableRange	guaranteed
seqan3::reference_t	std::remove_reference_t<value_t> &

See the view 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/view/repeat_n.hpp>
#include <seqan3/std/ranges>

using namespace seqan3;

int main()
{
    auto v = view::repeat_n(std::string{"foo"}, 5);

    debug_stream << v.size() << std::endl; // prints 5
    debug_stream << v << std::endl;        // prints ["foo", "foo", "foo", "foo", "foo"]

    v[0] = std::string{"foobar"};

    // Now it always prints "foobar"
    debug_stream << *std::ranges::begin(v) << std::endl; // prints "foobar"
    debug_stream << v.size() << std::endl;               // prints 5; Note: the size cannot be changed anymore
}

single_pass_input

constexpr auto seqan3::view::single_pass_input

inline

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

Template Parameters

urng_t

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

Parameters

[in]

urange

The range being processed.

Returns

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

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.

Header

#include <seqan3/range/view/single_pass_input.hpp>

View properties

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		lost
std::ranges::BidirectionalRange		lost
std::ranges::RandomAccessRange		lost
std::ranges::ContiguousRange		lost
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		lost
std::ranges::CommonRange		lost
std::ranges::OutputRange		preserved
seqan3::ConstIterableRange		lost
seqan3::reference_t		seqan3::reference_t<urng_t>

See the view 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

std::string str{"hello"};
auto v = str | view::single_pass_input;
debug_stream << *++v.begin() << std::endl;  // prints 'e'
debug_stream << *++v.begin() << std::endl;  // prints 'l'
debug_stream << *++v.begin() << std::endl;  // prints 'l'
debug_stream << *++v.begin() << std::endl;  // prints 'o'

slice

constexpr auto seqan3::view::slice

inline

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

Template Parameters

urng_t

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

Parameters

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

Returns

Up to end_pos - begin_pos elements of the underlying range.

Exceptions

std::invalid_argument

If end_pos < begin_pos.

Header

#include <seqan3/range/view/slice.hpp>

View properties

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved
std::ranges::BidirectionalRange		preserved
std::ranges::RandomAccessRange		preserved
std::ranges::ContiguousRange		preserved
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		preserved
std::ranges::CommonRange		preserved
std::ranges::OutputRange		preserved
seqan3::ConstIterableRange		preserved
seqan3::reference_t		seqan3::reference_t<urng_t>

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

This adaptor is a combination of seqan3::view::drop and seqan3::view::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::ForwardingRange && std::ranges::SizedRange && std::ranges::ContiguousRange	std::span
seqan3::ForwardingRange && std::ranges::SizedRange && std::ranges::RandomAccessRange	std::ranges::subrange
else	implementation defined type

The adaptor returns exactly the type specified above.

Complexity

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

Example

#include <string>
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/range/view/slice.hpp>              // provides view::slice
#include <seqan3/std/ranges>                        // provides std::view::reverse

using namespace seqan3;

int main()
{
    std::string s{"foobar"};
    auto v = s | view::slice(1,4);
    debug_stream << v << '\n';      // "oob"

    auto v2 = s | std::view::reverse | view::slice(1, 4);
    debug_stream << v2 << '\n';     // "abo"

}

take

auto constexpr seqan3::view::take

inline

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

Template Parameters

urng_t

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

Parameters

[in]	urange	The range being processed. [parameter is omitted in pipe notation]
[in]	size	The target size of the view.

Returns

Up to size elements of the underlying range.

Header

#include <seqan3/range/view/take.hpp>

View properties

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved
std::ranges::BidirectionalRange		preserved
std::ranges::RandomAccessRange		preserved
std::ranges::ContiguousRange		preserved
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		preserved
std::ranges::CommonRange		preserved
std::ranges::OutputRange		preserved
seqan3::ConstIterableRange		preserved
seqan3::reference_t		seqan3::reference_t<urng_t>

See the view 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::ForwardingRange && std::ranges::SizedRange && std::ranges::ContiguousRange	std::span
seqan3::ForwardingRange && std::ranges::SizedRange && std::ranges::RandomAccessRange	std::ranges::subrange
else	implementation defined type

This adaptor is different from std::view::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::view::take for pure forward and input ranges.

Example

std::string vec{"foobar"};
auto v = vec | view::take(3);
debug_stream << v << '\n'; // [f,o,o]

auto v2 = vec | std::view::reverse | view::take(3);
debug_stream << v2 << '\n'; // [r,a,b]

take_exactly

auto constexpr seqan3::view::take_exactly

inline

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_t

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

Parameters

[in]	urange	The range being processed. [parameter is omitted in pipe notation]
[in]	size	The target size of the view.

Returns

Up to size elements of the underlying range.

Header

#include <seqan3/range/view/take_exactly.hpp>

View properties

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved
std::ranges::BidirectionalRange		preserved
std::ranges::RandomAccessRange		preserved
std::ranges::ContiguousRange		preserved
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		guaranteed
std::ranges::CommonRange		preserved
std::ranges::OutputRange		preserved except if urng_t is std::basic_string
seqan3::ConstIterableRange		preserved
seqan3::reference_t		seqan3::reference_t<urng_t>

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

The difference to seqan3::view::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::view::take_exactly if the underlying range is shorter than size, the behaviour is undefined. seqan3::view::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/view/take_exactly.hpp>           // provides view::take_exactly and view::take_exactly_or_throw

using namespace seqan3;

int main()
{
    std::string vec{"foobar"};
    auto v = vec | view::take_exactly(3);               // or view::take_exactly_or_throw
    debug_stream << v << '\n';                          // "foo"
    debug_stream << std::ranges::size(v) << '\n';       // 3


    auto v2 = vec | view::take_exactly(9);
    debug_stream << std::ranges::size(v2) << '\n';      // 9 <- here be dragons!
//     debug_stream << v2 << '\n';                      // possibly memory access violation

//     auto v3 = vec | view::take_exactly_or_throw(9);  // safe, throws immediately on construction

}

take_exactly_or_throw

auto constexpr seqan3::view::take_exactly_or_throw

inline

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_input

If the underlying range is smaller than size.

Template Parameters

urng_t

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

Parameters

[in]	urange	The range being processed. [parameter is omitted in pipe notation]
[in]	size	The target size of the view.

Returns

Up to size elements of the underlying range.

Header

#include <seqan3/range/view/take_exactly.hpp>

View properties

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved
std::ranges::BidirectionalRange		preserved
std::ranges::RandomAccessRange		preserved
std::ranges::ContiguousRange		preserved
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		guaranteed
std::ranges::CommonRange		preserved
std::ranges::OutputRange		preserved except if urng_t is std::basic_string
seqan3::ConstIterableRange		preserved
seqan3::reference_t		seqan3::reference_t<urng_t>

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

The difference to seqan3::view::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::view::take_exactly if the underlying range is shorter than size, the behaviour is undefined. seqan3::view::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/view/take_exactly.hpp>           // provides view::take_exactly and view::take_exactly_or_throw

using namespace seqan3;

int main()
{
    std::string vec{"foobar"};
    auto v = vec | view::take_exactly(3);               // or view::take_exactly_or_throw
    debug_stream << v << '\n';                          // "foo"
    debug_stream << std::ranges::size(v) << '\n';       // 3


    auto v2 = vec | view::take_exactly(9);
    debug_stream << std::ranges::size(v2) << '\n';      // 9 <- here be dragons!
//     debug_stream << v2 << '\n';                      // possibly memory access violation

//     auto v3 = vec | view::take_exactly_or_throw(9);  // safe, throws immediately on construction

}

take_line

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

inline

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

Template Parameters

urng_t

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

Parameters

[in]

urange

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

Returns

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.

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::ForwardRange this is the same as calling

ranges::view::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).

Header

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

View properties

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved
std::ranges::BidirectionalRange		preserved
std::ranges::RandomAccessRange		preserved
std::ranges::ContiguousRange		preserved
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		lost
std::ranges::CommonRange		lost
std::ranges::OutputRange		preserved
seqan3::ConstIterableRange		preserved
seqan3::reference_t	std::CommonReference<char>	seqan3::reference_t<urng_t>

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

Example

Behaviour on std::ranges::ForwardRange:

std::string vec{"foo\nbar"};
auto v = vec | view::take_line;
debug_stream << v << '\n'; // [f,o,o]

auto v2 = vec | std::view::reverse | view::take_line;
debug_stream << v2 << '\n'; // [r,a,b]
debug_stream << v2 << '\n'; // [r,a,b] (parsing it again gives us the same result)

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

std::string vec{"foo\nbar"};
auto v = vec | view::single_pass_input | view::take_line;
debug_stream << v << '\n'; // [f,o,o]
debug_stream << v << '\n'; // [b,a,r] (parsing it again gives us the next line)

take_line_or_throw

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

inline

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_input

If the underlying range contains no end-of-line marker.

Template Parameters

urng_t

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

Parameters

[in]

urange

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

Returns

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.

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::ForwardRange this is the same as calling

ranges::view::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).

Header

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

View properties

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved
std::ranges::BidirectionalRange		preserved
std::ranges::RandomAccessRange		preserved
std::ranges::ContiguousRange		preserved
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		lost
std::ranges::CommonRange		lost
std::ranges::OutputRange		preserved
seqan3::ConstIterableRange		preserved
seqan3::reference_t	std::CommonReference<char>	seqan3::reference_t<urng_t>

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

Example

Behaviour on std::ranges::ForwardRange:

std::string vec{"foo\nbar"};
auto v = vec | view::take_line;
debug_stream << v << '\n'; // [f,o,o]

auto v2 = vec | std::view::reverse | view::take_line;
debug_stream << v2 << '\n'; // [r,a,b]
debug_stream << v2 << '\n'; // [r,a,b] (parsing it again gives us the same result)

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

std::string vec{"foo\nbar"};
auto v = vec | view::single_pass_input | view::take_line;
debug_stream << v << '\n'; // [f,o,o]
debug_stream << v << '\n'; // [b,a,r] (parsing it again gives us the next line)

take_until

auto constexpr seqan3::view::take_until

inline

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_t	The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
fun_t	The type of the functor; must model std::Invocable with seqan3::reference_t<urng_t> and return a type convertible to bool.

Parameters

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

Returns

All elements of the underlying range up until (but excluding) the element that evaluates the functor to true.

Header

#include <seqan3/range/view/take_until.hpp>

View properties

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved*¹
std::ranges::BidirectionalRange		*preserved*¹
std::ranges::RandomAccessRange		*preserved*¹
std::ranges::ContiguousRange		*preserved*¹
std::ranges::ViewableRange	*required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		lost
std::ranges::CommonRange		lost
std::ranges::OutputRange		preserved
seqan3::ConstIterableRange		*preserved*¹
seqan3::reference_t		seqan3::reference_t<urng_t>

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

¹ The marked properties are only preserved if the specified functor models std::RegularInvocable<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::RegularInvocable these concepts are lost.

Throwing: seqan3::view::take_until_or_throw and seqan3::view::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::view::take_until_and_consume and seqan3::view::take_until_or_throw_and_consume behave the same as their non-consuming counter-parts if the underlying range models at least std::ForwardRange. If, however, the underlying range is a pure std::InputRange, 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 <seqan3/core/char_operations/predicate.hpp>// for is_char
#include <seqan3/core/debug_stream.hpp>             // for debug_stream
#include <seqan3/range/view/single_pass_input.hpp>  // for view::single_pass_input
#include <seqan3/range/view/take_until.hpp>         // for view::take_until*
#include <seqan3/std/ranges>                        // for std::view::reverse

using namespace seqan3;

int main()
{
    // regular usage
    std::string vec{"foo\nbar"};
    auto v = vec | view::take_until(is_char<'\n'>); // or use a lambda
    debug_stream << v << '\n'; // "foo"

    auto v2 = vec | std::view::reverse | view::take_until(is_char<'\n'>);
    debug_stream << v2 << '\n'; // "rab"

    // consuming behaviour
    std::string vec2{"foo      bar"}; // ← multiple spaces
    auto vin = vec2 | view::single_pass_input;
    auto v3 = vin | view::take_until_and_consume(is_blank);
    debug_stream << v3 << '\n'; // "foo"
    debug_stream << *std::ranges::begin(vin) << '\n'; // "b", the spaces where skipped
}

take_until_and_consume

auto constexpr seqan3::view::take_until_and_consume

inline

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_input

If the underlying range contains no element that satisfies the functor.

Template Parameters

urng_t	The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
fun_t	The type of the functor; must model std::Invocable with seqan3::reference_t<urng_t> and return a type convertible to bool.

Parameters

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

Returns

All elements of the underlying range up until (but excluding) the element that evaluates the functor to true.

Header

#include <seqan3/range/view/take_until.hpp>

View properties

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved*¹
std::ranges::BidirectionalRange		*preserved*¹
std::ranges::RandomAccessRange		*preserved*¹
std::ranges::ContiguousRange		*preserved*¹
std::ranges::ViewableRange	*required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		lost
std::ranges::CommonRange		lost
std::ranges::OutputRange		preserved
seqan3::ConstIterableRange		*preserved*¹
seqan3::reference_t		seqan3::reference_t<urng_t>

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

¹ The marked properties are only preserved if the specified functor models std::RegularInvocable<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::RegularInvocable these concepts are lost.

Throwing: seqan3::view::take_until_or_throw and seqan3::view::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::view::take_until_and_consume and seqan3::view::take_until_or_throw_and_consume behave the same as their non-consuming counter-parts if the underlying range models at least std::ForwardRange. If, however, the underlying range is a pure std::InputRange, 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 <seqan3/core/char_operations/predicate.hpp>// for is_char
#include <seqan3/core/debug_stream.hpp>             // for debug_stream
#include <seqan3/range/view/single_pass_input.hpp>  // for view::single_pass_input
#include <seqan3/range/view/take_until.hpp>         // for view::take_until*
#include <seqan3/std/ranges>                        // for std::view::reverse

using namespace seqan3;

int main()
{
    // regular usage
    std::string vec{"foo\nbar"};
    auto v = vec | view::take_until(is_char<'\n'>); // or use a lambda
    debug_stream << v << '\n'; // "foo"

    auto v2 = vec | std::view::reverse | view::take_until(is_char<'\n'>);
    debug_stream << v2 << '\n'; // "rab"

    // consuming behaviour
    std::string vec2{"foo      bar"}; // ← multiple spaces
    auto vin = vec2 | view::single_pass_input;
    auto v3 = vin | view::take_until_and_consume(is_blank);
    debug_stream << v3 << '\n'; // "foo"
    debug_stream << *std::ranges::begin(vin) << '\n'; // "b", the spaces where skipped
}

take_until_or_throw

auto constexpr seqan3::view::take_until_or_throw

inline

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_input

If the underlying range contains no element that satisfies the functor.

Template Parameters

urng_t	The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
fun_t	The type of the functor; must model std::Invocable with seqan3::reference_t<urng_t> and return a type convertible to bool.

Parameters

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

Returns

All elements of the underlying range up until (but excluding) the element that evaluates the functor to true.

Header

#include <seqan3/range/view/take_until.hpp>

View properties

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved*¹
std::ranges::BidirectionalRange		*preserved*¹
std::ranges::RandomAccessRange		*preserved*¹
std::ranges::ContiguousRange		*preserved*¹
std::ranges::ViewableRange	*required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		lost
std::ranges::CommonRange		lost
std::ranges::OutputRange		preserved
seqan3::ConstIterableRange		*preserved*¹
seqan3::reference_t		seqan3::reference_t<urng_t>

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

¹ The marked properties are only preserved if the specified functor models std::RegularInvocable<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::RegularInvocable these concepts are lost.

Throwing: seqan3::view::take_until_or_throw and seqan3::view::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::view::take_until_and_consume and seqan3::view::take_until_or_throw_and_consume behave the same as their non-consuming counter-parts if the underlying range models at least std::ForwardRange. If, however, the underlying range is a pure std::InputRange, 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 <seqan3/core/char_operations/predicate.hpp>// for is_char
#include <seqan3/core/debug_stream.hpp>             // for debug_stream
#include <seqan3/range/view/single_pass_input.hpp>  // for view::single_pass_input
#include <seqan3/range/view/take_until.hpp>         // for view::take_until*
#include <seqan3/std/ranges>                        // for std::view::reverse

using namespace seqan3;

int main()
{
    // regular usage
    std::string vec{"foo\nbar"};
    auto v = vec | view::take_until(is_char<'\n'>); // or use a lambda
    debug_stream << v << '\n'; // "foo"

    auto v2 = vec | std::view::reverse | view::take_until(is_char<'\n'>);
    debug_stream << v2 << '\n'; // "rab"

    // consuming behaviour
    std::string vec2{"foo      bar"}; // ← multiple spaces
    auto vin = vec2 | view::single_pass_input;
    auto v3 = vin | view::take_until_and_consume(is_blank);
    debug_stream << v3 << '\n'; // "foo"
    debug_stream << *std::ranges::begin(vin) << '\n'; // "b", the spaces where skipped
}

take_until_or_throw_and_consume

auto constexpr seqan3::view::take_until_or_throw_and_consume

inline

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_input

If the underlying range contains no element that satisfies the functor.

Template Parameters

urng_t	The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation]
fun_t	The type of the functor; must model std::Invocable with seqan3::reference_t<urng_t> and return a type convertible to bool.

Parameters

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

Returns

All elements of the underlying range up until (but excluding) the element that evaluates the functor to true.

Header

#include <seqan3/range/view/take_until.hpp>

View properties

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved*¹
std::ranges::BidirectionalRange		*preserved*¹
std::ranges::RandomAccessRange		*preserved*¹
std::ranges::ContiguousRange		*preserved*¹
std::ranges::ViewableRange	*required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		lost
std::ranges::CommonRange		lost
std::ranges::OutputRange		preserved
seqan3::ConstIterableRange		*preserved*¹
seqan3::reference_t		seqan3::reference_t<urng_t>

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

¹ The marked properties are only preserved if the specified functor models std::RegularInvocable<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::RegularInvocable these concepts are lost.

Throwing: seqan3::view::take_until_or_throw and seqan3::view::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::view::take_until_and_consume and seqan3::view::take_until_or_throw_and_consume behave the same as their non-consuming counter-parts if the underlying range models at least std::ForwardRange. If, however, the underlying range is a pure std::InputRange, 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 <seqan3/core/char_operations/predicate.hpp>// for is_char
#include <seqan3/core/debug_stream.hpp>             // for debug_stream
#include <seqan3/range/view/single_pass_input.hpp>  // for view::single_pass_input
#include <seqan3/range/view/take_until.hpp>         // for view::take_until*
#include <seqan3/std/ranges>                        // for std::view::reverse

using namespace seqan3;

int main()
{
    // regular usage
    std::string vec{"foo\nbar"};
    auto v = vec | view::take_until(is_char<'\n'>); // or use a lambda
    debug_stream << v << '\n'; // "foo"

    auto v2 = vec | std::view::reverse | view::take_until(is_char<'\n'>);
    debug_stream << v2 << '\n'; // "rab"

    // consuming behaviour
    std::string vec2{"foo      bar"}; // ← multiple spaces
    auto vin = vec2 | view::single_pass_input;
    auto v3 = vin | view::take_until_and_consume(is_blank);
    debug_stream << v3 << '\n'; // "foo"
    debug_stream << *std::ranges::begin(vin) << '\n'; // "b", the spaces where skipped
}

to_char

auto const seqan3::view::to_char

inline

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

Template Parameters

urng_t

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

Parameters

[in]

urange

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

Returns

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

Header

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

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved
std::ranges::BidirectionalRange		preserved
std::ranges::RandomAccessRange		preserved
std::ranges::ContiguousRange		lost
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		preserved
std::ranges::CommonRange		preserved
std::ranges::OutputRange		lost
seqan3::ConstIterableRange		preserved
seqan3::reference_t	seqan3::Alphabet	seqan3::alphabet_char_t<seqan3::value_type_t<urng_t>>

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

Example

dna4_vector vec = "ACTTTGATA"_dna4;
auto v = vec | view::to_char;
debug_stream << v << '\n'; // [A,C,T,T,T,G,A,T,A]

std::vector<phred42> qvec{{0}, {7}, {5}, {3}, {7}, {4}, {30}, {16}, {23}};
auto v3 = qvec | view::to_char;
debug_stream << v3 << '\n'; // [!,(,&,$,(,%,?,1,8]

std::vector<dna4q> qcvec{{'C'_dna4, phred42{0}}, {'A'_dna4, phred42{7}}, {'G'_dna4, phred42{5}}, {'T'_dna4, phred42{3}},
                         {'G'_dna4, phred42{7}}, {'A'_dna4, phred42{4}}, {'C'_dna4, phred42{30}}, {'T'_dna4, phred42{16}}, {'A'_dna4, phred42{23}}};
auto v4 = qcvec | view::to_char;
debug_stream << v4 << '\n'; // [C,A,G,T,G,A,C,T,A]

to_lower

auto const seqan3::view::to_lower

inline

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

Template Parameters

urng_t

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

Parameters

[in]

urange

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

Returns

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

Header

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

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved
std::ranges::BidirectionalRange		preserved
std::ranges::RandomAccessRange		preserved
std::ranges::ContiguousRange		lost
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		preserved
std::ranges::CommonRange		preserved
std::ranges::OutputRange		lost
seqan3::ConstIterableRange		preserved
seqan3::reference_t	seqan3::Char	seqan3::remove_reference_t<seqan3::reference_t<urngt_>>

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

Example

std::string s{"CHanGED!"};
std::vector<std::string> sv{"CHANGED", "unchanged!"};
auto v1 = s | view::to_lower; 
auto v2 = sv | view::to_lower; 

debug_stream << v1 << '\n'; // => "changed!"
debug_stream << v2 << '\n'; // => ["changed", "unchanged!"]

to_rank

auto const seqan3::view::to_rank

inline

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

Template Parameters

urng_t

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

Parameters

[in]

urange

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

Returns

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

Header

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

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved
std::ranges::BidirectionalRange		preserved
std::ranges::RandomAccessRange		preserved
std::ranges::ContiguousRange		lost
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		preserved
std::ranges::CommonRange		preserved
std::ranges::OutputRange		lost
seqan3::ConstIterableRange		preserved
seqan3::reference_t	seqan3::Alphabet	seqan3::alphabet_rank_t<seqan3::value_type_t<urng_t>>

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

Example

dna4_vector vec = "ACTTTGATA"_dna4;
auto v = vec | view::to_rank | view::convert<unsigned>;
debug_stream << v << '\n'; // [0,1,3,3,3,2,0,3,0]

std::vector<phred42> qvec{{0}, {7}, {5}, {3}, {7}, {4}, {30}, {16}, {23}};
auto v3 = qvec | view::to_rank | view::convert<unsigned>;
debug_stream << v3 << '\n'; // [0,7,5,3,7,4,30,16,23]

std::vector<dna4q> qcvec{{'C'_dna4, phred42{0}}, {'A'_dna4, phred42{7}}, {'G'_dna4, phred42{5}}, {'T'_dna4, phred42{3}},
                         {'G'_dna4, phred42{7}}, {'A'_dna4, phred42{4}}, {'C'_dna4, phred42{30}}, {'T'_dna4, phred42{16}}, {'A'_dna4, phred42{23}}};
auto v4 = qcvec | view::to_rank | view::convert<unsigned>;
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

auto const seqan3::view::to_upper

inline

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

Template Parameters

urng_t

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

Parameters

[in]

urange

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

Returns

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

Header

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

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved
std::ranges::BidirectionalRange		preserved
std::ranges::RandomAccessRange		preserved
std::ranges::ContiguousRange		lost
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange		preserved
std::ranges::CommonRange		preserved
std::ranges::OutputRange		lost
seqan3::ConstIterableRange		preserved
seqan3::reference_t	seqan3::Char	seqan3::remove_reference_t<seqan3::reference_t<urngt_>>

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

Example

std::string s{"CHanGED!"};
std::vector<std::string> sv{"changed", "UNCHANGED!"};
auto v1 = s | view::to_upper; 
auto v2 = sv | view::to_upper; 

debug_stream << v1 << '\n'; // => "CHANGED!"
debug_stream << v2 << '\n'; // => ["CHANGED", "UNCHANGED!"]

translate

constexpr auto seqan3::view::translate

inline

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

Template Parameters

urng_t

The type of the range being processed.

Parameters

[in]	urange	The range being processed.
[in]	tf	A 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.

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

Header

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

View properties

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange	required	preserved
std::ranges::BidirectionalRange	required	preserved
std::ranges::RandomAccessRange	required	preserved
std::ranges::ContiguousRange		lost
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange	required	preserved
std::ranges::CommonRange		guaranteed
std::ranges::OutputRange		lost
seqan3::ConstIterableRange	required	preserved
seqan3::reference_t	seqan3::NucleotideAlphabet	std::ranges::View && std::ranges::RandomAccessRange && std::ranges::SizedRange

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

Example

Operating on a range of seqan3::dna5:

dna5_vector vec{"ACGTACGTACGTA"_dna5};

// default frame translation
auto v1 = vec | view::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 | view::translate(translation_frames::FWD_FRAME_0);                                               // == [[T,Y,V,R]]

// reverse translation
auto v3 = vec | view::translate(translation_frames::FWD_REV_0);                                       // == [[T,Y,V,R],[Y,V,R,T]]

// forward frames translation
auto v4 = vec | view::translate(translation_frames::FWD);                                     // == [[T,Y,V,R],[R,T,Y,V],[V,R,T]]

// six frame translation
auto v5 = vec | view::translate(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 = view::translate(vec, translation_frames::FWD_REV_0);                                        // == [[T,Y,V,R],[Y,V,R,T]]

// combinability
auto v7 = vec | view::complement | view::translate(translation_frames::FWD_REV_0);                    // == [[C,M,H,A],[M,H,A,C]]

translate_single

constexpr auto seqan3::view::translate_single

inline

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

Template Parameters

urng_t

The type of the range being processed.

Parameters

[in]	urange	The range being processed.
[in]	tf	A 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.

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

Header

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

View properties

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange	required	preserved
std::ranges::BidirectionalRange	required	preserved
std::ranges::RandomAccessRange	required	preserved
std::ranges::ContiguousRange		lost
std::ranges::ViewableRange	required	guaranteed
std::ranges::View		guaranteed
std::ranges::SizedRange	required	preserved
std::ranges::CommonRange		guaranteed
std::ranges::OutputRange		lost
seqan3::ConstIterableRange	required	preserved
seqan3::reference_t	seqan3::NucleotideAlphabet	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 View.

Example

Operating on a range of seqan3::dna5:

dna5_vector vec{"ACGTACGTACGTA"_dna5};

// Default (first forward frame)
auto v1 = vec | view::translate_single;                                                           // == [T,Y,V,R]
debug_stream << v1[1] << '\n';

// First forward frame
auto v2 = vec | view::translate_single(translation_frames::FWD_FRAME_0);                          // == [T,Y,V,R]

// First reverse frame
auto v3 = vec | view::translate_single(translation_frames::REV_FRAME_0);                          // == [Y,V,R,T]

// Second forward frame
auto v4 = vec | view::translate_single(translation_frames::FWD_FRAME_1);                          // == [R,T,Y,V]

// Second reverse frame
auto v5 = vec | view::translate_single(translation_frames::REV_FRAME_1);                          // == [T,Y,V,R]

// Third forward frame
auto v6 = vec | view::translate_single(translation_frames::FWD_FRAME_2);                            // == [V,R,T]

// Third reverse frame
auto v7 = vec | view::translate_single(translation_frames::REV_FRAME_2);                            // == [R,T,Y]

// function syntax
auto v8 = view::translate_single(vec, translation_frames::FWD_FRAME_0);                           // == [T,Y,V,R]

// combinability
auto v9 = vec | view::complement | view::translate_single(translation_frames::REV_FRAME_0);      // == [M,H,A,C]

// combinability with default parameter
auto v10 = vec | view::complement | view::translate_single;                                       // == [C,M,H,A]

// combinability with default parameter
auto v12 = vec | view::complement | view::translate_single();                                     // == [C,M,H,A]

trim

constexpr auto seqan3::view::trim

inline

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

Template Parameters

urng_t	The type of the range being processed. See below for requirements.
threshold_t	Either seqan3::value_type_t<urng_t> or seqan3::alphabet_phred_t<seqan3::value_type_t<urng_t>>.

Parameters

[in]	urange	The range being processed. [parameter is omitted in pipe notation]
[in]	threshold	The minimum quality.

Returns

A trimmed range. See below for the properties of the returned range.

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

Header

#include <seqan3/range/view/trim.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).

range concepts and reference_t	urng_t (underlying range type)	rrng_t (returned range type)
std::ranges::InputRange	required	preserved
std::ranges::ForwardRange		preserved
std::ranges::BidirectionalRange		preserved
std::ranges::RandomAccessRange		preserved
std::ranges::View		guaranteed
std::ranges::SizedRange		lost
std::ranges::CommonRange		lost
std::ranges::OutputRange		preserved
seqan3::ConstIterableRange		preserved
seqan3::reference_t	seqan3::QualityAlphabet	seqan3::reference_t<urng_t>

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

Example

Operating on a range of seqan3::phred42:

std::vector<phred42> vec{phred42{40}, phred42{40}, phred42{30}, phred42{20}, phred42{10}};

// trim by phred_value
auto v1 = vec | view::trim(20u);                        // == ['I','I','?','5']

// trim by quality character
auto v2 = vec | view::trim(phred42{40});             // == ['I','I']

// function syntax
auto v3 = view::trim(vec, 20u);                         // == ['I','I','?','5']

// combinability
std::string v4 = view::trim(vec, 20u) | view::to_char;  // == "II?5"

Or operating on a range of seqan3::dna5q:

std::vector<dna5q> vec{{'A'_dna5, phred42{40}}, {'G'_dna5, phred42{40}}, {'G'_dna5, phred42{30}},
                       {'A'_dna5, phred42{20}}, {'T'_dna5, phred42{10}}};
std::vector<dna5q> cmp{{'A'_dna5, phred42{40}}, {'G'_dna5, phred42{40}}, {'G'_dna5, phred42{30}},
                       {'A'_dna5, phred42{20}}};

// trim by phred_value
auto v1 = vec | view::trim(20u);
assert(std::vector<dna5q>(v1) == cmp);

// trim by quality character; in this case the nucleotide part of the character is irrelevant
auto v2 = vec | view::trim(dna5q{'C'_dna5, phred42{20}});
assert(std::vector<dna5q>(v2) == cmp);

// combinability
std::string v3 = view::trim(vec, 20u) | view::to_char;
EXPECT_EQ("AGGA", v3);