new function with points via (closes #2251) (#2252)

* [pgtap] organizing tests for via functions * [withPointsVia][pgtap] tests that need to pass * [withPointsVia][C/C++] adding code for new function * [withPointsVia][sql] adding code for new function * [withPointsVia][queries] adding queries for the documentation * [Via][queries] standarizng queries for via functions * [withPointsVia][queries] adding documentation for new function * [Via][doc] standarizing Via functions documentation * [doc] updating notes and news * [doc] ignoring links not exisiting yet
pgRouting · Feb 21, 2022 · f382bb6 · f382bb6
1 parent c585905
commit f382bb6
Show file tree

Hide file tree

Showing 40 changed files with 1,734 additions and 387 deletions.
diff --git a/NEWS b/NEWS
@@ -3,21 +3,25 @@ pgRouting 3.4.0 Release Notes
 
 **New proposed functions**
 
+* With points
+
+  * ``pgr_withPointsVia`` (One Via)
+
 * Turn Restrictions
 
-  * pgr_trspVia
+  * ``pgr_trspVia``
 
     * ``pgr_trspVia`` (One Via)
 
-  * pgr_trsp
+  * ``pgr_trsp``
 
     * ``pgr_trsp`` (One to One)
     * ``pgr_trsp`` (One to Many)
     * ``pgr_trsp`` (Many to One)
     * ``pgr_trsp`` (Many to Many)
     * ``pgr_trsp`` (Combinations)
 
-  * pgr_trsp_withPoints
+  * ``pgr_trsp_withPoints``
 
     * ``pgr_trsp_withPoints`` (One to One)
     * ``pgr_trsp_withPoints`` (One to Many)

diff --git a/doc/conf.py.in b/doc/conf.py.in
@@ -95,11 +95,6 @@ locale_dirs = ['@CMAKE_SOURCE_DIR@/locale/']
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 exclude_patterns = [
-    'doc/build',
-    'pgr_withPointsVia.rst',
-    'maxFlowApplications.rst',
-    '*/notUsed',
-    'tools/template'
     ]
 
 #    'src/pickDeliver/doc/pgr_withPointsVia.rst',
@@ -321,7 +316,10 @@ linkcheck_ignore = [
     'https://docs.pgrouting.org/latest/en/TRSP-family.html',
     'https://docs.pgrouting.org/latest/en/pgr_trsp_withPoints.html',
     'https://docs.pgrouting.org/latest/en/pgr_trspVia.html',
-    'https://docs.pgrouting.org/3.4/en/pgr_trspVia.html',
+    'https://docs.pgrouting.org/latest/en/pgr_withPointsVia.html',
+    'https://docs.pgrouting.org/latest/en/via-category.html',
+    'https://docs.pgrouting.org/3.4/en/pgr_withPointsVia.html',
+    'https://docs.pgrouting.org/3.4/en/via-category.html',
 
 
 

diff --git a/doc/dijkstra/pgr_dijkstraVia.rst b/doc/dijkstra/pgr_dijkstraVia.rst
@@ -44,14 +44,19 @@ a list of vertices.
   * New **proposed** function
 
 
+|
+
 Description
 -------------------------------------------------------------------------------
 
 Given a list of vertices and a graph, this function is equivalent to finding the
-shortest path between :math:`vertex_i` and :math:`vertex_{i+1}` for all :math:`i < size\_of(vertex_via)`.
+shortest path between :math:`vertex_i` and :math:`vertex_{i+1}` for all :math:`i
+< size\_of(vertex_via)`.
 
 The paths represents the sections of the route.
 
+|
+
 Signatures
 -------------------------------------------------------------------------------
 
@@ -60,93 +65,105 @@ Signatures
 .. index::
     single: dijkstraVia - Proposed on 2.2
 
-.. code-block:: none
-
-    pgr_dijkstraVia(edges_sql, via_vertices [, directed] [, strict] [, U_turn_on_edge])
-    RETURNS SET OF (seq, path_pid, path_seq, start_vid, end_vid,
-        node, edge, cost, agg_cost, route_agg_cost)
-    OR EMPTY SET
-
-.. rubric:: Using default
-
-.. code-block:: none
+.. parsed-literal::
 
-    pgr_dijkstraVia(edges_sql, via_vertices)
+    pgr_dijkstraVia(`Edges SQL`_, **via vertices**
+               [, directed] [, strict] [, U_turn_on_edge])
     RETURNS SET OF (seq, path_pid, path_seq, start_vid, end_vid,
-        node, edge, cost, agg_cost, route_agg_cost)
+                    node, edge, cost, agg_cost, route_agg_cost)
     OR EMPTY SET
 
-:Example: Find the route that visits the vertices :math:`\{ 1, 3, 9\}`  in that order
-
-.. literalinclude:: doc-pgr_dijkstraVia.queries
-    :start-after: -- q00
-    :end-before: -- q01
+|
 
 One Via
 ...............................................................................
 
-.. code-block:: none
+.. parsed-literal::
 
-    pgr_dijkstraVia(edges_sql, via_vertices [, directed] [, strict] [, U_turn_on_edge])
+    pgr_dijkstraVia(`Edges SQL`_, **via vertices**
+               [, directed] [, strict] [, U_turn_on_edge])
     RETURNS SET OF (seq, path_pid, path_seq, start_vid, end_vid,
-        node, edge, cost, agg_cost, route_agg_cost)
+                    node, edge, cost, agg_cost, route_agg_cost)
     OR EMPTY SET
 
-:Example: Find the route that visits the vertices :math:`\{ 1, 3, 9\}` in that order on an **undirected** graph, avoiding U-turns when possible
+:Example: Find the route that visits the vertices :math:`\{ 1, 7, 10\}` in that
+          order on an **directed** graph.
 
 .. literalinclude:: doc-pgr_dijkstraVia.queries
     :start-after: -- q01
     :end-before: -- q1
 
+|
+
 Parameters
 -------------------------------------------------------------------------------
 
-.. include:: pgRouting-concepts.rst
-    :start-after: pgr_dijkstra_via_parameters_start
-    :end-before: pgr_dijkstra_via_parameters_end
+.. parameters_start
+
+.. list-table::
+   :width: 81
+   :widths: 14 20 7 40
+   :header-rows: 1
+
+   * - Parameter
+     - Type
+     - Default
+     - Description
+   * - `Edges SQL`_
+     - ``TEXT``
+     -
+     - SQL query as described.
+   * - **via vertices**
+     - ``ARRAY[`` **ANY-INTEGER** ``]``
+     -
+     - Array of ordered vertices identifiers that are going to be visited.
+   * - ``directed``
+     - ``BOOLEAN``
+     - ``true``
+     - - When ``true`` Graph is considered `Directed`
+       - When ``false`` the graph is considered as Undirected.
+
+.. parameters_end
+
+|
+
+Via optional parameters
+...............................................................................
+
+.. include:: via-category.rst
+    :start-after: via_opt_parameters_start
+    :end-before: via_opt_parameters_end
+
+|
 
 Inner query
 -------------------------------------------------------------------------------
 
+|
+
 Edges SQL
 ...............................................................................
 
 .. include:: pgRouting-concepts.rst
     :start-after: basic_edges_sql_start
     :end-before: basic_edges_sql_end
 
+|
+
 Return Columns
 -------------------------------------------------------------------------------
 
-.. via result columns start
-
-Returns set of ``(seq, path_pid, path_seq, start_vid, end_vid, node, edge, cost, agg_cost, route_agg_cost)``
-
-================== ============= =================================================
-Column             Type          Description
-================== ============= =================================================
-``seq``            ``BIGINT``    Sequential value starting from 1.
-``path_pid``       ``BIGINT``    Identifier of the path.
-``path_seq``       ``BIGINT``    Sequential value starting from 1 for the path.
-``start_vid``      ``BIGINT``    Identifier of the starting vertex of the path.
-``end_vid``        ``BIGINT``    Identifier of the ending vertex of the path.
-``node``           ``BIGINT``    Identifier of the node in the path from start_vid to end_vid.
-``edge``           ``BIGINT``    Identifier of the edge used to go from node to the next node in the path sequence.
-
-                                 * -1 for the last node of the path.
-                                 * -2 for the last node of the route.
+.. include:: via-category.rst
+    :start-after: result columns start
+    :end-before: result columns end
 
-``cost``           ``FLOAT``     Cost to traverse from ``node`` using ``edge`` to the next node in the route sequence.
-``agg_cost``       ``FLOAT``     Total cost from ``start_vid`` to ``end_vid`` of the path.
-``route_agg_cost`` ``FLOAT``     Total cost from ``start_vid`` of ``seq = 1`` to ``end_vid`` of the current ``seq``.
-================== ============= =================================================
-
-.. via result columns end
+|
 
 Additional Examples
 -------------------------------------------------------------------------------
 
-:Example 1: Find the route that visits the vertices :math:`\{1, 5, 3, 9, 4\}` in that order
+:Example 1: Find the route that visits the vertices :math:`\{1, 5, 7, 10, 4\}`
+            in that order
 
 .. literalinclude:: doc-pgr_dijkstraVia.queries
     :start-after: -- q1
@@ -158,7 +175,8 @@ Additional Examples
     :start-after: -- q2
     :end-before: -- q3
 
-:Example 3: What's the route's aggregate cost of the route at the end of the third path?
+:Example 3: What's the route's aggregate cost of the route at the end of the
+            third path?
 
 .. literalinclude:: doc-pgr_dijkstraVia.queries
     :start-after: -- q3
@@ -170,22 +188,25 @@ Additional Examples
     :start-after: -- q4
     :end-before: -- q5
 
-:Example 5: What are the aggregate costs of the route when the visited vertices are reached?
+:Example 5: What are the aggregate costs of the route when the visited vertices
+            are reached?
 
 .. literalinclude:: doc-pgr_dijkstraVia.queries
     :start-after: -- q5
     :end-before: -- q6
 
-:Example 6: Show the route's seq and aggregate cost and a status of "passes in front" or "visits" node :math:`9`
+:Example 6: Show the route's seq and aggregate cost and a status of "passes in
+            front" or "visits"
 
 .. literalinclude:: doc-pgr_dijkstraVia.queries
     :start-after: -- q6
 
 See Also
 -------------------------------------------------------------------------------
 
-* https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm
+* :doc:`via-category`.
 * :doc:`sampledata` network.
+* https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm
 
 .. rubric:: Indices and tables
 

diff --git a/doc/src/CMakeLists.txt b/doc/src/CMakeLists.txt
@@ -12,6 +12,7 @@ SET(LOCAL_FILES
     support.rst
     cost-category.rst
     costMatrix-category.rst
+    via-category.rst
     )
 
 foreach (f ${LOCAL_FILES})

diff --git a/doc/src/pgRouting-concepts.rst b/doc/src/pgRouting-concepts.rst
@@ -504,10 +504,12 @@ Points SQL
    * - ``pid``
      - **ANY-INTEGER**
      - **value**
-     - (optional) Identifier of the point.
+     - Identifier of the point.
 
-       * If column present, it can not be NULL.
-       * If column not present, a sequential negative **value** will be given
+       * Use with positive value, as internally will be converted to negative
+         value
+       * If column is present, it can not be NULL.
+       * If column is not present, a sequential negative **value** will be given
          automatically.
    * - ``edge_id``
      - **ANY-INTEGER**
@@ -585,6 +587,11 @@ Parameters
 
 .. pgr_dijkstra_via_parameters_end
 
+.. rubric:: Parameters for the Via functions:
+
+* :doc:`pgr_withPointsVia`
+
+
 |
 
 Return columns

diff --git a/doc/src/proposed.rst b/doc/src/proposed.rst
@@ -115,6 +115,12 @@ Proposed Functions
    :start-after: index proposed from here
    :end-before: index proposed to here
 
+:doc:`via-category`
+
+.. include:: via-category.rst
+   :start-after: proposed start
+   :end-before: proposed end
+
 .. toctree::
     :hidden:
 

diff --git a/doc/src/release_notes.rst b/doc/src/release_notes.rst
@@ -39,21 +39,25 @@ pgRouting 3.4.0 Release Notes
 
 .. rubric:: New proposed functions
 
+* With points
+
+  * ``pgr_withPointsVia`` (One Via)
+
 * Turn Restrictions
 
-  * pgr_trspVia
+  * ``pgr_trspVia``
 
     * ``pgr_trspVia`` (One Via)
 
-  * pgr_trsp
+  * ``pgr_trsp``
 
     * ``pgr_trsp`` (One to One)
     * ``pgr_trsp`` (One to Many)
     * ``pgr_trsp`` (Many to One)
     * ``pgr_trsp`` (Many to Many)
     * ``pgr_trsp`` (Combinations)
 
-  * pgr_trsp_withPoints
+  * ``pgr_trsp_withPoints``
 
     * ``pgr_trsp_withPoints`` (One to One)
     * ``pgr_trsp_withPoints`` (One to Many)

diff --git a/doc/src/routingFunctions.rst b/doc/src/routingFunctions.rst
@@ -142,6 +142,12 @@ Functions by categories
    :start-after: index from here
    :end-before: index to here
 
+:doc:`via-category`
+
+.. include:: via-category.rst
+   :start-after: from here
+   :end-before: to here
+
 ..  to-here
 
 .. toctree::
@@ -169,6 +175,7 @@ Functions by categories
     costMatrix-category
     drivingDistance-category
     spanningTree-family
+    via-category
 
 See Also
 -------------------------------------------------------------------------------