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.
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.
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.
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.