GSoC 2023: Yige Huang Week 9

doc/src/migration.rst

@@ -20,6 +20,11 @@ Results can be different because of the changes.
 
 Migrating functions:
 
+:doc:`pgr_withPointsDD` signatures have changed, with the addition of new columns
+in the new signatures. It works mainly for driving cases, therefore the ``driving side``
+parameter changed from optional to compulsory, and its valid values differ for
+directed and undirected graphs.
+
 :doc:`pgr_maxCardinalityMatch` works only for undirected graphs, therefore the
 ``directed`` flag has been removed.
 
@@ -38,6 +43,76 @@ Migration of functions that add new columns
 .. contents:: Contents
    :local:
 
+Migration of ``pgr_withPointsDD``
+-------------------------------------------------------------------------------
+
+Starting from `v3.6.0 <https://docs.pgrouting.org/3.6/en/migration.html>`__
+
+Signatures to be migrated:
+
+* ``pgr_withPointsDD`` (`Single vertex`)
+* ``pgr_withPointsDD`` (`Multiple vertices`)
+
+:Before Migration:
+
+.. literalinclude:: migration.queries
+   :start-after: --withpointsdd1
+   :end-before: --withpointsdd2
+
+* ``driving_side`` parameter is optional.
+* Output columns were |result-generic-no-seq|
+
+  * Depending on the overload used, the columns ``start_vid`` might be missing:
+
+    * ``pgr_withPointsDD`` (`Single vertex`) does not have ``start_vid``
+
+:Migration:
+
+* ``driving side`` parameter is compulsory, and valid values differ for directed
+  and undirected graphs.
+
+  * Does not have a default value.
+
+  * In directed graph, valid values are [``r``, ``R``, ``l``, ``L``]
+
+  * In undirected graph, valid values are [``b``, ``B``]
+
+
+* Be aware of the existance of the additional columns.
+
+* In ``pgr_withPointsDD`` (`Single vertex`)
+
+  * ``start_vid`` contains the **start vid** parameter value.
+  * ``depth`` contains the **depth** parameter value.
+
+.. literalinclude:: migration.queries
+   :start-after: --withpointsdd2
+   :end-before: --withpointsdd3
+
+* In ``pgr_withPointsDD`` (`Multiple vertices`)
+
+  * ``depth`` contains the **depth** parameter value.
+
+.. literalinclude:: migration.queries
+   :start-after: --withpointsdd3
+   :end-before: --withpointsdd4
+
+* If needed filter out the added columns, for example:
+
+.. literalinclude:: migration.queries
+   :start-after: --withpointsdd4
+   :end-before: --withpointsdd5
+
+* If needed add the new columns, similar to the following example where
+  ``pgr_dijkstra`` is used, and the function had to be modified to be able to
+  return the new columns:
+
+  * In `v3.0 <https://docs.pgrouting.org/3.0/en/contraction-family.html#case-1-both-source-and-target-belong-to-the-contracted-graph>`__
+    the function ``my_dijkstra`` uses ``pgr_dijkstra``.
+  * Starting from `v3.5 <https://docs.pgrouting.org/3.5/en/contraction-family.html#case-1-both-source-and-target-belong-to-the-contracted-graph>`__
+    the function ``my_dijkstra`` returns the new additional columns of
+    ``pgr_dijkstra``.
+
 Migration of ``pgr_aStar``
 -------------------------------------------------------------------------------
 

doc/withPoints/pgr_withPointsDD.rst

@@ -138,11 +138,16 @@ Parameters
      - Upper limit for the inclusion of a node in the result.
    * - **driving side**
      - ``CHAR``
-     - Value in [``r``, ``R``, ``l``, ``L``, ``b``, ``B``] indicating if the driving side is:
+     - - Value in [``r``, ``R``, ``l``, ``L``, ``b``, ``B``] indicating if the driving side is:
 
-       - ``r``, ``R`` for right driving side,
-       - ``l``, ``L`` for left driving side.
-       - ``b``, ``B`` for both.
+         - ``r``, ``R`` for right driving side,
+         - ``l``, ``L`` for left driving side.
+         - ``b``, ``B`` for both.
+
+       - Valid values differ for directed and undirected graphs:
+
+         - In directed graphs: [``r``, ``R``, ``l``, ``L``].
+         - In undirected graphs: [``b``, ``B``].
 
 Where:
 

docqueries/src/migration.result

@@ -719,5 +719,88 @@ SELECT seq, path_seq, node, edge, cost, agg_cost FROM pgr_aStar(
 (6 rows)
 
 /* --astar5 */
+/* --withpointsdd1 */
+SELECT * FROM pgr_withPointsDD(
+  $$SELECT id, source, target, cost, reverse_cost FROM edges ORDER BY id$$,
+  $$SELECT pid, edge_id, fraction, side from pointsOfInterest$$,
+  -5, 2.3,
+  driving_side => 'r');
+WARNING:  pgr_withpointsdd(text,text,bigint,double precision,boolean,character,boolean) is been deprecated
+ seq | node | edge | cost | agg_cost
+-----+------+------+------+----------
+   1 |   -5 |   -1 |    0 |        0
+   2 |   11 |    5 |  0.2 |      0.2
+   3 |    7 |    8 |    1 |      1.2
+   4 |   12 |   11 |    1 |      1.2
+   5 |   16 |    9 |    1 |      1.2
+   6 |    3 |    7 |    1 |      2.2
+   7 |    6 |    4 |    1 |      2.2
+   8 |    8 |   10 |    1 |      2.2
+   9 |   15 |   16 |    1 |      2.2
+  10 |   17 |   13 |    1 |      2.2
+(10 rows)
+
+/* --withpointsdd2 */
+SELECT * FROM pgr_withPointsDD(
+  $$SELECT id, source, target, cost, reverse_cost FROM edges ORDER BY id$$,
+  $$SELECT pid, edge_id, fraction, side from pointsOfInterest$$,
+  -5, 2.3, 'r');
+ seq | depth | start_vid | node | edge | cost | agg_cost
+-----+-------+-----------+------+------+------+----------
+   1 |     0 |        -5 |   -5 |   -1 |    0 |        0
+   2 |     1 |        -5 |   11 |    5 |  0.2 |      0.2
+   3 |     2 |        -5 |    7 |    8 |    1 |      1.2
+   4 |     2 |        -5 |   12 |   11 |    1 |      1.2
+   5 |     2 |        -5 |   16 |    9 |    1 |      1.2
+   6 |     3 |        -5 |    3 |    7 |    1 |      2.2
+   7 |     3 |        -5 |    6 |    4 |    1 |      2.2
+   8 |     3 |        -5 |    8 |   10 |    1 |      2.2
+   9 |     3 |        -5 |   15 |   16 |    1 |      2.2
+  10 |     3 |        -5 |   17 |   13 |    1 |      2.2
+(10 rows)
+
+/* --withpointsdd3 */
+SELECT * FROM pgr_withPointsDD(
+  $$SELECT id, source, target, cost, reverse_cost FROM edges ORDER BY id$$,
+  $$SELECT pid, edge_id, fraction, side from pointsOfInterest$$,
+  ARRAY[-3, 16], 3.3, 'r');
+ seq | depth | start_vid | node | edge | cost | agg_cost
+-----+-------+-----------+------+------+------+----------
+   1 |     0 |        -3 |   -3 |   -1 |    0 |        0
+   2 |     1 |        -3 |   12 |   12 |  0.4 |      0.4
+   3 |     2 |        -3 |   17 |   13 |    1 |      1.4
+   4 |     3 |        -3 |   16 |   15 |    1 |      2.4
+   5 |     0 |        16 |   16 |   -1 |    0 |        0
+   6 |     1 |        16 |   11 |    9 |    1 |        1
+   7 |     1 |        16 |   15 |   16 |    1 |        1
+   8 |     1 |        16 |   17 |   15 |    1 |        1
+   9 |     2 |        16 |    7 |    8 |    1 |        2
+  10 |     2 |        16 |   10 |    3 |    1 |        2
+  11 |     2 |        16 |   12 |   11 |    1 |        2
+  12 |     3 |        16 |    3 |    7 |    1 |        3
+  13 |     3 |        16 |    6 |    2 |    1 |        3
+  14 |     3 |        16 |    8 |   10 |    1 |        3
+(14 rows)
+
+/* --withpointsdd4 */
+SELECT seq, node, edge, cost, agg_cost FROM pgr_withPointsDD(
+  $$SELECT id, source, target, cost, reverse_cost FROM edges ORDER BY id$$,
+  $$SELECT pid, edge_id, fraction, side from pointsOfInterest$$,
+  -5, 2.3, 'r');
+ seq | node | edge | cost | agg_cost
+-----+------+------+------+----------
+   1 |   -5 |   -1 |    0 |        0
+   2 |   11 |    5 |  0.2 |      0.2
+   3 |    7 |    8 |    1 |      1.2
+   4 |   12 |   11 |    1 |      1.2
+   5 |   16 |    9 |    1 |      1.2
+   6 |    3 |    7 |    1 |      2.2
+   7 |    6 |    4 |    1 |      2.2
+   8 |    8 |   10 |    1 |      2.2
+   9 |   15 |   16 |    1 |      2.2
+  10 |   17 |   13 |    1 |      2.2
+(10 rows)
+
+/* --withpointsdd5 */
 ROLLBACK;
 ROLLBACK

docqueries/src/migration.test.sql

@@ -244,3 +244,25 @@ SELECT seq, path_seq, node, edge, cost, agg_cost FROM pgr_aStar(
   $$SELECT id, source, target, cost, reverse_cost, x1, y1, x2, y2 FROM edges$$,
   6, 10);
 /* --astar5 */
+/* --withpointsdd1 */
+SELECT * FROM pgr_withPointsDD(
+  $$SELECT id, source, target, cost, reverse_cost FROM edges ORDER BY id$$,
+  $$SELECT pid, edge_id, fraction, side from pointsOfInterest$$,
+  -5, 2.3,
+  driving_side => 'r');
+/* --withpointsdd2 */
+SELECT * FROM pgr_withPointsDD(
+  $$SELECT id, source, target, cost, reverse_cost FROM edges ORDER BY id$$,
+  $$SELECT pid, edge_id, fraction, side from pointsOfInterest$$,
+  -5, 2.3, 'r');
+/* --withpointsdd3 */
+SELECT * FROM pgr_withPointsDD(
+  $$SELECT id, source, target, cost, reverse_cost FROM edges ORDER BY id$$,
+  $$SELECT pid, edge_id, fraction, side from pointsOfInterest$$,
+  ARRAY[-3, 16], 3.3, 'r');
+/* --withpointsdd4 */
+SELECT seq, node, edge, cost, agg_cost FROM pgr_withPointsDD(
+  $$SELECT id, source, target, cost, reverse_cost FROM edges ORDER BY id$$,
+  $$SELECT pid, edge_id, fraction, side from pointsOfInterest$$,
+  -5, 2.3, 'r');
+/* --withpointsdd5 */