Previous chapter: Conditionals, Flow of Control, and Evaluation

Dylan manual: Equality and <A NAME="Magnitude Comparison0">Magnitude Comparison</A>s

## 9. Equality and Magnitude Comparisons

Dylan provides an identity function, as well as a group of equality and magnitude comparison functions that can be extended for user classes. The methods =, /=, <, >, <=, and >= are defined in terms of binary= and binary<. By extending the behavior of binary= and binary<, programs can extend the behavior of the six methods.

For the protocol to work, all methods on binary= and binary< must preserve the following properties:

Identity:
If (id? a b), then (binary= a b).
Transitivity:
If (binary< a b) and (binary< b c), then (binary< a c).
If (binary= a b) and (binary= b c), then (binary= a c).
Trichotomy:
Exactly one of: (binary< a b), (binary= a b),
(binary< b a) always holds (on the assumption that these two operations are defined for the objects in question). FN22 , FN23

In addition, classes which provide their own definition of binary= should provide a definition for =hash, if instances of the class will be used as keys in = hash tables.

```id?>   object1 object2 #rest objects   ==>  boolean	[Method]
```
id? returns true if object1, object2, and all the objects are all identical. Otherwise, it returns false.

Objects are considered identical if they are computationally equivalent. That is, there is no way for any possible Dylan program to distinguish them. FN24

```=   object1 object2 #rest objects   ==>  boolean	[Method]
```
= returns true if every object is binary= to every other object. Otherwise, = returns false.

= is not guaranteed to return (for example, when called on circular structures or unbounded structures).

= is a method, so you cant add other methods to it. To extend the protocol, define methods on binary=.

```/=   object1 object2   ==>  boolean	[Method]
```
/= calls binary= on object1 and object2. Returns true if binary= returns false FN25.

/= is a method, so you cant add other methods to it. To extend the protocol, define methods on binary=.

```binary=[next citation]   object1 object2   ==>  boolean	[Generic Function]
```
binary= is called by = and other comparison predicates. Programs should not normally call this function directly.

The predefined methods on binary= behave as follows:

• Collections are equal if they have the same keys and if the values of corresponding keys are =. Keys are considered the same if they match according to the test used by the element method of the collection. If the collections use a different test, then an error is signaled. For example, an error would be signaled when trying to compare an = hash-table with an id? hash-table. An error would not be signaled when comparing a sequence and an id? hash-table.

This implies that the collections are the same size. For sequences, this means that elements at the same position are =.

• Dotted lists are equal if the elements are equal and if the final cdrs are equal.

• Built-in numbers are compared by mathematical value.

• Other objects are compared with id?.
If you define a method on binary= for a class of objects that you expect to use as keys in = tables, you must also define a corresponding method on =hash. The details are described in the section on collections.

```=hash=hash   object   ==>  integer	[Generic Function]
```
returns a hash-code for object. If you define any methods for binary= and wish to use objects affected by that definition as keys in = tables, then you must define corresponding methods for =hash.

The rule is that if two objects are =, then they must generate the same hash code when passed to =hash.

The value returned by =hash must be a integer.

```<   object1 object2 #rest objects   ==>  boolean	[Method]
```
< compares the objects two at a time with binary<. If each object is less than the one to its right, < returns true. Otherwise < returns false.

< is a method, so you cannot add other methods to it. To extend the protocol, define methods on binary<.

```>   object1 object2 #rest objects   ==>  boolean	[Method]
```
> compares the objects two at a time with binary< (with appropriate argument reordering). If each object is greater than the one to its right, > returns true. Otherwise, > returns false.

> is a method, so you cannot add other methods to it. To extend the protocol, define methods on binary<.

```<=   object1 object2 #rest objects   ==>  boolean	[Method]
```
<= compares the objects two at a time with binary< (with appropriate argument reordering). If each object is less than or equal to the one to its right, <= returns true. Otherwise, <= returns false.

<= is a method, so you cannot add other methods to it. To extend the protocol, define methods on binary<.

```>=>=   object1 object2 #rest objects   ==>  boolean	[Method]
```
>= compares the objects two at a time with binary<. If each object is greater than or equal to the one to its right, >= returns true. Otherwise, >= returns false.

>= is a method, so you cannot add other methods to it. To extend the protocol, define methods on binary<.

binary<[next citation]   object1 object2   ==>  boolean	[Generic Function]
Called by <, >, and other functions.  Programs should not call this function directly.

The predefined methods on binary< behave as follows:

• Built-in real numbers are compared by mathematical value.
• Characters are compared by the ordinal value of the underlying character set. Character case is significant.
• Strings are compared lexicographically, using binary< on corresponding elements. If one string is a strict prefix of the other, the shorter string is considered the smaller one.