# Bogus documentation for bogus geometric operators

From: Tom Lane pgsql-hackers(at)lists(dot)postgresql(dot)org Bogus documentation for bogus geometric operators 2020-04-21 04:42:40 24348.1587444160@sss.pgh.pa.us Raw Message | Whole Thread | Download mbox | Resend email 2020-04-21 04:42:40 from Tom Lane  2020-04-28 16:33:53 from Emre Hasegeli   2020-04-28 17:33:24 from Tom Lane  2020-08-21 11:00:45 from Emre Hasegeli 📎   2020-09-05 01:45:22 from Michael Paquier    2020-09-07 10:50:17 from Emre Hasegeli 📎     2020-11-03 09:30:41 from Pavel Borisov      2020-11-03 10:53:12 from Pavel Borisov       2020-11-04 09:02:52 from Pavel Borisov 📎        2020-11-04 09:32:19 from Emre Hasegeli         2020-11-04 09:43:18 from Pavel Borisov 📎          2020-11-12 22:16:33 from Tom Lane           2020-11-13 08:26:53 from Pavel Borisov 📎            2020-11-22 23:52:26 from Tom Lane 📎             2020-11-23 09:09:34 from Pavel Borisov              2020-11-23 09:17:37 from Pavel Borisov               2020-11-23 11:44:06 from Pavel Borisov                2020-11-23 16:39:29 from Tom Lane pgsql-hackers

While revising the docs for the geometric operators, I came across
these entries:

<^ Is below (allows touching)? circle '((0,0),1)' <^ circle '((0,5),1)'
>^ Is above (allows touching)? circle '((0,5),1)' >^ circle '((0,0),1)'

These have got more than a few problems:

1. There are no such operators for circles, so the examples are pure
fantasy.

2. What these operators do exist for is points (point_below, point_above
respectively) and boxes (box_below_eq, box_above_eq). However, the
stated behavior is not what the point functions actually do:

point_below(PG_FUNCTION_ARGS)
...
PG_RETURN_BOOL(FPlt(pt1->y, pt2->y));

point_above(PG_FUNCTION_ARGS)
...
PG_RETURN_BOOL(FPgt(pt1->y, pt2->y));

So point_below would be more accurately described as "is strictly below",
so its operator name really ought to be <<|. And point_above is "is
strictly above", so its operator name ought to be |>>.

3. The box functions do seem to be correctly documented:

box_below_eq(PG_FUNCTION_ARGS)
...
PG_RETURN_BOOL(FPle(box1->high.y, box2->low.y));

box_above_eq(PG_FUNCTION_ARGS)
...
PG_RETURN_BOOL(FPge(box1->low.y, box2->high.y));

But there are comments in the source code to the effect of

* box_below_eq and box_above_eq are obsolete versions that (probably
* erroneously) accept the equal-boundaries case. Since these are not
* in sync with the box_left and box_right code, they are deprecated and
* not supported in the PG 8.1 rtree operator class extension.

I'm not sure how seriously to take this deprecation comment, but it
is true that box_below (<<|) and box_above (|>>) have analogs for
other data types while these functions don't.

4. Just for extra fun, these point operators are listed in some
GIST and SP-GIST opclasses; though the box ones are not, as per
that code comment.

Perhaps it's too late in the v13 cycle to actually do anything