rework readme, improve examples, update license

Issue: saebyn#15
Signed-off-by: Gluttton <gluttton@ukr.net>

Author: Gluttton

README.md

@@ -12,15 +12,14 @@ target_link_libraries (example_02
     PRIVATE lp::munkres-cpp
 )
 
-find_package (Boost COMPONENTS system)
 add_executable (example_03
     EXCLUDE_FROM_ALL ${PROJECT_SOURCE_DIR}/examples/example_03.cpp
 )
 target_link_libraries (example_03
     PRIVATE lp::munkres-cpp
-    PRIVATE Boost::system
 )
 
+find_package (Boost COMPONENTS system)
 add_executable (example_04
     EXCLUDE_FROM_ALL ${PROJECT_SOURCE_DIR}/examples/example_04.cpp
 )
@@ -37,13 +36,40 @@ target_link_libraries (example_05
     PRIVATE Boost::system
 )
 
+find_package (OpenCV COMPONENTS core)
 add_executable (example_06
     EXCLUDE_FROM_ALL ${PROJECT_SOURCE_DIR}/examples/example_06.cpp
 )
+target_include_directories (example_06
+    PRIVATE ${OPENCV_INCLUDE_DIRS}
+)
 target_link_libraries (example_06
     PRIVATE lp::munkres-cpp
+    PRIVATE ${OpenCV_LIBS}
 )
 
+add_executable (example_07
+    EXCLUDE_FROM_ALL ${PROJECT_SOURCE_DIR}/examples/example_07.cpp
+)
+target_link_libraries (example_07
+    PRIVATE lp::munkres-cpp
+)
+
+add_executable (example_08
+    EXCLUDE_FROM_ALL ${PROJECT_SOURCE_DIR}/examples/example_08.cpp
+)
+target_link_libraries (example_08
+    PRIVATE lp::munkres-cpp
+)
+
+add_executable (example_09
+    EXCLUDE_FROM_ALL ${PROJECT_SOURCE_DIR}/examples/example_09.cpp
+)
+target_link_libraries (example_09
+    PRIVATE lp::munkres-cpp
+)
+
+
 add_custom_target (examples)
 add_dependencies  (examples
     example_01
@@ -52,4 +78,7 @@ add_dependencies  (examples
     example_04
     example_05
     example_06
+    example_07
+    example_08
+    example_09
 )

examples/CMakeLists.txt

@@ -1,5 +1,5 @@
 /*
- *   Copyright (c) 2007 John Weaver
+ *   Copyright (c) 2016 Gluttton <gluttton@ukr.net>
  *
  *   This program is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU General Public License as published by
@@ -18,33 +18,34 @@
 
 
 
-// The easiest way to start with munkres-cpp.
+// Trivial example with obvious solution.
+
+// Include header with the solver class.
 #include <munkres-cpp/munkres.h>
+// Include header with the built-in matrix class.
 #include <munkres-cpp/matrix.h>
 #include <cstdlib>
 
-int main (int /*argc*/, char * /*argv*/[])
+int main (int, char **)
 {
-    // Set input data (cost matrix) into matrix of generic type
-    // munkres_cpp::Matrix, which is provided by the library.
-    munkres_cpp::Matrix<int> data {
+    // Create an instance of matrix container and fill it with
+    // input (cost) data.
+    munkres_cpp::Matrix<unsigned> data {
     // Task I  Task II
         {1,       3}    // Worker I
        ,{5,       9}    // Worker II
     };
-    // You are totally responsible for correctness of the input data.
-    // Input data must be positive and well defined (no NaN or infinity).
 
-    // Next you need create the problem solver and pass data to it.
-    munkres_cpp::Munkres<int, munkres_cpp::Matrix> solver (data);
+    // Next, create a problem solver and pass data to it.
+    munkres_cpp::Munkres<unsigned, munkres_cpp::Matrix> solver (data);
 
     // Now the matrix contains the solution of the problem.
     // Zero value represents selected values.
     // For input above data the result will be:
     // Task I  Task II
     //   1,       0     // Worker I
     //   0,       1     // Worker II
-    // Which means that sum of the costs 3 and 5 is equal 8 and
+    // That means that sum of the costs 3 and 5 is equal 8 and
     // is minimum cost among the matrix.
 
     return EXIT_SUCCESS;

examples/example_01.cpp

@@ -1,5 +1,5 @@
 /*
- *   Copyright (c) 2007 John Weaver
+ *   Copyright (c) 2021 Gluttton <gluttton@ukr.net>
  *
  *   This program is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU General Public License as published by
@@ -18,40 +18,37 @@
 
 
 
-// Easy way to start with munkres-cpp.
+// Trivial example with less obvious solution.
+
+// Include header with the solver class.
 #include <munkres-cpp/munkres.h>
+// Include header with the built-in matrix class.
 #include <munkres-cpp/matrix.h>
-#include <munkres-cpp/utils.h>
 #include <cstdlib>
 
-int main (int /*argc*/, char * /*argv*/[])
+int main (int, char **)
 {
-    // Set input data (cost matrix) into matrix of generic type
-    // munkres_cpp::Matrix, which is provided by the library.
-    munkres_cpp::Matrix<int> data {
-        {1,   3}
-       ,{5,   9}
+    // Create an instance of matrix container and fill it with
+    // input (cost) data.
+    munkres_cpp::Matrix<unsigned> data {
+    // Task I  Task II Task III
+        {1,       3,      4}    // Worker I
+       ,{5,       9,      6}    // Worker II
+       ,{5,       8,      2}    // Worker III
     };
-    // You are totally responsible for correctness of the input data.
-    // Input data must be positive and well defined (no NaN or infinity).
-
-    // The library provide generic function for checking is input data
-    // correct and ready for processing. If you not sure in correctness
-    // of the input data you should use it.
-    if (munkres_cpp::is_data_valid (data) ) {
-        // Next you need to create the problem solver and pass data to it.
-        munkres_cpp::Munkres<int, munkres_cpp::Matrix> solver (data);
-
-        // Now the matrix contains the solution.
-        // Zero value represents selected values.
-        // For input above data the result will be:
-        //   1,   0
-        //   0,   1
-
-        return EXIT_SUCCESS;
-    }
-    else {
-        return EXIT_FAILURE;
-    }
-}
 
+    // Next, create a problem solver and pass data to it.
+    munkres_cpp::Munkres<unsigned, munkres_cpp::Matrix> solver (data);
+
+    // Now the matrix contains the solution of the problem.
+    // Zero value represents selected values.
+    // For input above data the result will be:
+    // Task I  Task II  Task III
+    //   1,       0,       1    // Worker I
+    //   0,       1,       1    // Worker II
+    //   1,       1,       0    // Worker III
+    // That means that sum of the costs 3, 5 and 2 is equal 10 and
+    // is minimum cost among the matrix.
+
+    return EXIT_SUCCESS;
+}

examples/example_02.cpp

@@ -1,5 +1,5 @@
 /*
- *   Copyright (c) 2007 John Weaver
+ *   Copyright (c) 2016 Gluttton <gluttton@ukr.net>
  *
  *   This program is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU General Public License as published by
@@ -18,30 +18,44 @@
 
 
 
-// Easy way to start with munkres-cpp.
+// Example with input data validation.
+
+// Include header with the solver class.
 #include <munkres-cpp/munkres.h>
-// The library provides set of adapters for the most popular containers
-// (for more info explore "adapters" folder).
-// If you are lucky then adapter for your container is already implemented.
-#include <munkres-cpp/adapters/matrix_boost.h>
+// Include header with the built-in matrix class.
+#include <munkres-cpp/matrix.h>
+// Include header with validation functions.
+#include <munkres-cpp/utils.h>
 #include <cstdlib>
 
-int main (int /*argc*/, char * /*argv*/[])
+int main (int, char **)
 {
-    // In such case you just need to create matrix of corresponding type,
-    // set input data (cost) and pass it to the solver.
-
-    // Set input data (cost matrix).
-    munkres_cpp::matrix_boost<double> data (2, 2);
-    data (0, 0) = 1.0; data (0, 1) = 3.0;
-    data (1, 0) = 5.0; data (1, 1) = 9.0;
-    // Don't forget! You are responsible for correctness of the input data.
-
-    // Create the solver and pass data to it.
-    munkres_cpp::Munkres<double, munkres_cpp::matrix_boost> solver (data);
-
-    // Now the matrix contains the solution.
-
-    return EXIT_SUCCESS;
+    // Create an instance of matrix container and fill it with
+    // input (cost) data.
+    munkres_cpp::Matrix<int> data {
+        {1,   3}
+       ,{5,   9}
+    };
+    // You are totally responsible for correctness of the input data.
+    // Input data must be positive and well defined (no NaN or infinity).
+
+    // The library provide generic function for checking is input data
+    // correct and ready for processing. If you not sure in correctness
+    // of the input data you should use it.
+    if (munkres_cpp::is_data_valid (data) ) {
+        // Next you need to create the problem solver and pass data to it.
+        munkres_cpp::Munkres<int, munkres_cpp::Matrix> solver (data);
+
+        // Now the matrix contains the solution.
+        // Zero value represents selected values.
+        // For input above data the result will be:
+        //   1,   0
+        //   0,   1
+
+        return EXIT_SUCCESS;
+    }
+    else {
+        return EXIT_FAILURE;
+    }
 }
 

examples/example_03.cpp

@@ -1,5 +1,5 @@
 /*
- *   Copyright (c) 2007 John Weaver
+ *   Copyright (c) 2016 Gluttton <gluttton@ukr.net>
  *
  *   This program is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU General Public License as published by
@@ -17,92 +17,33 @@
  */
 
 
+// Trivial example of using of adapter class.
 
-// More complex example.
+// Include header with the solver class.
 #include <munkres-cpp/munkres.h>
-// The library provides set of adapters for the most popular containers.
-// But if you need you can create adapter for any type of container by deriving
-// from base matrix class and implement the basic functions which allows to navigate
-// on container and access to its data.
-#include <munkres-cpp/matrix_base.h>
-#include <boost/numeric/ublas/matrix.hpp>
-#include <cstdlib>
-
-// In general there are several approaches how to implement adapters:
-// - use inheritance (inherited from both your container and
-//   munkres_cpp::matrix_base);
-// - use composition (inherited from munkres_cpp::matrix_base and use your
-//   container as member);
-template<class T>
-class matrix_boost_adapter : public munkres_cpp::matrix_base<T>
-{
-    public:
-        matrix_boost_adapter (boost::numeric::ublas::matrix<T> * data = nullptr)
-            : data        {data}
-            , is_own_data {false}
-        {
-            if (!data) {
-                data = new boost::numeric::ublas::matrix<T>;
-                is_own_data = true;
-            }
-        }
-
-        matrix_boost_adapter (size_t rows, size_t columns)
-            : data        {new boost::numeric::ublas::matrix<T> (rows, columns, 0)}
-            , is_own_data {true}
-        {
-        }
-
-        ~matrix_boost_adapter () override
-        {
-            if (is_own_data) {
-                delete data;
-            }
-        }
-
-        const T & operator () (const size_t row, const size_t column) const override
-        {
-            return data->operator () (row, column);
-        };
 
-        T & operator () (const size_t row, const size_t column) override
-        {
-            return data->operator () (row, column);
-        }
+// The library provides set of adapters for the most popular containers
+// (for more info explore "adapters" folder).
+// If you are lucky then adapter for your container is already implemented.
 
-        size_t columns () const override
-        {
-            return data->size2 ();
-        }
-
-        size_t rows () const override
-        {
-            return data->size1 ();
-        }
-
-        void resize (size_t, size_t, T/* value = T (0) */) override
-        {
-        }
-
-    private:
-        boost::numeric::ublas::matrix<T> * data;
-        bool is_own_data;
-};
+// Include header with the adapter for Boost matrix class.
+#include <munkres-cpp/adapters/matrix_boost.h>
+#include <cstdlib>
 
 int main (int /*argc*/, char * /*argv*/[])
 {
-    // Create (or use already existed) matrix of your type.
-    boost::numeric::ublas::matrix<double> data (2, 2);
+    // In such case you just need to create matrix of corresponding type,
+    // set input data (cost) and pass it to the solver.
+
     // Set input data (cost matrix).
+    munkres_cpp::matrix_boost<double> data (2, 2);
     data (0, 0) = 1.0; data (0, 1) = 3.0;
     data (1, 0) = 5.0; data (1, 1) = 9.0;
     // Don't forget! You are responsible for correctness of the input data.
-
-    // Create data adapter and pass your container to it.
-    matrix_boost_adapter<double> adapter (& data);
+    // NaN, infinities and negative values are prohibited!
 
     // Create the solver and pass data to it.
-    munkres_cpp::Munkres<double, matrix_boost_adapter> solver (adapter);
+    munkres_cpp::Munkres<double, munkres_cpp::matrix_boost> solver (data);
 
     // Now the matrix contains the solution.