Boost.Hana  1.7.1
Your standard library for metaprogramming
Foldable

Description

The Foldable concept represents data structures that can be reduced to a single value.

Generally speaking, folding refers to the concept of summarizing a complex structure as a single value, by successively applying a binary operation which reduces two elements of the structure to a single value. Folds come in many flavors; left folds, right folds, folds with and without an initial reduction state, and their monadic variants. This concept is able to express all of these fold variants.

Another way of seeing Foldable is as data structures supporting internal iteration with the ability to accumulate a result. By internal iteration, we mean that the loop control is in the hand of the structure, not the caller. Hence, it is the structure who decides when the iteration stops, which is normally when the whole structure has been consumed. Since C++ is an eager language, this requires Foldable structures to be finite, or otherwise one would need to loop indefinitely to consume the whole structure.

Note
While the fact that Foldable only works for finite structures may seem overly restrictive in comparison to the Haskell definition of Foldable, a finer grained separation of the concepts should mitigate the issue. For iterating over possibly infinite data structures, see the Iterable concept. For searching a possibly infinite data structure, see the Searchable concept.

Minimal complete definition

fold_left or unpack

However, please note that a minimal complete definition provided through unpack will be much more compile-time efficient than one provided through fold_left.

Concrete models

hana::map, hana::optional, hana::pair, hana::set, hana::range, hana::tuple

The linearization of a <tt>Foldable</tt>

Intuitively, for a Foldable structure xs, the linearization of xs is the sequence of all the elements in xs as if they had been put in a list:

linearization(xs) = [x1, x2, ..., xn]

Note that it is always possible to produce such a linearization for a finite Foldable by setting

linearization(xs) = fold_left(xs, [], flip(prepend))
constexpr auto prepend
Prepend an element to a monadic structure.
Definition: prepend.hpp:57
constexpr auto flip
Invoke a function with its two first arguments reversed.
Definition: flip.hpp:31

for an appropriate definition of [] and prepend. The notion of linearization is useful for expressing various properties of Foldable structures, and is used across the documentation. Also note that Iterables define an extended version of this allowing for infinite structures.

Compile-time Foldables

A compile-time Foldable is a Foldable whose total length is known at compile-time. In other words, it is a Foldable whose length method returns a Constant of an unsigned integral type. When folding a compile-time Foldable, the folding can be unrolled, because the final number of steps of the algorithm is known at compile-time.

Additionally, the unpack method is only available to compile-time Foldables. This is because the return type of unpack depends on the number of objects in the structure. Being able to resolve unpack's return type at compile-time hence requires the length of the structure to be known at compile-time too.

In the current version of the library, only compile-time Foldables are supported. While it would be possible in theory to support runtime Foldables too, doing so efficiently requires more research.

Provided conversion to <tt>Sequence</tt>s

Given a tag S which is a Sequence, an object whose tag is a model of the Foldable concept can be converted to an object of tag S. In other words, a Foldable can be converted to a Sequence S, by simply taking the linearization of the Foldable and creating the sequence with that. More specifically, given a Foldable xs with a linearization of [x1, ..., xn] and a Sequence tag S, to<S>(xs) is equivalent to make<S>(x1, ..., xn).

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
namespace hana = boost::hana;
int main() {
static_assert(hana::to<hana::tuple_tag>(hana::just(1)) == hana::make_tuple(1), "");
BOOST_HANA_CONSTANT_CHECK(hana::to<hana::tuple_tag>(hana::nothing) == hana::make_tuple());
hana::to<hana::tuple_tag>(hana::make_range(hana::int_c<3>, hana::int_c<6>))
==
hana::tuple_c<int, 3, 4, 5>
);
}
Defines macros to perform different kinds of assertions.
Defines boost::hana::to and related utilities.
Defines boost::hana::equal.
#define BOOST_HANA_CONSTANT_CHECK(...)
Equivalent to BOOST_HANA_CONSTANT_ASSERT, but not influenced by the BOOST_HANA_CONFIG_DISABLE_ASSERTI...
Definition: assert.hpp:239
Defines boost::hana::integral_constant.
Namespace containing everything in the library.
Definition: accessors.hpp:20
Defines boost::hana::optional.
Defines boost::hana::range.
Defines boost::hana::tuple.

Free model for builtin arrays

Builtin arrays whose size is known can be folded as-if they were homogeneous tuples. However, note that builtin arrays can't be made more than Foldable (e.g. Iterable) because they can't be empty and they also can't be returned from functions.

Primer on monadic folds

A monadic fold is a fold in which subsequent calls to the binary function are chained with the monadic chain operator of the corresponding Monad. This allows a structure to be folded in a custom monadic context. For example, performing a monadic fold with the hana::optional monad would require the binary function to return the result as a hana::optional, and the fold would abort and return nothing whenever one of the accumulation step would fail (i.e. return nothing). If, however, all the reduction steps succeed, then just the result would be returned. Different monads will of course result in different effects.

Variables

constexpr auto boost::hana::count
 Return the number of elements in the structure that compare equal to a given value. More...
 
constexpr auto boost::hana::count_if
 Return the number of elements in the structure for which the predicate is satisfied. More...
 
constexpr auto boost::hana::fold = fold_left
 Equivalent to fold_left; provided for convenience. More...
 
constexpr auto boost::hana::for_each
 Perform an action on each element of a foldable, discarding the result each time. More...
 
constexpr auto boost::hana::fuse
 Transform a function taking multiple arguments into a function that can be called with a compile-time Foldable. More...
 
constexpr auto boost::hana::length
 Return the number of elements in a foldable structure. More...
 
constexpr auto boost::hana::product = see documentation
 Compute the product of the numbers of a structure. More...
 
constexpr auto boost::hana::size = hana::length
 Equivalent to length; provided for consistency with the standard library. More...
 
constexpr auto boost::hana::sum = see documentation
 Compute the sum of the numbers of a structure. More...
 
constexpr auto boost::hana::unpack
 Invoke a function with the elements of a Foldable as arguments. More...
 

Variable Documentation

◆ count

constexpr auto boost::hana::count
constexpr

#include <boost/hana/fwd/count.hpp>

Initial value:
= [](auto&& xs, auto&& value) {
return tag-dispatched;
}
constexpr auto value
Return the compile-time value associated to a constant.
Definition: value.hpp:54

Return the number of elements in the structure that compare equal to a given value.

Given a Foldable structure xs and a value value, count returns an unsigned integral, or a Constant thereof, representing the number of elements of xs that compare equal to value. For this method to be well-defined, all the elements of the structure must be Comparable with the given value.

Parameters
xsThe structure whose elements are counted.
valueA value compared with each element in the structure. Elements that compare equal to this value are counted, others are not.

Example

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
namespace hana = boost::hana;
int main() {
constexpr auto ints = hana::tuple_c<int, 1, 2, 3, 2, 2, 4, 2>;
BOOST_HANA_CONSTANT_CHECK(hana::count(ints, hana::int_c<2>) == hana::size_c<4>);
static_assert(hana::count(ints, 2) == 4, "");
constexpr auto types = hana::tuple_t<int, char, long, short, char, double>;
BOOST_HANA_CONSTANT_CHECK(hana::count(types, hana::type_c<char>) == hana::size_c<2>);
}
Defines boost::hana::count.
constexpr auto count
Return the number of elements in the structure that compare equal to a given value.
Definition: count.hpp:41
Defines boost::hana::type and related utilities.

◆ count_if

constexpr auto boost::hana::count_if
constexpr

#include <boost/hana/fwd/count_if.hpp>

Initial value:
= [](auto&& xs, auto&& predicate) {
return tag-dispatched;
}

Return the number of elements in the structure for which the predicate is satisfied.

Specifically, returns an object of an unsigned integral type, or a Constant holding such an object, which represents the number of elements in the structure satisfying the given predicate.

Parameters
xsThe structure whose elements are counted.
predicateA function called as predicate(x), where x is an element of the structure, and returning a Logical representing whether x should be counted.

Example

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
#include <type_traits>
namespace hana = boost::hana;
using namespace hana::literals;
auto is_odd = [](auto x) {
return x % 2_c != 0_c;
};
int main() {
constexpr auto ints = hana::tuple_c<int, 1, 2, 3>;
BOOST_HANA_CONSTANT_CHECK(hana::count_if(ints, is_odd) == hana::size_c<2>);
constexpr auto types = hana::tuple_t<int, char, long, short, char, double>;
BOOST_HANA_CONSTANT_CHECK(hana::count_if(types, hana::trait<std::is_floating_point>) == hana::size_c<1>);
BOOST_HANA_CONSTANT_CHECK(hana::count_if(types, hana::equal.to(hana::type_c<char>)) == hana::size_c<2>);
BOOST_HANA_CONSTANT_CHECK(hana::count_if(types, hana::equal.to(hana::type_c<void>)) == hana::size_c<0>);
}
Defines boost::hana::count_if.
Adapts std::integral_constant for use with Hana.
constexpr auto equal
Returns a Logical representing whether x is equal to y.
Definition: equal.hpp:64
constexpr auto count_if
Return the number of elements in the structure for which the predicate is satisfied.
Definition: count_if.hpp:40
constexpr auto to
Converts an object from one data type to another.
Definition: to.hpp:97
Defines boost::hana::mod.
Defines boost::hana::not_equal.

◆ fold

constexpr auto boost::hana::fold = fold_left
constexpr

#include <boost/hana/fwd/fold.hpp>

Equivalent to fold_left; provided for convenience.

fold is equivalent to fold_left. However, it is not tag-dispatched on its own because it is just an alias to fold_left. Also note that fold can be called with or without an initial state, just like fold_left:

fold(xs, state, f) == fold_left(xs, state, f)
fold(xs, f) == fold_left(xs, f)
constexpr auto fold
Equivalent to fold_left; provided for convenience.
Definition: fold.hpp:35

Example

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
#include <sstream>
#include <string>
namespace hana = boost::hana;
auto to_string = [](auto x) {
std::ostringstream ss;
ss << x;
return ss.str();
};
int main() {
auto f = [=](std::string s, auto element) {
return "f(" + s + ", " + to_string(element) + ")";
};
// with an initial state
hana::fold(hana::make_tuple(2, '3', 4, 5.0), "1", f)
==
"f(f(f(f(1, 2), 3), 4), 5)"
);
// without initial state
hana::fold(hana::make_tuple("1", 2, '3', 4, 5.0), f)
==
"f(f(f(f(1, 2), 3), 4), 5)"
);
}
Defines boost::hana::fold.
#define BOOST_HANA_RUNTIME_CHECK(...)
Equivalent to BOOST_HANA_RUNTIME_ASSERT, but not influenced by the BOOST_HANA_CONFIG_DISABLE_ASSERTIO...
Definition: assert.hpp:209

◆ for_each

constexpr auto boost::hana::for_each
constexpr

#include <boost/hana/fwd/for_each.hpp>

Initial value:
= [](auto&& xs, auto&& f) -> void {
tag-dispatched;
}

Perform an action on each element of a foldable, discarding the result each time.

Iteration is done from left to right, i.e. in the same order as when using fold_left. If the structure is not finite, this method will not terminate.

Parameters
xsThe structure to iterate over.
fA function called as f(x) for each element x of the structure. The result of f(x), whatever it is, is ignored.

Example

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
#include <sstream>
namespace hana = boost::hana;
int main() {
std::stringstream ss;
hana::for_each(hana::make_tuple(0, '1', "234", 5.5), [&](auto x) {
ss << x << ' ';
});
BOOST_HANA_RUNTIME_CHECK(ss.str() == "0 1 234 5.5 ");
}
Defines boost::hana::for_each.
constexpr auto for_each
Perform an action on each element of a foldable, discarding the result each time.
Definition: for_each.hpp:39

◆ fuse

constexpr auto boost::hana::fuse
constexpr

#include <boost/hana/fwd/fuse.hpp>

Initial value:
= [](auto&& f) {
return [perfect-capture](auto&& xs) -> decltype(auto) {
return unpack(forwarded(xs), forwarded(f));
};
}
constexpr auto unpack
Invoke a function with the elements of a Foldable as arguments.
Definition: unpack.hpp:79
constexpr auto capture
Create a function capturing the given variables.
Definition: capture.hpp:45

Transform a function taking multiple arguments into a function that can be called with a compile-time Foldable.

This function is provided for convenience as a different way of calling unpack. Specifically, fuse(f) is a function such that

fuse(f)(foldable) == unpack(foldable, f)
== f(x...)
constexpr auto fuse
Transform a function taking multiple arguments into a function that can be called with a compile-time...
Definition: fuse.hpp:40

where x... are the elements in the foldable. This function is useful when one wants to create a function that accepts a foldable which is not known yet.

Note
This function is not tag-dispatched; customize unpack instead.

Example

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
namespace hana = boost::hana;
auto tie = [](auto& ...vars) {
return hana::fuse([&vars...](auto ...values) {
// Using an initializer list to sequence the assignments.
int dummy[] = {0, ((void)(vars = values), 0)...};
(void)dummy;
});
};
int main() {
int a = 0;
char b = '\0';
double c = 0;
tie(a, b, c)(hana::make_tuple(1, '2', 3.3));
BOOST_HANA_RUNTIME_CHECK(a == 1 && b == '2' && c == 3.3);
}
Defines boost::hana::fuse.

◆ length

constexpr auto boost::hana::length
constexpr

#include <boost/hana/fwd/length.hpp>

Initial value:
= [](auto const& xs) {
return tag-dispatched;
}

Return the number of elements in a foldable structure.

Given a Foldable xs, length(xs) must return an object of an unsigned integral type, or an IntegralConstant holding such an object, which represents the number of elements in the structure.

Note
Since only compile-time Foldables are supported in the library right now, length must always return an IntegralConstant.

Example

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
namespace hana = boost::hana;
int main() {
BOOST_HANA_CONSTANT_CHECK(hana::length(hana::make_tuple()) == hana::size_c<0>);
BOOST_HANA_CONSTANT_CHECK(hana::length(hana::make_tuple(1, '2', 3.0)) == hana::size_c<3>);
BOOST_HANA_CONSTANT_CHECK(hana::length(hana::nothing) == hana::size_c<0>);
BOOST_HANA_CONSTANT_CHECK(hana::length(hana::just('x')) == hana::size_c<1>);
}
constexpr auto length
Return the number of elements in a foldable structure.
Definition: length.hpp:34
Defines boost::hana::length.

◆ product

constexpr auto boost::hana::product = see documentation
constexpr

#include <boost/hana/fwd/product.hpp>

Compute the product of the numbers of a structure.

More generally, product will take any foldable structure containing objects forming a Ring and reduce them using the Ring's binary operation. The initial state for folding is the identity of the Ring's operation. It is sometimes necessary to specify the Ring to use; this is possible by using product<R>. If no Ring is specified, the structure will use the Ring formed by the elements it contains (if it knows it), or integral_constant_tag<int> otherwise. Hence,

product<R>(xs) = fold_left(xs, one<R or inferred Ring>(), mult)
product<> = product<integral_constant_tag<int>>
constexpr auto mult
Associative operation of a Ring.
Definition: mult.hpp:47

For numbers, this will just compute the product of the numbers in the xs structure.

Note
The elements of the structure are not actually required to be in the same Ring, but it must be possible to perform mult on any two adjacent elements of the structure, which requires each pair of adjacent element to at least have a common Ring embedding. The meaning of "adjacent" as used here is that two elements of the structure x and y are adjacent if and only if they are adjacent in the linearization of that structure, as documented by the Iterable concept.
See the documentation for sum to understand why the Ring must sometimes be specified explicitly.

Example

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
namespace hana = boost::hana;
int main() {
hana::product<>(hana::make_range(hana::int_c<1>, hana::int_c<6>)) == hana::int_c<1 * 2 * 3 * 4 * 5>
);
hana::product<>(hana::make_tuple(1, hana::int_c<3>, hana::long_c<-5>, 9)) == 1 * 3 * -5 * 9
);
hana::product<unsigned long>(hana::make_tuple(2ul, 3ul)) == 6ul
);
}
#define BOOST_HANA_CONSTEXPR_CHECK(...)
Equivalent to BOOST_HANA_CONSTEXPR_ASSERT, but not influenced by the BOOST_HANA_CONFIG_DISABLE_ASSERT...
Definition: assert.hpp:300
Defines boost::hana::product.

◆ size

constexpr auto boost::hana::size = hana::length
constexpr

#include <boost/hana/fwd/size.hpp>

Equivalent to length; provided for consistency with the standard library.

This method is an alias to length provided for convenience and consistency with the standard library. As an alias, size is not tag-dispatched on its own and length should be customized instead.

Example

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
namespace hana = boost::hana;
int main() {
BOOST_HANA_CONSTANT_CHECK(hana::size(hana::make_tuple()) == hana::size_c<0>);
BOOST_HANA_CONSTANT_CHECK(hana::size(hana::make_tuple(1, '2', 3.0)) == hana::size_c<3>);
BOOST_HANA_CONSTANT_CHECK(hana::size(hana::nothing) == hana::size_c<0>);
BOOST_HANA_CONSTANT_CHECK(hana::size(hana::just('x')) == hana::size_c<1>);
}
constexpr auto size
Equivalent to length; provided for consistency with the standard library.
Definition: size.hpp:30
Defines boost::hana::size.

◆ sum

constexpr auto boost::hana::sum = see documentation
constexpr

#include <boost/hana/fwd/sum.hpp>

Compute the sum of the numbers of a structure.

More generally, sum will take any foldable structure containing objects forming a Monoid and reduce them using the Monoid's binary operation. The initial state for folding is the identity of the Monoid. It is sometimes necessary to specify the Monoid to use; this is possible by using sum<M>. If no Monoid is specified, the structure will use the Monoid formed by the elements it contains (if it knows it), or integral_constant_tag<int> otherwise. Hence,

sum<M>(xs) = fold_left(xs, zero<M or inferred Monoid>(), plus)
sum<> = sum<integral_constant_tag<int>>
constexpr auto plus
Associative binary operation on a Monoid.
Definition: plus.hpp:47

For numbers, this will just compute the sum of the numbers in the xs structure.

Note
The elements of the structure are not actually required to be in the same Monoid, but it must be possible to perform plus on any two adjacent elements of the structure, which requires each pair of adjacent element to at least have a common Monoid embedding. The meaning of "adjacent" as used here is that two elements of the structure x and y are adjacent if and only if they are adjacent in the linearization of that structure, as documented by the Iterable concept.

Why must we sometimes specify the <tt>Monoid</tt> by using <tt>sum<M></tt>?

This is because sequence tags like tuple_tag are not parameterized (by design). Hence, we do not know what kind of objects are in the sequence, so we can't know a 0 value of which type should be returned when the sequence is empty. Therefore, the type of the 0 to return in the empty case must be specified explicitly. Other foldable structures like hana::ranges will ignore the suggested Monoid because they know the tag of the objects they contain. This inconsistent behavior is a limitation of the current design with non-parameterized tags, but we have no good solution for now.

Example

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
namespace hana = boost::hana;
BOOST_HANA_CONSTANT_CHECK(hana::sum<>(hana::make_range(hana::int_c<1>, hana::int_c<6>)) == hana::int_c<15>);
static_assert(hana::sum<>(hana::make_tuple(1, hana::int_c<3>, hana::long_c<-5>, 9)) == 8, "");
static_assert(hana::sum<unsigned long>(hana::make_tuple(1ul, 3ul)) == 4ul, "");
int main() { }
Defines boost::hana::sum.

◆ unpack

constexpr auto boost::hana::unpack
constexpr

#include <boost/hana/fwd/unpack.hpp>

Initial value:
= [](auto&& xs, auto&& f) -> decltype(auto) {
return tag-dispatched;
}

Invoke a function with the elements of a Foldable as arguments.

Given a function and a foldable structure whose length can be known at compile-time, unpack invokes the function with the contents of that structure. In other words, unpack(xs, f) is equivalent to f(x...), where x... are the elements of the structure. The length of the structure must be known at compile-time, because the version of f's operator() that will be compiled depends on the number of arguments it is called with, which has to be known at compile-time.

To create a function that accepts a foldable instead of variadic arguments, see fuse instead.

Parameters
xsThe structure to expand into the function.
fA function to be invoked as f(x...), where x... are the elements of the structure as-if they had been linearized with to<tuple_tag>.

Example

// Copyright Louis Dionne 2013-2017
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
namespace hana = boost::hana;
int main() {
BOOST_HANA_CONSTEXPR_LAMBDA auto add = [](auto x, auto y, auto z) {
return x + y + z;
};
BOOST_HANA_CONSTEXPR_CHECK(hana::unpack(hana::make_tuple(1, 2, 3), add) == 6);
}
Defines configuration macros used throughout the library.
Defines boost::hana::unpack.

Rationale: <tt>unpack</tt>'s name and parameter order

It has been suggested a couple of times that unpack be called apply instead, and that the parameter order be reversed to match that of the proposed std::apply function. However, the name apply is already used to denote normal function application, an use which is consistent with the Boost MPL library and with the rest of the world, especially the functional programming community. Furthermore, the author of this library considers the proposed std::apply to have both an unfortunate name and an unfortunate parameter order. Indeed, taking the function as the first argument means that using std::apply with a lambda function looks like

std::apply([](auto ...args) {
use(args...);
}, tuple);
constexpr auto apply
Invokes a Callable with the given arguments.
Definition: apply.hpp:40

which is undeniably ugly because of the trailing , tuple) part on the last line. On the other hand, taking the function as a second argument allows one to write

hana::unpack(tuple, [](auto ...args) {
use(args...);
});

which looks much nicer. Because of these observations, the author of this library feels justified to use unpack instead of apply, and to use a sane parameter order.