Return to README CVS log

Up to [local] / OpenXM_contrib / gmp

Annotation of OpenXM_contrib/gmp/README, Revision 1.1

1.1     ! maekawa     1:                        THE GNU MP LIBRARY
        !             2:
        !             3:
        !             4: GNU MP is a library for arbitrary precision arithmetic, operating on signed
        !             5: integers, rational numbers, and floating point numbers.  It has a rich set
        !             6: of functions, and the functions have a regular interface.
        !             7:
        !             8: GNU MP is designed to be as fast as possible, both for small operands and for
        !             9: huge operands.  The speed is achieved by using fullwords as the basic
        !            10: arithmetic type, by using fast algorithms, by carefully optimized assembly
        !            11: code for the most common inner loops for a lots of CPUs, and by a general
        !            12: emphasis on speed (instead of simplicity or elegance).
        !            13:
        !            14: The speed of GNU MP is believed to be faster than any other similar library.
        !            15: The advantage for GNU MP increases with the operand sizes for certain
        !            16: operations, since GNU MP in many cases has asymptotically faster algorithms.
        !            17:
        !            18:
        !            19:                        GETTING STARTED
        !            20:
        !            21: First, you have to configure and compiler GNU MP.  Simply typing
        !            22:
        !            23:        ./configure; make
        !            24:
        !            25: will normally do a reasonable job, but will not give optimal library
        !            26: execution speed.  So unless you're very unpatient, please read the detailed
        !            27: instructions in the file INSTALL or in gmp.texi.
        !            28:
        !            29: Once you have compiled the library, you should write some small example, and
        !            30: make sure you can compile them.  A typical compilation command is this:
        !            31:
        !            32:        gcc -g your-file.c -I<gmp-source-dir> <gmp-bin-dir>libgmp.a -lm
        !            33:
        !            34: If you have installed the library, you can simply do:
        !            35:
        !            36:        gcc -g your-file.c -lgmp -lm
        !            37:
        !            38: The -lm is normally not needed, since only a few functions in GNU MP use the
        !            39: math library.
        !            40:
        !            41: Here is a sample program that declares 2 variables, initializes them as
        !            42: required, and sets one of them from a signed integer, and the other from a
        !            43: string of digits.  It then prints the product of the two numbers in base 10.
        !            44:
        !            45:   #include <stdio.h>
        !            46:   #include "gmp.h"
        !            47:
        !            48:   main ()
        !            49:   {
        !            50:     mpz_t a, b, p;
        !            51:
        !            52:     mpz_init (a);                      /* initialize variables */
        !            53:     mpz_init (b);
        !            54:     mpz_init (p);
        !            55:
        !            56:     mpz_set_si (a, 756839);            /* assign variables */
        !            57:     mpz_set_str (b, "314159265358979323846", 0);
        !            58:     mpz_mul (p, a, b);                 /* generate product */
        !            59:     mpz_out_str (stdout, 10, p);       /* print number without newline */
        !            60:     puts ("");                         /* print newline */
        !            61:
        !            62:     mpz_clear (a);                     /* clear out variables */
        !            63:     mpz_clear (b);
        !            64:     mpz_clear (p);
        !            65:
        !            66:     exit (0);
        !            67:   }
        !            68:
        !            69: This might look tedious, with all initializing and clearing.  Fortunately
        !            70: some of these operations can be combined, and other operations can often be
        !            71: avoided.  The example above would be written differently by an experienced
        !            72: GNU MP user:
        !            73:
        !            74:   #include <stdio.h>
        !            75:   #include "gmp.h"
        !            76:
        !            77:   main ()
        !            78:   {
        !            79:     mpz_t b, p;
        !            80:
        !            81:     mpz_init (p);
        !            82:
        !            83:     mpz_init_set_str (b, "314159265358979323846", 0);
        !            84:     mpz_mul_ui (p, b, 756839);         /* generate product */
        !            85:     mpz_out_str (stdout, 10, p);       /* print number without newline */
        !            86:     puts ("");                         /* print newline */
        !            87:
        !            88:     exit (0);
        !            89:   }
        !            90:
        !            91:
        !            92:                        OVERVIEW OF GNU MP
        !            93:
        !            94: There are five classes of functions in GNU MP.
        !            95:
        !            96:  1. Signed integer arithmetic functions, mpz_*.  These functions are intended
        !            97:     to be easy to use, with their regular interface.  The associated type is
        !            98:     `mpz_t'.
        !            99:
        !           100:  2. Rational arithmetic functions, mpq_*.  For now, just a small set of
        !           101:     functions necessary for basic rational arithmetics.  The associated type
        !           102:     is `mpq_t'.
        !           103:
        !           104:  3. Floating-point arithmetic functions, mpf_*.  If the C type `double'
        !           105:     doesn't give enough precision for your application, declare your
        !           106:     variables as `mpf_t' instead, set the precision to any number desired,
        !           107:     and call the functions in the mpf class for the arithmetic operations.
        !           108:
        !           109:  4. Positive-integer, hard-to-use, very low overhead functions are in the
        !           110:     mpn_* class.  No memory management is performed.  The caller must ensure
        !           111:     enough space is available for the results.  The set of functions is not
        !           112:     regular, nor is the calling interface.  These functions accept input
        !           113:     arguments in the form of pairs consisting of a pointer to the least
        !           114:     significant word, and a integral size telling how many limbs (= words)
        !           115:     the pointer points to.
        !           116:
        !           117:     Almost all calculations, in the entire package, are made by calling these
        !           118:     low-level functions.
        !           119:
        !           120:  5. Berkeley MP compatible functions.
        !           121:
        !           122:     To use these functions, include the file "mp.h".  You can test if you are
        !           123:     using the GNU version by testing if the symbol __GNU_MP__ is defined.
        !           124:
        !           125: For more information on how to use GNU MP, please refer to the documentation.
        !           126: It is composed from the file gmp.texi, and can be displayed on the screen or
        !           127: printed.  How to do that, as well how to build the library, is described in
        !           128: the INSTALL file in this directory.
        !           129:
        !           130:
        !           131:                        REPORTING BUGS
        !           132:
        !           133: If you find a bug in the library, please make sure to tell us about it!
        !           134:
        !           135: Report bugs and propose modifications and enhancements to
        !           136: bug-gmp@prep.ai.mit.edu.  What information is needed in a good bug report is
        !           137: described in the manual.