SeqAn3 3.2.0
The Modern C++ library for sequence analysis.
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 container_t , typename... args_t>
constexpr auto seqan3::ranges::to (args_t &&... args)
 Converts a range to a container. More...
 
template<typename container_t , std::ranges::input_range rng_t, typename... args_t>
constexpr auto seqan3::ranges::to (rng_t &&rng, args_t &&... args)
 Converts a range to a container.This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 

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
Utility

Function Documentation

◆ to()

template<typename container_t , typename... args_t>
constexpr auto seqan3::ranges::to ( args_t &&...  args)
constexpr

Converts a range to a container.

Converts a range to a container.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

To convert a range to a container, either the "pipe syntax" or the "function call" syntax can be used. Both syntaxes support the explicit specification of the target container or a specification with a deduced value type.

Currently supported containers are:

#include <deque>
#include <forward_list>
#include <list>
#include <vector>
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(vec4), 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 vec6 = lst | seqan3::ranges::to<std::deque>();
static_assert(std::same_as<decltype(vec6), std::deque<int>>);
}
Provides seqan3::ranges::to.

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