[postgis-commits] svn - r2878 - trunk/doc
postgis-commits at postgis.refractions.net
postgis-commits at postgis.refractions.net
Wed Jul 23 05:03:03 PDT 2008
Author: robe
Date: 2008-07-23 05:03:03 -0700 (Wed, 23 Jul 2008)
New Revision: 2878
Modified:
trunk/doc/reference.xml
trunk/doc/reference_new.xml
Log:
move of ST_AsBinary,ST_AsEWKB - add examples, various minor fixes to ST_As function descriptions
Modified: trunk/doc/reference.xml
===================================================================
--- trunk/doc/reference.xml 2008-07-23 10:56:31 UTC (rev 2877)
+++ trunk/doc/reference.xml 2008-07-23 12:03:03 UTC (rev 2878)
@@ -380,23 +380,7 @@
<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(<geometry>,'XDR') and
- asBinary(<geometry>,'NDR')</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term>ST_SRID(geometry)</term>
<listitem>
@@ -1378,17 +1362,6 @@
<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>
<listitem>
@@ -2340,17 +2313,6 @@
<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>
<listitem>
Modified: trunk/doc/reference_new.xml
===================================================================
--- trunk/doc/reference_new.xml 2008-07-23 10:56:31 UTC (rev 2877)
+++ trunk/doc/reference_new.xml 2008-07-23 12:03:03 UTC (rev 2878)
@@ -1225,6 +1225,165 @@
<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 @@
<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 @@
<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 @@
<!-- 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 @@
<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 @@
<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>
More information about the postgis-commits
mailing list