Utopia::GraphUtils Namespace Reference

Functions
template<typename Graph , typename Iter , typename Rule >
void	apply_async (Iter it_begin, Iter it_end, Graph &&g, Rule &&rule)
	Apply a rule asynchronously.
template<typename Iter , typename Graph , typename Rule >
void	apply_sync (Iter it_begin, Iter it_end, Graph &&g, Rule &&rule)
	Apply a rule synchronously.
template<IterateOver iterate_over, typename Graph >
decltype(auto)	iterator_pair (const Graph &g)
	Get an iterator pair over selected graph entities.
template<IterateOver iterate_over, typename Graph , typename EntityDesc >
decltype(auto)	iterator_pair (EntityDesc e, const Graph &g)
	Get an iterator pair over selected graph entities.

Function Documentation

apply_async()

template<typename Graph , typename Iter , typename Rule >

void Utopia::GraphUtils::apply_async	(	Iter	it_begin,
		Iter	it_end,
		Graph &&	g,
		Rule &&	rule
	)

Apply a rule asynchronously.

This helper function applies a rule to a range of entities that is given through an iterator pair one after the other.

Template Parameters

Iter	The iterator type
Graph	The graph type
Rule	The rule type

Parameters

it_begin	The begin of the graph entity iterator range.
it_end	The end of the graph entity iterator range.
g	The graph
rule	The rule function to be applied to each element within the iterator range.

{
    // Determine whether the lambda function returns a void
    // The lambda function can either be called with a vertex descriptor or 
    // and edge descriptor. Therefore, both cases need to be accounted for
    using Desc = typename std::iterator_traits<Iter>::value_type;
    using ReturnType = typename std::invoke_result_t<Rule, Desc, Graph>;
    constexpr bool lambda_returns_void = std::is_same_v<ReturnType, void>;
 
    // Apply the rule to each element 
    if constexpr (lambda_returns_void){
        std::for_each(it_begin, it_end, 
        [&rule, &g](auto g_entity){
            rule(g_entity, g);
        });
    }
    else {
        std::for_each(it_begin, it_end, [&rule, &g](auto g_entity){
            g[g_entity].state = rule(g_entity, g);
        });
    }
}

apply_sync()

template<typename Iter , typename Graph , typename Rule >

void Utopia::GraphUtils::apply_sync	(	Iter	it_begin,
		Iter	it_end,
		Graph &&	g,
		Rule &&	rule
	)

Apply a rule synchronously.

This helper function applies a rule to a range of entities that is given through an iterator pair. A state cache is created that stores the returned states of the rule function. After the rule was applied to each graph entity within the iterator range the cached states are moved to the actual states of the graph entities, thus, updating their states synchronously.

Template Parameters

Iter	The iterator type
Graph	The graph type
Rule	The rule type

Parameters

it_begin	The begin of the graph entity iterator range.
it_end	The end of the graph entity iterator range.
g	The graph
rule	The rule function to be applied to each element within the iterator range.

Warning

Be careful to not operate directly on the state of a graph entity within the rule function. Rather, first create a copy of the state and return the copied and changed state at the end of the function.

{
    // initialize the state cache
    std::vector<decltype(g[*it_begin].state)> state_cache;
    state_cache.reserve(std::distance(it_begin, it_end));
 
    // apply the rule
    for (auto entity : boost::make_iterator_range(it_begin, it_end)){
        state_cache.push_back(rule(entity, g));
    }
 
    // move the cache
    auto counter = 0u;
    for (auto entity : boost::make_iterator_range(it_begin, it_end)){
        g[entity].state = std::move(state_cache[counter]);
        
        ++counter;
    }
}

iterator_pair() [1/2]

template<IterateOver iterate_over, typename Graph >

decltype(auto) Utopia::GraphUtils::iterator_pair

(

const Graph &

g

)

Get an iterator pair over selected graph entities.

Template Parameters

iterate_over	Specify over which graph entities to iterate Valid options: IterateOver::vertices IterateOver::edges
Graph	The graph type

Parameters

g

The graph

Returns

decltype(auto) The iterator pair

                                            {
    using namespace boost;
 
    if constexpr (iterate_over == IterateOver::vertices){
        return vertices(g);
    }
    else if constexpr (iterate_over == IterateOver::edges){
        return edges(g);
    }
    else {
        static_assert((iterate_over == IterateOver::vertices)
                      or (iterate_over == IterateOver::edges),
                      "Only the iterator pairs of vertices and edges can be"
                      "returned: iterate_over is set wrong!");
    }
}

iterator_pair() [2/2]

template<IterateOver iterate_over, typename Graph , typename EntityDesc >

decltype(auto) Utopia::GraphUtils::iterator_pair	(	EntityDesc	e,
		const Graph &	g
	)

Get an iterator pair over selected graph entities.

This function returns the iterator pair wrt. another graph entity. For example iteration over neighbors (adjacent_vertices) needs a references vertex.

Template Parameters

iterate_over	Specify over which graph entities to iterate over Valid options: IterateOver::neighbors IterateOver::inv_neighbors IterateOver::in_edges IterateOver::out_egdes
Graph	The graph type
EntityDesc	The graph entity descriptor that is the reference point for the iteration.

Parameters

e	The graph entity that serves as reference
g	The graph

Returns

decltype(auto) The iterator pair

                                                          {
    using namespace boost;
 
    if constexpr (iterate_over == IterateOver::neighbors){
        return adjacent_vertices(e, g);
    }
    else if constexpr (iterate_over == IterateOver::inv_neighbors){
        return inv_adjacent_vertices(e, g);
    }
    else if constexpr (iterate_over == IterateOver::in_edges){
        return in_edges(e, g);
    }
    else if constexpr (iterate_over == IterateOver::out_edges){
        return out_edges(e, g);
    }
    else {
        static_assert((iterate_over == IterateOver::neighbors)
                      or (iterate_over == IterateOver::inv_neighbors)
                      or (iterate_over == IterateOver::in_edges)
                      or (iterate_over == IterateOver::out_edges),
                      "Only the iterator pairs of neighbors, inv_neighbors, "
                      "in_edge, and out_edge can be returned: "
                      "iterate_over is set wrong!");
    }
}