Chapter 12
The Built-In Functions
Equality and Comparison
Dylan provides an identity function, as well as a group of equality and magnitude
comparison functions that can be extended for user classes. The
functions ~=, ~==, >, <=, >=, min
and max are defined in terms of == or =
and <. By extending the behavior of = and <,
programs can extend the behavior of the other functions.
For the protocol to work, user-defined methods on = and < must
preserve the following properties:
- Identity:
If (a
=b), then (b=a).- Transitivity:
If (a
<b) and (b<c), then (a<c).If (a
=b) and (b=c), then (a=c).- Trichotomy:
-
Exactly one of: (a
<b), (a=b), (b<a) always holds (on the assumption that these two operations are defined for the objects in question).
In the general case, the behavior of comparison operators when applied to instances
of <complex> is implementation defined. This is to allow
implementations to support IEEE floating point when
comparing NaNs. However, when instances of <rational> and instances
of <float> are compared, it is defined that the instance
of <float> is first converted to a rational and then an exact
comparison is performed.
Logical Negation
~ [Function]
Returns true if its argument is false; otherwise returns false.
- Signature:
-
~ thing⇒boolean - Arguments:
-
- thing
-
An instance of
<object>.
- Values:
-
- boolean
-
An instance of
<boolean>.
- Description:
Returns
#tif thing is false. Returns#fif thing is true.
Equality Comparisons
== [Function]
Compares two objects for identity.
- Signature:
-
object1 == object2⇒boolean - Arguments:
-
- object1
-
An instance of
<object>. - object2
An instance of
<object>.
- Values:
-
- boolean
-
An instance of
<boolean>.
- Description:
-
Returns true if object1 and object2 are 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.
At an implementation level, this will usually mean that the objects are pointers to the same storage or are the same immediate value. An extension is made for built-in number classes and characters. Because these objects are not mutable (i.e., cannot be changed), two of the same class with the same value will always be the same (and will thus be indistinguishable to programs).
~== [Function]
Compares two objects for nonidentity.
- Signature:
-
object1 ~== object2⇒boolean - Arguments:
-
- object1
-
An instance of
<object>. - object2
An instance of
<object>.
- Values:
-
- boolean
-
An instance of
<boolean>.
- Description:
-
Returns true if object1 and object2 are not identical. It returns false if they are identical.
If both arguments are instances of
<complex>then the result is computed in an implementation-defined way. Otherwise, the result is computed by~(object1 == object2).
= [Open Generic Function]
Compares two objects for equality.
- Signature:
-
object1 = object2⇒boolean - Arguments:
-
- object1
-
An instance of
<object>. - object2
An instance of
<object>.
- Values:
-
- boolean
-
An instance of
<boolean>.
- Description:
-
Returns true if object1 and object2 are equal. Otherwise, it returns false.
Programmers may define methods for
=specialized on classes they define. A programmer may be required to provide an=method when defining subclasses of some predefined classes in order to fullfill the protocol of the class, as described below. For objects that do not have a more specific = method, = returns the same as ==.= is not guaranteed to return. For example, it may not return when called on circular structures or otherwise unbounded structures.
In addition to the sealed domains specified by the methods below,
=is sealed over the following domains:<object>, <symbol>
<symbol>, <object>
<object>, <character>
<character>, <object>
<object>, <boolean>
<boolean>, <object>object1 = object2⇒boolean[G.F. Method]The default method on
=calls==and returns the result returned by==.complex1 = complex2⇒boolean[Sealed G.F. Method]Complex numbers are equal if they have the same mathematical value.
collection1 = collection2⇒boolean[G.F. Method]Two collections are equal if they have identical
key-testfunctions, they have the same keys (as determined by theirkey-testfunctions), the elements at corresponding keys are =, and neither collection is a dotted list.sequence1 = sequence2⇒boolean[G.F. Method]For sequences,
=returns true if sequence1 and sequence2 have the same size and elements with = keys are =, and returns false otherwise.list1 = list2⇒boolean[Sealed G.F. Method]For lists,
=returns true if the two lists are the same size, corresponding elements of list1 and list2 are=and the final tails are=. It returns false otherwise.list = sequence⇒boolean[G.F. Method]sequence = list⇒boolean[G.F. Method]For mixed lists and sequences,
=returns true if the list is not a dotted list, both have the same size, and elements with=keys are=. It returns false otherwise.range1 = range2⇒boolean[Sealed G.F. Method]When called with two ranges,
=always terminates, even if one or both ranges are unbounded in size.
~= [Function]
Compares two objects for inequality.
- Signature:
-
object1 ~= object2⇒boolean - Arguments:
-
- object1
-
An instance of
<object>. - object2
An instance of
<object>.
- Values:
-
- boolean
-
An instance of
<boolean>.
- Description:
-
Returns true if object1 and object2 are not equal. It returns false if they are equal.
If both arguments are instances of
<complex>then the result is computed in an implementation-defined way. Otherwise, the result is computed by the expression~(object1 = object2).
Magnitude Comparisons
< [Open Generic Function]
Returns true if its first operand is less than its second operand.
- Signature:
-
object1 < object2⇒boolean - Arguments:
-
- object1
-
An instance of
<object>. - object2
An instance of
<object>.
- Values:
-
- boolean
-
An instance of
<boolean>.
- Description:
-
Returns true if object1 is less than object2.
The generic function
<is sealed over the domain(<complex>, <complex>).real1 < real2⇒boolean[Sealed G.F. Method]Built-in real numbers are compared by mathematical value.
character1 < character2⇒boolean[Sealed G.F. Method]Characters are compared by the ordinal value of the underlying character set. Character case is significant.
string1 < string2⇒boolean[G.F. Method]When both arguments are strings,
<compares strings by comparing elements from left to right, using<and=on corresponding elements, and stopping when the elements are not=. If one string is a strict prefix of the other, the shorter string is considered thesmaller
one.For variations on string comparison (such as comparisons that ignore case), different comparison operators must be used.
> [Function]
Returns true if its first operand is greater than its second operand.
- Signature:
-
object1 > object2⇒boolean - Arguments:
-
- object1
-
An instance of
<object>. - object2
An instance of
<object>.
- Values:
-
- boolean
-
An instance of
<boolean>.
- Description:
-
Returns true if object1 is greater than object2.
If both arguments are instances of
<complex>then the result is computed in an implementation-defined way. Otherwise, the result is computed by the expression(object2 < object1).
<= [Function]
Returns true if its first operand is less than or equal to its second operand.
- Signature:
-
object1 <= object2⇒boolean - Arguments:
-
- object1
-
An instance of
<object>. - object2
An instance of
<object>.
- Values:
-
- boolean
-
An instance of
<boolean>.
- Description:
-
Returns true if object1 is less than or equal to object2.
If both arguments are instances of
<complex>then the result is computed in an implementation-defined way. Otherwise, the result is computed by the expression~(object2 < object1).
>= [Function]
Returns true if its first operand is greater than or equal to its second operand.
- Signature:
-
object1 >= object2⇒boolean - Arguments:
-
- object1
-
An instance of
<object>. - object2
An instance of
<object>.
- Values:
-
- boolean
-
An instance of
<boolean>.
- Description:
-
Returns true if object1 is greater than or equal to object2.
If both arguments are instances of
<complex>then the result is computed in an implementation-defined way. Otherwise, the result is computed by the expression~(object1 < object2).
min [Function]
Returns the least of its arguments.
- Signature:
-
min object1 #rest objects⇒object2 - Arguments:
-
- object1
-
An instance of
<object>. - objects
Zero or more instances of
<object>.
- Values:
-
- object2
-
An instance of
<object>.
- Description:
-
Returns the least of its arguments.
minoperates by calling<, and therefore is applicable to any objects for which<is defined.
max [Function]
Returns the greatest of its arguments.
- Signature:
-
max object1 #rest objects⇒object2 - Arguments:
-
- object1
-
An instance of
<object>. - objects
Zero or more instances of
<object>.
- Values:
-
- object2
-
An instance of
<object>.
- Description:
-
Returns the greatest of its arguments.
maxoperates by calling<, and therefore is applicable to any objects for which<is defined.