Deprecate non-CamelCase linear referencing function (#1994)

- ST_Line_Interpolate_Point renamed to ST_LineInterpolatePoint
- ST_Line_Substring renamed to ST_LineSubstring
- ST_Line_Locate_Point renamed to ST_LineLocatePoint

Tests updated to use the new signature, docs updated to show the
new signature and report deprecations

git-svn-id: http://svn.osgeo.org/postgis/trunk@11190 b70326c6-7e19-0410-871a-916f4a2858ee

diff --git a/NEWS b/NEWS
index 36e047629fff8099748fb81599bf418b8a41c522..650e034394438980492034a0754b9d1708adee25 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -27,6 +27,9 @@ PostGIS 2.1.0
            ST_Raster2WorldCoordY renamed to ST_RasterToWorldCoord,
            ST_RasterToWorldCoordX and ST_RasterToWorldCoordY
   - ST_Estimated_Extent renamed to ST_EstimatedExtent
+  - ST_Line_Interpolate_Point renamed to ST_LineInterpolatePoint
+  - ST_Line_Substring renamed to ST_LineSubstring
+  - ST_Line_Locate_Point renamed to ST_LineLocatePoint
   - ST_MapAlgebraFctNgb and 1 and 2 raster variants of ST_MapAlgebraFct.
     Use ST_MapAlgebra instead
   - 1 and 2 raster variants of ST_MapAlgebraExpr.

diff --git a/doc/reference_lrs.xml b/doc/reference_lrs.xml
index 1cfaa6c9971f13ca13a7505c49a941bb781f5e74..cac98ee8e92ca4ab4cd32444fe0bfdbef4048cb4 100644 (file)
--- a/doc/reference_lrs.xml
+++ b/doc/reference_lrs.xml
@@ -4,7 +4,7 @@
        
                <refentry id="ST_Line_Interpolate_Point">
                  <refnamediv>
-                       <refname>ST_Line_Interpolate_Point</refname>
+                       <refname>ST_LineInterpolatePoint</refname>
 
                        <refpurpose>Returns a point interpolated along a line. Second argument is a float8 between 0 and 1
                        representing fraction of total length of linestring the point has to be located.</refpurpose>
@@ -13,7 +13,7 @@
                  <refsynopsisdiv>
                        <funcsynopsis>
                          <funcprototype>
-                               <funcdef>geometry <function>ST_Line_Interpolate_Point</function></funcdef>
+                               <funcdef>geometry <function>ST_LineInterpolatePoint</function></funcdef>
                                <paramdef><type>geometry </type> <parameter>a_linestring</parameter></paramdef>
                                <paramdef><type>float </type> <parameter>a_fraction</parameter></paramdef>
                          </funcprototype>
@@ -36,6 +36,7 @@
                          0.0.</para>
                        </note>
                        <para>Availability: 0.8.2, Z and M supported added in 1.1.1</para>
+      <para>Changed: 2.1.0. Up to 2.0.x this was called ST_LineInterpolatePoint.</para>
                        <para>&Z_support;</para>
                  </refsection>
 
@@ -88,7 +89,7 @@ FROM (SELECT ST_GeomFromText('LINESTRING(1 2, 4 5, 6 7)') As the_line) As foo;
 
                <refentry id="ST_Line_Locate_Point">
                  <refnamediv>
-                       <refname>ST_Line_Locate_Point</refname>
+                       <refname>ST_LineLocatePoint</refname>
 
                        <refpurpose>Returns a float between 0 and 1 representing the location of
                        the closest point on LineString to the given Point, as a fraction
@@ -98,7 +99,7 @@ FROM (SELECT ST_GeomFromText('LINESTRING(1 2, 4 5, 6 7)') As the_line) As foo;
                  <refsynopsisdiv>
                        <funcsynopsis>
                          <funcprototype>
-                               <funcdef>float <function>ST_Line_Locate_Point</function></funcdef>
+                               <funcdef>float <function>ST_LineLocatePoint</function></funcdef>
                                <paramdef><type>geometry </type> <parameter>a_linestring</parameter></paramdef>
                                <paramdef><type>geometry </type> <parameter>a_point</parameter></paramdef>
                          </funcprototype>
@@ -118,6 +119,7 @@ FROM (SELECT ST_GeomFromText('LINESTRING(1 2, 4 5, 6 7)') As the_line) As foo;
                        <para>This is useful for approximating numbers of addresses</para>
 
                        <para>Availability: 1.1.0</para>
+      <para>Changed: 2.1.0. Up to 2.0.x this was called ST_Line_Locate_Point.</para>
                  </refsection>
 
 
@@ -133,7 +135,7 @@ FROM (SELECT ST_GeomFromText('LINESTRING(1 2, 4 5, 6 7)') As the_line) As foo;
 SELECT ST_AsText(house_loc) As as_text_house_loc,
        startstreet_num +
                CAST( (endstreet_num - startstreet_num)
-                       * ST_Line_Locate_Point(street_line, house_loc) As integer) As street_num
+                       * ST_LineLocatePoint(street_line, house_loc) As integer) As street_num
 FROM
 (SELECT ST_GeomFromText('LINESTRING(1 2, 3 4)') As street_line,
        ST_MakePoint(x*1.01,y*1.03) As house_loc, 10 As startstreet_num,
@@ -149,7 +151,7 @@ WHERE ST_DWithin(street_line, house_loc, 0.2);
  POINT(3.03 4.12)  |         20
 
  --find closest point on a line to a point or other geometry
- SELECT ST_AsText(ST_Line_Interpolate_Point(foo.the_line, ST_Line_Locate_Point(foo.the_line, ST_GeomFromText('POINT(4 3)'))))
+ SELECT ST_AsText(ST_Line_Interpolate_Point(foo.the_line, ST_LineLocatePoint(foo.the_line, ST_GeomFromText('POINT(4 3)'))))
 FROM (SELECT ST_GeomFromText('LINESTRING(1 2, 4 5, 6 7)') As the_line) As foo;
    st_astext
 ----------------
@@ -168,7 +170,7 @@ FROM (SELECT ST_GeomFromText('LINESTRING(1 2, 4 5, 6 7)') As the_line) As foo;
 
                <refentry id="ST_Line_Substring">
                  <refnamediv>
-                       <refname>ST_Line_Substring</refname>
+                       <refname>ST_LineSubstring</refname>
 
                        <refpurpose>Return a linestring being a substring of the input one
                        starting and ending at the given fractions of total 2d length.
@@ -179,7 +181,7 @@ FROM (SELECT ST_GeomFromText('LINESTRING(1 2, 4 5, 6 7)') As the_line) As foo;
                  <refsynopsisdiv>
                        <funcsynopsis>
                          <funcprototype>
-                               <funcdef>geometry <function>ST_Line_Substring</function></funcdef>
+                               <funcdef>geometry <function>ST_LineSubstring</function></funcdef>
                                <paramdef><type>geometry </type> <parameter>a_linestring</parameter></paramdef>
                                <paramdef><type>float </type> <parameter>startfraction</parameter></paramdef>
                                <paramdef><type>float </type> <parameter>endfraction</parameter></paramdef>
@@ -209,6 +211,7 @@ FROM (SELECT ST_GeomFromText('LINESTRING(1 2, 4 5, 6 7)') As the_line) As foo;
                        </note>
 
                        <para>Availability: 1.1.0, Z and M supported added in 1.1.1</para>
+    <para>Changed: 2.1.0. Up to 2.0.x this was called ST_LineSubstring.</para>
                        <para>&Z_support;</para>
                  </refsection>
 
@@ -240,7 +243,7 @@ LINESTRING(69.2846934853974 94.2846934853974,100 125,111.700356260683 140.210463
 --for better performance you can reduce the 10000
 --to match max number of segments you expect
 
-SELECT field1, field2, ST_Line_Substring(the_geom, 100.00*n/length,
+SELECT field1, field2, ST_LineSubstring(the_geom, 100.00*n/length,
   CASE
        WHEN 100.00*(n+1) &lt; length THEN 100.00*(n+1)/length
        ELSE 1

diff --git a/postgis/postgis.sql.in b/postgis/postgis.sql.in
index ad3e5f1ffa36026e948544b4ef4ad0507982b3ce..d4344b18a7fb85d91030638584b2230d37a87448 100644 (file)
--- a/postgis/postgis.sql.in
+++ b/postgis/postgis.sql.in
@@ -2692,30 +2692,50 @@ CREATE OR REPLACE FUNCTION ST_Segmentize(geometry, float8)
 ---------------------------------------------------------------
 
 -- Availability: 1.2.2
+-- Deprecation in 2.1.0 
 CREATE OR REPLACE FUNCTION ST_line_interpolate_point(geometry, float8)
        RETURNS geometry
        AS 'MODULE_PATHNAME', 'LWGEOM_line_interpolate_point'
        LANGUAGE 'c' IMMUTABLE STRICT;
 
+-- Availability: 2.1.0
+CREATE OR REPLACE FUNCTION ST_LineInterpolatePoint(geometry, float8)
+       RETURNS geometry
+       AS 'MODULE_PATHNAME', 'LWGEOM_line_interpolate_point'
+       LANGUAGE 'c' IMMUTABLE STRICT;
+
 -- Availability: 1.2.2
+-- Deprecation in 2.1.0 
 CREATE OR REPLACE FUNCTION ST_line_substring(geometry, float8, float8)
        RETURNS geometry
        AS 'MODULE_PATHNAME', 'LWGEOM_line_substring'
        LANGUAGE 'c' IMMUTABLE STRICT;
 
+-- Availability: 2.1.0
+CREATE OR REPLACE FUNCTION ST_LineSubstring(geometry, float8, float8)
+       RETURNS geometry
+       AS 'MODULE_PATHNAME', 'LWGEOM_line_substring'
+       LANGUAGE 'c' IMMUTABLE STRICT;
+
 -- Availability: 1.2.2
+-- Deprecation in 2.1.0 
 CREATE OR REPLACE FUNCTION ST_line_locate_point(geom1 geometry, geom2 geometry)
        RETURNS float8
        AS 'MODULE_PATHNAME', 'LWGEOM_line_locate_point'
        LANGUAGE 'c' IMMUTABLE STRICT;
 
+-- Availability: 2.1.0
+CREATE OR REPLACE FUNCTION ST_LineLocatePoint(geom1 geometry, geom2 geometry)
+       RETURNS float8
+       AS 'MODULE_PATHNAME', 'LWGEOM_line_locate_point'
+       LANGUAGE 'c' IMMUTABLE STRICT;
+
 -- Availability: 1.2.2
 CREATE OR REPLACE FUNCTION ST_locate_between_measures(geometry, float8, float8)
        RETURNS geometry
        AS 'MODULE_PATHNAME', 'LWGEOM_locate_between_m'
        LANGUAGE 'c' IMMUTABLE STRICT;
 
-
 -- Availability: 1.2.2
 CREATE OR REPLACE FUNCTION ST_locate_along_measure(geometry, float8)
        RETURNS geometry

diff --git a/regress/regress_lrs.sql b/regress/regress_lrs.sql
index 2f088ea2be8e81a3832fde0d05ee304572f4f7f9..761af96d335aa39c15797d3686926603e93c6309 100644 (file)
--- a/regress/regress_lrs.sql
+++ b/regress/regress_lrs.sql
@@ -26,36 +26,36 @@ select 'LINEZM_6', ST_AsText(ST_LocateBetween('LINESTRING(0 10 10 40, 10 0 0 0)'
 
 --- line_locate_point
 
-SELECT 'line_locate_point_1', ST_line_locate_point('LINESTRING(709243.393033887 163969.752725768,708943.240904444 163974.593889146,708675.634380651 163981.832927298)', 'POINT(705780 15883)');
+SELECT 'line_locate_point_1', ST_LineLocatePoint('LINESTRING(709243.393033887 163969.752725768,708943.240904444 163974.593889146,708675.634380651 163981.832927298)', 'POINT(705780 15883)');
 
 --- postgis-users/2006-January/010613.html
-select 'line_locate_point_2', ST_line_locate_point(ST_geomfromtext('LINESTRING(-1953743.873 471070.784,-1953735.105 471075.419,-1953720.034 471081.649)', 6269), ST_geomfromtext('POINT(-1953720.034 471081.649)', 6269));
-select 'line_locate_point_3', ST_line_locate_point(ST_geomfromtext('LINESTRING(-1953743.873 471070.784,-1953735.105 471075.419,-1953720.034 471081.649)', 6269), ST_geomfromtext('POINT(-1953743.873 471070.784)', 6269));
+select 'line_locate_point_2', ST_LineLocatePoint(ST_geomfromtext('LINESTRING(-1953743.873 471070.784,-1953735.105 471075.419,-1953720.034 471081.649)', 6269), ST_geomfromtext('POINT(-1953720.034 471081.649)', 6269));
+select 'line_locate_point_3', ST_LineLocatePoint(ST_geomfromtext('LINESTRING(-1953743.873 471070.784,-1953735.105 471075.419,-1953720.034 471081.649)', 6269), ST_geomfromtext('POINT(-1953743.873 471070.784)', 6269));
 --- http://trac.osgeo.org/postgis/ticket/1772#comment:2
-select 'line_locate_point_4', ST_line_locate_point('LINESTRING(0 1, 0 1, 0 1)', 'POINT(0 1)');
+select 'line_locate_point_4', ST_LineLocatePoint('LINESTRING(0 1, 0 1, 0 1)', 'POINT(0 1)');
 
 --- line_substring / line_interpolate_point
 
 --- postgis-devel/2006-January/001951.html
 with substr as (
-  select ST_line_substring(ST_geomfromewkt('SRID=4326;LINESTRING(0 0 0 0, 1 1 1 1, 2 2 2 2, 3 3 3 3, 4 4 4 4)'), 0.5, 0.8) as ln
+  select ST_LineSubstring(ST_geomfromewkt('SRID=4326;LINESTRING(0 0 0 0, 1 1 1 1, 2 2 2 2, 3 3 3 3, 4 4 4 4)'), 0.5, 0.8) as ln
 )      
 select 'line_substring_1', ST_SRID(ln), ST_AsText(ln) from substr;
 
-select 'line_substring_2', ST_AsText(ST_line_substring('LINESTRING(0 0 0 0, 1 1 1 1, 2 2 2 2, 3 3 3 3, 4 4 4 4)', 0.5, 0.75));
-select 'line_substring_3', ST_AsText(ST_line_substring('LINESTRING(0 0, 1 1, 2 2)', 0, 0.5));
-select 'line_substring_4', ST_AsText(ST_line_substring('LINESTRING(0 0, 1 1, 2 2)', 0.5, 1));
-select 'line_substring_5', ST_AsText(ST_line_substring('LINESTRING(0 0, 2 2)', 0.5, 1));
-select 'line_substring_6', ST_AsText(ST_line_substring('LINESTRING(0 0, 2 2)', 0, 0.5));
-select 'line_substring_7', ST_AsText(ST_line_substring('LINESTRING(0 0, 4 4)', .25, 0.5));
-select 'line_substring_8', ST_AsText(ST_line_substring('LINESTRINGM(0 0 0, 4 4 4)', .25, 0.5));
-select 'line_substring_9', ST_AsText(ST_line_substring('LINESTRINGM(0 0 4, 4 4 0)', .25, 0.5));
-select 'line_substring_10', ST_AsText(ST_line_substring('LINESTRING(0 0 4, 4 4 0)', .25, 0.5));
+select 'line_substring_2', ST_AsText(ST_LineSubstring('LINESTRING(0 0 0 0, 1 1 1 1, 2 2 2 2, 3 3 3 3, 4 4 4 4)', 0.5, 0.75));
+select 'line_substring_3', ST_AsText(ST_LineSubstring('LINESTRING(0 0, 1 1, 2 2)', 0, 0.5));
+select 'line_substring_4', ST_AsText(ST_LineSubstring('LINESTRING(0 0, 1 1, 2 2)', 0.5, 1));
+select 'line_substring_5', ST_AsText(ST_LineSubstring('LINESTRING(0 0, 2 2)', 0.5, 1));
+select 'line_substring_6', ST_AsText(ST_LineSubstring('LINESTRING(0 0, 2 2)', 0, 0.5));
+select 'line_substring_7', ST_AsText(ST_LineSubstring('LINESTRING(0 0, 4 4)', .25, 0.5));
+select 'line_substring_8', ST_AsText(ST_LineSubstring('LINESTRINGM(0 0 0, 4 4 4)', .25, 0.5));
+select 'line_substring_9', ST_AsText(ST_LineSubstring('LINESTRINGM(0 0 4, 4 4 0)', .25, 0.5));
+select 'line_substring_10', ST_AsText(ST_LineSubstring('LINESTRING(0 0 4, 4 4 0)', .25, 0.5));
 
-select 'line_substring_11', ST_AsText(ST_line_substring('LINESTRING(0 0, 1 1)', 0, 0));
-select 'line_substring_12', ST_AsText(ST_line_substring('LINESTRING(0 0 10, 1 1 5)', 0.5, .5));
+select 'line_substring_11', ST_AsText(ST_LineSubstring('LINESTRING(0 0, 1 1)', 0, 0));
+select 'line_substring_12', ST_AsText(ST_LineSubstring('LINESTRING(0 0 10, 1 1 5)', 0.5, .5));
 
 --- line_interpolate_point
 
-select 'line_interpolate_point', ST_AsText(ST_line_interpolate_point('LINESTRING(0 0, 1 1)', 0));
-select 'line_interpolate_point', ST_AsText(ST_line_interpolate_point('LINESTRING(0 0 10, 1 1 5)', 0.5));
+select 'line_interpolate_point', ST_AsText(ST_LineInterpolatePoint('LINESTRING(0 0, 1 1)', 0));
+select 'line_interpolate_point', ST_AsText(ST_LineInterpolatePoint('LINESTRING(0 0 10, 1 1 5)', 0.5));