GSoC 2023: Yige Huang Week 7

doc/driving_distance/pgr_drivingDistance.rst

@@ -122,7 +122,7 @@ Driving distance optional parameters
    * - ``equicost``
      - ``BOOLEAN``
      - ``true``
-     - * When ``true`` the node will only appear in the closest ``from_v``
+     - * When ``true`` the node will only appear in the closest ``start_vid``
          list.
        * When ``false`` which resembles several calls using the single starting
          point signatures. Tie brakes are arbitrary.

doc/withPoints/pgr_withPointsDD.rst

@@ -26,6 +26,13 @@
 
 .. rubric:: Availability
 
+* Version 3.6.0
+
+  * Standarizing output columns to |result-bfs|
+
+    * ``pgr_withPointsDD`` (`Single vertex`_) added ``depth`` and ``start_vid`` column.
+    * ``pgr_withPointsDD`` (`Multiple vertices`_) added ``depth`` column.
+
 * Version 2.2.0
 
   * New **proposed** function
@@ -45,12 +52,12 @@ Signatures
 .. admonition:: \ \
    :class: signatures
 
-   | pgr_withPointsDD(`Edges SQL`_, `Points SQL`_, **root vid**, **distance**, [**options A**])
-   | pgr_withPointsDD(`Edges SQL`_, `Points SQL`_, **root vids**, **distance**, [**options B**])
-   | **options A:** ``[directed, driving_side, details]``
-   | **options B:** ``[directed, driving_side, details, equicost]``
+   | pgr_withPointsDD(`Edges SQL`_, `Points SQL`_, **root vid**, **distance**, **driving side**, [**options A**])
+   | pgr_withPointsDD(`Edges SQL`_, `Points SQL`_, **root vids**, **distance**, **driving side**, [**options B**])
+   | **options A:** ``[directed, details]``
+   | **options B:** ``[directed, details, equicost]``
 
-   | RETURNS SET OF |result-generic-no-seq|
+   | RETURNS SET OF |result-bfs|
    | OR EMPTY SET
 
 .. index::
@@ -62,10 +69,10 @@ Single vertex
 .. admonition:: \ \
    :class: signatures
 
-   | pgr_withPointsDD(`Edges SQL`_, `Points SQL`_, **root vid**, **distance**, [**options**])
-   | **options:** ``[directed, driving_side, details]``
+   | pgr_withPointsDD(`Edges SQL`_, `Points SQL`_, **root vid**, **distance**, **driving side**, [**options**])
+   | **options:** ``[directed, details]``
 
-   | RETURNS SET OF |result-1-1-no-seq|
+   | RETURNS SET OF |result-bfs|
    | OR EMPTY SET
 
 :Example: Right side driving topology, from point :math:`1` within a distance of
@@ -84,10 +91,10 @@ Multiple vertices
 .. admonition:: \ \
    :class: signatures
 
-   | pgr_withPointsDD(`Edges SQL`_, `Points SQL`_, **root vids**, **distance**, [**options**])
-   | **options:** ``[directed, driving_side, details, equicost]``
+   | pgr_withPointsDD(`Edges SQL`_, `Points SQL`_, **root vids**, **distance**, **driving side**, [**options**])
+   | **options:** ``[directed, details, equicost]``
 
-   | RETURNS SET OF |result-m-1-no-seq|
+   | RETURNS SET OF |result-bfs|
    | OR EMPTY SET
 
 :Example: From point :math:`1` and vertex :math:`16` within a distance of
@@ -123,13 +130,23 @@ Parameters
      - ``ARRAY`` [**ANY-INTEGER**]
      - Array of identifiers of the root vertices.
 
-
        - Negative values represent a point
        - :math:`0` values are ignored
        - For optimization purposes, any duplicated value is ignored.
    * - **distance**
      - ``FLOAT``
      - 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:
+
+       - ``r``, ``R`` for right driving side,
+       - ``l``, ``L`` for left driving side.
+       - ``b``, ``B`` for both.
+
+Where:
+
+:ANY-INTEGER: SMALLINT, INTEGER, BIGINT
 
 Optional parameters
 ...............................................................................
@@ -141,9 +158,21 @@ Optional parameters
 With points optional parameters
 ...............................................................................
 
-.. include:: withPoints-family.rst
-   :start-after: withPoints_optionals_start
-   :end-before: withPoints_optionals_end
+.. list-table::
+   :width: 81
+   :widths: 14 7 7 60
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Default
+     - Description
+   * - ``details``
+     - ``BOOLEAN``
+     - ``false``
+     - - When ``true`` the results will include the points that are in the path.
+       - When ``false`` the results will not include the points that are in the
+         path.
 
 Driving distance optional parameters
 ...............................................................................
@@ -172,43 +201,9 @@ Points SQL
 Result Columns
 -------------------------------------------------------------------------------
 
-RETURNS SET OF |result-generic-no-seq|
-
-.. list-table::
-   :width: 81
-   :widths: auto
-   :header-rows: 1
-
-   * - Parameter
-     - Type
-     - Description
-   * - ``seq``
-     - ``BIGINT``
-     - Sequential value starting from :math:`1`.
-   * - ``[start_vid]``
-     - ``BIGINT``
-     - Identifier of the root vertex.
-
-   * - ``node``
-     - ``BIGINT``
-     - Identifier of ``node`` within the limits from ``from_v``.
-   * - ``edge``
-     - ``BIGINT``
-     - Identifier of the ``edge`` used to arrive to ``node``.
-
-       - :math:`0` when ``node`` = ``from_v``.
-
-   * - ``cost``
-     - ``FLOAT``
-     - Cost to traverse ``edge``.
-   * - ``agg_cost``
-     - ``FLOAT``
-     - Aggregate cost from ``from_v`` to ``node``.
-
-Where:
-
-:ANY-INTEGER: SMALLINT, INTEGER, BIGINT
-:ANY-NUMERIC: SMALLINT, INTEGER, BIGINT, REAL, FLOAT, NUMERIC
+.. include:: BFS-category.rst
+   :start-after: mst-bfs-dfs-dd-result-columns-start
+   :end-before: mst-bfs-dfs-dd-result-columns-end
 
 Additional Examples
 -------------------------------------------------------------------------------

docqueries/withPoints/doc-pgr_withPointsDD.result

@@ -8,63 +8,57 @@ SET
 SELECT * FROM pgr_withPointsDD(
   'SELECT id, source, target, cost, reverse_cost FROM edges ORDER BY id',
   'SELECT pid, edge_id, fraction, side from pointsOfInterest',
-  -1, 3.3,
-  driving_side => 'r',
+  -1, 3.3, 'r',
   details => true);
-WARNING:  pgr_withpointsdd(text,text,bigint,double precision,boolean,character,boolean) is been deprecated
- seq | node | edge | cost | agg_cost
------+------+------+------+----------
-   1 |   -1 |   -1 |    0 |        0
-   2 |    5 |    1 |  0.4 |      0.4
-   3 |    6 |    1 |    1 |      1.4
-   4 |   -6 |    4 |  0.7 |      2.1
-   5 |    7 |    4 |  0.3 |      2.4
+ seq | depth | start_vid | node | edge | cost | agg_cost
+-----+-------+-----------+------+------+------+----------
+   1 |     0 |        -1 |   -1 |   -1 |    0 |        0
+   2 |     1 |        -1 |    5 |    1 |  0.4 |      0.4
+   3 |     2 |        -1 |    6 |    1 |    1 |      1.4
+   4 |     3 |        -1 |   -6 |    4 |  0.7 |      2.1
+   5 |     4 |        -1 |    7 |    4 |  0.3 |      2.4
 (5 rows)
 
 /* -- q3 */
 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[-1, 16], 3.3,
-  driving_side => 'l',
+  ARRAY[-1, 16], 3.3, 'l',
   equicost => true);
-WARNING:  pgr_withpointsdd(text,text,anyarray,double precision,boolean,character,boolean,boolean) is been deprecated
- seq | start_vid | node | edge | cost | agg_cost
------+-----------+------+------+------+----------
-   1 |        -1 |   -1 |   -1 |    0 |        0
-   2 |        -1 |    6 |    1 |  0.6 |      0.6
-   3 |        -1 |    7 |    4 |    1 |      1.6
-   4 |        -1 |    5 |    1 |    1 |      1.6
-   5 |        -1 |    3 |    7 |    1 |      2.6
-   6 |        -1 |    8 |   10 |    1 |      2.6
-   7 |        16 |   16 |   -1 |    0 |        0
-   8 |        16 |   11 |    9 |    1 |        1
-   9 |        16 |   15 |   16 |    1 |        1
-  10 |        16 |   17 |   15 |    1 |        1
-  11 |        16 |   10 |    3 |    1 |        2
-  12 |        16 |   12 |   11 |    1 |        2
+ seq | depth | start_vid | node | edge | cost | agg_cost
+-----+-------+-----------+------+------+------+----------
+   1 |     0 |        -1 |   -1 |   -1 |    0 |        0
+   2 |     1 |        -1 |    6 |    1 |  0.6 |      0.6
+   3 |     2 |        -1 |    7 |    4 |    1 |      1.6
+   4 |     2 |        -1 |    5 |    1 |    1 |      1.6
+   5 |     3 |        -1 |    3 |    7 |    1 |      2.6
+   6 |     3 |        -1 |    8 |   10 |    1 |      2.6
+   7 |     0 |        16 |   16 |   -1 |    0 |        0
+   8 |     1 |        16 |   11 |    9 |    1 |        1
+   9 |     1 |        16 |   15 |   16 |    1 |        1
+  10 |     1 |        16 |   17 |   15 |    1 |        1
+  11 |     2 |        16 |   10 |    3 |    1 |        2
+  12 |     2 |        16 |   12 |   11 |    1 |        2
 (12 rows)
 
 /* -- q4 */
 SELECT * FROM pgr_withPointsDD(
   'SELECT id, source, target, cost, reverse_cost FROM edges ORDER BY id',
   'SELECT pid, edge_id, fraction, side from pointsOfInterest',
-  -1, 3.3,
-  driving_side => 'b',
+  -1, 3.3, 'b',
   details => true);
-WARNING:  pgr_withpointsdd(text,text,bigint,double precision,boolean,character,boolean) is been deprecated
- seq | node | edge | cost | agg_cost
------+------+------+------+----------
-   1 |   -1 |   -1 |    0 |        0
-   2 |    5 |    1 |  0.4 |      0.4
-   3 |    6 |    1 |  0.6 |      0.6
-   4 |   -6 |    4 |  0.7 |      1.3
-   5 |    7 |    4 |  0.3 |      1.6
-   6 |    3 |    7 |    1 |      2.6
-   7 |    8 |   10 |    1 |      2.6
-   8 |   11 |    8 |    1 |      2.6
-   9 |   -3 |   12 |  0.6 |      3.2
-  10 |   -4 |    6 |  0.7 |      3.3
+ seq | depth | start_vid | node | edge | cost | agg_cost
+-----+-------+-----------+------+------+------+----------
+   1 |     0 |        -1 |   -1 |   -1 |    0 |        0
+   2 |     1 |        -1 |    5 |    1 |  0.4 |      0.4
+   3 |     1 |        -1 |    6 |    1 |  0.6 |      0.6
+   4 |     2 |        -1 |   -6 |    4 |  0.7 |      1.3
+   5 |     3 |        -1 |    7 |    4 |  0.3 |      1.6
+   6 |     4 |        -1 |    3 |    7 |    1 |      2.6
+   7 |     4 |        -1 |    8 |   10 |    1 |      2.6
+   8 |     4 |        -1 |   11 |    8 |    1 |      2.6
+   9 |     5 |        -1 |   -3 |   12 |  0.6 |      3.2
+  10 |     5 |        -1 |   -4 |    6 |  0.7 |      3.3
 (10 rows)
 
 /* -- q5 */
@@ -76,33 +70,31 @@ SELECT * FROM pgr_withPointsDD(
         (SELECT ST_POINT(2.9, 1.8)),
         0.5, cap => 2)
   $p$,
-  ARRAY[-1, -2], 2.3,
-  driving_side => 'r',
+  ARRAY[-1, -2], 2.3, 'r',
   details => true);
-WARNING:  pgr_withpointsdd(text,text,anyarray,double precision,boolean,character,boolean,boolean) is been deprecated
- seq | start_vid | node | edge | cost | agg_cost
------+-----------+------+------+------+----------
-   1 |        -1 |   -1 |   -1 |    0 |        0
-   2 |        -1 |   11 |    5 |  0.2 |      0.2
-   3 |        -1 |    7 |    8 |    1 |      1.2
-   4 |        -1 |   12 |   11 |    1 |      1.2
-   5 |        -1 |   16 |    9 |    1 |      1.2
-   6 |        -1 |   -2 |    8 |  0.9 |      2.1
-   7 |        -1 |    3 |    7 |    1 |      2.2
-   8 |        -1 |    6 |    4 |    1 |      2.2
-   9 |        -1 |    8 |   10 |    1 |      2.2
-  10 |        -1 |   15 |   16 |    1 |      2.2
-  11 |        -1 |   17 |   13 |    1 |      2.2
-  12 |        -2 |   -2 |   -1 |    0 |        0
-  13 |        -2 |   11 |    8 |  0.1 |      0.1
-  14 |        -2 |    7 |    8 |    1 |      1.1
-  15 |        -2 |   12 |   11 |    1 |      1.1
-  16 |        -2 |   16 |    9 |    1 |      1.1
-  17 |        -2 |    3 |    7 |    1 |      2.1
-  18 |        -2 |    6 |    4 |    1 |      2.1
-  19 |        -2 |    8 |   10 |    1 |      2.1
-  20 |        -2 |   15 |   16 |    1 |      2.1
-  21 |        -2 |   17 |   13 |    1 |      2.1
+ seq | depth | start_vid | node | edge | cost | agg_cost
+-----+-------+-----------+------+------+------+----------
+   1 |     0 |        -1 |   -1 |   -1 |    0 |        0
+   2 |     1 |        -1 |   11 |    5 |  0.2 |      0.2
+   3 |     2 |        -1 |    7 |    8 |    1 |      1.2
+   4 |     2 |        -1 |   12 |   11 |    1 |      1.2
+   5 |     2 |        -1 |   16 |    9 |    1 |      1.2
+   6 |     3 |        -1 |   -2 |    8 |  0.9 |      2.1
+   7 |     3 |        -1 |    3 |    7 |    1 |      2.2
+   8 |     3 |        -1 |    6 |    4 |    1 |      2.2
+   9 |     3 |        -1 |    8 |   10 |    1 |      2.2
+  10 |     3 |        -1 |   15 |   16 |    1 |      2.2
+  11 |     3 |        -1 |   17 |   13 |    1 |      2.2
+  12 |     0 |        -2 |   -2 |   -1 |    0 |        0
+  13 |     1 |        -2 |   11 |    8 |  0.1 |      0.1
+  14 |     2 |        -2 |    7 |    8 |    1 |      1.1
+  15 |     2 |        -2 |   12 |   11 |    1 |      1.1
+  16 |     2 |        -2 |   16 |    9 |    1 |      1.1
+  17 |     3 |        -2 |    3 |    7 |    1 |      2.1
+  18 |     3 |        -2 |    6 |    4 |    1 |      2.1
+  19 |     3 |        -2 |    8 |   10 |    1 |      2.1
+  20 |     3 |        -2 |   15 |   16 |    1 |      2.1
+  21 |     3 |        -2 |   17 |   13 |    1 |      2.1
 (21 rows)
 
 /* -- q6 */

docqueries/withPoints/doc-pgr_withPointsDD.test.sql

@@ -5,22 +5,19 @@ SET extra_float_digits=-3;
 SELECT * FROM pgr_withPointsDD(
   'SELECT id, source, target, cost, reverse_cost FROM edges ORDER BY id',
   'SELECT pid, edge_id, fraction, side from pointsOfInterest',
-  -1, 3.3,
-  driving_side => 'r',
+  -1, 3.3, 'r',
   details => true);
 /* -- q3 */
 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[-1, 16], 3.3,
-  driving_side => 'l',
+  ARRAY[-1, 16], 3.3, 'l',
   equicost => true);
 /* -- q4 */
 SELECT * FROM pgr_withPointsDD(
   'SELECT id, source, target, cost, reverse_cost FROM edges ORDER BY id',
   'SELECT pid, edge_id, fraction, side from pointsOfInterest',
-  -1, 3.3,
-  driving_side => 'b',
+  -1, 3.3, 'b',
   details => true);
 /* -- q5 */
 SELECT * FROM pgr_withPointsDD(
@@ -31,7 +28,6 @@ SELECT * FROM pgr_withPointsDD(
         (SELECT ST_POINT(2.9, 1.8)),
         0.5, cap => 2)
   $p$,
-  ARRAY[-1, -2], 2.3,
-  driving_side => 'r',
+  ARRAY[-1, -2], 2.3, 'r',
   details => true);
 /* -- q6 */

include/drivers/driving_distance/withPoints_dd_driver.h

@@ -54,7 +54,7 @@ typedef struct MST_rt MST_rt;
 extern "C" {
 #endif
 
-    void do_withPointsDD(
+    void pgr_do_withPointsDD(
             Edge_t*,          size_t,
             Point_on_edge_t*, size_t,
             Edge_t*,          size_t,
@@ -68,6 +68,7 @@ extern "C" {
             char**, char**, char **);
 
 
+    /* TODO remove on V4 */
     void do_pgr_many_withPointsDD(
             Edge_t*,          size_t,
             Point_on_edge_t*, size_t,