The Within function

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

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

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

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