Document ST_IsValidDetail

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

diff --git a/doc/reference_accessor.xml b/doc/reference_accessor.xml
index ede5458d50a3a77cae2b9eff7fe52ceb1a85fe5a..ba3be94a5f4edebcdee9e8ef2f7701ebd8aeba77 100644 (file)
--- a/doc/reference_accessor.xml
+++ b/doc/reference_accessor.xml
@@ -953,7 +953,12 @@ NOTICE:  Self-intersection at or near point 0 0
          <refsection>
                <title>See Also</title>
 
-               <para><xref linkend="ST_IsSimple" />, <xref linkend="ST_IsValidReason" />, <xref linkend="ST_Summary" /></para>
+               <para>
+<xref linkend="ST_IsSimple" />,
+<xref linkend="ST_IsValidReason" />,
+<xref linkend="ST_IsValidDetail" />,
+<xref linkend="ST_Summary" />
+</para>
          </refsection>
        </refentry>
 
@@ -1032,6 +1037,84 @@ SELECT ST_IsValidReason('LINESTRING(220227 150406,2220227 150407,222020 150410)'
          </refsection>
        </refentry>
 
+       <refentry id="ST_IsValidDetail">
+         <refnamediv>
+               <refname>ST_IsValidDetail</refname>
+
+               <refpurpose>Returns a valid_detail (valid,reason,location) row stating if a geometry is valid or not and if not valid, a reason why and a location where.</refpurpose>
+         </refnamediv>
+
+         <refsynopsisdiv>
+               <funcsynopsis>
+                 <funcprototype>
+                       <funcdef>valid_detail <function>ST_IsValidDetail</function></funcdef>
+                       <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
+                 </funcprototype>
+               </funcsynopsis>
+         </refsynopsisdiv>
+
+         <refsection>
+               <title>Description</title>
+
+               <para>Returns a valid_detail row, formed by a boolean (valid) stating if a geometry is valid, a varchar (reason) stating a reason why it is invalid and a geometry (location) pointing out where it is invalid.</para>
+
+               <para>Useful to substitute and improve the combination of ST_IsValid and ST_IsValidReason to generate a detailed report of invalid geometries.</para>
+               <para>Availability: 2.0.0 - requires GEOS &gt;= 3.3.0.</para>
+
+         </refsection>
+
+
+         <refsection>
+               <title>Examples</title>
+
+               <programlisting>
+--First 3 Rejects from a successful quintuplet experiment
+SELECT gid, reason(ST_IsValidDetail(the_geom)), ST_AsText(location(ST_IsValidDetail(the_geom))) as location 
+FROM
+(SELECT ST_MakePolygon(ST_ExteriorRing(e.buff), ST_Accum(f.line)) As the_geom, gid
+FROM (SELECT ST_Buffer(ST_MakePoint(x1*10,y1), z1) As buff, x1*10 + y1*100 + z1*1000 As gid
+       FROM generate_series(-4,6) x1
+       CROSS JOIN generate_series(2,5) y1
+       CROSS JOIN generate_series(1,8) z1
+       WHERE x1 &gt; y1*0.5 AND z1 &lt; x1*y1) As e
+       INNER JOIN (SELECT ST_Translate(ST_ExteriorRing(ST_Buffer(ST_MakePoint(x1*10,y1), z1)),y1*1, z1*2) As line
+       FROM generate_series(-3,6) x1
+       CROSS JOIN generate_series(2,5) y1
+       CROSS JOIN generate_series(1,10) z1
+       WHERE x1 &gt; y1*0.75 AND z1 &lt; x1*y1) As f
+ON (ST_Area(e.buff) &gt; 78 AND ST_Contains(e.buff, f.line))
+GROUP BY gid, e.buff) As quintuplet_experiment
+WHERE ST_IsValid(the_geom) = false
+ORDER BY gid
+LIMIT 3;
+
+ gid  |      reason       |  location
+------+-------------------+-------------
+ 5330 | Self-intersection | POINT(32 5)
+ 5340 | Self-intersection | POINT(42 5)
+ 5350 | Self-intersection | POINT(52 5)
+
+ --simple example
+SELECT * FROM ST_IsValidDetail('LINESTRING(220227 150406,2220227 150407,222020 150410)');
+
+ valid | reason | location
+-------+--------+----------
+ t     |        |
+
+               </programlisting>
+         </refsection>
+
+         <!-- Optionally add a "See Also" section -->
+         <refsection>
+               <title>See Also</title>
+
+               <para>
+<xref linkend="ST_IsValid" />,
+<xref linkend="ST_IsValidReason" />
+</para>
+         </refsection>
+       </refentry>
+
        <refentry id="ST_M">
          <refnamediv>
                <refname>ST_M</refname>
@@ -1637,7 +1720,11 @@ Line[ZB] with 2 points : Polygon[ZB] with 1 rings
          <refsection>
                <title>See Also</title>
 
-               <para><xref linkend="ST_IsValid" />, <xref linkend="ST_IsValidReason" /></para>
+               <para>
+<xref linkend="ST_IsValid" />,
+<xref linkend="ST_IsValidReason" />,
+<xref linkend="ST_IsValidDetail" />
+</para>
          </refsection>
        </refentry>