= predecessor_recorder

Records the predecessor (parent) vertex of each vertex in a property map. This is
an efficient way to encode the search tree traversed during a graph search.

*Defined in:* `<boost/graph/visitors.hpp>` +
*Models:* xref:visitors/EventVisitor.adoc[EventVisitor] +
*Typical event:* `on_tree_edge` or `on_relax_edge` (edge events only; cannot be
used with vertex events)

To use it, wrap it in an algorithm adaptor and optionally combine it with other
event visitors; see the xref:visitors/overview.adoc[visitors overview].

== Synopsis

[source,cpp]
----
template <typename PredecessorMap, typename EventTag>
struct predecessor_recorder {
  typedef EventTag event_filter;
  predecessor_recorder(PredecessorMap pa);

  template <class Edge, class Graph>
  void operator()(Edge e, const Graph& g);
};

template <typename PredecessorMap, typename EventTag>
predecessor_recorder<PredecessorMap, EventTag>
record_predecessors(PredecessorMap pa, EventTag);
----

== Template Parameters

[cols="1,3",options="header"]
|===
| Parameter | Description

| `PredecessorMap`
| A WritablePropertyMap whose key and value types are both the graph's vertex
  descriptor.

| `EventTag`
| The event at which to record. Must be an edge event (e.g. `on_tree_edge`,
  `on_relax_edge`).
|===

== Associated Types

[cols="1,3",options="header"]
|===
| Type | Description

| `event_filter`
| The event tag the visitor responds to. Same type as `EventTag`.
|===

== Member Functions

[cols="1,3",options="header"]
|===
| Member | Description

| `predecessor_recorder(PredecessorMap pa)`
| Constructs a recorder writing predecessors into the property map `pa`.

| `void operator()(Edge e, const Graph& g)`
| Given edge `e = (u, v)`, records `u` as the predecessor of `v`: `put(pa, v, u)`.
|===

== Non-Member Functions

[cols="1,3",options="header"]
|===
| Function | Description

| `record_predecessors(PredecessorMap pa, EventTag)`
| Convenience factory that creates a `predecessor_recorder`.
|===

TIP: Algorithms such as Dijkstra and BFS do not assign a predecessor to the source
vertex (the root of the search tree). Initialize the source's predecessor to itself
to mark it as the only vertex that is its own parent. For DFS (which builds a
forest), initialize every vertex to itself so all roots can be distinguished.

== Example

[source,cpp]
----
include::example$visitors/predecessor_recorder.cpp[]
----

[,text]
----
include::example$visitors/predecessor_recorder.txt[]
----
