commit 47e59378e2fbab3ac72646bcae6074e4dff0996d
parent 1e0d807a102014be0a621fe6d84dc74925213d58
Author: Wolfgang Corcoran-Mathe <wcm@sigwinch.xyz>
Date: Fri, 2 Feb 2024 13:58:09 -0500
Numbers: Texify, part 1.
Diffstat:
2 files changed, 187 insertions(+), 93 deletions(-)
diff --git a/doc/r7rs-small/procedures/numbers.texinfo b/doc/r7rs-small/procedures/numbers.texinfo
@@ -23,15 +23,19 @@ numbers.
Mathematically, numbers are arranged into a tower of subtypes in which each level is a
subset of the level above it:
- number
- complex number
- real number
- rational number
- integer
-
-For example, 3 is an integer. Therefore 3 is also a rational, a real, and a complex number.
-The same is true of the Scheme numbers that model 3. For Scheme numbers, these types
-are defined by the predicates number?, complex?, real?, rational?, and integer?.
+@display
+number
+complex number
+real number
+rational number
+integer
+@end display
+
+For example, 3 is an integer. Therefore 3 is also a rational,
+a real, and a complex number. The same is true of the Scheme numbers
+that model 3. For Scheme numbers, these types are defined by the
+predicates @code{number?}, @code{complex?}, @code{real?}, @code{rational?},
+and @code{integer?}.
There is no simple relationship between a number's type and its representation inside a
computer. Although most implementations of Scheme will offer at least two different
@@ -53,12 +57,17 @@ rational and therefore inexact approximations. In order to catch uses of inexact
where exact numbers are required, Scheme explicitly distinguishes exact from inexact
numbers. This distinction is orthogonal to the dimension of type.
-A Scheme number is exact if it was written as an exact constant or was derived from exact
-numbers using only exact operations. A number is inexact if it was written as an inexact
-constant, if it was derived using inexact ingredients, or if it was derived using inexact
-operations. Thus inexactness is a contagious property of a number. In particular, an exact
-complex number has an exact real part and an exact imaginary part; all other complex
-numbers are inexact complex numbers.
+A Scheme number is
+@dfn{exact} if it was written as an exact constant or was derived from
+exact numbers using only exact operations. A number is
+@dfn{inexact} if it was written as an inexact constant,
+if it was
+derived using @dfn{inexact} ingredients, or if it was derived using
+@dfn{inexact} operations. Thus inexactness is a contagious
+property of a number.
+In particular, an @dfn{exact complex number} has an exact real part
+and an exact imaginary part; all other complex numbers are @dfn{inexact
+complex numbers}.
If two implementations produce exact results for a computation that did not involve
inexact intermediate results, the two ultimate results will be mathematically equal. This is
@@ -66,19 +75,19 @@ generally not true of computations involving inexact numbers since approximate
methods such as floating-point arithmetic may be used, but it is the duty of each
implementation to make the result as close as practical to the mathematically ideal result.
-Rational operations such as + should always produce exact results when given exact
+Rational operations such as @code{+} should always produce exact results when given exact
arguments. If the operation is unable to produce an exact result, then it may either report
the violation of an implementation restriction or it may silently coerce its result to an
-inexact value. However, (/ 3 4) must not return the mathematically incorrect value 0. See
-section 6.2.3.
+inexact value. However, @code{(/ 3 4)} must not return the mathematically incorrect value @code{0}.
+@xref{Implementation restrictions}.
-Except for exact, the operations described in this section must generally return inexact
+Except for @code{exact}, the operations described in this section must generally return inexact
results when given any inexact arguments. An operation may, however, return an exact
result if it can prove that the value of the result is unaffected by the inexactness of its
arguments. For example, multiplication of any number by an exact zero may produce an
exact zero result, even if the other argument is inexact.
-Specifically, the expression (* 0 +inf.0) may return 0, or +nan.0, or report that inexact
+Specifically, the expression @code{(* 0 +inf.0)} may return @code{0}, or @code{+nan.0}, or report that inexact
numbers are not supported, or report that non-rational real numbers are not supported,
or fail silently or noisily in other implementation-specific ways.
@@ -86,7 +95,7 @@ or fail silently or noisily in other implementation-specific ways.
@subsection Implementation restrictions
Implementations of Scheme are not required to implement the whole tower of subtypes
-given in section 6.2.1, but they must implement a coherent subset consistent with both
+given in @ref{Numerical types}, but they must implement a coherent subset consistent with both
the purposes of the implementation and the spirit of the Scheme language. For example,
implementations in which all numbers are real, or in which non-real numbers are always
inexact, or in which exact numbers are always integer, are still quite useful.
@@ -102,34 +111,107 @@ format. Furthermore, the gaps between the representable inexact integers and rat
are likely to be very large in such an implementation as the limits of this range are
approached.
-An implementation of Scheme must support exact integers throughout the range of
-numbers permitted as indexes of lists, vectors, bytevectors, and strings or that result from
-computing the length of one of these. The length, vector-length, bytevector-length, and
-string-length procedures must return an exact integer, and it is an error to use anything
-but an exact integer as an index. Furthermore, any integer constant within the index
-range, if expressed by an exact integer syntax, must be read as an exact integer,
-regardless of any implementation restrictions that apply outside this range. Finally, the
-procedures listed below will always return exact integer results provided all their
-arguments are exact integers and the mathematically expected results are representable
-as exact integers within the implementation:
-
-- *
-+ abs
-ceiling denominator
-exact-integer-sqrt expt
-floor floor/
-floor-quotient floor-remainder
-gcd lcm
-max min
-modulo numerator
-quotient rationalize
-remainder round
-square truncate
-truncate/ truncate-quotient
-truncate-remainder
+An implementation of Scheme must support exact integers
+throughout the range of numbers permitted as indexes of
+lists, vectors, bytevectors, and strings or that result from computing the length of
+one of these. The @code{length}, @code{vector-length},
+@code{bytevector-length}, and @code{string-length} procedures must return an exact
+integer, and it is an error to use anything but an exact integer as an
+index. Furthermore, any integer constant within the index range, if
+expressed by an exact integer syntax, must be read as an exact
+integer, regardless of any implementation restrictions that apply
+outside this range. Finally, the procedures listed below will always
+return exact integer results provided all their arguments are exact integers
+and the mathematically expected results are representable as exact integers
+within the implementation:
+
+@itemize @w{}
+@item
+@code{-}
+
+@item
+@code{*}
+
+@item
+@code{+}
+
+@item
+@code{abs}
+
+@item
+@code{ceiling}
+
+@item
+@code{denominator}
+
+@item
+@code{exact-integer-sqrt}
+
+@item
+@code{expt}
+
+@item
+@code{floor}
+
+@item
+@code{floor/}
+
+@item
+@code{floor-quotient}
+
+@item
+@code{floor-remainder}
+
+@item
+@code{gcd}
+
+@item
+@code{lcm}
+
+@item
+@code{max}
+
+@item
+@code{min}
+
+@item
+@code{modulo}
+
+@item
+@code{numerator}
+
+@item
+@code{quotient}
+
+@item
+@code{rationalize}
+
+@item
+@code{remainder}
+
+@item
+@code{round}
+
+@item
+@code{square}
+
+@item
+@code{truncate}
+
+@item
+@code{truncate/}
+
+@item
+@code{truncate-quotient}
+
+@item
+@code{truncate-remainder}
+
+@end itemize
+
It is recommended, but not required, that implementations support exact integers and
exact rationals of practically unlimited size and precision, and to implement the above
-procedures and the / procedure in such a way that they always return exact results when
+procedures and the @code{/} procedure in such a way that they always return exact results when
given exact arguments. If one of these procedures is unable to deliver an exact result
when given exact arguments, then it may either report a violation of an implementation
restriction or it may silently coerce its result to an inexact number; such a coercion can
@@ -160,9 +242,9 @@ Implementations may provide more than one representation of floating-point numbe
with differing precisions. In an implementation which does so, an inexact result must be
represented with at least as much precision as is used to express any of the inexact
arguments to that operation. Although it is desirable for potentially inexact operations
-such as sqrt to produce exact answers when applied to exact arguments, if an exact
+such as @code{sqrt} to produce exact answers when applied to exact arguments, if an exact
number is operated upon so as to produce an inexact result, then the most precise
-representation available must be used. For example, the value of (sqrt 4) should be 2, but
+representation available must be used. For example, the value of @code{(sqrt 4)} should be @code{2}, but
in an implementation that provides both single and double precision floating point
numbers it may be the latter but must not be the former.
@@ -186,20 +268,20 @@ IEEE 754.
A NaN is regarded as an inexact real (but not rational) number so indeterminate that it
might represent any real value, including positive or negative infinity, and might even be
greater than positive infinity or less than negative infinity. An implementation that does
-not support non-real numbers may use NaN to represent non-real values like (sqrt -1.0)
-and (asin 2.0).
+not support non-real numbers may use NaN to represent non-real values like @code{(sqrt -1.0)}
+and @code{(asin 2.0)}.
A NaN always compares false to any number, including a NaN. An arithmetic operation
where one operand is NaN returns NaN, unless the implementation can prove that the
result would be the same if the NaN were replaced by any rational number. Dividing zero
by zero results in NaN unless both zeros are exact.
-Negative zero is an inexact real value written -0.0 and is distinct (in the sense of eqv?) from
-0.0. A Scheme implementation is not required to distinguish negative zero. If it does,
+Negative zero is an inexact real value written @code{-0.0} and is distinct (in the sense of @code{eqv?}) from
+@code{0.0}. A Scheme implementation is not required to distinguish negative zero. If it does,
however, the behavior of the transcendental functions is sensitive to the distinction in
accordance with IEEE 754. Specifically, in a Scheme implementing both complex numbers
and negative zero, the branch cut of the complex logarithm function is such that
-(imag-part (log -1.0-0.0i)) is −π rather than π.
+@code{(imag-part (log -1.0-0.0i))} is @minus{}@greekpi{} rather than @greekpi{}.
Furthermore, the negation of negative zero is ordinary zero and vice versa. This implies
that the sum of two or more negative zeros is negative, and the result of subtracting
@@ -212,15 +294,16 @@ NaNs, or negative zero.
@node Syntax of numerical constants
@subsection Syntax of numerical constants
-The syntax of the written representations for numbers is described formally in section
-7.1.1. Note that case is not significant in numerical constants.
+The syntax of the written representations for numbers is described formally in
+@ref{Formal syntax}.
+Note that case is not significant in numerical constants.
A number can be written in binary, octal, decimal, or hexadecimal by the use of a radix
-prefix. The radix prefixes are #b(binary), #o(octal), #d(decimal), and #x(hexadecimal). With
+prefix. The radix prefixes are @code{#b} (binary), @code{#o} (octal), @code{#d} (decimal), and @code{#x} (hexadecimal). With
no radix prefix, a number is assumed to be expressed in decimal.
A numerical constant can be specified to be either exact or inexact by a prefix. The
-prefixes are #efor exact, and #ifor inexact. An exactness prefix can appear before or after
+prefixes are @code{#e} for exact, and @code{#i} for inexact. An exactness prefix can appear before or after
any radix prefix that is used. If the written representation of a number has no exactness
prefix, the constant is inexact if it contains a decimal point or an exponent. Otherwise, it is
exact.
@@ -228,50 +311,39 @@ exact.
In systems with inexact numbers of varying precisions it can be useful to specify the
precision of a constant. For this purpose, implementations may accept numerical
constants written with an exponent marker that indicates the desired precision of the
-inexact representation. If so, the letter s, f, d, or l, meaning
-
-short,
-
-single,
-
-double, or
-
-long precision, respectively, can be used in place of e. The default precision has at least as
+inexact representation. If so, the letter @code{s}, @code{f}, @code{d}, or @code{l}, meaning
+@dfn{short},
+@dfn{single},
+@dfn{double}, or
+@dfn{long} precision, respectively, can be used in place of @code{e}. The default precision has at least as
much precision as
-
double, but implementations may allow this default to be set by the user.
-3.14159265358979F0
- Round to single --- 3.141593
-0.6L0
- Extend to long --- .600000000000000 The numbers positive infinity, negative infinity,
-and NaN are written +inf.0, -inf.0 and +nan.0 respectively. NaN may also be written -nan.0.
+@display
+@code{3.14159265358979F0}
+ Round to single --- @code{3.141593}
+@code{0.6L0}
+ Extend to long --- @code{.600000000000000}
+@end display
+
+The numbers positive infinity, negative infinity,
+and NaN are written @code{+inf.0}, @code{-inf.0} and @dfn{+nan.0} respectively. NaN may also be written @code{-nan.0}.
The use of signs in the written representation does not necessarily reflect the underlying
sign of the NaN value, if any. Implementations are not required to support these
numbers, but if they do, they must do so in general conformance with IEEE 754. However,
implementations are not required to support signaling NaNs, nor to provide a way to
distinguish between different NaNs.
-There are two notations provided for non-real complex numbers: the rectangular notation
-
-a+
-
-bi, where
-
-a is the real part and
-
-b is the imaginary part; and the polar notation
-
-r@@θ, where
-
-r is the magnitude and θ is the phase (angle) in radians. These are related by the equation
-a + bi = r cos θ + (r sin θ) i. All of
-
-a,
-
-b,
-
-r, and θ are real numbers.
+There are two notations provided for non-real complex numbers:
+the @dfn{rectangular notation}
+@var{a}@code{+}@var{b}@code{i},
+where @var{a} is the real part and @var{b} is the imaginary part;
+and the @dfn{polar notation}
+@var{r}@code{@@}@var{@greektheta{}}
+where @var{r} is the magnitude and @var{@greektheta{}} is the phase (angle) in radians.
+These are related by the equation
+@var{a}+@var{b}i = @var{r} cos @var{@greektheta{}} + (r sin @var{@greektheta{}})i.
+All of @var{a}, @var{b}, @var{r}, and @var{@greektheta{}} are real numbers.
@node Numerical operations
@subsection Numerical operations
diff --git a/doc/r7rs-small/r7rs-texinfo-macros.texinfo b/doc/r7rs-small/r7rs-texinfo-macros.texinfo
@@ -36,6 +36,17 @@
@end macro
@end iftex
+@c Insert a lower-case pi.
+@macro greekpi
+@U{03c0}
+@end macro
+
+@iftex
+@unmacro greekpi
+@math{\\pi}
+@end macro
+@end iftex
+
@c Insert a lower-case iota.
@macro greekiota {}
@U{03b9}
@@ -47,3 +58,14 @@
@math{\\iota}
@end macro
@end iftex
+
+@c Insert a lower-case theta.
+@macro greektheta
+@U{03b8}
+@end macro
+
+@iftex
+@unmacro greektheta
+@math{\\theta}
+@end macro
+@end iftex
