Range

The range module provides general purpose range concepts. More...

Collaboration diagram for Range:

Classes
interface	const_iterable_range
	Specifies requirements of an input range type for which the const version of that type satisfies the same strength input range concept as the non-const version. More...
interface	pseudo_random_access_iterator
	This concept checks if an iterator type models pseudo random access. More...
interface	pseudo_random_access_range
	This concept checks if a type models a pseudo random access range. More...

Functions
template<typename T , typename... Args>
constexpr auto	seqan3::ranges::to (Args &&... args)
	Converts a range to a container. More...
template<typename T , std::ranges::range urng_t, typename... Args>
constexpr auto	seqan3::ranges::to (urng_t &&urng, Args &&... args)
	Converts a range to a container. More...

Detailed Description

The range module provides general purpose range concepts.

Introduction

Ranges are an abstraction of "a collection of items", or "something iterable". The most basic definition requires only the existence of begin() and end() on the range.

There are different ways to classify ranges, one way is through the capabilities of its default iterators. This is resembled by the range concepts defined in this module. Another way to classify ranges is by their storage behaviour, i.e. whether they own the data that is accessible through them. See below for more details.

Ranges are found throughout the SeqAn library, this module provides general-purpose ranges that are not specific to another module or biological function.

Iterator capabilities

All ranges in SeqAn are either input ranges (they can be read from) or output ranges (they can be written to) or both. E.g. an std::vector<int> is both, but a std::vector<int> const would only be an input range.

Input ranges have different strengths that are realised through more refined concepts:

std::ranges::input_range < std::ranges::forward_range < std::ranges::bidirectional_range < std::ranges::random_access_range < std::ranges::contiguous_range

(Click on the respective concepts to learn the exact definitions)

Independent of input or output, a range can also be sized and/or common .

Storage behaviour

Containers are the ranges most well known, they own their elements. SeqAn makes use of standard STL containers like std::vector, but also implements some custom containers. See the container submodule for more details.

Decorators are ranges that are always defined on another range and decorate/annotate the underlying range with additional information. They do not own the underlying range, but can contain member data of their own. See the decorator submodule for more details.

Views are ranges that are usually defined on another range and transform the underlying range via some algorithm or operation, however, some views are stand-alone, i.e. they are just an algorithm that produces elements. Views do not own any data beyond their algorithm and possible parameters to it and they can always be copied in constant time. The algorithm is required to be lazy-evaluated so it is feasible to combine multiple views. See the views submodule for more details.

If you are confused about decorators vs views, think of decorators as "underlying range + data" and views as "underlying range + algorithm".

The storage behaviour is orthogonal to the range concepts defined by the iterators mentioned above, i.e. you can have a container that satisfies std::ranges::random_access_range (e.g. std::vector does, but std::list does not) and you can have views or decorators that do so or don't. For some combinations of iterator capabilities and storage behaviour there are extra concept definitions, e.g. seqan3::random_access_container.

Attention

There are ranges in SeqAn that fit neither of these storage categories, e.g. all the files are input ranges (if they are input files) and output ranges (if they are output files), but they are neither containers, decorators nor views.

See also

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

Utility

Function Documentation

to() [1/2]

template<typename T , typename... Args>

constexpr auto seqan3::ranges::to ( Args &&...  args )

constexpr

Converts a range to a container.

Converts a range into a container allowing pipe syntax.

#include <deque>
#include <forward_list>
#include <list>
#include <vector>
 
#include <seqan3/utility/range/to.hpp>
 
int main()
{
    auto lst = std::views::iota(1, 10); // some range over the numbers 1-10
 
    // convert range to vector using pipe syntax
    auto vec0 = lst | seqan3::ranges::to<std::vector<int>>();
    static_assert(std::same_as<decltype(vec0), std::vector<int>>);
 
    // convert range to vector but auto deducing the element type
    auto vec1 = lst | seqan3::ranges::to<std::vector>();
    static_assert(std::same_as<decltype(vec1), std::vector<int>>);
 
    // convert range to vector using function call syntax
    auto vec2 = seqan3::ranges::to<std::vector<int>>(lst);
    static_assert(std::same_as<decltype(vec2), std::vector<int>>);
 
    // using function call syntax and auto deducing element type
    auto vec3 = seqan3::ranges::to<std::vector>(lst);
    static_assert(std::same_as<decltype(vec3), std::vector<int>>);
 
    // convert nested ranges into nested containers
    auto nested_lst = std::list<std::forward_list<int>>{{1, 2, 3}, {4, 5, 6, 7}};
    auto vec4 = nested_lst | seqan3::ranges::to<std::vector<std::vector<int>>>();
    static_assert(std::same_as<decltype(vec), std::vector<std::vector<int>>>);
 
    // different supported container types
    auto vec5 = lst | seqan3::ranges::to<std::list>();
    static_assert(std::same_as<decltype(vec5), std::list<int>>);
 
    auto vec5 = lst | seqan3::ranges::to<std::deque>();
    static_assert(std::same_as<decltype(vec5), std::deque<int>>);
 
 
 
}

This entity is stable.

{}

Converts a range into a container allowing pipe syntax and enabling auto deduction of container value type. Same as seqan3::ranges::to but for template templates.

This entity is stable.

{}

to() [2/2]

template<typename T , std::ranges::range urng_t, typename... Args>

constexpr auto seqan3::ranges::to ( urng_t &&  urng, Args &&...  args  )

constexpr

Converts a range to a container.

Converts a range into a container using function syntax.

This entity is stable.

{}

Converts a range into a container using function syntax and auto deducing container value type.

This entity is stable.

{}