C++20 Concepts for Graph Iterators

These concepts define the interface contracts for Aleph-w graph iterators.

Collaboration diagram for C++20 Concepts for Graph Iterators:

Concepts
concept	BasicGraphIterator
	Concept for basic graph iterators.
concept	ResettableGraphIterator
	Concept for resettable graph iterators.
concept	GraphNodeIterator
	Concept for graph node iterators.
concept	GraphArcIterator
	Concept for graph arc iterators.
concept	NodeArcIterator
	Concept for node adjacency iterators.

These concepts define the interface contracts for Aleph-w graph iterators.

They provide:

1. Compile-time verification: Catch interface mismatches at compile time instead of deep template instantiation errors.
2. Better error messages: Clear indication of which method is missing.
3. Self-documenting code: The concept IS the interface specification.
4. Generic algorithm development: Write algorithms that work with any conforming iterator.

Concept Hierarchy

BasicGraphIterator              <-- Core: has_curr(), next(), get_curr()
    |
    +-- ResettableGraphIterator <-- Adds: reset_first()
    |
    +-- GraphNodeIterator<Node> <-- get_curr() returns Node*
    |
    +-- GraphArcIterator<Arc>   <-- get_curr() returns Arc*
            |
            +-- NodeArcIterator<Node,Arc> <-- Adds: get_tgt_node()

Iterator Conformance Table

Iterator Type	BasicGraphIterator	GraphNodeIterator	GraphArcIterator	NodeArcIterator
GT::Node_Iterator	Yes	Yes	-	-
GT::Arc_Iterator	Yes	-	Yes	-
GT::Node_Arc_Iterator	Yes	-	Yes	Yes

This applies to all graph types: List_Graph, List_SGraph, Array_Graph, and their directed variants.

Usage Examples

Example 1: Constraining a template function

// This function accepts any iterator satisfying BasicGraphIterator
template <BasicGraphIterator It>
size_t count_elements(It it) {
  size_t n = 0;
  for (; it.has_curr(); it.next())
    ++n;
  return n;
}
 
// Works with node iterators:
auto node_count = count_elements(g.get_node_it());
 
// Works with arc iterators:
auto arc_count = count_elements(g.get_arc_it());
 
// Works with adjacency iterators:
auto adj_count = count_elements(g.get_arc_it(some_node));

Example 2: Type-safe node processing

template <class GT>
  requires GraphNodeIterator<typename GT::Node_Iterator, typename GT::Node>
void process_all_nodes(GT& g) {
  for (auto it = g.get_node_it(); it.has_curr(); it.next()) {
    typename GT::Node* node = it.get_curr();  // Guaranteed correct type
    // ... process node ...
  }
}

Example 3: Compile-time static assertion

// Verify at compile time that your iterator conforms:
static_assert(BasicGraphIterator<MyGraph::Node_Iterator>,
              "Node_Iterator must provide has_curr(), next(), get_curr()");