[postgis-tickets] r14929 - #3059, Allow passing per-dimension parameters in ST_Expand

[Daniel Baston]

Author: dbaston
Date: 2016-06-02 15:28:47 -0700 (Thu, 02 Jun 2016)
New Revision: 14929

Modified:
   trunk/doc/reference_misc.xml
Log:
#3059, Allow passing per-dimension parameters in ST_Expand

Modified: trunk/doc/reference_misc.xml
===================================================================
--- trunk/doc/reference_misc.xml	2016-06-02 01:24:52 UTC (rev 14928)
+++ trunk/doc/reference_misc.xml	2016-06-02 22:28:47 UTC (rev 14929)
@@ -264,36 +264,63 @@
 		<funcsynopsis>
 		  <funcprototype>
 			<funcdef>geometry <function>ST_Expand</function></funcdef>
-			<paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
+			<paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
 			<paramdef><type>float</type> <parameter>units_to_expand</parameter></paramdef>
 		  </funcprototype>
 
 		  <funcprototype>
+			<funcdef>geometry <function>ST_Expand</function></funcdef>
+			<paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
+			<paramdef><type>float</type> <parameter>dx</parameter></paramdef>
+			<paramdef><type>float</type> <parameter>dy</parameter></paramdef>
+			<paramdef choice="opt"><type>float</type> <parameter>dz=0</parameter></paramdef>
+			<paramdef choice="opt"><type>float</type> <parameter>dm=0</parameter></paramdef>
+		  </funcprototype>
+
+		  <funcprototype>
 			<funcdef>box2d <function>ST_Expand</function></funcdef>
-			<paramdef><type>box2d </type> <parameter>g1</parameter></paramdef>
+			<paramdef><type>box2d </type> <parameter>box</parameter></paramdef>
 			<paramdef><type>float</type> <parameter>units_to_expand</parameter></paramdef>
 		  </funcprototype>
 
 		  <funcprototype>
+			<funcdef>box2d <function>ST_Expand</function></funcdef>
+			<paramdef><type>box2d </type> <parameter>box</parameter></paramdef>
+			<paramdef><type>float</type> <parameter>dx</parameter></paramdef>
+			<paramdef><type>float</type> <parameter>dy</parameter></paramdef>
+		  </funcprototype>
+
+		  <funcprototype>
 			<funcdef>box3d <function>ST_Expand</function></funcdef>
-			<paramdef><type>box3d </type> <parameter>g1</parameter></paramdef>
+			<paramdef><type>box3d </type> <parameter>box</parameter></paramdef>
 			<paramdef><type>float</type> <parameter>units_to_expand</parameter></paramdef>
 		  </funcprototype>
+
+		  <funcprototype>
+			<funcdef>box3d <function>ST_Expand</function></funcdef>
+			<paramdef><type>box3d </type> <parameter>box</parameter></paramdef>
+			<paramdef><type>float</type>  <parameter>dx</parameter></paramdef>
+			<paramdef><type>float</type>  <parameter>dy</parameter></paramdef>
+			<paramdef choice="opt"><type>float</type>  <parameter>dz=0</parameter></paramdef>
+		  </funcprototype>
 		</funcsynopsis>
 	  </refsynopsisdiv>
 
 	  <refsection>
 		<title>Description</title>
 
-		<para>This function returns a bounding box expanded in all
-		directions from the bounding box of the input geometry, by an
-		amount specified in the second argument. Uses double-precision. Very useful for
-		distance() queries, or bounding box queries to add an index filter to the query.</para>
-		<para>There are 3 variants of this.  The one that takes a geometry will return a POLYGON geometry representation
-			of the bounding box and is the most commonly used variant.</para>
-		<para>ST_Expand is similar in concept to ST_Buffer except while buffer expands the geometry in all directions,
+		<para>This function returns a bounding box expanded from the bounding box of the input,
+			either by specifying a single distance with which the box should be expanded in all
+			directions, or by specifying an expansion distance for each direction.
+
+			Uses double-precision. Can be very useful for distance queries, or to add a bounding box 
+			filter to a query to take advantage of a spatial index.</para>
+		<para>In addition to the geometry version of ST_Expand, which is the most commonly used, variants 
+			are provided that accept and produce internal BOX2D and BOX3D data types.
+		</para>
+		<para>ST_Expand is similar in concept to ST_Buffer, except while buffer expands the geometry in all directions,
 			ST_Expand expands the bounding box an x,y,z unit amount.</para>
-		<para>Units are in the units of the spatial reference system in use denoted by the SRID</para>
+		<para>Units are in the units of the spatial reference system in use denoted by the SRID.</para>
 
 		<note>
 		  <para>Pre 1.3, ST_Expand was used in conjunction with distance to do indexable queries.  Something of the form
@@ -303,9 +330,10 @@
 
 		<note>
 			<para>Availability: 1.5.0 behavior changed to output double precision instead of float4 coordinates.</para>
+			<para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
+			<para>Enhanced: 2.3.0 support was added to expand a box by different amounts in different dimensions.</para>
 		</note>
 		
-		<para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
 		<para>&P_support;</para>
 		<para>&T_support;</para>