\input texinfo @setfilename mpc.info @settitle MPC @value{VERSION} @synindex tp fn @iftex @afourpaper @end iftex @include version.texi @set DATE October 2007 @set AUTHORS Andreas Enge, Paul Zimmermann @set COPYRIGHTDATES 2002, 2003, 2004, 2005, 2007 @ifinfo @format START-INFO-DIR-ENTRY * mpc: (mpc.info). Multiple Precision Complex Library. END-INFO-DIR-ENTRY @end format @end ifinfo @iftex @finalout @end iftex @copying @ifinfo This is the manual for MPC, a library for multiple precision complex arithmetic, version @value{VERSION}, of @value{DATE}. @end ifinfo @sp 1 Copyright (C) @value{COPYRIGHTDATES} @value{AUTHORS} @sp 2 Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. @ignore Permission is granted to process this file through TeX and print the results, provided the printed document carries copying permission notice identical to this one except for the removal of this paragraph (this paragraph not being relevant to the printed manual). @end ignore Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions. @end copying @setchapternewpage on @titlepage @title MPC @subtitle The Multiple Precision Complex Library @subtitle Edition @value{VERSION} @subtitle @value{DATE} @author @value{AUTHORS} @tex \global\parindent=0pt \global\parskip=8pt \global\baselineskip=13pt @end tex @page @vskip 0pt plus 1filll @insertcopying @end titlepage @headings double @ifnottex @node Top, Copying, (dir), (dir) @top MPC This manual documents how to install and use the Multiple Precision Complex Library, version @value{VERSION} @end ifnottex @menu * Copying:: MPC Copying Conditions (LGPL). * Introduction to MPC :: Brief introduction to MPC. * Installing MPC:: How to configure and compile the MPC library. * MPC Basics:: What every MPC user should know. * Reporting Bugs:: How to usefully report bugs. * Complex Functions:: Functions for arithmetic on complex numbers. * Contributors:: * References:: * Concept Index:: * Function Index:: @end menu @node Copying, Introduction to MPC, Top, Top @comment node-name, next, previous, up @unnumbered MPC Copying Conditions @cindex Copying conditions @cindex Conditions for copying MPC This library is @dfn{free}; this means that everyone is free to use it and free to redistribute it on a free basis. The library is not in the public domain; it is copyrighted and there are restrictions on its distribution, but these restrictions are designed to permit everything that a good cooperating citizen would want to do. What is not allowed is to try to prevent others from further sharing any version of this library that they might get from you.@refill Specifically, we want to make sure that you have the right to give away copies of the library, that you receive source code or else can get it if you want it, that you can change this library or use pieces of it in new free programs, and that you know you can do these things.@refill To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights. For example, if you distribute copies of the MPC library, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights.@refill Also, for our own protection, we must make certain that everyone finds out that there is no warranty for the MPC library. If it is modified by someone else and passed on, we want their recipients to know that what they have is not what we distributed, so that any problems introduced by others will not reflect on our reputation.@refill The precise conditions of the license for the MPC library are found in the Lesser General Public License that accompanies the source code. See the file COPYING.LIB.@refill @node Introduction to MPC, Installing MPC, Copying, Top @comment node-name, next, previous, up @chapter Introduction to MPC MPC is a portable library written in C for arbitrary precision arithmetic on complex numbers. It is based on the GNU MP library. This version of MPC is released under the GNU Lesser General Public License. It is permitted to link MPC to non-free programs, as long as when distributing them the MPC source code and a means to re-link with a modified MPC is provided. @section How to use this Manual Everyone should read @ref{MPC Basics}. If you need to install the library yourself, you need to read @ref{Installing MPC}, too. The rest of the manual can be used for later reference, although it is probably a good idea to glance through it. @node Installing MPC, Reporting Bugs, Introduction to MPC, Top @comment node-name, next, previous, up @chapter Installing MPC @cindex Installation To build MPC, you first have to install GNU MP (version 4.2.2 or higher) and MPFR (version 2.2.1 or higher) on your computer. You need a C compiler, preferably GCC, but any reasonable compiler should work. And you need a standard Unix @samp{make} program, plus some other standard Unix utility programs. Here are the steps needed to install the library on Unix systems: @enumerate @item @samp{tar xzf mpc-@value{VERSION}.tar.gz} @item @samp{cd mpc-@value{VERSION}} @item @samp{./configure} if GMP and MPFR are installed into standard directories, that is, directories that are searched by default by the compiler and the linking tools. @samp{./configure --with-gmp=} is used to indicate a different location where GMP is installed. @samp{./configure --with-mpfr=} is used to indicate a different location where MPFR is installed. @samp{./configure --with-gmp= --with-mpfr=} is used to indicate different locations of GMP and MPFR. @emph{Warning!} Do not use these options if you have CPPFLAGS and/or LDFLAGS containing a -I or -L option with a directory that contains a GMP header or library file, as these options just add -I and -L options to CPPFLAGS and LDFLAGS @emph{after} the ones that are currently declared, so that DIR will have a lower precedence. Also, this may not work if DIR is a system directory. @item @samp{make} This compiles MPC in the working directory. @item @samp{make check} This will make sure MPC was built correctly. If you get error messages, please report them to @samp{mpc-discuss@@lists.gforge.inria.fr} (@xref{Reporting Bugs}, for information on what to include in useful bug reports). @item @samp{make install} This will copy the file @file{mpc.h} to the directory @file{/usr/local/include}, the file @file{libmpc.a} to the directory @file{/usr/local/lib}, and the file @file{mpc.info} to the directory @file{/usr/local/share/info} (or if you passed the @samp{--prefix} option to @file{configure}, using the prefix directory given as argument to @samp{--prefix} instead of @file{/usr/local}). Note: you need write permissions on these directories. @end enumerate @section Other `make' Targets There are some other useful make targets: @itemize @bullet @item @samp{mpc.info} or @samp{info} Create an info version of the manual, in @file{mpc.info}. @item @samp{mpc.pdf} or @samp{pdf} Create a PDF version of the manual, in @file{mpc.pdf}. @item @samp{mpc.dvi} or @samp{dvi} Create a DVI version of the manual, in @file{mpc.dvi}. @item @samp{mpc.ps} or @samp{ps} Create a Postscript version of the manual, in @file{mpc.ps}. @item @samp{mpc.html} or @samp{html} Create a HTML version of the manual, in several pages in the directory @file{mpc.html}; if you want only one output HTML file, then type @samp{makeinfo --html --no-split mpc.texi} instead. @item @samp{clean} Delete all object files and archive files, but not the configuration files. @item @samp{distclean} Delete all files not included in the distribution. @item @samp{uninstall} Delete all files copied by @samp{make install}. @end itemize @section Known Build Problems MPC suffers from all bugs from the GNU MP and MPFR libraries, plus many many more. Please report other problems to @samp{enge@@lix.polytechnique.fr,zimmerma@@loria.fr}. @xref{Reporting Bugs}. @node Reporting Bugs, MPC Basics, Installing MPC, Top @comment node-name, next, previous, up @chapter Reporting Bugs @cindex Reporting bugs If you think you have found a bug in the MPC library, please investigate and report it. We have made this library available to you, and it is not to ask too much from you, to ask you to report the bugs that you find. There are a few things you should think about when you put your bug report together. You have to send us a test case that makes it possible for us to reproduce the bug. Include instructions on how to run the test case. You also have to explain what is wrong; if you get a crash, or if the results printed are incorrect and in that case, in what way. Please include compiler version information in your bug report. This can be extracted using @samp{cc -V} on some machines, or, if you are using gcc, @samp{gcc -v}. Also, include the output from @samp{uname -a}. If your bug report is good, we will do our best to help you to get a corrected version of the library; if the bug report is poor, we will not do anything about it (aside of chiding you to send better bug reports). Send your bug report to: @samp{enge@@lix.polytechnique.fr,zimmerma@@loria.fr}. If you think something in this manual is unclear, or downright incorrect, or if the language needs to be improved, please send a note to the same address. @node MPC Basics, Complex Functions, Reporting Bugs, Top @comment node-name, next, previous, up @chapter MPC Basics @cindex @file{mpc.h} All declarations needed to use MPC are collected in the include file @file{mpc.h}. It is designed to work with both C and C++ compilers. You should include that file in any program using the MPC library by adding the line @example #include "mpc.h" @end example @section Nomenclature and Types @cindex Complex number @tindex @code{mpc_t} @noindent @dfn{Complex number} or @dfn{Complex} for short, is a pair of two arbitrary precision floating-point numbers (for the real and imaginary parts). The C data type for such objects is @code{mpc_t}. @cindex Precision @tindex @code{mp_prec_t} @noindent The @dfn{Precision} is the number of bits used to represent the mantissa of the real and imaginary parts; the corresponding C data type is @code{mp_prec_t}. See the MPFR documentation for more details on the allowed precision range. @cindex Rounding Mode @tindex @code{mpc_rnd_t} @noindent The @dfn{rounding mode} specifies the way to round the result of a complex operation, in case the exact result can not be represented exactly in the destination mantissa; the corresponding C data type is @code{mpc_rnd_t}. A complex rounding mode is a pair of two rounding modes: one for the real part, one for the imaginary part. @section Function Classes There is only one class of functions in the MPC library, namely functions for complex arithmetic. The function names begin with @code{mpc_}. The associated type is @code{mpc_t}. @section MPC Variable Conventions As a general rule, all MPC functions expect output arguments before input arguments. This notation is based on an analogy with the assignment operator. MPC allows you to use the same variable for both input and output in the same expression. For example, the main function for floating-point multiplication, @code{mpc_mul}, can be used like this: @code{mpc_mul (x, x, x, rnd_mode)}. This computes the square of @var{x} with rounding mode @code{rnd_mode} and puts the result back in @var{x}. Before you can assign to an MPC variable, you need to initialize it by calling one of the special initialization functions. When you are done with a variable, you need to clear it out, using one of the functions for that purpose. A variable should only be initialized once, or at least cleared out between each initialization. After a variable has been initialized, it may be assigned to any number of times. For efficiency reasons, avoid to initialize and clear out a variable in loops. Instead, initialize it before entering the loop, and clear it out after the loop has exited. You do not need to be concerned about allocating additional space for MPC variables, since each of its real and imaginary part has a mantissa of fixed size. Hence unless you change its precision, or clear and reinitialize it, a complex variable will have the same allocated space during all its life. @node Complex Functions, Contributors, MPC Basics, Top @comment node-name, next, previous, up @chapter Complex Functions @cindex Complex functions The complex functions expect arguments of type @code{mpc_t}. The MPC floating-point functions have an interface that is similar to the GNU MP integer functions. The function prefix for operations on complex numbers is @code{mpc_}. @cindex User-defined precision The precision of a computation is defined as follows: Compute the requested operation exactly (with ``infinite precision''), and round the result to the destination variable precision with the given rounding mode. The MPC complex functions are intended to be a smooth extension of the IEEE P754 arithmetic. The results obtained on one computer should not differ from the results obtained on a computer with a different word size. @menu * Rounding Modes:: * Initializing Complex Numbers:: * Assigning Complex Numbers:: * Simultaneous Init & Assign:: * Complex Arithmetic:: * Complex Comparison:: * Special Complex Functions:: * I/O of Complex Numbers:: * Miscellaneous Complex Functions:: * Internals:: @end menu @node Rounding Modes, Initializing Complex Numbers, , Complex Functions @comment node-name, next, previous, up @cindex Rounding modes @section Rounding Modes A complex rounding mode is of the form @code{MPC_RNDxy} where @code{x} and @code{y} are one of @code{N} (to nearest), @code{Z} (towards zero), @code{U} (towards plus infinity), @code{D} (towards minus infinity). The first letter refers to the rounding mode for the real part, and the second one for the imaginary part. For example @code{MPC_RNDZU} indicates to round the real part towards zero, and the imaginary part towards plus infinity. The @samp{round to nearest} mode works as in the IEEE P754 standard: in case the number to be rounded lies exactly in the middle of two representable numbers, it is rounded to the one with the least significant bit set to zero. For example, the number 5, which is represented by (101) in binary, is rounded to (100)=4 with a precision of two bits, and not to (110)=6. Most MPC functions have a return value of type @code{int}, which is used to indicate the position of the rounded real or imaginary parts with respect to the exact (infinite precision) values. If this integer is @code{i}, the macros @code{MPC_INEX_RE(i)} and @code{MPC_INEX_IM(i)} give 0 if the corresponding rounded value is exact, a negative value if the rounded value is less than the exact one, and a positive value if it is greater than the exact one. However, some functions do not completely fulfill this: in some cases the sign is not guaranteed, and in some cases a non-zero value is returned although the result is exact; in these cases the function documentation explains the exact meaning of the return value. However, the return value never wrongly indicates an exact computation. @node Initializing Complex Numbers, Assigning Complex Numbers, Rounding Modes, Complex Functions @comment node-name, next, previous, up @section Initialization Functions @deftypefun void mpc_set_default_prec (mp_prec_t @var{prec}) Set the default precision to be @strong{exactly} @var{prec} bits. All subsequent calls to @code{mpc_init} will use this precision, but previously initialized variables are unaffected. This default precision is set to 53 bits initially. It is valid for the real and the imaginary parts alike. @end deftypefun @deftypefun mp_prec_t mpc_get_default_prec () Returns the default MPC precision in bits. @end deftypefun An @code{mpc_t} object must be initialized before storing the first value in it. The functions @code{mpc_init}, @code{mpc_init2} and @code{mpc_init3} are used for that purpose. @deftypefun void mpc_init (mpc_t @var{z}) Initialize @var{z}, and set its real and imaginary parts to NaN. Normally, a variable should be initialized once only or at least be cleared, using @code{mpc_clear}, between initializations. The precision of @var{x} is the default precision, which can be changed by a call to @code{mpc_set_default_prec}. @end deftypefun @deftypefun void mpc_init2 (mpc_t @var{z}, mp_prec_t @var{prec}) Initialize @var{z}, set its precision to be @var{prec} bits, and set its real and imaginary parts to NaN. @end deftypefun @deftypefun void mpc_init3 (mpc_t @var{z}, mp_prec_t @var{prec_r}, mp_prec_t @var{prec_i}) Initialize @var{z}, set the precision of its real part to @var{prec_r} bits, the precision of its imaginary part to @var{prec_i} bits, and set its real and imaginary parts to NaN. @end deftypefun @deftypefun void mpc_clear (mpc_t @var{z}) Free the space occupied by @var{z}. Make sure to call this function for all @code{mpc_t} variables when you are done with them. @end deftypefun @need 2000 Here is an example on how to initialize complex variables: @example @{ mpc_t x, y, z; mpc_init (x); /* use default precision */ mpc_init2 (y, 256); /* precision @emph{exactly} 256 bits */ mpc_init3 (z, 100, 50); /* 100/50 bits for the real/imaginary part */ @dots{} /* Unless the program is about to exit, do ... */ mpc_clear (x); mpc_clear (y); mpc_clear (z); @} @end example The following function is useful for changing the precision during a calculation. A typical use would be for adjusting the precision gradually in iterative algorithms like Newton-Raphson, making the computation precision closely match the actual accurate part of the numbers. @deftypefun void mpc_set_prec (mpc_t @var{x}, mp_prec_t @var{prec}) Reset the precision of @var{x} to be @strong{exactly} @var{prec} bits, and set its real/imaginary parts to NaN. The previous value stored in @var{x} is lost. It is equivalent to a call to @code{mpc_clear(x)} followed by a call to @code{mpc_init2(x, prec)}, but more efficient as no allocation is done in case the current allocated space for the mantissa of @var{x} is sufficient. @end deftypefun @deftypefun mp_prec_t mpc_get_prec (mpc_t @var{x}) If the real and imaginary part of @var{x} have the same precision, it is returned, otherwise, 0 is returned. @end deftypefun @deftypefun void mpc_get_prec2 (mp_prec_t* @var{pr}, mp_prec_t* @var{pi}, mpc_t @var{x}) Returns the precision of the real part of @var{x} via @var{pr} and of its imaginary part via @var{pi}. @end deftypefun @node Assigning Complex Numbers, Simultaneous Init & Assign, Initializing Complex Numbers, Complex Functions @comment node-name, next, previous, up @section Assignment Functions @cindex Complex assignment functions These functions assign new values to already initialized complex numbers (@pxref{Initializing Complex Numbers}). @deftypefn Function int mpc_set (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) @deftypefnx Macro int mpc_set_ui (mpc_t @var{rop}, unsigned long int @var{op}, mpc_rnd_t @var{rnd}) @deftypefnx Macro int mpc_set_si (mpc_t @var{rop}, long int @var{op}, mpc_rnd_t @var{rnd}) @deftypefnx Macro int mpc_set_d (mpc_t @var{rop}, double @var{op}, mpc_rnd_t @var{rnd}) Set the value of @var{rop} from @var{op}, rounded to the precision of @var{rop} with the given rounding mode @var{rnd}. Except for @code{mpc_set}, the argument @var{op} is interpreted as real, so the imaginary part of @var{rop} is set to zero. Please note that even a @code{long int} may have to be rounded, if the destination precision is less than the machine word width. For @code{mpc_set_d}, be careful that the input number @var{op} may not be exactly representable as a double-precision number (this happens for 0.1 for instance), in which case it is first rounded by the C compiler to a double-precision number, and then only to a complex number. @end deftypefn @deftypefun int mpc_set_d_d (mpc_t @var{rop}, double @var{op1}, double @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_set_ui_ui (mpc_t @var{rop}, unsigned long int @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_set_si_si (mpc_t @var{rop}, long int @var{op1}, long int @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_set_ui_fr (mpc_t @var{rop}, unsigned long int @var{op1}, mpfr_t @var{op2}, mpc_rnd_t @var{rnd}) Set the real part of @var{rop} from @var{op1}, and its imaginary part from @var{op2}, according to the rounding mode @var{rnd}. @end deftypefun @node Simultaneous Init & Assign, Complex Arithmetic, Assigning Complex Numbers, Complex Functions @comment node-name, next, previous, up @section Combined Initialization and Assignment Functions @cindex Initialization and assignment functions @deftypefn Macro int mpc_init_set (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) @deftypefnx Macro int mpc_init_set_ui (mpc_t @var{rop}, unsigned long int @var{op}, mpc_rnd_t @var{rnd}) Initialize @var{rop} and set its value from @var{op}, rounded with the rounding mode @var{rnd}. The precision of @var{rop} will be taken from the active default precision, as set by @code{mpc_set_default_prec}. @end deftypefn @deftypefn Macro int mpc_init_set_ui_ui (mpc_t @var{rop}, unsigned long int @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) @deftypefnx Macro int mpc_init_set_ui_fr (mpc_t @var{rop}, unsigned long int @var{op1}, mpfr_t @var{op2}, mpc_rnd_t @var{rnd}) @deftypefnx Macro int mpc_init_set_si_si (mpc_t @var{rop}, long int @var{op1}, long int @var{op2}, mpc_rnd_t @var{rnd}) Initialize @var{rop}, set its real part from @var{op1}, and its imaginary part from @var{op2}, rounded with the rounding mode @var{rnd}. The precision of @var{rop} will be taken from the active default precision, as set by @code{mpc_set_default_prec}. @end deftypefn @node Complex Arithmetic, Complex Comparison, Simultaneous Init & Assign, Complex Functions @comment node-name, next, previous, up @section Basic Arithmetic Functions @cindex Complex arithmetic functions @cindex Arithmetic functions All the following functions are designed in such a way that, when working with real numbers instead of complex numbers, their complexity should essentially be the same as with the MPFR library, with only a marginal overhead due to the MPC layer. @deftypefun int mpc_add (mpc_t @var{rop}, mpc_t @var{op1}, mpc_t @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_add_ui (mpc_t @var{rop}, mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_add_fr (mpc_t @var{rop}, mpc_t @var{op1}, mpfr_t @var{op2}, mpc_rnd_t @var{rnd}) Set @var{rop} to @var{op1} @math{+} @var{op2} rounded according to @var{rnd}. @end deftypefun @deftypefn Function int mpc_sub (mpc_t @var{rop}, mpc_t @var{op1}, mpc_t @var{op2}, mpc_rnd_t @var{rnd}) @deftypefnx Function int mpc_sub_ui (mpc_t @var{rop}, mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) @deftypefnx Macro int mpc_ui_sub (mpc_t @var{rop}, unsigned long int @var{op1}, mpc_t @var{op2}, mpc_rnd_t @var{rnd}) @deftypefnx Function int mpc_ui_ui_sub (mpc_t @var{rop}, unsigned long int @var{re1}, unsigned long int @var{im1}, mpc_t @var{op2}, mpc_rnd_t @var{rnd}) Set @var{rop} to @var{op1} @minus{} @var{op2} rounded according to @var{rnd}. For @code{mpc_ui_ui_sub}, @var{op1} is @var{re1} + @var{im1}. @end deftypefn @deftypefun int mpc_mul (mpc_t @var{rop}, mpc_t @var{op1}, mpc_t @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_mul_ui (mpc_t @var{rop}, mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_mul_si (mpc_t @var{rop}, mpc_t @var{op1}, long int @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_mul_fr (mpc_t @var{rop}, mpc_t @var{op1}, mpfr_t @var{op2}, mpc_rnd_t @var{rnd}) Set @var{rop} to @var{op1} times @var{op2} rounded according to @var{rnd}. @end deftypefun @deftypefun int mpc_mul_i (mpc_t @var{rop}, mpc_t @var{op}, int @var{sgn}, mpc_rnd_t @var{rnd}) Set @var{rop} to @var{op} times the imaginary unit i if @var{sgn} is non-negative, set @var{rop} to @var{op} times -i otherwise, in both cases rounded according to @var{rnd}. @end deftypefun @deftypefun int mpc_sqr (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) Set @var{rop} to the square of @var{op} rounded according to @var{rnd}. @end deftypefun @deftypefun int mpc_div (mpc_t @var{rop}, mpc_t @var{op1}, mpc_t @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_div_ui (mpc_t @var{rop}, mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_ui_div (mpc_t @var{rop}, unsigned long int @var{op1}, mpc_t @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_div_fr (mpc_t @var{rop}, mpc_t @var{op1}, mpfr_t @var{op2}, mpc_rnd_t @var{rnd}) Set @var{rop} to @var{op1}/@var{op2} rounded according to @var{rnd}. For @code{mpc_div} and @code{mpc_ui_div}, the return value may fail to recognize some exact results, and its sign is not significant. @end deftypefun @deftypefun int mpc_sqrt (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) Set @var{rop} to the square root of @var{op} rounded according to @var{rnd}. Here, when the return value is 0, it means the result is exact, but the contrary may be false. @end deftypefun @deftypefun int mpc_neg (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) Set @var{rop} to @minus{}@var{op} rounded according to @var{rnd}. Just changes the sign if @var{rop} and @var{op} are the same variable. @end deftypefun @deftypefun int mpc_conj (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) Set @var{rop} to the conjugate of @var{op} rounded according to @var{rnd}. Just changes the sign of the imaginary part if @var{rop} and @var{op} are the same variable. @end deftypefun @deftypefun int mpc_abs (mpfr_t @var{rop}, mpc_t @var{op}, mp_rnd_t @var{rnd}) Set the floating-point number @var{rop} to the absolute value of @var{op}, rounded in the direction @var{rnd}. The returned value is zero iff the result is exact. Note the destination is of type @code{mpfr_t}, not @code{mpc_t}. @end deftypefun @deftypefun int mpc_norm (mpfr_t @var{rop}, mpc_t @var{op}, mp_rnd_t @var{rnd}) Set the floating-point number @var{rop} to the norm of @var{op} (i.e. the square of its absolute value), rounded in the direction @var{rnd}. The returned value is zero iff the result is exact. Note that the destination is of type @code{mpfr_t}, not @code{mpc_t}. @end deftypefun @deftypefun int mpc_mul_2exp (mpc_t @var{rop}, mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) Set @var{rop} to @var{op1} times 2 raised to @var{op2} rounded according to @var{rnd}. Just increases the exponents of the real and imaginary parts by @var{op2} when @var{rop} and @var{op1} are identical. @end deftypefun @deftypefun int mpc_div_2exp (mpc_t @var{rop}, mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) Set @var{rop} to @var{op1} divided by 2 raised to @var{op2} rounded according to @var{rnd}. Just decreases the exponents of the real and imaginary parts by @var{op2} when @var{rop} and @var{op1} are identical. @end deftypefun @node Complex Comparison, Special Complex Functions, Complex Arithmetic, Complex Functions @comment node-name, next, previous, up @section Comparison Functions @cindex Complex comparisons functions @cindex Comparison functions @deftypefn Function int mpc_cmp (mpc_t @var{op1}, mpc_t @var{op2}) @deftypefnx Function int mpc_cmp_si_si (mpc_t @var{op1}, long int @var{op2r}, long int @var{op2i}) @deftypefnx Macro int mpc_cmp_si (mpc_t @var{op1}, long int @var{op2}) Compare @var{op1} and @var{op2}, where in the case of @code{mpc_cmp_si_si}, @var{op2} is taken to be @var{op2r} + i @var{op2i}. The return value @var{c} can be decomposed into @code{x = MPC_INEX_RE(c)} and @code{y = MPC_INEX_IM(c)}, such that @var{x} is positive if the real part of @var{op1} is greater than that of @var{op2}, zero if both real parts are equal, and negative if the real part of @var{op1} is less than that of @var{op2}, and likewise for @var{y}. Both @var{op1} and @var{op2} are considered to their full own precision, which may differ. It is not allowed that one of the operands has a NaN (Not-a-Number) part. The storage of the return value is such that equality can be simply checked with @code{mpc_cmp (op1, op2) == 0}. @end deftypefn @node Special Complex Functions, I/O of Complex Numbers, Complex Comparison, Complex Functions @comment node-name, next, previous, up @section Special Functions @cindex Special functions @cindex Special complex functions @deftypefun void mpc_exp (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) Set @var{rop} to the exponential of @var{op}, rounded according to @var{rnd} with the precision of @var{rop}. @end deftypefun @deftypefun void mpc_sin (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) Set @var{rop} to the sine of @var{op}, rounded according to @var{rnd} with the precision of @var{rop}. @end deftypefun @node I/O of Complex Numbers, Miscellaneous Complex Functions, Special Complex Functions, Complex Functions @comment node-name, next, previous, up @section Input and Output Functions @cindex Complex input and output functions @cindex Input functions @cindex Output functions @cindex I/O functions Functions that perform input from a standard input/output stream, and functions that output to a standard input/output stream. Passing a null pointer for a @var{stream} argument to any of these functions will make them read from @code{stdin} and write to @code{stdout}, respectively. When using any of these functions, it is a good idea to include @file{stdio.h} before @file{mpc.h}, since that will allow @file{mpc.h} to define prototypes for these functions. @deftypefun size_t mpc_out_str (FILE *@var{stream}, int @var{base}, size_t @var{n_digits}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) Output @var{op} on stdio stream @var{stream}, in base @var{base}, rounded according to @var{rnd}. First the real part is printed, then @code{+I*} followed by the imaginary part. The base may vary from 2 to 36. Print at most @var{n_digits} significant digits for each part, or if @var{n_digits} is 0, the maximum number of digits accurately representable by @var{op}. In addition to the significant digits, a decimal point at the right of the first digit and a trailing exponent, in the form @samp{eNNN}, are printed. If @var{base} is greater than 10, @samp{@@} will be used instead of @samp{e} as exponent delimiter. Return the number of characters written. @end deftypefun @deftypefun size_t mpc_inp_str (mpc_t @var{rop}, FILE *@var{stream}, int @var{base}, mpc_rnd_t @var{rnd}) Input a string in base @var{base} from stdio stream @var{stream}, rounded according to @var{rnd}, and put the read complex in @var{rop}. Each of the real and imaginary part should be of the form @samp{M@@N} or, if the base is 10 or less, alternatively @samp{MeN} or @samp{MEN}. @samp{M} is the mantissa and @samp{N} is the exponent. The mantissa is always in the specified base. The exponent is always read in decimal. This function first reads the real part, then @code{+} followed by @code{I*} and the imaginary part. The argument @var{base} may be in the range 2 to 36. Return the number of bytes read, or if an error occurred, return 0. @end deftypefun @node Miscellaneous Complex Functions, Internals, I/O of Complex Numbers, Complex Functions @comment node-name, next, previous, up @section Miscellaneous Functions @cindex Miscellaneous complex functions @deftypefun void mpc_random (mpc_t @var{rop}) Generate a random complex, with real and imaginary parts uniformly distributed in the interval -1 < X < 1. @end deftypefun @deftypefun void mpc_random2 (mpc_t @var{rop}, mp_size_t @var{max_size}, mp_exp_t @var{max_exp}) Generate a random complex, with real and imaginary part of at most @var{max_size} limbs, with long strings of zeros and ones in the binary representation. The exponent of the real (resp. imaginary) part is in the interval @minus{}@var{exp} to @var{exp}. This function is useful for testing functions and algorithms, since this kind of random numbers have proven to be more likely to trigger corner-case bugs. Negative parts are generated when @var{max_size} is negative. @end deftypefun @node Internals, , Miscellaneous Complex Functions, Complex Functions @comment node-name, next, previous, up @section Internals These types and functions were mainly designed for the implementation of MPC, but may be useful for users too. However no upward compatibility is guaranteed. You need to include @code{mpc-impl.h} to use them. The @code{mpc_t} type consists of two fields of type @code{mpfr_t}, one for the real part, one for the imaginary part. These fields can be accessed through @code{MPC_RE(z)} and @code{MPC_IM(z)}. Normally the real and imaginary part have the same precision, but the function @code{mpc_init3} enables one to have different precisions, and the user may also use @code{mpfr_set_prec} to change their precision. The macro @code{MPC_MAX_PREC(z)} gives the maximum of the precisions of the real and imaginary parts. @node Contributors, References, Complex Functions, Top @comment node-name, next, previous, up @unnumbered Contributors The main developers of the MPC library are Andreas Enge and Paul Zimmermann. Patrick Pelissier has cleaned up the code. Marc Helbling contributed the @code{mpc_ui_sub} and @code{mpc_ui_ui_sub} functions. @node References, Concept Index, Contributors, Top @comment node-name, next, previous, up @unnumbered References @itemize @bullet @item Torbj@"orn Granlund et al. @code{gmp} -- GNU multiprecision library. Version 4.2.1, @url{http://gmplib.org/}. @item Guillaume Hanrot, Vincent Lef@`evre, Patrick P@'elissier, Paul Zimmermann et al. @code{mpfr} -- A library for multiple-precision floating-point computations with exact rounding. Version 2.2.1, @url{http://www.mpfr.org}. @item IEEE standard for binary floating-point arithmetic, Technical Report ANSI-IEEE Standard 754-1985, New York, 1985. Approved March 21, 1985: IEEE Standards Board; approved July 26, 1985: American National Standards Institute, 18 pages. @item Donald E. Knuth, "The Art of Computer Programming", vol 2, "Seminumerical Algorithms", 2nd edition, Addison-Wesley, 1981. @end itemize @node Concept Index, Function Index, References, Top @comment node-name, next, previous, up @unnumbered Concept Index @printindex cp @node Function Index, , Concept Index, Top @comment node-name, next, previous, up @unnumbered Function and Type Index @printindex fn @ifnothtml @contents @end ifnothtml @bye