js-numbers: a Javascript implementation of Scheme's numeric tower

Developer: Danny Yoo ([email protected])

License: BSD

Summary: js-numbers implements the "numeric tower" commonly associated with the Scheme language. The operations in this package automatically coerse between fixnums, bignums, rationals, floating point, and complex numbers.

Contributors: The following people have contributed to this library

Zhe Zhang
Ethan Cecchetti
Ugur Cekmez
Dan King
Emmanuel Schanzer

Other sources: The bignum implementation (content from jsbn.js and jsbn2.js) used in js-numbers comes from Tom Wu's JSBN library at:

http://www-cs-students.stanford.edu/~tjw/jsbn/

======================================================================

WARNING WARNING

This package is currently being factored out of an existing project, Moby-Scheme. As such, the code here is in major flux, and this is nowhere near ready from public consumption yet. We're still in the middle of migrating over the test cases from Moby-Scheme over to this package, and furthermore, I'm taking the time to redo some of the implementation. So this is going to be buggy for a bit. Use at your own risk.

====================================================================== Examples

[fill me in]

====================================================================== API

Loading js-numbers.js will define a toplevel namespace called

jsnums

which contains following constants and functions:

pi: scheme-number

e: scheme-number

nan: scheme-number Not-A-Number

inf: scheme-number infinity

negative_inf: scheme-number negative infinity

negative_zero: scheme-number The value -0.0.

zero: scheme-number

one: scheme-number

negative_one: scheme-number

i: scheme-number The square root of -1.

negative_i: scheme-number The negative of i.

fromString: string -> (scheme-number | false) Convert from a string to a scheme-number. If we find the number is malformed, returns false.

fromFixnum: javascript-number -> scheme-number Convert from a javascript number to a scheme number. If the number looks like an integer, represents as an exact integer. Otherwise, represents as a float. If you need more precision over the representation, use makeFloat or makeRational instead.

makeRational: javascript-number javascript-number? -> scheme-number Low level constructor: Constructs a rational with the given numerator and denominator. If only one argument is given, assumes the denominator is 1. The numerator and denominator must be integers.

makeFloat: javascript-number -> scheme-number Low level constructor: constructs a floating-point number.

makeBignum: string -> scheme-number Low level constructor: constructs a bignum.

makeComplex: scheme-number scheme-number? -> scheme-number Constructs a complex number; the real and imaginary parts of the input must be basic scheme numbers (i.e. not complex). If only one argument is given, assumes the imaginary part is 0.

makeComplexPolar: scheme-number scheme-number -> scheme-number Constructs a complex number; the radius and theta must be basic scheme numbers (i.e. not complex).

isSchemeNumber: any -> boolean Produces true if the thing is a scheme number.

isRational: scheme-number -> boolean Produces true if the number is rational.

isReal: scheme-number -> boolean Produces true if the number is a real.

isExact: scheme-number -> boolean Produces true if the number is being represented exactly.

isInexact: scheme-number -> boolean Produces true if the number is inexact.

isInteger: scheme-number -> boolean Produces true if the number is an integer.

toFixnum: scheme-number -> javascript-number Produces the javascript number closest in interpretation to the given scheme-number.

toExact: scheme-number -> scheme-number Converts the number to an exact scheme-number.

toInexact: scheme-number -> scheme-number Converts the number to an inexact scheme-number.

add: scheme-number scheme-number -> scheme-number Adds the two numbers together.

subtract: scheme-number scheme-number -> scheme-number Subtracts the first number from the second.

mulitply: scheme-number scheme-number -> scheme-number Multiplies the two numbers together.

divide: scheme-number scheme-number -> scheme-number Divides the first number by the second.

equals: scheme-number scheme-number -> boolean Produces true if the two numbers are equal.

eqv: scheme-number scheme-number -> boolean Produces true if the two numbers are equivalent.

approxEquals: scheme-number scheme-number scheme-number -> boolean Produces true if the two numbers are approximately equal, within the bounds of the third argument.

greaterThanOrEqual: scheme-number scheme-number -> boolean Produces true if the first number is greater than or equal to the second.

lessThanOrEqual: scheme-number scheme-number -> boolean Produces true if the first number is less than or equal to the second.

greaterThan: scheme-number scheme-number -> boolean Produces true if the first number is greater than the second.

lessThan: scheme-number scheme-number -> boolean Produces true if the first number is less than the second.

expt: scheme-number scheme-number -> scheme-number Produces the first number exponentiated to the second number.

exp: scheme-number -> scheme-number Produces e exponentiated to the given number.

modulo: scheme-number scheme-number -> scheme-number Produces the modulo of the two numbers.

numerator: scheme-number -> scheme-number Produces the numerator of the rational number.

denominator: scheme-number -> scheme-number Produces the denominator of the rational number.

quotient: scheme-number scheme-number -> scheme-number Produces the quotient. Both inputs must be integers.

remainder: scheme-number scheme-number -> scheme-number Produces the remainder. Both inputs must be integers.

sqrt: scheme-number -> scheme-number Produces the square root.

abs: scheme-number -> scheme-number Produces the absolute value.

floor: scheme-number -> scheme-number Produces the floor.

round: scheme-number -> scheme-number Produces the number rounded to the nearest integer.

ceiling: scheme-number -> scheme-number Produces the ceiling.

conjugate: scheme-number -> scheme-number Produces the complex conjugate.

magnitude: scheme-number -> scheme-number Produces the complex magnitude.

log: scheme-number -> scheme-number Produces the natural log (base e) of the given number.

angle: scheme-number -> scheme-number Produces the complex angle.

cos: scheme-number -> scheme-number Produces the cosine.

sin: scheme-number -> scheme-number Produces the sin.

tan: scheme-number -> scheme-number Produces the tangent.

asin: scheme-number -> scheme-number Produces the arc sine.

acos: scheme-number -> scheme-number Produces the arc cosine.

atan: scheme-number -> scheme-number Produces the arc tangent.

cosh: scheme-number -> scheme-number Produces the hyperbolic cosine.

sinh: scheme-number -> scheme-number Produces the hyperbolic sine.

realPart: scheme-number -> scheme-number Produces the real part of the complex number.

imaginaryPart: scheme-number -> scheme-number Produces the imaginary part of the complex number.

sqr: scheme-number -> scheme-number Produces the square.

integerSqrt: scheme-number -> scheme-number Produces the integer square root.

gcd: scheme-number [scheme-number ...] -> scheme-number Produces the greatest common divisor.

lcm: scheme-number [scheme-number ...] -> scheme-number Produces the least common mulitple.

toRepeatedDecimal: scheme-number scheme-number {limit: number}? -> [string, string, string] Produces a string representation of the decimal expansion; the first and second argument must be integers. Returns an array of three parts: the portion before the decimal, the non-repeating part, and then the repeating part.

If the expansion goes beyond the limit (by default, 256 characters), then
the expansion will be cut off, and the third portion will be '...'.

====================================================================== Test suite

Open tests/index.html, which should run our test suite over all the public functions in js-numbers.

If you notice a good test case is missing, please let the developer know, and we'll be happy to add it in.

====================================================================== TODO

• Absorb implementations of:

  atan2, cosh, sinh, sgn

• Add real documentation.

======================================================================

Related work

There appears to be another Scheme numeric tower implementation that just came out in the last month or so, by Matt Might and John Tobey:

https://github.com/jtobey/javascript-bignum
http://silentmatt.com/biginteger/

====================================================================== History

February 2010: initial refactoring from the moby-scheme source tree.

June 2010: got implementation of integer-sqrt from Ugur Cekmez; brought in some fixes from Ethan Cecchetti.