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

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 82081e514fafa6acdb392913fc9fd7f11aa96d66..a5d81b6fddc99adf86fa30a6120e8a0e0c8211aa 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,5 +1,5 @@
 
 
@@ -5971,6 +5971,22 @@ SELECT TIMESTAMP 'now';
      as an array of two point values.
     
 
+    
+     The area function works for the types
+     box, circle, and path.
+     The area function only works on the
+     path data type if the points in the
+     path are non-intersecting.  For example, the
+     path
+     '((0,0),(0,1),(2,1),(2,2),(1,2),(1,0),(0,0))'::PATH
+     won't work, however, the following visually identical
+     path
+     '((0,0),(0,1),(1,1),(1,2),(2,2),(2,1),(1,1),(1,0),(0,0))'::PATH
+     will work.  If the concept of an intersecting versus
+     non-intersecting path is confusing, draw both of the
+     above paths side by side on a piece of graph paper.
+    
+