move of ST_AsBinary,ST_AsEWKB - add examples, various minor fixes to ST_As function...

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

diff --git a/doc/reference.xml b/doc/reference.xml
index 18ad920f9ad1715278785b5387da1a890ad6ca20..a14755022ff3bfd751c655f817e85b46132d9262 100644 (file)
--- a/doc/reference.xml
+++ b/doc/reference.xml
@@ -380,22 +380,6 @@
       <title>Geometry Accessors</title>
 
       <variablelist>
-
-        <varlistentry>
-          <term>ST_AsBinary(geometry)</term>
-
-          <listitem>
-            <para>Returns the geometry in the OGC "well-known-binary" format,
-            using the endian encoding of the server on which the database is
-            running. This is useful in binary cursors to pull data out of the
-            database without converting it to a string representation.</para>
-
-            <para>OGC SPEC s2.1.1.1 - also see
-            asBinary(&lt;geometry&gt;,'XDR') and
-            asBinary(&lt;geometry&gt;,'NDR')</para>
-          </listitem>
-        </varlistentry>
-
         <varlistentry>
           <term>ST_SRID(geometry)</term>
 
@@ -1377,17 +1361,6 @@ GROUP BY gid, field1,field2;
       <title>Geometry Outputs</title>
 
       <variablelist>
-        <varlistentry>
-          <term>ST_AsBinary(geometry,{'NDR'|'XDR'})</term>
-
-          <listitem>
-            <para>Returns the geometry in the OGC "well-known-binary" format
-            as a bytea, using little-endian (NDR) or big-endian (XDR)
-            encoding. This is useful in binary cursors to pull data out of the
-            database without converting it to a string representation.</para>
-          </listitem>
-        </varlistentry>
-
         <varlistentry>
           <term>ST_AsHEXEWKB(geometry, {'NDR'|'XDR'})</term>
 
@@ -2339,17 +2312,6 @@ WHERE n*100.00/length &lt; 1;
     </note>
 
     <variablelist>
-      <varlistentry>
-        <term>ST_AsBinary</term>
-
-        <listitem>
-          <para>Return the well-known binary representation of an ST_Geometry
-          value.</para>
-
-          <para>SQL-MM 3: 5.1.37</para>
-        </listitem>
-      </varlistentry>
-
       <varlistentry>
         <term>ST_Boundary</term>
 

diff --git a/doc/reference_new.xml b/doc/reference_new.xml
index 5ed334629fc4ac51d9ef6ad52dd35ff6c3b900f5..2438674205dcb11321033197834713b41e38d614 100644 (file)
--- a/doc/reference_new.xml
+++ b/doc/reference_new.xml
@@ -1225,6 +1225,165 @@ CREATE INDEX idx_the_geom_26986_parcels
 
   <sect1>
       <title>Geometry Outputs</title>
+                 <refentry id="ST_AsBinary">
+                 <refnamediv>
+                       <refname>ST_AsBinary</refname>
+                       <refpurpose>Return the Well-Known Binary (WKB) representation of the geometry without SRID meta data.</refpurpose>
+                 </refnamediv>
+               
+                 <refsynopsisdiv>
+                       <funcsynopsis>
+                         <funcprototype>
+                               <funcdef>bytea <function>ST_AsBinary</function></funcdef>
+                               <paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
+                         </funcprototype>
+                         <funcprototype>
+                               <funcdef>bytea <function>ST_AsBinary</function></funcdef>
+                               <paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
+                               <paramdef><type>text </type><parameter>NDR_or_XDR</parameter></paramdef>
+                         </funcprototype>
+                       </funcsynopsis>
+                 </refsynopsisdiv>
+               
+                 <refsection>
+                       <title>Description</title>
+               
+                       <para>Returns the Well-Known Binary representation of the geometry.  There are 2 variants of the function.  The first
+                       variant takes no endian encoding paramater and defaults to little endian.  The second variant takes a second argument
+                       denoting the encoding - using little-endian ('NDR') or big-endian ('XDR') encoding.</para>
+                       <para>This is useful in binary cursors to pull data out of the
+            database without converting it to a string representation.</para>
+
+                       <note>
+                         <para>The WKB spec does not include the SRID.  To get the OGC WKB with SRID format use ST_AsEWKB</para>
+                       </note>
+                       <note>
+                         <para>ST_AsBinary is the reverse of ST_GeomFromWKB.  Use ST_GeomFromWKB to convert to a postgis geometry from ST_AsBinary representation.</para>
+                       </note>
+                       
+                       <para><inlinemediaobject>
+                               <imageobject>
+                                 <imagedata fileref="images/check.png" />
+                               </imageobject>
+                         </inlinemediaobject> This method implements the <ulink
+                       url="http://www.opengeospatial.org/standards/sfs">OpenGIS Simple Features
+                       Implementation Specification for SQL. OGC SPEC s2.1.1.1</ulink></para>
+                       
+                       <para><inlinemediaobject>
+                               <imageobject>
+                                 <imagedata fileref="images/check.png" />
+                               </imageobject>
+                         </inlinemediaobject> This method implements the SQL/MM specification: SQL-MM 3: 5.1.37
+                       </para>
+                       
+                 </refsection>
+               
+               
+                 <refsection>
+                       <title>Examples</title>
+               
+                       <programlisting>SELECT ST_AsBinary(ST_GeomFromText('POLYGON((0 0,0 1,1 1,1 0,0 0))',4326));
+
+           st_asbinary
+--------------------------------
+\001\003\000\000\000\001\000\000\000\005
+\000\000\000\000\000\000\000\000\000\000
+\000\000\000\000\000\000\000\000\000\000
+\000\000\000\000\000\000\000\000\000\000
+\000\000\000\360?\000\000\000\000\000\000
+\360?\000\000\000\000\000\000\360?\000\000
+\000\000\000\000\360?\000\000\000\000\000
+\000\000\000\000\000\000\000\000\000\000\000
+\000\000\000\000\000\000\000\000
+(1 row)</programlisting>
+                       <programlisting>SELECT ST_AsBinary(ST_GeomFromText('POLYGON((0 0,0 1,1 1,1 0,0 0))',4326), 'XDR');
+           st_asbinary
+--------------------------------
+\000\000\000\000\003\000\000\000\001\000\000\000\005\000\000\000\000\000
+\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000
+\000?\360\000\000\000\000\000\000?\360\000\000\000\000\000\000?\360\000\000
+\000\000\000\000?\360\000\000\000\000\000\000\000\000\000\000\000\000\000\000
+\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000
+(1 row)</programlisting>
+                 </refsection>
+               
+                 <!-- Optionally add a "See Also" section -->
+                 <refsection>
+                       <title>See Also</title>
+                       <para><xref linkend="ST_AsEWKB" />, <xref linkend="ST_AsEWKT" />, <xref linkend="ST_AsText" />, <xref linkend="ST_GeomFromEWKB" /></para>
+                 </refsection>
+       </refentry>
+         <refentry id="ST_AsEWKB">
+                 <refnamediv>
+                       <refname>ST_AsEWKB</refname>
+                       <refpurpose>Return the Well-Known Binary (WKB) representation of the geometry with SRID meta data.</refpurpose>
+                 </refnamediv>
+               
+                 <refsynopsisdiv>
+                       <funcsynopsis>
+                         <funcprototype>
+                               <funcdef>bytea <function>ST_AsEWKB</function></funcdef>
+                               <paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
+                         </funcprototype>
+                         <funcprototype>
+                               <funcdef>bytea <function>ST_AsEWKB</function></funcdef>
+                               <paramdef><type>geometry </type> <parameter>g1</parameter></paramdef>
+                               <paramdef><type>text </type><parameter>NDR_or_XDR</parameter></paramdef>
+                         </funcprototype>
+                       </funcsynopsis>
+                 </refsynopsisdiv>
+               
+                 <refsection>
+                       <title>Description</title>
+                       <para>Returns the Well-Known Binary representation of the geometry with SRID metadata.  There are 2 variants of the function.  The first
+                       variant takes no endian encoding paramater and defaults to little endian.  The second variant takes a second argument
+                       denoting the encoding - using little-endian ('NDR') or big-endian ('XDR') encoding.</para>
+                       <para>This is useful in binary cursors to pull data out of the
+            database without converting it to a string representation.</para>
+                       <note>
+                         <para>The WKB spec does not include the SRID.  To get the OGC WKB format use ST_AsBinary</para>
+                       </note>
+                       <note>
+                         <para>ST_AsEWKB is the reverse of ST_GeomFromEWKB.  Use ST_GeomFromEWKB to convert to a postgis geometry from ST_AsEWKB representation.</para>
+                       </note>
+                 </refsection>
+               
+               
+                 <refsection>
+                       <title>Examples</title>
+               
+                       <programlisting>SELECT ST_AsEWKB(ST_GeomFromText('POLYGON((0 0,0 1,1 1,1 0,0 0))',4326));
+
+           st_asewkb
+--------------------------------
+\001\003\000\000 \346\020\000\000\001\000
+\000\000\005\000\000\000\000
+\000\000\000\000\000\000\000\000
+\000\000\000\000\000\000\000\000\000
+\000\000\000\000\000\000\000\000\000\000
+\000\000\360?\000\000\000\000\000\000\360?
+\000\000\000\000\000\000\360?\000\000\000\000\000
+\000\360?\000\000\000\000\000\000\000\000\000\000\000
+\000\000\000\000\000\000\000\000\000\000\000\000\000
+(1 row)</programlisting>
+               <programlisting>
+                       SELECT ST_AsEWKB(ST_GeomFromText('POLYGON((0 0,0 1,1 1,1 0,0 0))',4326), 'XDR');
+           st_asewkb
+--------------------------------
+\000 \000\000\003\000\000\020\346\000\000\000\001\000\000\000\005\000\000\000\000\
+000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000?
+\360\000\000\000\000\000\000?\360\000\000\000\000\000\000?\360\000\000\000\000
+\000\000?\360\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000
+\000\000\000\000\000\000\000\000\000\000\000\000\000
+               </programlisting>
+                 </refsection>
+               
+                 <!-- Optionally add a "See Also" section -->
+                 <refsection>
+                       <title>See Also</title>
+                       <para><xref linkend="ST_AsBinary" />, <xref linkend="ST_AsEWKT" />, <xref linkend="ST_AsText" />, <xref linkend="ST_GeomFromEWKT" />, <xref linkend="ST_SRID" /></para>
+                 </refsection>
+       </refentry>
          <refentry id="ST_AsEWKT">
                  <refnamediv>
                        <refname>ST_AsEWKT</refname>
@@ -1248,6 +1407,9 @@ CREATE INDEX idx_the_geom_26986_parcels
                        <note>
                          <para>The WKT spec does not include the SRID.  To get the OGC WKT format use ST_AsText</para>
                        </note>
+                       <para><inlinegraphic class="sfs_compliant" fileref="images/warning.png" />
+                               WKT format does not maintain precision so to prevent floating truncation, use ST_AsBinary or ST_AsEWKB format for transport.
+                       </para>
                        <note>
                          <para>ST_AsEWKT is the reverse of ST_GeomFromEWKT.  Use ST_GeomFromEWKT to convert to a postgis geometry from ST_AsEWKT representation.</para>
                        </note>
@@ -1257,10 +1419,10 @@ CREATE INDEX idx_the_geom_26986_parcels
                  <refsection>
                        <title>Examples</title>
                
-                       <programlisting>SELECT ST_AsEWKT(ST_SetSRID('01030000000100000005000000000000000000
-000000000000000000000000000000000000000000000000
-F03F000000000000F03F000000000000F03F000000000000F03
-F000000000000000000000000000000000000000000000000', 4326));
+                       <programlisting>SELECT ST_AsEWKT('0103000020E61000000100000005000000000000
+                       000000000000000000000000000000000000000000000000000000
+                       F03F000000000000F03F000000000000F03F000000000000F03
+                       F000000000000000000000000000000000000000000000000'::geometry);
 
            st_asewkt
 --------------------------------
@@ -1271,14 +1433,13 @@ SRID=4326;POLYGON((0 0,0 1,1 1,1 0,0 0))
                  <!-- Optionally add a "See Also" section -->
                  <refsection>
                        <title>See Also</title>
-               
-                       <para><xref linkend="ST_AsText" />, <xref linkend="ST_GeomFromEWKT" /></para>
+                       <para><xref linkend="ST_AsBinary" /><xref linkend="ST_AsEWKB" /><xref linkend="ST_AsText" />, <xref linkend="ST_GeomFromEWKT" /></para>
                  </refsection>
        </refentry>
          <refentry id="ST_AsText">
                  <refnamediv>
                        <refname>ST_AsText</refname>
-                       <refpurpose>Return the Well-Known Text (WKT) representation of the geometry.</refpurpose>
+                       <refpurpose>Return the Well-Known Text (WKT) representation of the geometry without SRID metadata.</refpurpose>
                  </refnamediv>
                
                  <refsynopsisdiv>
@@ -1299,6 +1460,9 @@ SRID=4326;POLYGON((0 0,0 1,1 1,1 0,0 0))
                          <para>The WKT spec does not include the SRID.  To get the SRID as part of the data, use the non-standard
                                PostGIS ST_AsEWKT()</para>
                        </note>
+                       <para><inlinegraphic class="sfs_compliant" fileref="images/warning.png" />
+                               WKT format does not maintain precision so to prevent floating truncation, use ST_AsBinary or ST_AsEWKB format for transport.
+                       </para>
                        <note>
                          <para>ST_AsText is the reverse of ST_GeomFromText.  Use ST_GeomFromText to convert to a postgis geometry from ST_AsText representation.</para>
                        </note>
@@ -1339,7 +1503,7 @@ F000000000000000000000000000000000000000000000000');
                  <refsection>
                        <title>See Also</title>
                
-                       <para><xref linkend="ST_AsEWKT" />, <xref linkend="ST_GeomFromText" /></para>
+                       <para><xref linkend="ST_AsBinary" />, <xref linkend="ST_AsEWKB" />, <xref linkend="ST_AsEWKT" />, <xref linkend="ST_GeomFromText" /></para>
                  </refsection>
        </refentry>
   </sect1>