dlib for dcu, version=19.24

dlib/dir_nav/posix.h

+// Copyright (C) 2003  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#ifndef DLIB_DIR_NAV_KERNEl_1_
+#include "dir_nav_kernel_2.h"
+#endif
+

dlib/dir_nav/windows.h

+// Copyright (C) 2003  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#ifndef DLIB_DIR_NAV_KERNEl_2_
+#include "dir_nav_kernel_1.h"
+#endif
+

dlib/directed_graph.h

+// Copyright (C) 2007  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#ifndef DLIB_DIRECTED_GRAPh_
+#define DLIB_DIRECTED_GRAPh_
+
+#include "directed_graph/directed_graph_kernel_1.h"
+
+#include "algs.h"
+
+namespace dlib
+{
+
+    template <
+        typename T,
+        typename E = char,
+        typename mem_manager = default_memory_manager
+        >
+    class directed_graph 
+    {
+        directed_graph() {}
+    public:
+                
+
+        //----------- kernels ---------------
+
+        // kernel_1a        
+        typedef     directed_graph_kernel_1<T,E,mem_manager,false>    
+                    kernel_1a;
+        typedef     directed_graph_kernel_1<T,E,mem_manager,true>    
+                    kernel_1a_c;
+ 
+    };
+}
+
+#endif // DLIB_DIRECTED_GRAPh_ 
+
+

dlib/directed_graph/directed_graph_kernel_1.h

+// Copyright (C) 2007  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#ifndef DLIB_DIRECTED_GRAPH_KERNEl_1_
+#define DLIB_DIRECTED_GRAPH_KERNEl_1_
+
+#include <memory>
+#include <vector>
+
+#include "../serialize.h"
+#include "../noncopyable.h"
+#include "../std_allocator.h"
+#include "../algs.h"
+#include "directed_graph_kernel_abstract.h"
+#include "../is_kind.h"
+
+namespace dlib
+{
+
+// ----------------------------------------------------------------------------------------
+
+    template <typename node_type, typename directed_graph, bool is_checked>
+    struct directed_graph_checker_helper 
+    { 
+        /*!
+            This object is used to check preconditions based on the value of is_checked
+        !*/
+
+        static void check_parent_edge (
+            unsigned long edge_index,
+            const node_type& self
+        )
+        {
+            // make sure requires clause is not broken
+            DLIB_CASSERT(edge_index < self.number_of_parents(),
+                         "\tnode_type& directed_graph::node_type::parent_edge(edge_index)"
+                         << "\n\tYou have specified an invalid index"
+                         << "\n\tedge_index:          " << edge_index 
+                         << "\n\tnumber_of_parents(): " << self.number_of_parents() 
+                         << "\n\tthis:              " << &self
+            );
+        }
+
+        static void check_child_edge (
+            unsigned long edge_index,
+            const node_type& self
+        )
+        {
+            // make sure requires clause is not broken
+            DLIB_CASSERT(edge_index < self.number_of_children(),
+                         "\tnode_type& directed_graph::node_type::child_edge(edge_index)"
+                         << "\n\tYou have specified an invalid index"
+                         << "\n\tedge_index:           " << edge_index 
+                         << "\n\tnumber_of_children(): " << self.number_of_children() 
+                         << "\n\tthis:              " << &self
+            );
+        }
+
+        static void check_parent (
+            unsigned long edge_index,
+            const node_type& self
+        )
+        {
+            // make sure requires clause is not broken
+            DLIB_CASSERT(edge_index < self.number_of_parents(),
+                         "\tnode_type& directed_graph::node_type::parent(edge_index)"
+                         << "\n\tYou have specified an invalid index"
+                         << "\n\tedge_index:          " << edge_index 
+                         << "\n\tnumber_of_parents(): " << self.number_of_parents() 
+                         << "\n\tthis:              " << &self
+            );
+        }
+
+        static void check_child (
+            unsigned long edge_index,
+            const node_type& self
+        )
+        {
+            // make sure requires clause is not broken
+            DLIB_CASSERT(edge_index < self.number_of_children(),
+                         "\tnode_type& directed_graph::node_type::child(edge_index)"
+                         << "\n\tYou have specified an invalid index"
+                         << "\n\tedge_index:           " << edge_index 
+                         << "\n\tnumber_of_children(): " << self.number_of_children() 
+                         << "\n\tthis:              " << &self
+            );
+        }
+
+        static void check_node (
+            unsigned long index,
+            const directed_graph& self
+        )
+        {
+            // make sure requires clause is not broken
+            DLIB_CASSERT(index < self.number_of_nodes(),
+                         "\tnode_type& directed_graph::node(index)"
+                         << "\n\tYou have specified an invalid index"
+                         << "\n\tindex:             " << index 
+                         << "\n\tnumber_of_nodes(): " << self.number_of_nodes()
+                         << "\n\tthis:              " << &self
+            );
+        }
+
+        static void check_has_edge (
+            unsigned long parent_node_index,
+            unsigned long child_node_index,
+            const directed_graph& self
+        )
+        {
+            // make sure requires clause is not broken
+            DLIB_CASSERT(parent_node_index < self.number_of_nodes() &&
+                         child_node_index < self.number_of_nodes(),
+                         "\tvoid directed_graph::has_edge(parent_node_index, child_node_index)"
+                         << "\n\tYou have specified an invalid index"
+                         << "\n\tparent_node_index: " << parent_node_index 
+                         << "\n\tchild_node_index:  " << child_node_index 
+                         << "\n\tnumber_of_nodes(): " << self.number_of_nodes() 
+                         << "\n\tthis:              " << &self
+            );
+        }
+
+        static void check_add_edge (
+            unsigned long parent_node_index,
+            unsigned long child_node_index,
+            const directed_graph& self
+        )
+        {
+            DLIB_CASSERT(parent_node_index < self.number_of_nodes() &&
+                         child_node_index < self.number_of_nodes(),
+                         "\tvoid directed_graph::add_edge(parent_node_index, child_node_index)" 
+                         << "\n\tYou have specified an invalid index"
+                         << "\n\tparent_node_index: " << parent_node_index 
+                         << "\n\tchild_node_index:  " << child_node_index 
+                         << "\n\tnumber_of_nodes(): " << self.number_of_nodes()
+                         << "\n\tthis:              " << &self
+            );
+
+            DLIB_CASSERT( self.has_edge(parent_node_index, child_node_index) == false,
+                          "\tvoid directed_graph::add_edge(parent_node_index, child_node_index)"
+                          << "\n\tYou can't add an edge if it already exists in the graph"
+                          << "\n\tparent_node_index: " << parent_node_index 
+                          << "\n\tchild_node_index:  " << child_node_index 
+                          << "\n\tnumber_of_nodes(): " << self.number_of_nodes() 
+                          << "\n\tthis:              " << &self
+            );
+
+        }
+
+        static void check_remove_edge (
+            unsigned long parent_node_index,
+            unsigned long child_node_index,
+            const directed_graph& self
+        )
+        {
+            DLIB_CASSERT(parent_node_index < self.number_of_nodes() &&
+                         child_node_index < self.number_of_nodes(),
+                         "\tvoid directed_graph::remove_edge(parent_node_index, child_node_index)" 
+                         << "\n\tYou have specified an invalid index"
+                         << "\n\tparent_node_index: " << parent_node_index 
+                         << "\n\tchild_node_index:  " << child_node_index 
+                         << "\n\tnumber_of_nodes(): " << self.number_of_nodes()
+                         << "\n\tthis:              " << &self
+            );
+
+            DLIB_CASSERT( self.has_edge(parent_node_index, child_node_index) == true,
+                          "\tvoid directed_graph::remove_edge(parent_node_index, child_node_index)"
+                          << "\n\tYou can't remove an edge if it isn't in the graph"
+                          << "\n\tparent_node_index: " << parent_node_index 
+                          << "\n\tchild_node_index:  " << child_node_index 
+                          << "\n\tnumber_of_nodes(): " << self.number_of_nodes()
+                          << "\n\tthis:              " << &self
+            );
+
+        }
+
+        static void check_remove_node (
+            unsigned long index,
+            const directed_graph& self
+        )
+        {
+            // make sure requires clause is not broken
+            DLIB_CASSERT(index < self.number_of_nodes(),
+                         "\tvoid directed_graph::remove_node(index)"
+                         << "\n\tYou have specified an invalid index"
+                         << "\n\tindex:             " << index 
+                         << "\n\tnumber_of_nodes(): " << self.number_of_nodes() 
+                         << "\n\tthis:              " << &self
+            );
+        }
+    };
+
+    template <typename node_type, typename directed_graph>
+    struct directed_graph_checker_helper <node_type, directed_graph, false>
+    { 
+        static inline void check_parent ( unsigned long , const node_type&) { }
+        static inline void check_child ( unsigned long , const node_type& ) { }
+        static inline void check_parent_edge ( unsigned long , const node_type&) { }
+        static inline void check_child_edge ( unsigned long , const node_type& ) { }
+        static inline void check_node ( unsigned long , const directed_graph& ) { }
+        static inline void check_has_edge ( unsigned long , unsigned long , const directed_graph& ) { }
+        static inline void check_add_edge ( unsigned long , unsigned long , const directed_graph& ) { }
+        static inline void check_remove_edge ( unsigned long , unsigned long , const directed_graph& ) { }
+        static inline void check_remove_node ( unsigned long , const directed_graph& ) { }
+    };
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T,
+        typename E = char,
+        typename mem_manager = default_memory_manager,
+        bool is_checked = true 
+        >
+    class directed_graph_kernel_1 : noncopyable
+    {
+
+        /*!
+            INITIAL VALUE
+                - nodes.size() == 0
+
+            CONVENTION
+                - nodes.size() == number_of_nodes()
+                - for all valid i:
+                    - *nodes[i] == node(i)
+                    - nodes[i]->parents.size() == nodes[i]->number_of_parents(i)
+                    - nodes[i]->children.size() == nodes[i]->number_of_children(i)
+                    - nodes[i]->edge_parents.size() == nodes[i]->number_of_parents(i)
+                    - nodes[i]->edge_children.size() == nodes[i]->number_of_children(i)
+                    - nodes[i]->idx == i == nodes[i]->index()
+                    - for all valid p:
+                        - nodes[i]->parents[p] == pointer to the p'th parent node of i
+                        - *nodes[i]->parents[p] == nodes[i]->parent(p)
+                        - *nodes[i]->edge_parents[p] == nodes[i]->parent_edge(p)
+                    - for all valid c:
+                        - nodes[i]->children[c] == pointer to the c'th child node of i
+                        - *nodes[i]->children[c] == nodes[i]->child(c)
+                        - *nodes[i]->edge_children[c] == nodes[i]->child_edge(c)
+        !*/
+
+    public:
+        struct node_type;
+
+    private:
+        typedef directed_graph_checker_helper<node_type, directed_graph_kernel_1, is_checked> checker;
+
+
+    public:
+
+        typedef T type;
+        typedef E edge_type;
+        typedef mem_manager mem_manager_type;
+
+        template <typename Tr, typename Er, typename MMr>
+        struct rebind {
+            typedef directed_graph_kernel_1<Tr,Er,MMr> other;
+        };
+
+        directed_graph_kernel_1(
+        ) {}
+
+        virtual ~directed_graph_kernel_1(
+        ) {}
+
+        void clear(
+        ) { nodes.clear(); }
+
+        void set_number_of_nodes (
+            unsigned long new_size
+        );
+
+        unsigned long number_of_nodes (
+        ) const { return nodes.size(); }
+
+        node_type& node (
+            unsigned long index
+        ) { checker::check_node(index,*this); return *nodes[index]; }
+
+        const node_type& node (
+            unsigned long index
+        ) const { checker::check_node(index,*this); return *nodes[index]; }
+
+        bool has_edge (
+            unsigned long parent_node_index,
+            unsigned long child_node_index
+        ) const;
+
+        void add_edge (
+            unsigned long parent_node_index,
+            unsigned long child_node_index
+        );
+
+        void remove_edge (
+            unsigned long parent_node_index,
+            unsigned long child_node_index
+        );
+
+        unsigned long add_node (
+        );
+
+        void remove_node (
+            unsigned long index
+        );
+
+        void swap (
+            directed_graph_kernel_1& item
+        ) { nodes.swap(item.nodes); }
+
+    private:
+
+
+    public:
+
+        struct node_type
+        {
+            T data;
+            typedef directed_graph_kernel_1 graph_type;
+
+            unsigned long index(
+            ) const { return idx; }
+
+            unsigned long number_of_parents (
+            ) const { return parents.size(); }
+
+            unsigned long number_of_children (
+            ) const { return children.size(); }
+
+            const node_type& parent (
+                unsigned long edge_index
+            ) const { checker::check_parent(edge_index,*this);  return *parents[edge_index]; }
+
+            node_type& parent (
+                unsigned long edge_index
+            ) { checker::check_parent(edge_index,*this);  return *parents[edge_index]; }
+
+            const node_type& child (
+                unsigned long edge_index
+            ) const { checker::check_child(edge_index,*this);  return *children[edge_index]; }
+
+            node_type& child (
+                unsigned long edge_index
+            ) { checker::check_child(edge_index,*this);  return *children[edge_index]; }
+
+            const E& parent_edge (
+                unsigned long edge_index
+            ) const { checker::check_parent_edge(edge_index,*this);  return *edge_parents[edge_index]; }
+
+            E& parent_edge (
+                unsigned long edge_index
+            ) { checker::check_parent_edge(edge_index,*this);  return *edge_parents[edge_index]; }
+
+            const E& child_edge (
+                unsigned long edge_index
+            ) const { checker::check_child_edge(edge_index,*this);  return *edge_children[edge_index]; }
+
+            E& child_edge (
+                unsigned long edge_index
+            ) { checker::check_child_edge(edge_index,*this);  return *edge_children[edge_index]; }
+
+        private:
+            friend class directed_graph_kernel_1;
+            typedef std_allocator<node_type*,mem_manager> alloc_type;
+            typedef std_allocator<std::shared_ptr<E>,mem_manager> alloc_edge_type;
+            std::vector<node_type*,alloc_type> parents;
+            std::vector<node_type*,alloc_type> children;
+            std::vector<std::shared_ptr<E>,alloc_edge_type> edge_parents;
+            std::vector<std::shared_ptr<E>,alloc_edge_type> edge_children;
+            unsigned long idx;
+        };
+
+    private:
+
+        typedef std_allocator<std::shared_ptr<node_type>,mem_manager> alloc_type;
+        typedef std::vector<std::shared_ptr<node_type>, alloc_type> vector_type;
+        vector_type nodes;
+    };
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T, 
+        typename E,
+        typename mem_manager,
+        bool is_checked
+        >
+    struct is_directed_graph<directed_graph_kernel_1<T,E,mem_manager, is_checked> >
+    {
+        static const bool value = true; 
+    };
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T, 
+        typename E,
+        typename mem_manager,
+        bool is_checked
+        >
+    inline void swap (
+        directed_graph_kernel_1<T,E,mem_manager,is_checked>& a, 
+        directed_graph_kernel_1<T,E,mem_manager,is_checked>& b 
+    ) { a.swap(b); }   
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T,
+        typename E,
+        typename mem_manager,
+        bool is_checked
+        >
+    void serialize (
+        const directed_graph_kernel_1<T,E,mem_manager,is_checked>& item,
+        std::ostream& out 
+    )   
+    {
+        try
+        {
+            serialize(item.number_of_nodes(), out);
+
+            // serialize each node
+            for (unsigned long i = 0; i < item.number_of_nodes(); ++i)
+            {
+                serialize(item.node(i).data, out);
+
+                // serialize all the child edges
+                serialize(item.node(i).number_of_children(), out);
+                for (unsigned long c = 0; c < item.node(i).number_of_children(); ++c)
+                {
+                    serialize(item.node(i).child(c).index(), out);
+                    serialize(item.node(i).child_edge(c), out);
+                }
+            }
+        }
+        catch (serialization_error& e)
+        {
+            throw serialization_error(e.info + "\n   while serializing object of type directed_graph_kernel_1"); 
+        }
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T,
+        typename E,
+        typename mem_manager,
+        bool is_checked
+        >
+    void deserialize (
+        directed_graph_kernel_1<T,E,mem_manager,is_checked>& item,
+        std::istream& in
+    )   
+    {
+        try
+        {
+            unsigned long size;
+            deserialize(size, in);
+
+            item.clear();
+            item.set_number_of_nodes(size);
+
+            // deserialize each node
+            for (unsigned long i = 0; i < item.number_of_nodes(); ++i)
+            {
+                deserialize(item.node(i).data, in);
+
+                unsigned long num_children;
+                deserialize(num_children, in);
+
+                // Add all the edges going to this nodes children nodes
+                for (unsigned long c = 0; c < num_children; ++c)
+                {
+                    unsigned long child_index;
+                    deserialize(child_index, in);
+
+                    item.add_edge(i, child_index);
+
+                    // find the edge we just added
+                    for (unsigned long j = 0; j < item.node(i).number_of_children(); ++j)
+                    {
+                        if (item.node(i).child(j).index() == child_index)
+                        {
+                            deserialize(item.node(i).child_edge(j), in);
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+        catch (serialization_error& e)
+        {
+            throw serialization_error(e.info + "\n   while deserializing object of type directed_graph_kernel_1"); 
+        }
+    }
+
+// ----------------------------------------------------------------------------------------
+// ----------------------------------------------------------------------------------------
+//                             member function definitions
+// ----------------------------------------------------------------------------------------
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T,
+        typename E,
+        typename mem_manager,
+        bool is_checked
+        >
+    void directed_graph_kernel_1<T,E,mem_manager,is_checked>::
+    set_number_of_nodes (
+        unsigned long new_size
+    )
+    {
+        try
+        {
+            nodes.resize(new_size);
+            for (unsigned long i = 0; i < nodes.size(); ++i)
+            {
+                nodes[i].reset(new node_type);
+                nodes[i]->idx = i;
+            }
+        }
+        catch (...)
+        {
+            clear();
+            throw;
+        }
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T,
+        typename E,
+        typename mem_manager,
+        bool is_checked
+        >
+    bool directed_graph_kernel_1<T,E,mem_manager,is_checked>::
+    has_edge (
+        unsigned long parent_node_index,
+        unsigned long child_node_index
+    ) const
+    {
+        checker::check_has_edge(parent_node_index, child_node_index, *this);
+
+        node_type& n = *nodes[parent_node_index];
+
+        // search all the child nodes to see if there is a link to the right node
+        for (unsigned long i = 0; i < n.children.size(); ++i)
+        {
+            if (n.children[i]->idx == child_node_index)
+                return true;
+        }
+
+        return false;
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T,
+        typename E,
+        typename mem_manager,
+        bool is_checked
+        >
+    void directed_graph_kernel_1<T,E,mem_manager,is_checked>::
+    add_edge (
+        unsigned long parent_node_index,
+        unsigned long child_node_index
+    )
+    {
+        checker::check_add_edge(parent_node_index, child_node_index, *this);
+        try
+        {
+            node_type& p = *nodes[parent_node_index];
+            node_type& c = *nodes[child_node_index];
+
+            p.children.push_back(&c);
+            c.parents.push_back(&p);
+
+            p.edge_children.push_back(std::shared_ptr<E>(new E));
+            c.edge_parents.push_back(p.edge_children.back());
+        }
+        catch (...)
+        {
+            clear();
+            throw;
+        }
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T,
+        typename E,
+        typename mem_manager,
+        bool is_checked
+        >
+    void directed_graph_kernel_1<T,E,mem_manager,is_checked>::
+    remove_edge (
+        unsigned long parent_node_index,
+        unsigned long child_node_index
+    )
+    {
+        checker::check_remove_edge(parent_node_index, child_node_index, *this);
+
+        node_type& p = *nodes[parent_node_index];
+        node_type& c = *nodes[child_node_index];
+
+        // remove the record of the link from the parent node
+        unsigned long pos = static_cast<unsigned long>(find( p.children.begin(),
+                                  p.children.end(),
+                                  &c) - p.children.begin());
+        p.children.erase(p.children.begin()+pos);
+        p.edge_children.erase(p.edge_children.begin()+pos);
+
+        // remove the record of the link from the child node
+        pos = static_cast<unsigned long>(find( c.parents.begin(),
+                  c.parents.end(),
+                  &p) - c.parents.begin());
+        c.parents.erase(c.parents.begin() + pos);
+        c.edge_parents.erase(c.edge_parents.begin() + pos);
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T,
+        typename E,
+        typename mem_manager,
+        bool is_checked
+        >
+    unsigned long directed_graph_kernel_1<T,E,mem_manager,is_checked>::
+    add_node (
+    )
+    {
+        try
+        {
+            std::shared_ptr<node_type> n(new node_type);
+            n->idx = nodes.size();
+            nodes.push_back(n);
+            return n->idx;
+        }
+        catch (...)
+        {
+            clear();
+            throw;
+        }
+    }
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename T,
+        typename E,
+        typename mem_manager,
+        bool is_checked
+        >
+    void directed_graph_kernel_1<T,E,mem_manager,is_checked>::
+    remove_node (
+        unsigned long index
+    )
+    {
+        checker::check_remove_node(index,*this);
+
+        node_type& n = *nodes[index];
+
+        // remove all edges pointing to this node from its parents 
+        for (unsigned long i = 0; i < n.parents.size(); ++i)
+        {
+            // remove the edge from this specific parent
+            unsigned long pos = static_cast<unsigned long>(find(n.parents[i]->children.begin(), 
+                     n.parents[i]->children.end(), 
+                     &n) - n.parents[i]->children.begin());
+
+            n.parents[i]->children.erase(n.parents[i]->children.begin() + pos);
+            n.parents[i]->edge_children.erase(n.parents[i]->edge_children.begin() + pos);
+        }
+
+        // remove all edges pointing to this node from its children 
+        for (unsigned long i = 0; i < n.children.size(); ++i)
+        {
+            // remove the edge from this specific child 
+            unsigned long pos = static_cast<unsigned long>(find(n.children[i]->parents.begin(),
+                     n.children[i]->parents.end(),
+                     &n) - n.children[i]->parents.begin());
+
+            n.children[i]->parents.erase(n.children[i]->parents.begin() + pos);
+            n.children[i]->edge_parents.erase(n.children[i]->edge_parents.begin() + pos);
+        }
+
+        // now remove this node by replacing it with the last node in the nodes vector
+        nodes[index] = nodes[nodes.size()-1];
+
+        // update the index for the node we just moved
+        nodes[index]->idx = index;
+
+        // now remove the duplicated node at the end of the vector
+        nodes.pop_back();
+    }
+
+// ----------------------------------------------------------------------------------------
+
+}
+
+#endif // DLIB_DIRECTED_GRAPH_KERNEl_1_
+

dlib/directed_graph/directed_graph_kernel_abstract.h

+// Copyright (C) 2007  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#undef DLIB_DIRECTED_GRAPH_KERNEl_ABSTRACT_
+#ifdef DLIB_DIRECTED_GRAPH_KERNEl_ABSTRACT_
+
+#include "../serialize.h"
+#include "../algs.h"
+#include "../noncopyable.h"
+
+namespace dlib
+{
+
+    template <
+        typename T,
+        typename E = char,
+        typename mem_manager = default_memory_manager 
+        >
+    class directed_graph : noncopyable
+    {
+
+        /*!
+            REQUIREMENTS ON T 
+                T must be swappable by a global swap() and
+                T must have a default constructor
+
+            REQUIREMENTS ON E 
+                E must be swappable by a global swap() and
+                E must have a default constructor
+
+            REQUIREMENTS ON mem_manager
+                must be an implementation of memory_manager/memory_manager_kernel_abstract.h or
+                must be an implementation of memory_manager_global/memory_manager_global_kernel_abstract.h or
+                must be an implementation of memory_manager_stateless/memory_manager_stateless_kernel_abstract.h 
+                mem_manager::type can be set to anything.
+
+            POINTERS AND REFERENCES TO INTERNAL DATA
+                The only time pointers or references to nodes or edges become invalid is when
+                they reference nodes or edges that have been removed from a graph.
+
+            INITIAL VALUE
+                number_of_nodes() == 0
+
+            WHAT THIS OBJECT REPRESENTS
+                This object represents a directed graph which is a set of nodes with directed
+                edges connecting various nodes.  
+
+                In this object if there is a directed edge from a node A to a node B then I say 
+                that A is the parent of B and B is the child of A.
+
+                Also note that unless specified otherwise, no member functions
+                of this object throw exceptions.
+        !*/
+
+    public:
+
+        typedef T type;
+        typedef E edge_type;
+        typedef mem_manager mem_manager_type;
+
+        template <typename Tr, typename Er, typename MMr>
+        struct rebind {
+            typedef directed_graph<Tr,Er,MMr> other;
+        };
+
+        directed_graph(
+        );
+        /*!
+            ensures 
+                - #*this is properly initialized
+            throws
+                - std::bad_alloc or any exception thrown by T's constructor.
+        !*/
+
+        virtual ~directed_graph(
+        ); 
+        /*!
+            ensures
+                - all resources associated with *this has been released
+        !*/
+
+        void clear(
+        );
+        /*!
+            ensures
+                - #*this has its initial value
+            throws
+                - std::bad_alloc or any exception thrown by T's constructor.
+                  If this exception is thrown then *this is unusable 
+                  until clear() is called and succeeds
+        !*/
+
+        void set_number_of_nodes (
+            unsigned long new_size
+        );
+        /*!
+            ensures
+                - #number_of_nodes() == new_size
+                - for all i < new_size:
+                    - number_of_parents(i) == 0
+                    - number_of_children(i) == 0
+            throws
+                - std::bad_alloc or any exception thrown by T's constructor.
+                  If this exception is thrown then this object reverts back 
+                  to its initial state.
+        !*/
+
+        unsigned long number_of_nodes (
+        ) const;
+        /*!
+            ensures
+                - returns the number of nodes in this graph
+        !*/
+
+        struct node_type
+        {
+            T data;
+            typedef directed_graph graph_type;
+
+            unsigned long index(
+            ) const;
+            /*!
+                ensures
+                    - let G be the graph that contains the node *this
+                    - returns a number N such that G.node(N) == *this
+                      (i.e. returns the index of this node in the graph)
+            !*/
+
+            unsigned long number_of_parents (
+            ) const;
+            /*!
+                ensures
+                    - returns the number of parents of this node 
+            !*/
+
+            unsigned long number_of_children (
+            ) const;
+            /*!
+                ensures
+                    - returns the number of children of this node 
+            !*/
+
+            const node_type& parent (
+                unsigned long edge_index
+            ) const;
+            /*!
+                requires
+                    - edge_index < number_of_parents()
+                ensures
+                    - returns a const reference to the edge_index'th parent of *this
+            !*/
+
+            node_type& parent (
+                unsigned long edge_index
+            );
+            /*!
+                requires
+                    - edge_index < number_of_parents()
+                ensures
+                    - returns a non-const reference to the edge_index'th parent of *this
+            !*/
+
+            const node_type& child (
+                unsigned long edge_index
+            ) const;
+            /*!
+                requires
+                    - edge_index < number_of_children()
+                ensures
+                    - returns a const reference to the edge_index'th child of *this
+            !*/
+
+            node_type& child (
+                unsigned long edge_index
+            );
+            /*!
+                requires
+                    - edge_index < number_of_children()
+                ensures
+                    - returns a non-const reference to the edge_index'th child of *this
+            !*/
+
+            const E& parent_edge (
+                unsigned long edge_index
+            ) const;
+            /*!
+                requires
+                    - edge_index < number_of_parents()
+                ensures
+                    - returns a const reference to the edge_index'th edge data for the
+                      edge connecting to node this->parent(edge_index)
+            !*/
+
+            E& parent_edge (
+                unsigned long edge_index
+            );
+            /*!
+                requires
+                    - edge_index < number_of_parents()
+                ensures
+                    - returns a non-const reference to the edge_index'th edge data for the
+                      edge connecting to node this->parent(edge_index)
+            !*/
+
+            const E& child_edge (
+                unsigned long edge_index
+            ) const;
+            /*!
+                requires
+                    - edge_index < number_of_children()
+                ensures
+                    - returns a const reference to the edge_index'th edge data for the
+                      edge connecting to node this->child(edge_index)
+            !*/
+
+            E& child_edge (
+                unsigned long edge_index
+            );
+            /*!
+                requires
+                    - edge_index < number_of_children()
+                ensures
+                    - returns a non-const reference to the edge_index'th edge data for the
+                      edge connecting to node this->child(edge_index)
+            !*/
+        };
+
+        node_type& node (
+            unsigned long index
+        );
+        /*!
+            requires
+                - index < number_of_nodes()
+            ensures
+                - returns a non-const reference to the node with the given index
+        !*/
+
+        const node_type& node (
+            unsigned long index
+        ) const;
+        /*!
+            requires
+                - index < number_of_nodes()
+            ensures
+                - returns a const reference to the node with the given index
+        !*/
+
+        bool has_edge (
+            unsigned long parent_node_index,
+            unsigned long child_node_index
+        ) const;
+        /*!
+            requires
+                - parent_node_index < number_of_nodes()
+                - child_node_index < number_of_nodes()
+            ensures
+                - if (there is an edge leading from node(parent_node_index) to
+                  node(child_node_index)) then
+                    - returns true
+                - else
+                    - returns false
+        !*/
+
+        void add_edge (
+            unsigned long parent_node_index,
+            unsigned long child_node_index
+        );
+        /*!
+            requires
+                - parent_node_index < number_of_nodes()
+                - child_node_index < number_of_nodes()
+                - has_edge(parent_node_index, child_node_index) == false
+            ensures
+                - #has_edge(parent_node_index, child_node_index) == true 
+            throws
+                - std::bad_alloc 
+                  If this exception is thrown then this object reverts back 
+                  to its initial state.
+        !*/
+
+        void remove_edge (
+            unsigned long parent_node_index,
+            unsigned long child_node_index
+        );
+        /*!
+            requires
+                - parent_node_index < number_of_nodes()
+                - child_node_index < number_of_nodes()
+                - has_edge(parent_node_index, child_node_index) == true 
+            ensures
+                - #has_edge(parent_node_index, child_node_index) == false 
+            throws
+                - std::bad_alloc 
+                  If this exception is thrown then this object reverts back 
+                  to its initial state.
+        !*/
+
+        unsigned long add_node (
+        );
+        /*!
+            ensures
+                - does not change the index number of existing nodes
+                - adds a node with index N == number_of_nodes() such that:
+                    - #node(N).number_of_parents() == 0 
+                    - #node(N).number_of_children() == 0 
+                    - #number_of_nodes() == number_of_nodes() + 1
+                    - returns N  
+            throws
+                - std::bad_alloc or any exception thrown by T's constructor.
+                  If this exception is thrown then this object reverts back 
+                  to its initial state.
+        !*/
+
+        void remove_node (
+            unsigned long index
+        );
+        /*!
+            requires
+                - index < number_of_nodes()
+            ensures
+                - removes the node with the given index from the graph. 
+                - removes all edges linking the removed node to the rest
+                  of the graph.
+                - the remaining node indexes are remapped so that they remain
+                  contiguous.  (This means that for all valid N, node(N) doesn't
+                  necessarily reference the same node as #node(N))
+                - #number_of_nodes() == number_of_nodes() - 1
+            throws
+                - std::bad_alloc or any exception thrown by T's constructor.
+                  If this exception is thrown then this object reverts back 
+                  to its initial state.
+        !*/
+
+        void swap (
+            directed_graph& item
+        );
+        /*!
+            ensures
+                - swaps *this and item
+        !*/ 
+
+    };
+
+    template <
+        typename T, 
+        typename mem_manager
+        >
+    inline void swap (
+        directed_graph<T,mem_manager>& a, 
+        directed_graph<T,mem_manager>& b 
+    ) { a.swap(b); }   
+    /*!
+        provides a global swap function
+    !*/
+
+    template <
+        typename T,
+        typename mem_manager
+        >
+    void serialize (
+        const directed_graph<T,mem_manager>& item,
+        std::ostream& out 
+    );   
+    /*!
+        provides deserialization support 
+    !*/
+
+    template <
+        typename T,
+        typename mem_manager
+        >
+    void deserialize (
+        directed_graph<T,mem_manager>& item,
+        std::istream& in
+    );   
+    /*!
+        provides deserialization support 
+    !*/
+
+}
+
+#endif // DLIB_DIRECTED_GRAPH_KERNEl_ABSTRACT_
+
+

dlib/disjoint_subsets.h

+// Copyright (C) 2011  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#ifndef DLIB_DISJOINt_SUBSETS_
+#define DLIB_DISJOINt_SUBSETS_
+
+
+#include "disjoint_subsets/disjoint_subsets.h"
+#include "disjoint_subsets/disjoint_subsets_sized.h"
+
+#endif // DLIB_DISJOINt_SUBSETS_
+
+

dlib/disjoint_subsets/disjoint_subsets.h

+// Copyright (C) 2011  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#ifndef DLIB_DISJOINT_SUBsETS_Hh_
+#define DLIB_DISJOINT_SUBsETS_Hh_
+
+#include "disjoint_subsets_abstract.h"
+#include <vector>
+#include "../algs.h"
+
+namespace dlib
+{
+
+// ----------------------------------------------------------------------------------------
+
+    class disjoint_subsets
+    {
+    public:
+
+        void clear (
+        ) noexcept
+        {
+            items.clear();
+        }
+
+        void set_size (
+            unsigned long new_size
+        )
+        {
+            items.resize(new_size);
+            for (unsigned long i = 0; i < items.size(); ++i)
+            {
+                items[i].parent = i;
+                items[i].rank = 0;
+            }
+        }
+
+        size_t size (
+        ) const noexcept
+        {
+            return items.size();
+        }
+
+        unsigned long find_set (
+            unsigned long item
+        ) const
+        {
+            // make sure requires clause is not broken
+            DLIB_ASSERT(item < size(),
+                "\t unsigned long disjoint_subsets::find_set()"
+                << "\n\t item must be less than size()"
+                << "\n\t item: " << item
+                << "\n\t size(): " << size()
+                << "\n\t this: " << this
+                );
+
+            if (items[item].parent == item)
+            {
+                return item;
+            }
+            else
+            {
+                // find root of item
+                unsigned long x = item;
+                do
+                {
+                    x = items[x].parent;
+                } while (items[x].parent != x);
+
+                // do path compression
+                const unsigned long root = x;
+                x = item;
+                while (items[x].parent != x)
+                {
+                    const unsigned long prev = x;
+                    x = items[x].parent;
+                    items[prev].parent = root;
+                }
+
+                return root;
+            }
+        }
+
+        unsigned long merge_sets (
+            unsigned long a,
+            unsigned long b
+        )
+        {
+            // make sure requires clause is not broken
+            DLIB_ASSERT(a != b &&
+                        a < size() &&
+                        b < size() &&
+                        find_set(a) == a &&
+                        find_set(b) == b,
+                "\t unsigned long disjoint_subsets::merge_sets(a,b)"
+                << "\n\t invalid arguments were given to this function"
+                << "\n\t a: " << a
+                << "\n\t b: " << b
+                << "\n\t size(): " << size()
+                << "\n\t find_set(a): " << find_set(a)
+                << "\n\t find_set(b): " << find_set(b)
+                << "\n\t this: " << this
+                );
+
+            if (items[a].rank > items[b].rank)
+            {
+                items[b].parent = a;
+                return a;
+            }
+            else
+            {
+                items[a].parent = b;
+                if (items[a].rank == items[b].rank)
+                {
+                    items[b].rank = items[b].rank + 1;
+                }
+                return b;
+            }
+        }
+
+    private:
+
+        /*
+            See the book Introduction to Algorithms by Cormen, Leiserson, Rivest and Stein
+            for a discussion of how this algorithm works.
+        */
+
+        struct data
+        {
+            unsigned long rank;
+            unsigned long parent;
+        };
+
+        mutable std::vector<data> items;
+
+    };
+
+// ----------------------------------------------------------------------------------------
+
+}
+
+#endif // DLIB_DISJOINT_SUBsETS_Hh_

dlib/disjoint_subsets/disjoint_subsets_abstract.h

+// Copyright (C) 2011  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#undef DLIB_DISJOINT_SUBsETS_ABSTRACT_Hh_
+#ifdef DLIB_DISJOINT_SUBsETS_ABSTRACT_Hh_
+
+#include <vector>
+#include "../algs.h"
+
+namespace dlib
+{
+
+// ----------------------------------------------------------------------------------------
+
+    class disjoint_subsets
+    {
+        /*!
+            INITIAL VALUE
+                - size() == 0
+
+            WHAT THIS OBJECT REPRESENTS
+                This object represents a set of integers which is partitioned into
+                a number of disjoint subsets.  It supports the two fundamental operations
+                of finding which subset a particular integer belongs to as well as
+                merging subsets.
+        !*/
+    public:
+
+        void clear (
+        ) noexcept;
+        /*!
+            ensures
+                - #size() == 0
+                - returns this object to its initial value
+        !*/
+
+        void set_size (
+            unsigned long new_size
+        );
+        /*!
+            ensures
+                - #size() == new_size
+                - for all valid i:
+                    - #find_set(i) == i
+                      (i.e. this object contains new_size subsets, each containing exactly one element)
+        !*/
+
+        size_t size (
+        ) const noexcept;
+        /*!
+            ensures
+                - returns the total number of integer elements represented
+                  by this object.
+        !*/
+
+        unsigned long find_set (
+            unsigned long item
+        ) const;
+        /*!
+            requires
+                - item < size()
+            ensures
+                - Each disjoint subset can be represented by any of its elements (since
+                  the sets are all disjoint).  In particular, for each subset we define
+                  a special "representative element" which is used to represent it.
+                  Therefore, this function returns the representative element for the
+                  set which contains item.
+                - find_set(find_set(item)) == find_set(item)
+                - Note that if A and B are both elements of the same subset then we always
+                  have find_set(A) == find_set(B).
+        !*/
+
+        unsigned long merge_sets (
+            unsigned long a,
+            unsigned long b
+        );
+        /*!
+            requires
+                - a != b
+                - a < size()
+                - b < size()
+                - find_set(a) == a
+                  (i.e. a is the representative element of some set)
+                - find_set(b) == b
+                  (i.e. b is the representative element of some set)
+            ensures
+                - #find_set(a) == #find_set(b)
+                  (i.e. merges the set's containing a and b)
+                - returns #find_set(a)
+        !*/
+    };
+
+// ----------------------------------------------------------------------------------------
+
+}
+
+#endif // DLIB_DISJOINT_SUBsETS_ABSTRACT_Hh_

dlib/disjoint_subsets/disjoint_subsets_sized.h

+// Copyright (C) 2011  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#ifndef DLIB_DISJOINT_SUBsETS_SIZED_Hh_
+#define DLIB_DISJOINT_SUBsETS_SIZED_Hh_
+
+#include "disjoint_subsets_sized_abstract.h"
+#include "disjoint_subsets.h"
+#include <vector>
+#include "../algs.h"
+
+namespace dlib
+{
+
+// ----------------------------------------------------------------------------------------
+
+    class disjoint_subsets_sized
+    {
+    public:
+
+        void clear (
+        ) noexcept
+        {
+            disjoint_subsets_.clear();
+            sets_size.clear();
+            number_of_sets = 0;
+        }
+
+        void set_size (
+            unsigned long new_size
+        )
+        {
+            disjoint_subsets_.set_size(new_size);
+            sets_size.assign(new_size, 1);
+            number_of_sets = new_size;
+        }
+
+        size_t size (
+        ) const noexcept
+        {
+            return disjoint_subsets_.size();
+        }
+
+        unsigned long find_set (
+            unsigned long item
+        ) const
+        {
+            // make sure requires clause is not broken
+            DLIB_ASSERT(item < size(),
+                "\t unsigned long disjoint_subsets::find_set()"
+                << "\n\t item must be less than size()"
+                << "\n\t item: " << item
+                << "\n\t size(): " << size()
+                << "\n\t this: " << this
+                );
+
+            return disjoint_subsets_.find_set(item);
+        }
+
+        unsigned long merge_sets (
+            unsigned long a,
+            unsigned long b
+        )
+        {
+            // make sure requires clause is not broken
+            DLIB_ASSERT(a != b &&
+                        a < size() &&
+                        b < size() &&
+                        find_set(a) == a &&
+                        find_set(b) == b,
+                "\t unsigned long disjoint_subsets::merge_sets(a,b)"
+                << "\n\t invalid arguments were given to this function"
+                << "\n\t a: " << a
+                << "\n\t b: " << b
+                << "\n\t size(): " << size()
+                << "\n\t find_set(a): " << find_set(a)
+                << "\n\t find_set(b): " << find_set(b)
+                << "\n\t this: " << this
+                );
+
+            disjoint_subsets_.merge_sets(a, b);
+
+            if (find_set(a) == a) sets_size[a] += sets_size[b];
+            else sets_size[b] += sets_size[a];
+            --number_of_sets;
+
+            return find_set(a);
+        }
+
+        unsigned long get_number_of_sets (
+        ) const noexcept
+        {
+            return number_of_sets;
+        }
+
+        unsigned long get_size_of_set(
+                unsigned long item
+        ) const
+        {
+            // make sure requires clause is not broken
+            DLIB_ASSERT(item < size() &&
+                        find_set(item) == item,
+                        "\t unsigned long disjoint_subsets::get_size_of_set()"
+                                << "\n\t invalid arguments were given to this function"
+                                << "\n\t item: " << item
+                                << "\n\t size(): " << size()
+                                << "\n\t find_set(item): " << find_set(item)
+                                << "\n\t this: " << this
+            );
+
+            return sets_size[item];
+        }
+
+    private:
+
+        /*
+            See the book Introduction to Algorithms by Cormen, Leiserson, Rivest and Stein
+            for a discussion of how this algorithm works.
+        */
+
+        mutable std::vector<unsigned long> sets_size;
+        unsigned long number_of_sets{0};
+        disjoint_subsets disjoint_subsets_;
+
+    };
+
+// ----------------------------------------------------------------------------------------
+
+}
+
+#endif // DLIB_DISJOINT_SUBsETS_SIZED_Hh_