The Contains function returns a Boolean value
that indicates whether an object entirely contains another object.
The following figure shows a circle that contains a box. The circle,
however, does not contain the triangle, because part of the triangle
lies outside the circle.
Figure 1. Example of a circle that contains a box
The signature of the
Contains function must
be:
Contains (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 Contains function returns TRUE if
the object in the first parameter completely contains the object in
the second parameter and FALSE otherwise.
When you design the Contains function, you might
want to first test if the bounding box of the first object contains
the bounding box of the second object; and if it does, then test if
the first data object contains 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 circle contains
the triangle. In this case, it does not.
Figure 2. Bounding box example of the contains
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 exact bounding box of the
rectangle does not contain the loose bounding box of the circle, the
rectangle still contains the circle.
Figure 3. Containment and loose bounding boxes
In this case, a preliminary test for bounding box containment returns
inaccurate results unless you used a compensating factor to account
for the circle's loose bounding box. For more information on loose
bounding boxes, refer to
Loose bounding box calculations.
Tip: The
Within strategy function is the
commutator of the
Contains strategy function. Remember
to specify the
Within function in the COMMUTATOR
clause in the CREATE FUNCTION command when you create the
Contains function,
and vice versa. 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 Contains function that takes
the MyShape data type as its two parameters.
