From: Sandro Santilli <strk@keybit.net>
Date: Wed, 18 Jan 2012 14:17:11 +0000 (+0000)
Subject: Add ST_Summary(geography), "G" flag (#1277), document (#649)
X-Git-Tag: 2.0.0alpha1~14
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=c7983112e05f9a01020042b4d7a7a924ca89e12e;p=postgis

Add ST_Summary(geography), "G" flag (#1277), document (#649)

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

diff --git a/doc/reference_accessor.xml b/doc/reference_accessor.xml
index bba4c8812..5050070f2 100644
--- a/doc/reference_accessor.xml
+++ b/doc/reference_accessor.xml
@@ -2078,8 +2078,8 @@ SELECT ST_AsEWKT(ST_StartPoint('LINESTRING(0 1 1, 0 2 2)'::geometry));
 	  <refnamediv>
 		<refname>ST_Summary</refname>
 
-		<refpurpose>Returns a text summary of the contents of the
-		<varname>ST_Geometry</varname>.
+		<refpurpose>
+Returns a text summary of the contents of the geometry.
 		</refpurpose>
 	  </refnamediv>
 
@@ -2087,9 +2087,12 @@ SELECT ST_AsEWKT(ST_StartPoint('LINESTRING(0 1 1, 0 2 2)'::geometry));
 		<funcsynopsis>
 		  <funcprototype>
 			<funcdef>text <function>ST_Summary</function></funcdef>
-
 			<paramdef><type>geometry </type> <parameter>g</parameter></paramdef>
 		  </funcprototype>
+		  <funcprototype>
+			<funcdef>text <function>ST_Summary</function></funcdef>
+			<paramdef><type>geography </type> <parameter>g</parameter></paramdef>
+		  </funcprototype>
 		</funcsynopsis>
 	  </refsynopsisdiv>
 
@@ -2097,34 +2100,46 @@ SELECT ST_AsEWKT(ST_StartPoint('LINESTRING(0 1 1, 0 2 2)'::geometry));
 		<title>Description</title>
 
 		<para>Returns a text summary of the contents of the geometry.</para>
+
+		<para>
+                  Flags shown square brackets after the geometry type
+                  have the following meaning:
+                  <itemizedlist>
+                    <listitem><para>M: has M ordinate</para></listitem>
+                    <listitem><para>Z: has Z ordinate</para></listitem>
+                    <listitem><para>B: has a cached bounding box</para></listitem>
+                    <listitem><para>G: is geodetic (geography)</para></listitem>
+                  </itemizedlist>
+                </para>
+
 		<para>&Z_support;</para>
+		<para>Availability: 1.2.2 - 2.0.0 added support for geography</para>
 
 	  </refsection>
 
 	  <refsection>
 		<title>Examples</title>
 
-		<programlisting>SELECT ST_Summary(ST_GeomFromText('LINESTRING(0 0, 1 1)')) As good_line,
-	ST_Summary(ST_GeomFromText('POLYGON((0 0, 1 1, 1 2, 1 1, 0 0))')) As bad_poly
---results
-	  good_line       |        bad_poly
-----------------------+-------------------------
-					  |
-Line[B] with 2 points : Polygon[B] with 1 rings
-					  :    ring 0 has 5 points
-					  :
+		<programlisting>
+=# SELECT ST_Summary(ST_GeomFromText('LINESTRING(0 0, 1 1)')) as geom,
+        ST_Summary(ST_GeogFromText('POLYGON((0 0, 1 1, 1 2, 1 1, 0 0))')) geog;
+            geom             |          geog    
+-----------------------------+--------------------------
+ LineString[B] with 2 points | Polygon[BG] with 1 rings
+                             :    ring 0 has 5 points
+                             :
+(1 row)
 
---3d polygon
-SELECT ST_Summary(ST_GeomFromEWKT('LINESTRING(0 0 1, 1 1 1)')) As good_line,
-	ST_Summary(ST_GeomFromEWKT('POLYGON((0 0 1, 1 1 2, 1 2 3, 1 1 1, 0 0 1))')) As poly
 
---results
-	  good_line       |        poly
-----------------------+-------------------------
-					  |
-Line[ZB] with 2 points : Polygon[ZB] with 1 rings
-					  :    ring 0 has 5 points
-					  :
+=# SELECT ST_Summary(ST_GeogFromText('LINESTRING(0 0 1, 1 1 1)')) As geog_line,
+        ST_Summary(ST_GeomFromText('POLYGON((0 0 1, 1 1 2, 1 2 3, 1 1 1, 0 0 1))')) As geom_poly;
+;
+           geog_line           |        geom_poly
+-------------------------------+--------------------------
+ LineString[ZBG] with 2 points | Polygon[ZB] with 1 rings
+                               :    ring 0 has 5 points
+                               :
+(1 row)
 
 </programlisting>
 	  </refsection>
@@ -2133,10 +2148,20 @@ Line[ZB] with 2 points : Polygon[ZB] with 1 rings
 		<title>See Also</title>
 
 		<para>
+<xref linkend="PostGIS_DropBBox" />,
+<xref linkend="PostGIS_AddBBox" />,
+<xref linkend="ST_Force_3DM" />,
+<xref linkend="ST_Force_3DZ" />,
+<xref linkend="ST_Force_2D" />,
+<xref linkend="geography" />
+		</para>
+
+		<para>
+<xref linkend="ST_IsValid" />,
 <xref linkend="ST_IsValid" />,
 <xref linkend="ST_IsValidReason" />,
 <xref linkend="ST_IsValidDetail" />
-</para>
+		</para>
 	  </refsection>
 	</refentry>
 
diff --git a/liblwgeom/lwgeom_debug.c b/liblwgeom/lwgeom_debug.c
index a01f113b4..d612e5e43 100644
--- a/liblwgeom/lwgeom_debug.c
+++ b/liblwgeom/lwgeom_debug.c
@@ -17,15 +17,16 @@
 #include <string.h>
 
 /* Place to hold the ZM string used in other summaries */
-static char tflags[4];
+static char tflags[5];
 
 static char *
-lwtype_zmflags(uint8_t flags)
+lwtype_flagchars(uint8_t flags)
 {
 	int flagno = 0;
 	if ( FLAGS_GET_Z(flags) ) tflags[flagno++] = 'Z';
 	if ( FLAGS_GET_M(flags) ) tflags[flagno++] = 'M';
 	if ( FLAGS_GET_BBOX(flags) ) tflags[flagno++] = 'B';
+	if ( FLAGS_GET_GEODETIC(flags) ) tflags[flagno++] = 'G';
 	tflags[flagno] = '\0';
 
 	LWDEBUGF(4, "Flags: %s - returning %p", flags, tflags);
@@ -41,7 +42,7 @@ lwpoint_summary(LWPOINT *point, int offset)
 {
 	char *result;
 	char *pad="";
-	char *zmflags = lwtype_zmflags(point->flags);
+	char *zmflags = lwtype_flagchars(point->flags);
 
 	result = (char *)lwalloc(128+offset);
 
@@ -56,7 +57,7 @@ lwline_summary(LWLINE *line, int offset)
 {
 	char *result;
 	char *pad="";
-	char *zmflags = lwtype_zmflags(line->flags);
+	char *zmflags = lwtype_flagchars(line->flags);
 
 	result = (char *)lwalloc(128+offset);
 
@@ -76,7 +77,7 @@ lwcollection_summary(LWCOLLECTION *col, int offset)
 	char *tmp;
 	int i;
 	char *pad="";
-	char *zmflags = lwtype_zmflags(col->flags);
+	char *zmflags = lwtype_flagchars(col->flags);
 
 	LWDEBUG(2, "lwcollection_summary called");
 
@@ -112,7 +113,7 @@ lwpoly_summary(LWPOLY *poly, int offset)
 	char *result;
 	int i;
 	char *pad="";
-	char *zmflags = lwtype_zmflags(poly->flags);
+	char *zmflags = lwtype_flagchars(poly->flags);
 
 	LWDEBUG(2, "lwpoly_summary called");
 
diff --git a/postgis/geography.sql.in.c b/postgis/geography.sql.in.c
index 1b28539eb..0c782e97b 100644
--- a/postgis/geography.sql.in.c
+++ b/postgis/geography.sql.in.c
@@ -703,6 +703,12 @@ CREATE OR REPLACE FUNCTION GeometryType(geography)
 	AS 'MODULE_PATHNAME', 'LWGEOM_getTYPE'
 	LANGUAGE 'C' IMMUTABLE STRICT;
 
+-- Availability: 2.0.0
+CREATE OR REPLACE FUNCTION ST_Summary(geography)
+	RETURNS text
+	AS 'MODULE_PATHNAME', 'LWGEOM_summary'
+	LANGUAGE 'C' IMMUTABLE STRICT;
+
 	
 -----------------------------------------------------------------------------