float.tex

精确小数算法库,可以实现任意长度的精确小数算法,用c语言实现,主要用于密码学中小数计算,验证可用

\section{Data Movement}
\subsection{Copying}
In order to copy one mp\_float into another mp\_float the following function has been provided.

\index{mpf\_copy}
\begin{alltt}
int  mpf_copy(mp_float *src, mp_float *dest);
\end{alltt}
This will copy the mp\_float from $src$ into $dest$.  Note that the final radix of $dest$ will be that of $src$.

\begin{alltt}
int main(void)
\{
   mp_float a, b;
   int err;

   /* initialize two mp_floats with a 96-bit mantissa */
   if ((err = mpf_init_multi(96, &a, &b, NULL)) != MP_OKAY) \{
      // error handle
   \}

   /* we now have two 96-bit mp_floats ready ... do work */

   /* put a into b */
   if ((err = mpf_copy(&a, &b)) != MP_OKAY) \{
      // error handle
   \}
   
   /* done */
   mpf_clear_multi(&a, &b, NULL);

   return EXIT_SUCCESS;
\}
\end{alltt}

\subsection{Exchange}

To exchange the contents of two mp\_float data types use this f00.

\index{mpf\_exch}
\begin{alltt}
void mpf_exch(mp_float *a, mp_float *b);
\end{alltt}

This will swap the contents of $a$ and $b$.  

\chapter{Basic Operations}
\section{Normalization}

\subsection{Simple Normalization}
Normalization is not required by the user unless they fiddle with the mantissa on their own.  If that's the case you can
use this function.
\index{mpf\_normalize}
\begin{alltt}
int  mpf_normalize(mp_float *a);
\end{alltt}
This will fix up the mantissa of $a$ such that the leading bit is one (if the number is non--zero).  

\subsection{Normalize to New Radix}
In order to change the radix of a non--zero number you must call this function.

\index{mpf\_normalize\_to}
\begin{alltt}
int  mpf_normalize_to(mp_float *a, long radix);
\end{alltt}
This will change the radix of $a$ then normalize it accordingly.

\section{Constants}

\subsection{Quick Constants}
The following are helpers for various numbers.

\index{mpf\_const\_0} \index{mpf\_const\_d} \index{mpf\_const\_ln\_d} \index{mpf\_const\_sqrt\_d}
\begin{alltt}
int  mpf_const_0(mp_float *a);
int  mpf_const_d(mp_float *a, long d);
int  mpf_const_ln_d(mp_float *a, long b);
int  mpf_const_sqrt_d(mp_float *a, long b);
\end{alltt}

mpf\_const\_0 will set $a$ to a valid representation of zero.  mpf\_const\_d will set $a$ to a valid signed representation of 
$d$.  mpf\_const\_ln\_d will set $a$ to the natural logarithm of $b$.  mpf\_const\_sqrt\_d will set $a$ to the square root of
$b$.

The next set of constants (fig. \ref{fig:const}) compute the standard constants as defined in ``math.h''.  
\begin{figure}[here]
\begin{center}
\begin{tabular}{|l|l|}
\hline \textbf{Function Name} & \textbf{Value} \\
mpf\_const\_e & $e$ \\
mpf\_const\_l2e & log$_2(e)$ \\
mpf\_const\_l10e & log$_{10}(e)$ \\
mpf\_const\_le2  & ln$(2)$ \\
mpf\_const\_pi  & $\pi$ \\
mpf\_const\_pi2  & $\pi / 2$ \\
mpf\_const\_pi4  & $\pi / 4$ \\
mpf\_const\_1pi  & $1 / \pi$ \\
mpf\_const\_2pi  & $2 / \pi$ \\
mpf\_const\_2rpi  & $2 / \sqrt{\pi}$ \\
mpf\_const\_r2  & ${\sqrt{2}}$ \\
mpf\_const\_1r2  & $1 / {\sqrt{2}}$ \\
\hline
\end{tabular}
\end{center}
\caption{LibTomFloat Constants.}
\label{fig:const}
\end{figure}

All of these functions accept a single input argument.  They calculate the constant at run--time using the precision specified in the input
argument.  

\begin{alltt}
int main(void)
\{
   mp_float a;
   int err;

   /* initialize a mp_float with a 96-bit mantissa */
   if ((err = mpf_init(&a, 96)) != MP_OKAY) \{
      // error handle
   \}

   /* let's find out what the square root of 2 is (approximately ;-)) */
   if ((err = mpf_const_r2(&a)) != MP_OKAY) \{
      // error handle 
   \}

   /* now a has sqrt(2) to 96-bits of precision */

   /* done */
   mpf_clear(&a);

   return EXIT_SUCCESS;
\}
\end{alltt}

\section{Sign Manipulation}
To manipulate the sign of a mp\_float use the following two functions.

\index{mpf\_abs} \index{mpf\_neg}
\begin{alltt}
int  mpf_abs(mp_float *a, mp_float *b);
int  mpf_neg(mp_float *a, mp_float *b);
\end{alltt}

mpf\_abs computes the absolute of $a$ and stores it in $b$.  mpf\_neg computes the negative of $a$ and stores it in $b$.  Note that the numbers
are normalized to the radix of $b$ before being returned.  

\begin{alltt}
int main(void)
\{
   mp_float a;
   int err;

   /* initialize a mp_float with a 96-bit mantissa */
   if ((err = mpf_init(&a, 96)) != MP_OKAY) \{
      // error handle
   \}

   /* let's find out what the square root of 2 is (approximately ;-)) */
   if ((err = mpf_const_r2(&a)) != MP_OKAY) \{
      // error handle 
   \}

   /* now make it negative */
   if ((err = mpf_neg(&a, &a)) != MP_OKAY) \{
      // error handle 
   \}
   
   /* done */
   mpf_clear(&a);

   return EXIT_SUCCESS;
\}
\end{alltt}

\chapter{Basic Algebra}
\section{Algebraic Operators}

The following four functions provide for basic addition, subtraction, multiplication and division of mp\_float numbers.

\index{mpf\_add} \index{mpf\_sub} \index{mpf\_mul} \index{mpf\_div} 
\begin{alltt}
int  mpf_add(mp_float *a, mp_float *b, mp_float *c);
int  mpf_sub(mp_float *a, mp_float *b, mp_float *c);
int  mpf_mul(mp_float *a, mp_float *b, mp_float *c);
int  mpf_div(mp_float *a, mp_float *b, mp_float *c);
\end{alltt}
These functions perform their respective operations on $a$ and $b$ and store the result in $c$.  

\subsection{Additional Interfaces}
In order to make programming easier with the library the following four functions have been provided as well.

\index{mpf\_add\_d} \index{mpf\_sub\_d} \index{mpf\_mul\_d} \index{mpf\_div\_d} 
\begin{alltt}
int  mpf_add_d(mp_float *a, long b, mp_float *c);
int  mpf_sub_d(mp_float *a, long b, mp_float *c);
int  mpf_mul_d(mp_float *a, long b, mp_float *c);
int  mpf_div_d(mp_float *a, long b, mp_float *c);
\end{alltt}
These work like the previous four functions except the second argument is a ``long'' type.  This allow operations with 
mixed mp\_float and integer types (specifically constants) to be performed relatively easy.  

\textit{I will put an example of all op/op\_d functions here...}

\subsection{Additional Operators}
The next three functions round out the simple algebraic operators.

\index{mpf\_mul\_2} \index{mpf\_div\_2} \index{mpf\_sqr}
\begin{alltt}
int  mpf_mul_2(mp_float *a, mp_float *b);
int  mpf_div_2(mp_float *a, mp_float *b);
int  mpf_sqr(mp_float *a, mp_float *b);
\end{alltt}

mpf\_mul\_2 and mpf\_div\_2 multiply (or divide) $a$ by two and store it in $b$.  mpf\_sqr squares $a$ and stores it in $b$.  mpf\_sqr is
faster than using mpf\_mul for squaring mp\_floats.

\section{Comparisons}
To compare two mp\_floats the following function can be used.
\index{mp\_cmp}
\begin{alltt}
int  mpf_cmp(mp_float *a,   mp_float *b);
\end{alltt}
This will compare $a$ to $b$ and return one of the LibTomMath comparison flags.  Simply put, if $a$ is larger than $b$ it returns 
MP\_GT.  If $a$ is smaller than $b$ it returns MP\_LT, otherwise it returns MP\_EQ.  The comparison is signed.

To quickly compare an mp\_float to a ``long'' the following is provided.

\index{mpf\_cmp\_d}
\begin{alltt}
int  mpf_cmp_d(mp_float *a, long b, int *res);
\end{alltt}

Which compares $a$ to $b$ and stores the result in $res$.  This function can fail which is unlike the digit compare from LibTomMath.

\chapter{Advanced Algebra}
\section{Powers}
\subsection{Exponential}
The following function computes $exp(x)$ otherwise known as $e^x$.

\index{mpf\_exp}
\begin{alltt}
int  mpf_exp(mp_float *a, mp_float *b);
\end{alltt}

This computes $e^a$ and stores it into $b$.  

\subsection{Power Operator}
The following function computes the generic $a^b$ operation.  

\index{mpf\_pow}
\begin{alltt}
int  mpf_pow(mp_float *a, mp_float *b, mp_float *c);
\end{alltt}
This computes $a^b$ and stores the result in $c$.

\subsection{Natural Logarithm}

The following function computes the natural logarithm.
\index{mpf\_ln}
\begin{alltt}
int  mpf_ln(mp_float *a, mp_float *b);
\end{alltt}
This computes $ln(a)$ and stores the result in $b$.

\section{Inversion and Roots}

\subsection{Inverse Square Root}
The following function computes $1 / \sqrt{x}$.

\index{mpf\_invsqrt}
\begin{alltt}
int  mpf_invsqrt(mp_float *a, mp_float *b);
\end{alltt}

This computes $1 / \sqrt{a}$ and stores the result in $b$.

\subsection{Inverse}

The following function computes $1 / x$.
\index{mpf\_inv}
\begin{alltt}
int  mpf_inv(mp_float *a, mp_float *b);
\end{alltt}
This computes $1/a$ and stores the result in $b$.


\subsection{Square Root}

The following function computes $\sqrt{x}$.

\index{mpf\_sqrt}
\begin{alltt}
int  mpf_sqrt(mp_float *a, mp_float *b);
\end{alltt}

This computes $\sqrt{a}$ and stores the result in $b$.

\section{Trigonometry Functions}
The following functions compute various trigonometric functions.  All inputs are assumed to be in radians.

\index{mpf\_cos} \index{mpf\_sin} \index{mpf\_tan} \index{mpf\_acos} \index{mpf\_asin} \index{mpf\_atan} 
\begin{alltt}
int  mpf_cos(mp_float *a, mp_float *b);
int  mpf_sin(mp_float *a, mp_float *b);
int  mpf_tan(mp_float *a, mp_float *b);
int  mpf_acos(mp_float *a, mp_float *b);
int  mpf_asin(mp_float *a, mp_float *b);
int  mpf_atan(mp_float *a, mp_float *b);
\end{alltt}

These all compute their respective trigonometric function on $a$ and store the result in $b$.  The ``a'' prefix stands for ``arc'' or more
commonly known as inverse.  

\input{float.ind}

\end{document}