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