4.3.2 Generic Numerics
Most Racket numeric operations work on any kind of number.
4.3.2.1 Arithmetic
If z is exact 0 and no w is exact 0, then the result is exact 0. If any w is exact 0, the exn:fail:contract:divide-by-zero exception is raised.
> (quotient 10 3) 3
> (quotient -10.0 3) -3.0
> (quotient +inf.0 3) quotient: contract violation
expected: integer?
given: +inf.0
If m is exact 0, the exn:fail:contract:divide-by-zero exception is raised.
> (remainder 10 3) 1
> (remainder -10.0 3) -1.0
> (remainder 10.0 -3) 1.0
> (remainder -10 -3) -1
> (remainder +inf.0 3) remainder: contract violation
expected: integer?
given: +inf.0
procedure
(quotient/remainder n m) →
integer? integer? n : integer? m : integer?
> (quotient/remainder 10 3)
3
1
(abs q) is between 0 (inclusive) and (abs m) (exclusive), and
the difference between q and (- n (* m (quotient n m))) is a multiple of m.
If m is exact 0, the exn:fail:contract:divide-by-zero exception is raised.
> (modulo 10 3) 1
> (modulo -10.0 3) 2.0
> (modulo 10.0 -3) -2.0
> (modulo -10 -3) -1
> (modulo +inf.0 3) modulo: contract violation
expected: integer?
given: +inf.0
> (truncate 17/4) 4
> (truncate -17/4) -4
> (truncate 2.5) 2.0
> (truncate -2.5) -2.0
> (truncate +inf.0) +inf.0
procedure
(denominator q) → (and/c integer? positive?)
q : rational?
> (denominator 5) 1
> (denominator 17/4) 4
> (denominator 2.3) 1125899906842624.0
procedure
(rationalize x tolerance) → real?
x : real? tolerance : real?
> (rationalize 1/4 1/10) 1/3
> (rationalize -1/4 1/10) -1/3
> (rationalize 1/4 1/4) 0
> (rationalize 11/40 1/4) 1/2
4.3.2.2 Number Comparison
Changed in version 7.0.0.13 of package base: Allow one argument, in addition to allowing two or more.
Changed in version 7.0.0.13 of package base: Allow one argument, in addition to allowing two or more.
Changed in version 7.0.0.13 of package base: Allow one argument, in addition to allowing two or more.
Changed in version 7.0.0.13 of package base: Allow one argument, in addition to allowing two or more.
Changed in version 7.0.0.13 of package base: Allow one argument, in addition to allowing two or more.
4.3.2.3 Powers and Roots
procedure
(integer-sqrt n) → complex?
n : integer?
> (integer-sqrt 4.0) 2.0
> (integer-sqrt 5) 2
> (integer-sqrt -4.0) 0.0+2.0i
> (integer-sqrt -4) 0+2i
procedure
(integer-sqrt/remainder n) →
complex? integer? n : integer?
> (integer-sqrt/remainder 4.0)
2.0
0.0
> (integer-sqrt/remainder 5)
2
1
If w is exact 0, the result is exact 1. If w is 0.0 or -0.0 and z is a real number other than exact 1 or 0, the result is 1.0 (even if z is +nan.0).
If z is exact 1, the result is exact 1. If z is 1.0 and w is a real number, the result is 1.0 (even if w is +nan.0).
w is exact 0 —
result is 1 w is 0.0 or -0.0 —
result is 1.0 real part of w is negative —
the exn:fail:contract:divide-by-zero exception is raised w is nonreal with a nonpositive real part —
the exn:fail:contract:divide-by-zero exception is raised w is +nan.0 —
result is +nan.0 otherwise —
result is 0
w is negative —
result is +inf.0 w is positive —
result is 0.0
- w is negative:
w is an odd integer —
result is -inf.0 w otherwise rational —
result is +inf.0
- w is positive:
w is an odd integer —
result is -0.0 w otherwise rational —
result is 0.0
z is less than 1.0 —
result is +inf.0 z is greater than 1.0 —
result is 0.0
z is less than 1.0 —
result is 0.0 z is greater than 1.0 —
result is +inf.0
- w is negative:
w is odd —
result is -0.0 w is even —
result is 0.0
- w is positive:
w is odd —
result is -inf.0 w is even —
result is +inf.0
w is negative —
result is 0.0 w is positive —
result is +inf.0
If b is provided, it serves as an alternative base. It is equivalent to (/ (log z) (log b)), but can potentially run faster. If b is exact 1, exn:fail:contract:divide-by-zero exception is raised.
Consider using fllogb from math/flonum instead when accuracy is important.
> (log (exp 1)) 1.0
> (log 2+3i) 1.2824746787307684+0.982793723247329i
> (log 1) 0
> (log 100 10) 2.0
> (log 8 2) 3.0
> (log 5 5) 1.0
Changed in version 6.9.0.1 of package base: Added second argument for arbitrary bases.
4.3.2.4 Trigonometric Functions
In the two-argument case, the result is roughly the same as (atan (/ (exact->inexact y)) (exact->inexact x)), but the signs of y and x determine the quadrant of the result. Moreover, a suitable angle is returned when y divided by x produces +nan.0 in the case that neither y nor x is +nan.0. Finally, if y is exact 0 and x is a positive number, the result is exact 0. If both x and y are exact 0, the exn:fail:contract:divide-by-zero exception is raised.
> (atan 0.5) 0.46364760900080615
> (atan 2 1) 1.1071487177940904
> (atan -2 -1) -2.0344439357957027
> (atan 1.0+5.0i) 1.530881333938778+0.19442614214700213i
> (atan +inf.0 -inf.0) 2.356194490192345
Changed in version 7.2.0.2 of package base: Changed to raise exn:fail:contract:divide-by-zero for 0+1i and 0-1i and to produce exact 0 for any positive x (not just exact values) when y is 0.
4.3.2.5 Complex Numbers
procedure
(make-rectangular x y) → number?
x : real? y : real?
> (make-rectangular 3 4.0) 3.0+4.0i
procedure
(make-polar magnitude angle) → number?
magnitude : real? angle : real?
> (make-polar 10 (* pi 1/2)) 6.123233995736766e-16+10.0i
> (make-polar 10 (* pi 1/4)) 7.0710678118654755+7.071067811865475i
Changed in version 7.2.0.2 of package base: Changed to always return +inf.0 for a complex number with a +inf.0 or -inf.0 component.
The result is guaranteed to be between (- pi) and pi, possibly equal to pi (but never equal to (- pi)).
> (angle -3) 3.141592653589793
> (angle 3.0) 0
> (angle 3+4i) 0.9272952180016122
> (angle +inf.0+inf.0i) 0.7853981633974483
> (angle -1) 3.141592653589793
4.3.2.6 Bitwise Operations
procedure
(bitwise-ior n ...) → exact-integer?
n : exact-integer?
> (bitwise-ior 1 2) 3
> (bitwise-ior -32 1) -31
procedure
(bitwise-and n ...) → exact-integer?
n : exact-integer?
> (bitwise-and 1 2) 0
> (bitwise-and -32 -1) -32
procedure
(bitwise-xor n ...) → exact-integer?
n : exact-integer?
> (bitwise-xor 1 5) 4
> (bitwise-xor -32 -1) 31
procedure
(bitwise-not n) → exact-integer?
n : exact-integer?
> (bitwise-not 5) -6
> (bitwise-not -1) 0
procedure
(bitwise-bit-set? n m) → boolean?
n : exact-integer? m : exact-nonnegative-integer?
This operation is equivalent to (not (zero? (bitwise-and n (arithmetic-shift 1 m)))), but it is faster and runs in constant time when n is positive.
> (bitwise-bit-set? 5 0) #t
> (bitwise-bit-set? 5 2) #t
> (bitwise-bit-set? -5 (expt 2 700)) #t
procedure
(bitwise-bit-field n start end) → exact-integer?
n : exact-integer? start : exact-nonnegative-integer?
end :
(and/c exact-nonnegative-integer? (>=/c start))
This operation is equivalent to the computation
(bitwise-and (sub1 (arithmetic-shift 1 (- end start))) (arithmetic-shift n (- start)))
but it runs in constant time when n is positive, start and end are fixnums, and (- end start) is no more than the maximum width of a fixnum.
Each pair of examples below uses the same numbers, showing the result both in binary and as integers.
> (format "~b" (bitwise-bit-field (string->number "1101" 2) 1 1)) "0"
> (bitwise-bit-field 13 1 1) 0
> (format "~b" (bitwise-bit-field (string->number "1101" 2) 1 3)) "10"
> (bitwise-bit-field 13 1 3) 2
> (format "~b" (bitwise-bit-field (string->number "1101" 2) 1 4)) "110"
> (bitwise-bit-field 13 1 4) 6
procedure
(arithmetic-shift n m) → exact-integer?
n : exact-integer? m : exact-integer?
> (arithmetic-shift 1 10) 1024
> (arithmetic-shift 255 -3) 31
procedure
(integer-length n) → exact-integer?
n : exact-integer?
> (integer-length 8) 4
> (integer-length -8) 3
4.3.2.7 Random Numbers
procedure
(random k [rand-gen]) → exact-nonnegative-integer?
k : (integer-in 1 4294967087)
rand-gen : pseudo-random-generator? = (current-pseudo-random-generator) (random min max [rand-gen]) → exact-integer? min : exact-integer? max : (integer-in (+ 1 min) (+ 4294967087 min))
rand-gen : pseudo-random-generator? = (current-pseudo-random-generator) (random [rand-gen]) → (and/c real? inexact? (>/c 0) (</c 1))
rand-gen : pseudo-random-generator? = (current-pseudo-random-generator)
When called with two integer arguments min and max, returns a random exact integer in the range min to max-1.
When called with zero arguments, returns a random inexact number between 0 and 1, exclusive.
In each case, the number is provided by the given pseudo-random number generator (which defaults to the current one, as produced by current-pseudo-random-generator). The generator maintains an internal state for generating numbers. The random number generator uses L’Ecuyer’s MRG32k3a algorithm [L'Ecuyer02] that has a state space of practically 192 bits.
When security is a concern, use crypto-random-bytes instead of random.
The math/base library provides additional functions for random number generation without the limit of 4294967087.
Changed in version 6.4 of package base: Added support for ranges.
procedure
(random-seed k) → void?
k : (integer-in 0 (sub1 (expt 2 31)))
The random-seed function is convenient for some purposes, but note that the space of states for a pseudo-random number generator is much larger that the space of allowed values for k. Use vector->pseudo-random-generator! to set a pseudo-random number generator to any of its possible states.
procedure
procedure
v : any/c
parameter
(current-pseudo-random-generator) → pseudo-random-generator?
(current-pseudo-random-generator rand-gen) → void? rand-gen : pseudo-random-generator?
procedure
(pseudo-random-generator->vector rand-gen)
→ pseudo-random-generator-vector? rand-gen : pseudo-random-generator?
procedure
→ pseudo-random-generator? vec : pseudo-random-generator-vector?
procedure
(vector->pseudo-random-generator! rand-gen vec) → void? rand-gen : pseudo-random-generator? vec : pseudo-random-generator-vector?
procedure
v : any/c
4.3.2.8 Other Randomness Utilities
| (require racket/random) | package: base |
procedure
(crypto-random-bytes n) → bytes?
n : exact-positive-integer?
Returns n random bytes. On Unix systems, the bytes are obtained from "/dev/urandom", while Windows uses the RtlGenRand system function.
> (crypto-random-bytes 14) #"\0\1\1\2\3\5\b\r\25\"7Y\220\351"
Added in version 6.3 of package base.
procedure
(random-ref seq [rand-gen]) → any/c
seq : sequence?
rand-gen : pseudo-random-generator? = (current-pseudo-random-generator)
Added in version 6.4 of package base.
procedure
(random-sample seq n [ rand-gen #:replacement? replacement?]) → (listof any/c) seq : sequence? n : exact-positive-integer?
rand-gen : pseudo-random-generator? = (current-pseudo-random-generator) replacement? : any/c = #t
Like sequence-length, does not terminate on infinite sequences, and evaluates the entire sequence.
Added in version 6.4 of package base.
4.3.2.9 Number–String Conversions
procedure
(number->string z [radix]) → string?
z : number? radix : (or/c 2 8 10 16) = 10
> (number->string 3.0) "3.0"
> (number->string 255 8) "377"
procedure
(string->number s [ radix convert-mode decimal-mode single-mode]) → (or/c number? #f string? extflonum?) s : string? radix : (integer-in 2 16) = 10
convert-mode : (or/c 'number-or-false 'read) = 'number-or-false
decimal-mode : (or/c 'decimal-as-inexact 'decimal-as-exact) =
(if (read-decimal-as-inexact) 'decimal-as-inexact 'decimal-as-exact)
single-mode : (or/c 'single 'double) =
(if (read-single-flonum) 'single 'double)
If convert-mode is 'number-or-false, the result is #f if s does not parse exactly as a number datum (with no whitespace). If convert-mode is 'read, the result can be an extflonum, and it can be a string that contains an error message if read of s would report a reader exception (but the result can still be #f if read would report a symbol).
The decimal-mode argument controls number parsing the same way that the read-decimal-as-inexact parameter affects read.
The single-mode argument controls number parsing the same way that the read-single-flonum parameter affects read.
> (string->number "3.0+2.5i") 3.0+2.5i
> (string->number "hello") #f
> (string->number "111" 7) 57
> (string->number "#b111" 7) 7
> (string->number "#e+inf.0" 10 'read) "no exact representation for +inf.0"
> (string->number "10.3" 10 'read 'decimal-as-exact) 103/10
Changed in version 6.8.0.2 of package base: Added the convert-mode and
decimal-mode arguments.
Changed in version 7.3.0.5: Added the single-mode argument.
procedure
(real->decimal-string n [decimal-digits]) → string?
n : rational? decimal-digits : exact-nonnegative-integer? = 2
Before printing, n is converted to an exact number, multiplied by (expt 10 decimal-digits), rounded, and then divided again by (expt 10 decimal-digits). The result of this process is an exact number whose decimal representation has no more than decimal-digits digits after the decimal (and it is padded with trailing zeros if necessary).
If n is a real number with no decimal representation (e.g. +nan.0, +inf.0), then the exn:fail:contract exception is raised. (Any real number that is convertible to decimal notation is rational, so n must be rational?, despite the name of the function.)
> (real->decimal-string pi) "3.14"
> (real->decimal-string pi 5) "3.14159"
procedure
(integer-bytes->integer bstr signed? [ big-endian? start end]) → exact-integer? bstr : bytes? signed? : any/c big-endian? : any/c = (system-big-endian?) start : exact-nonnegative-integer? = 0 end : exact-nonnegative-integer? = (bytes-length bstr)
Changed in version 6.10.0.1 of package base: Added support for decoding a 1-byte string.
procedure
(integer->integer-bytes n size-n signed? [ big-endian? dest-bstr start]) → bytes? n : exact-integer? size-n : (or/c 1 2 4 8) signed? : any/c big-endian? : any/c = (system-big-endian?)
dest-bstr : (and/c bytes? (not/c immutable?)) = (make-bytes size-n) start : exact-nonnegative-integer? = 0
The dest-bstr argument must be a mutable byte string of length size-n. The encoding of n is written into dest-bstr starting at offset start, and dest-bstr is returned as the result.
If n cannot be encoded in a byte string of the requested size and format, the exn:fail:contract exception is raised. If dest-bstr is not of length size-n, the exn:fail:contract exception is raised.
Changed in version 6.10.0.1 of package base: Added support for encoding a 1-byte value.
procedure
(floating-point-bytes->real bstr [ big-endian? start end]) → flonum? bstr : bytes? big-endian? : any/c = (system-big-endian?) start : exact-nonnegative-integer? = 0 end : exact-nonnegative-integer? = (bytes-length bstr)
procedure
(real->floating-point-bytes x size-n [ big-endian? dest-bstr start]) → bytes? x : real? size-n : (or/c 4 8) big-endian? : any/c = (system-big-endian?)
dest-bstr : (and/c bytes? (not/c immutable?)) = (make-bytes size-n) start : exact-nonnegative-integer? = 0
The dest-bstr argument must be a mutable byte string of length size-n. The encoding of n is written into dest-bstr starting with byte start, and dest-bstr is returned as the result.
If dest-bstr is provided and it has less than start plus size-n bytes, the exn:fail:contract exception is raised.
procedure
4.3.2.10 Extra Constants and Functions
| (require racket/math) | package: base |
value
Changed in version 7.3.0.5 of package base: Allow value to be a double-precision flonum.
procedure
(degrees->radians x) → real?
x : real?
> (degrees->radians 180) 3.141592653589793
> (sin (degrees->radians 45)) 0.7071067811865475
procedure
(radians->degrees x) → real?
x : real?
> (radians->degrees pi) 180.0
> (radians->degrees (* 1/4 pi)) 45.0
> (sgn 10) 1
> (sgn -10.0) -1.0
> (sgn 0) 0
> (sgn -0.0) -0.0
> (sgn 0.0) 0.0
> (sgn +nan.0) +nan.0
> (sgn +inf.0) 1.0
> (sgn -inf.0) -1.0
procedure
(exact-round x) → exact-integer?
x : rational?
procedure
(exact-floor x) → exact-integer?
x : rational?
procedure
(exact-ceiling x) → exact-integer?
x : rational?
procedure
(exact-truncate x) → exact-integer?
x : rational?
(<= (expt 10 m) (inexact->exact r))
(< (inexact->exact r) (expt 10 (add1 m)))
> (order-of-magnitude 999) 2
> (order-of-magnitude 1000) 3
> (order-of-magnitude 1/100) -2
> (order-of-magnitude 1/101) -3
procedure
(positive-integer? x) → boolean?
x : any/c
Added in version 6.8.0.2 of package base.
procedure
(negative-integer? x) → boolean?
x : any/c
Added in version 6.8.0.2 of package base.
procedure
(nonpositive-integer? x) → boolean?
x : any/c
Added in version 6.8.0.2 of package base.
procedure
(nonnegative-integer? x) → boolean?
x : any/c
Added in version 6.8.0.2 of package base.
Added in version 6.8.0.2 of package base.