From d11f5e8e0ebefdd4a294966bd60605db6d4bbeea Mon Sep 17 00:00:00 2001 From: Jeremy Siek Date: Tue, 19 Sep 2000 18:40:30 +0000 Subject: [PATCH] some new docs, and more documentation edits [SVN r7746] --- docs/UniformCostVisitor.html | 5 + docs/challenge.html | 7 + docs/distance_recorder.html | 10 +- docs/index.html | 53 +++----- docs/null_visitor.html | 50 +++++++ docs/predecessor_recorder.html | 10 +- docs/property_writer.html | 207 +++++++++++++++++++++++++++++ docs/quick_tour.html | 107 ++++++++------- docs/time_stamper.html | 42 ++++-- docs/ucs_visitor.html | 131 ++++++++++++++++++ docs/using_property_accessors.html | 27 ++-- 11 files changed, 537 insertions(+), 112 deletions(-) create mode 100644 docs/property_writer.html create mode 100644 docs/ucs_visitor.html diff --git a/docs/UniformCostVisitor.html b/docs/UniformCostVisitor.html index f59932f5..4cd18d46 100644 --- a/docs/UniformCostVisitor.html +++ b/docs/UniformCostVisitor.html @@ -167,6 +167,11 @@ search tree and all of the adjacent vertices have been discovered +

Models

+ +
diff --git a/docs/challenge.html b/docs/challenge.html index b91ecd15..1494a4b2 100644 --- a/docs/challenge.html +++ b/docs/challenge.html @@ -44,6 +44,10 @@ review. The pending items are:
  • disjoint_sets +
  • Port the graph library to Borland C++
    • + +
  • Port the graph library to Metrowerks C++
    • +
  • Construct a set of planar graph algorithms.

    • diff --git a/docs/distance_recorder.html b/docs/distance_recorder.html index 7c2ddcf3..39344193 100644 --- a/docs/distance_recorder.html +++ b/docs/distance_recorder.html @@ -32,7 +32,7 @@ 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 -connot be used with vertex events. +cannot be used with vertex events.

    distance_recorder can be used with graph algorithms by @@ -147,7 +147,7 @@ template <class DistancePA, class Tag>
    distance_recorder<DistancePA, Tag>
    record_distances(DistancePA pa, Tag); -A convenient wat to create a distance_recorder. +A convenient way to create a distance_recorder. @@ -178,3 +178,9 @@ HREF="mailto:lums@lsc.nd.edu">lums@lsc.nd.edu) + + + diff --git a/docs/index.html b/docs/index.html index ab58a91f..424e8a4c 100644 --- a/docs/index.html +++ b/docs/index.html @@ -42,7 +42,7 @@ interface.

    The BGL graph interface and graph components are generic in the same sense as the the Standard Template Library (STL) [2]. +HREF="bibliography.html#austern99:_gener_progr_stl">2]. In the following sections we review the role that generic programming plays in the STL and @@ -137,7 +137,7 @@ of their graph algorithms.

    In contrast, custom-made (or even legacy) graph structures can be used as-is with the generic graph algorithms of BGL using external -adaptation (see SectionHow to +adaptation (see Section How to Convert Existing Graphs to BGL). External adaptation wraps a new interface around a data-structure without copying and without placing the data inside adaptor objects. The BGL interface was carefully @@ -155,13 +155,11 @@ notion of a visitor which is just a function object with multiple methods. In graph algorithms there are often several key ``event points'' at which it is useful to insert user-defined operations. The visitor object has a different method that is invoked -at each event point. These methods include initialize(), -start(), discover(), explore(), and -finish(). In addition, several of the graph algorithms -naturally separate the edges of the graph into categories such as -forward and back edges. These categories can be used to obtain finer -grained control over when the process() method will be -invoked. +at each event point. The particular event points and corresponding +visitor methods depend on the particular algorithm. They often +include methods like start_vertex(), +discover_vertex(), examine_edge(), +tree_edge() and finish_vertex().

    @@ -208,8 +206,6 @@ algorithms. The core algorithm patterns are

  • Uniform Cost Search
    • -
  • Generalized Graph Initialization -

    • @@ -221,28 +217,19 @@ include

    diff --git a/docs/null_visitor.html b/docs/null_visitor.html index 831ccc0a..94634d9e 100644 --- a/docs/null_visitor.html +++ b/docs/null_visitor.html @@ -25,10 +25,60 @@ null_visitor +This is an EventVisitor that +does nothing. +

    Model of

    EventVisitor +

    Associated Types

    + + + + + + + + + + + + +
    TypeDescription
    null_visitor::event_filter +This type is void +
    + +

    Member Functions

    + +

    + + + + + + + + + + + + + + + + +
    MemberDescription
    +null_visitor(); + +Default constructor. +
    +template <class X, class Graph>
    +void operator()(X x, const Graph& g); +    		 +This does nothing. +
    +

    diff --git a/docs/predecessor_recorder.html b/docs/predecessor_recorder.html index 714d82ae..1902e791 100644 --- a/docs/predecessor_recorder.html +++ b/docs/predecessor_recorder.html @@ -31,7 +31,7 @@ accessor. This is particularly useful in graph search algorithms where recording the predecessors is an efficient way to encode the search tree that was traversed during the search. The predecessor recorder is typically used with the on_tree_edge or -on_relax_edge events, and connot be used with vertex events. +on_relax_edge events, and cannot be used with vertex events.

    predecessor_recorder can be used with graph algorithms by @@ -146,7 +146,7 @@ template <class PredecessorPA, class Tag>
    predecessor_recorder<PredecessorPA, Tag>
    record_predecessors(PredecessorPA pa, Tag); -A convenient wat to create a predecessor_recorder. +A convenient way to create a predecessor_recorder. @@ -177,3 +177,9 @@ HREF="mailto:lums@lsc.nd.edu">lums@lsc.nd.edu) + + + diff --git a/docs/property_writer.html b/docs/property_writer.html new file mode 100644 index 00000000..e77e3d1b --- /dev/null +++ b/docs/property_writer.html @@ -0,0 +1,207 @@ + + + +Boost Graph Library: property_writer + +C++ Boost + +
    + +

    +
    +property_writer<PropertyAccessor, OutputIterator, EventTag>
+
    +

    + +This is an EventVisitor that can be +used to output the property of a vertex or edge at some event-point +within an algorithm. + +

    +property_writer 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. + +

    Example

    + +The following is an excerpt from examples/dave.cpp. + +
    +  std::ostream_iterator cout_int(std::cout, " ");
+  std::ostream_iterator cout_char(std::cout, " ");
+
+  boost::breadth_first_search
+    (G, vertex(a, G), make_bfs_visitor(
+     std::make_pair(write_property(name, cout_char, on_discover_vertex()),
+     std::make_pair(write_property(distance.begin(), cout_int, 
+                                   on_discover_vertex()),
+     std::make_pair(print_edge(name, std::cout, on_examine_edge()),
+                    print_endl(std::cout, on_finish_vertex()
+                    ))))));
+
    + +

    Model of

    + +EventVisitor + + +

    Where Defined

    + +

    + +boost/graph/visitors.hpp + +

    Template Parameters

    + +

    + + + + + + + + + + + + + + + + + + + + + +
    ParameterDescriptionDefault
    PropertyAccessor +A ReadablePropertyAccessor, +where the key_type is the vertex descriptor type or edge +descriptor of the graph (depending on the kind of event tag), and +the value_type of the property is convertible +to the value_type of the OutputIterator. + 
    OutputIterator +The iterator type used to write out the property values, which must be +a model of OutputIterator. + 
    EventTag +The tag to specify when the property_writer should be +applied during the graph algorithm. + 
    + +

    Associated Types

    + + + + + + + + + + + + +
    TypeDescription
    property_writer::event_filter +This will be the same type as the template parameter EventTag. +
    + +

    Member Functions

    + +

    + + + + + + + + + + + + + + + + +
    MemberDescription
    +property_writer(PropertyAccessor pa, OutputIterator out); + +Construct a property writer object with the property accessor +pa and output iterator out. +
    +template <class X, class Graph> +void operator()(X x, const Graph& g); + +This writs the property value for x to the output iterator.
    +*out++ = get(pa, x); +
    + +

    Non-Member Functions

    + + + + + + + + +
    FunctionDescription
    +template <class PropertyAccessor, class OutputIterator, class Tag>
    +property_writer<PropertyAccessor, OutputIterator, Tag>
    +write_property(PropertyAccessor pa, OutputIterator out, Tag); +    		 +A convenient way to create a property_writer. +
    + +

    See Also

    + +Visitor concepts +

    +The following are other event visitors: distance_recorder, +predecessor_recorder, +and time_stamper. + + +
    +

    + + +
    Copyright © 2000 +Jeremy Siek, +Univ.of Notre Dame (jsiek@lsc.nd.edu)
    +Lie-Quan Lee, Univ.of Notre Dame (llee1@lsc.nd.edu)
    +Andrew Lumsdaine, +Univ.of Notre Dame (lums@lsc.nd.edu) +
    + + + + + + diff --git a/docs/quick_tour.html b/docs/quick_tour.html index 2cc038ee..9f61dcbb 100644 --- a/docs/quick_tour.html +++ b/docs/quick_tour.html @@ -516,9 +516,8 @@ href="http://www.sgi.com/Technology/STL/RandomAccessIterator.html">RandomAccessI 

    -  typedef plugin<weight_tag, int> weightp;
   typedef adjacency_list<listS, vecS, directedS, 
-                         no_plugin, weightp> Graph;
+                         no_plugin, plugin<weight_tag, int> > Graph;
   typedef graph_traits<Graph>::vertex_descriptor Vertex;
   typedef std::pair<int,int> E;
 
@@ -594,33 +593,46 @@ A visitor is like a functor, but instead of having just one
 "apply" method, it has several. Each of these methods get
 invoked at certain well-defined points within the algorithm. The
 visitor methods are explained in detail in Section Visitor Concepts. The BGL provides
-a number of visitors for some common tasks including a predecessor
-recording visitor. The user is encouraged to write his or her own
-visitors as a way of extending the BGL. Here we will take a quick look
-at the implementation and use of the predecessor recorder.
+href="./visitor_concepts.html">Visitor Concepts. 
+
+The BGL provides a number of visitors for some common tasks including
+a predecessor recording visitor. The user is encouraged to write his
+or her own visitors as a way of extending the BGL. Here we will take a
+quick look at the implementation and use of the predecessor recorder.
+Since we will be using the dijkstra_shortest_paths()
+algorithm, the visitor we create must be a (a UniformCostVisitor).
 
 
    
-The functionality of the predecessor recorder is separated into two
-parts. For the storage and access of the predecessor property, we will
-use a property accessor. The predecessor visitor will then only be
-responsible for what parent to record.  To implement this, we create a
-predecessor_recorder class and template it on the predecessor
-property accessor Predecessor. Since this visitor will only be
-filling in one of the visitor methods, we will inherit from
-null_visitor which will provide empty methods for the rest.
-The constructor of the predecessor_recorder will take the
-property accessor object and save it away in a data member.
+The functionality of the record_predecessors visitor is
+separated into two parts. For the storage and access of the
+predecessor property, we will use a property
+accessor. The predecessor visitor will then only be responsible
+for what parent to record.  To implement this, we create a
+record_predecessors class and template it on the predecessor
+property accessor PredecessorAccessor. Since this visitor
+will only be filling in one of the visitor methods, we will inherit
+from ucs_visitor which will
+provide empty methods for the rest.  The constructor of the
+predecessor_recorder will take the property accessor object
+and save it away in a data member.
 
 
    
 
       template <class PredecessorAccessor>
-  class predecessor_recorder : public null_visitor
+  class record_predecessors : public ucs_visitor<>
   {
   public:
-    predecessor_recorder(PredecessorAccessor p)
+    record_predecessors(PredecessorAccessor p)
       : m_predecessor(p) { }
-    //...
+
+    template <class Edge, class Graph>
+    void edge_relaxed(Edge e, Graph& g) {
+      // set the parent of the target(e) to source(e)
+      put(m_predecessor, target(e, g), source(e, g));
+    }
   protected:
     PredecessorAccessor m_predecessor;
   };
@@ -628,30 +640,15 @@ property accessor object and save it away in a data member.
 
 
    
 The job of recording the predecessors is quite simple. When Dijkstra's
-algorithm adds an edge to the shortest-paths tree we just record the
-source vertex as the parent of the target vertex. Here we use the
-put() function associated with the property accessor to record
-the predecessor. The edge_filter of the visitor tells the
-algorithm when to invoke the explore() method. In this case we
-only want to be notified about edges in the shortest-paths tree so we
-specify tree_edge_tag.
-
-
    
-
    -  template <class PredecessorAccessor>
-  class predecessor_recorder
-  {
-    //...
-    typedef tree_edge_tag edge_filter;
-
-    template <class Edge, class Graph>
-    void explore(Edge e, Graph& g) {
-      // set the parent of the target(e) to source(e)
-      put(m_predecessor, target(e, g), source(e, g));
-    }
-    //...
-  };
-
    
+algorithm relaxes an edge (potentially adding it to the shortest-paths
+tree) we record the source vertex as the predecessor of the target
+vertex. Later, if the edge is relaxed again the predecessor property
+will be overwritten by the new predecessor. Here we use the
+put() function associated with the property accessor to
+record the predecessor. The edge_filter of the visitor tells
+the algorithm when to invoke the explore() method. In this
+case we only want to be notified about edges in the shortest-paths
+tree so we specify tree_edge_tag.
 
 
    
 As a finishing touch, we create a helper function to make it more
@@ -661,14 +658,14 @@ helper function like this.
 
    
 
       template <class PredecessorAccessor>
-  predecessor_recorder<PredecessorAccessor>
-  record_predecessors(PredecessorAccessor p) {
-    return predecessor_recorder<PredecessorAccessor>(p);
+  record_predecessors<PredecessorAccessor>
+  make_predecessor_recorder(PredecessorAccessor p) {
+    return record_predecessors<PredecessorAccessor>(p);
   }
 
    
 
 
    
-We are now ready to use the predecessor_recorder in
+We are now ready to use the record_predecessors in
 Dijkstra's algorithm. Luckily, BGL's Dijkstra's algorithm is already
 equipped to handle visitors, so we just have to call the four argument
 version of the algorithm and pass in our new visitor. In this example
@@ -683,7 +680,7 @@ handle the use of multiple visitors in the same algorithm (see Section
   using std::endl;
   vector<Vertex> p(num_vertices(G)); //the predecessor array
   dijkstra_shortest_paths(G, s, d.begin(), 
-                          record_predecessors(p.begin()));
+                          make_predecessor_recorder(p.begin()));
 
   cout << "parents in the tree of shortest paths:" << endl;
   for(vi = vertices(G).first; vi != vertices(G).second; ++vi) {
@@ -715,3 +712,15 @@ The output is:
 
 
  
+
+
+
+
+
+
diff --git a/docs/time_stamper.html b/docs/time_stamper.html
index 95216748..95455734 100644
--- a/docs/time_stamper.html
+++ b/docs/time_stamper.html
@@ -27,8 +27,8 @@ time_stamper<TimePA, TimeT, EventTag>
 
 This is an EventVisitor that can be
 used to "stamp" a time at some event-point within an
-algorithm. An example of this is recording the discover or finish
-time of a vertex during a graph search.
+algorithm. An example of this is recording the discover or finish time
+of a vertex during a graph search.
 
 
    
 time_stamper can be used with graph algorithms by
@@ -79,17 +79,27 @@ href="../examples/bfs_basics.cpp">examples/bfs_basics.cpp.
 
 A WritablePropertyAccessor,
-where the key type and the value type are the vertex descriptor type
-of the graph.
+where the key_type is the vertex descriptor type or edge
+descriptor of the graph (depending on the kind of event tag), and
+where the TimeT type is convertible to the
+value_type of the time property accessor.
 
  
 
 
+TimeT
+
+The type for the time counter, which should be convertible to the
+value_type of the time property accessor
+
+ 
+
+
+
 EventTag
 
 The tag to specify when the time_stamper should be
-applied during the graph algorithm. EventTag must be an
-edge event.
+applied during the graph algorithm.
 
  
 
@@ -134,12 +144,12 @@ Construct a time stamper object with time property accessor
 
 
 
-template <class Vertex, class Graph>
-void operator()(Vertex u, const Graph& g);
+template <class X, class Graph>
+void operator()(X x, const Graph& g);
 
 
 This increments the time count and "stamps" the time:
    
-put(time_pa, u, ++t);
+put(time_pa, x, ++t);
 
 
 
@@ -153,11 +163,11 @@ This increments the time count and "stamps" the time:
    
 
 
 
-template <class TimePA, class Tag>
    
-time_stamper<TimePA, Tag> 
    
-record_predecessors(TimePA pa, Tag);
+template <class TimePA, class TimeT, class Tag>
    
+time_stamper<TimePA, TimeT, Tag>
    
+stamp_times(TimePA pa, TimeT& t, Tag);
     
-A convenient wat to create a time_stamper.
+A convenient way to create a time_stamper.
 
 
 
@@ -188,3 +198,9 @@ HREF="mailto:lums@lsc.nd.edu">lums@lsc.nd.edu)
 
 
  
+
+
+
diff --git a/docs/ucs_visitor.html b/docs/ucs_visitor.html
new file mode 100644
index 00000000..8344a894
--- /dev/null
+++ b/docs/ucs_visitor.html
@@ -0,0 +1,131 @@
+
+
+
+Boost Graph Library: ucs_visitor
+ 
+C++ Boost 
+
+
    
+
+
    
+
    +ucs_visitor<EventVisitorList>
+
    
+
    
+
+This class is an adapter that converts a list of EventVisitor's (constructed using
+std::pair) into a UniformCostVisitor.
+
+
+
    Example
    
+
+This is an excerpt from examples/dijkstra.cpp
+where the predecessor_recorder single-event visitor
+is used to record the shortest-paths search-tree calculated
+by Dijkstra's algorithm.
+
+
    +  std::vector<Vertex> p(num_vertices(G));
+  std::vector<int> d(num_vertices(G));
+
+  Vertex s = *(vertices(G).first);
+  
+  dijkstra_shortest_paths(G, s, d.begin(), 
+    make_ucs_visitor(record_predecessors(p.begin(), on_edge_relaxed())));
+
    
+
+
+
    Model of
    
+
+UniformCostVisitor
+
+
    Template Parameters
    
+
+
    
+
+
+
+
+
+
+
+
+
+
+
    ParameterDescriptionDefault
    EventVisitorList
+A list of EventVisitor's created
+with std::pair.
+null_visitor
    
+
+
    Where Defined
    
+
+
    
+
+boost/graph/uniform_cost_search.hpp
+
+
    Member Functions
    
+
+This class implements all of the member functions required by UniformCostVisitor. In each
+function the appropriate event is dispatched to the EventVisitor's in the EventVisitorList.
+
+
    Non-Member Functions
    
+
+
+
+
+
+
+
+
+
    FunctionDescription
    
+template <class EventVisitorList>
    
+bfs_visitor<EventVisitorList>
    
+make_bfs_visitor(EventVisitorList ev_list);
+    		
+Returns the event visitor list adapted to be a BFS visitor.
+
    
+
+
    See Also
    
+
+Visitor concepts
+
    
+The following are event visitors: predecessor_recorder,
+distance_recorder
+time_stamper,
+and property_writer.
+
+
+
    
+
    
+
+
+
    Copyright © 2000
+Jeremy Siek,
+Univ.of Notre Dame (jsiek@lsc.nd.edu)
    
+Lie-Quan Lee, Univ.of Notre Dame (llee1@lsc.nd.edu)
    
+Andrew Lumsdaine,
+Univ.of Notre Dame (lums@lsc.nd.edu)
+
    
+
+
+ 
diff --git a/docs/using_property_accessors.html b/docs/using_property_accessors.html
index 722d149f..520e8999 100644
--- a/docs/using_property_accessors.html
+++ b/docs/using_property_accessors.html
@@ -111,25 +111,25 @@ variables of the distance property type.
 
    
 
 
    
-There are two kinds of graph properties: internal and external. 
+There are two kinds of graph properties: interior and exterior. 
 
 
    
 
    
-
    Internal Properties
    
+
    Interior Properties
    
 
    are stored ``inside'' the graph object
 in some way, and the lifetime of the property value objects is the
 same as that of the graph object. 
 
 
    
 
    
-
    External Properties
    
+
    Exterior Properties
    
 
    are stored ``outside'' of the graph
 object and the lifetime of the property value objects is independent
 of the graph. This is useful for properties that are only needed
 temporarily, perhaps for the duration of a particular algorithm such
 as the color property used in breadth_first_search().  When
-using external properties with a BGL algorithm a property accessor
-object for the external property must be passed as an argument to the
+using exterior properties with a BGL algorithm a property accessor
+object for the exterior property must be passed as an argument to the
 algorithm.
 
    
 
    
@@ -141,7 +141,7 @@ Interior Properties
 
 
 
    
-A graph type that supports internal property storage (such as
+A graph type that supports interior property storage (such as
 adjacency_list) provides access to its property accessor
 objects through the interface defined in VertexPropertyGraph
 and EdgePropertyGraph.  There are two functions,
@@ -187,7 +187,7 @@ property accessors: distance, weight, color, and vertex ID.

    -Often times some or all of the properties will be internal to the +Often times some or all of the properties will be interior to the graph, so one would call Dijkstra's algorithm in the following way (given some graph g and source vertex src). @@ -204,11 +204,11 @@ graph, so one would call Dijkstra's algorithm in the following way

    Since it is somewhat cumbersome to specify all of the property accessors, BGL provides several ``short-cut'' interfaces to each -algorithm that assume some of the properties are internal and can be +algorithm that assume some of the properties are interior and can be accessed via get_vertex_property_accessor() from the graph. Below we show a call to variant 1 of the dijkstra_shortest_paths algorithm, which assumes -all of the properties are internal. This call is equivalent +all of the properties are interior. This call is equivalent to the previous call to Dijkstra's algorithm.

    @@ -217,7 +217,7 @@ to the previous call to Dijkstra's algorithm.

    -The next question is: how to internal properties become attached to a +The next question is: how to interior properties become attached to a graph object in the first place? This depends on the graph class that you are using. The adjacency_list graph class of BGL uses a plugin mechanism (see Section std::vector (obtained with a call to begin()) is a pointer, the pointer property accessor method also works for std::vector::iterator. The complete source code for this -examples is in examples/city_visitor.cpp. +examples is in examples/city_visitor.cpp. 

    @@ -370,7 +371,7 @@ int main(int,char*[])
   Graph G(N, edge_array, edge_array + sizeof(edge_array)/sizeof(E));
 
   // DFS and BFS need to "color" the vertices.
-  // Here we use std::vector as external property storage.
+  // Here we use std::vector as exterior property storage.
   std::vector<default_color_type> colors(N);
 
   cout << "*** Depth First ***" << endl;
@@ -408,7 +409,7 @@ class.
 
    
 The implementation of the
 random_access_iterator_property_accessor class
-serves as a good example for how to build and external property
+serves as a good example for how to build and exterior property
 accessor. Here we present a simplified implementation of the
 random_access_iterator_property_accessor class
 which we will name iterator_pa.