graph.hh

Go to the documentation of this file.
00001 /* vim: set sw=4 sts=4 et foldmethod=syntax : */
00002 
00003 /*
00004  * Copyright (c) 2007, 2008 Ciaran McCreesh
00005  *
00006  * This file is part of the Paludis package manager. Paludis is free software;
00007  * you can redistribute it and/or modify it under the terms of the GNU General
00008  * Public License version 2, as published by the Free Software Foundation.
00009  *
00010  * Paludis is distributed in the hope that it will be useful, but WITHOUT ANY
00011  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
00012  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
00013  * details.
00014  *
00015  * You should have received a copy of the GNU General Public License along with
00016  * this program; if not, write to the Free Software Foundation, Inc., 59 Temple
00017  * Place, Suite 330, Boston, MA  02111-1307  USA
00018  */
00019 
00020 #ifndef PALUDIS_GUARD_PALUDIS_UTIL_GRAPH_HH
00021 #define PALUDIS_GUARD_PALUDIS_UTIL_GRAPH_HH 1
00022 
00023 #include <paludis/util/graph-fwd.hh>
00024 #include <paludis/util/private_implementation_pattern.hh>
00025 #include <paludis/util/instantiation_policy.hh>
00026 #include <paludis/util/exception.hh>
00027 #include <tr1/memory>
00028 
00029 /** \file
00030  * Declarations for DirectedGraph and related utilities.
00031  *
00032  * \ingroup g_data_structures
00033  *
00034  * \section Examples
00035  *
00036  * - None at this time.
00037  */
00038 
00039 namespace paludis
00040 {
00041     /**
00042      * Base class for DirectedGraph errors.
00043      *
00044      * \ingroup g_data_structures
00045      * \ingroup g_exceptions
00046      * \nosubgrouping
00047      */
00048     class PALUDIS_VISIBLE GraphError :
00049         public Exception
00050     {
00051         protected:
00052             ///\name Basic operations
00053             ///\{
00054 
00055             GraphError(const std::string & msg) throw ();
00056 
00057             ///\}
00058     };
00059 
00060     /**
00061      * Thrown if a DirectedGraph operation relies upon a node being present when it is not.
00062      *
00063      * \ingroup g_exceptions
00064      * \ingroup g_data_structures
00065      * \nosubgrouping
00066      */
00067     class PALUDIS_VISIBLE NoSuchGraphNodeError :
00068         public GraphError
00069     {
00070         public:
00071             ///\name Basic operations
00072             ///\{
00073 
00074             template <typename Node_>
00075             NoSuchGraphNodeError(const Node_ & node) throw () :
00076                 GraphError("Node '" + stringify(node) + "' does not exist")
00077             {
00078             }
00079 
00080             ///\}
00081     };
00082 
00083     /**
00084      * Thrown if a DirectedGraph operation relies upon an edge being present when it is not.
00085      *
00086      * \ingroup g_exceptions
00087      * \ingroup g_data_structures
00088      * \nosubgrouping
00089      */
00090     class PALUDIS_VISIBLE NoSuchGraphEdgeError :
00091         public GraphError
00092     {
00093         public:
00094             ///\name Basic operations
00095             ///\{
00096 
00097             template <typename Node_>
00098             NoSuchGraphEdgeError(const Node_ & e1, const Node_ & e2) throw () :
00099                 GraphError("Edge '" + stringify(e1) + "' -> '" + stringify(e2) + "' does not exist")
00100             {
00101             }
00102 
00103             ///\}
00104     };
00105 
00106     /**
00107      * Thrown if no ordering is available for a DirectedGraph::topological_sort.
00108      *
00109      * \ingroup g_data_structures
00110      * \ingroup g_exceptions
00111      * \nosubgrouping
00112      */
00113     class PALUDIS_VISIBLE NoGraphTopologicalOrderExistsError :
00114         public GraphError
00115     {
00116         private:
00117             class RemainingNodes;
00118             std::tr1::shared_ptr<const RemainingNodes> _remaining_nodes;
00119 
00120         public:
00121             ///\name Basic operations
00122             ///\{
00123 
00124             NoGraphTopologicalOrderExistsError(const std::tr1::shared_ptr<const RemainingNodes> &) throw ();
00125             ~NoGraphTopologicalOrderExistsError() throw ();
00126 
00127             ///\}
00128 
00129             /**
00130              * The nodes remaining in the graph.
00131              */
00132             std::tr1::shared_ptr<const RemainingNodes> remaining_nodes() const;
00133     };
00134 
00135     /**
00136      * A simple directed graph.
00137      *
00138      * \ingroup g_data_structures
00139      * \nosubgrouping
00140      */
00141     template <typename Node_, typename Edge_, typename Comparator_>
00142     class PALUDIS_VISIBLE DirectedGraph :
00143         private PrivateImplementationPattern<DirectedGraph<Node_, Edge_, Comparator_> >
00144     {
00145         private:
00146             using PrivateImplementationPattern<DirectedGraph<Node_, Edge_, Comparator_> >::_imp;
00147 
00148             void operator= (const DirectedGraph &);
00149 
00150         public:
00151             ///\name Basic operations
00152             ///\{
00153 
00154             DirectedGraph();
00155             DirectedGraph(const DirectedGraph &);
00156             ~DirectedGraph();
00157 
00158             ///\}
00159 
00160             ///\name Node related functions
00161             ///\{
00162 
00163             /**
00164              * Add a node, if it does not already exist.
00165              */
00166             void add_node(const Node_ &);
00167 
00168             /**
00169              * Delete a node, if it exists.
00170              */
00171             void delete_node(const Node_ &);
00172 
00173             /**
00174              * Return whether a node exists.
00175              */
00176             bool has_node(const Node_ &) const;
00177 
00178             ///\}
00179 
00180             ///\name Iterate over our nodes
00181             ///\{
00182 
00183             class NodeConstIterator;
00184             NodeConstIterator begin_nodes() const;
00185             NodeConstIterator end_nodes() const;
00186 
00187             ///\}
00188 
00189             ///\name Edge related functions
00190             ///\{
00191 
00192             /**
00193              * Add an edge, if it does not already exist.
00194              *
00195              * \throw NoSuchGraphNodeError if either node is not in the graph.
00196              */
00197             void add_edge(const Node_ &, const Node_ &, const Edge_ &);
00198 
00199             /**
00200              * Delete an edge, if it exists.
00201              */
00202             void delete_edge(const Node_ &, const Node_ &);
00203 
00204             /**
00205              * Delete all edges leaving a node.
00206              */
00207             void delete_outgoing_edges(const Node_ &);
00208 
00209             /**
00210              * Delete all edges entering a node.
00211              */
00212             void delete_incoming_edges(const Node_ &);
00213 
00214             /**
00215              * Return whether an edge exists.
00216              */
00217             bool has_edge(const Node_ &, const Node_ &) const;
00218 
00219             /**
00220              * Fetch an edge.
00221              *
00222              * \throw NoSuchGraphEdgeError if the edge does not exist.
00223              */
00224             const Edge_ fetch_edge(const Node_ &, const Node_ &) const;
00225 
00226             /**
00227              * Return whether a node has outgoing edges.
00228              *
00229              * \throw NoSuchGraphNodeError if the node does not exist.
00230              */
00231             bool has_outgoing_edges(const Node_ &) const;
00232 
00233             ///\}
00234 
00235             ///\name Ordering functions
00236             ///\{
00237 
00238             /**
00239              * Place our nodes, topological sorted, into OutputIterator_.
00240              *
00241              * \throw NoGraphTopologicalOrderExistsError if no such order exists.
00242              */
00243             template <typename OutputIterator_>
00244             void topological_sort(OutputIterator_ i) const;
00245 
00246             ///\}
00247     };
00248 }
00249 
00250 #endif

Generated on Mon Sep 21 10:36:08 2009 for paludis by  doxygen 1.5.4