pgr_maxCardinalityMatch fix

.github/workflows/check-queries.yml

@@ -100,6 +100,7 @@ jobs:
           sudo -u postgres createdb -p ${PGPORT}  ____sigs_routing____
           sudo -u postgres psql -p ${PGPORT} -c "CREATE ROLE runner SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN" -d ____sigs_routing____
           tools/release-scripts/get_signatures.sh -p ${PGPORT}
+          git diff --name-only sql/sigs/*.sig
           git diff --exit-code --quiet sql/sigs/*.sig
 
       - name: Test documentation queries are up to date

NEWS

@@ -30,7 +30,6 @@ pgRouting 3.4.0 Release Notes
     * ``pgr_trsp_withPoints`` (Many to Many)
     * ``pgr_trsp_withPoints`` (Combinations)
 
-
 * Topology
 
   * ``pgr_degree``
@@ -40,6 +39,14 @@ pgRouting 3.4.0 Release Notes
   * ``pgr_findCloseEdges`` (One point)
   * ``pgr_findCloseEdges`` (Many points)
 
+**Official functions changes**
+
+* Flow functions
+
+  * ``pgr_maxCardinalityMatch(text)``
+
+    * Deprecating ``pgr_maxCardinalityMatch(text,boolean)``
+
 **Deprecated functions**
 
 * Turn Restrictions
@@ -56,6 +63,27 @@ To see all issues & pull requests closed by this release see the `Git closed
 milestone for 3.3.2
 <https://github.com/pgRouting/pgrouting/issues?utf8=%E2%9C%93&q=milestone%3A%22Release%203.3.2%22>`_
 
+* Revised documentation
+
+  * Simplifying table names and table columns, for example:
+
+    * ``edges`` instead of ``edge_table``
+
+      * Removing unused columns ``category_id`` and ``reverse_category_id``.
+
+    * ``combinations`` instead of ``combinations_table``
+
+     * Using PostGIS standard for geometry column.
+
+       * ``geom`` instead of ``the_geom``
+
+  * Avoiding usage of functions that modify indexes, columns etc on tables.
+
+    * Using ``pgr_extractVertices`` to create a routing topology
+
+  * Restructure of the pgRouting concepts page.
+
+
 **Issue fixes**
 
 * [#2276](https://github.com/pgRouting/pgrouting/issues/2276):

doc/max_flow/pgr_maxCardinalityMatch.rst

@@ -35,6 +35,21 @@ graph.
 
 .. Rubric:: Availability
 
+* Version 3.4.0
+
+  * Use ``cost`` and ``reverse_cost`` on the inner query
+  * Results are ordered
+  * Works for undirected graphs.
+  * New signature
+
+    * ``pgr_maxCardinalityMatch(text)`` returns only ``edge`` column.
+
+  * Deprecated signature
+
+    * ``pgr_maxCardinalityMatch(text,boolean)``
+
+      * ``directed => false`` when used.
+
 * Version 3.0.0
 
   * **Official** function
@@ -52,17 +67,16 @@ graph.
 Description
 -------------------------------------------------------------------------------
 
-**The main characteristics are:**
+The main characteristics are:
 
+* Works for **undirected** graphs.
 * A matching or independent edge set in a graph is a set of edges without common
   vertices.
 * A maximum matching is a matching that contains the largest possible number of
   edges.
 
   * There may be many maximum matchings.
-  * Calculates **one** possible maximum cardinality matching in a graph.
-
-* The graph can be **directed** or **undirected**.
+  * Calculates one possible maximum cardinality matching in a graph.
 
 * Running time: :math:`O( E*V * \alpha(E,V))`
 
@@ -78,17 +92,24 @@ Signatures
 
 .. parsed-literal::
 
-    pgr_maxCardinalityMatch(`Edges SQL`_ [, directed])
-
-    RETURNS SET OF (seq, edge_id, source, target)
+    pgr_maxCardinalityMatch(`Edges SQL`_)
+    RETURNS SET OF (edge)
     OR EMPTY SET
 
-:Example: For a **directed** graph
+:Example: Using all edges.
+
 
 .. literalinclude:: doc-pgr_maxCardinalityMatch.queries
    :start-after: -- q2
    :end-before: -- q3
 
+Parameters
+-------------------------------------------------------------------------------
+
+.. include:: pgRouting-concepts.rst
+   :start-after: only_edge_param_start
+   :end-before: only_edge_param_end
+
 Inner Queries
 -------------------------------------------------------------------------------
 
@@ -97,39 +118,57 @@ Edges SQL
 
 SQL query, which should return a set of rows with the following columns:
 
-========== =============== =================================================
-Column     Type            Description
-========== =============== =================================================
-``id``     ``ANY-INTEGER`` Identifier of the edge.
-``source`` ``ANY-INTEGER`` Identifier of the first end point vertex of the edge.
-``target`` ``ANY-INTEGER`` Identifier of the second end point vertex of the edge.
-``going``  ``ANY-NUMERIC`` A positive value represents the existence of the edge
-                           (``source``, ``target``).
-``coming`` ``ANY-NUMERIC`` A positive value represents the existence of the edge
-                           (``target``, ``source``).
-========== =============== =================================================
+.. list-table::
+   :width: 81
+   :widths: 14 14 7 44
+   :header-rows: 1
+
+   * - Column
+     - Type
+     - Default
+     - Description
+   * - ``id``
+     - **ANY-INTEGER**
+     -
+     - Identifier of the edge.
+   * - ``source``
+     - **ANY-INTEGER**
+     -
+     - Identifier of the first end point vertex of the edge.
+   * - ``target``
+     - **ANY-INTEGER**
+     -
+     - Identifier of the second end point vertex of the edge.
+   * - ``cost``
+     - **ANY-NUMERICAL**
+     -
+     - A positive value represents the existence of the edge (``source``,
+       ``target``).
+   * - ``reverse_cost``
+     - **ANY-NUMERICAL**
+     - -1
+     - A positive value represents the existence of the edge (``target``,
+       ``source``)
 
 Where:
 
-:ANY-INTEGER: SMALLINT, INTEGER, BIGINT
-:ANY-NUMERIC: SMALLINT, INTEGER, BIGINT, REAL FLOAT
+:ANY-INTEGER: ``SMALLINT``, ``INTEGER``, ``BIGINT``
+:ANY-NUMERICAL: ``SMALLINT``, ``INTEGER``, ``BIGINT``, ``REAL``, ``FLOAT``
 
 Result Columns
 -------------------------------------------------------------------------------
 
 ========== ========== =================================================
 Column     Type       Description
 ========== ========== =================================================
-``seq``    ``INT``    Sequential value starting from **1**.
 ``edge``   ``BIGINT`` Identifier of the edge in the original query.
-``source`` ``BIGINT`` Identifier of the first end point of the edge.
-``target`` ``BIGINT`` Identifier of the second end point of the edge.
 ========== ========== =================================================
 
 See Also
 -------------------------------------------------------------------------------
 
 * :doc:`flow-family`
+* :doc:`migration`
 * https://www.boost.org/libs/graph/doc/maximum_matching.html
 * https://en.wikipedia.org/wiki/Matching_%28graph_theory%29
 * https://en.wikipedia.org/wiki/Ackermann_function
@@ -138,4 +177,3 @@ See Also
 
 * :ref:`genindex`
 * :ref:`search`
-

doc/src/migration.rst

@@ -16,18 +16,72 @@
 Migration guide
 ===============================================================================
 
-``pgr_trsp`` signatures have changed and many issues have been fixed in the new
-signatures. This section will show how to migrate from the old signatures to the
-new replacement functions.
+Several functions are having changes on the signatures, and/or have been
+replaced by new functions.
+
+Results can be different because of the changes.
 
-.. Note:: Results might be different as the deprecated function's code is
-   different from the replacement function.
+Migrating functions:
+
+:doc:`pgr_maxCardinalityMatch` works only for undirected graphs, therefore the
+``directed`` flag has been removed.
+
+:doc:`pgr_trsp` signatures have changed and many issues have been fixed in the new
+signatures. This section will show how to migrate from the old signatures to the
+new replacement functions. This also affects the restrictions.
 
 .. warning::
    All deprecated functions will be removed on next mayor version 4.0.0
 
 .. contents:: Contents
 
+Migration of ``pgr_maxCardinalityMatch``
+-------------------------------------------------------------------------------
+
+Signature to be migrated:
+
+.. parsed-literal::
+
+  pgr_maxCardinalityMatch(Edges SQL, [directed])
+   RETURNS SETOF (seq, edge, source, target)
+
+Migration is needed, because:
+
+* Use ``cost`` and ``reverse_cost`` on the inner query
+* Results are ordered
+* Works for undirected graphs.
+* New signature
+
+  * ``pgr_maxCardinalityMatch(text)`` returns only ``edge`` column.
+  * The optional flag ``directed`` is removed.
+
+:Before migration:
+
+.. literalinclude:: migration.queries
+   :start-after: --maxcard1
+   :end-before: --maxcard2
+
+* Columns used are ``going`` and ``coming`` to represent the existence of an
+  edge.
+* Flag ``directed`` was used to indicate if it was for a **directed** or
+  **undirected** graph.
+
+  * The flag ``directed`` is ignored.
+
+    * Regardless of it's value it gives the result considering the graph as
+      **undirected**.
+
+:Migration:
+
+* Use the columns ``cost`` and ``reverse_cost`` to represent the existence of an
+  edge.
+* Do not use the flag ``directed``.
+* In the query returns only ``edge`` column.
+
+.. literalinclude:: migration.queries
+   :start-after: --maxcard2
+   :end-before: --maxcard3
+
 Migration of restrictions
 -------------------------------------------------------------------------------
 
@@ -60,7 +114,7 @@ Creation of the old restrictions table
    :start-after: --rest00
    :end-before: --rest01
 
-Old restrictions fillup
+Old restrictions fill up
 
 .. literalinclude:: migration.queries
    :start-after: --rest01
@@ -120,12 +174,12 @@ To transform the old restrictions table to the new restrictions structure,
 
   * In this migration guide ``new_restrictions`` is been used.
 
-* For this migration pgRuoting supllies an auxilary function for reversal of an
+* For this migration pgRouting supplies an auxiliary function for reversal of an
   array ``_pgr_array_reverse`` needed for the migration.
 
   * ``_pgr_array_reverse``:
 
-    * Was created temporarly for this migration
+    * Was created temporally for this migration
     * Is not documented.
     * Will be removed on the next mayor version 4.0.0
 
@@ -160,7 +214,7 @@ Signature to be migrated:
 
 * Does not autodetect if ``reverse_cost`` column exist.
 
-  * User must be carefull to match the existance of the column with the value of
+  * User must be careful to match the existence of the column with the value of
     ``has_rcost`` parameter.
 
 * The restrictions inner query is optional.
@@ -289,7 +343,7 @@ Signature to be migrated:
 
 * Does not autodetect if ``reverse_cost`` column exist.
 
-  * User must be carefull to match the existance of the column with the value of
+  * User must be careful to match the existence of the column with the value of
     ``has_rcost`` parameter.
 
 * The restrictions inner query is optional.
@@ -425,7 +479,7 @@ Signature to be migrated:
 
 * Does not autodetect if ``reverse_cost`` column exist.
 
-  * User must be carefull to match the existance of the column with the value of
+  * User must be careful to match the existence of the column with the value of
     ``has_rcost`` parameter.
 
 * The restrictions inner query is optional.
@@ -556,7 +610,7 @@ Signature to be migrated:
 
 * Does not autodetect if ``reverse_cost`` column exist.
 
-  * User must be carefull to match the existance of the column with the value of
+  * User must be careful to match the existence of the column with the value of
     ``has_rcost`` parameter.
 
 * The restrictions inner query is optional.
@@ -567,7 +621,7 @@ For these migration guide the following points will be used:
    :start-after: --viav7
    :end-before: --edgesvia1
 
-And will travel thru the follwoing Via points :math:`4\rightarrow3\rightarrow6`
+And will travel thru the following Via points :math:`4\rightarrow3\rightarrow6`
 
 Migrate by using: