dist/doc/mpc.texi

\input texinfo
@setfilename mpc.info
@include version.texi
@settitle GNU MPC @value{VERSION}

@set MINGMP 5.0.0
@set MINMPFR 4.1.0

@set AUTHORS Andreas Enge, Philippe Th@'eveny, Paul Zimmermann

@copying
This manual is for GNU MPC, a library for multiple precision complex arithmetic,
version @value{VERSION} of @value{UPDATED-MONTH}.

Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2016, 2018, 2020, 2022 INRIA

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections. A copy of the license is included in the section
entitled ``GNU Free Documentation License.''
@end quotation
@end copying

@iftex
@afourpaper
@end iftex
@tex
\global\parindent=0pt
\global\parskip=8pt
\global\baselineskip=13pt
@end tex

@dircategory GNU Packages
@direntry
* mpc: (mpc)Multiple Precision Complex Library.
@end direntry


@titlepage
@title GNU MPC
@subtitle The GNU Multiple Precision Complex Library
@subtitle Edition @value{VERSION}
@subtitle @value{UPDATED-MONTH}
@author @value{AUTHORS}
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage


@ifnottex
@node Top
@top GNU MPC

This manual documents how to install and use the GNU Multiple Precision
Complex Library, version @value{VERSION}
@end ifnottex

@menu
* Copying::                     GNU MPC Copying Conditions (LGPL).
* Introduction to GNU MPC::     Brief introduction to GNU MPC.
* Installing GNU MPC::          How to configure and compile the GNU MPC library.
* Reporting Bugs::              How to usefully report bugs.
* GNU MPC Basics::              What every GNU MPC user should know.
* Complex Functions::           Functions for arithmetic on complex numbers.
* Ball Arithmetic::             Types and functions for complex balls.
* References::
* Concept Index::
* Function Index::
* Type Index::
* GNU Free Documentation License::
@end menu

@c  @times{} made available as a "x" in info and html (already works in tex).
@ifnottex
@macro times
x
@end macro
@end ifnottex

@c  @m{T,N} is $T$ in tex or @math{N} otherwise.  This is an easy way to give
@c  different forms for math in tex and info.  Commas in N or T don't work,
@c  but @C{} can be used instead.  \, works in info but not in tex.
@c  (copied from mpfr.texi)
@iftex
@macro m {T,N}
@tex$\T\$@end tex
@end macro
@end iftex
@ifnottex
@macro m {T,N}
@math{\N\}
@end macro
@end ifnottex

@node Copying
@unnumbered GNU MPC Copying Conditions
@cindex Copying conditions
@cindex Conditions for copying GNU MPC

GNU MPC is free software; you can redistribute it and/or modify it under
the terms of the GNU Lesser General Public License as published by the
Free Software Foundation; either version 3 of the License, or (at your
option) any later version.

GNU MPC is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
more details.

You should have received a copy of the GNU Lesser General Public License
along with this program. If not, see @uref{http://www.gnu.org/licenses/}.


@node Introduction to GNU MPC
@chapter Introduction to GNU MPC


GNU MPC is a portable library written in C for arbitrary precision arithmetic
on complex numbers providing correct rounding. It implements a multiprecision
equivalent of the C99 standard.
It builds upon the GNU MP and the GNU MPFR libraries.

@section How to use this Manual

Everyone should read @ref{GNU MPC Basics}.  If you need to install the library
yourself, you need to read @ref{Installing GNU MPC}, too.

The remainder of the manual can be used for later reference, although it is
probably a good idea to skim through it.

@node Installing GNU MPC
@chapter Installing GNU MPC
@cindex Installation

To build GNU MPC, you first have to install GNU MP (version @value{MINGMP} or higher) and
GNU MPFR (version @value{MINMPFR} or higher) on your computer.  You need a C compiler;
GCC version 4.4 or higher is recommended, since GNU MPC may trigger a bug in previous
versions, see the thread at
@uref{https://sympa.inria.fr/sympa/arc/mpc-discuss/2011-02/msg00024.html}.
And you need a
standard Unix @samp{make} program, plus some other standard Unix utility
programs.

Here are the steps needed to install the library on Unix systems:

@enumerate
@item
@samp{tar xzf mpc-@value{VERSION}.tar.gz}

@item
@samp{cd mpc-@value{VERSION}}

@item
@samp{./configure}

if GMP and GNU MPFR are installed into standard directories, that is, directories
that are searched by default by the compiler and the linking tools.

@samp{./configure --with-gmp=<gmp_install_dir>}

is used to indicate a different location where GMP is
installed. Alternatively, you can specify directly GMP include and GMP lib
directories with @samp{./configure --with-gmp-lib=<gmp_lib_dir>
--with-gmp-include=<gmp_include_dir>}.

@samp{./configure --with-mpfr=<mpfr_install_dir>}

is used to indicate a different location where GNU MPFR is
installed. Alternatively, you can specify directly GNU MPFR include and GNU MPFR lib
directories with @samp{./configure --with-mpf-lib=<mpfr_lib_dir>
--with-mpfr-include=<mpfr_include_dir>}.

Another useful parameter is @samp{--prefix}, which can be used to
specify an alternative installation location instead of
@file{/usr/local}; see @samp{make install} below.

To enable checking for memory leaks using @command{valgrind} during
@code{make check}, add the parameter @code{--enable-valgrind-tests}.

If for debugging purposes you wish to log calls to GNU MPC functions from
within your code, add the parameter @samp{--enable-logging}.
In your code, replace the inclusion of @file{mpc.h} by @file{mpc-log.h}
and link the executable dynamically.
Then all calls to functions with only complex arguments are printed to
@file{stderr} in the following form: First, the function name is given,
followed by its type such as @samp{c_cc}, meaning that the function has
one complex result (one @samp{c} in front of the @samp{_}), computed from
two complex arguments (two @samp{c} after the @samp{_}). Then, the
precisions of the real and the imaginary part of the first result is given,
followed by the second one and so on. Finally, for each argument, the
precisions of its real and imaginary part are specified and the argument
itself is printed in hexadecimal via the function
@code{mpc_out_str}
(@pxref{String and Stream Input and Output}).
The option requires a dynamic library, so it may not be combined with
@code{--disable-shared}.

Use @samp{./configure --help} for an exhaustive list of parameters.

@item
@samp{make}

This compiles GNU MPC in the working directory.

@item
@samp{make check}

This will make sure GNU MPC was built correctly.

If you get error messages, please report them to
@samp{mpc-discuss@@inria.fr} (@xref{Reporting Bugs}, for
information on what to include in useful bug reports).

@item
@samp{make install}

This will copy the file @file{mpc.h} to the directory
@file{/usr/local/include}, the file @file{libmpc.a} to the directory
@file{/usr/local/lib}, and the file @file{mpc.info} to the directory
@file{/usr/local/share/info} (or if you passed the @samp{--prefix} option to
@file{configure}, using the prefix directory given as argument to
@samp{--prefix} instead of @file{/usr/local}). Note: you need write permissions
on these directories.

@end enumerate


@section Other `make' Targets

There are some other useful make targets:

@itemize @bullet
@item
@samp{info}

Create an info version of the manual, in @file{mpc.info}.

@item
@samp{pdf}

Create a PDF version of the manual, in @file{doc/mpc.pdf}.

@item
@samp{dvi}

Create a DVI version of the manual, in @file{doc/mpc.dvi}.

@item
@samp{ps}

Create a Postscript version of the manual, in @file{doc/mpc.ps}.

@item
@samp{html}

Create an HTML version of the manual, in several pages in the
directory @file{doc/mpc.html}; if you want only one output HTML file,
then type @samp{makeinfo --html --no-split mpc.texi} instead.

@item
@samp{clean}

Delete all object files and archive files, but not the configuration files.

@item
@samp{distclean}

Delete all files not included in the distribution.

@item
@samp{uninstall}

Delete all files copied by @samp{make install}.
@end itemize


@section Known Build Problems

On AIX, if GMP was built with the 64-bit ABI, before building and testing GNU MPC,
it might be necessary to set the @samp{OBJECT_MODE} environment variable to 64
by, e.g.,

@samp{export OBJECT_MODE=64}

This has been tested with the C compiler IBM XL C/C++ Enterprise Edition
V8.0 for AIX, version: 08.00.0000.0021, GMP 4.2.4 and GNU MPFR 2.4.1.

Please report any other problems you encounter to
@samp{mpc-discuss@@inria.fr}.
@xref{Reporting Bugs}.

@node Reporting Bugs
@chapter Reporting Bugs
@cindex Reporting bugs

If you think you have found a bug in the GNU MPC library,
please investigate
and report it. We have made this library available to you, and it is not to ask
too much from you, to ask you to report the bugs that you find.

There are a few things you should think about when you put your bug report
together.

You have to send us a test case that makes it possible for us to reproduce the
bug.  Include instructions on how to run the test case.

You also have to explain what is wrong; if you get a crash, or if the results
printed are incorrect and in that case, in what way.

Please include compiler version information in your bug report.
This can be extracted using @samp{gcc -v},
or @samp{cc -V} on some machines.
Also, include the output from @samp{uname -a}.

If your bug report is good, we will do our best to help you to get a corrected
version of the library; if the bug report is poor, we will not do anything about
it (aside of chiding you to send better bug reports).

Send your bug report to: @samp{mpc-discuss@@inria.fr}.

If you think something in this manual is unclear, or downright incorrect, or if
the language needs to be improved, please send a note to the same address.

@node GNU MPC Basics
@chapter GNU MPC Basics


@cindex @file{mpc.h}
All declarations needed to use GNU MPC are collected in the include file
@file{mpc.h}.  It is designed to work with both C and C++ compilers.
You should include that file in any program using the GNU MPC library
by adding the line
@example
   #include "mpc.h"
@end example

@section Nomenclature and Types

@cindex Complex number
@tindex mpc_t
@tindex mpc_ptr
@tindex mpc_srcptr
@noindent
@dfn{Complex number} or @dfn{Complex} for short, is a pair of two
arbitrary precision floating-point numbers (for the real and imaginary parts).
The C data type for such objects is @code{mpc_t}.

@cindex Precision
@tindex mpfr_prec_t
@noindent
The @dfn{Precision} is the number of bits used to represent the mantissa
of the real and imaginary parts;
the corresponding C data type is @code{mpfr_prec_t}.
For more details on the allowed precision range,
@ifinfo
@pxref{Nomenclature and Types,,, mpfr.info,GNU MPFR}.
@end ifinfo
@ifnotinfo
see Section ``Nomenclature and Types'' in @cite{GNU MPFR}.
@end ifnotinfo

@cindex Rounding Mode
@tindex mpc_rnd_t
@noindent
The @dfn{rounding mode} specifies the way to round the result of a
complex operation, in case the exact result can not be represented
exactly in the destination mantissa;
the corresponding C data type is @code{mpc_rnd_t}.
A complex rounding mode is a pair of two rounding modes: one for the real
part, one for the imaginary part.

@section Function Classes

There is only one class of functions in the GNU MPC library, namely functions for
complex arithmetic. The function names begin with @code{mpc_}. The
associated type is @code{mpc_t}.


@section GNU MPC Variable Conventions

As a general rule, all GNU MPC functions expect output arguments before input
arguments.  This notation is based on an analogy with the assignment operator.

GNU MPC allows you to use the same variable for both input and output in the same
expression.  For example, the main function for floating-point multiplication,
@code{mpc_mul}, can be used like this: @code{mpc_mul (x, x, x, rnd_mode)}.
This
computes the square of @var{x} with rounding mode @code{rnd_mode}
and puts the result back in @var{x}.

Before you can assign to an GNU MPC variable, you need to initialise it by calling
one of the special initialization functions.  When you are done with a
variable, you need to clear it out, using one of the functions for that
purpose.

A variable should only be initialised once, or at least cleared out between
each initialization.  After a variable has been initialised, it may be
assigned to any number of times.

For efficiency reasons, avoid to initialise and clear out a variable in loops.
Instead, initialise it before entering the loop, and clear it out after the
loop has exited.

You do not need to be concerned about allocating additional space for GNU MPC
variables, since each of its real and imaginary part
has a mantissa of fixed size.
Hence unless you change its precision, or clear and reinitialise it,
a complex variable will have the same allocated space during all its
life.


@section Rounding Modes

A complex rounding mode is of the form @code{MPC_RNDxy} where
@code{x} and @code{y} are one of @code{N} (to nearest), @code{Z} (towards
zero), @code{U} (towards plus infinity), @code{D} (towards minus infinity),
@code{A} (away from zero, that is, towards plus or minus infinity depending
on the sign of the number to be rounded).
The first letter refers to the rounding mode for the real part,
and the second one for the imaginary part.
For example @code{MPC_RNDZU} indicates to round the real part towards zero,
and the imaginary part towards plus infinity.

The @samp{round to nearest} mode works as in the IEEE P754 standard: in case
the number to be rounded lies exactly in the middle of two representable
numbers, it is rounded to the one with the least significant bit set to zero.
For example, the number 5, which is represented by (101) in binary, is rounded
to (100)=4 with a precision of two bits, and not to (110)=6.


@anchor{return-value}
@section Return Value

Most GNU MPC functions have a return value of type @code{int}, which is used
to indicate the position of the rounded real and imaginary parts with respect
to the exact (infinite precision) values.
If this integer is @code{i}, the macros @code{MPC_INEX_RE(i)} and
@code{MPC_INEX_IM(i)} give 0 if the corresponding rounded value is exact,
a negative value if the rounded value is less than the exact one,
and a positive value if it is greater than the exact one.
Similarly, functions computing a result of type @code{mpfr_t}
return an integer that is 0, positive or negative depending on
whether the rounded value is the same, larger or smaller then
the exact result.

Some functions, such as @code{mpc_sin_cos}, compute two complex results;
the macros @code{MPC_INEX1(i)} and @code{MPC_INEX2(i)}, applied to
the return value @code{i} of such a function, yield the exactness value
corresponding to the first or the second computed value, respectively.


@section Branch Cuts And Special Values

Some complex functions have branch cuts, across which the function is
discontinous. In GNU MPC, the branch cuts chosen are the same as those
specified for the corresponding functions in the ISO C99 standard.

Likewise, when evaluated at a point whose real or imaginary part is
either infinite or a NaN or a signed zero, a function returns the same
value as those specified for the corresponding function in the ISO C99
standard.


@node Complex Functions
@chapter Complex Functions
@cindex Complex functions

The complex functions expect arguments of type @code{mpc_t}.

The GNU MPC floating-point functions have an interface that is similar to the
GNU MP
integer functions.  The function prefix for operations on complex numbers is
@code{mpc_}.

@cindex User-defined precision
The precision of a computation is defined as follows: Compute the requested
operation exactly (with ``infinite precision''), and round the result to
the destination variable precision with the given rounding mode.

The GNU MPC complex functions are intended to be a smooth extension
of the IEEE P754 arithmetic. The results obtained on one
computer should not differ from the results obtained on a computer with a
different word size.


@menu
* Initializing Complex Numbers::
* Assigning Complex Numbers::
* Converting Complex Numbers::
* String and Stream Input and Output::
* Complex Comparison::
* Projection & Decomposing::
* Basic Arithmetic::
* Power Functions and Logarithm::
* Trigonometric Functions::
* Modular Functions::
* Miscellaneous Complex Functions::
* Advanced Functions::
* Internals::
@end menu

@node Initializing Complex Numbers
@section Initialization Functions

An @code{mpc_t} object must be initialised before storing the first value in
it.  The functions @code{mpc_init2} and @code{mpc_init3}
are used for that purpose.

@deftypefun void mpc_init2 (mpc_t @var{z}, mpfr_prec_t @var{prec})
Initialise @var{z} to precision @var{prec} bits
and set its real and imaginary parts to NaN.
Normally, a variable should be initialised once only
or at least be cleared, using @code{mpc_clear}, between initializations.
@end deftypefun

@deftypefun void mpc_init3 (mpc_t @var{z}, mpfr_prec_t @var{prec_r}, mpfr_prec_t @var{prec_i})
Initialise @var{z} with the precision of its real part being
@var{prec_r} bits and the precision of its imaginary part being
@var{prec_i} bits, and set the real and imaginary parts to NaN.
@end deftypefun

@deftypefun void mpc_clear (mpc_t @var{z})
Free the space occupied by @var{z}.  Make sure to call this function for all
@code{mpc_t} variables when you are done with them.
@end deftypefun

@need 2000
Here is an example on how to initialise complex variables:
@example
@{
  mpc_t x, y;
  mpc_init2 (x, 256);		/* precision @emph{exactly} 256 bits */
  mpc_init3 (y, 100, 50);	/* 100/50 bits for the real/imaginary part */
  @dots{}
  mpc_clear (x);
  mpc_clear (y);
@}
@end example

The following function is useful for changing the precision during a
calculation.  A typical use would be for adjusting the precision gradually in
iterative algorithms like Newton-Raphson, making the computation precision
closely match the actual accurate part of the numbers.

@deftypefun void mpc_set_prec (mpc_t @var{x}, mpfr_prec_t @var{prec})
Reset the precision of @var{x} to be @strong{exactly} @var{prec} bits,
and set its real/imaginary parts to NaN.
The previous value stored in @var{x} is lost. It is equivalent to
a call to @code{mpc_clear(x)} followed by a call to
@code{mpc_init2(x, prec)}, but more efficient as no allocation is done in
case the current allocated space for the mantissa of @var{x} is sufficient.
@end deftypefun

@deftypefun mpfr_prec_t mpc_get_prec (const mpc_t @var{x})
If the real and imaginary part of @var{x} have the same precision, it is returned,
otherwise, 0 is returned.
@end deftypefun

@deftypefun void mpc_get_prec2 (mpfr_prec_t* @var{pr}, mpfr_prec_t* @var{pi}, const mpc_t @var{x})
Returns the precision of the real part of @var{x} via @var{pr} and of its imaginary part
via @var{pi}.
@end deftypefun


@node Assigning Complex Numbers
@section Assignment Functions
@cindex Complex assignment functions

These functions assign new values to already initialised complex numbers
(@pxref{Initializing Complex Numbers}).
When using any functions with @code{intmax_t} or @code{uintmax_t}
parameters, you must include
@code{<stdint.h>} or @code{<inttypes.h>} @emph{before} @file{mpc.h}, to allow
@file{mpc.h} to define prototypes for these functions.
Similarly, functions with parameters of type @code{complex} or
@code{long complex} are defined only if @code{<complex.h>} is included
@emph{before} @file{mpc.h}.
If you need assignment functions that are not in the current API, you can
define them using the @code{MPC_SET_X_Y} macro (@pxref{Advanced Functions}).

@deftypefun int mpc_set (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
Set the value of @var{rop} from @var{op}, rounded to the precision of @var{rop}
with the given rounding mode @var{rnd}.
@end deftypefun

@deftypefun int mpc_set_ui (mpc_t @var{rop}, unsigned long int @var{op}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_set_si (mpc_t @var{rop}, long int @var{op}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_set_uj (mpc_t @var{rop}, uintmax_t @var{op}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_set_sj (mpc_t @var{rop}, intmax_t @var{op}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_set_d (mpc_t @var{rop}, double @var{op}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_set_ld (mpc_t @var{rop}, long double @var{op}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_set_dc (mpc_t @var{rop}, double _Complex @var{op}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_set_ldc (mpc_t @var{rop}, long double _Complex @var{op}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_set_z (mpc_t @var{rop}, const mpz_t @var{op} mpc_rnd_t @var{rnd})
@deftypefunx int mpc_set_q (mpc_t @var{rop}, const mpq_t @var{op} mpc_rnd_t @var{rnd})
@deftypefunx int mpc_set_f (mpc_t @var{rop}, const mpf_t @var{op} mpc_rnd_t @var{rnd})
@deftypefunx int mpc_set_fr (mpc_t @var{rop}, const mpfr_t @var{op}, mpc_rnd_t @var{rnd})
Set the value of @var{rop} from @var{op}, rounded to the precision of
@var{rop} with the given rounding mode @var{rnd}.
The argument @var{op} is interpreted as real, so the imaginary part of
@var{rop} is set to zero with a positive sign.
Please note that even a @code{long int} may have to be rounded, if the
destination precision is less than the machine word width.
For @code{mpc_set_d}, be careful that the input number @var{op} may not be
exactly representable as a double-precision number (this happens for 0.1 for
instance), in which case it is first rounded by the C compiler to a
double-precision number, and then only to a complex number.
@end deftypefun

@deftypefun int mpc_set_ui_ui (mpc_t @var{rop}, unsigned long int @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_set_si_si (mpc_t @var{rop}, long int @var{op1}, long int @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_set_uj_uj (mpc_t @var{rop}, uintmax_t @var{op1}, uintmax_t @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_set_sj_sj (mpc_t @var{rop}, intmax_t @var{op1}, intmax_t @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_set_d_d (mpc_t @var{rop}, double @var{op1}, double @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_set_ld_ld (mpc_t @var{rop}, long double @var{op1}, long double @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_set_z_z (mpc_t @var{rop}, const mpz_t @var{op1}, const mpz_t @var{op2}, mpc_rnd_t @var{rnd})
@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})
@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})
@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})
Set the real part of @var{rop} from @var{op1}, and its imaginary part from
@var{op2}, according to the rounding mode @var{rnd}.

Beware that the behaviour of @code{mpc_set_fr_fr} is undefined if @var{op1}
or @var{op2} is a pointer to the real or imaginary part of @var{rop}.
To exchange the real and the imaginary part of a complex number, either use
@code{mpfr_swap (mpc_realref (rop), mpc_imagref (rop))}, which also exchanges
the precisions of the two parts; or use a temporary variable.
@end deftypefun

For functions assigning complex variables from strings or input streams,
@pxref{String and Stream Input and Output}.

@deftypefun void mpc_set_nan (mpc_t @var{rop})
Set @var{rop} to Nan+i*NaN.
@end deftypefun

@deftypefun void mpc_swap (mpc_t @var{op1}, mpc_t @var{op2})
Swap the values of @var{op1} and @var{op2} efficiently. Warning: The
precisions are exchanged, too; in case these are different,
@code{mpc_swap} is thus not equivalent to three @code{mpc_set} calls using a
third auxiliary variable.
@end deftypefun


@node Converting Complex Numbers
@section Conversion Functions
@cindex Conversion functions

The following functions are available only if @code{<complex.h>}
is included @emph{before} @file{mpc.h}.

@deftypefun double _Complex mpc_get_dc (const mpc_t @var{op}, mpc_rnd_t @var{rnd})
@deftypefunx {long double _Complex} mpc_get_ldc (mpc_t @var{op}, mpc_rnd_t @var{rnd})
Convert @var{op} to a C complex number, using the rounding mode @var{rnd}.
@end deftypefun


For functions converting complex variables to strings or stream output,
@pxref{String and Stream Input and Output}.


@node String and Stream Input and Output
@section String and Stream Input and Output
@cindex String and stream input and output

@deftypefun int mpc_strtoc (mpc_t @var{rop}, const char *@var{nptr}, char **@var{endptr}, int @var{base}, mpc_rnd_t @var{rnd})
Read a complex number from a string @var{nptr} in base @var{base}, rounded to
the precision of @var{rop} with the given rounding mode @var{rnd}.
The @var{base} must be either 0 or a number from 2 to 36 (otherwise the
behaviour is undefined).
If @var{nptr} starts with valid data, the result is stored in @var{rop},
the usual inexact value is returned (@pxref{return-value,, Return
Value}) and, if @var{endptr} is not the null pointer,
@var{*endptr} points to the character just after the valid data.
Otherwise, @var{rop} is set to @code{NaN + i * NaN}, -1 is returned and,
if @var{endptr} is not the null pointer,
the value of @var{nptr} is stored in the location referenced by
@var{endptr}.

The expected form of a complex number string is either a real number (an
optional leading whitespace, an optional sign followed by a floating-point
number), or a pair of real numbers in parentheses separated by whitespace. If
a real number is read, the missing imaginary part is set to +0.
The form of a floating-point number depends on the base and is described
in the documentation of @code{mpfr_strtofr}
@ifinfo
(@pxref{Assignment Functions,,, mpfr.info,GNU MPFR}).
@end ifinfo
@ifnotinfo
in the GNU MPFR manual.
@end ifnotinfo
For instance, @code{"3.1415926"}, @code{"(1.25e+7 +.17)"}, @code{"(@@nan@@
2)"} and @code{"(-0 -7)"} are valid strings for @var{base} = 10.
If @var{base} = 0, then a prefix may be used to indicate the base in which the
floating-point number is written. Use prefix '0b' for binary numbers, prefix
'0x' for hexadecimal numbers, and no prefix for decimal numbers.
The real and imaginary part may then be written in different bases.
For instance, @code{"(1.024e+3 +2.05e+3)"} and @code{"(0b1p+10 +0x802)"} are
valid strings for @code{base}=0 and represent the same value.
@end deftypefun

@deftypefun int mpc_set_str (mpc_t @var{rop}, const char *@var{s}, int @var{base}, mpc_rnd_t rnd)
Set @var{rop} to the value of the string @var{s} in base @var{base}, rounded
to the precision of @var{rop} with the given rounding mode @var{rnd}.
See the documentation of @code{mpc_strtoc} for a detailed description of the
valid string formats.
Contrarily to @code{mpc_strtoc}, @code{mpc_set_str} requires the @emph{whole}
string to represent a valid complex number (potentially followed by
additional white space).
This function returns the usual inexact value (@pxref{return-value,, Return
Value}) if the entire string up to the final null character is a valid number
in base @var{base}; otherwise it returns @minus{}1, and @var{rop} is set to
NaN+i*NaN.
@end deftypefun

@deftypefun {char *} mpc_get_str (int @var{b}, size_t @var{n}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
Convert @var{op} to a string containing its real and imaginary parts,
separated by a space and enclosed in a pair of parentheses.
The numbers are written in base @var{b} (which may vary from 2 to 36) and
rounded according to @var{rnd}. The number of significant digits, at least 2,
is given by @var{n}. It is also possible to let
@var{n} be zero, in which case the number of digits is chosen large
enough so that re-reading the printed value with the same precision, assuming
both output and input use rounding to nearest, will recover the original value
of @var{op}.
Note that @code{mpc_get_str} uses the decimal point of the current locale
if available, and @samp{.} otherwise.

The string is generated using the current memory allocation function
(@code{malloc} by default, unless it has been modified using the custom
memory allocation interface of @code{gmp}); once it is not needed any more,
it should be freed by calling @code{mpc_free_str}.
@end deftypefun

@deftypefun {void} mpc_free_str (char *@var{str})
Free the string @var{str}, which needs to have been allocated by
a call to @code{mpc_get_str}.
@end deftypefun

The following two functions read numbers from input streams and write
them to output streams.
When using any of these functions, you need to include @file{stdio.h}
@emph{before} @file{mpc.h}.

@deftypefun int mpc_inp_str (mpc_t @var{rop}, FILE *@var{stream}, size_t *@var{read}, int @var{base}, mpc_rnd_t @var{rnd})
Input a string in base @var{base} in the same format as for @code{mpc_strtoc}
from stdio stream @var{stream}, rounded according to @var{rnd}, and put the
read complex number into @var{rop}.
If @var{stream} is the null pointer, @var{rop} is read from @code{stdin}.
Return the usual inexact value; if an error occurs, set @var{rop} to @code{NaN
+ i * NaN} and return -1.
If @var{read} is not the null pointer, it is set to the number of read
characters.

Unlike @code{mpc_strtoc}, the function @code{mpc_inp_str} does not possess
perfect knowledge of the string to transform and has to read it
character by character, so it behaves slightly differently: It tries
to read a string describing a complex number and processes this string
through a call to @code{mpc_set_str}. Precisely, after skipping optional
whitespace, a minimal string is read according to the regular expression
@code{mpfr | '(' \s* mpfr \s+ mpfr \s* ')'}, where @code{\s} denotes a whitespace,
and @code{mpfr} is either a string containing neither whitespaces nor
parentheses, or @code{nan(n-char-sequence)} or @code{@@nan@@(n-char-sequence)}
(regardless of capitalisation) with @code{n-char-sequence} a string
of ascii letters, digits or @code{'_'}.

For instance, upon input of @code{"nan(13 1)"}, the function
@code{mpc_inp_str} starts to recognise a value of NaN followed by an
n-char-sequence indicated by the opening parenthesis; as soon as the
space is reached, it becomes clear that the expression in parentheses
is not an n-char-sequence, and the error flag -1 is returned after 6
characters have been consumed from the stream (the whitespace itself
remaining in the stream).
The function @code{mpc_strtoc}, on the other hand, may track back
when reaching the whitespace; it treats the string as the two successive
complex numbers @code{NaN + i * 0} and @code{13 + i}.
It is thus recommended to have a whitespace follow each floating point number
to avoid this problem.
@end deftypefun

@deftypefun size_t mpc_out_str (FILE *@var{stream}, int @var{base}, size_t @var{n_digits}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
Output @var{op} on stdio stream @var{stream} in
base @var{base}, rounded according to @var{rnd}, in the same format
as for @code{mpc_strtoc}
If @var{stream} is the null pointer, @var{rop} is written to @code{stdout}.

Return the number of characters written.
@end deftypefun


@node Complex Comparison
@section Comparison Functions
@cindex Complex comparisons functions
@cindex Comparison functions

@deftypefn Function int mpc_cmp (const mpc_t @var{op1}, const mpc_t @var{op2})
@deftypefnx Function int mpc_cmp_si_si (const mpc_t @var{op1}, long int @var{op2r}, long int @var{op2i})
@deftypefnx Macro int mpc_cmp_si (mpc_t @var{op1}, long int @var{op2})

Compare @var{op1} and @var{op2}, where in the case of @code{mpc_cmp_si_si},
@var{op2} is taken to be @var{op2r} + i @var{op2i}.
The return value @var{c} can be decomposed into @code{x = MPC_INEX_RE(c)}
and @code{y = MPC_INEX_IM(c)}, such that @var{x} is
positive if the real part of @var{op1} is greater than that of @var{op2},
zero if both real parts are equal, and negative if the real part of @var{op1}
is less than that of @var{op2}, and likewise for @var{y}.
Both @var{op1} and @var{op2} are considered to their full own precision,
which may differ.
It is not allowed that one of the operands has a NaN (Not-a-Number) part.

The storage of the return value is such that equality can be simply checked
with @code{mpc_cmp (op1, op2) == 0}.
@end deftypefn

@deftypefn Function int mpc_cmp_abs (const mpc_t @var{op1}, const mpc_t @var{op2})

Compare the absolute values of @var{op1} and @var{op2}.
The return value is 0 if both are the same (including infinity),
positive if the absolute value of @var{op1} is greater than that of @var{op2},
and negative if it is smaller.
If @var{op1} or @var{op2} has a real or imaginary part which is NaN,
the function behaves like @code{mpfr_cmp} on two real numbers of which at least
one is NaN.
@end deftypefn


@node Projection & Decomposing
@section Projection and Decomposing Functions
@cindex Projection and Decomposing Functions

@deftypefn Function int mpc_real (mpfr_t @var{rop}, const mpc_t @var{op}, mpfr_rnd_t @var{rnd})
Set @var{rop} to the value of the real part of @var{op} rounded
in the direction @var{rnd}.
@end deftypefn

@deftypefn Function int mpc_imag (mpfr_t @var{rop}, const mpc_t @var{op}, mpfr_rnd_t @var{rnd})
Set @var{rop} to the value of the imaginary part of @var{op} rounded in the
direction @var{rnd}.
@end deftypefn

@deftypefn Macro mpfr_t mpc_realref (mpc_t @var{op})
@deftypefnx Macro mpfr_t mpc_imagref (mpc_t @var{op})
Return a reference to the real part and imaginary part of @var{op},
respectively. The @code{mpfr} functions can be used on the result of these
macros (note that the @code{mpfr_t} type is itself a pointer).
@end deftypefn

@deftypefn Function int mpc_arg (mpfr_t @var{rop}, const mpc_t @var{op}, mpfr_rnd_t @var{rnd})
Set @var{rop} to the argument of @var{op}, with a branch cut along the
negative real axis.
@end deftypefn

@deftypefn Function int mpc_proj (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
Compute a projection of @var{op} onto the Riemann sphere. Set @var{rop} to
@var{op} rounded in the direction @var{rnd}, except when at least one part of
@var{op} is infinite (even if the other part is a NaN) in which case the real
part of @var{rop} is set to plus infinity and its imaginary part to a signed
zero with the same sign as the imaginary part of @var{op}.
@end deftypefn


@node Basic Arithmetic
@section Basic Arithmetic Functions
@cindex Complex arithmetic functions
@cindex Arithmetic functions

All the following functions are designed in such a way that, when working
with real numbers instead of complex numbers, their complexity should
essentially be the same as with the GNU MPFR library, with only a marginal
overhead due to the GNU MPC layer.

For functions taking as input an integer argument
(for example @code{mpc_add_ui}), when this argument is zero,
it is considered as an unsigned (that is, exact in this context)
zero, and we follow the MPFR conventions:
(0) + (+0) = +0, (0) - (+0) = -0, (0) - (+0) = -0, (0) - (-0) = +0.
The same applies for functions taking an argument of type @code{mpfr_t},
such as @code{mpc_add_fr}, of which the imaginary part is considered
to be an exact, unsigned zero.

@deftypefun int mpc_add (mpc_t @var{rop}, const mpc_t @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_add_ui (mpc_t @var{rop}, const mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_add_fr (mpc_t @var{rop}, const mpc_t @var{op1}, const mpfr_t @var{op2}, mpc_rnd_t @var{rnd})
Set @var{rop} to @var{op1} @math{+} @var{op2} rounded according to @var{rnd}.
@end deftypefun

@deftypefn Function int mpc_sub (mpc_t @var{rop}, const mpc_t @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd})
@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})
@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})
@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})
@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})
@deftypefnx Function int mpc_ui_ui_sub (mpc_t @var{rop}, unsigned long int @var{re1}, unsigned long int @var{im1}, mpc_t @var{op2}, mpc_rnd_t @var{rnd})
Set @var{rop} to @var{op1} @minus{} @var{op2} rounded according to @var{rnd}.
For @code{mpc_ui_ui_sub}, @var{op1} is @var{re1} + @var{im1}.
@end deftypefn

@deftypefun int mpc_neg (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
Set @var{rop} to @minus{}@var{op} rounded according to @var{rnd}.
Just changes the sign if @var{rop} and @var{op} are the same variable.
@end deftypefun

@deftypefun int mpc_sum (mpc_t @var{rop}, const mpc_ptr* @var{op}, unsigned long @var{n}, mpc_rnd_t @var{rnd})
Set @var{rop} to the sum of the elements in the array @var{op} of
length @var{n}, rounded according to @var{rnd}.
@end deftypefun

@deftypefun int mpc_mul (mpc_t @var{rop}, const mpc_t @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_mul_ui (mpc_t @var{rop}, const mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_mul_si (mpc_t @var{rop}, const mpc_t @var{op1}, long int @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_mul_fr (mpc_t @var{rop}, const mpc_t @var{op1}, const mpfr_t @var{op2}, mpc_rnd_t @var{rnd})
Set @var{rop} to @var{op1} times @var{op2} rounded according to @var{rnd}.
Note: for @code{mpc_mul}, in case @var{op1} and @var{op2} have the same value,
use @code{mpc_sqr} for better efficiency.
@end deftypefun

@deftypefun int mpc_mul_i (mpc_t @var{rop}, const mpc_t @var{op}, int @var{sgn}, mpc_rnd_t @var{rnd})
Set @var{rop} to @var{op} times the imaginary unit i if @var{sgn} is
non-negative, set @var{rop} to @var{op} times -i otherwise,
in both cases rounded according to @var{rnd}.
@end deftypefun

@deftypefun int mpc_sqr (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
Set @var{rop} to the square of @var{op} rounded according to @var{rnd}.
@end deftypefun

@deftypefun int mpc_fma (mpc_t @var{rop}, const mpc_t @var{op1}, const mpc_t @var{op2}, const mpc_t @var{op3}, mpc_rnd_t @var{rnd})
Set @var{rop} to @var{op1}*@var{op2}+@var{op3},
rounded according to @var{rnd}, with only one final rounding.
@end deftypefun

@deftypefun int mpc_dot (mpc_t @var{rop}, const mpc_ptr* @var{op1}, mpc_ptr* @var{op2}, unsigned long @var{n}, mpc_rnd_t @var{rnd})
Set @var{rop} to the dot product of the elements in the arrays @var{op1} and
@var{op2}, both of length @var{n}, rounded according to @var{rnd}.
@end deftypefun

@deftypefun int mpc_div (mpc_t @var{rop}, const mpc_t @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_div_ui (mpc_t @var{rop}, const mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_div_fr (mpc_t @var{rop}, const mpc_t @var{op1}, const mpfr_t @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_ui_div (mpc_t @var{rop}, unsigned long int @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_fr_div (mpc_t @var{rop}, const mpfr_t @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd})
Set @var{rop} to @var{op1}/@var{op2} rounded according to @var{rnd}.
@end deftypefun

@deftypefun int mpc_conj (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
Set @var{rop} to the conjugate of @var{op} rounded according to @var{rnd}.
Just changes the sign of the imaginary part
if @var{rop} and @var{op} are the same variable.
@end deftypefun

@deftypefun int mpc_abs (mpfr_t @var{rop}, const mpc_t @var{op}, mpfr_rnd_t @var{rnd})
Set the floating-point number @var{rop} to the absolute value of @var{op},
rounded in the direction @var{rnd}.
@end deftypefun

@deftypefun int mpc_norm (mpfr_t @var{rop}, const mpc_t @var{op}, mpfr_rnd_t @var{rnd})
Set the floating-point number @var{rop} to the norm of @var{op}
(i.e., the square of its absolute value),
rounded in the direction @var{rnd}.
@end deftypefun

@deftypefun int mpc_mul_2ui (mpc_t @var{rop}, const mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_mul_2si (mpc_t @var{rop}, const mpc_t @var{op1}, long int @var{op2}, mpc_rnd_t @var{rnd})
Set @var{rop} to @var{op1} times 2 raised to @var{op2}
rounded according to @var{rnd}. Just modifies the exponents
of the real and imaginary parts by @var{op2}
when @var{rop} and @var{op1} are identical.
@end deftypefun

@deftypefun int mpc_div_2ui (mpc_t @var{rop}, const mpc_t @var{op1}, unsigned long int @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_div_2si (mpc_t @var{rop}, const mpc_t @var{op1}, long int @var{op2}, mpc_rnd_t @var{rnd})
Set @var{rop} to @var{op1} divided by 2 raised to @var{op2}
rounded according to @var{rnd}. Just modifies the exponents
of the real and imaginary parts by @var{op2}
when @var{rop} and @var{op1} are identical.
@end deftypefun


@node Power Functions and Logarithm
@section Power Functions and Logarithm
@cindex Power functions
@cindex Logarithm

@deftypefun int mpc_sqrt (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
Set @var{rop} to the square root of @var{op} rounded according to @var{rnd}.
The returned value @var{rop} has a non-negative real part, and if its real
part is zero, a non-negative imaginary part.
@end deftypefun

@deftypefun int mpc_pow (mpc_t @var{rop}, const mpc_t @var{op1}, const mpc_t @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_pow_d (mpc_t @var{rop}, const mpc_t @var{op1}, double @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_pow_ld (mpc_t @var{rop}, const mpc_t @var{op1}, long double @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_pow_si (mpc_t @var{rop}, const mpc_t @var{op1}, long @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_pow_ui (mpc_t @var{rop}, const mpc_t @var{op1}, unsigned long @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_pow_z (mpc_t @var{rop}, const mpc_t @var{op1}, const mpz_t @var{op2}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_pow_fr (mpc_t @var{rop}, const mpc_t @var{op1}, const mpfr_t @var{op2}, mpc_rnd_t @var{rnd})
Set @var{rop} to @var{op1} raised to the power @var{op2}, rounded according
to @var{rnd}.
For @code{mpc_pow_d}, @code{mpc_pow_ld}, @code{mpc_pow_si}, @code{mpc_pow_ui},
@code{mpc_pow_z} and @code{mpc_pow_fr},
the imaginary part of @var{op2} is considered as +0.
When both @var{op1} and @var{op2} are zero, the result has real part 1,
and imaginary part 0, with sign being the opposite of that of @var{op2}.
@end deftypefun

@deftypefun int mpc_exp (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
Set @var{rop} to the exponential of @var{op},
rounded according to @var{rnd} with the precision of @var{rop}.
@end deftypefun

@deftypefun int mpc_log (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_log10 (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
Set @var{rop} to the natural and base-10 logarithm of @var{op} respectively,
rounded according to @var{rnd} with the precision of @var{rop}.
The principal branch is chosen, with the branch cut on the negative real axis,
so that the imaginary part of the result lies in
@iftex
@math{]-\pi , \pi]}
@end iftex
@ifnottex
]-Pi , Pi]
@end ifnottex
and
@iftex
@math{]-\pi/\log(10) , \pi/\log(10)]}
@end iftex
@ifnottex
]-Pi/log(10) , Pi/log(10)]
@end ifnottex
respectively.
@end deftypefun

@deftypefun int mpc_rootofunity (mpc_t @var{rop}, unsigned long int @var{n}, unsigned long int @var{k}, mpc_rnd_t @var{rnd})
Set @var{rop} to the standard primitive @var{n}-th root of unity raised to the power @var{k}, that is,
@m{\exp (2 \pi i k / n),exp (2 Pi i k / n)},
rounded according to @var{rnd} with the precision of @var{rop}.
@end deftypefun

@deftypefun int mpc_agm (mpc_t @var{rop}, const mpc_t @var{a}, const mpc_t @var{b}, mpc_rnd_t @var{rnd})
Set @var{rop} to the arithmetic-geometric mean (AGM) of @var{a} and
@var{b}, rounded according to @var{rnd} with the precision of @var{rop}.
Concerning the branch cut, the function is computed by homogeneity either
as @var{a} AGM(1,b0) with b0=@var{b}/@var{a} if |@var{a}|>=|@var{b}|,
or as @var{b} AGM(1,b0) with b0=@var{a}/@var{b} otherwise;
then when b0 is real and negative, AGM(1,b0) is chosen to have positive
imaginary part.
@end deftypefun


@node Trigonometric Functions
@section Trigonometric Functions
@cindex Trigonometric functions

@deftypefun int mpc_sin (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_cos (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_tan (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
Set @var{rop} to the sine, cosine, tangent of @var{op},
rounded according to @var{rnd} with the precision of @var{rop}.
@end deftypefun

@deftypefun int mpc_sin_cos (mpc_t @var{rop_sin}, mpc_t @var{rop_cos}, const mpc_t @var{op}, mpc_rnd_t @var{rnd_sin}, mpc_rnd_t @var{rnd_cos})
Set @var{rop_sin} to the sine of @var{op},
rounded according to @var{rnd_sin} with the precision of @var{rop_sin},
and @var{rop_cos} to the cosine of @var{op},
rounded according to @var{rnd_cos} with the precision of @var{rop_cos}.
@end deftypefun

@deftypefun int mpc_sinh (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_cosh (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_tanh (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
Set @var{rop} to the hyperbolic sine, hyperbolic cosine, hyperbolic tangent of @var{op},
rounded according to @var{rnd} with the precision of @var{rop}.
@end deftypefun

@deftypefun int mpc_asin (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_acos (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_atan (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
Set @var{rop} to the inverse sine, inverse cosine, inverse tangent of @var{op},
rounded according to @var{rnd} with the precision of @var{rop}.
@end deftypefun

@deftypefun int mpc_asinh (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_acosh (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
@deftypefunx int mpc_atanh (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
Set @var{rop} to the inverse hyperbolic sine, inverse hyperbolic cosine,
inverse hyperbolic tangent of @var{op},
rounded according to @var{rnd} with the precision of @var{rop}.
The branch cut of @code{mpc_acosh} is
@iftex
@math{(-\infty, 1)}.
@end iftex
@ifnottex
(-Inf, 1)
@end ifnottex
@end deftypefun


@node Modular Functions
@section Modular Functions
@cindex Modular functions

The following function is experimental, not least because it depends on
the equally experimental ball arithmetic, see @ref {Ball Arithmetic}.
So its prototype may change in future releases, and it may be removed
altogether.

@deftypefun int mpc_eta_fund (mpc_t @var{rop}, const mpc_t @var{op}, mpc_rnd_t @var{rnd})
Assuming that the argument @var{op} lies in the fundamental domain for
@math{Sl_2(Z)}, that is, it has real part not below @math{-1/2} and
not above @math{+1/2} and absolute value at least 1,
return the value of the Dedekind eta-function in @var{rop}.
For arguments outside the fundamental domain the function is expected to
loop indefinitely.
@end deftypefun


@node Miscellaneous Complex Functions
@section Miscellaneous Functions
@cindex Miscellaneous complex functions

@deftypefun int mpc_urandom (mpc_t @var{rop}, gmp_randstate_t @var{state})
Generate a uniformly distributed random complex in the unit square @math{[0,
1] @times [0, 1]}. Return 0, unless an exponent in the real or imaginary part
is not in the current exponent range, in which case that part is set to NaN
and a zero value is returned. The second argument is a @code{gmp_randstate_t}
structure which should be created using the GMP @code{rand_init} function, see
the GMP manual.
@end deftypefun

@deftypefun {const char *} mpc_get_version (void)
Return the GNU MPC version, as a null-terminated string.
@end deftypefun

@defmac MPC_VERSION
@defmacx MPC_VERSION_MAJOR
@defmacx MPC_VERSION_MINOR
@defmacx MPC_VERSION_PATCHLEVEL
@defmacx MPC_VERSION_STRING
@code{MPC_VERSION} is the version of GNU MPC as a preprocessing constant.
@code{MPC_VERSION_MAJOR}, @code{MPC_VERSION_MINOR} and
@code{MPC_VERSION_PATCHLEVEL} are respectively the major, minor and
patch level of GNU MPC version, as preprocessing constants.
@code{MPC_VERSION_STRING} is the version as a string constant, which
can be compared to the result of @code{mpc_get_version} to check at
run time the header file and library used match:
@example
if (strcmp (mpc_get_version (), MPC_VERSION_STRING))
  fprintf (stderr, "Warning: header and library do not match\n");
@end example
Note: Obtaining different strings is not necessarily an error, as in
general, a program compiled with some old GNU MPC version can be
dynamically linked with a newer GNU MPC library version (if allowed by the
library versioning system).
@end defmac

@deftypefn Macro long MPC_VERSION_NUM (@var{major}, @var{minor}, @var{patchlevel})
Create an integer in the same format as used by @code{MPC_VERSION} from the
given @var{major}, @var{minor} and @var{patchlevel}.
Here is an example of how to check the GNU MPC version at compile time:
@example
#if (!defined(MPC_VERSION) || (MPC_VERSION<MPC_VERSION_NUM(2,1,0)))
# error "Wrong GNU MPC version."
#endif
@end example
@end deftypefn

@node Advanced Functions
@section Advanced Functions

@defmac MPC_SET_X_Y (@var{real_suffix}, @var{imag_suffix}, @var{rop}, @var{real}, @var{imag}, @var{rnd})
The macro MPC_SET_X_Y is designed to serve as the body of an assignment
function and cannot be used by itself.
The @var{real_suffix} and @var{imag_suffix} parameters are the
types of the real and imaginary part, that is, the @code{x} in the
@code{mpfr_set_x} function one would use to set the part;
for the mpfr type, use @code{fr}.
@var{real} (respectively @var{imag}) is the value you want to assign to the
real (resp. imaginary) part, its type must conform to @var{real_suffix}
(resp. @var{imag_suffix}).
@var{rnd} is the @code{mpc_rnd_t} rounding mode.
The return value is the usual inexact value (@pxref{return-value,, Return
Value}).

For instance, you can define mpc_set_ui_fr as follows:
@example
int mpc_set_ui_fr (mpc_t rop, unsigned long int re, mpfr_t im, mpc_rnd_t rnd)
    MPC_SET_X_Y (ui, fr, rop, re, im, rnd);
@end example
@end defmac


@node Internals
@section Internals

These macros and
functions are mainly designed for the implementation of GNU MPC,
but may be useful for users too.
However, no upward compatibility is guaranteed.
You need to include @code{mpc-impl.h} to use them.

The macro @code{MPC_MAX_PREC(z)} gives the maximum of the precisions
of the real and imaginary parts of a complex number.


@node Ball Arithmetic
@chapter Ball Arithmetic
@cindex Ball arithmetic

Since release 1.3.0, GNU MPC contains a simple and very limited
implementation of complex balls (or rather, circles). This part is
experimental, its interface may vary and it may be removed completely
in future releases.

@tindex mpcb_t
A complex ball of the new type @code{mpcb_t} is defined by a non-zero centre
@math{c} of the type @code{mpc_t} and a relative radius @math{r} of
the new type @code{mpcr_t}, and it represents all complex numbers
@math{z = c (1 + ��)} with @math{|��| ��� r}, or equivalently
the closed circle with centre @math{c} and radius @math{r |c|}.
The approach of using a relative error (or radius) instead of an absolute
one simplifies error analyses for multiplicative operations (multiplication,
division, square roots, and the AGM), at the expense of making them more
complicated for additive operations. It has the major drawback of not being
able to represent balls centred at 0; in floating point arithmetic, however,
0 is never reached by rounding, but only through operations with exact
result, which could be handled at a higher, application level. For more
discussion on these issues, see the file @code{algorithms.tex}.


@section Radius type and functions
@tindex mpcr_t
@tindex mpcr_ptr
@tindex mpcr_srcptr

The radius type is defined by
@verbatim
struct {
   int64_t mant;
   int64_t exp;
}
@end verbatim
with the usual trick in the GNU multiprecision libraries of defining the
main type @code{mpcr_t} as a 1-dimensional array of this struct, and
variable and constant pointers @code{mpcr_ptr} and @code{mpcr_srcptr}.
It can contain the special values infinity or zero, or floating point
numbers encoded as @math{m���2@sup{e}} for a positive mantissa
@math{m} and an arbitrary (usually negative) exponent @math{e}.
Normalised finite radii use 31 bits for the mantissa, that is,
@math{2@sup{30}���m���2@sup{31} - 1}.
The special values infinity and 0 are encoded through the sign of
@math{m}, but should be tested for and set using dedicated functions.

Unless indicated otherwise, the following functions
assume radius arguments to be normalised,
they return normalised results, and they round their results up, not
necessarily to the smallest representable number, although reasonable
effort is made to get a tight upper bound: They only guarantee that
their outputs are an upper bound on the true results.
(There may be a trade-off between tightness of the result and speed of
computation. For instance, when a 32-bit mantissa is normalised, an even
mantissa should be divided by 2, an odd mantissa should be divided by 2
and 1 should be added, and then in both cases the exponent must be
increased by 1. It might be more efficient to add 1 all the time instead
of testing the last bit of the mantissa.)

@deftypefun int mpcr_inf_p (mpcr_srcptr @var{r})
@deftypefunx int mpcr_zero_p (mpcr_srcptr @var{r})
Test whether @var{r} is infinity or zero, respectively, and return a
boolean.
@end deftypefun


@deftypefun int mpcr_lt_half_p (mpcr_srcptr @var{r})
Return @code{true} if @var{r}<1/2, and @code{false} otherwise.
(Everywhere in this document,
@code{true} means any non-zero value, and @code{false} means zero.)
@end deftypefun


@deftypefun int mpcr_cmp (mpcr_srcptr @var{r}, mpcr_srcptr @var{s})
Return +1, 0 or -1 depending on whether @var{r} is larger than, equal to
or less than @var{s}, with the natural total order on the compactified
non-negative real axis letting 0 be smaller and letting infinity be larger
than any finite real number.
@end deftypefun


@deftypefun void mpcr_set_inf (mpcr_ptr @var{r})
@deftypefunx void mpcr_set_zero (mpcr_ptr @var{r})
@deftypefunx void mpcr_set_one (mpcr_ptr @var{r})
@deftypefunx void mpcr_set (mpcr_ptr @var{r}, mpcr_srcptr @var{s})
@deftypefunx void mpcr_set_ui64_2si64 (mpcr_ptr @var{r}, uint64_t @var{mant}, int64_t @var{exp})
Set @var{r} to infinity, zero, 1, @var{s} or
@var{mant}���2@sup{@var{exp}}, respectively.
@end deftypefun


@deftypefun void mpcr_max (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, mpcr_srcptr @var{t})
Set @var{r} to the maximum of @var{s} and @var{t}.
@end deftypefun


@deftypefun int64_t mpcr_get_exp (mpcr_srcptr @var{r})
Assuming that @var{r} is neither infinity nor 0, return its exponent
@math{e} when writing @math{r = m���2@sup{e}} with
@math {1/2 ��� m < 1}. (Notice that this is @emph{not} the same as the
field @code{exp} in the struct representing a radius, but that instead it
is independent of the implementation.)
Otherwise the behaviour is undefined.
@end deftypefun


@deftypefun void mpcr_out_str (FILE *@var{f}, mpcr_srcptr @var{r})
Output @var{r} on @var{f}, which may be @code{stdout}.
Caveat: This function so far serves mainly for debugging purposes, its
behaviour will probably change in the future.
@end deftypefun


@deftypefun void mpcr_add (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, mpcr_srcptr @var{t})
@deftypefunx void mpcr_sub (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, mpcr_srcptr @var{t})
@deftypefunx void mpcr_mul (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, mpcr_srcptr @var{t})
@deftypefunx void mpcr_div (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, mpcr_srcptr @var{t})
@deftypefunx void mpcr_mul_2ui (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, unsigned long int @var{t})
@deftypefunx void mpcr_div_2ui (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, unsigned long int @var{t})
@deftypefunx void mpcr_sqr (mpcr_ptr @var{r}, mpcr_srcptr @var{s})
@deftypefunx void mpcr_sqrt (mpcr_ptr @var{r}, mpcr_srcptr @var{s})
Set @var{r} to the sum, difference, product or quotient of @var{s} and
@var{t}, or to the product of @var{s} by 2@sup{@var{t}} or to the
quotient of @var{s} by 2@sup{@var{t}},
or to the square or the square root of @var{s}.
If any of the arguments is infinity, or if a difference is negative,
the result is infinity.
@end deftypefun


@deftypefun void mpcr_sub_rnd (mpcr_ptr @var{r}, mpcr_srcptr @var{s}, mpcr_srcptr @var{t}, mpfr_rnd_t @var{rnd})
Set @var{r} to the difference of @var{s} and @var{t}, rounded into
direction @var{rnd}, which can be one of @code{MPFR_RNDU} or
@code{MPFR_RNDD}. If one of the arguments is infinity or the difference is
negative, the result is infinity. Calling the function with @code{MPFR_RNDU}
is equivalent to calling @code{mpcr_sub}.

This is one out of several functions taking a rounding parameter. Rounding
down may be useful to obtain an upper bound when dividing by the result.
@end deftypefun


@deftypefun void mpcr_c_abs_rnd (mpcr_ptr @var{r}, mpc_srcptr @var{z}, mpfr_rnd_t @var{rnd})
Set @var{r} to the absolute value of the complex number @var{z}, rounded
in direction @var{rnd}, which may be one of @code{MPFR_RNDU} or
@code{MPFR_RNDD}.
@end deftypefun


@deftypefun void mpcr_add_rounding_error (mpcr_ptr @var{r}, mpfr_prec_t @var{p}, mpfr_rnd_t @var{rnd})
Set @var{r} to @math{r + (1 + r) 2@sup{-p}} if @var{rnd} equals
@code{MPFR_RNDN}, and to @math{r + (1 + r) 2@sup{1-p}} otherwise.
The idea is that if a (potentially not representable) centre of an ideal
complex ball of radius @var{r} is rounded to a representable complex
number at precision @var{p}, this shifts the centre by up to 1/2 ulp
(for rounding to nearest) or 1 ulp (for directed rounding of at least one
of the real or imaginary parts), which increases the radius accordingly.
So this function is typically called internally at the end of each
operation with complex balls to account for the error made by rounding
the centre.
@end deftypefun


@section Ball type and functions
@tindex mpcb_t
@tindex mpcb_ptr
@tindex mpcb_srcptr

The ball type is defined by
@verbatim
typedef struct {
  mpc_t  c;
  mpcr_t r;
}
@end verbatim
or, more precisely, @code{mpcb_t} is again a 1-dimensional array of such
a struct, and variable and constant pointer types are defined as
@code{mpcb_ptr} and @code{mpcb_srcptr}, respectively.
As usual, the components should only be accessed through corresponding
functions.

To understand functions on balls, one needs to consider the balls passed
as arguments as sets of complex values, to which a mathematical function
is applied; the C function ``rounds up'' in the sense that it returns a
ball containing all possible values of the function in all the possible
input values. Reasonable effort is made to return small balls, but again
there is no guarantee that the result is the smallest possible one.
In the current implementation, the centre of a ball returned as a value
is obtained by applying the function to the centres of the balls passed
as arguments, and rounding. While this is a natural approach, it is not
the only possible one; however, it also simplifies the error analysis
as already carried out for functions with regular complex arguments.
Whenever the centre of a complex ball has a non-finite real or imaginary
part (positive or negative infinity or NaN) the radius is set to infinity;
this can be interpreted as the ``useless ball'', representing the whole
complex plane, whatever the value of the centre is.

Unlike for variables of @code{mpc_t} type, where the precision needs to
be set explicitly at initialisation, variables of type @code{mpcb_t}
handle their precision dynamically. Ball centres always have the same
precision for their real and their imaginary parts (again this is a
choice of the implementation; if they are of very different sizes, one
could theoretically reduce the precision of the part that is smaller
in absolute value, which is more strongly affected by the common error
coded in the radius).
When setting a complex ball from a value of a different type, an
additional precision parameter is passed, which determines the precision
of the centre. Functions on complex balls set the precision of their
result depending on the input. In the current implementation, this is the
minimum of the argument precisions, so if all balls are initially set to
the same precision, this is preserved throughout the computations.
(Notice that the exponent of the radius encodes roughly the number of
correct binary digits of the ball centre; so it would also make sense
to reduce the precision if the radius becomes larger.)

The following functions on complex balls are currently available; the
eclectic collection is motivated by the desire to provide an implementation
of the arithmetic-geometric mean of complex numbers through the use of
ball arithmetic. As for functions taking complex arguments, there may
be arbitrary overlaps between variables representing arguments and
results; for instance
@code{mpcb_mul (z, z, z)} is an allowed way of replacing the ball @var{z}
by its square.


@deftypefun void mpcb_init (mpcb_ptr @var{z})
@deftypefunx void mpcb_clear (mpcb_ptr @var{z})
Initialise or free memory for @var{z}; @code{mpcb_init} must be called once
before using a variable, and @code{mpcb_clear} must be called once before
stopping to use a variable. Unlike its @code{mpc_t} counterpart,
@code{mpcb_init} does not fix the precision of @var{z}, but it sets its
radius to infinity, so that @var{z} represents the whole complex plane.
@end deftypefun


@deftypefun mpfr_prec_t mpcb_get_prec (mpcb_srcptr @var{z})
Return the (common) precision of the real and the complex parts of the
centre of @var{z}.
@end deftypefun


@deftypefun void mpcb_set (mpcb_ptr @var{z}, mpcb_srcptr @var{z1})
Set @var{z} to @var{z1}, preserving the precision of the centre.
@end deftypefun


@deftypefun void mpcb_set_inf (mpcb_ptr @var{z})
Set @var{z} to the whole complex plane. This is intended to be used much
in the spirit of an assertion: When a precondition is not satisfied inside
a function, it can set its result to this value, which will propagate
through further computations.
@end deftypefun


@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})
Set @var{z} to a ball with centre @var{c} at precision @var{prec}.
If @var{prec} is at least the maximum of the precisions of the real and the
imaginary parts of @var{c} and @var{err_re} and @var{err_im} are 0, then
the resulting ball is exact with radius zero. Using a larger value for
@var{prec} makes sense if @var{c} is considered exact and a larger target
precision for the result is desired, or some leeway for the working
precision is to be taken into account.
If @var{prec} is less than the precision of @var{c}, then usually some
rounding error occurs when setting the centre, which is taken into account
in the radius.

If @var{err_re} and @var{err_im} are non-zero, the argument @var{c} is
considered as an inexact complex number, with a bound on the absolute error
of its real part given in @var{err_re} as a multiple of 1/2 ulp of the real
part of @var{c}, and a bound on the absolute error of its imaginary part
given in @var{err_im} as a multiple of 1/2 ulp of the imaginary part of
@var{c}. (Notice that if the parts of @var{c} have different precisions or
exponents, the absolute values of their ulp differ.)
Then @var{z} is created as a ball with centre @var{c} and a radius taking
these errors on @var{c} as well as the potential additional rounding error
for the centre into account.
If the real part of @var{c} is 0, then @var{err_re} must be 0, since
ulp of 0 makes no sense; otherwise the radius is set to infinity. The same
remark holds for the imaginary part.

Using @var{err_re} and @var{err_im} different from 0 is particularly
useful in two settings: If @var{c} is itself the result of a call to an
@code{mpc_} function with exact input and rounding mode @code{MPC_RNDNN}
of both parts to nearest, then its parts are known with errors of at most
1/2 ulp, and setting @var{err_re} and @var{err_im} to 1 yields a ball
which is known to contain the exact result (this motivates the strange
unit of 1/2 ulp); if directed rounding was used, @var{err_re} and
@var{err_im} can be set to 2 instead.

And if @var{c} is the result of a sequence of calls to @code{mpc_}
functions for which some error analysis has been carried out (as is
frequently the case internally when implementing complex functions),
again the resulting ball @var{z} is known to contain the exact result
when using appropriate values for @var{err_re} and @var{err_im}.
@end deftypefun


@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})
Set @var{z} to a ball with centre @var{re}+I*@var{im} at precision
@var{prec} or the size of an @code{unsigned long int}, whatever is larger.
@end deftypefun


@deftypefun void mpcb_neg (mpcb_ptr @var{z}, mpcb_srcptr @var{z1})
@deftypefunx void mpcb_add (mpcb_ptr @var{z}, mpcb_srcptr @var{z1}, mpcb_srcptr @var{z2})
@deftypefunx void mpcb_mul (mpcb_ptr @var{z}, mpcb_srcptr @var{z1}, mpcb_srcptr @var{z2})
@deftypefunx void mpcb_sqr (mpcb_ptr @var{z}, mpcb_srcptr @var{z1})
@deftypefunx void mpcb_pow_ui (mpcb_ptr @var{z}, mpcb_srcptr @var{z1}, unsigned long int @var{e})
@deftypefunx void mpcb_sqrt (mpcb_ptr @var{z}, mpcb_srcptr @var{z1})
@deftypefunx void mpcb_div (mpcb_ptr @var{z}, mpcb_srcptr @var{z1}, mpcb_srcptr @var{z2})
@deftypefunx void mpcb_div_2ui (mpcb_ptr @var{z}, mpcb_srcptr @var{z1}, unsigned long int @var{e})
These are the exact counterparts of the corresponding functions
@code{mpc_neg}, @code{mpc_add} and so on, but on complex balls instead of
complex numbers.
@end deftypefun


@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})
If the function returns @code{true} (a non-zero number), then rounding
any of the complex numbers in the ball to a complex number with precision
@var{prec_re} of its real and precision @var{prec_im} of its imaginary
part and rounding mode @var{rnd} yields the same result and rounding
direction value, cf. @ref{return-value}.
If the function returns @code{false} (that is, 0), then it could not
conclude, or there are two numbers in the ball which would be rounded to
a different complex number or in a different direction. Notice that the
function works in a best effort mode and errs on the side of caution by
potentially returning @code{false} on a roundable ball; this is consistent
with computational functions not necessarily returning the smallest
enclosing ball.

If @var{z} contains the result of evaluating some mathematical function
through a sequence of calls to @code{mpcb} functions, starting with exact
complex numbers, that is, balls of radius 0, then a return value of
@code{true} indicates that rounding any value in the ball (its centre is
readily available) in direction @var{rnd} yields the correct result of
the function and the correct rounding direction value with the usual
MPC semantics.

Notice that when the precision of @var{z} is larger than @var{prec_re}
or @var{prec_im}, the centre need not be representable at the desired
precision, and in fact the ball need not contain a representable number
at all to be ``roundable''. Even worse, when @var{rnd} is a directed
rounding mode for the real or the imaginary part and the ball of
non-zero radius contains
a representable number, the return value is necessarily @code{false}.
Even worse, when the rounding mode for one part is to nearest, the
corresponding part of the centre of the ball is representable and the ball
has a non-zero radius, then the return value is also necessarily
@code{false}, since even if rounding may be possible, the rounding
direction value cannot be determined.
@end deftypefun


@deftypefun int mpcb_round (mpc_ptr @var{c}, mpcb_srcptr @var{z}, mpc_rnd_t @var{rnd})
Set @var{c} to the centre of @var{z}, rounded in direction @var{rnd},
and return the corresponding rounding direction value.
If @code{mpcb_can_round}, called with @var {z}, the precisions of @var{c}
and the rounding mode @var{rnd} returns @code{true}, then this function
does what is expected, it ``correctly rounds the ball'' and returns a
rounding direction value that is valid for all of the ball.
As explained above, the result is then not necessarily (in the presence of
directed rounding with radius different from 0, it is rather
necessarily not) an element of the ball.
@end deftypefun


@node References
@unnumbered References

@itemize @bullet

@item
Torbj@"orn Granlund et al.
@code{GMP} -- GNU multiprecision library.
Version 6.2.0, @url{http://gmplib.org}.

@item
Guillaume Hanrot, Vincent Lef@`evre, Patrick P@'elissier, Paul Zimmermann et al.
@code{MPFR} -- A library for multiple-precision floating-point computations with exact rounding.
Version 4.1.0, @url{http://www.mpfr.org}.

@item
IEEE Standard for Floating-Point Arithmetic,
IEEE Computer Society,
IEEE Std 754-2019, Approved 13 June 2019, 84 pages.

@item
Donald E. Knuth, "The Art of Computer Programming", vol 2,
"Seminumerical Algorithms", 2nd edition, Addison-Wesley, 1981.

@item
ISO/IEC 9899:1999, Programming languages ��� C.

@end itemize

@node Concept Index
@unnumbered Concept Index
@printindex cp

@node Function Index
@unnumbered Function Index
@printindex fn

@node Type Index
@unnumbered Type Index
@printindex tp

@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl-1.3.texi

@ifnothtml
@contents
@end ifnothtml

@bye