 |
Boost.Hana
1.7.1
Your standard library for metaprogramming
|
|
|
Boost.Hana
1.7.1
Your standard library for metaprogramming
|
|
The Sequence concept represents generic index-based sequences.
Compared to other abstract concepts, the Sequence concept is very specific. It represents generic index-based sequences. The reason why such a specific concept is provided is because there are a lot of models that behave exactly the same while being implemented in wildly different ways. It is useful to regroup all those data types under the same umbrella for the purpose of generic programming.
In fact, models of this concept are not only similar. They are actually isomorphic, in a sense that we define below, which is a fancy way of rigorously saying that they behave exactly the same to an external observer.
Iterable, Foldable, and make
The Sequence concept does not provide basic methods that could be used as a minimal complete definition; instead, it borrows methods from other concepts and add laws to them. For this reason, it is necessary to specialize the Sequence metafunction in Hana's namespace to tell Hana that a type is indeed a Sequence. Explicitly specializing the Sequence metafunction can be seen like a seal saying "this data type satisfies the additional laws of a `Sequence`", since those can't be checked by Hana automatically.
The laws for being a Sequence are simple, and their goal is to restrict the semantics that can be associated to the functions provided by other concepts. First, a Sequence must be a finite Iterable (thus a Foldable too). Secondly, for a Sequence tag S, make<S>(x1, ..., xn) must be an object of tag S and whose linearization is [x1, ..., xn]. This basically ensures that objects of tag S are equivalent to their linearization, and that they can be created from such a linearization (with make).
While it would be possible in theory to handle infinite sequences, doing so complicates the implementation of many algorithms. For simplicity, the current version of the library only handles finite sequences. However, note that this does not affect in any way the potential for having infinite Searchables and Iterables.
Comparable (definition provided automatically)Sequences are equal if and only if they contain the same number of elements and their elements at any given index are equal. Orderable (definition provided automatically)Sequences are ordered using the traditional lexicographical ordering. Functor (definition provided automatically)Sequences implement transform as the mapping of a function over each element of the sequence. This is somewhat equivalent to what std::transform does to ranges of iterators. Also note that mapping a function over an empty sequence returns an empty sequence and never applies the function, as would be expected. Applicative (definition provided automatically)lifting a value into a Sequence is the same as creating a singleton sequence containing that value. Second, applying a sequence of functions to a sequence of values will apply each function to all the values in the sequence, and then return a list of all the results. In other words, Monad (definition provided automatically)flatenning a Sequence takes a sequence of sequences and concatenates them to get a larger sequence. In other words, std::tuple_cat function, except it receives a sequence of sequences instead of a variadic pack of sequences to flatten.Monad for Sequences can be seen as modeling nondeterminism. A nondeterministic computation can be modeled as a function which returns a sequence of possible results. In this line of thought, chaining a sequence of values into such a function will return a sequence of all the possible output values, i.e. a sequence of all the values applied to all the functions in the sequences.MonadPlus (definition provided automatically)Sequences are models of the MonadPlus concept by considering the empty sequence as the unit of concat, and sequence concatenation as concat. FoldableFoldable for Sequences is uniquely determined by the model of Iterable. IterableIterable for Sequences corresponds to iteration over each element of the sequence, in order. This model is not provided automatically, and it is in fact part of the minimal complete definition for the Sequence concept. Searchable (definition provided automatically)Sequence is equivalent to just searching through a list of the values it contains. The keys and the values on which the search is performed are both the elements of the sequence. Variables | |
| constexpr auto | boost::hana::drop_back |
Drop the last n elements of a finite sequence, and return the rest. More... | |
| constexpr insert_t | boost::hana::insert {} |
| Insert a value at a given index in a sequence. More... | |
| constexpr auto | boost::hana::insert_range |
| Insert several values at a given index in a sequence. More... | |
| constexpr auto | boost::hana::intersperse |
| Insert a value between each pair of elements in a finite sequence. More... | |
| constexpr auto | boost::hana::permutations |
| Return a sequence of all the permutations of the given sequence. More... | |
| constexpr auto | boost::hana::remove_at |
| Remove the element at a given index from a sequence. More... | |
| template<std::size_t n> | |
| constexpr auto | boost::hana::remove_at_c |
Equivalent to remove_at; provided for convenience. More... | |
| constexpr auto | boost::hana::remove_range |
| Remove the elements inside a given range of indices from a sequence. More... | |
| template<std::size_t from, std::size_t to> | |
| constexpr auto | boost::hana::remove_range_c |
Equivalent to remove_range; provided for convenience. More... | |
| constexpr auto | boost::hana::reverse |
| Reverse a sequence. More... | |
| constexpr auto | boost::hana::scan_left |
| Fold a Sequence to the left and return a list containing the successive reduction states. More... | |
| constexpr auto | boost::hana::scan_right |
| Fold a Sequence to the right and return a list containing the successive reduction states. More... | |
| constexpr auto | boost::hana::slice |
Extract the elements of a Sequence at the given indices. More... | |
| template<std::size_t from, std::size_t to> | |
| constexpr auto | boost::hana::slice_c |
Shorthand to slice a contiguous range of elements. More... | |
| constexpr auto | boost::hana::take_back |
Returns the last n elements of a sequence, or the whole sequence if the sequence has less than n elements. More... | |
| template<std::size_t n> | |
| constexpr auto | boost::hana::take_back_c |
Equivalent to take_back; provided for convenience. More... | |
| constexpr auto | boost::hana::take_front |
Returns the first n elements of a sequence, or the whole sequence if the sequence has less than n elements. More... | |
| template<std::size_t n> | |
| constexpr auto | boost::hana::take_front_c |
Equivalent to take_front; provided for convenience. More... | |
| constexpr auto | boost::hana::take_while |
Take elements from a sequence while the predicate is satisfied. More... | |
| constexpr auto | boost::hana::zip |
| Zip one sequence or more. More... | |
| constexpr auto | boost::hana::zip_shortest |
| Zip one sequence or more. More... | |
| constexpr auto | boost::hana::zip_shortest_with |
| Zip one sequence or more with a given function. More... | |
| constexpr auto | boost::hana::zip_with |
| Zip one sequence or more with a given function. More... | |
|
constexpr |
#include <boost/hana/fwd/drop_back.hpp>
Drop the last n elements of a finite sequence, and return the rest.
Given a finite Sequence xs with a linearization of [x1, ..., xm] and a non-negative IntegralConstant n, drop_back(xs, n) is a sequence with the same tag as xs whose linearization is [x1, ..., xm-n]. If n is not given, it defaults to an IntegralConstant with a value equal to 1.
In case length(xs) <= n, drop_back will simply drop the whole sequence without failing, thus returning an empty sequence.
| xs | The sequence from which elements are dropped. |
| n | A non-negative IntegralConstant representing the number of elements to be dropped from the end of the sequence. If n is not given, it defaults to an IntegralConstant with a value equal to 1. |
|
related |
#include <boost/hana/fwd/insert.hpp>
Insert a value at a given index in a sequence.
Given a sequence, an index and an element to insert, insert inserts the element at the given index.
| xs | The sequence in which a value should be inserted. |
| n | The index at which an element should be inserted. This must be a non-negative Constant of an integral type, and it must also be true that n < length(xs) if xs is a finite sequence. |
| element | The element to insert in the sequence. |
|
constexpr |
#include <boost/hana/fwd/insert_range.hpp>
Insert several values at a given index in a sequence.
Given a sequence, an index and any Foldable containing elements to insert, insert_range inserts the elements in the Foldable at the given index of the sequence.
| xs | The sequence in which values should be inserted. |
| n | The index at which elements should be inserted. This must be a non-negative Constant of an integral type, and it must also be true that n < length(xs) if xs is a finite sequence. |
| elements | A Foldable containing elements to insert in the sequence. |
|
constexpr |
#include <boost/hana/fwd/intersperse.hpp>
Insert a value between each pair of elements in a finite sequence.
Given a finite Sequence xs with a linearization of [x1, x2, ..., xn], intersperse(xs, z) is a new sequence with a linearization of [x1, z, x2, z, x3, ..., xn-1, z, xn]. In other words, it inserts the z element between every pair of elements of the original sequence. If the sequence is empty or has a single element, intersperse returns the sequence as-is. In all cases, the sequence must be finite.
| xs | The sequence in which a value is interspersed. |
| z | The value to be inserted between every pair of elements of the sequence. |
|
constexpr |
#include <boost/hana/fwd/permutations.hpp>
Return a sequence of all the permutations of the given sequence.
Specifically, permutations(xs) is a sequence whose elements are permutations of the original sequence xs. The permutations are not guaranteed to be in any specific order. Also note that the number of permutations grows very rapidly as the length of the original sequence increases. The growth rate is O(length(xs)!); with a sequence xs of length only 8, permutations(xs) contains over 40 000 elements!
|
constexpr |
#include <boost/hana/fwd/remove_at.hpp>
Remove the element at a given index from a sequence.
remove_at returns a new sequence identical to the original, except that the element at the given index is removed. Specifically, remove_at([x0, ..., xn-1, xn, xn+1, ..., xm], n) is a new sequence equivalent to [x0, ..., xn-1, xn+1, ..., xm].
| xs | A sequence from which an element is to be removed. |
| n | An non-negative IntegralConstant representing the index of the element to be removed from the sequence. The behavior is undefined if that index is not in the bounds of the sequence. |
|
constexpr |
#include <boost/hana/fwd/remove_at.hpp>
Equivalent to remove_at; provided for convenience.
|
constexpr |
#include <boost/hana/fwd/remove_range.hpp>
Remove the elements inside a given range of indices from a sequence.
remove_range returns a new sequence identical to the original, except that elements at indices in the provided range are removed. Specifically, remove_range([x0, ..., xn], from, to) is a new sequence equivalent to [x0, ..., x_from-1, x_to, ..., xn].
| xs | A sequence from which elements are removed. |
| [from,to) | An half-open interval of IntegralConstants representing the indices of the elements to be removed from the sequence. The IntegralConstants in the half-open interval must be non-negative and in the bounds of the sequence. The half-open interval must also be valid, meaning that from <= to. |
|
constexpr |
#include <boost/hana/fwd/remove_range.hpp>
Equivalent to remove_range; provided for convenience.
|
constexpr |
#include <boost/hana/fwd/reverse.hpp>
Reverse a sequence.
Specifically, reverse(xs) is a new sequence containing the same elements as xs, except in reverse order.
| xs | The sequence to reverse. |
|
constexpr |
#include <boost/hana/fwd/scan_left.hpp>
Fold a Sequence to the left and return a list containing the successive reduction states.
Like fold_left, scan_left reduces a sequence to a single value using a binary operation. However, unlike fold_left, it builds up a sequence of the intermediary results computed along the way and returns that instead of only the final reduction state. Like fold_left, scan_left can be used with or without an initial reduction state.
When the sequence is empty, two things may arise. If an initial state was provided, a singleton list containing that state is returned. Otherwise, if no initial state was provided, an empty list is returned. In particular, unlike for fold_left, using scan_left on an empty sequence without an initial state is not an error.
More specifically, scan_left([x1, ..., xn], state, f) is a sequence whose ith element is equivalent to fold_left([x1, ..., xi], state, f). The no-state variant is handled in an analogous way. For illustration, consider this left fold on a short sequence:
The analogous sequence generated with scan_left will be
Similarly, consider this left fold (without an initial state) on a short sequence:
The analogous sequence generated with scan_left will be
| xs | The sequence to scan from the left. |
| state | The (optional) initial reduction state. |
| f | A binary function called as f(state, x), where state is the result accumulated so far and x is an element in the sequence. If no initial state is provided, f is called as f(x1, x2), where x1 and x2 are both elements of the sequence. |
|
constexpr |
#include <boost/hana/fwd/scan_right.hpp>
Fold a Sequence to the right and return a list containing the successive reduction states.
Like fold_right, scan_right reduces a sequence to a single value using a binary operation. However, unlike fold_right, it builds up a sequence of the intermediary results computed along the way and returns that instead of only the final reduction state. Like fold_right, scan_right can be used with or without an initial reduction state.
When the sequence is empty, two things may arise. If an initial state was provided, a singleton list containing that state is returned. Otherwise, if no initial state was provided, an empty list is returned. In particular, unlike for fold_right, using scan_right on an empty sequence without an initial state is not an error.
More specifically, scan_right([x1, ..., xn], state, f) is a sequence whose ith element is equivalent to fold_right([x1, ..., xi], state, f). The no-state variant is handled in an analogous way. For illustration, consider this right fold on a short sequence:
The analogous sequence generated with scan_right will be
Similarly, consider this right fold (without an initial state) on a short sequence:
The analogous sequence generated with scan_right will be
| xs | The sequence to scan from the right. |
| state | The (optional) initial reduction state. |
| f | A binary function called as f(x, state), where state is the result accumulated so far and x is an element in the sequence. When no initial state is provided, f is called as f(x1, x2), where x1 and x2 are elements of the sequence. |
|
constexpr |
#include <boost/hana/fwd/slice.hpp>
Extract the elements of a Sequence at the given indices.
Given an arbitrary sequence of indices, slice returns a new sequence of the elements of the original sequence that appear at those indices. In other words,
The indices do not have to be ordered or contiguous in any particular way, but they must not be out of the bounds of the sequence. It is also possible to specify the same index multiple times, in which case the element at this index will be repeatedly included in the resulting sequence.
| xs | The sequence from which a subsequence is extracted. |
| indices | A compile-time Foldable containing non-negative IntegralConstants representing the indices. The indices are 0-based, and they must all be in bounds of the xs sequence. Note that any Foldable will really do (no need for an Iterable, for example); the linearization of the indices is used to determine the order of the elements included in the slice. |
|
constexpr |
#include <boost/hana/fwd/slice.hpp>
Shorthand to slice a contiguous range of elements.
slice_c is simply a shorthand to slice a contiguous range of elements. In particular, slice_c<from, to>(xs) is equivalent to slice(xs, range_c<std::size_t, from, to>), which simply slices all the elements of xs contained in the half-open interval delimited by [from, to). Like for slice, the indices used with slice_c are 0-based and they must be in the bounds of the sequence being sliced.
| from | The index of the first element in the slice. |
| to | One-past the index of the last element in the slice. It must hold that from <= to. |
|
constexpr |
#include <boost/hana/fwd/take_back.hpp>
Returns the last n elements of a sequence, or the whole sequence if the sequence has less than n elements.
Given a Sequence xs and an IntegralConstant n, take_back(xs, n) is a new sequence containing the last n elements of xs, in the same order. If length(xs) <= n, the whole sequence is returned and no error is triggered.
| xs | The sequence to take the elements from. |
| n | A non-negative IntegralConstant representing the number of elements to keep in the resulting sequence. |
|
constexpr |
#include <boost/hana/fwd/take_back.hpp>
Equivalent to take_back; provided for convenience.
|
constexpr |
#include <boost/hana/fwd/take_front.hpp>
Returns the first n elements of a sequence, or the whole sequence if the sequence has less than n elements.
Given a Sequence xs and an IntegralConstant n, take_front(xs, n) is a new sequence containing the first n elements of xs, in the same order. If length(xs) <= n, the whole sequence is returned and no error is triggered.
| xs | The sequence to take the elements from. |
| n | A non-negative IntegralConstant representing the number of elements to keep in the resulting sequence. |
|
constexpr |
#include <boost/hana/fwd/take_front.hpp>
Equivalent to take_front; provided for convenience.
|
constexpr |
#include <boost/hana/fwd/take_while.hpp>
Take elements from a sequence while the predicate is satisfied.
Specifically, take_while returns a new sequence containing the longest prefix of xs in which all the elements satisfy the given predicate.
| xs | The sequence to take elements from. |
| predicate | A function called as predicate(x), where x is an element of the sequence, and returning a Logical representing whether x should be included in the resulting sequence. In the current version of the library, predicate has to return a Constant Logical. |
|
constexpr |
#include <boost/hana/fwd/zip.hpp>
Zip one sequence or more.
Given n sequences s1, ..., sn, zip produces a sequence whose i-th element is a tuple of (s1[i], ..., sn[i]), where sk[i] denotes the i-th element of the k-th sequence. In other words, zip produces a sequence of the form
where M is the length of the sequences, which are all assumed to have the same length. Assuming the sequences to all have the same size allows the library to perform some optimizations. To zip sequences that may have different lengths, zip_shortest should be used instead. Also note that it is an error to provide no sequence at all, i.e. zip expects at least one sequence.
|
constexpr |
#include <boost/hana/fwd/zip_shortest.hpp>
Zip one sequence or more.
Given n sequences s1, ..., sn, zip_shortest produces a sequence whose i-th element is a tuple of (s1[i], ..., sn[i]), where sk[i] denotes the i-th element of the k-th sequence. In other words, zip_shortest produces a sequence of the form
where M is the length of the shortest sequence. Hence, the returned sequence stops when the shortest input sequence is exhausted. If you know that all the sequences you are about to zip have the same length, you should use zip instead, since it can be more optimized. Also note that it is an error to provide no sequence at all, i.e. zip_shortest expects at least one sequence.
|
constexpr |
#include <boost/hana/fwd/zip_shortest_with.hpp>
Zip one sequence or more with a given function.
Given a n-ary function f and n sequences s1, ..., sn, zip_shortest_with produces a sequence whose i-th element is f(s1[i], ..., sn[i]), where sk[i] denotes the i-th element of the k-th sequence. In other words, zip_shortest_with produces a sequence of the form
where M is the length of the shortest sequence. Hence, the returned sequence stops when the shortest input sequence is exhausted. If you know that all the sequences you are about to zip have the same length, you should use zip_with instead, since it can be more optimized. Also note that it is an error to provide no sequence at all, i.e. zip_shortest_with expects at least one sequence.
|
constexpr |
#include <boost/hana/fwd/zip_with.hpp>
Zip one sequence or more with a given function.
Given a n-ary function f and n sequences s1, ..., sn, zip_with produces a sequence whose i-th element is f(s1[i], ..., sn[i]), where sk[i] denotes the i-th element of the k-th sequence. In other words, zip_with produces a sequence of the form
where M is the length of the sequences, which are all assumed to have the same length. Assuming the sequences to all have the same size allows the library to perform some optimizations. To zip sequences that may have different lengths, zip_shortest_with should be used instead. Also note that it is an error to provide no sequence at all, i.e. zip_with expects at least one sequence.