[postgis-commits] svn - r2838 - trunk/doc

[postgis-commits at postgis.refractions.net]

Author: robe
Date: 2008-07-11 03:48:46 -0700 (Fri, 11 Jul 2008)
New Revision: 2838

Modified:
   trunk/doc/reference.xml
Log:
Example uses of ST_Line_SubString

Modified: trunk/doc/reference.xml
===================================================================
--- trunk/doc/reference.xml	2008-07-10 13:16:20 UTC (rev 2837)
+++ trunk/doc/reference.xml	2008-07-11 10:48:46 UTC (rev 2838)
@@ -2457,13 +2457,14 @@
         </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 @@
             </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>