Ranges

The ranges module provides general purpose containers, decorators and views. More...

Collaboration diagram for Ranges:

Modules
	Container
	The container submodule contains special BioC++ containers and generic container concepts.
	Views
	Views are "lazy range combinators" that offer modified views onto other ranges.

Namespaces
namespace	bio::ranges
	The ranges module's namespace.

Classes
struct	std::hash< urng_t >
	Struct for hashing a range of characters. More...
struct	bio::ranges::range_innermost_value< t >
	Recursively determines the value_type on containers and/or iterators. More...

Concepts
concept	bio::ranges::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.
concept	bio::ranges::back_insertable_with
	Describes range types that can grow in amortised constant time by appending an element of type val_t.
concept	bio::ranges::back_insertable
	Describes range types that can grow in amortised constant time by appending an element.
concept	bio::ranges::back_emplaceable_with
	Describes range types that can grow in amortised constant time by appending an element which is constructed in place.

Typedefs
template<typename t >
using	bio::ranges::range_innermost_value_t = typename range_innermost_value< t >::type
	Shortcut for bio::ranges::range_innermost_value (transformation_trait shortcut).

Functions
template<typename container_t , typename... args_t>
constexpr auto	bio::ranges::to (args_t &&... args)
	Converts a range to a container.

Variables
template<typename t >
constexpr size_t	bio::ranges::range_dimension_v = 1
	Returns the number of times you can call std::ranges::value_type_t recursively on t (type trait).

Detailed Description

The ranges module provides general purpose containers, decorators and views.

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 BioC++ library, this module provides general-purpose ranges that are not specific to another module or biological function.

Iterator capabilities

All ranges in BioC++ 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. BioC++ makes use of standard STL containers like std::vector, but also implements some custom containers. See the container 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.

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. bio::ranges::detail::random_access_container.

Attention

There are ranges in BioC++ 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

range.hpp

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

Typedef Documentation

range_innermost_value_t

template<typename t >

using bio::ranges::range_innermost_value_t = typedef typename range_innermost_value<t>::type

Shortcut for bio::ranges::range_innermost_value (transformation_trait shortcut).

See also

bio::ranges::range_innermost_value

Function Documentation

to()

template<typename container_t , typename... args_t>

constexpr auto bio::ranges::to ( args_t &&...  args )

constexpr

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 different call syntax can be used. Either the "pipe syntax" or the "function call" syntax. Both syntaxes support the explicit specification of the target container or a specification with an deduced value type.

#include <deque>
#include <forward_list>
#include <list>
#include <vector>
 
#include <bio/ranges/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 | bio::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 | bio::ranges::to<std::vector>();
    static_assert(std::same_as<decltype(vec1), std::vector<int>>);
 
    // convert range to vector using function call syntax
    auto vec2 = bio::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 = bio::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 | bio::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 | bio::ranges::to<std::list>();
    static_assert(std::same_as<decltype(vec5), std::list<int>>);
 
    auto vec6 = lst | bio::ranges::to<std::deque>();
    static_assert(std::same_as<decltype(vec6), std::deque<int>>);
}

Variable Documentation

range_dimension_v

template<typename t >

constexpr size_t bio::ranges::range_dimension_v = 1

constexpr

Returns the number of times you can call std::ranges::value_type_t recursively on t (type trait).

Template Parameters

t	The type to be queried; must resolve std::ranges::value_type_t at least once.

Attention, this type trait implicitly removes cv-qualifiers and reference from the types it recurses on and returns.