function.ref

任意精度的数学库

-----------------------------------------------------------------------------
                        MAPM Function Descriptions              Sept 24, 1999
-----------------------------------------------------------------------------

Prototype:  M_APM  m_apm_init(void);

Example:    M_APM  apmvalue;
            apmvalue = m_apm_init();

            This function initializes a new MAPM value. The value 0 is 
	    assigned to the variable. This function must be called before 
	    any MAPM operation is performed on the value. This is because 
	    it is analogous to :

	    char  *p;
	    .
	    .
	    memset(p, 'A', 10000);

	    The above example will likely fail because 'p' does not point 
	    to a valid memory block yet. The same is true of an MAPM value
	    that is declared but not yet initialized.

-----------------------------------------------------------------------------

Prototype:  void  m_apm_free(M_APM);

Example:    M_APM  apmvalue;
            m_apm_free(apmvalue);

            This function will free the memory previously allocated by 
	    'm_apm_init'.

-----------------------------------------------------------------------------

Prototype:  void  m_apm_set_string(M_APM, char *);

Example:    M_APM  apmvalue;
	    char   in_string[128];
            m_apm_set_string(apmvalue, in_string);

            This function will set the MAPM value to the value specified 
	    by the string variable. Integers and floating point are supported
	    as is floating point with scientific notation.

	    o) Lead-in whitespace is ignored.
	    o) A lead-in '+' sign is optional.
	    o) A negative number must have '-' as the first non-whitespace char
	    o) An exponent, 'E' or 'e', is optional.
	    o) The decimal point is optional. The decimal point may be 
	       anywhere in the number, but before the exponent.
	    o) The exponent may have an optional '+' sign.
	    o) The exponent must be an integer value (no decimal point)

            m_apm_set_string(apmvalue, "-23");
            m_apm_set_string(apmvalue, "1964.425206");
            m_apm_set_string(apmvalue, "-9.344218785E-12");
            m_apm_set_string(apmvalue, "+987622.87633e+27");
            m_apm_set_string(apmvalue, ".0000004217");

-----------------------------------------------------------------------------

Prototype:  void  m_apm_set_long(M_APM, long);

Example:    M_APM  apmvalue;
	    long   longval;
            m_apm_set_long(apmvalue, longval);

            This function will set the MAPM value to the value specified 
	    by the long variable. 

            m_apm_set_long(apmvalue, -203L);
            m_apm_set_long(apmvalue, 1964L);
            m_apm_set_long(apmvalue, 5219954L);

-----------------------------------------------------------------------------

Prototype:  void  m_apm_set_double(M_APM, double);

Example:    M_APM   apmvalue;
	    double  doubleval;
            m_apm_set_double(apmvalue, doubleval);

            This function will set the MAPM value to the value specified 
	    by the double variable. The double value will be rounded to
	    the 15 most significant digits and then converted to the MAPM 
	    value. If you want an 'exact' conversion, use the m_apm_set_string 
	    function since some C floating point library's may round your 
	    double in an unpredictable manner.

            m_apm_set_double(apmvalue, -2.03);
            m_apm_set_double(apmvalue, 21887.4421964);
            m_apm_set_double(apmvalue, -9.4421E-3);

-----------------------------------------------------------------------------

Prototype:  void  m_apm_to_string(char *, int, M_APM);

Example:    M_APM   apmvalue;
	    int     decimal_places;
	    char    out_string[256];
            m_apm_to_string(out_string, decimal_places, apmvalue);

            This function will convert an MAPM value into a string and is
	    meant to be used with floating point MAPM values.  The output 
	    string must be large enough to hold the result. The output 
	    string will be always be in scientific (exponential) notation. 
	    There will be a leading '-' sign for negative numbers. There 
	    will be 'decimal_places' number of digits after the decimal 
	    point. If decimal_places is >= 0, the value will be rounded to 
	    that number of digits and then the string will be filled, with 
	    trailing zero's appended if necessary to fill out the decimal
	    place specification. If decimal_places < 0, ALL the significant 
	    digits of the MAPM number will be output. In some applications, 
	    it is convienent to round the value yourself (see 'm_apm_round') 
	    and then display ALL the digits.

            If apmvalue is == 3.640083E-4 :

            1)  m_apm_to_string(out_string, 4, apmvalue);
	        out_string -> "3.6401E-4"

            2)  m_apm_to_string(out_string, 14, apmvalue);
	        out_string -> "3.64008300000000E-4"

            3)  m_apm_to_string(out_string, -1, apmvalue);
	        out_string -> "3.640083E-4"

-----------------------------------------------------------------------------

Prototype:  void  m_apm_to_integer_string(char *, M_APM);

Example:    M_APM   apmvalue;
	    char    out_string[256];
            m_apm_to_integer_string(out_string, apmvalue);

            This function will convert an MAPM value into a string and is
	    meant to be used with integer values. The output string must 
	    be large enough to hold the result. If the MAPM number is not
	    an integer, the function will truncate the value to the nearest 
	    integer and the output will be formatted as an integer, with a 
	    possible leading '-' sign.

	    Examples:

	    M_APM Value            Output String
	    -----------            -------------
	    3.28E+2                "328"
	    -4.56993E+2            "-456"
	    4.32E-3                "0"
	    -1.62E+5               "-162000"

-----------------------------------------------------------------------------

Prototype:  void  m_apm_absolute_value(M_APM, M_APM);

Example:    M_APM  apmresult, apmvalue;
            m_apm_absolute_value(apmresult, apmvalue);

            This function will take the absolute value of 'apmvalue'
	    and put it in 'apmresult'.  The 'apmresult' parameter cannot 
	    be the other MAPM parameter.

-----------------------------------------------------------------------------

Prototype:  void  m_apm_negate(M_APM, M_APM);

Example:    M_APM  apmresult, apmvalue;
            m_apm_negate(apmresult, apmvalue);

            This function will negate the value of 'apmvalue' and put it 
	    in 'apmresult'.  The 'apmresult' parameter cannot be the 
	    other MAPM parameter.

-----------------------------------------------------------------------------

Prototype:  void  m_apm_copy(M_APM, M_APM);

Example:    M_APM  apmresult, apmvalue;
            m_apm_copy(apmresult, apmvalue);

            This function will copy the value of 'apmvalue' and put it 
	    in 'apmresult'.  The 'apmresult' parameter cannot be the 
	    other MAPM parameter.

-----------------------------------------------------------------------------

Prototype:  void  m_apm_round(M_APM, int, M_APM);

Example:    M_APM  apmresult, apmvalue;
	    int    decimal_places;
            m_apm_round(apmresult, decimal_places, apmvalue);

            This function will round the value of 'apmvalue' to the number 
	    of decimal places specified and put it in 'apmresult'. The 
	    decimal places parameter is referenced to the number when the
	    number is in scientific notation.  The 'apmresult' parameter 
	    cannot be the other MAPM parameter.

-----------------------------------------------------------------------------

Prototype:  int   m_apm_compare(M_APM, M_APM);

Example:    M_APM   apm_num1, apm_num2;
	    int     cmp_result;
            cmp_result = m_apm_compare(apm_num1, apm_num2);

            This function will compare the value of apm_num1 to apm_num2.
	    The function will return :
	    -1 : num1 < num2
	     0 : num1 = num2
	     1 : num1 > num2

-----------------------------------------------------------------------------

Prototype:  int   m_apm_sign(M_APM);

Example:    M_APM   apm_num;
	    int     sign_result;
            sign_result = m_apm_sign(apm_num);

            This function will return the sign of apm_num.
	    The function will return :
	    -1 : num < 0
	     0 : num = 0
	     1 : num > 0

-----------------------------------------------------------------------------

Prototype:  int   m_apm_exponent(M_APM);

Example:    M_APM   apm_num;
	    int     exponent;
            exponent = m_apm_exponent(apm_num);

            This function will return the exponent of apm_num.

	    If apm_num = 3.86742E+12,    12 will be returned.
	               = 9.61082E-56,   -56 will be returned.

-----------------------------------------------------------------------------

Prototype:  int   m_apm_significant_digits(M_APM);

Example:    M_APM   apm_num;
	    int     digits;
            digits = m_apm_significant_digits(apm_num);

            This function will return the number of significant digits
	    in apm_num. This may be used to determine how big to malloc
	    a char array so the full number can be converted to a string.

	    If apm_num = 3.86742E+12    :  6 will be returned.
	               = -96108.27608   : 10 will be returned.

-----------------------------------------------------------------------------

Prototype:  void    m_apm_get_random(M_APM);

Example:    M_APM   random_number;
            m_apm_get_random(random_number);

            This function will return a random floating point number 
	    between the values 0 and 1. The first time the function is 
	    called the generator is initialized with the system time. 
	    This generator will not repeat its pattern until 1.0E+15 
	    numbers have been generated.

	    Note that the MAPM parameter passed may be used for other
	    purposes. The function itself maintains the correct sequence 
	    and just returns a copy of the next random number.

-----------------------------------------------------------------------------

Prototype:  void  m_apm_add(M_APM, M_APM, M_APM);

Example:    M_APM  apmresult, apm_num1, apm_num2;
            m_apm_add(apmresult, apm_num1, apm_num2);

            This function will add apm_num1 to apm_num2 and put the result
	    in 'apmresult'.  The 'apmresult' parameter cannot be one of 
	    the other MAPM parameters.

-----------------------------------------------------------------------------

Prototype:  void  m_apm_subtract(M_APM, M_APM, M_APM);

Example:    M_APM  apmresult, apm_num1, apm_num2;
            m_apm_subtract(apmresult, apm_num1, apm_num2);

            This function will subtract apm_num2 from apm_num1 and put the 
	    result in 'apmresult'.  (result = num1 - num2)  The 'apmresult' 
	    parameter cannot be one of the other MAPM parameters.

-----------------------------------------------------------------------------

Prototype:  void  m_apm_multiply(M_APM, M_APM, M_APM);

Example:    M_APM  apmresult, apm_num1, apm_num2;
            m_apm_multiply(apmresult, apm_num1, apm_num2);

            This function will multiply apm_num1 and apm_num2 and put the 
	    result in 'apmresult'.  The 'apmresult' parameter cannot be 
	    one of the other MAPM parameters.

-----------------------------------------------------------------------------

Prototype:  void  m_apm_divide(M_APM, int, M_APM, M_APM);