|From:||Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>|
|Subject:||Bogus documentation for bogus geometric operators|
|Views:||Raw Message | Whole Thread | Download mbox | Resend email|
While revising the docs for the geometric operators, I came across
<^ 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
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:
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:
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
about this code-wise, but what should I do documentation-wise?
I'm certainly not eager to document that these operators behave
inconsistently depending on which type you're talking about.
regards, tom lane
|Next Message||Amit Kapila||2020-04-21 04:50:01||Re: design for parallel backup|
|Previous Message||Amit Kapila||2020-04-21 04:27:31||Re: WIP/PoC for parallel backup|