Algorithm Traits

Detailed Description

Reading, rewriting and carrying a set of algorithm traits.

Writing an algorithm the way EVE writes its own means reading what the caller asked for. The tools below answer that: the readers report a decision, the rewriters turn a caller's set into the canonical one an algorithm loops on, and function_with_traits builds the callable that accepts a set at all. Calling an algorithm needs none of them, only the Options it accepts.

Convenience header:

#include <eve/module/algo.hpp> 

Unrolled iterations run on the same loop step, so a custom algorithm keeps them free of dependencies, for_each_iteration rather than for_each when that takes a hand-written loop.

See also

algo_rationale for the order these tools are used in.

Contents
	default_simple_algo_traits
	Predefined set the algorithms with a short body start from.
	no_traits
	Empty set, for an algorithm that starts from no default.

Classes
struct	eve::algo::traits< Settings >
	Compile time set of tuning parameters an algorithm accepts. More...

Typedefs
template<typename Traits>
using	eve::algo::extra_types_to_consider = rbr::result::fetch_t<(consider_types_key | kumi::tuple{}), Traits>
	Types eve::algo::consider_types added to the set, as a kumi::tuple.
template<typename Traits, typename RorI>
using	eve::algo::get_types_to_consider_for
	Every type the cardinal selection weighs, as a kumi::tuple.
template<typename Traits, typename RorI>
using	eve::algo::iteration_cardinal_t
	Cardinal an algorithm iterates with.
template<typename Traits, typename RorI>
using	eve::algo::get_index_type_t
	Integral type an algorithm counts indices in.

Functions
template<typename Traits>
constexpr std::ptrdiff_t	eve::algo::get_unrolling ()
	Number of SIMD registers handled per loop step.
template<typename Traits>
constexpr std::ptrdiff_t	eve::algo::get_overflow ()
	Number of lanes the loop may write past its range.
template<typename Traits>
constexpr std::optional< std::ptrdiff_t >	eve::algo::get_expected_smaller_r ()
	Which of two ranges eve::algo::expect_smaller_range named, if any.
template<typename K, typename Traits>
constexpr auto	eve::algo::drop_key (K k, Traits tr)
	Trait set without the key k.
template<bool cond, typename K, typename Traits>
constexpr auto	eve::algo::drop_key_if (K k, Traits tr)
	Trait set without the key k, when cond holds.
template<typename Traits>
constexpr auto	eve::algo::density_for_compress_copy ()
	Output density a compressing copy writes with.
template<typename Settings>
constexpr auto	eve::algo::process_equivalents (traits< Settings > tr)
	Trait set with every shorthand expanded.

Variables
constexpr auto	eve::algo::default_to
	Trait set where a caller's choices override an algorithm's defaults.
template<typename Traits>
constexpr bool	eve::algo::has_type_overrides_v = Traits::contains(force_type_key) || Traits::contains(common_with_types_key)
	Whether a zip trait set requests a type conversion.
template<template< typename > typename F>
constexpr auto	eve::algo::function_with_traits = F<eve_implementation_defined>{}
	Callable accepting a trait set, built from an algorithm's implementation.

Typedef Documentation

extra_types_to_consider

template<typename Traits>

using eve::algo::extra_types_to_consider = rbr::result::fetch_t<(consider_types_key | kumi::tuple{}), Traits>

Types eve::algo::consider_types added to the set, as a kumi::tuple.

Template Parameters

Traits

Trait set to read.

Empty tuple when the set carries no eve::algo::consider_types.

get_index_type_t

template<typename Traits, typename RorI>

using eve::algo::get_index_type_t

Initial value:

 
typename rbr::result::fetch_t<(index_type_key | eve_implementation_defined()),
                       Traits>::type

Integral type an algorithm counts indices in.

Template Parameters

Traits	Trait set to read.
RorI	Range or iterator the algorithm walks.

Trait set	Result
carries eve::algo::index_type	that type
otherwise	smallest unsigned type covering RorI

get_types_to_consider_for

template<typename Traits, typename RorI>

using eve::algo::get_types_to_consider_for

Initial value:

 
kumi::result::cat_t<extra_types_to_consider<Traits>, types_to_consider_for_t<RorI>>

Every type the cardinal selection weighs, as a kumi::tuple.

Template Parameters

Traits	Trait set to read.
RorI	Range or iterator the algorithm walks.

The types RorI carries, followed by those eve::algo::consider_types added.

iteration_cardinal_t

template<typename Traits, typename RorI>

using eve::algo::iteration_cardinal_t

Initial value:

 
rbr::result::fetch_t< (force_cardinal_key | eve_implementation_defined{})
                    , Traits
                    >

Cardinal an algorithm iterates with.

Template Parameters

Traits	Trait set to read.
RorI	Range or iterator the algorithm walks.

Trait set	Result
carries eve::algo::force_cardinal	that cardinal
carries allow_frequency_scaling	expected cardinal of the considered types
otherwise	cardinal that avoids frequency scaling

See also

get_types_to_consider_for

Function Documentation

density_for_compress_copy()

template<typename Traits>

auto eve::algo::density_for_compress_copy ( )

constexpr

Output density a compressing copy writes with.

Template Parameters

Traits

Trait set to read.

eve::sparse when the set carries eve::algo::sparse_output, eve::dense otherwise.

drop_key()

template<typename K, typename Traits>

auto eve::algo::drop_key ( K k, Traits tr )

inlineconstexpr

Trait set without the key k.

Template Parameters

K	Keyword to remove.
Traits	Trait set to strip.

Called once the decision k carried is taken, so the rest of the loop cannot read it again.

See also

drop_key_if

drop_key_if()

template<bool cond, typename K, typename Traits>

auto eve::algo::drop_key_if ( K k, Traits tr )

inlineconstexpr

Trait set without the key k, when cond holds.

Template Parameters

cond	Condition deciding the removal.
K	Keyword to remove.
Traits	Trait set to strip.

Keeps an if constexpr out of the call site.

get_expected_smaller_r()

template<typename Traits>

std::optional< std::ptrdiff_t > eve::algo::get_expected_smaller_r ( )

constexpr

Which of two ranges eve::algo::expect_smaller_range named, if any.

Template Parameters

Traits

Trait set to read.

Empty optional when the set names none.

get_overflow()

template<typename Traits>

std::ptrdiff_t eve::algo::get_overflow ( )

constexpr

Number of lanes the loop may write past its range.

Template Parameters

Traits

Trait set to read, which has to carry eve::algo::overflow.

get_unrolling()

template<typename Traits>

std::ptrdiff_t eve::algo::get_unrolling ( )

constexpr

Number of SIMD registers handled per loop step.

Template Parameters

Traits

Trait set to read.

Reports 1 when the set carries no eve::algo::unroll.

process_equivalents()

template<typename Settings>

auto eve::algo::process_equivalents ( traits< Settings > tr )

inlineconstexpr

Trait set with every shorthand expanded.

Template Parameters

Settings

Settings of the trait set to expand.

Written	Stands for
eve::algo::expensive_callable	no_aligning, unroll<1> and single_pass

An algorithm reads this first, so the rest of its loop sees one canonical set.

See also

algo_rationale

Variable Documentation

default_to

auto eve::algo::default_to

inlineconstexpr

Initial value:

                                 =
   []<typename User, typename Default>(traits<User> const& user, traits<Default> const& defaults)
{
  if constexpr ( User::contains(consider_types_key) &&
                 Default::contains(consider_types_key) )
  {
    auto consider_all_types = kumi::result::cat_t < rbr::result::fetch_t<consider_types_key, User   >
                                                  , rbr::result::fetch_t<consider_types_key, Default>
                                                  >{};
    auto settings = rbr::merge(rbr::merge(rbr::settings(consider_types_key = consider_all_types),
                                          user),
                               defaults);
    return traits<decltype(settings)>{settings};
  }
  else
  {
    using settings_t = decltype(rbr::merge(user, defaults));
    return traits<settings_t>{rbr::merge(user, defaults)};
  }
}

Trait set where a caller's choices override an algorithm's defaults.

Both sets keep their eve::algo::consider_types entries, which add up rather than replace one another. Every other key comes from the caller when present.

function_with_traits

template<template< typename > typename F>

auto eve::algo::function_with_traits = F<eve_implementation_defined>{}

constexpr

Callable accepting a trait set, built from an algorithm's implementation.

Template Parameters

F	Implementation template, taking the type that carries the traits.

template<typename TraitsSupport>
struct my_algo_ : TraitsSupport
{
  template<relaxed_range R> auto operator()(R&& r) const;
};
 
inline constexpr auto my_algo = function_with_traits<my_algo_>[default_simple_algo_traits];

Every algorithm under eve/module/algo/algo is declared this way.

See also

algo_rationale

has_type_overrides_v

template<typename Traits>

bool eve::algo::has_type_overrides_v = Traits::contains(force_type_key) || Traits::contains(common_with_types_key)

constexpr

Whether a zip trait set requests a type conversion.

Template Parameters

Traits

Trait set to read.

True when the set carries eve::algo::force_type or eve::algo::common_with_types.