geopoly_contains_point(P,X,Y) doc is overly modest

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

geopoly_contains_point(P,X,Y) doc is overly modest

Larry Brasfield
The documentation at https://www.sqlite.org/geopoly.html , at 3.8. for geopoly_contains_point(), asserts that the function “returns true if and only if the coordinate X,Y is inside or on the boundary of the polygon P.”  As now implemented, in the v3.26 release, it returns 1 where the point is on a boundary and 2 where the point is inside of the boundary.  While the documentation is technically correct, (for a suitable definition of “true” differing from its meaning in SQL), this seems to be a useful behavior worthy of exposure.

I suggest the rewording, “returns 2 if the coordinate X,Y is inside polygon P, 1 if on the boundary, or 0 otherwise.”  I submit that this might help avoid errors such as “… WHERE geopoly_contains_point(_shape, ptX, ptY) = TRUE”, which will produce surprise for those who read the present claim literally.
_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: geopoly_contains_point(P,X,Y) doc is overly modest

Richard Hipp-3
On 12/1/18, Larry Brasfield <[hidden email]> wrote:
> The documentation at https://www.sqlite.org/geopoly.html , at 3.8. for
> geopoly_contains_point(), asserts that the function “returns true if and
> only if the coordinate X,Y is inside or on the boundary of the polygon P.”
> As now implemented, in the v3.26 release, it returns 1 where the point is on
> a boundary and 2 where the point is inside of the boundary.

The geopoly_overlap() and geopoly_within() routines are similarly
modest about what they compute.  Geopoly_within(A,B) returns +1 if B
is completely contained inside of A, and returns +2 if A and B are the
same polygon.  Geopoly_overlap(A,B) returns 4 different non-zero
values (1, 2, 3, and 4) depending on whether or not A is contained in
B (2), B is contained in A (3), A and B are the same polygon (4), or
if they just overlap (1).

I haven't documented those behaviors, because I wanted to leave myself
some wiggle room in case I need to change the behavior in the future.
--
D. Richard Hipp
[hidden email]
_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: geopoly_contains_point(P,X,Y) doc is overly modest

Richard Damon
On 12/1/18 1:52 PM, Richard Hipp wrote:

> On 12/1/18, Larry Brasfield <[hidden email]> wrote:
>> The documentation at https://www.sqlite.org/geopoly.html , at 3.8. for
>> geopoly_contains_point(), asserts that the function “returns true if and
>> only if the coordinate X,Y is inside or on the boundary of the polygon P.”
>> As now implemented, in the v3.26 release, it returns 1 where the point is on
>> a boundary and 2 where the point is inside of the boundary.
> The geopoly_overlap() and geopoly_within() routines are similarly
> modest about what they compute.  Geopoly_within(A,B) returns +1 if B
> is completely contained inside of A, and returns +2 if A and B are the
> same polygon.  Geopoly_overlap(A,B) returns 4 different non-zero
> values (1, 2, 3, and 4) depending on whether or not A is contained in
> B (2), B is contained in A (3), A and B are the same polygon (4), or
> if they just overlap (1).
>
> I haven't documented those behaviors, because I wanted to leave myself
> some wiggle room in case I need to change the behavior in the future.

Maybe it should say 'Non-Zero' or 'Greater than Zero' rather than true,
since true, as a symbol, as a special value.

--
Richard Damon

_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: geopoly_contains_point(P,X,Y) doc is overly modest

Keith Medcalf

>Maybe it should say 'Non-Zero' or 'Greater than Zero' rather than
>true, since true, as a symbol, as a special value.

Yes and no, True and False is SQLite work as one would expect (assuming that one is a programmer is a language that behaves as the underlying hardware (CPU) behaves).  The "False" state is any state in which all the bits are zero.  The "True" state is one in which ANY bit is non-zero.

Therefore you get:

sqlite> select -1 is true;
1
sqlite> select 0 is true;
0
sqlite> select 1 is true;
1
sqlite> select 2 is true;
1

and conversely for "is false".  You can also treat True and False as "values" in which case True has the arbitrary integer value 1, and false has the arbitrary integer value 0 (which complies with the "True means ANY bit is 1 and false means NO bits are one".  Any arbitrary non-zero value could have been chosen for the "value" of True when it is used as a value.

Using the expression "= TRUE" and "= FALSE" is likely a programmer error, just as "= NULL" is likely a programmer error, because what is really meant is "is TRUE", "is FALSE" and "is NULL" ...

---
The fact that there's a Highway to Hell but only a Stairway to Heaven says a lot about anticipated traffic volume.




_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: geopoly_contains_point(P,X,Y) doc is overly modest

Richard Hipp-3
On 12/1/18, Keith Medcalf <[hidden email]> wrote:
>
>>Maybe it should say 'Non-Zero' or 'Greater than Zero' rather than
>>true, since true, as a symbol, as a special value.
>
> Yes and no, True and False is SQLite work as one would expect (assuming that
> one is a programmer is a language that behaves as the underlying hardware
> (CPU) behaves).

Yeah, but Mr. Damon is probably right that the documentation should be
more precise.  So I have now updated it.

--
D. Richard Hipp
[hidden email]
_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: geopoly_contains_point(P,X,Y) doc is overly modest

Graham Hardman
In reply to this post by Richard Hipp-3
oh, I hope you dont do that since the application I am working on hopes
to exploit the retval = 4 of geopoly_overlap !

regards,
Graham

On 02-12-2018 7:52 am, Richard Hipp wrote:

> On 12/1/18, Larry Brasfield <[hidden email]> wrote:
>> The documentation at https://www.sqlite.org/geopoly.html , at 3.8. for
>> geopoly_contains_point(), asserts that the function “returns true if
>> and
>> only if the coordinate X,Y is inside or on the boundary of the polygon
>> P.”
>> As now implemented, in the v3.26 release, it returns 1 where the point
>> is on
>> a boundary and 2 where the point is inside of the boundary.
>
> The geopoly_overlap() and geopoly_within() routines are similarly
> modest about what they compute.  Geopoly_within(A,B) returns +1 if B
> is completely contained inside of A, and returns +2 if A and B are the
> same polygon.  Geopoly_overlap(A,B) returns 4 different non-zero
> values (1, 2, 3, and 4) depending on whether or not A is contained in
> B (2), B is contained in A (3), A and B are the same polygon (4), or
> if they just overlap (1).
>
> I haven't documented those behaviors, because I wanted to leave myself
> some wiggle room in case I need to change the behavior in the future.
_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: [EXTERNAL] geopoly_contains_point(P, X, Y) doc is overly modest

Hick Gunter
In reply to this post by Larry Brasfield
Maybe you should be using IS TRUE. See https://sqlite.org/lang_expr.html

     Boolean Expressions

     The SQL language features several contexts where an expression is evaluated and the result converted to a boolean (true or false) value. These contexts are:
     • the WHERE clause of a SELECT, UPDATE or DELETE statement,
     • the ON or USING clause of a join in a SELECT statement,
     • the HAVING clause of a SELECT statement,
     • the WHEN clause of an SQL trigger, and
     • the WHEN clause or clauses of some CASE expressions.

     To convert the results of an SQL expression to a boolean value, SQLite first casts the result to a NUMERIC value in the same way as a CAST expression. A numeric zero value (integer value 0 or real value 0.0) is considered to be false. A NULL value is still NULL. All other values are considered true.

     For example, the values NULL, 0.0, 0, 'english' and '0' are all considered to be false. Values 1, 1.0, 0.1, -0.1 and '1english' are considered to be true.

     Beginning with SQLite 3.23.0 (2018-04-02), SQLite recognizes the identifiers "TRUE" and "FALSE" as boolean literals, if and only if those identifiers are not already used for some other meaning. If there already exists columns or tables or other objects named TRUE or FALSE, then for the sake of backwards compatibility, the TRUE and FALSE identifiers refer to those other objects, not to the boolean values.

     The boolean identifiers TRUE and FALSE are usually just aliases for the integer values 1 and 0, respectively. However, if TRUE or FALSE occur on the right-hand side of an IS operator, then they form new unary postfix operators "IS TRUE" and "IS FALSE" which test the boolean value of the operand on the left.

-----Ursprüngliche Nachricht-----
Von: sqlite-users [mailto:[hidden email]] Im Auftrag von Larry Brasfield
Gesendet: Samstag, 01. Dezember 2018 19:39
An: [hidden email]
Betreff: [EXTERNAL] [sqlite] geopoly_contains_point(P,X,Y) doc is overly modest

The documentation at https://www.sqlite.org/geopoly.html , at 3.8. for geopoly_contains_point(), asserts that the function “returns true if and only if the coordinate X,Y is inside or on the boundary of the polygon P.”  As now implemented, in the v3.26 release, it returns 1 where the point is on a boundary and 2 where the point is inside of the boundary.  While the documentation is technically correct, (for a suitable definition of “true” differing from its meaning in SQL), this seems to be a useful behavior worthy of exposure.

I suggest the rewording, “returns 2 if the coordinate X,Y is inside polygon P, 1 if on the boundary, or 0 otherwise.”  I submit that this might help avoid errors such as “… WHERE geopoly_contains_point(_shape, ptX, ptY) = TRUE”, which will produce surprise for those who read the present claim literally.
_______________________________________________
sqlite-users mailing list
[hidden email]<mailto:[hidden email]>
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users


___________________________________________
 Gunter Hick | Software Engineer | Scientific Games International GmbH | Klitschgasse 2-4, A-1130 Vienna | FN 157284 a, HG Wien, DVR: 0430013 | (O) +43 1 80100 - 0

May be privileged. May be confidential. Please delete if not the addressee.

_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users