Add FAQ_CVS.

contrib/earthdistance/Makefile

@@ -0,0 +1,15 @@
+# PGLIB is probably /usr/local/pgsql/lib
+
+PGINCLUDE=${PGLIB}/../include
+CFLAGS+=-I${PGINCLUDE}
+
+install-earthdistance: ${PGLIB}/earthdistance.so
+
+${PGLIB}/earthdistance.so: earthdistance.so
+	sudo install -C -g bin -o bin earthdistance.so ${PGLIB}
+
+earthdistance.so:  earthdistance.o
+	$(LD) -o $@ -Bshareable $<
+
+earthdistance.o:  earthdistance.c
+	$(CC) -o $@ -c $(CFLAGS) $<

contrib/earthdistance/README

@@ -0,0 +1,31 @@
+Date: Wed, 1 Apr 1998 15:19:32 -0600 (CST)
+From: Hal Snyder <hal@vailsys.com>
+To: vmehr@ctp.com
+Subject: [QUESTIONS] Re: Spatial data, R-Trees
+
+> From: Vivek Mehra <vmehr@ctp.com>
+> Date: Wed, 1 Apr 1998 10:06:50 -0500
+
+>  Am just starting out with PostgreSQL and would like to learn more about
+> the spatial data handling ablilities of postgreSQL - in terms of using
+> R-tree indexes, user defined types, operators and functions. 
+> 
+> Would you be able to suggest where I could find some code and SQL to
+> look at to create these?
+
+Here's the setup for adding an operator '<@>' to give distance in
+statute miles between two points on the earth's surface. Coordinates
+are in degrees. Points are taken as (longitude, latitude) and not vice
+versa as longitude is closer to the intuitive idea of x-axis and
+latitude to y-axis.
+
+There's C source, Makefile for FreeBSD, and SQL for installing and
+testing the function.
+
+Let me know if anything looks fishy!
+
+A note on testing C extensions - it seems not enough to drop a function
+and re-create it - if I change a function, I have to stop and restart
+the backend for the new version to be seen. I guess it would be too
+messy to track which functions are added from a .so and do a dlclose
+when the last one is dropped.

contrib/earthdistance/earthdistance.c

@@ -0,0 +1,65 @@
+#include <math.h>
+#include <stdio.h>
+#include <string.h>
+
+#include <postgres.h>
+#include <utils/geo_decls.h>	/* for Pt */
+#include <utils/palloc.h>	/* for palloc */
+
+/* Earth's radius is in statute miles. */
+const EARTH_RADIUS = 3958.747716;
+const TWO_PI = 2.0 * M_PI;
+
+/******************************************************
+ *
+ * degtorad - convert degrees to radians
+ *
+ * arg:	double, angle in degrees
+ *
+ * returns:	double, same angle in radians
+ ******************************************************/
+
+static double
+degtorad (double degrees) {
+	return (degrees / 360.0) * TWO_PI;
+}
+
+
+/******************************************************
+ *
+ * geo_distance - distance between points
+ *
+ * args:
+ *   a pair of points - for each point,
+ *     x-coordinate is longitude in degrees west of Greenwich
+ *     y-coordinate is latitude in degrees above equator
+ *
+ * returns:	double
+ *   distance between the points in miles on earth's surface
+ ******************************************************/
+
+double *
+geo_distance (Point *pt1, Point *pt2) {
+
+	double long1, lat1, long2, lat2;
+	double longdiff;
+	double * resultp = palloc (sizeof(double));
+
+	/* convert degrees to radians */
+
+	long1 = degtorad (pt1->x);
+	lat1 = degtorad (pt1->y);
+
+	long2 = degtorad (pt2->x);
+	lat2 = degtorad (pt2->y);
+
+	/* compute difference in longitudes - want < 180 degrees */
+	longdiff = fabs (long1 - long2);
+	if (longdiff > M_PI)
+		longdiff = TWO_PI - longdiff;
+
+	* resultp = EARTH_RADIUS * acos
+	  (sin (lat1) * sin (lat2) + cos (lat1) * cos (lat2) * cos (longdiff));
+
+	return resultp;
+}

contrib/earthdistance/earthdistance.sql

@@ -0,0 +1,23 @@
+
+--------------- geo_distance
+
+DROP FUNCTION geo_distance (point, point);
+CREATE FUNCTION geo_distance (point, point) RETURNS float8
+  AS '/usr/local/pgsql/lib/earthdistance.so' LANGUAGE 'c';
+
+SELECT geo_distance ('(1,2)'::point, '(3,4)'::point);
+
+--------------- geo_distance as operator <@>
+
+DROP OPERATOR <@> (point, point);
+CREATE OPERATOR <@> (
+  leftarg = point,
+  rightarg = point,
+  procedure = geo_distance,
+  commutator = <@>
+);
+
+-- ( 87.6, 41.8) is in Chicago
+-- (106.7, 35.1) is in Albuquerque
+-- The cities are about 1100 miles apart
+SELECT '(87.6,41.8)'::point <@> '(106.7,35.1)'::point;