From: Regina Obe <lr@pcorp.us>
Date: Wed, 4 Nov 2009 18:59:30 +0000 (+0000)
Subject: amend ST_Length to include use_spheroid proto and amend examples to state new default... 
X-Git-Tag: 1.5.0b1~296
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=bf3dd2ed07a58f10fffad504a10bd75f75cdab7a;p=postgis

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

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 b368575ed..9b9d75400 100644
--- 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>