1\input texinfo 2@setfilename mpc.info 3@include version.texi 4@settitle GNU MPC @value{VERSION} 5 6@set MINGMP 5.0.0 7@set MINMPFR 4.1.0 8 9@set AUTHORS Andreas Enge, Philippe Th@'eveny, Paul Zimmermann 10 11@copying 12This manual is for GNU MPC, a library for multiple precision complex arithmetic, 13version @value{VERSION} of @value{UPDATED-MONTH}. 14 15Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2016, 2018, 2020, 2022 INRIA 16 17@quotation 18Permission is granted to copy, distribute and/or modify this document 19under the terms of the GNU Free Documentation License, Version 1.3 or 20any later version published by the Free Software Foundation; with no 21Invariant Sections. A copy of the license is included in the section 22entitled ``GNU Free Documentation License.'' 23@end quotation 24@end copying 25 26@iftex 27@afourpaper 28@end iftex 29@tex 30\global\parindent=0pt 31\global\parskip=8pt 32\global\baselineskip=13pt 33@end tex 34 35@dircategory GNU Packages 36@direntry 37* mpc: (mpc)Multiple Precision Complex Library. 38@end direntry 39 40 41@titlepage 42@title GNU MPC 43@subtitle The GNU Multiple Precision Complex Library 44@subtitle Edition @value{VERSION} 45@subtitle @value{UPDATED-MONTH} 46@author @value{AUTHORS} 47@page 48@vskip 0pt plus 1filll 49@insertcopying 50@end titlepage 51 52 53@ifnottex 54@node Top 55@top GNU MPC 56 57This manual documents how to install and use the GNU Multiple Precision 58Complex Library, version @value{VERSION} 59@end ifnottex 60 61@menu 62* Copying:: GNU MPC Copying Conditions (LGPL). 63* Introduction to GNU MPC:: Brief introduction to GNU MPC. 64* Installing GNU MPC:: How to configure and compile the GNU MPC library. 65* Reporting Bugs:: How to usefully report bugs. 66* GNU MPC Basics:: What every GNU MPC user should know. 67* Complex Functions:: Functions for arithmetic on complex numbers. 68* Ball Arithmetic:: Types and functions for complex balls. 69* References:: 70* Concept Index:: 71* Function Index:: 72* Type Index:: 73* GNU Free Documentation License:: 74@end menu 75 76@c @times{} made available as a "x" in info and html (already works in tex). 77@ifnottex 78@macro times 79x 80@end macro 81@end ifnottex 82 83@c @m{T,N} is $T$ in tex or @math{N} otherwise. This is an easy way to give 84@c different forms for math in tex and info. Commas in N or T don't work, 85@c but @C{} can be used instead. \, works in info but not in tex. 86@c (copied from mpfr.texi) 87@iftex 88@macro m {T,N} 89@tex$\T\$@end tex 90@end macro 91@end iftex 92@ifnottex 93@macro m {T,N} 94@math{\N\} 95@end macro 96@end ifnottex 97 98@node Copying 99@unnumbered GNU MPC Copying Conditions 100@cindex Copying conditions 101@cindex Conditions for copying GNU MPC 102 103GNU MPC is free software; you can redistribute it and/or modify it under 104the terms of the GNU Lesser General Public License as published by the 105Free Software Foundation; either version 3 of the License, or (at your 106option) any later version. 107 108GNU MPC is distributed in the hope that it will be useful, but WITHOUT ANY 109WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 110FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for 111more details. 112 113You should have received a copy of the GNU Lesser General Public License 114along with this program. If not, see @uref{http://www.gnu.org/licenses/}. 115 116 117@node Introduction to GNU MPC 118@chapter Introduction to GNU MPC 119 120 121GNU MPC is a portable library written in C for arbitrary precision arithmetic 122on complex numbers providing correct rounding. It implements a multiprecision 123equivalent of the C99 standard. 124It builds upon the GNU MP and the GNU MPFR libraries. 125 126@section How to use this Manual 127 128Everyone should read @ref{GNU MPC Basics}. If you need to install the library 129yourself, you need to read @ref{Installing GNU MPC}, too. 130 131The remainder of the manual can be used for later reference, although it is 132probably a good idea to skim through it. 133 134@node Installing GNU MPC 135@chapter Installing GNU MPC 136@cindex Installation 137 138To build GNU MPC, you first have to install GNU MP (version @value{MINGMP} or higher) and 139GNU MPFR (version @value{MINMPFR} or higher) on your computer. You need a C compiler; 140GCC version 4.4 or higher is recommended, since GNU MPC may trigger a bug in previous 141versions, see the thread at 142@uref{https://sympa.inria.fr/sympa/arc/mpc-discuss/2011-02/msg00024.html}. 143And you need a 144standard Unix @samp{make} program, plus some other standard Unix utility 145programs. 146 147Here are the steps needed to install the library on Unix systems: 148 149@enumerate 150@item 151@samp{tar xzf mpc-@value{VERSION}.tar.gz} 152 153@item 154@samp{cd mpc-@value{VERSION}} 155 156@item 157@samp{./configure} 158 159if GMP and GNU MPFR are installed into standard directories, that is, directories 160that are searched by default by the compiler and the linking tools. 161 162@samp{./configure --with-gmp=<gmp_install_dir>} 163 164is used to indicate a different location where GMP is 165installed. Alternatively, you can specify directly GMP include and GMP lib 166directories with @samp{./configure --with-gmp-lib=<gmp_lib_dir> 167--with-gmp-include=<gmp_include_dir>}. 168 169@samp{./configure --with-mpfr=<mpfr_install_dir>} 170 171is used to indicate a different location where GNU MPFR is 172installed. Alternatively, you can specify directly GNU MPFR include and GNU MPFR lib 173directories with @samp{./configure --with-mpf-lib=<mpfr_lib_dir> 174--with-mpfr-include=<mpfr_include_dir>}. 175 176Another useful parameter is @samp{--prefix}, which can be used to 177specify an alternative installation location instead of 178@file{/usr/local}; see @samp{make install} below. 179 180To enable checking for memory leaks using @command{valgrind} during 181@code{make check}, add the parameter @code{--enable-valgrind-tests}. 182 183If for debugging purposes you wish to log calls to GNU MPC functions from 184within your code, add the parameter @samp{--enable-logging}. 185In your code, replace the inclusion of @file{mpc.h} by @file{mpc-log.h} 186and link the executable dynamically. 187Then all calls to functions with only complex arguments are printed to 188@file{stderr} in the following form: First, the function name is given, 189followed by its type such as @samp{c_cc}, meaning that the function has 190one complex result (one @samp{c} in front of the @samp{_}), computed from 191two complex arguments (two @samp{c} after the @samp{_}). Then, the 192precisions of the real and the imaginary part of the first result is given, 193followed by the second one and so on. Finally, for each argument, the 194precisions of its real and imaginary part are specified and the argument 195itself is printed in hexadecimal via the function 196@code{mpc_out_str} 197(@pxref{String and Stream Input and Output}). 198The option requires a dynamic library, so it may not be combined with 199@code{--disable-shared}. 200 201Use @samp{./configure --help} for an exhaustive list of parameters. 202 203@item 204@samp{make} 205 206This compiles GNU MPC in the working directory. 207 208@item 209@samp{make check} 210 211This will make sure GNU MPC was built correctly. 212 213If you get error messages, please report them to 214@samp{mpc-discuss@@inria.fr} (@xref{Reporting Bugs}, for 215information on what to include in useful bug reports). 216 217@item 218@samp{make install} 219 220This will copy the file @file{mpc.h} to the directory 221@file{/usr/local/include}, the file @file{libmpc.a} to the directory 222@file{/usr/local/lib}, and the file @file{mpc.info} to the directory 223@file{/usr/local/share/info} (or if you passed the @samp{--prefix} option to 224@file{configure}, using the prefix directory given as argument to 225@samp{--prefix} instead of @file{/usr/local}). Note: you need write permissions 226on these directories. 227 228@end enumerate 229 230 231@section Other `make' Targets 232 233There are some other useful make targets: 234 235@itemize @bullet 236@item 237@samp{info} 238 239Create an info version of the manual, in @file{mpc.info}. 240 241@item 242@samp{pdf} 243 244Create a PDF version of the manual, in @file{doc/mpc.pdf}. 245 246@item 247@samp{dvi} 248 249Create a DVI version of the manual, in @file{doc/mpc.dvi}. 250 251@item 252@samp{ps} 253 254Create a Postscript version of the manual, in @file{doc/mpc.ps}. 255 256@item 257@samp{html} 258 259Create an HTML version of the manual, in several pages in the 260directory @file{doc/mpc.html}; if you want only one output HTML file, 261then type @samp{makeinfo --html --no-split mpc.texi} instead. 262 263@item 264@samp{clean} 265 266Delete all object files and archive files, but not the configuration files. 267 268@item 269@samp{distclean} 270 271Delete all files not included in the distribution. 272 273@item 274@samp{uninstall} 275 276Delete all files copied by @samp{make install}. 277@end itemize 278 279 280 281@section Known Build Problems 282 283On AIX, if GMP was built with the 64-bit ABI, before building and testing GNU MPC, 284it might be necessary to set the @samp{OBJECT_MODE} environment variable to 64 285by, e.g., 286 287@samp{export OBJECT_MODE=64} 288 289This has been tested with the C compiler IBM XL C/C++ Enterprise Edition 290V8.0 for AIX, version: 08.00.0000.0021, GMP 4.2.4 and GNU MPFR 2.4.1. 291 292Please report any other problems you encounter to 293@samp{mpc-discuss@@inria.fr}. 294@xref{Reporting Bugs}. 295 296@node Reporting Bugs 297@chapter Reporting Bugs 298@cindex Reporting bugs 299 300If you think you have found a bug in the GNU MPC library, 301please investigate 302and report it. We have made this library available to you, and it is not to ask 303too much from you, to ask you to report the bugs that you find. 304 305There are a few things you should think about when you put your bug report 306together. 307 308You have to send us a test case that makes it possible for us to reproduce the 309bug. Include instructions on how to run the test case. 310 311You also have to explain what is wrong; if you get a crash, or if the results 312printed are incorrect and in that case, in what way. 313 314Please include compiler version information in your bug report. 315This can be extracted using @samp{gcc -v}, 316or @samp{cc -V} on some machines. 317Also, include the output from @samp{uname -a}. 318 319If your bug report is good, we will do our best to help you to get a corrected 320version of the library; if the bug report is poor, we will not do anything about 321it (aside of chiding you to send better bug reports). 322 323Send your bug report to: @samp{mpc-discuss@@inria.fr}. 324 325If you think something in this manual is unclear, or downright incorrect, or if 326the language needs to be improved, please send a note to the same address. 327 328@node GNU MPC Basics 329@chapter GNU MPC Basics 330 331 332@cindex @file{mpc.h} 333All declarations needed to use GNU MPC are collected in the include file 334@file{mpc.h}. It is designed to work with both C and C++ compilers. 335You should include that file in any program using the GNU MPC library 336by adding the line 337@example 338 #include "mpc.h" 339@end example 340 341@section Nomenclature and Types 342 343@cindex Complex number 344@tindex mpc_t 345@tindex mpc_ptr 346@tindex mpc_srcptr 347@noindent 348@dfn{Complex number} or @dfn{Complex} for short, is a pair of two 349arbitrary precision floating-point numbers (for the real and imaginary parts). 350The C data type for such objects is @code{mpc_t}. 351 352@cindex Precision 353@tindex mpfr_prec_t 354@noindent 355The @dfn{Precision} is the number of bits used to represent the mantissa 356of the real and imaginary parts; 357the corresponding C data type is @code{mpfr_prec_t}. 358For more details on the allowed precision range, 359@ifinfo 360@pxref{Nomenclature and Types,,, mpfr.info,GNU MPFR}. 361@end ifinfo 362@ifnotinfo 363see Section ``Nomenclature and Types'' in @cite{GNU MPFR}. 364@end ifnotinfo 365 366@cindex Rounding Mode 367@tindex mpc_rnd_t 368@noindent 369The @dfn{rounding mode} specifies the way to round the result of a 370complex operation, in case the exact result can not be represented 371exactly in the destination mantissa; 372the corresponding C data type is @code{mpc_rnd_t}. 373A complex rounding mode is a pair of two rounding modes: one for the real 374part, one for the imaginary part. 375 376@section Function Classes 377 378There is only one class of functions in the GNU MPC library, namely functions for 379complex arithmetic. The function names begin with @code{mpc_}. The 380associated type is @code{mpc_t}. 381 382 383@section GNU MPC Variable Conventions 384 385As a general rule, all GNU MPC functions expect output arguments before input 386arguments. This notation is based on an analogy with the assignment operator. 387 388GNU MPC allows you to use the same variable for both input and output in the same 389expression. For example, the main function for floating-point multiplication, 390@code{mpc_mul}, can be used like this: @code{mpc_mul (x, x, x, rnd_mode)}. 391This 392computes the square of @var{x} with rounding mode @code{rnd_mode} 393and puts the result back in @var{x}. 394 395Before you can assign to an GNU MPC variable, you need to initialise it by calling 396one of the special initialization functions. When you are done with a 397variable, you need to clear it out, using one of the functions for that 398purpose. 399 400A variable should only be initialised once, or at least cleared out between 401each initialization. After a variable has been initialised, it may be 402assigned to any number of times. 403 404For efficiency reasons, avoid to initialise and clear out a variable in loops. 405Instead, initialise it before entering the loop, and clear it out after the 406loop has exited. 407 408You do not need to be concerned about allocating additional space for GNU MPC 409variables, since each of its real and imaginary part 410has a mantissa of fixed size. 411Hence unless you change its precision, or clear and reinitialise it, 412a complex variable will have the same allocated space during all its 413life. 414 415 416@section Rounding Modes 417 418A complex rounding mode is of the form @code{MPC_RNDxy} where 419@code{x} and @code{y} are one of @code{N} (to nearest), @code{Z} (towards 420zero), @code{U} (towards plus infinity), @code{D} (towards minus infinity), 421@code{A} (away from zero, that is, towards plus or minus infinity depending 422on the sign of the number to be rounded). 423The first letter refers to the rounding mode for the real part, 424and the second one for the imaginary part. 425For example @code{MPC_RNDZU} indicates to round the real part towards zero, 426and the imaginary part towards plus infinity. 427 428The @samp{round to nearest} mode works as in the IEEE P754 standard: in case 429the number to be rounded lies exactly in the middle of two representable 430numbers, it is rounded to the one with the least significant bit set to zero. 431For example, the number 5, which is represented by (101) in binary, is rounded 432to (100)=4 with a precision of two bits, and not to (110)=6. 433 434 435@anchor{return-value} 436@section Return Value 437 438Most GNU MPC functions have a return value of type @code{int}, which is used 439to indicate the position of the rounded real and imaginary parts with respect 440to the exact (infinite precision) values. 441If this integer is @code{i}, the macros @code{MPC_INEX_RE(i)} and 442@code{MPC_INEX_IM(i)} give 0 if the corresponding rounded value is exact, 443a negative value if the rounded value is less than the exact one, 444and a positive value if it is greater than the exact one. 445Similarly, functions computing a result of type @code{mpfr_t} 446return an integer that is 0, positive or negative depending on 447whether the rounded value is the same, larger or smaller then 448the exact result. 449 450Some functions, such as @code{mpc_sin_cos}, compute two complex results; 451the macros @code{MPC_INEX1(i)} and @code{MPC_INEX2(i)}, applied to 452the return value @code{i} of such a function, yield the exactness value 453corresponding to the first or the second computed value, respectively. 454 455 456@section Branch Cuts And Special Values 457 458Some complex functions have branch cuts, across which the function is 459discontinous. In GNU MPC, the branch cuts chosen are the same as those 460specified for the corresponding functions in the ISO C99 standard. 461 462Likewise, when evaluated at a point whose real or imaginary part is 463either infinite or a NaN or a signed zero, a function returns the same 464value as those specified for the corresponding function in the ISO C99 465standard. 466 467 468@node Complex Functions 469@chapter Complex Functions 470@cindex Complex functions 471 472The complex functions expect arguments of type @code{mpc_t}. 473 474The GNU MPC floating-point functions have an interface that is similar to the 475GNU MP 476integer functions. The function prefix for operations on complex numbers is 477@code{mpc_}. 478 479@cindex User-defined precision 480The precision of a computation is defined as follows: Compute the requested 481operation exactly (with ``infinite precision''), and round the result to 482the destination variable precision with the given rounding mode. 483 484The GNU MPC complex functions are intended to be a smooth extension 485of the IEEE P754 arithmetic. The results obtained on one 486computer should not differ from the results obtained on a computer with a 487different word size. 488 489 490@menu 491* Initializing Complex Numbers:: 492* Assigning Complex Numbers:: 493* Converting Complex Numbers:: 494* String and Stream Input and Output:: 495* Complex Comparison:: 496* Projection & Decomposing:: 497* Basic Arithmetic:: 498* Power Functions and Logarithm:: 499* Trigonometric Functions:: 500* Modular Functions:: 501* Miscellaneous Complex Functions:: 502* Advanced Functions:: 503* Internals:: 504@end menu 505 506@node Initializing Complex Numbers 507@section Initialization Functions 508 509An @code{mpc_t} object must be initialised before storing the first value in 510it. The functions @code{mpc_init2} and @code{mpc_init3} 511are used for that purpose. 512 513@deftypefun void mpc_init2 (mpc_t @var{z}, mpfr_prec_t @var{prec}) 514Initialise @var{z} to precision @var{prec} bits 515and set its real and imaginary parts to NaN. 516Normally, a variable should be initialised once only 517or at least be cleared, using @code{mpc_clear}, between initializations. 518@end deftypefun 519 520@deftypefun void mpc_init3 (mpc_t @var{z}, mpfr_prec_t @var{prec_r}, mpfr_prec_t @var{prec_i}) 521Initialise @var{z} with the precision of its real part being 522@var{prec_r} bits and the precision of its imaginary part being 523@var{prec_i} bits, and set the real and imaginary parts to NaN. 524@end deftypefun 525 526@deftypefun void mpc_clear (mpc_t @var{z}) 527Free the space occupied by @var{z}. Make sure to call this function for all 528@code{mpc_t} variables when you are done with them. 529@end deftypefun 530 531@need 2000 532Here is an example on how to initialise complex variables: 533@example 534@{ 535 mpc_t x, y; 536 mpc_init2 (x, 256); /* precision @emph{exactly} 256 bits */ 537 mpc_init3 (y, 100, 50); /* 100/50 bits for the real/imaginary part */ 538 @dots{} 539 mpc_clear (x); 540 mpc_clear (y); 541@} 542@end example 543 544The following function is useful for changing the precision during a 545calculation. A typical use would be for adjusting the precision gradually in 546iterative algorithms like Newton-Raphson, making the computation precision 547closely match the actual accurate part of the numbers. 548 549@deftypefun void mpc_set_prec (mpc_t @var{x}, mpfr_prec_t @var{prec}) 550Reset the precision of @var{x} to be @strong{exactly} @var{prec} bits, 551and set its real/imaginary parts to NaN. 552The previous value stored in @var{x} is lost. It is equivalent to 553a call to @code{mpc_clear(x)} followed by a call to 554@code{mpc_init2(x, prec)}, but more efficient as no allocation is done in 555case the current allocated space for the mantissa of @var{x} is sufficient. 556@end deftypefun 557 558@deftypefun mpfr_prec_t mpc_get_prec (const mpc_t @var{x}) 559If the real and imaginary part of @var{x} have the same precision, it is returned, 560otherwise, 0 is returned. 561@end deftypefun 562 563@deftypefun void mpc_get_prec2 (mpfr_prec_t* @var{pr}, mpfr_prec_t* @var{pi}, const mpc_t @var{x}) 564Returns the precision of the real part of @var{x} via @var{pr} and of its imaginary part 565via @var{pi}. 566@end deftypefun 567 568 569@node Assigning Complex Numbers 570@section Assignment Functions 571@cindex Complex assignment functions 572 573These functions assign new values to already initialised complex numbers 574(@pxref{Initializing Complex Numbers}). 575When using any functions with @code{intmax_t} or @code{uintmax_t} 576parameters, you must include 577@code{<stdint.h>} or @code{<inttypes.h>} @emph{before} @file{mpc.h}, to allow 578@file{mpc.h} to define prototypes for these functions. 579Similarly, functions with parameters of type @code{complex} or 580@code{long complex} are defined only if @code{<complex.h>} is included 581@emph{before} @file{mpc.h}. 582If you need assignment functions that are not in the current API, you can 583define them using the @code{MPC_SET_X_Y} macro (@pxref{Advanced Functions}). 584 585@deftypefun int mpc_set (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 586Set the value of @var{rop} from @var{op}, rounded to the precision of @var{rop} 587with the given rounding mode @var{rnd}. 588@end deftypefun 589 590@deftypefun int mpc_set_ui (mpc_t @var{rop}, unsigned long int @var{op}, mpc_rnd_t @var{rnd}) 591@deftypefunx int mpc_set_si (mpc_t @var{rop}, long int @var{op}, mpc_rnd_t @var{rnd}) 592@deftypefunx int mpc_set_uj (mpc_t @var{rop}, uintmax_t @var{op}, mpc_rnd_t @var{rnd}) 593@deftypefunx int mpc_set_sj (mpc_t @var{rop}, intmax_t @var{op}, mpc_rnd_t @var{rnd}) 594@deftypefunx int mpc_set_d (mpc_t @var{rop}, double @var{op}, mpc_rnd_t @var{rnd}) 595@deftypefunx int mpc_set_ld (mpc_t @var{rop}, long double @var{op}, mpc_rnd_t @var{rnd}) 596@deftypefunx int mpc_set_dc (mpc_t @var{rop}, double _Complex @var{op}, mpc_rnd_t @var{rnd}) 597@deftypefunx int mpc_set_ldc (mpc_t @var{rop}, long double _Complex @var{op}, mpc_rnd_t @var{rnd}) 598@deftypefunx int mpc_set_z (mpc_t @var{rop}, const mpz_t @var{op} mpc_rnd_t @var{rnd}) 599@deftypefunx int mpc_set_q (mpc_t @var{rop}, const mpq_t @var{op} mpc_rnd_t @var{rnd}) 600@deftypefunx int mpc_set_f (mpc_t @var{rop}, const mpf_t @var{op} mpc_rnd_t @var{rnd}) 601@deftypefunx int mpc_set_fr (mpc_t @var{rop}, const mpfr_t @var{op}, mpc_rnd_t @var{rnd}) 602Set the value of @var{rop} from @var{op}, rounded to the precision of 603@var{rop} with the given rounding mode @var{rnd}. 604The argument @var{op} is interpreted as real, so the imaginary part of 605@var{rop} is set to zero with a positive sign. 606Please note that even a @code{long int} may have to be rounded, if the 607destination precision is less than the machine word width. 608For @code{mpc_set_d}, be careful that the input number @var{op} may not be 609exactly representable as a double-precision number (this happens for 0.1 for 610instance), in which case it is first rounded by the C compiler to a 611double-precision number, and then only to a complex number. 612@end deftypefun 613 614@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}) 615@deftypefunx int mpc_set_si_si (mpc_t @var{rop}, long int @var{op1}, long int @var{op2}, mpc_rnd_t @var{rnd}) 616@deftypefunx int mpc_set_uj_uj (mpc_t @var{rop}, uintmax_t @var{op1}, uintmax_t @var{op2}, mpc_rnd_t @var{rnd}) 617@deftypefunx int mpc_set_sj_sj (mpc_t @var{rop}, intmax_t @var{op1}, intmax_t @var{op2}, mpc_rnd_t @var{rnd}) 618@deftypefunx int mpc_set_d_d (mpc_t @var{rop}, double @var{op1}, double @var{op2}, mpc_rnd_t @var{rnd}) 619@deftypefunx int mpc_set_ld_ld (mpc_t @var{rop}, long double @var{op1}, long double @var{op2}, mpc_rnd_t @var{rnd}) 620@deftypefunx int mpc_set_z_z (mpc_t @var{rop}, const mpz_t @var{op1}, const mpz_t @var{op2}, mpc_rnd_t @var{rnd}) 621@deftypefunx int mpc_set_q_q (mpc_t @var{rop}, const mpq_t @var{op1}, const mpq_t @var{op2}, mpc_rnd_t @var{rnd}) 622@deftypefunx int mpc_set_f_f (mpc_t @var{rop}, const mpf_t @var{op1}, const mpf_t @var{op2}, mpc_rnd_t @var{rnd}) 623@deftypefunx int mpc_set_fr_fr (mpc_t @var{rop}, const mpfr_t @var{op1}, const mpfr_t @var{op2}, mpc_rnd_t @var{rnd}) 624Set the real part of @var{rop} from @var{op1}, and its imaginary part from 625@var{op2}, according to the rounding mode @var{rnd}. 626 627Beware that the behaviour of @code{mpc_set_fr_fr} is undefined if @var{op1} 628or @var{op2} is a pointer to the real or imaginary part of @var{rop}. 629To exchange the real and the imaginary part of a complex number, either use 630@code{mpfr_swap (mpc_realref (rop), mpc_imagref (rop))}, which also exchanges 631the precisions of the two parts; or use a temporary variable. 632@end deftypefun 633 634For functions assigning complex variables from strings or input streams, 635@pxref{String and Stream Input and Output}. 636 637@deftypefun void mpc_set_nan (mpc_t @var{rop}) 638Set @var{rop} to Nan+i*NaN. 639@end deftypefun 640 641@deftypefun void mpc_swap (mpc_t @var{op1}, mpc_t @var{op2}) 642Swap the values of @var{op1} and @var{op2} efficiently. Warning: The 643precisions are exchanged, too; in case these are different, 644@code{mpc_swap} is thus not equivalent to three @code{mpc_set} calls using a 645third auxiliary variable. 646@end deftypefun 647 648 649@node Converting Complex Numbers 650@section Conversion Functions 651@cindex Conversion functions 652 653The following functions are available only if @code{<complex.h>} 654is included @emph{before} @file{mpc.h}. 655 656@deftypefun double _Complex mpc_get_dc (const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 657@deftypefunx {long double _Complex} mpc_get_ldc (mpc_t @var{op}, mpc_rnd_t @var{rnd}) 658Convert @var{op} to a C complex number, using the rounding mode @var{rnd}. 659@end deftypefun 660 661 662For functions converting complex variables to strings or stream output, 663@pxref{String and Stream Input and Output}. 664 665 666@node String and Stream Input and Output 667@section String and Stream Input and Output 668@cindex String and stream input and output 669 670@deftypefun int mpc_strtoc (mpc_t @var{rop}, const char *@var{nptr}, char **@var{endptr}, int @var{base}, mpc_rnd_t @var{rnd}) 671Read a complex number from a string @var{nptr} in base @var{base}, rounded to 672the precision of @var{rop} with the given rounding mode @var{rnd}. 673The @var{base} must be either 0 or a number from 2 to 36 (otherwise the 674behaviour is undefined). 675If @var{nptr} starts with valid data, the result is stored in @var{rop}, 676the usual inexact value is returned (@pxref{return-value,, Return 677Value}) and, if @var{endptr} is not the null pointer, 678@var{*endptr} points to the character just after the valid data. 679Otherwise, @var{rop} is set to @code{NaN + i * NaN}, -1 is returned and, 680if @var{endptr} is not the null pointer, 681the value of @var{nptr} is stored in the location referenced by 682@var{endptr}. 683 684The expected form of a complex number string is either a real number (an 685optional leading whitespace, an optional sign followed by a floating-point 686number), or a pair of real numbers in parentheses separated by whitespace. If 687a real number is read, the missing imaginary part is set to +0. 688The form of a floating-point number depends on the base and is described 689in the documentation of @code{mpfr_strtofr} 690@ifinfo 691(@pxref{Assignment Functions,,, mpfr.info,GNU MPFR}). 692@end ifinfo 693@ifnotinfo 694in the GNU MPFR manual. 695@end ifnotinfo 696For instance, @code{"3.1415926"}, @code{"(1.25e+7 +.17)"}, @code{"(@@nan@@ 6972)"} and @code{"(-0 -7)"} are valid strings for @var{base} = 10. 698If @var{base} = 0, then a prefix may be used to indicate the base in which the 699floating-point number is written. Use prefix '0b' for binary numbers, prefix 700'0x' for hexadecimal numbers, and no prefix for decimal numbers. 701The real and imaginary part may then be written in different bases. 702For instance, @code{"(1.024e+3 +2.05e+3)"} and @code{"(0b1p+10 +0x802)"} are 703valid strings for @code{base}=0 and represent the same value. 704@end deftypefun 705 706@deftypefun int mpc_set_str (mpc_t @var{rop}, const char *@var{s}, int @var{base}, mpc_rnd_t rnd) 707Set @var{rop} to the value of the string @var{s} in base @var{base}, rounded 708to the precision of @var{rop} with the given rounding mode @var{rnd}. 709See the documentation of @code{mpc_strtoc} for a detailed description of the 710valid string formats. 711Contrarily to @code{mpc_strtoc}, @code{mpc_set_str} requires the @emph{whole} 712string to represent a valid complex number (potentially followed by 713additional white space). 714This function returns the usual inexact value (@pxref{return-value,, Return 715Value}) if the entire string up to the final null character is a valid number 716in base @var{base}; otherwise it returns @minus{}1, and @var{rop} is set to 717NaN+i*NaN. 718@end deftypefun 719 720@deftypefun {char *} mpc_get_str (int @var{b}, size_t @var{n}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 721Convert @var{op} to a string containing its real and imaginary parts, 722separated by a space and enclosed in a pair of parentheses. 723The numbers are written in base @var{b} (which may vary from 2 to 36) and 724rounded according to @var{rnd}. The number of significant digits, at least 2, 725is given by @var{n}. It is also possible to let 726@var{n} be zero, in which case the number of digits is chosen large 727enough so that re-reading the printed value with the same precision, assuming 728both output and input use rounding to nearest, will recover the original value 729of @var{op}. 730Note that @code{mpc_get_str} uses the decimal point of the current locale 731if available, and @samp{.} otherwise. 732 733The string is generated using the current memory allocation function 734(@code{malloc} by default, unless it has been modified using the custom 735memory allocation interface of @code{gmp}); once it is not needed any more, 736it should be freed by calling @code{mpc_free_str}. 737@end deftypefun 738 739@deftypefun {void} mpc_free_str (char *@var{str}) 740Free the string @var{str}, which needs to have been allocated by 741a call to @code{mpc_get_str}. 742@end deftypefun 743 744The following two functions read numbers from input streams and write 745them to output streams. 746When using any of these functions, you need to include @file{stdio.h} 747@emph{before} @file{mpc.h}. 748 749@deftypefun int mpc_inp_str (mpc_t @var{rop}, FILE *@var{stream}, size_t *@var{read}, int @var{base}, mpc_rnd_t @var{rnd}) 750Input a string in base @var{base} in the same format as for @code{mpc_strtoc} 751from stdio stream @var{stream}, rounded according to @var{rnd}, and put the 752read complex number into @var{rop}. 753If @var{stream} is the null pointer, @var{rop} is read from @code{stdin}. 754Return the usual inexact value; if an error occurs, set @var{rop} to @code{NaN 755+ i * NaN} and return -1. 756If @var{read} is not the null pointer, it is set to the number of read 757characters. 758 759Unlike @code{mpc_strtoc}, the function @code{mpc_inp_str} does not possess 760perfect knowledge of the string to transform and has to read it 761character by character, so it behaves slightly differently: It tries 762to read a string describing a complex number and processes this string 763through a call to @code{mpc_set_str}. Precisely, after skipping optional 764whitespace, a minimal string is read according to the regular expression 765@code{mpfr | '(' \s* mpfr \s+ mpfr \s* ')'}, where @code{\s} denotes a whitespace, 766and @code{mpfr} is either a string containing neither whitespaces nor 767parentheses, or @code{nan(n-char-sequence)} or @code{@@nan@@(n-char-sequence)} 768(regardless of capitalisation) with @code{n-char-sequence} a string 769of ascii letters, digits or @code{'_'}. 770 771For instance, upon input of @code{"nan(13 1)"}, the function 772@code{mpc_inp_str} starts to recognise a value of NaN followed by an 773n-char-sequence indicated by the opening parenthesis; as soon as the 774space is reached, it becomes clear that the expression in parentheses 775is not an n-char-sequence, and the error flag -1 is returned after 6 776characters have been consumed from the stream (the whitespace itself 777remaining in the stream). 778The function @code{mpc_strtoc}, on the other hand, may track back 779when reaching the whitespace; it treats the string as the two successive 780complex numbers @code{NaN + i * 0} and @code{13 + i}. 781It is thus recommended to have a whitespace follow each floating point number 782to avoid this problem. 783@end deftypefun 784 785@deftypefun size_t mpc_out_str (FILE *@var{stream}, int @var{base}, size_t @var{n_digits}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 786Output @var{op} on stdio stream @var{stream} in 787base @var{base}, rounded according to @var{rnd}, in the same format 788as for @code{mpc_strtoc} 789If @var{stream} is the null pointer, @var{rop} is written to @code{stdout}. 790 791Return the number of characters written. 792@end deftypefun 793 794 795@node Complex Comparison 796@section Comparison Functions 797@cindex Complex comparisons functions 798@cindex Comparison functions 799 800@deftypefn Function int mpc_cmp (const mpc_t @var{op1}, const mpc_t @var{op2}) 801@deftypefnx Function int mpc_cmp_si_si (const mpc_t @var{op1}, long int @var{op2r}, long int @var{op2i}) 802@deftypefnx Macro int mpc_cmp_si (mpc_t @var{op1}, long int @var{op2}) 803 804Compare @var{op1} and @var{op2}, where in the case of @code{mpc_cmp_si_si}, 805@var{op2} is taken to be @var{op2r} + i @var{op2i}. 806The return value @var{c} can be decomposed into @code{x = MPC_INEX_RE(c)} 807and @code{y = MPC_INEX_IM(c)}, such that @var{x} is 808positive if the real part of @var{op1} is greater than that of @var{op2}, 809zero if both real parts are equal, and negative if the real part of @var{op1} 810is less than that of @var{op2}, and likewise for @var{y}. 811Both @var{op1} and @var{op2} are considered to their full own precision, 812which may differ. 813It is not allowed that one of the operands has a NaN (Not-a-Number) part. 814 815The storage of the return value is such that equality can be simply checked 816with @code{mpc_cmp (op1, op2) == 0}. 817@end deftypefn 818 819@deftypefn Function int mpc_cmp_abs (const mpc_t @var{op1}, const mpc_t @var{op2}) 820 821Compare the absolute values of @var{op1} and @var{op2}. 822The return value is 0 if both are the same (including infinity), 823positive if the absolute value of @var{op1} is greater than that of @var{op2}, 824and negative if it is smaller. 825If @var{op1} or @var{op2} has a real or imaginary part which is NaN, 826the function behaves like @code{mpfr_cmp} on two real numbers of which at least 827one is NaN. 828@end deftypefn 829 830 831@node Projection & Decomposing 832@section Projection and Decomposing Functions 833@cindex Projection and Decomposing Functions 834 835@deftypefn Function int mpc_real (mpfr_t @var{rop}, const mpc_t @var{op}, mpfr_rnd_t @var{rnd}) 836Set @var{rop} to the value of the real part of @var{op} rounded 837in the direction @var{rnd}. 838@end deftypefn 839 840@deftypefn Function int mpc_imag (mpfr_t @var{rop}, const mpc_t @var{op}, mpfr_rnd_t @var{rnd}) 841Set @var{rop} to the value of the imaginary part of @var{op} rounded in the 842direction @var{rnd}. 843@end deftypefn 844 845@deftypefn Macro mpfr_t mpc_realref (mpc_t @var{op}) 846@deftypefnx Macro mpfr_t mpc_imagref (mpc_t @var{op}) 847Return a reference to the real part and imaginary part of @var{op}, 848respectively. The @code{mpfr} functions can be used on the result of these 849macros (note that the @code{mpfr_t} type is itself a pointer). 850@end deftypefn 851 852@deftypefn Function int mpc_arg (mpfr_t @var{rop}, const mpc_t @var{op}, mpfr_rnd_t @var{rnd}) 853Set @var{rop} to the argument of @var{op}, with a branch cut along the 854negative real axis. 855@end deftypefn 856 857@deftypefn Function int mpc_proj (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 858Compute a projection of @var{op} onto the Riemann sphere. Set @var{rop} to 859@var{op} rounded in the direction @var{rnd}, except when at least one part of 860@var{op} is infinite (even if the other part is a NaN) in which case the real 861part of @var{rop} is set to plus infinity and its imaginary part to a signed 862zero with the same sign as the imaginary part of @var{op}. 863@end deftypefn 864 865 866@node Basic Arithmetic 867@section Basic Arithmetic Functions 868@cindex Complex arithmetic functions 869@cindex Arithmetic functions 870 871All the following functions are designed in such a way that, when working 872with real numbers instead of complex numbers, their complexity should 873essentially be the same as with the GNU MPFR library, with only a marginal 874overhead due to the GNU MPC layer. 875 876For functions taking as input an integer argument 877(for example @code{mpc_add_ui}), when this argument is zero, 878it is considered as an unsigned (that is, exact in this context) 879zero, and we follow the MPFR conventions: 880(0) + (+0) = +0, (0) - (+0) = -0, (0) - (+0) = -0, (0) - (-0) = +0. 881The same applies for functions taking an argument of type @code{mpfr_t}, 882such as @code{mpc_add_fr}, of which the imaginary part is considered 883to be an exact, unsigned zero. 884 885@deftypefun int mpc_add (mpc_t @var{rop}, const mpc_t @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd}) 886@deftypefunx int mpc_add_ui (mpc_t @var{rop}, const mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) 887@deftypefunx int mpc_add_fr (mpc_t @var{rop}, const mpc_t @var{op1}, const mpfr_t @var{op2}, mpc_rnd_t @var{rnd}) 888Set @var{rop} to @var{op1} @math{+} @var{op2} rounded according to @var{rnd}. 889@end deftypefun 890 891@deftypefn Function int mpc_sub (mpc_t @var{rop}, const mpc_t @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd}) 892@deftypefnx Function int mpc_sub_fr (mpc_t @var{rop}, const mpc_t @var{op1}, const mpfr_t @var{op2}, mpc_rnd_t @var{rnd}) 893@deftypefnx Function int mpc_fr_sub (mpc_t @var{rop}, const mpfr_t @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd}) 894@deftypefnx Function int mpc_sub_ui (mpc_t @var{rop}, const mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) 895@deftypefnx Macro int mpc_ui_sub (mpc_t @var{rop}, unsigned long int @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd}) 896@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}) 897Set @var{rop} to @var{op1} @minus{} @var{op2} rounded according to @var{rnd}. 898For @code{mpc_ui_ui_sub}, @var{op1} is @var{re1} + @var{im1}. 899@end deftypefn 900 901@deftypefun int mpc_neg (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 902Set @var{rop} to @minus{}@var{op} rounded according to @var{rnd}. 903Just changes the sign if @var{rop} and @var{op} are the same variable. 904@end deftypefun 905 906@deftypefun int mpc_sum (mpc_t @var{rop}, const mpc_ptr* @var{op}, unsigned long @var{n}, mpc_rnd_t @var{rnd}) 907Set @var{rop} to the sum of the elements in the array @var{op} of 908length @var{n}, rounded according to @var{rnd}. 909@end deftypefun 910 911@deftypefun int mpc_mul (mpc_t @var{rop}, const mpc_t @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd}) 912@deftypefunx int mpc_mul_ui (mpc_t @var{rop}, const mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) 913@deftypefunx int mpc_mul_si (mpc_t @var{rop}, const mpc_t @var{op1}, long int @var{op2}, mpc_rnd_t @var{rnd}) 914@deftypefunx int mpc_mul_fr (mpc_t @var{rop}, const mpc_t @var{op1}, const mpfr_t @var{op2}, mpc_rnd_t @var{rnd}) 915Set @var{rop} to @var{op1} times @var{op2} rounded according to @var{rnd}. 916Note: for @code{mpc_mul}, in case @var{op1} and @var{op2} have the same value, 917use @code{mpc_sqr} for better efficiency. 918@end deftypefun 919 920@deftypefun int mpc_mul_i (mpc_t @var{rop}, const mpc_t @var{op}, int @var{sgn}, mpc_rnd_t @var{rnd}) 921Set @var{rop} to @var{op} times the imaginary unit i if @var{sgn} is 922non-negative, set @var{rop} to @var{op} times -i otherwise, 923in both cases rounded according to @var{rnd}. 924@end deftypefun 925 926@deftypefun int mpc_sqr (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 927Set @var{rop} to the square of @var{op} rounded according to @var{rnd}. 928@end deftypefun 929 930@deftypefun int mpc_fma (mpc_t @var{rop}, const mpc_t @var{op1}, const mpc_t @var{op2}, const mpc_t @var{op3}, mpc_rnd_t @var{rnd}) 931Set @var{rop} to @var{op1}*@var{op2}+@var{op3}, 932rounded according to @var{rnd}, with only one final rounding. 933@end deftypefun 934 935@deftypefun int mpc_dot (mpc_t @var{rop}, const mpc_ptr* @var{op1}, mpc_ptr* @var{op2}, unsigned long @var{n}, mpc_rnd_t @var{rnd}) 936Set @var{rop} to the dot product of the elements in the arrays @var{op1} and 937@var{op2}, both of length @var{n}, rounded according to @var{rnd}. 938@end deftypefun 939 940@deftypefun int mpc_div (mpc_t @var{rop}, const mpc_t @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd}) 941@deftypefunx int mpc_div_ui (mpc_t @var{rop}, const mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) 942@deftypefunx int mpc_div_fr (mpc_t @var{rop}, const mpc_t @var{op1}, const mpfr_t @var{op2}, mpc_rnd_t @var{rnd}) 943@deftypefunx int mpc_ui_div (mpc_t @var{rop}, unsigned long int @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd}) 944@deftypefunx int mpc_fr_div (mpc_t @var{rop}, const mpfr_t @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd}) 945Set @var{rop} to @var{op1}/@var{op2} rounded according to @var{rnd}. 946@end deftypefun 947 948@deftypefun int mpc_conj (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 949Set @var{rop} to the conjugate of @var{op} rounded according to @var{rnd}. 950Just changes the sign of the imaginary part 951if @var{rop} and @var{op} are the same variable. 952@end deftypefun 953 954@deftypefun int mpc_abs (mpfr_t @var{rop}, const mpc_t @var{op}, mpfr_rnd_t @var{rnd}) 955Set the floating-point number @var{rop} to the absolute value of @var{op}, 956rounded in the direction @var{rnd}. 957@end deftypefun 958 959@deftypefun int mpc_norm (mpfr_t @var{rop}, const mpc_t @var{op}, mpfr_rnd_t @var{rnd}) 960Set the floating-point number @var{rop} to the norm of @var{op} 961(i.e., the square of its absolute value), 962rounded in the direction @var{rnd}. 963@end deftypefun 964 965@deftypefun int mpc_mul_2ui (mpc_t @var{rop}, const mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) 966@deftypefunx int mpc_mul_2si (mpc_t @var{rop}, const mpc_t @var{op1}, long int @var{op2}, mpc_rnd_t @var{rnd}) 967Set @var{rop} to @var{op1} times 2 raised to @var{op2} 968rounded according to @var{rnd}. Just modifies the exponents 969of the real and imaginary parts by @var{op2} 970when @var{rop} and @var{op1} are identical. 971@end deftypefun 972 973@deftypefun int mpc_div_2ui (mpc_t @var{rop}, const mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd}) 974@deftypefunx int mpc_div_2si (mpc_t @var{rop}, const mpc_t @var{op1}, long int @var{op2}, mpc_rnd_t @var{rnd}) 975Set @var{rop} to @var{op1} divided by 2 raised to @var{op2} 976rounded according to @var{rnd}. Just modifies the exponents 977of the real and imaginary parts by @var{op2} 978when @var{rop} and @var{op1} are identical. 979@end deftypefun 980 981 982@node Power Functions and Logarithm 983@section Power Functions and Logarithm 984@cindex Power functions 985@cindex Logarithm 986 987@deftypefun int mpc_sqrt (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 988Set @var{rop} to the square root of @var{op} rounded according to @var{rnd}. 989The returned value @var{rop} has a non-negative real part, and if its real 990part is zero, a non-negative imaginary part. 991@end deftypefun 992 993@deftypefun int mpc_pow (mpc_t @var{rop}, const mpc_t @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd}) 994@deftypefunx int mpc_pow_d (mpc_t @var{rop}, const mpc_t @var{op1}, double @var{op2}, mpc_rnd_t @var{rnd}) 995@deftypefunx int mpc_pow_ld (mpc_t @var{rop}, const mpc_t @var{op1}, long double @var{op2}, mpc_rnd_t @var{rnd}) 996@deftypefunx int mpc_pow_si (mpc_t @var{rop}, const mpc_t @var{op1}, long @var{op2}, mpc_rnd_t @var{rnd}) 997@deftypefunx int mpc_pow_ui (mpc_t @var{rop}, const mpc_t @var{op1}, unsigned long @var{op2}, mpc_rnd_t @var{rnd}) 998@deftypefunx int mpc_pow_z (mpc_t @var{rop}, const mpc_t @var{op1}, const mpz_t @var{op2}, mpc_rnd_t @var{rnd}) 999@deftypefunx int mpc_pow_fr (mpc_t @var{rop}, const mpc_t @var{op1}, const mpfr_t @var{op2}, mpc_rnd_t @var{rnd}) 1000Set @var{rop} to @var{op1} raised to the power @var{op2}, rounded according 1001to @var{rnd}. 1002For @code{mpc_pow_d}, @code{mpc_pow_ld}, @code{mpc_pow_si}, @code{mpc_pow_ui}, 1003@code{mpc_pow_z} and @code{mpc_pow_fr}, 1004the imaginary part of @var{op2} is considered as +0. 1005When both @var{op1} and @var{op2} are zero, the result has real part 1, 1006and imaginary part 0, with sign being the opposite of that of @var{op2}. 1007@end deftypefun 1008 1009@deftypefun int mpc_exp (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1010Set @var{rop} to the exponential of @var{op}, 1011rounded according to @var{rnd} with the precision of @var{rop}. 1012@end deftypefun 1013 1014@deftypefun int mpc_log (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1015@deftypefunx int mpc_log10 (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1016Set @var{rop} to the natural and base-10 logarithm of @var{op} respectively, 1017rounded according to @var{rnd} with the precision of @var{rop}. 1018The principal branch is chosen, with the branch cut on the negative real axis, 1019so that the imaginary part of the result lies in 1020@iftex 1021@math{]-\pi , \pi]} 1022@end iftex 1023@ifnottex 1024]-Pi , Pi] 1025@end ifnottex 1026and 1027@iftex 1028@math{]-\pi/\log(10) , \pi/\log(10)]} 1029@end iftex 1030@ifnottex 1031]-Pi/log(10) , Pi/log(10)] 1032@end ifnottex 1033respectively. 1034@end deftypefun 1035 1036@deftypefun int mpc_rootofunity (mpc_t @var{rop}, unsigned long int @var{n}, unsigned long int @var{k}, mpc_rnd_t @var{rnd}) 1037Set @var{rop} to the standard primitive @var{n}-th root of unity raised to the power @var{k}, that is, 1038@m{\exp (2 \pi i k / n),exp (2 Pi i k / n)}, 1039rounded according to @var{rnd} with the precision of @var{rop}. 1040@end deftypefun 1041 1042@deftypefun int mpc_agm (mpc_t @var{rop}, const mpc_t @var{a}, const mpc_t @var{b}, mpc_rnd_t @var{rnd}) 1043Set @var{rop} to the arithmetic-geometric mean (AGM) of @var{a} and 1044@var{b}, rounded according to @var{rnd} with the precision of @var{rop}. 1045Concerning the branch cut, the function is computed by homogeneity either 1046as @var{a} AGM(1,b0) with b0=@var{b}/@var{a} if |@var{a}|>=|@var{b}|, 1047or as @var{b} AGM(1,b0) with b0=@var{a}/@var{b} otherwise; 1048then when b0 is real and negative, AGM(1,b0) is chosen to have positive 1049imaginary part. 1050@end deftypefun 1051 1052 1053@node Trigonometric Functions 1054@section Trigonometric Functions 1055@cindex Trigonometric functions 1056 1057@deftypefun int mpc_sin (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1058@deftypefunx int mpc_cos (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1059@deftypefunx int mpc_tan (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1060Set @var{rop} to the sine, cosine, tangent of @var{op}, 1061rounded according to @var{rnd} with the precision of @var{rop}. 1062@end deftypefun 1063 1064@deftypefun int mpc_sin_cos (mpc_t @var{rop_sin}, mpc_t @var{rop_cos}, const mpc_t @var{op}, mpc_rnd_t @var{rnd_sin}, mpc_rnd_t @var{rnd_cos}) 1065Set @var{rop_sin} to the sine of @var{op}, 1066rounded according to @var{rnd_sin} with the precision of @var{rop_sin}, 1067and @var{rop_cos} to the cosine of @var{op}, 1068rounded according to @var{rnd_cos} with the precision of @var{rop_cos}. 1069@end deftypefun 1070 1071@deftypefun int mpc_sinh (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1072@deftypefunx int mpc_cosh (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1073@deftypefunx int mpc_tanh (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1074Set @var{rop} to the hyperbolic sine, hyperbolic cosine, hyperbolic tangent of @var{op}, 1075rounded according to @var{rnd} with the precision of @var{rop}. 1076@end deftypefun 1077 1078@deftypefun int mpc_asin (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1079@deftypefunx int mpc_acos (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1080@deftypefunx int mpc_atan (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1081Set @var{rop} to the inverse sine, inverse cosine, inverse tangent of @var{op}, 1082rounded according to @var{rnd} with the precision of @var{rop}. 1083@end deftypefun 1084 1085@deftypefun int mpc_asinh (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1086@deftypefunx int mpc_acosh (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1087@deftypefunx int mpc_atanh (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1088Set @var{rop} to the inverse hyperbolic sine, inverse hyperbolic cosine, 1089inverse hyperbolic tangent of @var{op}, 1090rounded according to @var{rnd} with the precision of @var{rop}. 1091The branch cut of @code{mpc_acosh} is 1092@iftex 1093@math{(-\infty, 1)}. 1094@end iftex 1095@ifnottex 1096(-Inf, 1) 1097@end ifnottex 1098@end deftypefun 1099 1100 1101@node Modular Functions 1102@section Modular Functions 1103@cindex Modular functions 1104 1105The following function is experimental, not least because it depends on 1106the equally experimental ball arithmetic, see @ref {Ball Arithmetic}. 1107So its prototype may change in future releases, and it may be removed 1108altogether. 1109 1110@deftypefun int mpc_eta_fund (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd}) 1111Assuming that the argument @var{op} lies in the fundamental domain for 1112@math{Sl_2(Z)}, that is, it has real part not below @math{-1/2} and 1113not above @math{+1/2} and absolute value at least 1, 1114return the value of the Dedekind eta-function in @var{rop}. 1115For arguments outside the fundamental domain the function is expected to 1116loop indefinitely. 1117@end deftypefun 1118 1119 1120@node Miscellaneous Complex Functions 1121@section Miscellaneous Functions 1122@cindex Miscellaneous complex functions 1123 1124@deftypefun int mpc_urandom (mpc_t @var{rop}, gmp_randstate_t @var{state}) 1125Generate a uniformly distributed random complex in the unit square @math{[0, 11261] @times [0, 1]}. Return 0, unless an exponent in the real or imaginary part 1127is not in the current exponent range, in which case that part is set to NaN 1128and a zero value is returned. The second argument is a @code{gmp_randstate_t} 1129structure which should be created using the GMP @code{rand_init} function, see 1130the GMP manual. 1131@end deftypefun 1132 1133@deftypefun {const char *} mpc_get_version (void) 1134Return the GNU MPC version, as a null-terminated string. 1135@end deftypefun 1136 1137@defmac MPC_VERSION 1138@defmacx MPC_VERSION_MAJOR 1139@defmacx MPC_VERSION_MINOR 1140@defmacx MPC_VERSION_PATCHLEVEL 1141@defmacx MPC_VERSION_STRING 1142@code{MPC_VERSION} is the version of GNU MPC as a preprocessing constant. 1143@code{MPC_VERSION_MAJOR}, @code{MPC_VERSION_MINOR} and 1144@code{MPC_VERSION_PATCHLEVEL} are respectively the major, minor and 1145patch level of GNU MPC version, as preprocessing constants. 1146@code{MPC_VERSION_STRING} is the version as a string constant, which 1147can be compared to the result of @code{mpc_get_version} to check at 1148run time the header file and library used match: 1149@example 1150if (strcmp (mpc_get_version (), MPC_VERSION_STRING)) 1151 fprintf (stderr, "Warning: header and library do not match\n"); 1152@end example 1153Note: Obtaining different strings is not necessarily an error, as in 1154general, a program compiled with some old GNU MPC version can be 1155dynamically linked with a newer GNU MPC library version (if allowed by the 1156library versioning system). 1157@end defmac 1158 1159@deftypefn Macro long MPC_VERSION_NUM (@var{major}, @var{minor}, @var{patchlevel}) 1160Create an integer in the same format as used by @code{MPC_VERSION} from the 1161given @var{major}, @var{minor} and @var{patchlevel}. 1162Here is an example of how to check the GNU MPC version at compile time: 1163@example 1164#if (!defined(MPC_VERSION) || (MPC_VERSION<MPC_VERSION_NUM(2,1,0))) 1165# error "Wrong GNU MPC version." 1166#endif 1167@end example 1168@end deftypefn 1169 1170@node Advanced Functions 1171@section Advanced Functions 1172 1173@defmac MPC_SET_X_Y (@var{real_suffix}, @var{imag_suffix}, @var{rop}, @var{real}, @var{imag}, @var{rnd}) 1174The macro MPC_SET_X_Y is designed to serve as the body of an assignment 1175function and cannot be used by itself. 1176The @var{real_suffix} and @var{imag_suffix} parameters are the 1177types of the real and imaginary part, that is, the @code{x} in the 1178@code{mpfr_set_x} function one would use to set the part; 1179for the mpfr type, use @code{fr}. 1180@var{real} (respectively @var{imag}) is the value you want to assign to the 1181real (resp. imaginary) part, its type must conform to @var{real_suffix} 1182(resp. @var{imag_suffix}). 1183@var{rnd} is the @code{mpc_rnd_t} rounding mode. 1184The return value is the usual inexact value (@pxref{return-value,, Return 1185Value}). 1186 1187For instance, you can define mpc_set_ui_fr as follows: 1188@example 1189int mpc_set_ui_fr (mpc_t rop, unsigned long int re, mpfr_t im, mpc_rnd_t rnd) 1190 MPC_SET_X_Y (ui, fr, rop, re, im, rnd); 1191@end example 1192@end defmac 1193 1194 1195@node Internals 1196@section Internals 1197 1198These macros and 1199functions are mainly designed for the implementation of GNU MPC, 1200but may be useful for users too. 1201However, no upward compatibility is guaranteed. 1202You need to include @code{mpc-impl.h} to use them. 1203 1204The macro @code{MPC_MAX_PREC(z)} gives the maximum of the precisions 1205of the real and imaginary parts of a complex number. 1206 1207 1208@node Ball Arithmetic 1209@chapter Ball Arithmetic 1210@cindex Ball arithmetic 1211 1212Since release 1.3.0, GNU MPC contains a simple and very limited 1213implementation of complex balls (or rather, circles). This part is 1214experimental, its interface may vary and it may be removed completely 1215in future releases. 1216 1217@tindex mpcb_t 1218A complex ball of the new type @code{mpcb_t} is defined by a non-zero centre 1219@math{c} of the type @code{mpc_t} and a relative radius @math{r} of 1220the new type @code{mpcr_t}, and it represents all complex numbers 1221@math{z = c (1 + ��)} with @math{|��| ��� r}, or equivalently 1222the closed circle with centre @math{c} and radius @math{r |c|}. 1223The approach of using a relative error (or radius) instead of an absolute 1224one simplifies error analyses for multiplicative operations (multiplication, 1225division, square roots, and the AGM), at the expense of making them more 1226complicated for additive operations. It has the major drawback of not being 1227able to represent balls centred at 0; in floating point arithmetic, however, 12280 is never reached by rounding, but only through operations with exact 1229result, which could be handled at a higher, application level. For more 1230discussion on these issues, see the file @code{algorithms.tex}. 1231 1232 1233@section Radius type and functions 1234@tindex mpcr_t 1235@tindex mpcr_ptr 1236@tindex mpcr_srcptr 1237 1238The radius type is defined by 1239@verbatim 1240struct { 1241 int64_t mant; 1242 int64_t exp; 1243} 1244@end verbatim 1245with the usual trick in the GNU multiprecision libraries of defining the 1246main type @code{mpcr_t} as a 1-dimensional array of this struct, and 1247variable and constant pointers @code{mpcr_ptr} and @code{mpcr_srcptr}. 1248It can contain the special values infinity or zero, or floating point 1249numbers encoded as @math{m���2@sup{e}} for a positive mantissa 1250@math{m} and an arbitrary (usually negative) exponent @math{e}. 1251Normalised finite radii use 31 bits for the mantissa, that is, 1252@math{2@sup{30}���m���2@sup{31} - 1}. 1253The special values infinity and 0 are encoded through the sign of 1254@math{m}, but should be tested for and set using dedicated functions. 1255 1256Unless indicated otherwise, the following functions 1257assume radius arguments to be normalised, 1258they return normalised results, and they round their results up, not 1259necessarily to the smallest representable number, although reasonable 1260effort is made to get a tight upper bound: They only guarantee that 1261their outputs are an upper bound on the true results. 1262(There may be a trade-off between tightness of the result and speed of 1263computation. For instance, when a 32-bit mantissa is normalised, an even 1264mantissa should be divided by 2, an odd mantissa should be divided by 2 1265and 1 should be added, and then in both cases the exponent must be 1266increased by 1. It might be more efficient to add 1 all the time instead 1267of testing the last bit of the mantissa.) 1268 1269@deftypefun int mpcr_inf_p (mpcr_srcptr @var{r}) 1270@deftypefunx int mpcr_zero_p (mpcr_srcptr @var{r}) 1271Test whether @var{r} is infinity or zero, respectively, and return a 1272boolean. 1273@end deftypefun 1274 1275 1276@deftypefun int mpcr_lt_half_p (mpcr_srcptr @var{r}) 1277Return @code{true} if @var{r}<1/2, and @code{false} otherwise. 1278(Everywhere in this document, 1279@code{true} means any non-zero value, and @code{false} means zero.) 1280@end deftypefun 1281 1282 1283@deftypefun int mpcr_cmp (mpcr_srcptr @var{r}, mpcr_srcptr @var{s}) 1284Return +1, 0 or -1 depending on whether @var{r} is larger than, equal to 1285or less than @var{s}, with the natural total order on the compactified 1286non-negative real axis letting 0 be smaller and letting infinity be larger 1287than any finite real number. 1288@end deftypefun 1289 1290 1291@deftypefun void mpcr_set_inf (mpcr_ptr @var{r}) 1292@deftypefunx void mpcr_set_zero (mpcr_ptr @var{r}) 1293@deftypefunx void mpcr_set_one (mpcr_ptr @var{r}) 1294@deftypefunx void mpcr_set (mpcr_ptr @var{r}, mpcr_srcptr @var{s}) 1295@deftypefunx void mpcr_set_ui64_2si64 (mpcr_ptr @var{r}, uint64_t @var{mant}, int64_t @var{exp}) 1296Set @var{r} to infinity, zero, 1, @var{s} or 1297@var{mant}���2@sup{@var{exp}}, respectively. 1298@end deftypefun 1299 1300 1301@deftypefun void mpcr_max (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, mpcr_srcptr @var{t}) 1302Set @var{r} to the maximum of @var{s} and @var{t}. 1303@end deftypefun 1304 1305 1306@deftypefun int64_t mpcr_get_exp (mpcr_srcptr @var{r}) 1307Assuming that @var{r} is neither infinity nor 0, return its exponent 1308@math{e} when writing @math{r = m���2@sup{e}} with 1309@math {1/2 ��� m < 1}. (Notice that this is @emph{not} the same as the 1310field @code{exp} in the struct representing a radius, but that instead it 1311is independent of the implementation.) 1312Otherwise the behaviour is undefined. 1313@end deftypefun 1314 1315 1316@deftypefun void mpcr_out_str (FILE *@var{f}, mpcr_srcptr @var{r}) 1317Output @var{r} on @var{f}, which may be @code{stdout}. 1318Caveat: This function so far serves mainly for debugging purposes, its 1319behaviour will probably change in the future. 1320@end deftypefun 1321 1322 1323@deftypefun void mpcr_add (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, mpcr_srcptr @var{t}) 1324@deftypefunx void mpcr_sub (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, mpcr_srcptr @var{t}) 1325@deftypefunx void mpcr_mul (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, mpcr_srcptr @var{t}) 1326@deftypefunx void mpcr_div (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, mpcr_srcptr @var{t}) 1327@deftypefunx void mpcr_mul_2ui (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, unsigned long int @var{t}) 1328@deftypefunx void mpcr_div_2ui (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, unsigned long int @var{t}) 1329@deftypefunx void mpcr_sqr (mpcr_ptr @var{r}, mpcr_srcptr @var{s}) 1330@deftypefunx void mpcr_sqrt (mpcr_ptr @var{r}, mpcr_srcptr @var{s}) 1331Set @var{r} to the sum, difference, product or quotient of @var{s} and 1332@var{t}, or to the product of @var{s} by 2@sup{@var{t}} or to the 1333quotient of @var{s} by 2@sup{@var{t}}, 1334or to the square or the square root of @var{s}. 1335If any of the arguments is infinity, or if a difference is negative, 1336the result is infinity. 1337@end deftypefun 1338 1339 1340@deftypefun void mpcr_sub_rnd (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, mpcr_srcptr @var{t}, mpfr_rnd_t @var{rnd}) 1341Set @var{r} to the difference of @var{s} and @var{t}, rounded into 1342direction @var{rnd}, which can be one of @code{MPFR_RNDU} or 1343@code{MPFR_RNDD}. If one of the arguments is infinity or the difference is 1344negative, the result is infinity. Calling the function with @code{MPFR_RNDU} 1345is equivalent to calling @code{mpcr_sub}. 1346 1347This is one out of several functions taking a rounding parameter. Rounding 1348down may be useful to obtain an upper bound when dividing by the result. 1349@end deftypefun 1350 1351 1352@deftypefun void mpcr_c_abs_rnd (mpcr_ptr @var{r}, mpc_srcptr @var{z}, mpfr_rnd_t @var{rnd}) 1353Set @var{r} to the absolute value of the complex number @var{z}, rounded 1354in direction @var{rnd}, which may be one of @code{MPFR_RNDU} or 1355@code{MPFR_RNDD}. 1356@end deftypefun 1357 1358 1359@deftypefun void mpcr_add_rounding_error (mpcr_ptr @var{r}, mpfr_prec_t @var{p}, mpfr_rnd_t @var{rnd}) 1360Set @var{r} to @math{r + (1 + r) 2@sup{-p}} if @var{rnd} equals 1361@code{MPFR_RNDN}, and to @math{r + (1 + r) 2@sup{1-p}} otherwise. 1362The idea is that if a (potentially not representable) centre of an ideal 1363complex ball of radius @var{r} is rounded to a representable complex 1364number at precision @var{p}, this shifts the centre by up to 1/2 ulp 1365(for rounding to nearest) or 1 ulp (for directed rounding of at least one 1366of the real or imaginary parts), which increases the radius accordingly. 1367So this function is typically called internally at the end of each 1368operation with complex balls to account for the error made by rounding 1369the centre. 1370@end deftypefun 1371 1372 1373@section Ball type and functions 1374@tindex mpcb_t 1375@tindex mpcb_ptr 1376@tindex mpcb_srcptr 1377 1378The ball type is defined by 1379@verbatim 1380typedef struct { 1381 mpc_t c; 1382 mpcr_t r; 1383} 1384@end verbatim 1385or, more precisely, @code{mpcb_t} is again a 1-dimensional array of such 1386a struct, and variable and constant pointer types are defined as 1387@code{mpcb_ptr} and @code{mpcb_srcptr}, respectively. 1388As usual, the components should only be accessed through corresponding 1389functions. 1390 1391To understand functions on balls, one needs to consider the balls passed 1392as arguments as sets of complex values, to which a mathematical function 1393is applied; the C function ``rounds up'' in the sense that it returns a 1394ball containing all possible values of the function in all the possible 1395input values. Reasonable effort is made to return small balls, but again 1396there is no guarantee that the result is the smallest possible one. 1397In the current implementation, the centre of a ball returned as a value 1398is obtained by applying the function to the centres of the balls passed 1399as arguments, and rounding. While this is a natural approach, it is not 1400the only possible one; however, it also simplifies the error analysis 1401as already carried out for functions with regular complex arguments. 1402Whenever the centre of a complex ball has a non-finite real or imaginary 1403part (positive or negative infinity or NaN) the radius is set to infinity; 1404this can be interpreted as the ``useless ball'', representing the whole 1405complex plane, whatever the value of the centre is. 1406 1407Unlike for variables of @code{mpc_t} type, where the precision needs to 1408be set explicitly at initialisation, variables of type @code{mpcb_t} 1409handle their precision dynamically. Ball centres always have the same 1410precision for their real and their imaginary parts (again this is a 1411choice of the implementation; if they are of very different sizes, one 1412could theoretically reduce the precision of the part that is smaller 1413in absolute value, which is more strongly affected by the common error 1414coded in the radius). 1415When setting a complex ball from a value of a different type, an 1416additional precision parameter is passed, which determines the precision 1417of the centre. Functions on complex balls set the precision of their 1418result depending on the input. In the current implementation, this is the 1419minimum of the argument precisions, so if all balls are initially set to 1420the same precision, this is preserved throughout the computations. 1421(Notice that the exponent of the radius encodes roughly the number of 1422correct binary digits of the ball centre; so it would also make sense 1423to reduce the precision if the radius becomes larger.) 1424 1425The following functions on complex balls are currently available; the 1426eclectic collection is motivated by the desire to provide an implementation 1427of the arithmetic-geometric mean of complex numbers through the use of 1428ball arithmetic. As for functions taking complex arguments, there may 1429be arbitrary overlaps between variables representing arguments and 1430results; for instance 1431@code{mpcb_mul (z, z, z)} is an allowed way of replacing the ball @var{z} 1432by its square. 1433 1434 1435@deftypefun void mpcb_init (mpcb_ptr @var{z}) 1436@deftypefunx void mpcb_clear (mpcb_ptr @var{z}) 1437Initialise or free memory for @var{z}; @code{mpcb_init} must be called once 1438before using a variable, and @code{mpcb_clear} must be called once before 1439stopping to use a variable. Unlike its @code{mpc_t} counterpart, 1440@code{mpcb_init} does not fix the precision of @var{z}, but it sets its 1441radius to infinity, so that @var{z} represents the whole complex plane. 1442@end deftypefun 1443 1444 1445@deftypefun mpfr_prec_t mpcb_get_prec (mpcb_srcptr @var{z}) 1446Return the (common) precision of the real and the complex parts of the 1447centre of @var{z}. 1448@end deftypefun 1449 1450 1451@deftypefun void mpcb_set (mpcb_ptr @var{z}, mpcb_srcptr @var{z1}) 1452Set @var{z} to @var{z1}, preserving the precision of the centre. 1453@end deftypefun 1454 1455 1456@deftypefun void mpcb_set_inf (mpcb_ptr @var{z}) 1457Set @var{z} to the whole complex plane. This is intended to be used much 1458in the spirit of an assertion: When a precondition is not satisfied inside 1459a function, it can set its result to this value, which will propagate 1460through further computations. 1461@end deftypefun 1462 1463 1464@deftypefun void mpcb_set_c (mpcb_ptr @var{z}, mpc_srcptr @var{c}, mpfr_prec_t @var{prec}, unsigned long int @var{err_re}, unsigned long int @var {err_im}) 1465Set @var{z} to a ball with centre @var{c} at precision @var{prec}. 1466If @var{prec} is at least the maximum of the precisions of the real and the 1467imaginary parts of @var{c} and @var{err_re} and @var{err_im} are 0, then 1468the resulting ball is exact with radius zero. Using a larger value for 1469@var{prec} makes sense if @var{c} is considered exact and a larger target 1470precision for the result is desired, or some leeway for the working 1471precision is to be taken into account. 1472If @var{prec} is less than the precision of @var{c}, then usually some 1473rounding error occurs when setting the centre, which is taken into account 1474in the radius. 1475 1476If @var{err_re} and @var{err_im} are non-zero, the argument @var{c} is 1477considered as an inexact complex number, with a bound on the absolute error 1478of its real part given in @var{err_re} as a multiple of 1/2 ulp of the real 1479part of @var{c}, and a bound on the absolute error of its imaginary part 1480given in @var{err_im} as a multiple of 1/2 ulp of the imaginary part of 1481@var{c}. (Notice that if the parts of @var{c} have different precisions or 1482exponents, the absolute values of their ulp differ.) 1483Then @var{z} is created as a ball with centre @var{c} and a radius taking 1484these errors on @var{c} as well as the potential additional rounding error 1485for the centre into account. 1486If the real part of @var{c} is 0, then @var{err_re} must be 0, since 1487ulp of 0 makes no sense; otherwise the radius is set to infinity. The same 1488remark holds for the imaginary part. 1489 1490Using @var{err_re} and @var{err_im} different from 0 is particularly 1491useful in two settings: If @var{c} is itself the result of a call to an 1492@code{mpc_} function with exact input and rounding mode @code{MPC_RNDNN} 1493of both parts to nearest, then its parts are known with errors of at most 14941/2 ulp, and setting @var{err_re} and @var{err_im} to 1 yields a ball 1495which is known to contain the exact result (this motivates the strange 1496unit of 1/2 ulp); if directed rounding was used, @var{err_re} and 1497@var{err_im} can be set to 2 instead. 1498 1499And if @var{c} is the result of a sequence of calls to @code{mpc_} 1500functions for which some error analysis has been carried out (as is 1501frequently the case internally when implementing complex functions), 1502again the resulting ball @var{z} is known to contain the exact result 1503when using appropriate values for @var{err_re} and @var{err_im}. 1504@end deftypefun 1505 1506 1507@deftypefun void mpcb_set_ui_ui (mpcb_ptr @var{z}, unsigned long int @var{re}, unsigned long int @var {im}, mpfr_prec_t @var{prec}) 1508Set @var{z} to a ball with centre @var{re}+I*@var{im} at precision 1509@var{prec} or the size of an @code{unsigned long int}, whatever is larger. 1510@end deftypefun 1511 1512 1513@deftypefun void mpcb_neg (mpcb_ptr @var{z}, mpcb_srcptr @var{z1}) 1514@deftypefunx void mpcb_add (mpcb_ptr @var{z}, mpcb_srcptr @var{z1}, mpcb_srcptr @var{z2}) 1515@deftypefunx void mpcb_mul (mpcb_ptr @var{z}, mpcb_srcptr @var{z1}, mpcb_srcptr @var{z2}) 1516@deftypefunx void mpcb_sqr (mpcb_ptr @var{z}, mpcb_srcptr @var{z1}) 1517@deftypefunx void mpcb_pow_ui (mpcb_ptr @var{z}, mpcb_srcptr @var{z1}, unsigned long int @var{e}) 1518@deftypefunx void mpcb_sqrt (mpcb_ptr @var{z}, mpcb_srcptr @var{z1}) 1519@deftypefunx void mpcb_div (mpcb_ptr @var{z}, mpcb_srcptr @var{z1}, mpcb_srcptr @var{z2}) 1520@deftypefunx void mpcb_div_2ui (mpcb_ptr @var{z}, mpcb_srcptr @var{z1}, unsigned long int @var{e}) 1521These are the exact counterparts of the corresponding functions 1522@code{mpc_neg}, @code{mpc_add} and so on, but on complex balls instead of 1523complex numbers. 1524@end deftypefun 1525 1526 1527@deftypefun int mpcb_can_round (mpcb_srcptr @var{z}, mpfr_prec_t @var{prec_re}, mpfr_prec_t @var{prec_im}, mpc_rnd_t @var{rnd}) 1528If the function returns @code{true} (a non-zero number), then rounding 1529any of the complex numbers in the ball to a complex number with precision 1530@var{prec_re} of its real and precision @var{prec_im} of its imaginary 1531part and rounding mode @var{rnd} yields the same result and rounding 1532direction value, cf. @ref{return-value}. 1533If the function returns @code{false} (that is, 0), then it could not 1534conclude, or there are two numbers in the ball which would be rounded to 1535a different complex number or in a different direction. Notice that the 1536function works in a best effort mode and errs on the side of caution by 1537potentially returning @code{false} on a roundable ball; this is consistent 1538with computational functions not necessarily returning the smallest 1539enclosing ball. 1540 1541If @var{z} contains the result of evaluating some mathematical function 1542through a sequence of calls to @code{mpcb} functions, starting with exact 1543complex numbers, that is, balls of radius 0, then a return value of 1544@code{true} indicates that rounding any value in the ball (its centre is 1545readily available) in direction @var{rnd} yields the correct result of 1546the function and the correct rounding direction value with the usual 1547MPC semantics. 1548 1549Notice that when the precision of @var{z} is larger than @var{prec_re} 1550or @var{prec_im}, the centre need not be representable at the desired 1551precision, and in fact the ball need not contain a representable number 1552at all to be ``roundable''. Even worse, when @var{rnd} is a directed 1553rounding mode for the real or the imaginary part and the ball of 1554non-zero radius contains 1555a representable number, the return value is necessarily @code{false}. 1556Even worse, when the rounding mode for one part is to nearest, the 1557corresponding part of the centre of the ball is representable and the ball 1558has a non-zero radius, then the return value is also necessarily 1559@code{false}, since even if rounding may be possible, the rounding 1560direction value cannot be determined. 1561@end deftypefun 1562 1563 1564@deftypefun int mpcb_round (mpc_ptr @var{c}, mpcb_srcptr @var{z}, mpc_rnd_t @var{rnd}) 1565Set @var{c} to the centre of @var{z}, rounded in direction @var{rnd}, 1566and return the corresponding rounding direction value. 1567If @code{mpcb_can_round}, called with @var {z}, the precisions of @var{c} 1568and the rounding mode @var{rnd} returns @code{true}, then this function 1569does what is expected, it ``correctly rounds the ball'' and returns a 1570rounding direction value that is valid for all of the ball. 1571As explained above, the result is then not necessarily (in the presence of 1572directed rounding with radius different from 0, it is rather 1573necessarily not) an element of the ball. 1574@end deftypefun 1575 1576 1577 1578@node References 1579@unnumbered References 1580 1581@itemize @bullet 1582 1583@item 1584Torbj@"orn Granlund et al. 1585@code{GMP} -- GNU multiprecision library. 1586Version 6.2.0, @url{http://gmplib.org}. 1587 1588@item 1589Guillaume Hanrot, Vincent Lef@`evre, Patrick P@'elissier, Paul Zimmermann et al. 1590@code{MPFR} -- A library for multiple-precision floating-point computations with exact rounding. 1591Version 4.1.0, @url{http://www.mpfr.org}. 1592 1593@item 1594IEEE Standard for Floating-Point Arithmetic, 1595IEEE Computer Society, 1596IEEE Std 754-2019, Approved 13 June 2019, 84 pages. 1597 1598@item 1599Donald E. Knuth, "The Art of Computer Programming", vol 2, 1600"Seminumerical Algorithms", 2nd edition, Addison-Wesley, 1981. 1601 1602@item 1603ISO/IEC 9899:1999, Programming languages ��� C. 1604 1605@end itemize 1606 1607@node Concept Index 1608@unnumbered Concept Index 1609@printindex cp 1610 1611@node Function Index 1612@unnumbered Function Index 1613@printindex fn 1614 1615@node Type Index 1616@unnumbered Type Index 1617@printindex tp 1618 1619@node GNU Free Documentation License 1620@appendix GNU Free Documentation License 1621@include fdl-1.3.texi 1622 1623@ifnothtml 1624@contents 1625@end ifnothtml 1626 1627@bye 1628