amend ST_Length to include use_spheroid proto and amend examples to state new default...

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

diff --git a/doc/reference.xml b/doc/reference.xml
index b368575ed1db0f649e128d62a7c9018cf8c9232b..9b9d75400f68416b3a16183c331666a9775f4e28 100644 (file)
--- a/doc/reference.xml
+++ b/doc/reference.xml
@@ -10797,7 +10797,7 @@ SELECT ST_Intersects('POINT(0 0)'::geometry, 'LINESTRING ( 0 0, 0 2 )'::geometry
                <refnamediv>
                  <refname>ST_Length</refname>
 
-                 <refpurpose>Returns the 2d length of the geometry if it is a linestring or multilinestring. geometry are in units of spatial reference and geography are in meters</refpurpose>
+                 <refpurpose>Returns the 2d length of the geometry if it is a linestring or multilinestring. geometry are in units of spatial reference and geography are in meters (default spheroid)</refpurpose>
                </refnamediv>
                <refsynopsisdiv>
                  <funcsynopsis>
@@ -10809,18 +10809,24 @@ SELECT ST_Intersects('POINT(0 0)'::geometry, 'LINESTRING ( 0 0, 0 2 )'::geometry
                          <funcdef>float <function>ST_Length</function></funcdef>
                                <paramdef><type>geography </type><parameter>gg</parameter></paramdef>
                        </funcprototype>
+                       <funcprototype>
+                         <funcdef>float <function>ST_Length</function></funcdef>
+                               <paramdef><type>geography </type><parameter>gg</parameter></paramdef>
+                               <paramdef><type>boolean </type><parameter>use_spheroid</parameter></paramdef>
+                       </funcprototype>
                  </funcsynopsis>
                </refsynopsisdiv>
                <refsection>
                        <title>Description</title>
 
-                       <para>For geometry: Returns the 2D length of the geometry if it is a linestring, multilinestring, ST_Curve, ST_MultiCurve.  0 is returned for
+                       <para>For geometry: Returns the cartesian 2D length of the geometry if it is a linestring, multilinestring, ST_Curve, ST_MultiCurve.  0 is returned for
                                areal geometries.  For areal geometries use ST_Perimeter. Geometry: Measurements are in the units of the
                                spatial reference system of the geometry. Geography: Units are in meters and also acts as a Perimeter function for areal geogs.</para>
 
                        <para>Currently for geometry this is an alias for ST_Length2D, but this may change to support higher dimensions.</para>
                        <note><para>Currently applying this to a MULTI/POLYGON of type geography will give you the perimeter of the POLYGON/MULTIPOLYGON.  This is not the 
                        case with the geometry implementation.</para></note>
+                       <note><para>For geography measurement defaults spheroid measurement.  To use the faster less accurate sphere use ST_Length(gg,false);</para></note>
                        <para><inlinemediaobject>
                                <imageobject>
                                  <imagedata fileref="images/check.png" />
@@ -10868,11 +10874,13 @@ st_length
                        <para>Return length of WGS 84 geography line</para>
                        <programlisting>
                        -- default calculation is using a sphere rather than spheroid
-SELECT ST_Length(ST_GeographyFromText(
-'SRID=4326;LINESTRING(-72.1260 42.45, -72.1240 42.45666, -72.123 42.1546)'));
-st_length
----------
-34346.2060960738
+SELECT ST_Length(the_geog) As length_spheroid,  ST_Length(the_geog,false) As length_sphere
+FROM (SELECT ST_GeographyFromText(
+'SRID=4326;LINESTRING(-72.1260 42.45, -72.1240 42.45666, -72.123 42.1546)') As the_geog)
+ As foo;
+ length_spheroid  |  length_sphere
+------------------+------------------
+ 34310.5703627305 | 34346.2060960742
 (1 row)
                        </programlisting>
                  </refsection>