[/
 / Copyright (c) 2007 Andrew Sutton
 /
 / Distributed under the Boost Software License, Version 1.0. (See accompanying
 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 /]

[section Distance Recorder]

    template <class DistanceMap, class EventTag>
    class distance_recorder;

This is an [EventVisitor] that records the distance of a vertex (using a property
map) from some source vertex during a graph search. When applied to edge /e = (u,v)/,
the distance of /v/ is recorded to be one more than the distance of /u/. The distance
recorder is typically used with the `on_tree_edge` or `on_relax_edge` events, and cannot
be used with vertex events.

The [distance_recorder] class can be used with graph algorithms by wrapping it with
the algorithm specific adaptor, such as [bfs_visitor] and [dfs_visitor]. Also,
this event visitor can be combined with other event visitors using `std::pair` to form
an [EventVisitorList].

[h4 Model Of]
[EventVisitor]

[h4 Where Defined]
`boost/graph/visitors.hpp`

[h4 Template Parameters]
[table
    [[Parameter] [Description] [Default]]
    [
        [`DistanceMap`]
        [
            A [WritablePropertyMap] where the key type is of type `vertex_descriptor`
            and the value type is numeric (usually an integer or the same type as the
            edge weight).
        ]
    ]
    [
        [`EventTag`]
        [
            A tag used to specify when the recorder should be applied during the graph
            algorithm. `EventTag` must be an edge event.
        ]
    ]
]

[h4 Associated Types]
[table
    [[Type] [Description]]
    [
        [`distance_recorder::event_filter`]
        [
            This type will be the same as the template parameter `EventTag`.
        ]
    ]
]

[h4 Member Functions]
[table
    [[Function] [Description]]
    [
        [`distance_recorder(DistanceMap pa)`]
        [Construct a distance recorder object with a predecessor property map `pa`.]
    ]
    [
        [
``
template <class Edge, class Graph>
void operator()(Edge e, const Graph& g)
``
        ]
        [
            Given edge `e` as /(u,v)/, this records the distance of `v` as one
            plus the distance of `u`.
        ]
    ]
]

[h4 Non-Member Functions]
[table
    [[Function] [Description]]
    [
        [
``
template <class DistanceMap, class EventTag>
distance_recorder<DistanceMap, EventTag>
record_distances(DistanceMap pa, EventTag)
``
        ]
        [
            A convenience function for creating [distance_recorder] instances.
        ]
    ]
]

[endsect]
