REF NUMBERS John Gibson Feb 1995 COPYRIGHT University of Sussex 1995. All Rights Reserved. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< PROCEDURES ON NUMBERS >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< This file describes all the Poplog number types and procedures to operate on them. For information on the textual representation of different kinds of numbers in Pop-11 see REF * ITEMISE All the Poplog arithmetic operations described in this file check the types of their arguments at run time in order to determine what to do. Fast, non-checking (hence more efficient) integer operations are described in REF * FASTPROCS CONTENTS - (Use <ENTER> g to access required sections) 1 Overview 1.1 Note on Terminology 1.2 Fast integer operations 1.3 Computation on Real Numbers 1.4 Complex Numbers 1.5 Conventions for Formal Parameters of Procedures 2 Predicates Relating to Numbers 3 Comparisons on Numbers 4 Number Representation 5 Arithmetic Operations 6 Rational and Integer Specific Operations 7 Complex Specific Operations 8 Mathematical Functions 9 Trigonometric Functions 10 Bitwise/Logical Integer Operations 11 Random Numbers 12 Floating_Point Utilities 13 Numeric Constants 13.1 Integer 13.2 Floating-Point 14 Miscellaneous ----------- 1 Overview ----------- From Version 12 of Poplog, support is provided for all the numerical data types and associated functions specified by the Common LISP standard. This includes integers, bigintegers, decimals, ddecimals, ratios and complex numbers. This REF file describes the Pop-11 interface to these facilities, which, while differing in some minor respects from the Common LISP standard, (and of course employing different names for procedures in many cases), is essentially an upward-compatible version of it. For a description of the Clisp version see Guy L. Steele, Common LISP: The Language, Chapter 12. For information on the textual representation of different kinds of numbers in Pop-11 see REF * ITEMISE All the Poplog arithmetic operations described in this REF file check the types of their arguments at run time in order to determine what to do. Fast, non-checking (hence more efficient) integer operations are described in REF * FASTPROCS 1.1 Note on Terminology ------------------------ In this document the term 'integer' means either a simple integer or a biginteger, except where explicitly qualified as one or the other; 'integral' means the same in the nominal sense, or 'integer-valued' as an adjective. Similarily, 'real' means 'non-complex', or 'non-complex number' - it does NOT carry the meaning of 'floating-point number' used by some programming languages. 1.2 Fast integer operations ---------------------------- All Poplog arithmetic operations described below check the types of their arguments at run time in order to determine what to do. This gives great flexibility in writing generic procedures, but can mean that efficiency is sacrificed. As a partial solution fast, non-checking integer operations are provided. These are described in REF * FASTPROCS Further information concerning efficiency is available in HELP * EFFICIENCY 1.3 Computation on Real Numbers -------------------------------- Overall, the number types in Poplog provide three classes of representation: ¤ rational (simple integers, bigintegers and ratios) ¤ simple floating-point (decimals) ¤ double-length floating-point (ddecimals) These classes are orthogonal in the sense that a given real number has exactly one representation in each format (the representation being exact for rational, and approximate for floating-point). In particular for rationals, this implies that integers, bigintegers and ratios are mutually disjoint in terms of the numbers they represent, and that no two ratios represent the same number unless they have the same numerator and denominator. In other words, a ratio is always reduced to its lowest common terms, by dividing numerator and denominator by their greatest common divisor; if this makes the denominator equal to 1, the result is the integer numerator (this is the rule of 'rational canonicalisation'). Any integral result from a computation will always produce a simple integer (rather than a biginteger) if it can be so represented. With very few exceptions, numerical procedures are 'generic', that is, will accept any kind of numbers as arguments. For all procedures that perform a rational-type function (i.e. excluding 'irrational' or 'transcendental' functions like sqrt, log, etc), rational argument(s) will cause the computation to be done using rational arithmetic, and the result will be rational. Otherwise, when the function is irrational, or one or more of the arguments is floating-point, all arguments are converted to double-length floating-point and the computation performed with double-float arithmetic (this is the rule of 'floating-point contagion'). The result will be a floating-point whose actual format depends on the value of the variable popdprecision (see the description of this below). 1.4 Complex Numbers -------------------- Complex numbers always have both real and imaginary parts of the same representation class, and so may similarily be sub-divided into rational complex, simple-float-complex and double-float-complex. Aside from those irrational functions that can produce a complex result from a real argument (sqrt applied to a negative real, for example), the only way of constructing complex numbers is with the operators +: and -: ('plus i times' and 'minus i times'). These obey the same rules as for real arithmetic: with both arguments rational or rational-complex the result is a rational-complex; if either argument is floating or float-complex, the result is a float-complex whose format depends on popdprecision. The only rider to this is the rule of 'rational-complex canonicalisation', which prevents the production of a rational-complex number with a 0 imaginary part. Instead, the result is just the real part of the number. Note that this does not apply to float-complex numbers, which can have a 0.0 imaginary part. Most numerical procedures allow complex or mixed real and complex arguments. In a similar way to the rational/float distinction for the real case, computations are done in real arithmetic producing a real result if all arguments are real, or otherwise all arguments are converted to complex and the operation performed in complex to give a complex result (the rule of 'complex contagion'). 1.5 Conventions for Formal Parameters of Procedures ---------------------------------------------------- Except in those cases where the arguments or results of a procedure are sufficiently complicated to require names that describe their function, rather than just their type, the following conventions are used: Convention Data type ---------- --------- item anything bool a boolean, true or false num, num1, num2 any number, including complex real, real1, real2 any number except complex N a simple integer int, int1, int2 any integer, simple or big float, float1, float2 a decimal or ddecimal --------------------------------- 2 Predicates Relating to Numbers --------------------------------- isinteger(item) -> bool [procedure] Returns true if item is a simple integer, false otherwise. isbiginteger(item) -> bool [procedure] Returns true if item is a biginteger, false otherwise. isintegral(item) -> bool [procedure] Returns true if item is a simple integer or a biginteger, false otherwise. isratio(item) -> bool [procedure] Returns true if item is a ratio, false otherwise. isrational(item) -> bool [procedure] Returns true if item is a simple integer, a biginteger or a ratio, and false otherwise. isdecimal(item) -> bool [procedure] Returns true if item is a decimal or a ddecimal, false otherwise. issdecimal(item) -> bool [procedure] Returns true if item is a simple decimal, false otherwise. isddecimal(item) -> bool [procedure] Returns true if item is a ddecimal, false otherwise. isreal(item) -> bool [procedure] Returns true if item is any number except a complex, false otherwise. iscomplex(item) -> bool [procedure] Returns true if item is a complex number, false otherwise. isnumber(item) -> bool [procedure] Returns true if item is any kind of number, false otherwise. ------------------------- 3 Comparisons on Numbers ------------------------- num1 = num2 -> bool [operator 7] num1 /= num2 -> bool [operator 7] On numbers, these operators compare their arguments for mathematical equality and inequality respectively. Different types of rationals (integers, bigintegers and ratios) can never represent the same number and so can never be equal; comparisons between floating-point (decimals and ddecimals) and between floating-point and rationals first convert both arguments to double float. The same rules apply to the comparison of the real and imaginary parts of a complex numbers. Note that a real number compared with a complex number will be equal only if the complex number is a float-complex with 0.0 imaginary part (since the imaginary part of a rational complex must always be non-zero). See also REF * DATA, HELP * EQUAL real1 < real2 -> bool [operator 6] real1 <= real2 -> bool [operator 6] real1 > real2 -> bool [operator 6] real1 >= real2 -> bool [operator 6] These operators compare their first argument to be respectively less than, less than or equal, greater than, and greater than or equal to their second argument, where comparisons between different number types are performed as for = and /=. Both arguments must be real numbers. max(real1, real2) -> greatest [procedure] min(real1, real2) -> least [procedure] max returns the greatest of its two arguments and min the least, where 'greatest' means closest to positive infinity, and 'least' means closest to negative infinity. Both arguments must be real numbers. num1 ==# num2 -> bool [operator 7] Returns true if num1 and num2 are identical (i.e. ==), or numbers of the same representational type and numeric value. Decimals and ddecimals are NOT considered to be of the same type. Two complex numbers are ==# if their real parts are ==# and their imaginary parts are ==# . ------------------------ 4 Number Representation ------------------------ popdprecision -> bool_or_word [variable] bool_or_word -> popdprecision The value of this variable controls the production of results from floating-point computations, in combination with the types of the arguments supplied to the relevant procedure. In the following, "decimal" includes decimal-complex and "ddecimal" includes ddecimal-complex (when a complex floating-point operation is involved): Value Effect ----- ------ false Simple decimal results are always produced. the word A ddecimal result is produced only if one or "ddecimal" other (or the only) argument was ddecimal. (This is the behaviour specified by Common LISP.) any other Same as the previous case, except that a ddecimal result is also produced when neither argument is a simple decimal, i.e. all argument(s) are ddecimal or rational. (Note that in NO case is there an increase in precision of floating point computations if all arguments are simple decimal to start with.) The default value of popdprecision is false. pop_reduce_ratios -> bool [variable] bool -> pop_reduce_ratios It was stated above that a ratio result is always reduced to its lowest common terms (and therefore to an integral result if the denominator becomes 1). However, in situations where a rational computation is being performed that involves a number of intermediate results, the continual reduction of intermediate values can be time-consuming; this boolean variable is therefore provided to enable reduction to be turned off (by setting it false). Although unreduced ratios will give correct results in computation, comparisons on them may not do so (e.g. 2/2 will not come out = to 1), so this facility must be used CAREFULLY: pop_reduce_ratios should only be set false inside a procedure that has it as a dynamic local, and you should always ensure that the variable is returned to true before producing the final result of a computation. number_coerce(num1, to_num) -> num2 [procedure] Produces a number num2 which is the number num1 converted to the representation class (i.e. rational, simple decimal or double-float ddecimal) of the number to_num. Firstly, no new number is constructed unless necessary; thus if the class of num1 already matches that of to_num, num1 is returned unchanged. Otherwise, conversion from one class to another proceeds. Conversion from rational form to floating-point form, or from one float format to the other, takes place in the obvious way. For conversion from floating-point to rational, the float is assumed to be completely accurate, and a mathematically equal rational number is returned. If num1 is complex, then num2 is the complex number got by applying number_coerce recursively to the real and imaginary parts of num1, i.e. number_coerce(realpart(num1), to_num) +: number_coerce(imagpart(num1), to_num) -> num2 If the second argument to_num is itself complex, then num1 is coerced to a complex number of the same representation class, i.e. the result is computed as realpart(to_num) -> to_num; number_coerce(realpart(num1), to_num) +: number_coerce(imagpart(num1), to_num) -> num2 where imagpart will fill in an appropriate zero value for the imaginary part if num1 is real. ------------------------ 5 Arithmetic Operations ------------------------ num1 + num2 -> num3 [operator 5] num1 - num2 -> num3 [operator 5] num1 * num2 -> num3 [operator 4] num1 / num2 -> num3 [operator 4] These operators respectively add, subtract, multiply and divide their arguments, which may be any numbers. The type of the result depends on the rules of floating-point and complex contagion as described above. In particular, note that dividing one integer by another produces a ratio when the result is not exact. - num1 -> num2 [operator 1] As a prefix operator, - is equivalent to negate(num1). divid // divis -> (rem, quot) [operator 4] divid div divis -> quot [operator 2] divid rem divis -> rem [operator 2] The two results returned by the operator // are defined by intof(divid / divis) -> quot and divid - (quot * divis) -> rem where the arguments may be any numbers, including complex. The two results may be obtained separately with div (quot only) and rem (rem only). divid mod divis -> mod [operator 2] Returns divid modulo divis, where both numbers must be real. This is defined as divid rem divis -> rem; if (divis > 0 and rem < 0) or (divis < 0 and rem >= 0) then rem+divis -> mod else rem -> mod endif (i.e. the result always has the same sign as the divisor). intof(num) -> int [procedure] For num real, intof truncates its argument to an integer, i.e. it returns the integer of the same sign as num and with the largest magnitude such that abs(int) <= abs(num). For a complex number, the result is the integral complex number obtained by applying intof to its parts, i.e. intof(realpart(num)) +: intof(imagpart(num)) fracof(num) -> frac [procedure] The fractional part of num, defined as num - intof(num) round(num) -> int [procedure] For num real, rounds num to an integer by taking intof(num+1/2) if num is positive, or intof(num-1/2) otherwise. If num is complex, the result is round(realpart(num)) +: round(imagpart(num)) abs(num) -> real [procedure] Returns the absolute value of num, which (except for complex) will always be a number of the same type. For any complex num, the result will be a floating-point real, computed as sqrt( realpart(num)**2 + imagpart(num)**2 ) negate(num1) -> num2 [procedure] Returns the negation of num1, which will always be a number of the same type. sign(num) -> sign [procedure] For num real, sign returns -1, 0 or 1 of the same type as num, depending on whether num is negative, zero or positive. If num is complex, the result is a floating-point complex number such that abs(sign) = 1.0, phase(sign) = phase(num) ------------------------------------------- 6 Rational and Integer Specific Operations ------------------------------------------- checkinteger(item, low_int, hi_int) [procedure] Checks item to be a (simple) integer within the range specified by lower bound low_int and upper bound hi_int (inclusive). Either or both bounds may be false to indicate no upper or lower limit. If all conditions are satisfied the procedure returns with no action, otherwise a mishap occurs. (Note that * fi_check is a faster version that does not check its second and third arguments are integers, and also returns item if it is an integer within the given range.) gcd_n(int1, int2, ..., intN, N) -> gcd [procedure] Computes the greatest common divisor of the all the N integers int1, int2, ..., intN, where the number N itself (a simple integer >= 0) appears as the rightmost argument. If N = 0, then gcd = 0; if N = 1, then gcd = int1. lcm_n(int1, int2, ..., intN, N) -> lcm [procedure] Computes the least common multiple of the all the N integers int1, int2, ..., intN, where the number N itself (a simple integer >= 0) appears as the rightmost argument. If N = 0, then lcm = 1; if N = 1, then lcm = int1. destratio(rat) -> (numerator, denominator) [procedure] numerator(rat) -> numerator [procedure] denominator(rat) -> denominator [procedure] These procedures return the numerator and denominator parts of a rational number, either together (destratio), or separately (numerator and denominator). When rat is integral, then numerator = rat, and denominator = 1. ------------------------------ 7 Complex Specific Operations ------------------------------ num1 +: num2 -> num3 [operator 5] num1 -: num2 -> num3 [operator 5] These two operators are the basic way of creating complex numbers. Effectively, they both multiply their second argument by "i" (the positive square root of -1), and then either add the result to (+:) or subtract the result from (-:) the first argument. +: num1 -> num2 [operator 1] -: num1 -> num2 [operator 1] As prefix operators, +: and -: are equivalent to unary_+:(num1) and unary_-:(num1) respectively. unary_+:(num1) -> num2 [procedure] unary_-:(num1) -> num2 [procedure] Single-argument versions of +: and -:, which multiply their argument by i and -i respectively. conjugate(num1) -> num2 [procedure] Returns the complex conjugate of its argument. The conjugate of a real number is itself, while for a complex number it is realpart(num1) -: imagpart(num1) i.e. a complex number with the same realpart, but negated imagpart. destcomplex(num) -> (realpart, imagpart) [procedure] realpart(num) -> realpart [procedure] imagpart(num) -> imagpart [procedure] These procedures return the real and imaginary parts of a complex number, either together (destcomplex), or separately (realpart and imagpart). When num is real, then realpart = num, and a zero of the same type as num is returned for imagpart. ------------------------- 8 Mathematical Functions ------------------------- The procedures in this section, as well as most of those in the following section on trigonometric procedures, compute mathematical functions whose definitions on the complex plane necessitate choices of branch cuts and principal values. See the section Branch Cuts, Principal Values and Boundary Conditions in Chapter 12 of Steele for details of these. sqrt(num) -> sqrt [procedure] Returns the (principal) square root of num. This will be a real floating-point if num is real and non-negative, and a float-complex otherwise. log(num) -> log [procedure] Returns the natural (base e) logarithm of num, which must not be a zero of any kind. If num is real and non-negative, the result is a real floating-point. Otherwise, it is the float-complex number log(abs(num)) +: phase(num) log10(num) -> log [procedure] Returns the base 10 logarithm of num, which must not be a zero of any kind. Defined as log(num) / log(10) exp(num) -> exponent [procedure] Returns e raised to the power num, where e is the base of natural logarithms. The result is a floating-point if the argument is real, or a float-complex otherwise. base ** power -> exponent [operator 3] Returns base raised to the power power, where either may be any numbers (except that base must not be zero if power is zero of any type other than integer 0). If power is an integer, the computation is performed by successively multiplying powers of base; thus if base is rational, the result will be exact. If power is integer 0, the result is always a 1 of the same type as base. Otherwise, if power is not an integer, the result is computed as exp(power * log(base)) -------------------------- 9 Trigonometric Functions -------------------------- All the procedures in this section take an angle as argument, or return one as a result. In both cases, the units of the angle (radians or degrees) are controlled by the boolean variable popradians (this applies equally when the angle is complex). The following diagram of the real plane is provided as a visualisation aid (angles are given in radians): Quadrant II | Quadrant I x < 0, y >= 0 | x >= 0, y >= 0 pi/2 < angle <= pi | 0 <= angle <= pi/2 | | pi-A | A \ | / ---------------+-------------- / | \ -(pi-A) | -A | | Quadrant III | Quadrant IV x < 0, y < 0 | x >= 0, y < 0 -pi < angle < -pi/2 | -pi/2 <= angle < 0 (The above is particularly useful in relation to arctan2.) popradians -> bool [variable] bool -> popradians This boolean variable specifies whether the angle arguments for trigonometric procedures such as sin, cos etc are in radians (true) or degrees (false). Similarily, it controls the units of angle results produced by procedures like arcsin, arccos, etc. Note that the default value is false, implying angles in degrees. phase(num) -> realangle [procedure] Returns the complex phase angle of num as a floating-point quantity. This will be in the range - pi < realangle <= pi (radians) - 180 < realangle <= 180 (degrees) If num is real, then realangle = 0.0. This procedure is defined as arctan2(destcomplex(num)) cis(realangle) -> num [procedure] Returns the float-complex number cos(realangle) +: sin(realangle) (the name cis standing for 'cos + i sin'). Note that this is the same as exp(+: realangle) ONLY when popradians is true (because the latter always interprets realangle in radians). sin(angle) -> num [procedure] cos(angle) -> num [procedure] tan(angle) -> num [procedure] These procedures compute the sine, cosine and tangent of angle. The result is a floating-point, or a float-complex if angle is complex. arcsin(num) -> angle [procedure] arccos(num) -> angle [procedure] arctan(num) -> angle [procedure] These procedures compute the arcsine, arccosine and arctangent of num. For num complex, the result is a float-complex. For num real, it is a real float, except in the case of arcsin and arccos when abs(num) > 1. For arctan, it is an error if num = +:1 or -:1. arctan2(real_x, real_y) -> realangle [procedure] Computes the arctangent of real_y / real_x, but using the signs of the two numbers to derive quadrant information. The result is a floating-point number in the range - pi < realangle <= pi (radians) - 180 < realangle <= 180 (degrees) (see diagram above). When real_x = 0 and real_y = 0 the result is defined (arbitrarily) to be 0.0. sinh(angle) -> num [procedure] cosh(angle) -> num [procedure] tanh(angle) -> num [procedure] These procedures compute the hyperbolic sine, hyperbolic cosine and hyperbolic tangent of angle. The result is a floating-point, or a float-complex if angle is complex. arcsinh(num) -> angle [procedure] arccosh(num) -> angle [procedure] arctanh(num) -> angle [procedure] These procedures compute the hyperbolic arcsine, hyperbolic arccosine and hyperbolic arctangent of num. For num complex, the result is a float-complex. For num real, the result will be a real float, except in the following cases: arccosh: num < 1 arctanh: abs(num) > 1 For arctanh, it is an error if num = 1 or -1. pi -> float [constant] This constant is the best ddecimal approximation to "pi", = 3.14159.... -------------------------------------- 10 Bitwise/Logical Integer Operations -------------------------------------- These procedures enable integers to be manipulated as bit patterns representing two's-complement values, where bit position N has weight 2**N (i.e. bits are numbered from 0 upwards). Note that (conceptually, at any rate), the sign bit of an integer is extended indefinitely to the left. Thus everywhere above its most significant bit, a positive integer has 0 bits and a negative integer has 1 bits. int1 && int2 -> int3 [operator 4] The result of this operation is the logical "and" of the integers int1 and int2, i.e. there is a 1 in the result for each bit position for which there is a 1 in both int1 and int2. int1 &&~~ int2 -> int3 [operator 4] The result of this operation is the logical "and" of int1 and the logical complement of int2, i.e. there is a 1 in the result for each bit position for which there is a 1 in int1 and a 0 in int2. (Same as int1 && (~~int2) -- useful for clearing bits of int1 set in int2). int1 || int2 -> int3 [operator 4] The result of this operation is the logical "inclusive or" of int1 and int2, i.e. there is a 1 in the result for each bit position for which there is a 1 in either int1 or int2. int1 ||/& int2 -> int3 [operator 4] The result of this operation is the logical "exclusive or" of int1 and int2, i.e. there is a 1 in the result for each bit position for which there is a 1 in either int1 or int2 but not in both. ~~ int1 -> int2 [operator 4] Produces the logical complement of the integer int1, i.e. there is a 1 in the result for each bit position for which int1 has 0. It is always true that ~~ int = -(int + 1) int1 << N -> int2 [operator 4] Produces the bit pattern of int1 shifted left by (simple integer) N positions; a negative value for N produces a right shift. int1 >> N -> int2 [operator 4] Gives the bit pattern of int1 shifted right by (simple integer) N positions; a negative value for N implies a left shift. int1 &&/=_0 int2 -> bool [operator 6] int1 &&=_0 int2 -> bool [operator 6] These two operators are equivalent to the boolean expressions int1 && int2 /== 0 int1 && int2 == 0 but are more efficient (and avoid producing intermediate results). testbit(int, N) -> bool [procedure] bool -> testbit(int, N) -> newint This procedure and its updater enable the testing and setting or clearing of the bit at position N in the integer int. The base procedure returns the state of bit N as a boolean value, true for 1 and false for 0. The updater (which is somewhat unusual for an updater in that it returns a result) produces a new integer newint which is int with bit N set to 1 or cleared to 0 as specified by the input bool argument (which may in fact be any item, false meaning 0 and anything else meaning 1). integer_leastbit(int) -> N_or_false [procedure] Returns the bit position N of the least-significant bit set in the integer int (equivalently, N is the highest power of 2 by which int divides exactly). false is returned for int 0. integer_length(int) -> N [procedure] Returns the length in bits of int as a two's-complement integer. That is, N is the smallest integer such that int < ( 1 << N) if int >= 0 int >= (-1 << N) if int < 0 Put another way: if int is non-negative then the representation of int as an unsigned integer requires a field of at least N bits; alternatively, a minimum of N+1 bits are required to represent int as a signed integer, regardless of its sign. integer_bitcount(int) -> N [procedure] Counts the number of 1 or 0 bits in the two's-complement representation of int. If int is non-negative, N is the number of 1 bits; if int is negative, it is the number of 0 bits. (Note that, owing to the sign extension, there are an infinite number of 0 bits in a non-negative integer or 1 bits in a negative integer.) It is always the case that integer_bitcount(int) = integer_bitcount(-(int+1)) integer_field(size, position) -> access_p [procedure] This procedure is used to create accessing/updating procedures for sub-bitfields within integers, and provides a more convenient (and more efficient) way of manipulating such fields than by masking and shifting with the operators && and >>, etc. Given a specification of a bitfield in terms of its width in bits size, and lowest bit position position (both simple integers), it returns a procedure access_p. When this is applied to any integer it extracts the binary value represented by bits position to position+size-1 within the integer (shifting it right by position bits to align it at bit 0). That is, access_p(int) -> field_value If the size argument is > 0, the field is taken to contain unsigned (positive or zero values) only; if size < 0, then the field is signed, and upon extraction, the highest bit of the field is extended as the sign bit of the resulting value (cf the corresponding convention used by conskey). The updater of access_p, on the other hand, takes a field value and an integer, and returns a new integer in which the contents of the field bits are replaced by the given value (but which has the same bits everywhere else). That is: field_value -> access_p(int) -> newint Note that the updater makes no check on the range of field_value; bits 0 to size-1 of field_value are masked out, shifted up, and inserted into the field position (and it is therefore irrelevant in this context whether the field is signed or unsigned). A further feature is that access_p and its updater can be made to merely mask out or mask in the field bits, without shifting the value down or up. That is, upon extraction the field value is left aligned at bit position in the result; the input value for updating is assumed to be similarily aligned. This is achieved by supplying a second argument of false to access_p or its updater, i.e. access_p(int, false) -> unshifted_field_value unshifted_field_value -> access_p(int, false) -> newint Note also that in this case, extraction of a signed field will NOT cause it to be sign-extended. ------------------ 11 Random Numbers ------------------ The value of the variable ranseed is used as the seed for the generation of random numbers, each random number generated using one or more successive seed values (depending on the type of the INT_OR_FLOAT argument to random0 and random). The algorithm used to generate each successive seed value is ranseed fi_* 524269 fi_+ 32749 -> ranseed which (since all current implementations use 30 bits for a simple integer) produces a result modulo 2**30. This algorithm has a verified cycle length of 2**30, i.e. it will produce every possible combination of 30 bits before repeating a number. random0(int_or_float) -> random [procedure] Given a strictly-positive integer or floating-point argument, this procedure generates a random number of the same type, in the range 0 <= random < int_or_float where the distribution of random will be approximately uniform. The value of the variable ranseed is used as the seed for the generation process, and is replaced with a new seed value afterwards. random(int_or_float) -> random [procedure] Same as random0, except that whenever the latter would return 0 or 0.0, the original argument int_or_float is returned instead. It can thus be defined as random0(int_or_float) -> random; if random = 0 then int_or_float else random endif; Hence the range of the result is 0 < random <= int_or_float for a float, or 1 <= random <= int_or_float for an integer. ranseed -> n_or_false [variable] n_or_false -> ranseed This variable is used to hold the next seed for generation of random numbers by random0 or random, both of which side-effect it. If set to false, it will be re-initialised to a random simple integer the next time either procedure is called (by using sys_real_time). Otherwise, its value must always be a simple integer. ---------------------------- 12 Floating_Point Utilities ---------------------------- The procedures in this section provide the means to manipulate floating-point numbers, and make possible the writing of machine-independent floating-point software. Note that none of these procedures are affected by the value of popdprecision. float_decode(float, want_int) -> (mantissa, expo, sign) [procedure] This procedure takes a floating-point number and splits it into its component parts, i.e. mantissa, exponent and sign. The exponent expo is always an integer; the boolean argument want_int controls whether the mantissa mantissa and sign sign are returned as floats or integers. sign represents the sign, and is returned either as a float or an integer. For want_int false, it is 1.0 or -1.0 of the same type as the argument, and with the same sign (note that sign is 1.0 for 0.0). For want_int true, it is 1 or -1 (1 for 0.0). Denoting the radix of the floating-point representation by b (see pop_float_radix below), expo is the integer power of b by which mantissa must be multiplied to regain the magnitude of the original number. mantissa itself is the absolute value of the number with b ** expo divided out, and can be returned in one of two ways: If want_int is false, then mantissa is returned as a float of the same type, in the range 1/b <= mantissa < 1 Otherwise, mantissa is is returned as an integer, scaled by b ** float_precision(float) (that is, so that the least significant digit in the representation of float is scaled to unity in the result). If P = float_precision(float) we then have b ** (P-1) <= mantissa < b ** P Thus whether the mantissa is returned as a float or an integer, it will always be the case that mantissa * (b ** expo) = abs(float) (Note that this holds also when float = 0.0, since in this case expo = 0, and mantissa is 0.0 or 0 depending on want_int.) float_scale(float1, expo) -> float2 [procedure] This provides a more efficient way of scaling a float by a power of the floating-point radix 'b' than by using ** (and avoids any intermediate overflow or underflow that could occur with the latter). It returns float1 * (b ** expo) as a floating-point of the same type. If the final result overflows or underflows (i.e. the absolute value of the exponent is too large for the representation), then false is returned. For example, this procedure can be used in conjunction with float_sign to put back together a floating-point number decomposed with float_decode. That is, after float_decode(float, false) -> (mantissa, expo, sign) one can use float_sign(sign, float_scale(mantissa, expo)) to retrieve the original number. float_sign(sign_float, float1) -> float2 [procedure] Returns a floating-point number float2 of the same type and absolute value as float1, but which has the sign of the float sign_float. The argument float1 may also be false. In this case, float2 is returned as a 1.0 or -1.0 of the same type and sign as sign_float. float_digits(float) -> digits [procedure] Returns, as an integer, the number of radix-'b' digits represented in the floating-point format of the argument. (I.e. digits has only two possible values, one for decimals and one for ddecimals. In all current Poplog implementations, b = 2 and ddecimal digits is 53 or 56; decimal digits is 50 on Alpha OSF and 22 on other platforms.) float_precision(float) -> sigdigits [procedure] Same as float_digits, except that the number of significant radix-'b' digits in the argument is returned. Since Poplog floating-point decimals and ddecimals are always normalised, this will in fact be identical to float_digits(float), with the single exception that float_precision(0.0) = 0 for either float type. --------------------- 13 Numeric Constants --------------------- This section describes constants that define the ranges of numbers available in various representation classes. 13.1 Integer ------------- int_parameters [library] This is a library; to use any of the constants it defines, you must load it explicitly with uses int_parameters; It defines the following parameter constants, all of whose values relate to the particular implementation of Poplog in use: pop_max_int [constant] The largest (i.e. most positive) integer value represented in immediate format (as an integer). pop_min_int [constant] The smallest (i.e. most negative) integer value represented in immediate format (as an integer). 13.2 Floating-Point -------------------- float_parameters [library] This is a library; to use any of the constants it defines, you must load it explicitly with uses float_parameters; It defines the following parameter constants, all of whose values relate to the particular implementation of Poplog in use: pop_most_positive_decimal [constant] The greatest positive value representable in simple decimal format. pop_least_positive_decimal [constant] The smallest positive (non-zero) value representable in simple decimal format. pop_least_negative_decimal [constant] The least negative value (i.e. closest to zero) representable in simple decimal format. pop_most_negative_decimal [constant] The most negative value (i.e. closest to negative infinity) representable in simple decimal format. pop_most_positive_ddecimal [constant] pop_least_positive_ddecimal [constant] pop_least_negative_ddecimal [constant] pop_most_negative_ddecimal [constant] Same as the above for double-length ddecimal format. pop_plus_epsilon_decimal [constant] pop_plus_epsilon_ddecimal [constant] These are the smallest positive numbers in each format which when added to 1.0 of the same format produce a value not equal to 1.0. I.e. for each format, the smallest positive e such that number_coerce(1, e) + e /= 1.0 is true. (N.B. For ddecimal format, this depends on popdprecision not being false.) pop_minus_epsilon_decimal [constant] pop_minus_epsilon_ddecimal [constant] Same as before, but subtracting from 1.0 instead of adding, i.e. for each format the smallest positive e such that number_coerce(1, e) - e /= 1.0 is true. pop_float_parameters -> fvec [constant] This is a full vector that holds all the floating-point constants given above, and which the latter uses to define each value as a separate constant. You are not advised to use this directly (since its format may change); always access the values via LIB * FLOAT_PARAMETERS. pop_float_radix -> int [constant] This integer constant is the radix of the floating-point representation (= 2 in all current Poplog implementations). ----------------- 14 Miscellaneous ----------------- linearfit(list) -> (m, c) [procedure] Takes a list of pairs of numbers representing co-ordinates of points, works out the best straight line through the points, and returns its slope m, and its Y-intercept c. For vertical or nearly lines it will produce an error. See LIB * LINEARFIT. integer_key -> key [constant] biginteger_key -> key [constant] ratio_key -> key [constant] decimal_key -> key [constant] ddecimal_key -> key [constant] complex_key -> key [constant] Structure keys for simple integers, bigintegers, ratios, decimals, ddecimals and complex numbers (see REF * KEYS). +-+ C.all/ref/numbers +-+ Copyright University of Sussex 1995. All rights reserved.