Views are "lazy range combinators" that offer modified views onto other ranges. More...
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... | |
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.
ranges::view
.seqan3::views
.Functional and pipe notations:
Re-transform into a distinct container:
Composability:
When talking about views, two different entities are often conflated:
auto vec_view
above)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".
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.
|
inline |
A view that provides only const &
to elements of the underlying range.
urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation] |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
const
-protected elements. Header File
#include <seqan3/range/views/as_const.hpp>
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.
|
inlineconstexpr |
A view adapter that returns a concurrent-queue-like view over the underlying range.
urng_t | The type of the range being processed. See below for requirements. |
[in,out] | urange | The range being processed. |
[in] | buffer_size | Size of the buffer. Choose the size (> 0) depending on the expected work per element. |
Header
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.
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).
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).
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.
The following operations are thread-safe:
.begin()
and .end()
on the view returned by this adaptor;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.
Running the snippet could yield the following output:
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:
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.
|
inline |
A view over an alphabet, given a range of characters.
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. |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
Header File
#include <seqan3/range/views/char_to.hpp>
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.
|
inline |
A view that converts a range of nucleotides to their complement.
urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation] |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
Header File
#include <seqan3/range/views/complement.hpp>
Calls seqan3::nucleotide_alphabet::complement() on every element of the input range.
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.
const auto seqan3::views::convert |
A view that converts each element in the input range (implicitly or via static_cast
).
urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation] |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
Header File
#include <seqan3/range/views/convert.hpp>
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.
Convert from int
to bool
:
Convert from seqan3::dna15 to seqan3::dna5:
|
inlineconstexpr |
A view adaptor that returns all elements after n from the underlying range (or an empty range if the underlying range is shorter).
urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation] |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
[in] | drop_size | The number of elements to drop from the beginning. |
drop_size
. Header File
#include <seqan3/range/views/drop.hpp>
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.
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.
Construction time of the returned view is in if the underlying range models at least std::ranges::random_access_range and std::ranges::sized_range; otherwise in
.
|
inlineconstexpr |
A view adaptor that converts a pseudo random access range to a std::random_access_range.
urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation] |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
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.
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.
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.
Construction of the returned view is in .
|
inline |
A view calling std::get on each element in a range.
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. |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
Header File
#include <seqan3/range/views/get.hpp>
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.
|
inlineconstexpr |
A view that interleaves a given range into another range at regular intervals.
urng_t | The type of the range being processed. |
inserted_rng_t | The type of the range being inserted. |
[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. |
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).
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.
|
inlineconstexpr |
A view factory that returns a view over the stream buffer of an input stream.
istreambuf_t | The type of the stream(buffer); must be std::basic_streambuf or model seqan3::input_stream. |
[in] | istreambuf | The stream buffer or an input stream of whome the buffer is retrieved. |
Header File
#include <seqan3/range/views/istreambuf.hpp>
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.
|
inlineconstexpr |
Computes hash values for each position of a range via a given shape.
urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation] |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
[in] | shape | The seqan3::shape that determines how to compute the hash value. |
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.
urange
and the shape size shape
it must hold that uint64_t
.
|
inline |
A view that turns lvalue-references into rvalue-references.
urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation] |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
Header File
#include <seqan3/range/views/move.hpp>
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.
This is a slightly more verbose version of calling std::ranges::move
on the range.
A more useful example can be found in the tutorial .
|
inlineconstexpr |
A view adaptor that generates all pairwise combinations of the elements of the underlying range.
urng_t | The type of the range being processed. See below for requirements. |
[in] | urange | The range being processed. |
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.
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.
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.
Concurrent access to this view, e.g. while iterating over it, is thread-safe and must not be protected externally.
|
inlineconstexpr |
A view adaptor that wraps rvalue references of non-views.
urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation] |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
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.
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.
|
inline |
A view over an alphabet, given a range of ranks.
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::writable_semialphabet. |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
Header File
#include <seqan3/range/views/rank_to.hpp>
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.
|
inlineconstexpr |
A view factory that repeats a given value infinitely.
value_t | The type of value to repeat wrapped in a std::views::single; must model std::copy_constructible. |
[in] | value | The value to repeat. |
Header File
#include <seqan3/range/views/repeat.hpp>
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.
|
inlineconstexpr |
A view factory that repeats a given value n
times.
value_t | The type of value to repeat; must be std::copy_constructible. |
[in] | value | The value to repeat. |
[in] | count | The number of times to repeat value . |
count
, where each element equals value
. Header File
#include <seqan3/range/views/repeat_n.hpp>
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.
|
inlineconstexpr |
A view adapter that decays most of the range properties and adds single pass behavior.
urng_t | The type of the range being processed. See below for requirements. |
[in] | urange | The range being processed. |
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.
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.
Concurrent access to this view, e.g. while iterating over it, is not thread-safe and must be protected externally.
|
inlineconstexpr |
A view adaptor that returns a half-open interval on the underlying range.
urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation] |
[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). |
end_pos - begin_pos
elements of the underlying range. std::invalid_argument | If end_pos < begin_pos . |
Header File
#include <seqan3/range/views/slice.hpp>
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.
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.
Construction of the returned view is in for some views, see seqan3::views::drop.
|
inlineconstexpr |
A view adaptor that returns the first size
elements from the underlying range (or less if the underlying range is shorter).
urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation] |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
[in] | size | The target size of the view. |
size
elements of the underlying range. Header File
#include <seqan3/range/views/take.hpp>
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.
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.
|
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.
urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation] |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
[in] | size | The target size of the view. |
size
elements of the underlying range. Header File
#include <seqan3/range/views/take_exactly.hpp>
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.
|
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
.
seqan3::unexpected_end_of_input | If the underlying range is smaller than size . |
urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation] |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
[in] | size | The target size of the view. |
size
elements of the underlying range. Header File
#include <seqan3/range/views/take_exactly.hpp>
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.
|
inlineconstexpr |
A view adaptor that returns a single line from the underlying range or the full range if there is no newline.
urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation] |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
\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:
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).
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.
Behaviour on std::ranges::forward_range:
On single pass std::ranges::input_range it can be used to tokenise the input stream line-wise:
|
inlineconstexpr |
A view adaptor that returns a single line from the underlying range (throws if there is no end-of-line).
seqan3::unexpected_end_of_input | If the underlying range contains no end-of-line marker. |
urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation] |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
\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:
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).
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.
Behaviour on std::ranges::forward_range:
On single pass std::ranges::input_range it can be used to tokenise the input stream line-wise:
|
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).
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 . |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
[in] | fun | The functor. |
Header File
#include <seqan3/range/views/take_until.hpp>
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.
|
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).
seqan3::unexpected_end_of_input | If the underlying range contains no element that satisfies the functor. |
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 . |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
[in] | fun | The functor. |
Header File
#include <seqan3/range/views/take_until.hpp>
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.
|
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).
seqan3::unexpected_end_of_input | If the underlying range contains no element that satisfies the functor. |
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 . |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
[in] | fun | The functor. |
Header File
#include <seqan3/range/views/take_until.hpp>
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.
|
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).
seqan3::unexpected_end_of_input | If the underlying range contains no element that satisfies the functor. |
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 . |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
[in] | fun | The functor. |
Header File
#include <seqan3/range/views/take_until.hpp>
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.
|
inline |
A view that calls seqan3::to_char() on each element in the input range.
urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation] |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
Header File
#include <seqan3/range/views/to_char.hpp>
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.
|
inline |
A view that calls seqan3::to_lower() on each element in the input range.
urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation] |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
Header File
#include <seqan3/range/views/to_lower.hpp>
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.
|
inline |
A view that calls seqan3::to_rank() on each element in the input range.
urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation] |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
Header File
#include <seqan3/range/views/to_rank.hpp>
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.
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.
|
inline |
A view that calls seqan3::to_upper() on each element in the input range.
urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation] |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
Header File
#include <seqan3/range/views/to_upper.hpp>
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.
|
inlineconstexpr |
A view that translates nucleotide into aminoacid alphabet with 1, 2, 3 or 6 frames.
urng_t | The type of the range being processed. |
[in] | urange | The range being processed. |
[in] | tf | A value of seqan3::tanslation_frames that indicates the desired frames. |
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).
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.Operating on a range of seqan3::dna5:
|
inlineconstexpr |
A view that translates nucleotide into aminoacid alphabet with 1, 2, 3 or 6 frames. Input and output range are always two-dimensional.
urng_t | The type of the range being processed. |
[in] | urange | The range being processed. Needs to be a range of ranges (two-dimensional). |
[in] | tf | A value of seqan3::tanslation_frames that indicates the desired frames. |
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:
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.Operating on a range of seqan3::dna5:
|
inlineconstexpr |
A view that translates nucleotide into aminoacid alphabet for one of the six frames.
urng_t | The type of the range being processed. |
[in] | urange | The range being processed. |
[in] | tf | A value of seqan3::translation_frames that indicates the desired frames. |
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).
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.Operating on a range of seqan3::dna5:
|
inlineconstexpr |
A view that does quality-threshold trimming on a range of seqan3::quality_alphabet.
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>>. |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
[in] | threshold | The minimum quality. |
Header File
#include <seqan3/range/views/trim.hpp>
This view can be used to do easy quality based trimming of sequences.
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.
Operating on a range of seqan3::phred42:
Or operating on a range of seqan3::dna5q:
|
inlineconstexpr |
A view adaptor that behaves like std::views::all, but type erases certain ranges.
urng_t | The type of the range being processed. See below for requirements. [template parameter is omitted in pipe notation] |
[in] | urange | The range being processed. [parameter is omitted in pipe notation] |
Header File
#include <seqan3/range/views/view_type_reduce.hpp>
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.
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.