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.
Figure 1. Example
of a box that is within a circle
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.
Figure 2. Bounding box example of the within function
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.
Figure 3. Containment and loose bounding boxes
For more information on loose bounding boxes, refer to
Loose bounding box calculations.
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.
