1.1 --- a/README.mkd	Fri Oct 21 12:57:46 2016 +0200
     1.2 +++ b/README.mkd	Tue Oct 25 18:44:43 2016 +0200
     1.3 @@ -1,4 +1,4 @@
     1.4 -pgLatLon v0.8 documentation
     1.5 +pgLatLon v0.9 documentation
     1.6  ===========================
     1.7  
     1.8  pgLatLon is a spatial database extension for the PostgreSQL object-relational
     1.9 @@ -39,8 +39,8 @@
    1.10  It is also possible to compile and install the extension without GNU Make as
    1.11  follows:
    1.12  
    1.13 -    cc -Wall -O2 -fPIC -shared -I `pg_config --includedir-server` -o latlon-v0007.so latlon-v0007.c
    1.14 -    cp latlon-v0007.so `pg_config --pkglibdir`
    1.15 +    cc -Wall -O2 -fPIC -shared -I `pg_config --includedir-server` -o latlon-v0008.so latlon-v0008.c
    1.16 +    cp latlon-v0008.so `pg_config --pkglibdir`
    1.17      cp latlon.control `pg_config --sharedir`/extension/
    1.18      cp latlon--*.sql `pg_config --sharedir`/extension/
    1.19  
    1.20 @@ -469,6 +469,38 @@
    1.21  
    1.22  Same as `epoint(float8, float8)` but with arguments reversed.
    1.23  
    1.24 +#### `fair_distance(ecluster, epoint,` samples `int4 = 10000)`
    1.25 +
    1.26 +When working with user-generated content, users may be tempted to create
    1.27 +intentionally oversized objects in order to optimize search results in an
    1.28 +unfair manner. The `fair_distance` function aims to handle this by returning an
    1.29 +adjusted distance (i.e. distance increased by a penalty) if a geographic object
    1.30 +(the `ecluster`) consists of more than one point.
    1.31 +
    1.32 +The first argument to this function is an `ecluster`, the second argument is a
    1.33 +search point (`epoint`), and the third argument is an interger related to the
    1.34 +precision (higher precision will require more computation time).
    1.35 +
    1.36 +The penalty by which the returned distance is increased fulfills (at least) the
    1.37 +following properties:
    1.38 +
    1.39 +* For search points far away from the `ecluster` (i.e. distance approaching
    1.40 +  infinity), the penalty approaches zero (i.e. `fair_distance` behaves the same
    1.41 +  as `distance`).
    1.42 +* If the `ecluster` consists of a set of points, the penalty for a search point
    1.43 +  close to one of that points (closer than half of the minimum distance between
    1.44 +  each pair of points in the `ecluster`) is chosen in such a way that the
    1.45 +  adjusted distance is equal to the distance from the search point to the
    1.46 +  closest point in the `ecluster` multiplied by the square root of the count of
    1.47 +  points in the `ecluster`.
    1.48 +
    1.49 +The function interally uses a Monte Carlo simulation to compute the result. The
    1.50 +third parameter (which defaults to 10000) can be used to adjust the number of
    1.51 +samples taken. It is ensured that the penalty is always positive, i.e. results
    1.52 +returned by the `fair_distance` function are always equal to or greater than
    1.53 +the results returned by the `distance` function regardless of stochastic
    1.54 +effects.
    1.55 +
    1.56  #### `GeoJSON_to_epoint(jsonb, text)`
    1.57  
    1.58  Maps a GeoJSON object of type "Point" or "Feature" (which contains a