mpc.texi revision 1.1.1.1
1\input texinfo 2@setfilename mpc.info 3@include version.texi 4@settitle GNU MPC @value{VERSION} 5@synindex tp fn 6 7@set MINGMP 4.3.2 8@set MINMPFR 2.4.2 9 10@set AUTHORS Andreas Enge, Philippe Th@'eveny, Paul Zimmermann 11 12@copying 13This manual is for GNU MPC, a library for multiple precision complex arithmetic, 14version @value{VERSION} of @value{UPDATED-MONTH}. 15 16Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 INRIA 17 18@quotation 19Permission is granted to copy, distribute and/or modify this document 20under the terms of the GNU Free Documentation License, Version 1.3 or 21any later version published by the Free Software Foundation; with no 22Invariant Sections. A copy of the license is included in the section 23entitled ``GNU Free Documentation License.'' 24@end quotation 25@end copying 26 27@iftex 28@afourpaper 29@end iftex 30@tex 31\global\parindent=0pt 32\global\parskip=8pt 33\global\baselineskip=13pt 34@end tex 35 36@dircategory GNU Packages 37@direntry 38* mpc: (mpc)Multiple Precision Complex Library. 39@end direntry 40 41 42@titlepage 43@title GNU MPC 44@subtitle The GNU Multiple Precision Complex Library 45@subtitle Edition @value{VERSION} 46@subtitle @value{UPDATED-MONTH} 47@author @value{AUTHORS} 48@page 49@vskip 0pt plus 1filll 50@insertcopying 51@end titlepage 52 53 54@ifnottex 55@node Top 56@top GNU MPC 57 58This manual documents how to install and use the GNU Multiple Precision 59Complex Library, version @value{VERSION} 60@end ifnottex 61 62@menu 63* Copying:: GNU MPC Copying Conditions (LGPL). 64* Introduction to GNU MPC:: Brief introduction to GNU MPC. 65* Installing GNU MPC:: How to configure and compile the GNU MPC library. 66* Reporting Bugs:: How to usefully report bugs. 67* GNU MPC Basics:: What every GNU MPC user should know. 68* Complex Functions:: Functions for arithmetic on complex numbers. 69* References:: 70* Concept Index:: 71* Function Index:: 72* GNU Free Documentation License:: 73@end menu 74 75@c @times{} made available as a "x" in info and html (already works in tex). 76@ifnottex 77@macro times 78x 79@end macro 80@end ifnottex 81 82 83@node Copying 84@unnumbered GNU MPC Copying Conditions 85@cindex Copying conditions 86@cindex Conditions for copying GNU MPC 87 88GNU MPC is free software; you can redistribute it and/or modify it under 89the terms of the GNU Lesser General Public License as published by the 90Free Software Foundation; either version 3 of the License, or (at your 91option) any later version. 92 93GNU MPC is distributed in the hope that it will be useful, but WITHOUT ANY 94WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 95FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for 96more details. 97 98You should have received a copy of the GNU Lesser General Public License 99along with this program. If not, see @uref{http://www.gnu.org/licenses/}. 100 101 102@node Introduction to GNU MPC 103@chapter Introduction to GNU MPC 104 105 106GNU MPC is a portable library written in C for arbitrary precision arithmetic 107on complex numbers providing correct rounding. It implements a multiprecision 108equivalent of the C99 standard. 109It builds upon the GNU MP and the GNU MPFR libraries. 110 111@section How to use this Manual 112 113Everyone should read @ref{GNU MPC Basics}. If you need to install the library 114yourself, you need to read @ref{Installing GNU MPC}, too. 115 116The remainder of the manual can be used for later reference, although it is 117probably a good idea to skim through it. 118 119@node Installing GNU MPC 120@chapter Installing GNU MPC 121@cindex Installation 122 123To build GNU MPC, you first have to install GNU MP (version @value{MINGMP} or higher) and 124GNU MPFR (version @value{MINMPFR} or higher) on your computer. You need a C compiler; 125GCC version 4.4 or higher is recommended, since GNU MPC may trigger a bug in previous 126versions, see the thread at 127@uref{http://lists.gforge.inria.fr/pipermail/mpc-discuss/2011-February/000823.html}. 128And you need a 129standard Unix @samp{make} program, plus some other standard Unix utility 130programs. 131 132Here are the steps needed to install the library on Unix systems: 133 134@enumerate 135@item 136@samp{tar xzf mpc-@value{VERSION}.tar.gz} 137 138@item 139@samp{cd mpc-@value{VERSION}} 140 141@item 142@samp{./configure} 143 144if GMP and GNU MPFR are installed into standard directories, that is, directories 145that are searched by default by the compiler and the linking tools. 146 147@samp{./configure --with-gmp=<gmp_install_dir>} 148 149is used to indicate a different location where GMP is 150installed. Alternatively, you can specify directly GMP include and GMP lib 151directories with @samp{./configure --with-gmp-lib=<gmp_lib_dir> 152--with-gmp-include=<gmp_include_dir>}. 153 154@samp{./configure --with-mpfr=<mpfr_install_dir>} 155 156is used to indicate a different location where GNU MPFR is 157installed. Alternatively, you can specify directly GNU MPFR include and GNU MPFR lib 158directories with @samp{./configure --with-mpf-lib=<mpfr_lib_dir> 159--with-mpfr-include=<mpfr_include_dir>}. 160 161Another useful parameter is @samp{--prefix}, which can be used to 162specify an alternative installation location instead of 163@file{/usr/local}; see @samp{make install} below. 164 165To enable checking for memory leaks using @command{valgrind} during 166@code{make check}, add the parameter @code{--enable-valgrind-tests}. 167 168If for debugging purposes you wish to log calls to GNU MPC functions from 169within your code, add the parameter @samp{--enable-logging}. 170In your code, replace the inclusion of @file{mpc.h} by @file{mpc-log.h} 171and link the executable dynamically. 172Then all calls to functions with only complex arguments are printed to 173@file{stderr} in the following form: First, the function name is given, 174followed by its type such as @samp{c_cc}, meaning that the function has 175one complex result (one @samp{c} in front of the @samp{_}), computed from 176two complex arguments (two @samp{c} after the @samp{_}). Then, the 177precisions of the real and the imaginary part of the first result is given, 178followed by the second one and so on. Finally, for each argument, the 179precisions of its real and imaginary part are specified and the argument 180itself is printed in hexadecimal via the function 181@code{mpc_out_str} 182(@pxref{String and Stream Input and Output}). 183The option requires a dynamic library, so it may not be combined with 184@code{--disable-shared}. 185 186Use @samp{./configure --help} for an exhaustive list of parameters. 187 188@item 189@samp{make} 190 191This compiles GNU MPC in the working directory. 192 193@item 194@samp{make check} 195 196This will make sure GNU MPC was built correctly. 197 198If you get error messages, please report them to 199@samp{mpc-discuss@@lists.gforge.inria.fr} (@xref{Reporting Bugs}, for 200information on what to include in useful bug reports). 201 202@item 203@samp{make install} 204 205This will copy the file @file{mpc.h} to the directory 206@file{/usr/local/include}, the file @file{libmpc.a} to the directory 207@file{/usr/local/lib}, and the file @file{mpc.info} to the directory 208@file{/usr/local/share/info} (or if you passed the @samp{--prefix} option to 209@file{configure}, using the prefix directory given as argument to 210@samp{--prefix} instead of @file{/usr/local}). Note: you need write permissions 211on these directories. 212 213@end enumerate 214 215 216@section Other `make' Targets 217 218There are some other useful make targets: 219 220@itemize @bullet 221@item 222@samp{info} 223 224Create an info version of the manual, in @file{mpc.info}. 225 226@item 227@samp{pdf} 228 229Create a PDF version of the manual, in @file{doc/mpc.pdf}. 230 231@item 232@samp{dvi} 233 234Create a DVI version of the manual, in @file{doc/mpc.dvi}. 235 236@item 237@samp{ps} 238 239Create a Postscript version of the manual, in @file{doc/mpc.ps}. 240 241@item 242@samp{html} 243 244Create an HTML version of the manual, in several pages in the 245directory @file{doc/mpc.html}; if you want only one output HTML file, 246then type @samp{makeinfo --html --no-split mpc.texi} instead. 247 248@item 249@samp{clean} 250 251Delete all object files and archive files, but not the configuration files. 252 253@item 254@samp{distclean} 255 256Delete all files not included in the distribution. 257 258@item 259@samp{uninstall} 260 261Delete all files copied by @samp{make install}. 262@end itemize 263 264 265 266@section Known Build Problems 267 268On AIX, if GMP was built with the 64-bit ABI, before building and testing GNU MPC, 269it might be necessary to set the @samp{OBJECT_MODE} environment variable to 64 270by, e.g., 271 272@samp{export OBJECT_MODE=64} 273 274This has been tested with the C compiler IBM XL C/C++ Enterprise Edition 275V8.0 for AIX, version: 08.00.0000.0021, GMP 4.2.4 and GNU MPFR 2.4.1. 276 277Please report any other problems you encounter to 278@samp{mpc-discuss@@lists.gforge.inria.fr}. 279@xref{Reporting Bugs}. 280 281@node Reporting Bugs 282@chapter Reporting Bugs 283@cindex Reporting bugs 284 285If you think you have found a bug in the GNU MPC library, 286please investigate 287and report it. We have made this library available to you, and it is not to ask 288too much from you, to ask you to report the bugs that you find. 289 290There are a few things you should think about when you put your bug report 291together. 292 293You have to send us a test case that makes it possible for us to reproduce the 294bug. Include instructions on how to run the test case. 295 296You also have to explain what is wrong; if you get a crash, or if the results 297printed are incorrect and in that case, in what way. 298 299Please include compiler version information in your bug report. 300This can be extracted using @samp{gcc -v}, 301or @samp{cc -V} on some machines. 302Also, include the output from @samp{uname -a}. 303 304If your bug report is good, we will do our best to help you to get a corrected 305version of the library; if the bug report is poor, we will not do anything about 306it (aside of chiding you to send better bug reports). 307 308Send your bug report to: @samp{mpc-discuss@@lists.gforge.inria.fr}. 309 310If you think something in this manual is unclear, or downright incorrect, or if 311the language needs to be improved, please send a note to the same address. 312 313@node GNU MPC Basics 314@chapter GNU MPC Basics 315 316 317@cindex @file{mpc.h} 318All declarations needed to use GNU MPC are collected in the include file 319@file{mpc.h}. It is designed to work with both C and C++ compilers. 320You should include that file in any program using the GNU MPC library 321by adding the line 322@example 323 #include "mpc.h" 324@end example 325 326@section Nomenclature and Types 327 328@cindex Complex number 329@tindex @code{mpc_t} 330@noindent 331@dfn{Complex number} or @dfn{Complex} for short, is a pair of two 332arbitrary precision floating-point numbers (for the real and imaginary parts). 333The C data type for such objects is @code{mpc_t}. 334 335@cindex Precision 336@tindex @code{mpfr_prec_t} 337@noindent 338The @dfn{Precision} is the number of bits used to represent the mantissa 339of the real and imaginary parts; 340the corresponding C data type is @code{mpfr_prec_t}. 341For more details on the allowed precision range, 342@ifinfo 343@pxref{Nomenclature and Types,,, mpfr.info,GNU MPFR}. 344@end ifinfo 345@ifnotinfo 346see Section ``Nomenclature and Types'' in @cite{GNU MPFR}. 347@end ifnotinfo 348 349@cindex Rounding Mode 350@tindex @code{mpc_rnd_t} 351@noindent 352The @dfn{rounding mode} specifies the way to round the result of a 353complex operation, in case the exact result can not be represented 354exactly in the destination mantissa; 355the corresponding C data type is @code{mpc_rnd_t}. 356A complex rounding mode is a pair of two rounding modes: one for the real 357part, one for the imaginary part. 358 359@section Function Classes 360 361There is only one class of functions in the GNU MPC library, namely functions for 362complex arithmetic. The function names begin with @code{mpc_}. The 363associated type is @code{mpc_t}. 364 365 366@section GNU MPC Variable Conventions 367 368As a general rule, all GNU MPC functions expect output arguments before input 369arguments. This notation is based on an analogy with the assignment operator. 370 371GNU MPC allows you to use the same variable for both input and output in the same 372expression. For example, the main function for floating-point multiplication, 373@code{mpc_mul}, can be used like this: @code{mpc_mul (x, x, x, rnd_mode)}. 374This 375computes the square of @var{x} with rounding mode @code{rnd_mode} 376and puts the result back in @var{x}. 377 378Before you can assign to an GNU MPC variable, you need to initialize it by calling 379one of the special initialization functions. When you are done with a 380variable, you need to clear it out, using one of the functions for that 381purpose. 382 383A variable should only be initialized once, or at least cleared out between 384each initialization. After a variable has been initialized, it may be 385assigned to any number of times. 386 387For efficiency reasons, avoid to initialize and clear out a variable in loops. 388Instead, initialize it before entering the loop, and clear it out after the 389loop has exited. 390 391You do not need to be concerned about allocating additional space for GNU MPC 392variables, since each of its real and imaginary part 393has a mantissa of fixed size. 394Hence unless you change its precision, or clear and reinitialize it, 395a complex variable will have the same allocated space during all its 396life. 397 398 399@section Rounding Modes 400 401A complex rounding mode is of the form @code{MPC_RNDxy} where 402@code{x} and @code{y} are one of @code{N} (to nearest), @code{Z} (towards 403zero), @code{U} (towards plus infinity), @code{D} (towards minus infinity). 404The first letter refers to the rounding mode for the real part, 405and the second one for the imaginary part. 406For example @code{MPC_RNDZU} indicates to round the real part towards zero, 407and the imaginary part towards plus infinity. 408 409The @samp{round to nearest} mode works as in the IEEE P754 standard: in case 410the number to be rounded lies exactly in the middle of two representable 411numbers, it is rounded to the one with the least significant bit set to zero. 412For example, the number 5, which is represented by (101) in binary, is rounded 413to (100)=4 with a precision of two bits, and not to (110)=6. 414 415 416@anchor{return-value} 417@section Return Value 418 419Most GNU MPC functions have a return value of type @code{int}, which is used 420to indicate the position of the rounded real and imaginary parts with respect 421to the exact (infinite precision) values. 422If this integer is @code{i}, the macros @code{MPC_INEX_RE(i)} and 423@code{MPC_INEX_IM(i)} give 0 if the corresponding rounded value is exact, 424a negative value if the rounded value is less than the exact one, 425and a positive value if it is greater than the exact one. 426Similarly, functions computing a result of type @code{mpfr_t} 427return an integer that is 0, positive or negative depending on 428whether the rounded value is the same, larger or smaller then 429the exact result. 430 431Some functions, such as @code{mpc_sin_cos}, compute two complex results; 432the macros @code{MPC_INEX1(i)} and @code{MPC_INEX2(i)}, applied to 433the return value @code{i} of such a function, yield the exactness value 434corresponding to the first or the second computed value, respectively. 435 436 437@section Branch Cuts And Special Values 438 439Some complex functions have branch cuts, across which the function is 440discontinous. In GNU MPC, the branch cuts chosen are the same as those 441specified for the corresponding functions in the ISO C99 standard. 442 443Likewise, when evaluated at a point whose real or imaginary part is 444either infinite or a NaN or a signed zero, a function returns the same 445value as those specified for the corresponding function in the ISO C99 446standard. 447 448 449@node Complex Functions 450@chapter Complex Functions 451@cindex Complex functions 452 453The complex functions expect arguments of type @code{mpc_t}. 454 455The GNU MPC floating-point functions have an interface that is similar to the 456GNU MP 457integer functions. The function prefix for operations on complex numbers is 458@code{mpc_}. 459 460@cindex User-defined precision 461The precision of a computation is defined as follows: Compute the requested 462operation exactly (with ``infinite precision''), and round the result to 463the destination variable precision with the given rounding mode. 464 465The GNU MPC complex functions are intended to be a smooth extension 466of the IEEE P754 arithmetic. The results obtained on one 467computer should not differ from the results obtained on a computer with a 468different word size. 469 470 471@menu 472* Initializing Complex Numbers:: 473* Assigning Complex Numbers:: 474* Converting Complex Numbers:: 475* String and Stream Input and Output:: 476* Complex Comparison:: 477* Projection & Decomposing:: 478* Basic Arithmetic:: 479* Power Functions and Logarithm:: 480* Trigonometric Functions:: 481* Miscellaneous Complex Functions:: 482* Advanced Functions:: 483* Internals:: 484@end menu 485 486@node Initializing Complex Numbers 487@section Initialization Functions 488 489An @code{mpc_t} object must be initialized before storing the first value in 490it. The functions @code{mpc_init2} and @code{mpc_init3} 491are used for that purpose. 492 493@deftypefun void mpc_init2 (mpc_t @var{z}, mpfr_prec_t @var{prec}) 494Initialize @var{z} to precision @var{prec} bits 495and set its real and imaginary parts to NaN. 496Normally, a variable should be initialized once only 497or at least be cleared, using @code{mpc_clear}, between initializations. 498@end deftypefun 499 500@deftypefun void mpc_init3 (mpc_t @var{z}, mpfr_prec_t @var{prec_r}, mpfr_prec_t @var{prec_i}) 501Initialize @var{z} with the precision of its real part being 502@var{prec_r} bits and the precision of its imaginary part being 503@var{prec_i} bits, and set the real and imaginary parts to NaN. 504@end deftypefun 505 506@deftypefun void mpc_clear (mpc_t @var{z}) 507Free the space occupied by @var{z}. Make sure to call this function for all 508@code{mpc_t} variables when you are done with them. 509@end deftypefun 510 511@need 2000 512Here is an example on how to initialize complex variables: 513@example 514@{ 515 mpc_t x, y; 516 mpc_init2 (x, 256); /* precision @emph{exactly} 256 bits */ 517 mpc_init3 (y, 100, 50); /* 100/50 bits for the real/imaginary part */ 518 @dots{} 519 mpc_clear (x); 520 mpc_clear (y); 521@} 522@end example 523 524The following function is useful for changing the precision during a 525calculation. A typical use would be for adjusting the precision gradually in 526iterative algorithms like Newton-Raphson, making the computation precision 527closely match the actual accurate part of the numbers. 528 529@deftypefun void mpc_set_prec (mpc_t @var{x}, mpfr_prec_t @var{prec}) 530Reset the precision of @var{x} to be @strong{exactly} @var{prec} bits, 531and set its real/imaginary parts to NaN. 532The previous value stored in @var{x} is lost. It is equivalent to 533a call to @code{mpc_clear(x)} followed by a call to 534@code{mpc_init2(x, prec)}, but more efficient as no allocation is done in 535case the current allocated space for the mantissa of @var{x} is sufficient. 536@end deftypefun 537 538@deftypefun mpfr_prec_t mpc_get_prec (mpc_t @var{x}) 539If the real and imaginary part of @var{x} have the same precision, it is returned, 540otherwise, 0 is returned. 541@end deftypefun 542 543@deftypefun void mpc_get_prec2 (mpfr_prec_t* @var{pr}, mpfr_prec_t* @var{pi}, mpc_t @var{x}) 544Returns the precision of the real part of @var{x} via @var{pr} and of its imaginary part 545via @var{pi}. 546@end deftypefun 547 548 549@node Assigning Complex Numbers 550@section Assignment Functions 551@cindex Complex assignment functions 552 553These functions assign new values to already initialized complex numbers 554(@pxref{Initializing Complex Numbers}). 555When using any functions with @code{intmax_t} or @code{uintmax_t} 556parameters, you must include 557@code{<stdint.h>} or @code{<inttypes.h>} @emph{before} @file{mpc.h}, to allow 558@file{mpc.h} to define prototypes for these functions. 559Similarly, functions with parameters of type @code{complex} or 560@code{long complex} are defined only if @code{<complex.h>} is included 561@emph{before} @file{mpc.h}. 562If you need assignment functions that are not in the current API, you can 563define them using the @code{MPC_SET_X_Y} macro (@pxref{Advanced Functions}). 564 565@deftypefun int mpc_set (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 566Set the value of @var{rop} from @var{op}, rounded to the precision of @var{rop} 567with the given rounding mode @var{rnd}. 568@end deftypefun 569 570@deftypefun int mpc_set_ui (mpc_t @var{rop}, unsigned long int @var{op}, mpc_rnd_t @var{rnd}) 571@deftypefunx int mpc_set_si (mpc_t @var{rop}, long int @var{op}, mpc_rnd_t @var{rnd}) 572@deftypefunx int mpc_set_uj (mpc_t @var{rop}, uintmax_t @var{op}, mpc_rnd_t @var{rnd}) 573@deftypefunx int mpc_set_sj (mpc_t @var{rop}, intmax_t @var{op}, mpc_rnd_t @var{rnd}) 574@deftypefunx int mpc_set_d (mpc_t @var{rop}, double @var{op}, mpc_rnd_t @var{rnd}) 575@deftypefunx int mpc_set_ld (mpc_t @var{rop}, long double @var{op}, mpc_rnd_t @var{rnd}) 576@deftypefunx int mpc_set_dc (mpc_t @var{rop}, double _Complex @var{op}, mpc_rnd_t @var{rnd}) 577@deftypefunx int mpc_set_ldc (mpc_t @var{rop}, long double _Complex @var{op}, mpc_rnd_t @var{rnd}) 578@deftypefunx int mpc_set_z (mpc_t @var{rop}, mpz_t @var{op} mpc_rnd_t @var{rnd}) 579@deftypefunx int mpc_set_q (mpc_t @var{rop}, mpq_t @var{op} mpc_rnd_t @var{rnd}) 580@deftypefunx int mpc_set_f (mpc_t @var{rop}, mpf_t @var{op} mpc_rnd_t @var{rnd}) 581@deftypefunx int mpc_set_fr (mpc_t @var{rop}, mpfr_t @var{op}, mpc_rnd_t @var{rnd}) 582Set the value of @var{rop} from @var{op}, rounded to the precision of 583@var{rop} with the given rounding mode @var{rnd}. 584The argument @var{op} is interpreted as real, so the imaginary part of 585@var{rop} is set to zero with a positive sign. 586Please note that even a @code{long int} may have to be rounded, if the 587destination precision is less than the machine word width. 588For @code{mpc_set_d}, be careful that the input number @var{op} may not be 589exactly representable as a double-precision number (this happens for 0.1 for 590instance), in which case it is first rounded by the C compiler to a 591double-precision number, and then only to a complex number. 592@end deftypefun 593 594@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}) 595@deftypefunx int mpc_set_si_si (mpc_t @var{rop}, long int @var{op1}, long int @var{op2}, mpc_rnd_t @var{rnd}) 596@deftypefunx int mpc_set_uj_uj (mpc_t @var{rop}, uintmax_t @var{op1}, uintmax_t @var{op2}, mpc_rnd_t @var{rnd}) 597@deftypefunx int mpc_set_sj_sj (mpc_t @var{rop}, intmax_t @var{op1}, intmax_t @var{op2}, mpc_rnd_t @var{rnd}) 598@deftypefunx int mpc_set_d_d (mpc_t @var{rop}, double @var{op1}, double @var{op2}, mpc_rnd_t @var{rnd}) 599@deftypefunx int mpc_set_ld_ld (mpc_t @var{rop}, long double @var{op1}, long double @var{op2}, mpc_rnd_t @var{rnd}) 600@deftypefunx int mpc_set_z_z (mpc_t @var{rop}, mpz_t @var{op1}, mpz_t @var{op2}, mpc_rnd_t @var{rnd}) 601@deftypefunx int mpc_set_q_q (mpc_t @var{rop}, mpq_t @var{op1}, mpq_t @var{op2}, mpc_rnd_t @var{rnd}) 602@deftypefunx int mpc_set_f_f (mpc_t @var{rop}, mpf_t @var{op1}, mpf_t @var{op2}, mpc_rnd_t @var{rnd}) 603@deftypefunx int mpc_set_fr_fr (mpc_t @var{rop}, mpfr_t @var{op1}, mpfr_t @var{op2}, mpc_rnd_t @var{rnd}) 604Set the real part of @var{rop} from @var{op1}, and its imaginary part from 605@var{op2}, according to the rounding mode @var{rnd}. 606 607Beware that the behaviour of @code{mpc_set_fr_fr} is undefined if @var{op1} 608or @var{op2} is a pointer to the real or imaginary part of @var{rop}. 609To exchange the real and the imaginary part of a complex number, either use 610@code{mpfr_swap (mpc_realref (rop), mpc_imagref (rop))}, which also exchanges 611the precisions of the two parts; or use a temporary variable. 612@end deftypefun 613 614For functions assigning complex variables from strings or input streams, 615@pxref{String and Stream Input and Output}. 616 617@deftypefun void mpc_set_nan (mpc_t @var{rop}) 618Set @var{rop} to Nan+i*NaN. 619@end deftypefun 620 621@deftypefun void mpc_swap (mpc_t @var{op1}, mpc_t @var{op2}) 622Swap the values of @var{op1} and @var{op2} efficiently. Warning: The 623precisions are exchanged, too; in case these are different, 624@code{mpc_swap} is thus not equivalent to three @code{mpc_set} calls using a 625third auxiliary variable. 626@end deftypefun 627 628 629@node Converting Complex Numbers 630@section Conversion Functions 631@cindex Conversion functions 632 633The following functions are available only if @code{<complex.h>} 634is included @emph{before} @file{mpc.h}. 635 636@deftypefun double _Complex mpc_get_dc (mpc_t @var{op}, mpc_rnd_t @var{rnd}) 637@deftypefunx {long double _Complex} mpc_get_ldc (mpc_t @var{op}, mpc_rnd_t @var{rnd}) 638Convert @var{op} to a C complex number, using the rounding mode @var{rnd}. 639@end deftypefun 640 641 642For functions converting complex variables to strings or stream output, 643@pxref{String and Stream Input and Output}. 644 645 646@node String and Stream Input and Output 647@section String and Stream Input and Output 648@cindex String and stream input and output 649 650@deftypefun int mpc_strtoc (mpc_t @var{rop}, const char *@var{nptr}, char **@var{endptr}, int @var{base}, mpc_rnd_t @var{rnd}) 651Read a complex number from a string @var{nptr} in base @var{base}, rounded to 652the precision of @var{rop} with the given rounding mode @var{rnd}. 653The @var{base} must be either 0 or a number from 2 to 36 (otherwise the 654behaviour is undefined). 655If @var{nptr} starts with valid data, the result is stored in @var{rop}, 656the usual inexact value is returned (@pxref{return-value,, Return 657Value}) and, if @var{endptr} is not the null pointer, 658@var{*endptr} points to the character just after the valid data. 659Otherwise, @var{rop} is set to @code{NaN + i * NaN}, -1 is returned and, 660if @var{endptr} is not the null pointer, 661the value of @var{nptr} is stored in the location referenced by 662@var{endptr}. 663 664The expected form of a complex number string is either a real number (an 665optional leading whitespace, an optional sign followed by a floating-point 666number), or a pair of real numbers in parentheses separated by whitespace. If 667a real number is read, the missing imaginary part is set to +0. 668The form of a floating-point number depends on the base and is described 669in the documentation of @code{mpfr_strtofr} 670@ifinfo 671(@pxref{Assignment Functions,,, mpfr.info,GNU MPFR}). 672@end ifinfo 673@ifnotinfo 674in the GNU MPFR manual. 675@end ifnotinfo 676For instance, @code{"3.1415926"}, @code{"(1.25e+7 +.17)"}, @code{"(@@nan@@ 6772)"} and @code{"(-0 -7)"} are valid strings for @var{base} = 10. 678If @var{base} = 0, then a prefix may be used to indicate the base in which the 679floating-point number is written. Use prefix '0b' for binary numbers, prefix 680'0x' for hexadecimal numbers, and no prefix for decimal numbers. 681The real and imaginary part may then be written in different bases. 682For instance, @code{"(1.024e+3 +2.05e+3)"} and @code{"(0b1p+10 +0x802)"} are 683valid strings for @code{base}=0 and represent the same value. 684@end deftypefun 685 686@deftypefun int mpc_set_str (mpc_t @var{rop}, const char *@var{s}, int @var{base}, mpc_rnd_t rnd) 687Set @var{rop} to the value of the string @var{s} in base @var{base}, rounded 688to the precision of @var{rop} with the given rounding mode @var{rnd}. 689See the documentation of @code{mpc_strtoc} for a detailed description of the 690valid string formats. 691Contrarily to @code{mpc_strtoc}, @code{mpc_set_str} requires the @emph{whole} 692string to represent a valid complex number (potentially followed by 693additional white space). 694This function returns the usual inexact value (@pxref{return-value,, Return 695Value}) if the entire string up to the final null character is a valid number 696in base @var{base}; otherwise it returns @minus{}1, and @var{rop} is set to 697NaN+i*NaN. 698@end deftypefun 699 700@deftypefun {char *} mpc_get_str (int @var{b}, size_t @var{n}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 701Convert @var{op} to a string containing its real and imaginary parts, 702separated by a space and enclosed in a pair of parentheses. 703The numbers are written in base @var{b} (which may vary from 2 to 36) and 704rounded according to @var{rnd}. The number of significant digits, at least 2, 705is given by @var{n}. It is also possible to let 706@var{n} be zero, in which case the number of digits is chosen large 707enough so that re-reading the printed value with the same precision, assuming 708both output and input use rounding to nearest, will recover the original value 709of @var{op}. 710Note that @code{mpc_get_str} uses the decimal point of the current locale 711if available, and @samp{.} otherwise. 712 713The string is generated using the current memory allocation function 714(@code{malloc} by default, unless it has been modified using the custom 715memory allocation interface of @code{gmp}); once it is not needed any more, 716it should be freed by calling @code{mpc_free_str}. 717@end deftypefun 718 719@deftypefun {void} mpc_free_str (char *@var{str}) 720Free the string @var{str}, which needs to have been allocated by 721a call to @code{mpc_get_str}. 722@end deftypefun 723 724The following two functions read numbers from input streams and write 725them to output streams. 726When using any of these functions, you need to include @file{stdio.h} 727@emph{before} @file{mpc.h}. 728 729@deftypefun int mpc_inp_str (mpc_t @var{rop}, FILE *@var{stream}, size_t *@var{read}, int @var{base}, mpc_rnd_t @var{rnd}) 730Input a string in base @var{base} in the same format as for @code{mpc_strtoc} 731from stdio stream @var{stream}, rounded according to @var{rnd}, and put the 732read complex number into @var{rop}. 733If @var{stream} is the null pointer, @var{rop} is read from @code{stdin}. 734Return the usual inexact value; if an error occurs, set @var{rop} to @code{NaN 735+ i * NaN} and return -1. 736If @var{read} is not the null pointer, it is set to the number of read 737characters. 738 739Unlike @code{mpc_strtoc}, the function @code{mpc_inp_str} does not possess 740perfect knowledge of the string to transform and has to read it 741character by character, so it behaves slightly differently: It tries 742to read a string describing a complex number and processes this string 743through a call to @code{mpc_set_str}. Precisely, after skipping optional 744whitespace, a minimal string is read according to the regular expression 745@code{mpfr | '(' \s* mpfr \s+ mpfr \s* ')'}, where @code{\s} denotes a whitespace, 746and @code{mpfr} is either a string containing neither whitespaces nor 747parentheses, or @code{nan(n-char-sequence)} or @code{@@nan@@(n-char-sequence)} 748(regardless of capitalisation) with @code{n-char-sequence} a string 749of ascii letters, digits or @code{'_'}. 750 751For instance, upon input of @code{"nan(13 1)"}, the function 752@code{mpc_inp_str} starts to recognise a value of NaN followed by an 753n-char-sequence indicated by the opening parenthesis; as soon as the 754space is reached, it becocmes clear that the expression in parentheses 755is not an n-char-sequence, and the error flag -1 is returned after 6 756characters have been consumed from the stream (the whitespace itself 757remaining in the stream). 758The function @code{mpc_strtoc}, on the other hand, may track back 759when reaching the whitespace; it treats the string as the two successive 760complex numbers @code{NaN + i * 0} and @code{13 + i}. 761It is thus recommended to have a whitespace follow each floating point number 762to avoid this problem. 763@end deftypefun 764 765@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}) 766Output @var{op} on stdio stream @var{stream} in 767base @var{base}, rounded according to @var{rnd}, in the same format 768as for @code{mpc_strtoc} 769If @var{stream} is the null pointer, @var{rop} is written to @code{stdout}. 770 771Return the number of characters written. 772@end deftypefun 773 774 775@node Complex Comparison 776@section Comparison Functions 777@cindex Complex comparisons functions 778@cindex Comparison functions 779 780@deftypefn Function int mpc_cmp (mpc_t @var{op1}, mpc_t @var{op2}) 781@deftypefnx Function int mpc_cmp_si_si (mpc_t @var{op1}, long int @var{op2r}, long int @var{op2i}) 782@deftypefnx Macro int mpc_cmp_si (mpc_t @var{op1}, long int @var{op2}) 783 784Compare @var{op1} and @var{op2}, where in the case of @code{mpc_cmp_si_si}, 785@var{op2} is taken to be @var{op2r} + i @var{op2i}. 786The return value @var{c} can be decomposed into @code{x = MPC_INEX_RE(c)} 787and @code{y = MPC_INEX_IM(c)}, such that @var{x} is 788positive if the real part of @var{op1} is greater than that of @var{op2}, 789zero if both real parts are equal, and negative if the real part of @var{op1} 790is less than that of @var{op2}, and likewise for @var{y}. 791Both @var{op1} and @var{op2} are considered to their full own precision, 792which may differ. 793It is not allowed that one of the operands has a NaN (Not-a-Number) part. 794 795The storage of the return value is such that equality can be simply checked 796with @code{mpc_cmp (op1, op2) == 0}. 797@end deftypefn 798 799 800@node Projection & Decomposing 801@section Projection and Decomposing Functions 802@cindex Projection and Decomposing Functions 803 804@deftypefn Function int mpc_real (mpfr_t @var{rop}, mpc_t @var{op}, mpfr_rnd_t @var{rnd}) 805Set @var{rop} to the value of the real part of @var{op} rounded 806in the direction @var{rnd}. 807@end deftypefn 808 809@deftypefn Function int mpc_imag (mpfr_t @var{rop}, mpc_t @var{op}, mpfr_rnd_t @var{rnd}) 810Set @var{rop} to the value of the imaginary part of @var{op} rounded in the 811direction @var{rnd}. 812@end deftypefn 813 814@deftypefn Macro mpfr_t mpc_realref (mpc_t @var{op}) 815@deftypefnx Macro mpfr_t mpc_imagref (mpc_t @var{op}) 816Return a reference to the real part and imaginary part of @var{op}, 817respectively. The @code{mpfr} functions can be used on the result of these 818macros (note that the @code{mpfr_t} type is itself a pointer). 819@end deftypefn 820 821@deftypefn Function int mpc_arg (mpfr_t @var{rop}, mpc_t @var{op}, mpfr_rnd_t @var{rnd}) 822Set @var{rop} to the argument of @var{op}, with a branch cut along the 823negative real axis. 824@end deftypefn 825 826@deftypefn Function int mpc_proj (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 827Compute a projection of @var{op} onto the Riemann sphere. Set @var{rop} to 828@var{op} rounded in the direction @var{rnd}, except when at least one part of 829@var{op} is infinite (even if the other part is a NaN) in which case the real 830part of @var{rop} is set to plus infinity and its imaginary part to a signed 831zero with the same sign as the imaginary part of @var{op}. 832@end deftypefn 833 834 835@node Basic Arithmetic 836@section Basic Arithmetic Functions 837@cindex Complex arithmetic functions 838@cindex Arithmetic functions 839 840All the following functions are designed in such a way that, when working 841with real numbers instead of complex numbers, their complexity should 842essentially be the same as with the GNU MPFR library, with only a marginal 843overhead due to the GNU MPC layer. 844 845@deftypefun int mpc_add (mpc_t @var{rop}, mpc_t @var{op1}, mpc_t @var{op2}, mpc_rnd_t @var{rnd}) 846@deftypefunx int mpc_add_ui (mpc_t @var{rop}, mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) 847@deftypefunx int mpc_add_fr (mpc_t @var{rop}, mpc_t @var{op1}, mpfr_t @var{op2}, mpc_rnd_t @var{rnd}) 848Set @var{rop} to @var{op1} @math{+} @var{op2} rounded according to @var{rnd}. 849@end deftypefun 850 851@deftypefn Function int mpc_sub (mpc_t @var{rop}, mpc_t @var{op1}, mpc_t @var{op2}, mpc_rnd_t @var{rnd}) 852@deftypefnx Function int mpc_sub_fr (mpc_t @var{rop}, mpc_t @var{op1}, mpfr_t @var{op2}, mpc_rnd_t @var{rnd}) 853@deftypefnx Function int mpc_fr_sub (mpc_t @var{rop}, mpfr_t @var{op1}, mpc_t @var{op2}, mpc_rnd_t @var{rnd}) 854@deftypefnx Function int mpc_sub_ui (mpc_t @var{rop}, mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) 855@deftypefnx Macro int mpc_ui_sub (mpc_t @var{rop}, unsigned long int @var{op1}, mpc_t @var{op2}, mpc_rnd_t @var{rnd}) 856@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}) 857Set @var{rop} to @var{op1} @minus{} @var{op2} rounded according to @var{rnd}. 858For @code{mpc_ui_ui_sub}, @var{op1} is @var{re1} + @var{im1}. 859@end deftypefn 860 861@deftypefun int mpc_neg (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 862Set @var{rop} to @minus{}@var{op} rounded according to @var{rnd}. 863Just changes the sign if @var{rop} and @var{op} are the same variable. 864@end deftypefun 865 866@deftypefun int mpc_mul (mpc_t @var{rop}, mpc_t @var{op1}, mpc_t @var{op2}, mpc_rnd_t @var{rnd}) 867@deftypefunx int mpc_mul_ui (mpc_t @var{rop}, mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) 868@deftypefunx int mpc_mul_si (mpc_t @var{rop}, mpc_t @var{op1}, long int @var{op2}, mpc_rnd_t @var{rnd}) 869@deftypefunx int mpc_mul_fr (mpc_t @var{rop}, mpc_t @var{op1}, mpfr_t @var{op2}, mpc_rnd_t @var{rnd}) 870Set @var{rop} to @var{op1} times @var{op2} rounded according to @var{rnd}. 871Note: for @code{mpc_mul}, in case @var{op1} and @var{op2} have the same value, 872use @code{mpc_sqr} for better efficiency. 873@end deftypefun 874 875@deftypefun int mpc_mul_i (mpc_t @var{rop}, mpc_t @var{op}, int @var{sgn}, mpc_rnd_t @var{rnd}) 876Set @var{rop} to @var{op} times the imaginary unit i if @var{sgn} is 877non-negative, set @var{rop} to @var{op} times -i otherwise, 878in both cases rounded according to @var{rnd}. 879@end deftypefun 880 881@deftypefun int mpc_sqr (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 882Set @var{rop} to the square of @var{op} rounded according to @var{rnd}. 883@end deftypefun 884 885@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}) 886Set @var{rop} to @var{op1}*@var{op2}+@var{op3}, 887rounded according to @var{rnd}, with only one final rounding. 888@end deftypefun 889 890@deftypefun int mpc_div (mpc_t @var{rop}, mpc_t @var{op1}, mpc_t @var{op2}, mpc_rnd_t @var{rnd}) 891@deftypefunx int mpc_div_ui (mpc_t @var{rop}, mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) 892@deftypefunx int mpc_div_fr (mpc_t @var{rop}, mpc_t @var{op1}, mpfr_t @var{op2}, mpc_rnd_t @var{rnd}) 893@deftypefunx int mpc_ui_div (mpc_t @var{rop}, unsigned long int @var{op1}, mpc_t @var{op2}, mpc_rnd_t @var{rnd}) 894@deftypefunx int mpc_fr_div (mpc_t @var{rop}, mpfr_t @var{op1}, mpc_t @var{op2}, mpc_rnd_t @var{rnd}) 895Set @var{rop} to @var{op1}/@var{op2} rounded according to @var{rnd}. 896@end deftypefun 897 898@deftypefun int mpc_conj (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 899Set @var{rop} to the conjugate of @var{op} rounded according to @var{rnd}. 900Just changes the sign of the imaginary part 901if @var{rop} and @var{op} are the same variable. 902@end deftypefun 903 904@deftypefun int mpc_abs (mpfr_t @var{rop}, mpc_t @var{op}, mpfr_rnd_t @var{rnd}) 905Set the floating-point number @var{rop} to the absolute value of @var{op}, 906rounded in the direction @var{rnd}. 907@end deftypefun 908 909@deftypefun int mpc_norm (mpfr_t @var{rop}, mpc_t @var{op}, mpfr_rnd_t @var{rnd}) 910Set the floating-point number @var{rop} to the norm of @var{op} 911(i.e., the square of its absolute value), 912rounded in the direction @var{rnd}. 913@end deftypefun 914 915@deftypefun int mpc_mul_2ui (mpc_t @var{rop}, mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) 916@deftypefunx int mpc_mul_2si (mpc_t @var{rop}, mpc_t @var{op1}, long int @var{op2}, mpc_rnd_t @var{rnd}) 917Set @var{rop} to @var{op1} times 2 raised to @var{op2} 918rounded according to @var{rnd}. Just modifies the exponents 919of the real and imaginary parts by @var{op2} 920when @var{rop} and @var{op1} are identical. 921@end deftypefun 922 923@deftypefun int mpc_div_2ui (mpc_t @var{rop}, mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) 924@deftypefunx int mpc_div_2si (mpc_t @var{rop}, mpc_t @var{op1}, long int @var{op2}, mpc_rnd_t @var{rnd}) 925Set @var{rop} to @var{op1} divided by 2 raised to @var{op2} 926rounded according to @var{rnd}. Just modifies the exponents 927of the real and imaginary parts by @var{op2} 928when @var{rop} and @var{op1} are identical. 929@end deftypefun 930 931 932@node Power Functions and Logarithm 933@section Power Functions and Logarithm 934@cindex Power functions 935@cindex Logarithm 936 937@deftypefun int mpc_sqrt (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 938Set @var{rop} to the square root of @var{op} rounded according to @var{rnd}. 939The returned value @var{rop} has a non-negative real part, and if its real 940part is zero, a non-negative imaginary part. 941@end deftypefun 942 943@deftypefun int mpc_pow (mpc_t @var{rop}, mpc_t @var{op1}, mpc_t @var{op2}, mpc_rnd_t @var{rnd}) 944@deftypefunx int mpc_pow_d (mpc_t @var{rop}, mpc_t @var{op1}, double @var{op2}, mpc_rnd_t @var{rnd}) 945@deftypefunx int mpc_pow_ld (mpc_t @var{rop}, mpc_t @var{op1}, long double @var{op2}, mpc_rnd_t @var{rnd}) 946@deftypefunx int mpc_pow_si (mpc_t @var{rop}, mpc_t @var{op1}, long @var{op2}, mpc_rnd_t @var{rnd}) 947@deftypefunx int mpc_pow_ui (mpc_t @var{rop}, mpc_t @var{op1}, unsigned long @var{op2}, mpc_rnd_t @var{rnd}) 948@deftypefunx int mpc_pow_z (mpc_t @var{rop}, mpc_t @var{op1}, mpz_t @var{op2}, mpc_rnd_t @var{rnd}) 949@deftypefunx int mpc_pow_fr (mpc_t @var{rop}, mpc_t @var{op1}, mpfr_t @var{op2}, mpc_rnd_t @var{rnd}) 950Set @var{rop} to @var{op1} raised to the power @var{op2}, rounded according 951to @var{rnd}. 952For @code{mpc_pow_d}, @code{mpc_pow_ld}, @code{mpc_pow_si}, @code{mpc_pow_ui}, 953@code{mpc_pow_z} and @code{mpc_pow_fr}, 954the imaginary part of @var{op2} is considered as +0. 955When both @var{op1} and @var{op2} are zero, the result has real part 1, 956and imaginary part 0, with sign being the opposite of that of @var{op2}. 957@end deftypefun 958 959@deftypefun int mpc_exp (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 960Set @var{rop} to the exponential of @var{op}, 961rounded according to @var{rnd} with the precision of @var{rop}. 962@end deftypefun 963 964@deftypefun int mpc_log (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 965@deftypefunx int mpc_log10 (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 966Set @var{rop} to the natural and base-10 logarithm of @var{op} respectively, 967rounded according to @var{rnd} with the precision of @var{rop}. 968The principal branch is chosen, with the branch cut on the negative real axis, 969so that the imaginary part of the result lies in 970@math{]-\pi , \pi]} and @math{]-\pi/log(10) , \pi/log(10)]} respectively. 971@end deftypefun 972 973 974@node Trigonometric Functions 975@section Trigonometric Functions 976@cindex Trigonometric functions 977 978@deftypefun int mpc_sin (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 979Set @var{rop} to the sine of @var{op}, 980rounded according to @var{rnd} with the precision of @var{rop}. 981@end deftypefun 982 983@deftypefun int mpc_cos (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 984Set @var{rop} to the cosine of @var{op}, 985rounded according to @var{rnd} with the precision of @var{rop}. 986@end deftypefun 987 988@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}) 989Set @var{rop_sin} to the sine of @var{op}, 990rounded according to @var{rnd_sin} with the precision of @var{rop_sin}, 991and @var{rop_cos} to the cosine of @var{op}, 992rounded according to @var{rnd_cos} with the precision of @var{rop_cos}. 993@end deftypefun 994 995@deftypefun int mpc_tan (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 996Set @var{rop} to the tangent of @var{op}, 997rounded according to @var{rnd} with the precision of @var{rop}. 998@end deftypefun 999 1000@deftypefun int mpc_sinh (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1001Set @var{rop} to the hyperbolic sine of @var{op}, 1002rounded according to @var{rnd} with the precision of @var{rop}. 1003@end deftypefun 1004 1005@deftypefun int mpc_cosh (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1006Set @var{rop} to the hyperbolic cosine of @var{op}, 1007rounded according to @var{rnd} with the precision of @var{rop}. 1008@end deftypefun 1009 1010@deftypefun int mpc_tanh (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1011Set @var{rop} to the hyperbolic tangent of @var{op}, 1012rounded according to @var{rnd} with the precision of @var{rop}. 1013@end deftypefun 1014 1015@deftypefun int mpc_asin (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1016@deftypefunx int mpc_acos (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1017@deftypefunx int mpc_atan (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1018Set @var{rop} to the inverse sine, inverse cosine, inverse tangent of @var{op}, 1019rounded according to @var{rnd} with the precision of @var{rop}. 1020@end deftypefun 1021 1022@deftypefun int mpc_asinh (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1023@deftypefunx int mpc_acosh (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1024@deftypefunx int mpc_atanh (mpc_t @var{rop}, mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1025Set @var{rop} to the inverse hyperbolic sine, inverse hyperbolic cosine, 1026inverse hyperbolic tangent of @var{op}, 1027rounded according to @var{rnd} with the precision of @var{rop}. 1028The branch cut of @var{mpc_acosh} is @math{(-\infty, 1)}. 1029@end deftypefun 1030 1031@node Miscellaneous Complex Functions 1032@section Miscellaneous Functions 1033@cindex Miscellaneous complex functions 1034 1035@deftypefun int mpc_urandom (mpc_t @var{rop}, gmp_randstate_t @var{state}) 1036Generate a uniformly distributed random complex in the unit square @math{[0, 10371] @times [0, 1]}. Return 0, unless an exponent in the real or imaginary part 1038is not in the current exponent range, in which case that part is set to NaN 1039and a zero value is returned. The second argument is a @code{gmp_randstate_t} 1040structure which should be created using the GMP @code{rand_init} function, see 1041the GMP manual. 1042@end deftypefun 1043 1044@deftypefun {const char *} mpc_get_version (void) 1045Return the GNU MPC version, as a null-terminated string. 1046@end deftypefun 1047 1048@defmac MPC_VERSION 1049@defmacx MPC_VERSION_MAJOR 1050@defmacx MPC_VERSION_MINOR 1051@defmacx MPC_VERSION_PATCHLEVEL 1052@defmacx MPC_VERSION_STRING 1053@code{MPC_VERSION} is the version of GNU MPC as a preprocessing constant. 1054@code{MPC_VERSION_MAJOR}, @code{MPC_VERSION_MINOR} and 1055@code{MPC_VERSION_PATCHLEVEL} are respectively the major, minor and 1056patch level of GNU MPC version, as preprocessing constants. 1057@code{MPC_VERSION_STRING} is the version as a string constant, which 1058can be compared to the result of @code{mpc_get_version} to check at 1059run time the header file and library used match: 1060@example 1061if (strcmp (mpc_get_version (), MPC_VERSION_STRING)) 1062 fprintf (stderr, "Warning: header and library do not match\n"); 1063@end example 1064Note: Obtaining different strings is not necessarily an error, as in 1065general, a program compiled with some old GNU MPC version can be 1066dynamically linked with a newer GNU MPC library version (if allowed by the 1067library versioning system). 1068@end defmac 1069 1070@deftypefn Macro long MPC_VERSION_NUM (@var{major}, @var{minor}, @var{patchlevel}) 1071Create an integer in the same format as used by @code{MPC_VERSION} from the 1072given @var{major}, @var{minor} and @var{patchlevel}. 1073Here is an example of how to check the GNU MPC version at compile time: 1074@example 1075#if (!defined(MPC_VERSION) || (MPC_VERSION<MPC_VERSION_NUM(2,1,0))) 1076# error "Wrong GNU MPC version." 1077#endif 1078@end example 1079@end deftypefn 1080 1081@node Advanced Functions 1082@section Advanced Functions 1083 1084@defmac MPC_SET_X_Y (@var{real_suffix}, @var{imag_suffix}, @var{rop}, @var{real}, @var{imag}, @var{rnd}) 1085The macro MPC_SET_X_Y is designed to serve as the body of an assignment 1086function and cannot be used by itself. 1087The @var{real_suffix} and @var{imag_suffix} parameters are the 1088types of the real and imaginary part, that is, the @code{x} in the 1089@code{mpfr_set_x} function one would use to set the part; 1090for the mpfr type, use @code{fr}. 1091@var{real} (respectively @var{imag}) is the value you want to assign to the 1092real (resp. imaginary) part, its type must conform to @var{real_suffix} 1093(resp. @var{imag_suffix}). 1094@var{rnd} is the @code{mpc_rnd_t} rounding mode. 1095The return value is the usual inexact value (@pxref{return-value,, Return 1096Value}). 1097 1098For instance, you can define mpc_set_ui_fr as follows: 1099@example 1100int mpc_set_ui_fr (mpc_t rop, long int re, double im, mpc_rnd_t rnd) 1101 MPC_SET_X_Y (ui, fr, rop, re, im, rnd); 1102@end example 1103@end defmac 1104 1105 1106@node Internals 1107@section Internals 1108 1109These macros and 1110functions are mainly designed for the implementation of GNU MPC, 1111but may be useful for users too. 1112However, no upward compatibility is guaranteed. 1113You need to include @code{mpc-impl.h} to use them. 1114 1115The macro @code{MPC_MAX_PREC(z)} gives the maximum of the precisions 1116of the real and imaginary parts of a complex number. 1117 1118 1119@node References 1120@unnumbered References 1121 1122@itemize @bullet 1123 1124@item 1125Torbj@"orn Granlund et al. 1126@code{gmp} -- GNU multiprecision library. 1127Version 4.2.4, @url{http://gmplib.org/}. 1128 1129@item 1130Guillaume Hanrot, Vincent Lef@`evre, Patrick P@'elissier, Paul Zimmermann et al. 1131@code{mpfr} -- A library for multiple-precision floating-point computations with exact rounding. 1132Version 2.4.1, @url{http://www.mpfr.org}. 1133 1134@item 1135IEEE standard for binary floating-point arithmetic, Technical Report 1136ANSI-IEEE Standard 754-1985, New York, 1985. 1137Approved March 21, 1985: IEEE Standards Board; approved July 26, 1138 1985: American National Standards Institute, 18 pages. 1139 1140@item 1141Donald E. Knuth, "The Art of Computer Programming", vol 2, 1142"Seminumerical Algorithms", 2nd edition, Addison-Wesley, 1981. 1143 1144@item 1145ISO/IEC 9899:1999, Programming languages ��� C. 1146 1147@end itemize 1148 1149@node Concept Index 1150@unnumbered Concept Index 1151@printindex cp 1152 1153@node Function Index 1154@unnumbered Function Index 1155@printindex fn 1156 1157@node GNU Free Documentation License 1158@appendix GNU Free Documentation License 1159@include fdl-1.3.texi 1160 1161@ifnothtml 1162@contents 1163@end ifnothtml 1164 1165@bye 1166