Modifying withpointsdd

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/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/src/pgRouting-introduction.rst

@@ -74,7 +74,8 @@ Rajat Shinde,
 Regina Obe,
 Shobhit Chaurasia,
 Swapnil Joshi,
-Virginia Vergara
+Virginia Vergara,
+Yige Huang
 
 
 And all the people that give us a little of their time making comments, finding
@@ -150,7 +151,8 @@ Sylvain Housseman,
 Sylvain Pasche,
 Veenit Kumar,
 Vidhan Jain,
-Virginia Vergara
+Virginia Vergara,
+Yige Huang
 
 Corporate Sponsors (in alphabetical order)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

doc/withPoints/pgr_withPointsDD.rst

@@ -26,6 +26,24 @@
 
 .. rubric:: Availability
 
+* Version 3.6.0
+
+  * New proposed signatures:
+
+    * ``pgr_withPointsDD`` (`Single vertex`_)
+    * ``pgr_withPointsDD`` (`Multiple vertices`_)
+
+  * Deprecated signatures:
+
+    * ``pgr_withpointsdd(text,text,bigint,double precision,boolean,character,boolean)``
+    * ``pgr_withpointsdd(text,text,anyarray,double precision,boolean,character,boolean,boolean)``
+
+  * 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 +63,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 +80,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 +102,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 +141,28 @@ 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.
+
+       - Valid values differ for directed and undirected graphs:
+
+         - In directed graphs: [``r``, ``R``, ``l``, ``L``].
+         - In undirected graphs: [``b``, ``B``].
+
+Where:
+
+:ANY-INTEGER: SMALLINT, INTEGER, BIGINT
 
 Optional parameters
 ...............................................................................
@@ -141,9 +174,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 +217,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/src/migration.result

@@ -785,5 +785,88 @@ SELECT seq, path_seq, node, edge, cost, agg_cost FROM pgr_bdAstar(
 (6 rows)
 
 /* --bdastar5 */
+/* --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