MPINT(3) BSD Library Functions Manual MPINT(3)NAMElibmpint- multiple-precision integer arithmeticSYNOPSIS#include<mpint.h>mp_t*mp_add(mp_t*r,mp_t*a);mp_t*mp_add_d(mp_t*r,mp_digit_td);mp_t*mp_and(mp_t*r,mp_t*a);mp_t*mp_clear(mp_t*r);intmp_cmp(mp_t*a,mp_t*b);mp_t*mp_copy(mp_t*r,mp_t*a);char*mp_cvt(mp_t*r,intbase);mp_digit_tmp_digitAt(mp_t*r,mp_size_ti);mp_digit_tmp_digitAtPut(mp_t*r,mp_size_ti,mp_digit_t_d);mp_t*mp_div(mp_t*quo,mp_t*rem,mp_t*dend,mp_t*ds_or);mp_digit_tmp_div_d(mp_t*quo,mp_digit_td);mp_t*mp_mul(mp_t*r,mp_t*a);mp_t*mp_mul_d(mp_t*r,mp_digit_td);mp_t*mp_neg(mp_t*r);mp_t*mp_normalise(mp_t*r);mp_t*mp_not(mp_t*r);mp_t*mp_or(mp_t*r,mp_t*a);mp_t*mp_shift(mp_t*r,intn);mp_t*mp_shiftl(mp_t*r,mp_size_tn);mp_t*mp_shiftr(mp_t*r,mp_size_tn);mp_digit_tmp_sub(mp_t*r,mp_t*a);mp_digit_tmp_sub_d(mp_t*r,mp_digit_td);mp_digit_tmp_subf_d(mp_t*r,mp_digit_td);mp_t*mp_xor(mp_t*r,mp_t*a);intmp_zerop(mp_t*a);DESCRIPTIONThe mpint library provides operations on multiple-precision integers. Each MP integer is stored as amp_tstructure containing at least the following fields: typedef struct { mp_size_t width; mp_digit_t *bits; } mp_t; These members can be statically initialised (to zero) using the value of theMP_INITIALISERmacro. mp_t my_mp = MP_INITIALISER; When no longer needed, any resources associated with amp_tobject should be released usingmp_clear(): mp_clear(&my_mp);OPERATORSAll operators work on pointers to objects of typemp_t. Most operators return their first argument (the first operand of the operation and the object into which the result is stored). In the descriptions below, the return value will only be mentioned explicitly in cases where it does not conform to this convention. Some operators take an integer of typemp_digit_tas argument. This integer represents a single "digit" within a multi-precision integer. Digits are nominally 32 bits wide, but arguments of typemp_digit_tshould never exceed 31 bits to avoid risk of overflowing the single bit of carry internallyt propagated between digits by certain operations.mp_t*mp_add(mp_t*r,mp_t*a) Computes the sum ofrandaand stores the result inr.mp_t*mp_add_d(mp_t*r,mp_digit_td) Computes the sum ofrand the single digitdand stores the result inr.mp_t*mp_and(mp_t*r,mp_t*a) Computes the bitwise "and" ofrandaand stores the result inr.mp_t*mp_clear(mp_t*r) Frees any resources associated withrand resets it to zero.intmp_cmp(mp_t*a,mp_t*b) Comparesaandband returns -1, 0 or 1 ifais less than, equal to, or greater thanbrespectively.mp_t*mp_copy(mp_t*r,mp_t*a) Copies the value ofaintor. (Subsequent modifications to one will be independe of the other.) Returns a pointer to the ascii representation ofrin the givenbase. (The contents of the storage pointed to will be overwritten on subsequent calls. This function is not reentrant.)mp_digit_tmp_digitAt(mp_t*r,mp_size_ti) Returns digit at indexi(numbered from zero) inr.mp_digit_tmp_digitAtPut(mp_t*r,mp_size_ti, _mp_digit_td) Sets the digit at indexi(numbered from zero) inrtodand returnsd.mp_t*mp_div(mp_t*quo,mp_t*rem,mp_t*dend,mp_t*dsor) Dividesdendbydsorand stores the quotient inquoand the remainder inrem. Returnsquo. Ifdsoris zero then no division occurs (nor is any error signalled).mp_digit_tmp_div_d(mp_t*quo,mp_digit_td) Dividesquoby the single digitd, stores the result inquo, and returnsquo. Ifdis zero then no division occurs (nor is any error signalled).mp_t*mp_mul(mp_t*r,mp_t*a) Multipliesrbyaand stores the result inr.mp_t*mp_mul_d(mp_t*r,mp_digit_td) Multiplesrby the single digitdand stores the result inr.mp_t*mp_neg(mp_t*r) Negates (takes the two's complement of)rand stores it back intor. Removes leading zeros fromr. (This operator should not nor- mally be used. It is called implicitly by the other operators whenever appropriate.)mp_t*mp_not(mp_t*r) Inverts (takes the ones's complement of)rand stores the it back intor.mp_t*mp_or(mp_t*r,mp_t*a) Computes the bitwise inclusive "or" ofrandaand stores it inr.mp_t*mp_shift(mp_t*r,intn) Shiftsrleft bynbits and stores the result inr. (Ifnis negative thenris shifted right bynbits.)mp_t*mp_shiftl(mp_t*r,mp_size_tn) Shiftsrleft bynbits. (This operator has no effect ifnis negative.)mp_t*mp_shiftr(mp_t*r,mp_size_tn) Shiftsrright bynbits. (This operator has no effect ifnis negative.)mp_digit_tmp_sub(mp_t*r,mp_t*a) Subtractsafromrand stores the result inr. Returns the carry ("not borrow") bit generated from the operation; i.e., 1 if there was no borrow out of the most significant digit inr, 0 if there was a borrow. (The carry is useful when implementing "sign+magnitude" multi- precision arithmetic as a wrapper around unsigned multi-precision integers. If carry is generated during subtraction then bit- inverting the result and adding one will yield the correct magni- tude; the "sign" of the result will be the opposite of that of the left hand operand. Similar pre- and post-processing will be required for all signed binary operands and results. See any decent introductory CS textbook for details.)mp_digit_tmp_sub_d(mp_t*r,mp_digit_td) Subtracts the single digitdfromrand stores the result inr. Answers the carry ("not borrow") generated from the subtraction.mp_digit_tmp_subf_d(mp_t*r,mp_digit_td) Subtractsrfrom the single digitdand stores the result inr. Answers the carry ("not borrow") generated from the subtraction.mp_t*mp_xor(mp_t*r,mp_t*a) Computes the bitwise exclusive "or" ofrandaand stores the result inr.intmp_zerop(mp_t*a) Returns 1 ifais zero, otherwise 0.RETURNVALUESMost operators return their first argument, which is both the left hand operand and the location into which the result of the operation is stored. Predicates and comparison operators return an integer represent- ing the result of the test. Subtraction operators return the single digit carry ("not borrow") out of the most significant digit.EXAMPLESThe following program prints the factorials of the first 50 non-zero pos- itive integers on the standard output. #include <mpint.h> #include <stdio.h> int main() { int i; mp_t mp = MP_INITIALISER; mp_digitAtPut(&mp, 0, 1); for (i= 1; i <= 50; ++i) puts(mp_cvt(mp_mul_d(&mp, i), 10)); mp_clear(&mp); return 0; }COMPATIBILITYThe interface is similar to those provided by some other multi-precision integer libraries (most notably LibTomMath by Tom St Denis).AUTHORSThe software and manual pages were written by Ian Piumarta. The software is provided as-is, with absolutely no warranty, in the hope that you will enjoy and benefit from it. You may use (entirely at your own risk) and redistribute it under the terms of a very liberal license that does not threaten your project with infection by a debilitating infectious disease. See the file COPYING for details.BUGSNo checks are made for out-of-memory errors, nor for ridiculously large arguments that might cause requests for larger amounts of memory than the system could reasonably be expected to provide. Division by zero is detected and then silently ignored. The interface ofmp_div() is incongruent with the other operators: a lone three-address operator adrift in a sea of two-address operators. The library was written to support the conversion of floating point num- bers to ascii. Only those operators needed for that purpose have been tested more than superficially. The other operators were added for com- pleteness and probably still contain bugs. The header file should be called "mp_int.h" rather than "mpint.h". Please send bug reports (or suggestions for improvements) to the author at: firstName (at) lastName (dot) com. (SeeAUTHORSabove for suitable values of firstName and lastName.) BSD December 17, 2009 BSD