The Contains function

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

begin figure description - This figure is described in the surrounding text. - end figure description
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

begin figure description - This figure is described in the surrounding text. - end figure description
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

begin figure description - This figure is described in the surrounding text. - end figure description
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.