Formal comment #120 (enhancement) Clean-up in the additional arithmetic libraries Reported by: Alan Watson Component: arithmetic Version: 5.91 Text: Consistency and simplicity of naming is important, especially when dealing with libratries that introduce variants on a common operation. I propose the following renamings and additions to the arithmetic libraries defined in section 16. These have the global advantage of using exactly the same names for both generic and type-specific procedures representing similar mathematical operations. How then would one distinguish between different procedures with the same name? One would use the renaming or prefixing procedures allowed by the library system. For example, one would import the fixnum procedures with a prefix of "fixnum:". This would give completely consistent names; currently some of the current names are prefixed by "fixnum" and others by "fixnum-", and some have an appended "?". 16.3.1 ====== Library (r6rs arithmetic fixnum) is renamed as (r6rs arithmetic fixnum quotient-ring) or (r6rs arithmetic fixnum modular). Current New fixnum? number? NONE complex? NONE real? NONE rational? NONE integer? NONE real-valued? NONE rational-valued? NONE integer-values? All of these routines are synonums for the current "fixnum?". Rationale: The generic routines use these procedures to discern types. The fixnum specific routines should use the the same names. In this context, "number?" means "Does the fixnum library treat this as a number?". NONE exact? NONE inexact? Comment: Equivalent to the generic exact? and inexact?, but with the arguments restricted for fixnums. NONE ->inexact NONE ->exact Comment: Fixnum to general inexact and general number to fixnum, signalling if "no reasonable close equivalent". NONE real->fixnum NONE real->single NONE real->double fixnum-width width least-fixnum least greatest-fixnum greatest fixnum=? = fixnum>? > fixnum=? >= fixnum<=? <= fixnum-zero? zero? fixnum-positive? positive? fixnum-negative? negative? fixnum-odd? odd? fixnum-even? even? NONE finite? NONE infinite? NONE nan? fixnum-min min fixnum-max max fixnum+ + fixnum* * fixnum- - NONE abs fixnum-div+mon div-and-mod Comment: "+" means something quite specific in arithmetic. The routine "div+mod" should properly return the sum of the div and mod. With "div-and-mod", this confusion does not arise. fixnum-div div fixnum-mod mod fixnum-div0+mod0 div0-and-mod0 fixnum-div0 div0 fixnum-mod0 mod0 NONE gcd NONE lcm fixnum+/carry +-with-carry fixnum-/carry /-with-carry fixnum*/carry *-with-carry Comment: The use of "/" to mean "with" is specific to only certain dialects of English. It is not well know, for example, in British English. Furthermore, "/" already has a specific meaning in arithmetic; the procedure "+/carry" should return the sum divided by the carry. fixnum-not bitwise-not fixnum-and bitwise-and fixnum-ior bitwise-or fixnum-xor bitwise-exclusive-or Comment: These perform bitwise operations, not logical operations, and should be marked as such. For example, using "bitwise-not" makes it clear that the procedure corresponds to C's "~" operations not C's "!" operations. I suggest "or" instead of "ior" because "or" is already used in the base library to mean inclusive or (albeit a logical inclusive or). I suggest "exclusive-or" instead of "xor" because Scheme has historically preferred to avoid abreviations. However, "xor" would not be wrong. fixnum-if bitwise-if fixnum-bit-count bit-count fixnum-length bit-length fixnum-first-bit-set first-bit-set fixnum-bit-set? bit-set? fixnum-copy-bit copy-bit? fixnum-bit-field bit-field fixnum-copy-bit-field copy-bit-field NONE set-bit! Comment: This should be the same as: (fixnum-copy-bit fx1 fx2 (fixnum-logical-shift-left 1 fx2)) fixnum-arithmetic-shift arithmetic-shift fixnum-arithmetic-shift-left arithmetic-shift-left fixnum-arithmetic-shift-right arithmetic-shift-right NONE bitwise-shift fixnum-logical-shift-left bitwise-shift-left fixnum-logical-shift-right bitwise-shift-right Comment: "logical" in the context of Scheme seems to me to refer more to booleans. I would suggest "bitwise-shift" here or, failing that, just plain "shift". Comment: Why is there no three-argument logical shift, to match the three-argument arithmetic shift? fixnum-rotate-bit-field rotate-bit-field fixnum-reverse-bit-field reverse-bit-field NONE number->string NONE string->number 16.3.2 ====== Library "(r6rs arithmetic fx)" is renamed "(r6rs arithmetic fixnum signalling)". Similar changes are made in the procedures. In addition, I see no reason for omitting procedures simply because they depend on the precision w, so I would add the carry procedures and the logical shift procedures. The results are perfectly well defined, although obviously they depend on w. 16.4 ==== Current New flonum? number? NONE complex? NONE real? NONE rational? flinteger? integer? NONE real-valued? NONE rational-valued? NONE integer-valued? NONE exact? NONE inexact? ->exact ->inexact Comment: Generic number to flonum, yielding a NaN if the number is complex, and flonum to generic exact number. NONE real->flonum NONE real->single NONE real->double fl=? = fl? > fl<=? <= fl>=? >= flzero? zero? flpositive? positive? flnegative? negative? flodd? odd? fleven? even? flfinite? finite? flinfinite? infinite? flnan? nan? flmax max flmin min fl+ + fl* * fl- - fl/ / flabs abs fldiv+mod div-and-mod fldiv div flmod mod fldiv0+mod0 div0-and-mod0 fldiv0 div0 flmod0 mod0 NONE gcd NONE lcm flnumerator numerator fldenominator denominator flfloor floor flceiling ceiling fltruncate truncate flround round NONE rationalize flexp exp fllog log flsin sin flcos cos fltan tan flasin asin NONE acos flatan atan Comment: Even if you hate this idea, flcos is missing. flsqrt sqrt flexpt expt NONE number->string NONE string->number 16.5 Exact arithmetic ===================== By now, the pattern of my suggested renamings should be clear. This library also needs: real? real-valued? rational-valued? integer-valued? exact? inexact? ->inexact ->exact real->flonum real->single real->double infinite? finite? nan? rationalize string->number number->string along with appropriate additions corresponding to the added fixnum procedures. 16.6 Inexact arithmetic ======================= Again, renamings to remove prefixes and spurious ? suffixes, along with: real-valued? rational-valued? integer-valued? exact? inexact? ->exact ->inexact real->flonum real->single real->double rationalize acos string->number number->string RESPONSE: Formal comment #120 proposes renaming of the (r6rs arithmetic fixnum), and (r6rs arithmetic fx) libraries. More importantly, Formal comment #120 proposes to rename most procedures that are exported by all five of the libraries described in sections 16.3, 16.4, 16.5, and 16.6 of the draft R6RS. The renaming would "have the global advantage of using exactly the same names for both generic and type-specific procedures" that have related (but generally not identical) semantics. The basic idea of the renaming is to strip off the prefix that identifies the library from which the procedure is imported and (in most cases) the types of its arguments. To prevent illegal name clashes, programs that use one of those libraries together with (r6rs base) would have to rename the imported procedures, typically by prefixing them with a programmer-specified prefix. The net effect would be to let the renaming prefix be chosen by individual programmers, which would make it harder for Scheme programmers to read each other's code. Several of the proposed renamings are controversial. For example, a program that imports (r6rs arithmetic fixnum) and uses "fixnum:" as a prefix would import all of the following names for exactly the same procedure: fixnum:number? fixnum:complex? fixnum:real? fixnum:rational? fixnum:integer? fixnum:real-valued? fixnum:rational-valued? fixnum:integer-values? It would also import fixnum:exact?, which is the generic exact? procedure restricted to fixnum arguments; that procedure would return #t whenever it does not raise an exception. Similarly fixnum:inexact? would raise #f whenever it does not raise an exception. Most of the changes proposed by Formal comment #120 would be more confusing than helpful, and should not be adopted for the R6RS. Some of the renamings suggested by Formal comment #120 are plausible. The following suggestions were considered by the editors (without dropping the prefix): draft R6RS possible renaming fixnum-div+mod fixnum-div-and-mod fixnum-div0+mod0 fixnum-div0-and-mod0 fixnum+/carry fixnum+with-carry fixnum-/carry fixnum-with-carry fixnum*/carry fixnum*with-carry fixnum-ior fixnum-or fixnum-xor fixnum-exclusive-or The editors decided to adopt the first two renamings (with implications for similarly named procedures); the others were not. (Rationale for not adopting the other renamings: When fixnum-with-carry is seen by itself, the minus sign is more likely to be read as a hyphen. When seen by itself, fixnum-or is not as clear as fixnum-ior. The corresponding fxior and fxxor were judged a nicer pair than fxor and fxexclusive-or.) The rationale for including the X-arithmetic-shift procedures but not any X-logical-shift procedures is that the arithmetic shifts have simple definitions in terms of the generic floor, *, and expt procedures, but the semantics of a logical shift involves an essential discontinuity based on the sign of the second argument. As suggested by formal comments #120 and #121, an flacos procedure should be added to the (r6rs arithmetic flonum) library.