Compare function

The Compare() function compares two opaque types and returns an integer indicating the result of the comparison. The C name for each opaque data type is OpaqueCompare().

BladeSmith generates the complete C code for this function.

The generated code

The generated code compares the members of an opaque type C structure to the members in the other opaque type, in the order defined in the structure. This algorithm might not be the appropriate way to compare your data; if it is not, you must customize the code as described in the next section.

The Compare() function returns:
  • -1 if the values of two corresponding members are not equal and the value of the first is less than the value of the second.
  • 0 if the values of all members of the two opaque data types are equivalent.
  • +1 if the values of two corresponding members are not equal and the value of the first is greater than the value of the second.
For example, the Circle DataBlade® module defines a Pnt data type as follows: 
typedef struct
{
   mi_double_precision            x;
   mi_double_precision            y;
}
Pnt;

The Compare() function generated for the Pnt type first compares the two values of x. If the two values of x are not equal, Compare() stops and returns the result of the comparison. If the two values of x are equal, Compare() proceeds to compare the two values of y.

For data types such as mi_boolean, which cannot be compared for relative magnitude, the Compare() function returns +1 if the values differ. If all structure members are equal, it returns 0.

Customize the code

The algorithm used to generate the Compare() function cannot evaluate the semantic content of an opaque type. Therefore, for many opaque types, replace the generated code with more appropriate code.

For example, the Circ.h file of the Circle DataBlade module defines the Circ data type as follows: 
typedef struct
{
       Pnt                 center;
       mi_double_precision radius;
}
Circ;

The Pnt member has two mi_double_precision members: x and y. The generated code for Compare() compares the three mi_double_precision values individually: first x, then y, and then radius. However, if the size of your circles is more important than their origins, you could remove the code that compares the x and y members to base the comparison on the length of the radius only.

If you want to use B-tree indexing, the Compare() function is the B-tree support function. Therefore, analyze how you want to index your opaque data types when modifying Compare().

Smart large object considerations

The generated Compare() function does not compare the values of the smart large objects; it compares the smart large object handles. If the smart large object handles are the same, then both handles refer to the same object. You can customize the code to compare the actual values of the smart large objects.

Examples

The following example DataBlade modules implement the Compare() function to compare opaque data types member by member:
  • Matrix DataBlade module
  • Circle DataBlade module

The Shapes DataBlade module uses Compare() to perform a bitwise comparison on its Circle and Box data types.