\input texinfo @setfilename mpc.info @include version.texi @settitle GNU MPC @value{VERSION} @synindex tp fn @set MINGMP 4.3.2 @set MINMPFR 3.0.0 @set AUTHORS Andreas Enge, Philippe Th@'eveny, Paul Zimmermann @copying This manual is for GNU MPC, a library for multiple precision complex arithmetic, version @value{VERSION} of @value{UPDATED-MONTH}. Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 INRIA @quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections. A copy of the license is included in the section entitled ``GNU Free Documentation License.'' @end quotation @end copying @iftex @afourpaper @end iftex @tex \global\parindent=0pt \global\parskip=8pt \global\baselineskip=13pt @end tex @dircategory GNU Packages @direntry * mpc: (mpc)Multiple Precision Complex Library. @end direntry @titlepage @title GNU MPC @subtitle The GNU Multiple Precision Complex Library @subtitle Edition @value{VERSION} @subtitle @value{UPDATED-MONTH} @author @value{AUTHORS} @page @vskip 0pt plus 1filll @insertcopying @end titlepage @ifnottex @node Top @top GNU MPC This manual documents how to install and use the GNU Multiple Precision Complex Library, version @value{VERSION} @end ifnottex @menu * Copying:: GNU MPC Copying Conditions (LGPL). * Introduction to GNU MPC:: Brief introduction to GNU MPC. * Installing GNU MPC:: How to configure and compile the GNU MPC library. * Reporting Bugs:: How to usefully report bugs. * GNU MPC Basics:: What every GNU MPC user should know. * Complex Functions:: Functions for arithmetic on complex numbers. * References:: * Concept Index:: * Function Index:: * GNU Free Documentation License:: @end menu @c @times{} made available as a "x" in info and html (already works in tex). @ifnottex @macro times x @end macro @end ifnottex @node Copying @unnumbered GNU MPC Copying Conditions @cindex Copying conditions @cindex Conditions for copying GNU MPC GNU MPC is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. GNU MPC is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this program. If not, see @uref{http://www.gnu.org/licenses/}. @node Introduction to GNU MPC @chapter Introduction to GNU MPC GNU MPC is a portable library written in C for arbitrary precision arithmetic on complex numbers providing correct rounding. It implements a multiprecision equivalent of the C99 standard. It builds upon the GNU MP and the GNU MPFR libraries. @section How to use this Manual Everyone should read @ref{GNU MPC Basics}. If you need to install the library yourself, you need to read @ref{Installing GNU MPC}, too. The remainder of the manual can be used for later reference, although it is probably a good idea to skim through it. @node Installing GNU MPC @chapter Installing GNU MPC @cindex Installation To build GNU MPC, you first have to install GNU MP (version @value{MINGMP} or higher) and GNU MPFR (version @value{MINMPFR} or higher) on your computer. You need a C compiler; GCC version 4.4 or higher is recommended, since GNU MPC may trigger a bug in previous versions, see the thread at @uref{http://lists.gforge.inria.fr/pipermail/mpc-discuss/2011-February/000823.html}. 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 GNU 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. Alternatively, you can specify directly GMP include and GMP lib directories with @samp{./configure --with-gmp-lib= --with-gmp-include=}. @samp{./configure --with-mpfr=} is used to indicate a different location where GNU MPFR is installed. Alternatively, you can specify directly GNU MPFR include and GNU MPFR lib directories with @samp{./configure --with-mpf-lib= --with-mpfr-include=}. Another useful parameter is @samp{--prefix}, which can be used to specify an alternative installation location instead of @file{/usr/local}; see @samp{make install} below. To enable checking for memory leaks using @command{valgrind} during @code{make check}, add the parameter @code{--enable-valgrind-tests}. If for debugging purposes you wish to log calls to GNU MPC functions from within your code, add the parameter @samp{--enable-logging}. In your code, replace the inclusion of @file{mpc.h} by @file{mpc-log.h} and link the executable dynamically. Then all calls to functions with only complex arguments are printed to @file{stderr} in the following form: First, the function name is given, followed by its type such as @samp{c_cc}, meaning that the function has one complex result (one @samp{c} in front of the @samp{_}), computed from two complex arguments (two @samp{c} after the @samp{_}). Then, the precisions of the real and the imaginary part of the first result is given, followed by the second one and so on. Finally, for each argument, the precisions of its real and imaginary part are specified and the argument itself is printed in hexadecimal via the function @code{mpc_out_str} (@pxref{String and Stream Input and Output}). The option requires a dynamic library, so it may not be combined with @code{--disable-shared}. Use @samp{./configure --help} for an exhaustive list of parameters. @item @samp{make} This compiles GNU MPC in the working directory. @item @samp{make check} This will make sure GNU 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{info} Create an info version of the manual, in @file{mpc.info}. @item @samp{pdf} Create a PDF version of the manual, in @file{doc/mpc.pdf}. @item @samp{dvi} Create a DVI version of the manual, in @file{doc/mpc.dvi}. @item @samp{ps} Create a Postscript version of the manual, in @file{doc/mpc.ps}. @item @samp{html} Create an HTML version of the manual, in several pages in the directory @file{doc/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 On AIX, if GMP was built with the 64-bit ABI, before building and testing GNU MPC, it might be necessary to set the @samp{OBJECT_MODE} environment variable to 64 by, e.g., @samp{export OBJECT_MODE=64} This has been tested with the C compiler IBM XL C/C++ Enterprise Edition V8.0 for AIX, version: 08.00.0000.0021, GMP 4.2.4 and GNU MPFR 2.4.1. Please report any other problems you encounter to @samp{mpc-discuss@@lists.gforge.inria.fr}. @xref{Reporting Bugs}. @node Reporting Bugs @chapter Reporting Bugs @cindex Reporting bugs If you think you have found a bug in the GNU 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{gcc -v}, or @samp{cc -V} on some machines. 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{mpc-discuss@@lists.gforge.inria.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 GNU MPC Basics @chapter GNU MPC Basics @cindex @file{mpc.h} All declarations needed to use GNU 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 GNU 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{mpfr_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{mpfr_prec_t}. For more details on the allowed precision range, @ifinfo @pxref{Nomenclature and Types,,, mpfr.info,GNU MPFR}. @end ifinfo @ifnotinfo see Section ``Nomenclature and Types'' in @cite{GNU MPFR}. @end ifnotinfo @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 GNU MPC library, namely functions for complex arithmetic. The function names begin with @code{mpc_}. The associated type is @code{mpc_t}. @section GNU MPC Variable Conventions As a general rule, all GNU MPC functions expect output arguments before input arguments. This notation is based on an analogy with the assignment operator. GNU 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 GNU MPC variable, you need to initialise 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 initialised once, or at least cleared out between each initialization. After a variable has been initialised, it may be assigned to any number of times. For efficiency reasons, avoid to initialise and clear out a variable in loops. Instead, initialise 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 GNU 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 reinitialise it, a complex variable will have the same allocated space during all its life. @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. @anchor{return-value} @section Return Value Most GNU MPC functions have a return value of type @code{int}, which is used to indicate the position of the rounded real and 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. Similarly, functions computing a result of type @code{mpfr_t} return an integer that is 0, positive or negative depending on whether the rounded value is the same, larger or smaller then the exact result. Some functions, such as @code{mpc_sin_cos}, compute two complex results; the macros @code{MPC_INEX1(i)} and @code{MPC_INEX2(i)}, applied to the return value @code{i} of such a function, yield the exactness value corresponding to the first or the second computed value, respectively. @section Branch Cuts And Special Values Some complex functions have branch cuts, across which the function is discontinous. In GNU MPC, the branch cuts chosen are the same as those specified for the corresponding functions in the ISO C99 standard. Likewise, when evaluated at a point whose real or imaginary part is either infinite or a NaN or a signed zero, a function returns the same value as those specified for the corresponding function in the ISO C99 standard. @node Complex Functions @chapter Complex Functions @cindex Complex functions The complex functions expect arguments of type @code{mpc_t}. The GNU 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 GNU 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 * Initializing Complex Numbers:: * Assigning Complex Numbers:: * Converting Complex Numbers:: * String and Stream Input and Output:: * Complex Comparison:: * Projection & Decomposing:: * Basic Arithmetic:: * Power Functions and Logarithm:: * Trigonometric Functions:: * Miscellaneous Complex Functions:: * Advanced Functions:: * Internals:: @end menu @node Initializing Complex Numbers @section Initialization Functions An @code{mpc_t} object must be initialised before storing the first value in it. The functions @code{mpc_init2} and @code{mpc_init3} are used for that purpose. @deftypefun void mpc_init2 (mpc_t @var{z}, mpfr_prec_t @var{prec}) Initialise @var{z} to precision @var{prec} bits and set its real and imaginary parts to NaN. Normally, a variable should be initialised once only or at least be cleared, using @code{mpc_clear}, between initializations. @end deftypefun @deftypefun void mpc_init3 (mpc_t @var{z}, mpfr_prec_t @var{prec_r}, mpfr_prec_t @var{prec_i}) Initialise @var{z} with the precision of its real part being @var{prec_r} bits and the precision of its imaginary part being @var{prec_i} bits, and set the 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 initialise complex variables: @example @{ mpc_t x, y; mpc_init2 (x, 256); /* precision @emph{exactly} 256 bits */ mpc_init3 (y, 100, 50); /* 100/50 bits for the real/imaginary part */ @dots{} mpc_clear (x); mpc_clear (y); @} @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}, mpfr_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 mpfr_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 (mpfr_prec_t* @var{pr}, mpfr_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 @section Assignment Functions @cindex Complex assignment functions These functions assign new values to already initialised complex numbers (@pxref{Initializing Complex Numbers}). When using any functions with @code{intmax_t} or @code{uintmax_t} parameters, you must include @code{} or @code{} @emph{before} @file{mpc.h}, to allow @file{mpc.h} to define prototypes for these functions. Similarly, functions with parameters of type @code{complex} or @code{long complex} are defined only if @code{} is included @emph{before} @file{mpc.h}. If you need assignment functions that are not in the current API, you can define them using the @code{MPC_SET_X_Y} macro (@pxref{Advanced Functions}). @deftypefun int mpc_set (mpc_t @var{rop}, mpc_t @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}. @end deftypefun @deftypefun int mpc_set_ui (mpc_t @var{rop}, unsigned long int @var{op}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_set_si (mpc_t @var{rop}, long int @var{op}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_set_uj (mpc_t @var{rop}, uintmax_t @var{op}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_set_sj (mpc_t @var{rop}, intmax_t @var{op}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_set_d (mpc_t @var{rop}, double @var{op}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_set_ld (mpc_t @var{rop}, long double @var{op}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_set_dc (mpc_t @var{rop}, double _Complex @var{op}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_set_ldc (mpc_t @var{rop}, long double _Complex @var{op}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_set_z (mpc_t @var{rop}, mpz_t @var{op} mpc_rnd_t @var{rnd}) @deftypefunx int mpc_set_q (mpc_t @var{rop}, mpq_t @var{op} mpc_rnd_t @var{rnd}) @deftypefunx int mpc_set_f (mpc_t @var{rop}, mpf_t @var{op} mpc_rnd_t @var{rnd}) @deftypefunx int mpc_set_fr (mpc_t @var{rop}, mpfr_t @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}. The argument @var{op} is interpreted as real, so the imaginary part of @var{rop} is set to zero with a positive sign. 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 deftypefun @deftypefun 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_uj_uj (mpc_t @var{rop}, uintmax_t @var{op1}, uintmax_t @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_set_sj_sj (mpc_t @var{rop}, intmax_t @var{op1}, intmax_t @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_set_d_d (mpc_t @var{rop}, double @var{op1}, double @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_set_ld_ld (mpc_t @var{rop}, long double @var{op1}, long double @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_set_z_z (mpc_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_set_q_q (mpc_t @var{rop}, mpq_t @var{op1}, mpq_t @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_set_f_f (mpc_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_set_fr_fr (mpc_t @var{rop}, mpfr_t @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}. Beware that the behaviour of @code{mpc_set_fr_fr} is undefined if @var{op1} or @var{op2} is a pointer to the real or imaginary part of @var{rop}. To exchange the real and the imaginary part of a complex number, either use @code{mpfr_swap (mpc_realref (rop), mpc_imagref (rop))}, which also exchanges the precisions of the two parts; or use a temporary variable. @end deftypefun For functions assigning complex variables from strings or input streams, @pxref{String and Stream Input and Output}. @deftypefun void mpc_set_nan (mpc_t @var{rop}) Set @var{rop} to Nan+i*NaN. @end deftypefun @deftypefun void mpc_swap (mpc_t @var{op1}, mpc_t @var{op2}) Swap the values of @var{op1} and @var{op2} efficiently. Warning: The precisions are exchanged, too; in case these are different, @code{mpc_swap} is thus not equivalent to three @code{mpc_set} calls using a third auxiliary variable. @end deftypefun @node Converting Complex Numbers @section Conversion Functions @cindex Conversion functions The following functions are available only if @code{} is included @emph{before} @file{mpc.h}. @deftypefun double _Complex mpc_get_dc (mpc_t @var{op}, mpc_rnd_t @var{rnd}) @deftypefunx {long double _Complex} mpc_get_ldc (mpc_t @var{op}, mpc_rnd_t @var{rnd}) Convert @var{op} to a C complex number, using the rounding mode @var{rnd}. @end deftypefun For functions converting complex variables to strings or stream output, @pxref{String and Stream Input and Output}. @node String and Stream Input and Output @section String and Stream Input and Output @cindex String and stream input and output @deftypefun int mpc_strtoc (mpc_t @var{rop}, const char *@var{nptr}, char **@var{endptr}, int @var{base}, mpc_rnd_t @var{rnd}) Read a complex number from a string @var{nptr} in base @var{base}, rounded to the precision of @var{rop} with the given rounding mode @var{rnd}. The @var{base} must be either 0 or a number from 2 to 36 (otherwise the behaviour is undefined). If @var{nptr} starts with valid data, the result is stored in @var{rop}, the usual inexact value is returned (@pxref{return-value,, Return Value}) and, if @var{endptr} is not the null pointer, @var{*endptr} points to the character just after the valid data. Otherwise, @var{rop} is set to @code{NaN + i * NaN}, -1 is returned and, if @var{endptr} is not the null pointer, the value of @var{nptr} is stored in the location referenced by @var{endptr}. The expected form of a complex number string is either a real number (an optional leading whitespace, an optional sign followed by a floating-point number), or a pair of real numbers in parentheses separated by whitespace. If a real number is read, the missing imaginary part is set to +0. The form of a floating-point number depends on the base and is described in the documentation of @code{mpfr_strtofr} @ifinfo (@pxref{Assignment Functions,,, mpfr.info,GNU MPFR}). @end ifinfo @ifnotinfo in the GNU MPFR manual. @end ifnotinfo For instance, @code{"3.1415926"}, @code{"(1.25e+7 +.17)"}, @code{"(@@nan@@ 2)"} and @code{"(-0 -7)"} are valid strings for @var{base} = 10. If @var{base} = 0, then a prefix may be used to indicate the base in which the floating-point number is written. Use prefix '0b' for binary numbers, prefix '0x' for hexadecimal numbers, and no prefix for decimal numbers. The real and imaginary part may then be written in different bases. For instance, @code{"(1.024e+3 +2.05e+3)"} and @code{"(0b1p+10 +0x802)"} are valid strings for @code{base}=0 and represent the same value. @end deftypefun @deftypefun int mpc_set_str (mpc_t @var{rop}, const char *@var{s}, int @var{base}, mpc_rnd_t rnd) Set @var{rop} to the value of the string @var{s} in base @var{base}, rounded to the precision of @var{rop} with the given rounding mode @var{rnd}. See the documentation of @code{mpc_strtoc} for a detailed description of the valid string formats. Contrarily to @code{mpc_strtoc}, @code{mpc_set_str} requires the @emph{whole} string to represent a valid complex number (potentially followed by additional white space). This function returns the usual inexact value (@pxref{return-value,, Return Value}) if the entire string up to the final null character is a valid number in base @var{base}; otherwise it returns @minus{}1, and @var{rop} is set to NaN+i*NaN. @end deftypefun @deftypefun {char *} mpc_get_str (int @var{b}, size_t @var{n}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) Convert @var{op} to a string containing its real and imaginary parts, separated by a space and enclosed in a pair of parentheses. The numbers are written in base @var{b} (which may vary from 2 to 36) and rounded according to @var{rnd}. The number of significant digits, at least 2, is given by @var{n}. It is also possible to let @var{n} be zero, in which case the number of digits is chosen large enough so that re-reading the printed value with the same precision, assuming both output and input use rounding to nearest, will recover the original value of @var{op}. Note that @code{mpc_get_str} uses the decimal point of the current locale if available, and @samp{.} otherwise. The string is generated using the current memory allocation function (@code{malloc} by default, unless it has been modified using the custom memory allocation interface of @code{gmp}); once it is not needed any more, it should be freed by calling @code{mpc_free_str}. @end deftypefun @deftypefun {void} mpc_free_str (char *@var{str}) Free the string @var{str}, which needs to have been allocated by a call to @code{mpc_get_str}. @end deftypefun The following two functions read numbers from input streams and write them to output streams. When using any of these functions, you need to include @file{stdio.h} @emph{before} @file{mpc.h}. @deftypefun int mpc_inp_str (mpc_t @var{rop}, FILE *@var{stream}, size_t *@var{read}, int @var{base}, mpc_rnd_t @var{rnd}) Input a string in base @var{base} in the same format as for @code{mpc_strtoc} from stdio stream @var{stream}, rounded according to @var{rnd}, and put the read complex number into @var{rop}. If @var{stream} is the null pointer, @var{rop} is read from @code{stdin}. Return the usual inexact value; if an error occurs, set @var{rop} to @code{NaN + i * NaN} and return -1. If @var{read} is not the null pointer, it is set to the number of read characters. Unlike @code{mpc_strtoc}, the function @code{mpc_inp_str} does not possess perfect knowledge of the string to transform and has to read it character by character, so it behaves slightly differently: It tries to read a string describing a complex number and processes this string through a call to @code{mpc_set_str}. Precisely, after skipping optional whitespace, a minimal string is read according to the regular expression @code{mpfr | '(' \s* mpfr \s+ mpfr \s* ')'}, where @code{\s} denotes a whitespace, and @code{mpfr} is either a string containing neither whitespaces nor parentheses, or @code{nan(n-char-sequence)} or @code{@@nan@@(n-char-sequence)} (regardless of capitalisation) with @code{n-char-sequence} a string of ascii letters, digits or @code{'_'}. For instance, upon input of @code{"nan(13 1)"}, the function @code{mpc_inp_str} starts to recognise a value of NaN followed by an n-char-sequence indicated by the opening parenthesis; as soon as the space is reached, it becomes clear that the expression in parentheses is not an n-char-sequence, and the error flag -1 is returned after 6 characters have been consumed from the stream (the whitespace itself remaining in the stream). The function @code{mpc_strtoc}, on the other hand, may track back when reaching the whitespace; it treats the string as the two successive complex numbers @code{NaN + i * 0} and @code{13 + i}. It is thus recommended to have a whitespace follow each floating point number to avoid this problem. @end deftypefun @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}, in the same format as for @code{mpc_strtoc} If @var{stream} is the null pointer, @var{rop} is written to @code{stdout}. Return the number of characters written. @end deftypefun @node Complex Comparison @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 Projection & Decomposing @section Projection and Decomposing Functions @cindex Projection and Decomposing Functions @deftypefn Function int mpc_real (mpfr_t @var{rop}, mpc_t @var{op}, mpfr_rnd_t @var{rnd}) Set @var{rop} to the value of the real part of @var{op} rounded in the direction @var{rnd}. @end deftypefn @deftypefn Function int mpc_imag (mpfr_t @var{rop}, mpc_t @var{op}, mpfr_rnd_t @var{rnd}) Set @var{rop} to the value of the imaginary part of @var{op} rounded in the direction @var{rnd}. @end deftypefn @deftypefn Macro mpfr_t mpc_realref (mpc_t @var{op}) @deftypefnx Macro mpfr_t mpc_imagref (mpc_t @var{op}) Return a reference to the real part and imaginary part of @var{op}, respectively. The @code{mpfr} functions can be used on the result of these macros (note that the @code{mpfr_t} type is itself a pointer). @end deftypefn @deftypefn Function int mpc_arg (mpfr_t @var{rop}, mpc_t @var{op}, mpfr_rnd_t @var{rnd}) Set @var{rop} to the argument of @var{op}, with a branch cut along the negative real axis. @end deftypefn @deftypefn Function int mpc_proj (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) Compute a projection of @var{op} onto the Riemann sphere. Set @var{rop} to @var{op} rounded in the direction @var{rnd}, except when at least one part of @var{op} is infinite (even if the other part is a NaN) in which case the real part of @var{rop} is set to plus infinity and its imaginary part to a signed zero with the same sign as the imaginary part of @var{op}. @end deftypefn @node Basic Arithmetic @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 GNU MPFR library, with only a marginal overhead due to the GNU 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_fr (mpc_t @var{rop}, mpc_t @var{op1}, mpfr_t @var{op2}, mpc_rnd_t @var{rnd}) @deftypefnx Function int mpc_fr_sub (mpc_t @var{rop}, mpfr_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_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_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}. Note: for @code{mpc_mul}, in case @var{op1} and @var{op2} have the same value, use @code{mpc_sqr} for better efficiency. @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_fma (mpc_t @var{rop}, mpc_t @var{op1}, mpc_t @var{op2}, mpc_t @var{op3}, mpc_rnd_t @var{rnd}) Set @var{rop} to @var{op1}*@var{op2}+@var{op3}, rounded according to @var{rnd}, with only one final rounding. @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_div_fr (mpc_t @var{rop}, mpc_t @var{op1}, mpfr_t @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_fr_div (mpc_t @var{rop}, mpfr_t @var{op1}, mpc_t @var{op2}, mpc_rnd_t @var{rnd}) Set @var{rop} to @var{op1}/@var{op2} rounded according to @var{rnd}. @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}, mpfr_rnd_t @var{rnd}) Set the floating-point number @var{rop} to the absolute value of @var{op}, rounded in the direction @var{rnd}. @end deftypefun @deftypefun int mpc_norm (mpfr_t @var{rop}, mpc_t @var{op}, mpfr_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}. @end deftypefun @deftypefun int mpc_mul_2ui (mpc_t @var{rop}, mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_mul_2si (mpc_t @var{rop}, mpc_t @var{op1}, 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 modifies 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_2ui (mpc_t @var{rop}, mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_div_2si (mpc_t @var{rop}, mpc_t @var{op1}, 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 modifies the exponents of the real and imaginary parts by @var{op2} when @var{rop} and @var{op1} are identical. @end deftypefun @node Power Functions and Logarithm @section Power Functions and Logarithm @cindex Power functions @cindex Logarithm @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}. The returned value @var{rop} has a non-negative real part, and if its real part is zero, a non-negative imaginary part. @end deftypefun @deftypefun int mpc_pow (mpc_t @var{rop}, mpc_t @var{op1}, mpc_t @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_pow_d (mpc_t @var{rop}, mpc_t @var{op1}, double @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_pow_ld (mpc_t @var{rop}, mpc_t @var{op1}, long double @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_pow_si (mpc_t @var{rop}, mpc_t @var{op1}, long @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_pow_ui (mpc_t @var{rop}, mpc_t @var{op1}, unsigned long @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_pow_z (mpc_t @var{rop}, mpc_t @var{op1}, mpz_t @var{op2}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_pow_fr (mpc_t @var{rop}, mpc_t @var{op1}, mpfr_t @var{op2}, mpc_rnd_t @var{rnd}) Set @var{rop} to @var{op1} raised to the power @var{op2}, rounded according to @var{rnd}. For @code{mpc_pow_d}, @code{mpc_pow_ld}, @code{mpc_pow_si}, @code{mpc_pow_ui}, @code{mpc_pow_z} and @code{mpc_pow_fr}, the imaginary part of @var{op2} is considered as +0. When both @var{op1} and @var{op2} are zero, the result has real part 1, and imaginary part 0, with sign being the opposite of that of @var{op2}. @end deftypefun @deftypefun int 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 int mpc_log (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_log10 (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) Set @var{rop} to the natural and base-10 logarithm of @var{op} respectively, rounded according to @var{rnd} with the precision of @var{rop}. The principal branch is chosen, with the branch cut on the negative real axis, so that the imaginary part of the result lies in @math{]-\pi , \pi]} and @math{]-\pi/log(10) , \pi/log(10)]} respectively. @end deftypefun @node Trigonometric Functions @section Trigonometric Functions @cindex Trigonometric functions @deftypefun int 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 @deftypefun int mpc_cos (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) Set @var{rop} to the cosine of @var{op}, rounded according to @var{rnd} with the precision of @var{rop}. @end deftypefun @deftypefun int mpc_sin_cos (mpc_t @var{rop_sin}, mpc_t @var{rop_cos}, mpc_t @var{op}, mpc_rnd_t @var{rnd_sin}, mpc_rnd_t @var{rnd_cos}) Set @var{rop_sin} to the sine of @var{op}, rounded according to @var{rnd_sin} with the precision of @var{rop_sin}, and @var{rop_cos} to the cosine of @var{op}, rounded according to @var{rnd_cos} with the precision of @var{rop_cos}. @end deftypefun @deftypefun int mpc_tan (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) Set @var{rop} to the tangent of @var{op}, rounded according to @var{rnd} with the precision of @var{rop}. @end deftypefun @deftypefun int mpc_sinh (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) Set @var{rop} to the hyperbolic sine of @var{op}, rounded according to @var{rnd} with the precision of @var{rop}. @end deftypefun @deftypefun int mpc_cosh (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) Set @var{rop} to the hyperbolic cosine of @var{op}, rounded according to @var{rnd} with the precision of @var{rop}. @end deftypefun @deftypefun int mpc_tanh (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) Set @var{rop} to the hyperbolic tangent of @var{op}, rounded according to @var{rnd} with the precision of @var{rop}. @end deftypefun @deftypefun int mpc_asin (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_acos (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_atan (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) Set @var{rop} to the inverse sine, inverse cosine, inverse tangent of @var{op}, rounded according to @var{rnd} with the precision of @var{rop}. @end deftypefun @deftypefun int mpc_asinh (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_acosh (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) @deftypefunx int mpc_atanh (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) Set @var{rop} to the inverse hyperbolic sine, inverse hyperbolic cosine, inverse hyperbolic tangent of @var{op}, rounded according to @var{rnd} with the precision of @var{rop}. The branch cut of @var{mpc_acosh} is @math{(-\infty, 1)}. @end deftypefun @node Miscellaneous Complex Functions @section Miscellaneous Functions @cindex Miscellaneous complex functions @deftypefun int mpc_urandom (mpc_t @var{rop}, gmp_randstate_t @var{state}) Generate a uniformly distributed random complex in the unit square @math{[0, 1] @times [0, 1]}. Return 0, unless an exponent in the real or imaginary part is not in the current exponent range, in which case that part is set to NaN and a zero value is returned. The second argument is a @code{gmp_randstate_t} structure which should be created using the GMP @code{rand_init} function, see the GMP manual. @end deftypefun @deftypefun {const char *} mpc_get_version (void) Return the GNU MPC version, as a null-terminated string. @end deftypefun @defmac MPC_VERSION @defmacx MPC_VERSION_MAJOR @defmacx MPC_VERSION_MINOR @defmacx MPC_VERSION_PATCHLEVEL @defmacx MPC_VERSION_STRING @code{MPC_VERSION} is the version of GNU MPC as a preprocessing constant. @code{MPC_VERSION_MAJOR}, @code{MPC_VERSION_MINOR} and @code{MPC_VERSION_PATCHLEVEL} are respectively the major, minor and patch level of GNU MPC version, as preprocessing constants. @code{MPC_VERSION_STRING} is the version as a string constant, which can be compared to the result of @code{mpc_get_version} to check at run time the header file and library used match: @example if (strcmp (mpc_get_version (), MPC_VERSION_STRING)) fprintf (stderr, "Warning: header and library do not match\n"); @end example Note: Obtaining different strings is not necessarily an error, as in general, a program compiled with some old GNU MPC version can be dynamically linked with a newer GNU MPC library version (if allowed by the library versioning system). @end defmac @deftypefn Macro long MPC_VERSION_NUM (@var{major}, @var{minor}, @var{patchlevel}) Create an integer in the same format as used by @code{MPC_VERSION} from the given @var{major}, @var{minor} and @var{patchlevel}. Here is an example of how to check the GNU MPC version at compile time: @example #if (!defined(MPC_VERSION) || (MPC_VERSION