The Within function returns a Boolean value
that indicates whether an object is contained by another object. It
is similar to the Contains function, but the order
of the two parameters is switched.
The following figure shows a box that is within, or contained by,
a circle. The triangle, however, is not within either the circle or
the box, because all or part of the triangle lies outside both the
circle and the box.
The signature of the Within function must be:
Within (UDT, UDT) RETURNS BOOLEAN
UDT refers to user-defined type, or the data
type you want to index with the R-tree access method.
The Within function returns TRUE if
the object in the first parameter is within, or completely contained
in, the object in the second parameter and FALSE otherwise.
When you design the Within function, you might
want to first test if the bounding box of the first object is contained
in the bounding box of the second object; and if it is, then test
if the first data object is contained in the second data object. The
first test is a relatively quick and easy calculation and might eliminate
many candidates before the second, more complicated test.
For example, the following figure shows that the first bounding
box test eliminates the box-circle containment immediately, but the
second data object test is required to find out if the triangle is
within the circle. In this case, it is not.
If you allow loose, or inexact, bounding boxes, be careful when
you calculate the containment of bounding boxes. For example, the
following figure shows that although the loose bounding box of the
circle is not within the exact bounding box of the rectangle, the
circle is still within the rectangle.
Tip: The Contains function
is the commutator of the Within function. Remember
to specify the Contains function in the COMMUTATOR
clause in the CREATE FUNCTION command when you create the Within function.
For an example of how to specify a commutator when you create a function,
see Example of creating a strategy function.
Shapes3 sample DataBlade module contains sample
C code to create a Within function that takes the
MyShape data type as its two parameters.