[Next] [Previous] [Up] [Top] [Contents] [Index]
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 (a = b).
- 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.
Not and Identity
~ [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 true if thing is false. Returns false if 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 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 which 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.
The generic function = is inert over the domain (<complex>, <complex>).
object1 = object2 Þ boolean [G.F. Method]
The default method on = calls == and returns the result returned by ==.
complex1 = complex2 Þ boolean [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-test functions, they have the same keys (as determined by their key-test functions), 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 [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 [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 inert over the domain (<complex>, <complex>).
real1 < real2 Þ boolean [G.F. Method]
Built-in real numbers are compared by mathematical value.
character1 < character2 Þ boolean [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 the "smaller" 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.
min operates 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.
max operates by calling <, and therefore is applicable to any objects for which < is defined.
Dylan Reference Manual - 17 OCT 1995
[Next] [Previous] [Up] [Top] [Contents] [Index]
Generated with Harlequin WebMaker