commit a76250d0b19ba815de41cac37a2390f104cd57e0
parent ad8f528d5e290280db1ff5ac18b5e2adb9ccc779
Author: Wolfgang Corcoran-Mathe <wcm@sigwinch.xyz>
Date: Sat, 3 Feb 2024 01:49:24 -0500
Numbers: Texify, part 3.
Diffstat:
2 files changed, 202 insertions(+), 178 deletions(-)
diff --git a/doc/r7rs-small/procedures/numbers.texinfo b/doc/r7rs-small/procedures/numbers.texinfo
@@ -597,7 +597,7 @@ number-theoretic (integer) division. It is an error if @var{n} is zero.
The procedures ending in @code{/} return two integers; the other
procedures return an integer. All the procedures compute a
quotient @var{n@sub{q}} and remainder @var{n@sub{r}} such that
-@var{n@sub{1}} = @var{n@sub{2}}@var{n@sub{q}} + @var{n@sub{r}}. For each of the
+@var{n@sub{1}} = @var{n@sub{2}}@var{n@sub{q}} + @var{n@sub{r}}. For each of the
division operators, there are three procedures defined as follows:
@c This is hideous. Can we do any better?
@@ -738,7 +738,7 @@ procedure. If the argument is infinite or a NaN, then it is returned.
The @code{rationalize} procedure returns the @emph{simplest} rational number
differing from @var{x} by no more than @var{y}. A rational number @var{r@sub{1}} is
@emph{simpler} than another rational number
-@var{r@sub{2}} if @math{r_1 = p_1/q_1} and @math{r_2 = p_2/q_2} (in lowest terms) and
+@var{r@sub{2}} if @math{r_1 = p_1/q_1} and @math{r_2 = p_2/q_2} (in lowest terms) and
@math{|p_1| \leq |p_2|} and @math{|q_1| \leq |q_2|}. Thus 3/5 is simpler than 4/7.
Although not all rationals are comparable in this ordering (consider 2/7
and 3/5), any interval contains a rational number that is simpler than
@@ -751,11 +751,12 @@ all.
(exact .3) 1/10) @result{} 1/3 ; exact
(rationalize .3 1/10) @result{} #i1/3 ; inexact
@end example
+
@end deffn
-@deffn {inexact library procedure} exp z
+@deffn {inexact library procedure} exp z
@deffnx {inexact library procedure} log z
-@deffnx {inexact library procedure} log z1 z2
+@deffnx {inexact library procedure} log z@sub{1} z@sub{2}
@deffnx {inexact library procedure} sin z
@deffnx {inexact library procedure} cos z
@deffnx {inexact library procedure} tan z
@@ -764,200 +765,214 @@ all.
@deffnx {inexact library procedure} atan z
@deffnx {inexact library procedure} atan y x
-These procedures compute the usual transcendental functions. The log procedure
-computes the natural logarithm of
-
-z (not the base ten logarithm) if a single argument is given, or the base-
-
-z2 logarithm of
-
-z1 if two arguments are given. The asin, acos, and atan procedures compute arcsine (sin
-−1), arc-cosine (cos −1), and arctangent (tan −1), respectively. The two-argument variant
-of atan computes (angle (make-rectangular
-
-x
-
-y)) (see below), even in implementations that don't support complex numbers.
-
-In general, the mathematical functions log, arcsine, arc-cosine, and arctangent are
-multiply defined. The value of log z is defined to be the one whose imaginary part lies in
-the range from −π (inclusive if -0.0 is distinguished, exclusive otherwise) to π (inclusive).
-The value of log 0 is mathematically undefined. With log defined this way, the values of
-sin −1z, cos −1z, and tan −1z are according to the following formulæ:
-
- sin −1z = −i log (i z + (1 −
- z2)1/2)
-
- cos −1z = π/ 2 − sin −1z
-
- tan −1z = (log (1 + i z) − log (1 − i z)) /
- (2 i)
-
-However, (log 0.0) returns -inf.0 (and (log -0.0) returns -inf.0+πi) if the implementation
-supports infinities (and -0.0).
-
-The range of (atan
-
-y
-
-x) is as in the following table. The asterisk (*) indicates that the entry applies to
+These procedures
+compute the usual transcendental functions. The @code{log} procedure
+computes the natural logarithm of @var{z} (not the base ten logarithm)
+if a single argument is given, or the base-@var{z@sub{2}} logarithm of @var{z@sub{1}}
+if two arguments are given.
+The @code{asin}, @code{acos}, and @code{atan} procedures compute arcsine (sin@sup{@minus{}1}),
+arc-cosine (cos@sup{@minus{}1}), and arctangent (tan@sup{@minus{}1}), respectively.
+The two-argument variant of @code{atan} computes @code{(angle
+(make-rectangular @var{x} @var{y}))} (see below), even in implementations
+that don't support complex numbers.
+
+In general, the mathematical functions log, arcsine, arc-cosine, and
+arctangent are multiply defined.
+The value of log @var{z} is defined to be the one whose imaginary part
+lies in the range from @minus{}@greekpi (inclusive if @code{-0.0} is distinguished,
+exclusive otherwise) to @greekpi (inclusive).
+The value of log 0 is mathematically undefined.
+With log defined this way, the values of sin@sup{@minus{}1} @var{z},
+cos@sup{@minus{}1} @var{z},
+and tan@sup{@minus{}1} @var{z} are according to the following formul@ae{}:
+
+@displaymath
+\sin^{-1} z = -i \log (i z + \sqrt{1 - z^2})
+@end displaymath
+
+@displaymath
+\cos^{-1} z = \pi / 2 - \sin^{-1} z
+@end displaymath
+
+@displaymath
+\tan^{-1} z = (\log (1 + i z) - \log (1 - i z)) / (2 i)
+@end displaymath
+
+However, @code{(log 0.0)} returns @code{-inf.0} (and @code{(log -0.0)}
+returns @code{-inf.0+@greekpi{}i}) if the implementation
+supports infinities (and @code{-0.0}).
+
+The range of @code{(atan }@var{y} @var{x}@code{)} is as in the
+following table. The asterisk (*) indicates that the entry applies to
implementations that distinguish minus zero.
- y condition x condition range of result r
- y = 0.0 x > 0.0 0.0
- ∗ y = + 0.0 x > 0.0 + 0.0
- ∗ y = −0.0 x > 0.0 −0.0
- y > 0.0 x > 0.0 0.0 < r < π/2
- y > 0.0 x = 0.0 π/2
- y > 0.0 x < 0.0 π/2 < r < π
- y = 0.0 x < 0 π
- ∗ y = + 0.0 x < 0.0 π
- ∗ y = −0.0 x < 0.0 −π
- y < 0.0 x < 0.0 −π< r< −π/2
- y < 0.0 x = 0.0 −π/2
- y @svar{ 0.0 x } 0.0 −π/2 < r< 0.0
- y = 0.0 x = 0.0 undefined
- ∗ y = + 0.0 x = + 0.0 + 0.0
- ∗ y = −0.0 x = + 0.0 −0.0
- ∗ y = + 0.0 x = −0.0 π
- ∗ y = −0.0 x = −0.0 −π
- ∗ y = + 0.0 x = 0 π/2
- ∗ y = −0.0 x = 0 −π/2
+@multitable @columnfractions .16 .24 .24 .36
+@headitem @tab @var{y} condition @tab @var{x} condition @tab
+ range of result @var{r}
+@item @tab @var{y} = 0.0 @tab @var{x} > 0.0 @tab 0.0
+@item ∗ @tab @var{y} = +0.0 @tab @var{x} > 0.0 @tab +0.0
+@item ∗ @tab @var{y} = @minus{}0.0 @tab @var{x} > 0.0 @tab @minus{}0.0
+@item @tab @var{y} > 0.0 @tab @var{x} > 0.0 @tab
+ 0.0 < @var{r} < @greekpi/2
+@item @tab @var{y} > 0.0 @tab @var{x} = 0.0 @tab @greekpi/2
+@item @tab @var{y} > 0.0 @tab @var{x} < 0.0 @tab
+ @greekpi/2 < @var{r} < @greekpi
+@item @tab @var{y} = 0.0 @tab @var{x} < 0 @tab @greekpi
+@item ∗ @tab @var{y} = +0.0 @tab @var{x} < 0.0 @tab @greekpi
+@item ∗ @tab @var{y} = @minus{}0.0 @tab @var{x} < 0.0 @tab
+ @minus{}@greekpi
+@item @tab @var{y} < 0.0 @tab @var{x} < 0.0 @tab
+ @minus{}@greekpi < @var{r} < @minus{}@greekpi/2
+@item @tab @var{y} < 0.0 @tab @var{x} = 0.0 @tab @minus{}@greekpi/2
+@item @tab @var{y} < 0.0 @tab @var{x} > 0.0 @tab
+ @minus{}@greekpi/2 < @var{r}< 0.0
+@item @tab @var{y} = 0.0 @tab @var{x} = 0.0 @tab undefined
+@item ∗ @tab @var{y} = +0.0 @tab @var{x} = +0.0 @tab +0.0
+@item ∗ @tab @var{y} = @minus{}0.0 @tab @var{x} = +0.0 @tab @minus{}0.0
+@item ∗ @tab @var{y} = +0.0 @tab @var{x} = @minus{}0.0 @tab @greekpi
+@item ∗ @tab @var{y} = @minus{}0.0 @tab @var{x} = @minus{}0.0 @tab
+ @minus{}@greekpi
+@item ∗ @tab @var{y} = +0.0 @tab @var{x} = 0 @tab
+ @greekpi/2
+@item ∗ @tab @var{y} = @minus{}0.0 @tab @var{x} = 0 @tab
+ @minus{}@greekpi/2
+@end multitable
+
The above specification follows [34], which in turn cites [26]; refer to these sources for
more detailed discussion of branch cuts, boundary conditions, and implementation of
these functions. When it is possible, these procedures produce a real result from a real
argument.
+
@end deffn
@deffn procedure square z
-Returns the square of z. This is equivalent to @code{(* z z)}.
+Returns the square of z. This is equivalent to @code{(* }@var{z} @var{z}@code{)}.
@example
(square 42) @result{} 1764
(square 2.0) @result{} 4.0
@end example
+
@end deffn
@deffn {inexact library procedure} sqrt z
-Returns the principal square root of
-
-z. The result will have either a positive real part, or a zero real part and a non-negative
+Returns the principal square root of @var{z}. The result will have either a positive real part, or a zero real part and a non-negative
imaginary part.
@example
(sqrt 9) @result{} 3
(sqrt -1) @result{} +i
@end example
+
@end deffn
@deffn procedure exact-integer-sqrt k
-Returns two non-negative exact integers s and r where
-
-k = s2 + r and
-
-k < (s + 1)2.
+Returns two non-negative exact integers @var{s} and @var{r} where
+@var{k} = @var{s}@sup{2} + @var{r} and @var{k} < (@var{s} + 1)@sup{2}.
@example
(exact-integer-sqrt 4) @result{} 2 0
(exact-integer-sqrt 5) @result{} 2 1
@end example
-@end deffn
-@deffn procedure expt z1 z2
-
-Returns
+@end deffn
-z1 raised to the power
+@deffn procedure expt z@sub{1} z@sub{2}
-z2. For nonzero
+Returns z@sub{1} raised to the power z@sub{2}. For nonzero
+z@sub{1}, this is
-z1, this is
+@displaymath
+{z_1}^{z_2} = e^{z_2 \log {z_1}}
+@end displaymath
- z1 z2 = ez2 log z1
+The value of 0@sup{@var{z}} is 1 if @code{(zero? }@var{z}@code{)}, 0 if
+@code{(real-part }@var{z}@code{)} is positive, and an error otherwise.
+Similarly for 0.0@sup{@var{z}}, with inexact results.
-The value of 0z is 1 if (zero? z), 0 if (real-part z) is positive, and an error otherwise.
-Similarly for 0.0z, with inexact results.
@end deffn
-@deffn {complex library procedure} make-rectangular x1 x2
-@deffnx {complex library procedure} make-polar x3 x4
+@deffn {complex library procedure} make-rectangular x@sub{1} x@sub{2}
+@deffnx {complex library procedure} make-polar x@sub{3} x@sub{4}
@deffnx {complex library procedure} real-part z
@deffnx {complex library procedure} imag-part z
@deffnx {complex library procedure} magnitude z
@deffnx {complex library procedure} angle z
-Let
-
-x1,
+Let @var{x@sub{1}}, @var{x@sub{2}}, @var{x@sub{3}}, and @var{x@sub{4}}
+be real numbers and @var{z} be a complex number such that
-x2,
-
-x3, and
-
-x4 be real numbers and
-
-z be a complex number such that
-
- z = x1 + x2 i = x3 ·
- ei
- x4
+@displaymath
+z = x_1 + x_{2}i = x_3 \cdot e^{i x_4}
+@end displaymath
Then all of
@example
-(make-rectangular x1 x2) @result{} z
-(make-polar x3 x4) @result{} z
-(real-part z) @result{} x1
-(imag-part z) @result{} x2
-(magnitude z) @result{} |x3|
-(angle z) @result{} xangle
+(make-rectangular @r{@var{x@sub{1}} @var{x@sub{2}}}) @result{} z
+(make-polar @r{@var{x@sub{3}} @var{x@sub{4}}}) @result{} z
+(real-part z) @result{} @r{@var{x@sub{1}}}
+(imag-part z) @result{} @r{@var{x@sub{2}}}
+(magnitude z) @result{} |@r{@var{x@sub{3}}}|
+(angle z) @result{} @r{@var{x}@sub{angle}}
@end example
-are true, where −π≤xangle ≤π with xangle =
+are true, where @minus{}@greekpi{} @leq{} @var{x@sub{angle}} @leq{}
+@greekpi{} with @var{x@sub{angle}} = @var{x@sub{4}} + 2@greekpi{}@var{n}
+for some integer @var{n}.
-x4 + 2πn for some integer n.
+The @code{make-polar} procedure may return an inexact complex number even if its
+arguments are exact.
+The @code{real-part} and @code{imag-part} procedures may return exact real
+numbers when applied to an inexact complex number if the corresponding
+argument passed to @code{make-rectangular} was exact.
-The make-polar procedure may return an inexact complex number even if its arguments
-are exact. The real-part and imag-part procedures may return exact real numbers when
-applied to an inexact complex number if the corresponding argument passed to
-make-rectangular was exact.
+The @code{magnitude} procedure is the same as @code{abs} for a real argument,
+but @code{abs} is in the base library, whereas
+@code{magnitude} is in the optional complex library.
-Rationale: The magnitude procedure is the same as abs for a real argument, but abs
-is in the base library, whereas magnitude is in the optional complex library.
@end deffn
@deffn procedure inexact z
@deffnx procedure exact z
-The procedure inexact returns an inexact representation of
-
-z. The value returned is the inexact number that is numerically closest to the argument.
-For inexact arguments, the result is the same as the argument. For exact complex
-numbers, the result is a complex number whose real and imaginary parts are the result
-of applying inexact to the real and imaginary parts of the argument, respectively. If an
-exact argument has no reasonably close inexact equivalent (in the sense of =), then a
-violation of an implementation restriction may be reported.
-
-The procedure exact returns an exact representation of
+The procedure @code{inexact} returns an inexact representation of @var{z}.
+The value returned is the
+inexact number that is numerically closest to the argument.
+For inexact arguments, the result is the same as the argument. For exact
+complex numbers, the result is a complex number whose real and imaginary
+parts are the result of applying @code{inexact} to the real
+and imaginary parts of the argument, respectively.
+If an exact argument has no reasonably close inexact equivalent
+(in the sense of @code{=}),
+then a violation of an implementation restriction may be reported.
+
+The procedure @code{exact} returns an exact representation of
+@var{z}. The value returned is the exact number that is numerically
+closest to the argument.
+For exact arguments, the result is the same as the argument. For inexact
+non-integral real arguments, the implementation may return a rational
+approximation, or may report an implementation violation. For inexact
+complex arguments, the result is a complex number whose real and
+imaginary parts are the result of applying @code{exact} to the
+real and imaginary parts of the argument, respectively.
+If an inexact argument has no reasonably close exact equivalent,
+(in the sense of @code{=}),
+then a violation of an implementation restriction may be reported.
+
+These procedures implement the natural one-to-one correspondence between
+exact and inexact integers throughout an
+implementation-dependent range. @xref{Implementation restrictions}.
+
+Note:
+These procedures were known in @rfivers{} as @code{exact->inexact} and
+@code{inexact->exact}, respectively, but they have always accepted
+arguments of any exactness. The new names are clearer and shorter,
+as well as being compatible with @rsixrs{}.
-z. The value returned is the exact number that is numerically closest to the argument.
-For exact arguments, the result is the same as the argument. For inexact non-integral
-real arguments, the implementation may return a rational approximation, or may report
-an implementation violation. For inexact complex arguments, the result is a complex
-number whose real and imaginary parts are the result of applying exact to the real and
-imaginary parts of the argument, respectively. If an inexact argument has no reasonably
-close exact equivalent, (in the sense of =), then a violation of an implementation
-restriction may be reported.
-
-These procedures implement the natural one-to-one correspondence between exact and
-inexact integers throughout an implementation-dependent range. See section 6.2.3.
-
-Note: These procedures were known in R5RS as exact->inexact and inexact->exact,
-respectively, but they have always accepted arguments of any exactness. The new
-names are clearer and shorter, as well as being compatible with R6RS.
@end deffn
@node Numerical input and output
@@ -967,10 +982,9 @@ names are clearer and shorter, as well as being compatible with R6RS.
@deffnx procedure number->string z radix
It is an error if
+@var{radix} is not one of 2, 8, 10, or 16.
-radix is not one of 2, 8, 10, or 16.
-
-The procedure number->string takes a number and a radix and returns as a string an
+The procedure @code{number->string} takes a number and a radix and returns as a string an
external representation of the given number in the given radix such that
@example
@@ -983,54 +997,43 @@ external representation of the given number in the given radix such that
@end example
is true. It is an error if no possible result makes this expression true. If omitted,
-
-radix defaults to 10.
+@var{radix} defaults to 10.
If
-
-z is inexact, the radix is 10, and the above expression can be satisfied by a result that
+@var{z} is inexact, the radix is 10, and the above expression can be satisfied by a result that
contains a decimal point, then the result contains a decimal point and is expressed using
the minimum number of digits (exclusive of exponent and trailing zeroes) needed to
make the above expression true [4, 5]; otherwise the format of the result is unspecified.
-The result returned by number->string never contains an explicit radix prefix.
+The result returned by @code{number->string} never contains an explicit radix prefix.
Note: The error case can occur only when
-
-z is not a complex number or is a complex number with a non-rational real or
+@var{z} is not a complex number or is a complex number with a non-rational real or
imaginary part.
Rationale: If
-
-z is an inexact number and the radix is 10, then the above expression is normally
+@var{z} is an inexact number and the radix is 10, then the above expression is normally
satisfied by a result containing a decimal point. The unspecified case allows for
infinities, NaNs, and unusual representations.
+
@end deffn
@deffn procedure string->number string
@deffnx procedure string->number string radix
Returns a number of the maximally precise representation expressed by the given
-
-string.
-
+@var{string}.
It is an error if
-
-radix is not 2, 8, 10, or 16.
+@var{radix} is not 2, 8, 10, or 16.
If supplied,
-
-radix is a default radix that will be overridden if an explicit radix prefix is present in
-
-string (e.g. "#o177"). If
-
-radix is not supplied, then the default radix is 10. If
-
-string is not a syntactically valid notation for a number, or would result in a number that
-the implementation cannot represent, then string->number returns #f. An error is never
+@var{radix} is a default radix that will be overridden if an explicit radix prefix is present in
+string (e.g.@: @code{"#o177"}). If
+@var{radix} is not supplied, then the default radix is 10. If
+@var{string} is not a syntactically valid notation for a number, or would result in a number that
+the implementation cannot represent, then @code{string->number} returns @code{#f}. An error is never
signaled due to the content of
-
-string.
+@var{string}.
@example
(string->number "100") @result{} 100
@@ -1038,20 +1041,27 @@ string.
(string->number "1e2") @result{} 100.0
@end example
-Note: The domain of string->number may be restricted by implementations in the
- following ways. If all numbers supported by an implementation are real, then
- string->number is permitted to return #f whenever
-
- string uses the polar or rectangular notations for complex numbers. If all numbers
- are integers, then string->number may return #f whenever the fractional notation is
- used. If all numbers are exact, then string->number may return #f whenever an
- exponent marker or explicit exactness prefix is used. If all inexact numbers are
- integers, then string->number may return #f whenever a decimal point is used.
-
- The rules used by a particular implementation for string->number must also be
- applied to read and to the routine that reads programs, in order to maintain
- consistency between internal numeric processing, I/O, and the processing of
- programs. As a consequence, the R5RS permission to return #f when
+Note:
+The domain of @code{string->number} may be restricted by implementations
+in the following ways.
+If all numbers supported by an implementation are real, then
+@code{string->number} is permitted to return @code{#f} whenever
+@var{string} uses the polar or rectangular notations for complex
+numbers. If all numbers are integers, then
+@code{string->number} may return @code{#f} whenever
+the fractional notation is used. If all numbers are exact, then
+@code{string->number} may return @code{#f} whenever
+an exponent marker or explicit exactness prefix is used.
+If all inexact
+numbers are integers, then
+@code{string->number} may return @code{#f} whenever
+a decimal point is used.
+
+The rules used by a particular implementation for @code{string->number} must
+also be applied to @code{read} and to the routine that reads programs, in
+order to maintain consistency between internal numeric processing, I/O,
+and the processing of programs.
+As a consequence, the @rfivers{} permission to return @code{#f} when
+@var{string} has an explicit radix prefix has been withdrawn.
- string has an explicit radix prefix has been withdrawn.
@end deffn
diff --git a/doc/r7rs-small/r7rs-texinfo-macros.texinfo b/doc/r7rs-small/r7rs-texinfo-macros.texinfo
@@ -1,3 +1,17 @@
+@c Report names.
+
+@macro rsevenrs
+R@sup{7}RS
+@end macro
+
+@macro rfivers
+R@sup{5}RS
+@end macro
+
+@macro rsixrs
+R@sup{6}RS
+@end macro
+
@c Syntactic variables
@c These will be presented in angle brackets, which have to be
@c produced differently in TeX output. Because Texinfo has no
