      BigRatOps
      Copyright (c)  2018 John Abbott and Anna M. Bigatti
      GNU Free Documentation License, Version 1.2
%!includeconf: ../aux-txt2tags/config.t2t
      TeXTitle{BigRatOps}{John Abbott}


== Examples ==[examples]
%======================================================================
- [ex-BigRat1.C   ../../examples/index.html#ex-BigRat1.C]
-


== User documentation ==
%======================================================================

Here is a collection of basic operations available for rational values;
see also the more advanced functions in [[NumTheory]].

The usual arithmetic operations are available with standard C++
syntax.  The type ``BigRat`` is provided for convenience of
representing rational values rather than for rapid computation; the
native GMP operations may be noticeably faster.

There is an important exception to the natural syntax: ``^`` does **not**
denote exponentiation; you must use the function ``power`` instead.
We have chosen not to define ``operator^`` to perform exponentiation
because it is too easy to write misleading code: for instance,
``a*b^2`` is interpreted by the compiler as ``(a*b)^2``.  There is no
way to make the C++ compiler use the expected interpretation.

Arithmetic may also be performed between a ``BigRat`` and a machine
integer or a [[BigInt]].  The result is always of type ``BigRat``
(even if the value turns out to be an integer).  Do remember, though,
that operations between two machine integers are handled directly by
C++, and problems of overflow can occur.




==== Infix operators ====

**NOTE:** similar to operations on ``BigInt`` -- see [[BigIntOps]]

+ normal arithmetic (potentially inefficient because of temporaries)
 - ``+``    the sum
 - ``-``    the difference
 - ``*``    the product
 - ``/``    quotient
 - ``=``    assignment

+ arithmetic and assignment
 - ``+=``, ``-=``, ``*=``, ``/=`` --  definitions as expected; LHS must be of type ``BigRat``

+ arithmetic ordering
 - ``==``, ``!=``
 - ``<``, ``<=``, ``>``, ``>=`` -- comparison (using the normal arithmetic ordering)
    -- see also the ``cmp`` function below.

+ increment/decrement
 - ``++``, ``--`` (prefix, e.g. ``++a``)   use these if you can
 - ``++``, ``--`` (postfix, e.g. ``a++``)  avoid these if you can, as they create temporaries


==== More functions ====
+ query functions (all take 1 argument)
 - ``IsZero(q)``     -- true iff ``q`` is zero
 - ``IsOne(q)``      -- true iff ``q`` is 1
 - ``IsMinusOne(q)`` -- true iff ``q`` is -1
 - ``IsOneNum(q)``   -- true iff ``num(q)`` is 1
 - ``IsOneDen(q)``   -- true iff ``den(q)`` is 1
 - ``sign(q)``       -- gives -1 (machine integer) to mean ``q`` is negative,
                         0 (machine integer) to mean ``q`` is zero,
                        +1 (machine integer) to mean ``q`` is positive.

+ Exponentiation
  - ``power(a, b)`` -- returns ``a`` to the power ``b`` (result is always a ``BigRat``)

+ The cmp function (three way comparison)
 - ``cmp(a,b)`` -- returns an ``int`` which is ``< 0`` if ``a < b``, or ``== 0`` if ``a == b``, or ``> 0`` if ``a > b``.
 - ``CmpAbs(a,b)`` -- equivalent to ``cmp(abs(a),abs(b))``

+ Other functions
 - ``abs(q)``   -- gives the absolute value of ``q``
 - ``floor(q)`` -- returns a [[BigInt]] for the greatest integer ``<= q``
 - ``ceil(q)``  -- returns a [[BigInt]] for the least integer ``>= q``
 - ``round(q)`` -- returns a [[BigInt]] which is the nearest to ``q``
                   (halves round the same way as in ``RoundDiv``, see [[BigIntOps]])
 - ``num(q)``   -- returns a [[BigInt]] which is the numerator of ``q``
 - ``den(q)``   -- returns a positive [[BigInt]] which is the denominator of ``q``
 - ``log(q)``   -- returns a double whose value is (approx) the natural logarithm of ``q``
 - ``FloorLog2(q) -- same as ``FloorLogBase(q,2)``
 - ``FloorLog10(q) -- same as ``FloorLogBase(q,10)``
 - ``FloorLogBase(q,base)`` -- returns largest integer ``k`` such that ``power(base,k) <= abs(q)``
 - ``mantissa(q)`` -- returns a ``double`` between 0.5 and 1 (excluded)
 - ``exponent(q)`` -- 
 -
+

==== Conversion functions ====
Only for [[BigInt]]
- ``mantissa(N)`` -- ``N`` represented as a floating-point number.
  	    If ``N`` is zero, produces 0.0.
            If ``N>0``, produces a value between 0.5 and 0.999...;
            otherwise (when ``N<0``) a value between -0.5 and -0.999...
            The bits of the floating point result are the topmost
            bits of the binary representation of ``N``.
- ``exponent(N)`` -- result is a ``long`` whose value is the least integer e such that
              2^e > abs(n).  If ``N`` is zero, result is zero.
-

==== Miscellany ====
Only for [[BigInt]]
- ``SizeInBase(N, b)`` -- (returns ``long``) the number of digits ``N`` has
                         when written in base ``b``.  Very fast!
                         **WARNING** the result may sometimes to be too large by 1; use ``1+FloorLogBase(N)`` to get the exact result.
-





== Maintainer Documentation ==
%======================================================================

Most impls are very simple (since GMP does all the real work).


== Bugs, shortcomings and other ideas ==
%======================================================================

Impl of ``FloorLogBase`` is ugly!

There are some NYI functions!


== Main changes ==
%======================================================================

**2018**
- June
 - split off from [[BigRat]]
 


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% For "txt2tags safety" leave 2 empty lines after the last line of text.
