Let list_for_each_entry(), list_for_each_entry_reverse() and list_for_each_entry_safe...

[libfirm] / include / libfirm / adt / hungarian.h

diff --git a/include/libfirm/adt/hungarian.h b/include/libfirm/adt/hungarian.h
index 8a65361..7d1b85e 100644 (file)
--- a/include/libfirm/adt/hungarian.h
+++ b/include/libfirm/adt/hungarian.h
@@ -15,7 +15,7 @@
  ** "Stanford GraphGase", but I made changes to this code.
  ** As asked by  the copyright node of the "Stanford GraphGase",
  ** I hereby proclaim that this file are *NOT* part of the
- ** "Stanford GraphGase" distrubition!
+ ** "Stanford GraphGase" distribution!
  **
  ** This file is distributed in the hope that it will be useful,
  ** but WITHOUT ANY WARRANTY; without even the implied
@@ -28,54 +28,75 @@
 /**
  * @file
  * @brief   Solving the Minimum Assignment Problem using the Hungarian Method.
- * @version $Id$
  */
 #ifndef FIRM_ADT_HUNGARIAN_H
 #define FIRM_ADT_HUNGARIAN_H
 
-#define HUNGARIAN_MODE_MINIMIZE_COST 0
-#define HUNGARIAN_MODE_MAXIMIZE_UTIL 1
+#include "../begin.h"
 
-#define HUNGARIAN_MATCH_NORMAL  0
-#define HUNGARIAN_MATCH_PERFECT 1
+/**
+ * @ingroup algorithms
+ * @defgroup hungarian Hungarian Algorithm
+ * Solves bipartite matching problems (minimize/maximize cost function)
+ * @{
+ */
+
+/** type of matching */
+typedef enum match_type_t {
+       HUNGARIAN_MATCH_NORMAL,   /**< ever nodes matches another node */
+       HUNGARIAN_MATCH_PERFECT   /**< matchings of nodes having no edge getting
+                                      removed */
+} match_type_t;
 
-typedef struct _hungarian_problem_t hungarian_problem_t;
+/** mode of matching (the optimization goal) */
+typedef enum hungarian_mode_t {
+       HUNGARIAN_MODE_MINIMIZE_COST, /**< minimize cost */
+       HUNGARIAN_MODE_MAXIMIZE_UTIL  /**< maximize cost */
+} hungarian_mode_t;
+
+/**
+ * Internal representation of a bipartite matching problem
+ */
+typedef struct hungarian_problem_t hungarian_problem_t;
 
 /**
  * This method initialize the hungarian_problem structure and init
  * the cost matrix (missing lines or columns are filled with 0).
  *
- * @param rows       Number of rows in the given matrix
- * @param cols       Number of cols in the given matrix
- * @param match_type The type of matching:
- *                   HUNGARIAN_MATCH_PERFECT - every nodes matches another node
- *                   HUNGARIAN_MATCH_NORMAL  - matchings of nodes having no edge getting removed
+ * @param num_rows   Number of rows in the given matrix
+ * @param num_cols   Number of cols in the given matrix
+ * @param match_type The type of matching
  * @return The problem object.
  */
-hungarian_problem_t *hungarian_new(int rows, int cols, int match_type);
+FIRM_API hungarian_problem_t *hungarian_new(unsigned num_rows,
+                                            unsigned num_cols,
+                                            match_type_t match_type);
 
 /**
  * Adds an edge from left to right with some costs.
  */
-void hungarian_add(hungarian_problem_t *p, int left, int right, int cost);
+FIRM_API void hungarian_add(hungarian_problem_t *p, unsigned left,
+                            unsigned right, unsigned cost);
 
 /**
-* Removes the edge from left to right.
-*/
-void hungarian_remv(hungarian_problem_t *p, int left, int right);
+ * Removes the edge from left to right.
+ */
+FIRM_API void hungarian_remove(hungarian_problem_t *p, unsigned left,
+                               unsigned right);
 
 /**
- * Prepares the cost matrix, dependend on the given mode.
+ * Prepares the cost matrix dependent on the given mode.
  *
  * @param p     The hungarian object
- * @param mode  HUNGARIAN_MODE_MAXIMIZE_UTIL or HUNGARIAN_MODE_MINIMIZE_COST (default)
+ * @param mode  specify whether to minimize or maximize the costs
  */
-void hungarian_prepare_cost_matrix(hungarian_problem_t *p, int mode);
+FIRM_API void hungarian_prepare_cost_matrix(hungarian_problem_t *p,
+                                            hungarian_mode_t mode);
 
 /**
  * Destroys the hungarian object.
  */
-void hungarian_free(hungarian_problem_t *p);
+FIRM_API void hungarian_free(hungarian_problem_t *p);
 
 /**
  * This method computes the optimal assignment.
@@ -85,12 +106,19 @@ void hungarian_free(hungarian_problem_t *p);
  * @param cost_threshold Matchings with costs >= this limit will be removed (if limit > 0)
  * @return 0 on success, negative number otherwise
  */
-int hungarian_solve(hungarian_problem_t *p, int *assignment, int *final_cost, int cost_threshold);
+FIRM_API int hungarian_solve(hungarian_problem_t *p, unsigned *assignment,
+                             unsigned *final_cost, unsigned cost_threshold);
 
 /**
  * Print the cost matrix.
- * @param p The hungarian object
+ * @param p          The hungarian object
+ * @param cost_width The minimum field width of the costs
  */
-void hungarian_print_costmatrix(hungarian_problem_t *p, int cost_width);
+FIRM_API void hungarian_print_cost_matrix(hungarian_problem_t *p,
+                                          int cost_width);
+
+/** @} */
+
+#include "../end.h"
 
-#endif /* _HUNGARIAN_H_ */
+#endif