commit cc4001143d7de4e03485c1c8f5e8b3f4f6e0a184
parent bf3d0faad209b5f305b458d7fbea638e964a1929
Author: Wolfgang Corcoran-Mathe <wcm@sigwinch.xyz>
Date: Fri, 2 Feb 2024 13:10:24 -0500
Equivalence procs.: Further Texify.
Diffstat:
1 file changed, 126 insertions(+), 118 deletions(-)
diff --git a/doc/r7rs-small/procedures/equivalence-predicates.texinfo b/doc/r7rs-small/procedures/equivalence-predicates.texinfo
@@ -1,119 +1,123 @@
@node Equivalence predicates
@section Equivalence predicates
-A predicate is a procedure that always returns a boolean value (#t or #f). An equivalence
-predicate is the computational analogue of a mathematical equivalence relation; it is
-symmetric, reflexive, and transitive. Of the equivalence predicates described in this
-section, eq? is the finest or most discriminating, equal? is the coarsest, and eqv? is
-slightly less discriminating than eq?.
+A @dfn{predicate} is a procedure that always returns a boolean
+value (@code{#t} or @code{#f}). An @dfn{equivalence predicate} is
+the computational analogue of a mathematical equivalence relation; it is
+symmetric, reflexive, and transitive. Of the equivalence predicates
+described in this section, @code{eq?} is the finest or most
+discriminating, @code{equal?} is the coarsest, and @code{eqv?} is
+slightly less discriminating than @code{eq?}.
-@deffn procedure eqv? obj1 obj2
+@deffn procedure eqv? @var{obj@sub{1}} @var{obj@sub{2}}
-The @code{eqv?} procedure defines a useful equivalence relation on objects. Briefly, it returns #t
+The @code{eqv?} procedure defines a useful equivalence relation on objects. Briefly, it returns @code{#t}
if
-
-@var{obj1} and @var{obj2} are normally regarded as the same object. This relation is left slightly open to
+@var{@var{obj@sub{1}}} and @var{@var{obj@sub{2}}} are normally regarded as the same object. This relation is left slightly open to
interpretation, but the following partial specification of @code{eqv?} holds for all implementations
of Scheme.
-The @code{eqv?} procedure returns #t if:
-
-* @var{obj1} and
-
- @var{obj2} are both #t or both #f.
+The @code{eqv?} procedure returns @code{#t} if:
-* @var{obj1} and
+@itemize
- @var{obj2} are both symbols and are the same symbol according to the symbol=? procedure
- (section 6.5).
+@item
+@var{@var{obj@sub{1}}} and
+ @var{@var{obj@sub{2}}} are both @code{#t} or both @code{#f}.
-* @var{obj1} and
+@item
+@var{@var{obj@sub{1}}} and
+ @var{@var{obj@sub{2}}} are both symbols and are the same symbol according to the @code{symbol=?} procedure
+ (@ref{Symbols}).
- @var{obj2} are both exact numbers and are numerically equal (in the sense of =).
+@item
+@var{@var{obj@sub{1}}} and
+ @var{@var{obj@sub{2}}} are both exact numbers and are numerically equal (in the sense of @code{=}).
-* @var{obj1} and
-
- @var{obj2} are both inexact numbers such that they are numerically equal (in the sense of =)
+@item
+@var{@var{obj@sub{1}}} and
+ @var{@var{obj@sub{2}}} are both inexact numbers such that they are numerically equal (in the sense of @code{=})
and they yield the same results (in the sense of @code{eqv?}) when passed as arguments to any
other procedure that can be defined as a finite composition of Scheme's standard
arithmetic procedures, provided it does not result in a NaN value.
-* @var{obj1} and
-
- @var{obj2} are both characters and are the same character according to the char=? procedure
- (section 6.6).
-
-* @var{obj1} and
-
- @var{obj2} are both the empty list.
-
-* @var{obj1} and
-
- @var{obj2} are pairs, vectors, bytevectors, records, or strings that denote the same location in
- the store (section 3.4).
-
-* @var{obj1} and
-
- @var{obj2} are procedures whose location tags are equal (section 4.1.4).
-
-The @code{eqv?} procedure returns #f if:
+@item
+@var{@var{obj@sub{1}}} and
+ @var{@var{obj@sub{2}}} are both characters and are the same character according to the @code{char=?} procedure
+ (@ref{Characters}).
-* @var{obj1} and
+@item
+@var{@var{obj@sub{1}}} and
+ @var{@var{obj@sub{2}}} are both the empty list.
- @var{obj2} are of different types (section 3.2).
+@item
+@var{@var{obj@sub{1}}} and
+ @var{@var{obj@sub{2}}} are pairs, vectors, bytevectors, records, or strings that denote the same location in
+ the store (@ref{Storage model}).
-* one of
+@item
+@var{@var{obj@sub{1}}} and
+ @var{@var{obj@sub{2}}} are procedures whose location tags are equal (@ref{Procedures}).
- @var{obj1} and
+@end itemize
- @var{obj2} is #t but the other is #f.
+The @code{eqv?} procedure returns @code{#f} if:
-* @var{obj1} and
+@itemize
- @var{obj2} are symbols but are not the same symbol according to the symbol=? procedure
- (section 6.5).
+@item
+@var{@var{obj@sub{1}}} and
+ @var{@var{obj@sub{2}}} are of different types (@ref{Disjointness of types}).
-* one of
+@item
+one of
+ @var{@var{obj@sub{1}}} and
+ @var{@var{obj@sub{2}}} is @code{#t} but the other is @code{#f}.
- @var{obj1} and
+@item
+@var{@var{obj@sub{1}}} and
+ @var{@var{obj@sub{2}}} are symbols but are not the same symbol according to the @code{symbol=?} procedure
+ (@ref{Symbols}).
- @var{obj2} is an exact number but the other is an inexact number.
+@item
+one of
+ @var{@var{obj@sub{1}}} and
+ @var{@var{obj@sub{2}}} is an exact number but the other is an inexact number.
-* @var{obj1} and
+@item
+@var{@var{obj@sub{1}}} and
+ @var{@var{obj@sub{2}}} are both exact numbers and are numerically unequal (in the sense of @code{=}).
- @var{obj2} are both exact numbers and are numerically unequal (in the sense of =).
-
-* @var{obj1} and
-
- @var{obj2} are both inexact numbers such that either they are numerically unequal (in the
- sense of =), or they do not yield the same results (in the sense of @code{eqv?}) when passed as
+@item
+@var{@var{obj@sub{1}}} and
+ @var{@var{obj@sub{2}}} are both inexact numbers such that either they are numerically unequal (in the
+ sense of @code{=}), or they do not yield the same results (in the sense of @code{eqv?}) when passed as
arguments to any other procedure that can be defined as a finite composition of
Scheme's standard arithmetic procedures, provided it does not result in a NaN value. As
an exception, the behavior of @code{eqv?} is unspecified when both
+ @var{@var{obj@sub{1}}} and
+ @var{@var{obj@sub{2}}} are NaN.
- @var{obj1} and
-
- @var{obj2} are NaN.
-
-* @var{obj1} and
-
- @var{obj2} are characters for which the char=? procedure returns #f.
-
-* one of
+@item
+@var{@var{obj@sub{1}}} and
+ @var{@var{obj@sub{2}}} are characters for which the @code{char=?} procedure returns @code{#f}.
- @var{obj1} and
+@item
+one of
+ @var{@var{obj@sub{1}}} and
+ @var{@var{obj@sub{2}}} is the empty list but the other is not.
- @var{obj2} is the empty list but the other is not.
+@item
+@var{@var{obj@sub{1}}} and
+ @var{@var{obj@sub{2}}} are pairs, vectors, bytevectors, records, or strings that denote distinct locations.
-* @var{obj1} and
-
- @var{obj2} are pairs, vectors, bytevectors, records, or strings that denote distinct locations.
-
-* @var{obj1} and
-
- @var{obj2} are procedures that would behave differently (return different values or have
+@item
+@var{@var{obj@sub{1}}} and
+ @var{@var{obj@sub{2}}} are procedures that would behave differently (return different values or have
different side effects) for some arguments.
+@end itemize
+
@example
(eqv? 'a 'a) @result{} #t
(eqv? 'a 'b) @result{} #f
@@ -135,22 +139,22 @@ do not fully specify the behavior of @code{eqv?}. All that can be said about suc
value returned by @code{eqv?} must be a boolean.
@example
-(eqv? "" "") @result{} unspecified
-(eqv? '#() '#()) @result{} unspecified
+(eqv? "" "") @result{} @r{unspecified}
+(eqv? '#() '#()) @result{} @r{unspecified}
(eqv? (lambda (x) x)
- (lambda (x) x)) @result{} unspecified
+ (lambda (x) x)) @result{} @r{unspecified}
(eqv? (lambda (x) x)
- (lambda (y) y)) @result{} unspecified
-(eqv? 1.0e0 1.0f0) @result{} unspecified
-(eqv? +nan.0 +nan.0) @result{} unspecified
+ (lambda (y) y)) @result{} @r{unspecified}
+(eqv? 1.0e0 1.0f0) @result{} @r{unspecified}
+(eqv? +nan.0 +nan.0) @result{} @r{unspecified}
@end example
-Note that (@code{eqv?} 0.0 -0.0) will return #f if negative zero
-is distinguished, and #t if negative zero is not distinguished.
+Note that @code{(eqv? 0.0 -0.0)} will return @code{#f} if negative zero
+is distinguished, and @code{#t} if negative zero is not distinguished.
The next set of examples shows the use of @code{eqv?} with procedures that have local state. The
-gen-counter procedure must return a distinct procedure every time, since each
-procedure has its own internal counter. The gen-loser procedure, however, returns
+@code{gen-counter} procedure must return a distinct procedure every time, since each
+procedure has its own internal counter. The @code{gen-loser} procedure, however, returns
operationally equivalent procedures each time, since the local state does not affect the
value or side effects of the procedures. However, @code{eqv?} may or may not detect this
equivalence.
@@ -171,12 +175,12 @@ equivalence.
(let ((g (gen-loser)))
(eqv? g g)) @result{} #t
(eqv? (gen-loser) (gen-loser))
- @result{} unspecified
+ @result{} @r{unspecified}
(letrec ((f (lambda () (if (eqv? f g) 'both 'f)))
(g (lambda () (if (eqv? f g) 'both 'g))))
(eqv? f g))
- @result{} unspecified
+ @result{} @r{unspecified}
(letrec ((f (lambda () (if (eqv? f g) 'f 'both)))
(g (lambda () (if (eqv? f g) 'g 'both))))
@@ -190,9 +194,9 @@ appropriate. Thus the value of @code{eqv?} on constants is sometimes
implementation-dependent.
@example
-(eqv? '(a) '(a)) @result{} unspecified
-(eqv? "a" "a") @result{} unspecified
-(eqv? '(b) (cdr '(a b))) @result{} unspecified
+(eqv? '(a) '(a)) @result{} @r{unspecified}
+(eqv? "a" "a") @result{} @r{unspecified}
+(eqv? '(b) (cdr '(a b))) @result{} @r{unspecified}
(let ((x '(a)))
(eqv? x x)) @result{} #t
@end example
@@ -206,33 +210,37 @@ or bit pattern to represent both.
Note: If inexact numbers are represented as IEEE binary floating-point numbers, then
an implementation of @code{eqv?} that simply compares equal-sized inexact numbers for
bitwise equality is correct by the above definition.
+
@end deffn
-@deffn procedure eq? obj1 obj2
+@deffn procedure eq? @var{obj@sub{1}} @var{obj@sub{2}}
-The @code{eq?} procedure is similar to eqv? except that in some cases it is capable of discerning
-distinctions finer than those detectable by eqv?. It must always return #f when eqv? also
-would, but may return #f in some cases where eqv? would return #t.
+The @code{eq?} procedure is similar to @code{eqv?} except that in some cases it is
+capable of discerning distinctions finer than those detectable by
+@code{eqv?}. It must always return @code{#f} when @code{eqv?} also
+would, but may return @code{#f} in some cases where @code{eqv?} would return @code{#t}.
-On symbols, booleans, the empty list, pairs, and records, and also on non-empty strings,
-vectors, and bytevectors, @code{eq?} and eqv? are guaranteed to have the same behavior. On
-procedures, @code{eq?} must return true if the arguments' location tags are equal. On numbers
-and characters, @code{eq?}'s behavior is implementation-dependent, but it will always return
-either true or false. On empty strings, empty vectors, and empty bytevectors, @code{eq?} may also
-behave differently from eqv?.
+On symbols, booleans, the empty list, pairs, and records,
+and also on non-empty
+strings, vectors, and bytevectors, @code{eq?} and @code{eqv?} are guaranteed to have the same
+behavior. On procedures, @code{eq?} must return true if the arguments' location
+tags are equal. On numbers and characters, @code{eq?}'s behavior is
+implementation-dependent, but it will always return either true or
+false. On empty strings, empty vectors, and empty bytevectors, @code{eq?} may also behave
+differently from @code{eqv?}.
@example
(eq? 'a 'a) @result{} #t
-(eq? '(a) '(a)) @result{} unspecified
+(eq? '(a) '(a)) @result{} @r{unspecified}
(eq? (list 'a) (list 'a)) @result{} #f
-(eq? "a" "a") @result{} unspecified
-(eq? "" "") @result{} unspecified
+(eq? "a" "a") @result{} @r{unspecified}
+(eq? "" "") @result{} @r{unspecified}
(eq? '() '()) @result{} #t
-(eq? 2 2) @result{} unspecified
-(eq? #\A #\A) @result{} unspecified
+(eq? 2 2) @result{} @r{unspecified}
+(eq? #\A #\A) @result{} @r{unspecified}
(eq? car car) @result{} #t
(let ((n (+ 2 3)))
- (eq? n n)) @result{} unspecified
+ (eq? n n)) @result{} @r{unspecified}
(let ((x '(a)))
(eq? x x)) @result{} #t
(let ((x '#()))
@@ -242,21 +250,21 @@ behave differently from eqv?.
@end example
Rationale: It will usually be possible to implement @code{eq?} much more efficiently than
- eqv?, for example, as a simple pointer comparison instead of as some more
- complicated operation. One reason is that it is not always possible to compute eqv?
+ @code{eqv?}, for example, as a simple pointer comparison instead of as some more
+ complicated operation. One reason is that it is not always possible to compute @code{eqv?}
of two numbers in constant time, whereas @code{eq?} implemented as pointer comparison
will always finish in constant time.
@end deffn
-@deffn procedure equal? obj1 obj2
+@deffn procedure equal? @var{obj@sub{1}} @var{obj@sub{2}}
The @code{equal?} procedure, when applied to pairs, vectors, strings and bytevectors, recursively
-compares them, returning #t when the unfoldings of its arguments into (possibly infinite)
-trees are equal (in the sense of @code{equal?}) as ordered trees, and #f otherwise. It returns the
-same as eqv? when applied to booleans, symbols, numbers, characters, ports,
-procedures, and the empty list. If two objects are eqv?, they must be @code{equal?} as well. In all
-other cases, @code{equal?} may return either #t or #f. Even if its arguments are circular data
+compares them, returning @code{#t} when the unfoldings of its arguments into (possibly infinite)
+trees are equal (in the sense of @code{equal?}) as ordered trees, and @code{#f} otherwise. It returns the
+same as @code{eqv?} when applied to booleans, symbols, numbers, characters, ports,
+procedures, and the empty list. If two objects are @code{eqv?}, they must be @code{equal?} as well. In all
+other cases, @code{equal?} may return either @code{#t} or @code{#f}. Even if its arguments are circular data
structures, @code{equal?} must always terminate.
@example
@@ -271,8 +279,8 @@ structures, @code{equal?} must always terminate.
(equal? '#1=(a b . #1#)
'#2=(a b a b . #2#)) @result{} #t
(equal? (lambda (x) x)
- (lambda (y) y)) @result{} unspecified
+ (lambda (y) y)) @result{} @r{unspecified}
@end example
-Note: A rule of thumb is that objects are generally equal? if they print the same.
+Note: A rule of thumb is that objects are generally @code{equal?} if they print the same.
@end deffn
