[q-lang-users] rational.q: "Q+Q": a rational number module for Q

[Rob H. <hub...@gm...>]

Dear all,

My rational number module "Q+Q" rational_136.tar.gz is now available from
    <http://q-lang.sourceforge.net/examples.html>
    <http://q-lang.sourceforge.net/rational_136.tar.gz>

The module includes:
    constructors (and decomposition functions)
    rational arithmetic (+), (-), (*), (/), ... and relations (=3D),
(<), (<=3D), ..., cmp, ...
        (mixed arithmetic with Ints and Floats is also supported;
        there is one "gotcha" regarding division of ints -- see =A74.1)
    'complexity' comparison functions
    some simple maths functions: abs, sgn, min, max, gcd, lcm, ...
    conversion, approximation and rounding routines
    various string formatting routines
    calculating and evaluating continued fractions (and convergents)

Here are some examples:

    // Arithmetic
    =3D=3D> 5 over 7 + 2 over 3 ; str_mixed _
    rat 29 21
    "1+8/21"
    =3D=3D> (3 over 8) < (1 over 3)
    false
    =3D=3D> cmp (3 over 8) (1 over 3)
    1
    =3D=3D> max (3 over 8) (1 over 3)
    rat 3 8

    // Finding a rational approximations to a real number (or rather, Float=
)
    =3D=3D> def phi =3D (1 + sqrt 5) / 2
    =3D=3D> rational_approx_epsilon .001 phi // Least complex to within
some 'epsilon'
    rat 55 34
    =3D=3D> rational_approx_max_den 1000 phi // Best given a bound on the
denominator
    rat 1597 987

    // Formatting mixed fraction strings
    =3D=3D> def L =3D while (<=3D 3 over 2) (+(1 over 2)) (-3 over 2); L
    [rat (-3) 2,rat (-1) 1,rat (-1) 2,rat 0 1,rat 1 2,rat 1 1,rat 3 2]
    =3D=3D> map str_mixed L
    ["-(1+1/2)","-1","-1/2","0","1/2","1","1+1/2"]

    // Formatting recurring decimal expansion string (exact)
    =3D=3D> str_real_recur format_uk 10 3 (-1 over 700)
    "-0.00[142857...]"

    // Formatting engineering notation (approximation)
    =3D=3D> str_real_approx_eng format_uk 3 10 3 3 round 7 (rational 999950=
)
    "999.950,0*10^3"
    =3D=3D> str_real_approx_eng format_uk 3 10 3 3 round 4 (rational 999950=
)
    "1.000*10^6(-)"
    // The "(-)" should be read as "but a bit less".
    // Different formatting structures are supported (UK used here)
    // Different rounding modes are supported
    // Different radices are supported

    // Calculating and evaluating continued fractions
    =3D=3D> continued_fraction (1234 over 1001)
    [1,4,3,2,1,1,1,8]
    =3D=3D> evaluate_continued_fraction _
    rat 1234 1001

The tarball contains the module source itself, plus a PDF document.

[Some notes for Windoze users (like me): The tarball is easily
unpacked with the 7-Zip program, available from
<http://www.7-zip.org/>; I'd recommend that anyway. The contained
module source rational.q has Linux-style line endings that might upset
some Windoze editors. If that's a problem for you there are various
solutions: if you have Cygwin installed, use unix2dos; write a
conversion script (in Q or Python, say); use an editor such as
Programmers' Notepad <http://www.pnotepad.org/>, Notepad++
<http://notepad-plus.sourceforge.net/uk/about.php> or SciTE
<http://www.scintilla.org/SciTE.html>. All the tools I mention here
are free and/or open source.]

I consider that the module is only an "alpha" version at the moment,
as I may make some minor adjustments to the API over the coming weeks.
The code has had some testing but I plan to do more extensive testing
in the no too distant future. In order to ensure that the examples in
the documentation are correct, these are generated by automatically
evaluating the commands using rational.q.

Please let me know of any bugs that you find. There is currently at
least one minor bug: the string evaluation routines do not detect
out-of-range digits.

Constructive criticism of my implementations is also welcome. I am
relatively new to 'Q' and to the functional style of programming
generally.

Please also let me know of any omissions from (or mistakes or
ambiguities or otherwise unclear material in) the documentation.

I hope to produce a further update soon.

Rob.