From 70f5a87ecc4cfa8810fb27ad55fa4904dcb40a6a Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Wed, 2 Jun 2004 21:34:49 +0000
Subject: [PATCH] Small patch that adds some documentation for the area()
 function. Specifically, point out that intersecting points in a path will
 yield (most likely), unexpected results.  Visually these are identical paths,
 but mathematically they're not the same.  Ex:

  area |                                           plan
------
+-----------------------------------------------------------------------
-------------------
    -0 | ((0,0),(0,1),(2,1),(2,2),(1,2),(1,0),(0,0))
     2 | ((0,0),(0,1),(1,1),(1,2),(2,2),(2,1),(1,1),(1,0),(0,0))

The current algorithm for area(PATH) is very quick, but only handles
non-intersecting paths.  I'm going to work on two other functions for
the PATH data type that determines if a PATH is intersecting or not,
and a function that returns the area() for an intersecting PATH.  The
intersecting area() function will be considerably slower (I think it's
going to be O(n!) or worse instead of the current O(n), but that comes
with the territory).

Sean Chittenden
---
 doc/src/sgml/func.sgml | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 82081e514f..a5d81b6fdd 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.205 2004/05/26 18:35:31 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.206 2004/06/02 21:34:49 momjian Exp $
 PostgreSQL documentation
 -->
 
@@ -5971,6 +5971,22 @@ SELECT TIMESTAMP 'now';
      as an array of two <type>point</> values.
     </para>
 
+    <para>
+     The <function>area</function> function works for the types
+     <type>box</type>, <type>circle</type>, and <type>path</type>.
+     The <function>area</function> function only works on the
+     <type>path</type> data type if the points in the
+     <type>path</type> are non-intersecting.  For example, the
+     <type>path</type>
+     <literal>'((0,0),(0,1),(2,1),(2,2),(1,2),(1,0),(0,0))'::PATH</literal>
+     won't work, however, the following visually identical
+     <type>path</type>
+     <literal>'((0,0),(0,1),(1,1),(1,2),(2,2),(2,1),(1,1),(1,0),(0,0))'::PATH</literal>
+     will work.  If the concept of an intersecting versus
+     non-intersecting <type>path</type> is confusing, draw both of the
+     above <type>path</type>s side by side on a piece of graph paper.
+    </para>
+
   </sect1>