[postgis-tickets] [SCM] PostGIS branch master updated. 3.1.0rc1-129-gbb76b0c

[git at osgeo.org]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "PostGIS".

The branch, master has been updated
       via  bb76b0c7a4744e71d70470ddf3d54bbc8b02f64b (commit)
      from  6316fa32e8e8d027d6cf09f683dabef024450403 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit bb76b0c7a4744e71d70470ddf3d54bbc8b02f64b
Author: Martin Davis <mtnclimb at gmail.com>
Date:   Fri Apr 9 12:41:46 2021 -0700

    Improve doc for ST_CollectionHomogenize

diff --git a/doc/reference_editor.xml b/doc/reference_editor.xml
index 77c0fea..f34c5ec 100644
--- a/doc/reference_editor.xml
+++ b/doc/reference_editor.xml
@@ -142,64 +142,88 @@ MULTILINESTRING((0 0, 1 1), (2 2, 3 3))
 		</refsection>
 	</refentry>
 
-		<refentry id="ST_CollectionHomogenize">
-			<refnamediv>
-				<refname>ST_CollectionHomogenize</refname>
-
-				<refpurpose>
-	Given a geometry collection, return the "simplest" representation of the contents.
-				</refpurpose>
-			</refnamediv>
-
-			<refsynopsisdiv>
-				<funcsynopsis>
-				  <funcprototype>
-					<funcdef>geometry <function>ST_CollectionHomogenize</function></funcdef>
-					<paramdef><type>geometry </type> <parameter>collection</parameter></paramdef>
-				  </funcprototype>
-				</funcsynopsis>
-			</refsynopsisdiv>
-
-			<refsection>
-				<title>Description</title>
+    <refentry id="ST_CollectionHomogenize">
+        <refnamediv>
+            <refname>ST_CollectionHomogenize</refname>
 
-				<para>
-					Given a geometry collection, returns the "simplest" representation of the contents.  Singletons will be returned as singletons.  Collections that are homogeneous will be returned as the appropriate multi-type.
-				</para>
+            <refpurpose>
+Returns the simplest representation of a geometry collection.
+            </refpurpose>
+        </refnamediv>
 
-				<warning><para>When specifying 3 == POLYGON a multipolygon is returned even when the edges are shared.  This results in an invalid multipolygon for many cases
-			such as applying this function on an <xref linkend="ST_Split" /> result.</para></warning>
+        <refsynopsisdiv>
+            <funcsynopsis>
+                <funcprototype>
+                <funcdef>geometry <function>ST_CollectionHomogenize</function></funcdef>
+                <paramdef><type>geometry </type> <parameter>collection</parameter></paramdef>
+                </funcprototype>
+            </funcsynopsis>
+        </refsynopsisdiv>
 
+        <refsection>
+            <title>Description</title>
 
-				<para>Availability: 2.0.0</para>
+            <para>
+            Given a geometry collection, returns the "simplest" representation of the contents.
+            Collections containing a single atomic element are returned as that element.
+            Homogeneous collections are returned as the appropriate multi-geometry.
+            Atomic geometries are returned unchanged.
+            </para>
 
-			</refsection>
+            <warning><para>This function does not ensure that the result is valid.
+            In particular, a collection containing adjacent or overlapping Polygons
+            will create an invalid MultiPolygon.
+            This situation can be checked with <xref linkend="ST_IsValid" /> and repaired with <xref linkend="ST_MakeValid" />.
+            </para></warning>
 
-			<refsection>
-				<title>Examples</title>
+            <para>Availability: 2.0.0</para>
 
-				<programlisting>
+        </refsection>
+
+        <refsection>
+            <title>Examples</title>
+<para>Single-element collection converted to an atomic geometry</para>
+<programlisting>
   SELECT ST_AsText(ST_CollectionHomogenize('GEOMETRYCOLLECTION(POINT(0 0))'));
 
 	st_astext
 	------------
-	 POINT(0 0)
-	(1 row)
+	POINT(0 0)
+</programlisting>
+
+<para>Nested single-element collection converted to an atomic geometry</para>
+<programlisting>
+  SELECT ST_AsText(ST_CollectionHomogenize('GEOMETRYCOLLECTION(MULTIPOINT((0 0)))'));
+
+	st_astext
+	------------
+	POINT(0 0)
+</programlisting>
 
+<para>Collection converted to a multi-geometry</para>
+<programlisting>
   SELECT ST_AsText(ST_CollectionHomogenize('GEOMETRYCOLLECTION(POINT(0 0),POINT(1 1))'));
 
 	st_astext
 	---------------------
-	 MULTIPOINT(0 0,1 1)
-	(1 row)
+	MULTIPOINT(0 0,1 1)
+</programlisting>
 
-				</programlisting>
-			</refsection>
-			<refsection>
-				<title>See Also</title>
-				<para><xref linkend="ST_Multi" />, <xref linkend="ST_CollectionExtract" /></para>
-			</refsection>
-		</refentry>
+<para>Collection of Polygons converted to an invalid MultiPolygon</para>
+<programlisting>
+  SELECT ST_AsText(ST_CollectionHomogenize('GEOMETRYCOLLECTION (POLYGON ((10 50, 50 50, 50 10, 10 10, 10 50)), POLYGON ((90 50, 90 10, 50 10, 50 50, 90 50)))'));
+
+	st_astext
+	---------------------
+	MULTIPOLYGON(((10 50,50 50,50 10,10 10,10 50)),((90 50,90 10,50 10,50 50,90 50)))
+</programlisting>
+        </refsection>
+        <refsection>
+            <title>See Also</title>
+            <para><xref linkend="ST_Multi" />, <xref linkend="ST_CollectionExtract" />,
+            <xref linkend="ST_IsValid" />, <xref linkend="ST_MakeValid" /></para>
+        </refsection>
+    </refentry>
 
     <refentry id="ST_CurveToLine">
       <refnamediv>

-----------------------------------------------------------------------

Summary of changes:
 doc/reference_editor.xml | 106 +++++++++++++++++++++++++++++------------------
 1 file changed, 65 insertions(+), 41 deletions(-)


hooks/post-receive
-- 
PostGIS