Example uses of ST_Line_SubString

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

diff --git a/doc/reference.xml b/doc/reference.xml
index 1703058c443af5ca9bf2e6fc3f85cfe179c4ab66..0fccb47288882695622d71f1459e965251cb684c 100644 (file)
--- a/doc/reference.xml
+++ b/doc/reference.xml
@@ -2457,13 +2457,14 @@ z' = z </programlisting> This method is a subcase of the 3D method
         </varlistentry>
 
         <varlistentry id="line_substring">
-          <term>ST_Line_substring(linestring geometry, startfraction float8, endfraction float8)</term>
+          <term>ST_Line_Substring(linestring geometry, startfraction float8, endfraction float8)</term>
 
           <listitem>
             <para>Return a linestring being a substring of the input one
             starting and ending at the given fractions of total 2d length.
             Second and third arguments are float8 values between 0 and
-            1.</para>
+            1. This only works with LINESTRINGs.  
+                       To use with contiguous MULTILINESTRINGs use in conjunction with ST_LineMerge.</para>
 
             <para>If 'start' and 'end' have the same value this is equivalent
             to <link
@@ -2480,6 +2481,36 @@ z' = z </programlisting> This method is a subcase of the 3D method
             </note>
 
             <para>Availability: 1.1.0</para>
+                       <programlisting>
+--Return the approximate 1/3 mid-range part of a linestring    
+SELECT ST_Line_SubString(ST_LineFromText('LINESTRING(748130.463 2919491.079,
+       747979.395 2919630.415,
+       747895.989829177 2919705.518)'), 0.333, 0.666); 
+       
+--The below example simulates a while loop in 
+--SQL using PostgreSQL generate_series() to cut all 
+--linestrings in a table to 100 unit segments
+-- of which no segment is longer than 100 units
+-- units are measured in the SRID units of measurement
+-- It also assumes all geometries are LINESTRING or contiguous MULTILINESTRING 
+--and no geometry is longer than 100 units*10000
+--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,
+  CASE
+    WHEN 100.00*(n+1) &lt; length THEN 100.00*(n+1)/length
+    ELSE 1
+  END) As the_geom
+FROM 
+  (SELECT sometable.field1, sometable.field2, 
+  ST_LineMerge(sometable.the_geom) AS the_geom,
+  ST_Length(sometable.the_geom) As length 
+  FROM sometable 
+  ) AS t 
+CROSS JOIN generate_series(0,10000) AS n 
+WHERE n*100.00/length &lt; 1;
+                       </programlisting>
           </listitem>
         </varlistentry>