1
This is gmp.info, produced by makeinfo version 4.0 from gmp.texi.
3
INFO-DIR-SECTION GNU libraries
5
* gmp: (gmp). GNU Multiple Precision Arithmetic Library.
9
File: gmp.info, Node: I/O of Integers, Next: Integer Random Numbers, Prev: Integer Logic and Bit Fiddling, Up: Integer Functions
11
Input and Output Functions
12
==========================
14
Functions that perform input from a stdio stream, and functions that
15
output to a stdio stream. Passing a `NULL' pointer for a STREAM
16
argument to any of these functions will make them read from `stdin' and
17
write to `stdout', respectively.
19
When using any of these functions, it is a good idea to include
20
`stdio.h' before `gmp.h', since that will allow `gmp.h' to define
21
prototypes for these functions.
23
- Function: size_t mpz_out_str (FILE *STREAM, int BASE, mpz_t OP)
24
Output OP on stdio stream STREAM, as a string of digits in base
25
BASE. The base may vary from 2 to 36.
27
Return the number of bytes written, or if an error occurred,
30
- Function: size_t mpz_inp_str (mpz_t ROP, FILE *STREAM, int BASE)
31
Input a possibly white-space preceded string in base BASE from
32
stdio stream STREAM, and put the read integer in ROP. The base
33
may vary from 2 to 36. If BASE is 0, the actual base is
34
determined from the leading characters: if the first two
35
characters are `0x' or `0X', hexadecimal is assumed, otherwise if
36
the first character is `0', octal is assumed, otherwise decimal is
39
Return the number of bytes read, or if an error occurred, return 0.
41
- Function: size_t mpz_out_raw (FILE *STREAM, mpz_t OP)
42
Output OP on stdio stream STREAM, in raw binary format. The
43
integer is written in a portable format, with 4 bytes of size
44
information, and that many bytes of limbs. Both the size and the
45
limbs are written in decreasing significance order (i.e., in
48
The output can be read with `mpz_inp_raw'.
50
Return the number of bytes written, or if an error occurred,
53
The output of this can not be read by `mpz_inp_raw' from GMP 1,
54
because of changes necessary for compatibility between 32-bit and
57
- Function: size_t mpz_inp_raw (mpz_t ROP, FILE *STREAM)
58
Input from stdio stream STREAM in the format written by
59
`mpz_out_raw', and put the result in ROP. Return the number of
60
bytes read, or if an error occurred, return 0.
62
This routine can read the output from `mpz_out_raw' also from GMP
63
1, in spite of changes necessary for compatibility between 32-bit
67
File: gmp.info, Node: Integer Random Numbers, Next: Miscellaneous Integer Functions, Prev: I/O of Integers, Up: Integer Functions
69
Random Number Functions
70
=======================
72
The random number functions of GMP come in two groups; older function
73
that rely on a global state, and newer functions that accept a state
74
parameter that is read and modified. Please see the *Note Random
75
Number Functions:: for more information on how to use and not to use
76
random number functions.
78
- Function: void mpz_urandomb (mpz_t ROP, gmp_randstate_t STATE,
80
Generate a uniformly distributed random integer in the range 0 to
83
The variable STATE must be initialized by calling one of the
84
`gmp_randinit' functions (*Note Random State Initialization::)
85
before invoking this function.
87
- Function: void mpz_urandomm (mpz_t ROP, gmp_randstate_t STATE, mpz_t
89
Generate a uniform random integer in the range 0 to N-1, inclusive.
91
The variable STATE must be initialized by calling one of the
92
`gmp_randinit' functions (*Note Random State Initialization::)
93
before invoking this function.
95
- Function: void mpz_rrandomb (mpz_t ROP, gmp_randstate_t STATE,
97
Generate a random integer with long strings of zeros and ones in
98
the binary representation. Useful for testing functions and
99
algorithms, since this kind of random numbers have proven to be
100
more likely to trigger corner-case bugs. The random number will
101
be in the range 0 to 2^N-1, inclusive.
103
The variable STATE must be initialized by calling one of the
104
`gmp_randinit' functions (*Note Random State Initialization::)
105
before invoking this function.
107
- Function: void mpz_random (mpz_t ROP, mp_size_t MAX_SIZE)
108
Generate a random integer of at most MAX_SIZE limbs. The generated
109
random number doesn't satisfy any particular requirements of
110
randomness. Negative random numbers are generated when MAX_SIZE
113
This function is obsolete. Use `mpz_urandomb' or `mpz_urandomm'
116
- Function: void mpz_random2 (mpz_t ROP, mp_size_t MAX_SIZE)
117
Generate a random integer of at most MAX_SIZE limbs, with long
118
strings of zeros and ones in the binary representation. Useful
119
for testing functions and algorithms, since this kind of random
120
numbers have proven to be more likely to trigger corner-case bugs.
121
Negative random numbers are generated when MAX_SIZE is negative.
123
This function is obsolete. Use `mpz_rrandomb' instead.
126
File: gmp.info, Node: Miscellaneous Integer Functions, Prev: Integer Random Numbers, Up: Integer Functions
128
Miscellaneous Functions
129
=======================
131
- Function: int mpz_fits_ulong_p (mpz_t OP)
132
- Function: int mpz_fits_slong_p (mpz_t OP)
133
- Function: int mpz_fits_uint_p (mpz_t OP)
134
- Function: int mpz_fits_sint_p (mpz_t OP)
135
- Function: int mpz_fits_ushort_p (mpz_t OP)
136
- Function: int mpz_fits_sshort_p (mpz_t OP)
137
Return non-zero iff the value of OP fits in an `unsigned long int',
138
`signed long int', `unsigned int', `signed int', `unsigned short
139
int', or `signed short int', respectively. Otherwise, return zero.
141
- Macro: int mpz_odd_p (mpz_t OP)
142
- Macro: int mpz_even_p (mpz_t OP)
143
Determine whether OP is odd or even, respectively. Return
144
non-zero if yes, zero if no. These macros evaluate their argument
147
- Function: size_t mpz_size (mpz_t OP)
148
Return the size of OP measured in number of limbs. If OP is zero,
149
the returned value will be zero.
151
- Function: size_t mpz_sizeinbase (mpz_t OP, int BASE)
152
Return the size of OP measured in number of digits in base BASE.
153
The base may vary from 2 to 36. The sign of OP is ignored, just
154
the absolute value is used. The returned value will be exact or 1
155
too big. If BASE is a power of 2, the returned value will always
158
This function is useful in order to allocate the right amount of
159
space before converting OP to a string. The right amount of
160
allocation is normally two more than the value returned by
161
`mpz_sizeinbase' (one extra for a minus sign and one for the
165
File: gmp.info, Node: Rational Number Functions, Next: Floating-point Functions, Prev: Integer Functions, Up: Top
167
Rational Number Functions
168
*************************
170
This chapter describes the GMP functions for performing arithmetic
171
on rational numbers. These functions start with the prefix `mpq_'.
173
Rational numbers are stored in objects of type `mpq_t'.
175
All rational arithmetic functions assume operands have a canonical
176
form, and canonicalize their result. The canonical from means that the
177
denominator and the numerator have no common factors, and that the
178
denominator is positive. Zero has the unique representation 0/1.
180
Pure assignment functions do not canonicalize the assigned variable.
181
It is the responsibility of the user to canonicalize the assigned
182
variable before any arithmetic operations are performed on that
185
- Function: void mpq_canonicalize (mpq_t OP)
186
Remove any factors that are common to the numerator and
187
denominator of OP, and make the denominator positive.
191
* Initializing Rationals::
192
* Rational Conversions::
193
* Rational Arithmetic::
194
* Comparing Rationals::
195
* Applying Integer Functions::
199
File: gmp.info, Node: Initializing Rationals, Next: Rational Conversions, Prev: Rational Number Functions, Up: Rational Number Functions
201
Initialization and Assignment Functions
202
=======================================
204
- Function: void mpq_init (mpq_t DEST_RATIONAL)
205
Initialize DEST_RATIONAL and set it to 0/1. Each variable should
206
normally only be initialized once, or at least cleared out (using
207
the function `mpq_clear') between each initialization.
209
- Function: void mpq_clear (mpq_t RATIONAL_NUMBER)
210
Free the space occupied by RATIONAL_NUMBER. Make sure to call this
211
function for all `mpq_t' variables when you are done with them.
213
- Function: void mpq_set (mpq_t ROP, mpq_t OP)
214
- Function: void mpq_set_z (mpq_t ROP, mpz_t OP)
217
- Function: void mpq_set_ui (mpq_t ROP, unsigned long int OP1,
218
unsigned long int OP2)
219
- Function: void mpq_set_si (mpq_t ROP, signed long int OP1, unsigned
221
Set the value of ROP to OP1/OP2. Note that if OP1 and OP2 have
222
common factors, ROP has to be passed to `mpq_canonicalize' before
223
any operations are performed on ROP.
225
- Function: int mpq_set_str (mpq_t ROP, char *STR, int BASE)
226
Set ROP from a null-terminated string STR in the given BASE.
228
The string can be an integer like "41" or a fraction like
229
"41/152". The fraction must be in canonical form (*note Rational
230
Number Functions::), or if not then `mpq_canonicalize' must be
233
The numerator and optional denominator are parsed the same as in
234
`mpz_set_str' (*note Assigning Integers::). White space is
235
allowed in the string, and is simply ignored. The BASE can vary
236
from 2 to 36, or if BASE is 0 then the leading characters are
237
used: `0x' for hex, `0' for octal, or decimal otherwise. Note
238
that this is done separately for the numerator and denominator, so
239
for instance `0xEF/100' is 239/100, whereas `0xEF/0x100' is
242
The return value is 0 if the entire string is a valid number, or
245
- Function: void mpq_swap (mpq_t ROP1, mpq_t ROP2)
246
Swap the values ROP1 and ROP2 efficiently.
249
File: gmp.info, Node: Rational Conversions, Next: Rational Arithmetic, Prev: Initializing Rationals, Up: Rational Number Functions
254
- Function: double mpq_get_d (mpq_t OP)
255
Convert OP to a `double'.
257
- Function: void mpq_set_d (mpq_t ROP, double OP)
258
- Function: void mpq_set_f (mpq_t ROP, mpf_t OP)
259
Set ROP to the value of OP, without rounding.
261
- Function: char * mpq_get_str (char *STR, int BASE, mpq_t OP)
262
Convert OP to a string of digits in base BASE. The base may vary
263
from 2 to 36. The string will be of the form `num/den', or if the
264
denominator is 1 then just `num'.
266
If STR is `NULL', the result string is allocated using the current
267
allocation function (*note Custom Allocation::). The block will be
268
`strlen(str)+1' bytes, that being exactly enough for the string and
271
If STR is not `NULL', it should point to a block of storage large
272
enough for the result, that being
274
mpz_sizeinbase (mpq_numref(OP), BASE)
275
+ mpz_sizeinbase (mpq_denref(OP), BASE) + 3
277
The three extra bytes are for a possible minus sign, possible
278
slash, and the null-terminator.
280
A pointer to the result string is returned, being either the
281
allocated block, or the given STR.
284
File: gmp.info, Node: Rational Arithmetic, Next: Comparing Rationals, Prev: Rational Conversions, Up: Rational Number Functions
289
- Function: void mpq_add (mpq_t SUM, mpq_t ADDEND1, mpq_t ADDEND2)
290
Set SUM to ADDEND1 + ADDEND2.
292
- Function: void mpq_sub (mpq_t DIFFERENCE, mpq_t MINUEND, mpq_t
294
Set DIFFERENCE to MINUEND - SUBTRAHEND.
296
- Function: void mpq_mul (mpq_t PRODUCT, mpq_t MULTIPLIER, mpq_t
298
Set PRODUCT to MULTIPLIER times MULTIPLICAND.
300
- Function: void mpq_mul_2exp (mpq_t ROP, mpq_t OP1, unsigned long int
302
Set ROP to OP1 times 2 raised to OP2.
304
- Function: void mpq_div (mpq_t QUOTIENT, mpq_t DIVIDEND, mpq_t
306
Set QUOTIENT to DIVIDEND/DIVISOR.
308
- Function: void mpq_div_2exp (mpq_t ROP, mpq_t OP1, unsigned long int
310
Set ROP to OP1 divided by 2 raised to OP2.
312
- Function: void mpq_neg (mpq_t NEGATED_OPERAND, mpq_t OPERAND)
313
Set NEGATED_OPERAND to -OPERAND.
315
- Function: void mpq_abs (mpq_t ROP, mpq_t OP)
316
Set ROP to the absolute value of OP.
318
- Function: void mpq_inv (mpq_t INVERTED_NUMBER, mpq_t NUMBER)
319
Set INVERTED_NUMBER to 1/NUMBER. If the new denominator is zero,
320
this routine will divide by zero.
323
File: gmp.info, Node: Comparing Rationals, Next: Applying Integer Functions, Prev: Rational Arithmetic, Up: Rational Number Functions
328
- Function: int mpq_cmp (mpq_t OP1, mpq_t OP2)
329
Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero
330
if OP1 = OP2, and a negative value if OP1 < OP2.
332
To determine if two rationals are equal, `mpq_equal' is faster than
335
- Macro: int mpq_cmp_ui (mpq_t OP1, unsigned long int NUM2, unsigned
337
- Macro: int mpq_cmp_si (mpq_t OP1, long int NUM2, unsigned long int
339
Compare OP1 and NUM2/DEN2. Return a positive value if OP1 >
340
NUM2/DEN2, zero if OP1 = NUM2/DEN2, and a negative value if OP1 <
343
NUM2 and DEN2 are allowed to have common factors.
345
These functions are implemented as a macros and evaluate their
346
arguments multiple times.
348
- Macro: int mpq_sgn (mpq_t OP)
349
Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0.
351
This function is actually implemented as a macro. It evaluates its
352
arguments multiple times.
354
- Function: int mpq_equal (mpq_t OP1, mpq_t OP2)
355
Return non-zero if OP1 and OP2 are equal, zero if they are
356
non-equal. Although `mpq_cmp' can be used for the same purpose,
357
this function is much faster.
360
File: gmp.info, Node: Applying Integer Functions, Next: I/O of Rationals, Prev: Comparing Rationals, Up: Rational Number Functions
362
Applying Integer Functions to Rationals
363
=======================================
365
The set of `mpq' functions is quite small. In particular, there are
366
few functions for either input or output. The following functions give
367
direct access to the numerator and denominator of an `mpq_t'.
369
Note that if an assignment to the numerator and/or denominator could
370
take an `mpq_t' out of the canonical form described at the start of
371
this chapter (*note Rational Number Functions::) then
372
`mpq_canonicalize' must be called before any other `mpq' functions are
373
applied to that `mpq_t'.
375
- Macro: mpz_t mpq_numref (mpq_t OP)
376
- Macro: mpz_t mpq_denref (mpq_t OP)
377
Return a reference to the numerator and denominator of OP,
378
respectively. The `mpz' functions can be used on the result of
381
- Function: void mpq_get_num (mpz_t NUMERATOR, mpq_t RATIONAL)
382
- Function: void mpq_get_den (mpz_t DENOMINATOR, mpq_t RATIONAL)
383
- Function: void mpq_set_num (mpq_t RATIONAL, mpz_t NUMERATOR)
384
- Function: void mpq_set_den (mpq_t RATIONAL, mpz_t DENOMINATOR)
385
Get or set the numerator or denominator of a rational. These
386
functions are equivalent to calling `mpz_set' with an appropriate
387
`mpq_numref' or `mpq_denref'. Direct use of `mpq_numref' or
388
`mpq_denref' is recommended instead of these functions.
391
File: gmp.info, Node: I/O of Rationals, Prev: Applying Integer Functions, Up: Rational Number Functions
393
Input and Output Functions
394
==========================
396
When using any of these functions, it's a good idea to include
397
`stdio.h' before `gmp.h', since that will allow `gmp.h' to define
398
prototypes for these functions.
400
Passing a `NULL' pointer for a STREAM argument to any of these
401
functions will make them read from `stdin' and write to `stdout',
404
- Function: size_t mpq_out_str (FILE *STREAM, int BASE, mpq_t OP)
405
Output OP on stdio stream STREAM, as a string of digits in base
406
BASE. The base may vary from 2 to 36. Output is in the form
407
`num/den' or if the denominator is 1 then just `num'.
409
Return the number of bytes written, or if an error occurred,
412
- Function: size_t mpq_inp_str (mpq_t ROP, FILE *STREAM, int BASE)
413
Read a string of digits from STREAM and convert them to a rational
414
in ROP. Any initial white-space characters are read and
415
discarded. Return the number of characters read (including white
416
space), or 0 if a rational could not be read.
418
The input can be a fraction like `17/63' or just an integer like
419
`123'. Reading stops at the first character not in this form, and
420
white space is not permitted within the string. If the input
421
might not be in canonical form, then `mpq_canonicalize' must be
422
called (*note Rational Number Functions::).
424
The BASE can be between 2 and 36, or can be 0 in which case the
425
leading characters of the string determine the base, `0x' or `0X'
426
for hexadecimal, `0' for octal, or decimal otherwise. The leading
427
characters are examined separately for the numerator and
428
denominator of a fraction, so for instance `0x10/11' is 16/11,
429
whereas `0x10/0x11' is 16/17.
432
File: gmp.info, Node: Floating-point Functions, Next: Low-level Functions, Prev: Rational Number Functions, Up: Top
434
Floating-point Functions
435
************************
437
GMP floating point numbers are stored in objects of type `mpf_t' and
438
functions operating on them have an `mpf_' prefix.
440
The mantissa of each float has a user-selectable precision, limited
441
only by available memory. Each variable has its own precision, and
442
that can be increased or decreased at any time.
444
The exponent of each float is a fixed precision, one machine word on
445
most systems. In the current implementation the exponent is a count of
446
limbs, so for example on a 32-bit system this means a range of roughly
447
2^-68719476768 to 2^68719476736, or on a 64-bit system this will be
448
greater. Note however `mpf_get_str' can only return an exponent which
449
fits an `mp_exp_t' and currently `mpf_set_str' doesn't accept exponents
450
bigger than a `long'.
452
Each variable keeps a size for the mantissa data actually in use.
453
This means that if a float is exactly represented in only a few bits
454
then only those bits will be used in a calculation, even if the
455
selected precision is high.
457
All calculations are performed to the precision of the destination
458
variable. Each function is defined to calculate with "infinite
459
precision" followed by a truncation to the destination precision, but
460
of course the work done is only what's needed to determine a result
461
under that definition.
463
The precision selected for a variable is a minimum value, GMP may
464
increase it a little to facilitate efficient calculation. Currently
465
this means rounding up to a whole limb, and then sometimes having a
466
further partial limb, depending on the high limb of the mantissa. But
467
applications shouldn't be concerned by such details.
469
`mpf' functions and variables have no special notion of infinity or
470
not-a-number, and applications must take care not to overflow the
471
exponent or results will be unpredictable. This might change in a
474
Note that the `mpf' functions are _not_ intended as a smooth
475
extension to IEEE P754 arithmetic. In particular results obtained on
476
one computer often differ from the results on a computer with a
481
* Initializing Floats::
483
* Simultaneous Float Init & Assign::
484
* Converting Floats::
488
* Miscellaneous Float Functions::
491
File: gmp.info, Node: Initializing Floats, Next: Assigning Floats, Prev: Floating-point Functions, Up: Floating-point Functions
493
Initialization Functions
494
========================
496
- Function: void mpf_set_default_prec (unsigned long int PREC)
497
Set the default precision to be *at least* PREC bits. All
498
subsequent calls to `mpf_init' will use this precision, but
499
previously initialized variables are unaffected.
501
- Function: unsigned long int mpf_get_default_prec (void)
502
Return the default default precision actually used.
504
An `mpf_t' object must be initialized before storing the first value
505
in it. The functions `mpf_init' and `mpf_init2' are used for that
508
- Function: void mpf_init (mpf_t X)
509
Initialize X to 0. Normally, a variable should be initialized
510
once only or at least be cleared, using `mpf_clear', between
511
initializations. The precision of X is undefined unless a default
512
precision has already been established by a call to
513
`mpf_set_default_prec'.
515
- Function: void mpf_init2 (mpf_t X, unsigned long int PREC)
516
Initialize X to 0 and set its precision to be *at least* PREC
517
bits. Normally, a variable should be initialized once only or at
518
least be cleared, using `mpf_clear', between initializations.
520
- Function: void mpf_clear (mpf_t X)
521
Free the space occupied by X. Make sure to call this function for
522
all `mpf_t' variables when you are done with them.
524
Here is an example on how to initialize floating-point variables:
527
mpf_init (x); /* use default precision */
528
mpf_init2 (y, 256); /* precision _at least_ 256 bits */
530
/* Unless the program is about to exit, do ... */
535
The following three functions are useful for changing the precision
536
during a calculation. A typical use would be for adjusting the
537
precision gradually in iterative algorithms like Newton-Raphson, making
538
the computation precision closely match the actual accurate part of the
541
- Function: unsigned long int mpf_get_prec (mpf_t OP)
542
Return the current precision of OP, in bits.
544
- Function: void mpf_set_prec (mpf_t ROP, unsigned long int PREC)
545
Set the precision of ROP to be *at least* PREC bits. The value in
546
ROP will be truncated to the new precision.
548
This function requires a call to `realloc', and so should not be
549
used in a tight loop.
551
- Function: void mpf_set_prec_raw (mpf_t ROP, unsigned long int PREC)
552
Set the precision of ROP to be *at least* PREC bits, without
553
changing the memory allocated.
555
PREC must be no more than the allocated precision for ROP, that
556
being the precision when ROP was initialized, or in the most recent
559
The value in ROP is unchanged, and in particular if it had a higher
560
precision than PREC it will retain that higher precision. New
561
values written to ROP will use the new PREC.
563
Before calling `mpf_clear' or the full `mpf_set_prec', another
564
`mpf_set_prec_raw' call must be made to restore ROP to its original
565
allocated precision. Failing to do so will have unpredictable
568
`mpf_get_prec' can be used before `mpf_set_prec_raw' to get the
569
original allocated precision. After `mpf_set_prec_raw' it
570
reflects the PREC value set.
572
`mpf_set_prec_raw' is an efficient way to use an `mpf_t' variable
573
at different precisions during a calculation, perhaps to gradually
574
increase precision in an iteration, or just to use various
575
different precisions for different purposes during a calculation.
578
File: gmp.info, Node: Assigning Floats, Next: Simultaneous Float Init & Assign, Prev: Initializing Floats, Up: Floating-point Functions
583
These functions assign new values to already initialized floats
584
(*note Initializing Floats::).
586
- Function: void mpf_set (mpf_t ROP, mpf_t OP)
587
- Function: void mpf_set_ui (mpf_t ROP, unsigned long int OP)
588
- Function: void mpf_set_si (mpf_t ROP, signed long int OP)
589
- Function: void mpf_set_d (mpf_t ROP, double OP)
590
- Function: void mpf_set_z (mpf_t ROP, mpz_t OP)
591
- Function: void mpf_set_q (mpf_t ROP, mpq_t OP)
592
Set the value of ROP from OP.
594
- Function: int mpf_set_str (mpf_t ROP, char *STR, int BASE)
595
Set the value of ROP from the string in STR. The string is of the
596
form `M@N' or, if the base is 10 or less, alternatively `MeN'.
597
`M' is the mantissa and `N' is the exponent. The mantissa is
598
always in the specified base. The exponent is either in the
599
specified base or, if BASE is negative, in decimal. The decimal
600
point expected is taken from the current locale, on systems
601
providing `localeconv'.
603
The argument BASE may be in the ranges 2 to 36, or -36 to -2.
604
Negative values are used to specify that the exponent is in
607
Unlike the corresponding `mpz' function, the base will not be
608
determined from the leading characters of the string if BASE is 0.
609
This is so that numbers like `0.23' are not interpreted as octal.
611
White space is allowed in the string, and is simply ignored.
612
[This is not really true; white-space is ignored in the beginning
613
of the string and within the mantissa, but not in other places,
614
such as after a minus sign or in the exponent. We are considering
615
changing the definition of this function, making it fail when
616
there is any white-space in the input, since that makes a lot of
617
sense. Please tell us your opinion about this change. Do you
618
really want it to accept "3 14" as meaning 314 as it does now?]
620
This function returns 0 if the entire string is a valid number in
621
base BASE. Otherwise it returns -1.
623
- Function: void mpf_swap (mpf_t ROP1, mpf_t ROP2)
624
Swap ROP1 and ROP2 efficiently. Both the values and the
625
precisions of the two variables are swapped.
628
File: gmp.info, Node: Simultaneous Float Init & Assign, Next: Converting Floats, Prev: Assigning Floats, Up: Floating-point Functions
630
Combined Initialization and Assignment Functions
631
================================================
633
For convenience, GMP provides a parallel series of
634
initialize-and-set functions which initialize the output and then store
635
the value there. These functions' names have the form `mpf_init_set...'
637
Once the float has been initialized by any of the `mpf_init_set...'
638
functions, it can be used as the source or destination operand for the
639
ordinary float functions. Don't use an initialize-and-set function on
640
a variable already initialized!
642
- Function: void mpf_init_set (mpf_t ROP, mpf_t OP)
643
- Function: void mpf_init_set_ui (mpf_t ROP, unsigned long int OP)
644
- Function: void mpf_init_set_si (mpf_t ROP, signed long int OP)
645
- Function: void mpf_init_set_d (mpf_t ROP, double OP)
646
Initialize ROP and set its value from OP.
648
The precision of ROP will be taken from the active default
649
precision, as set by `mpf_set_default_prec'.
651
- Function: int mpf_init_set_str (mpf_t ROP, char *STR, int BASE)
652
Initialize ROP and set its value from the string in STR. See
653
`mpf_set_str' above for details on the assignment operation.
655
Note that ROP is initialized even if an error occurs. (I.e., you
656
have to call `mpf_clear' for it.)
658
The precision of ROP will be taken from the active default
659
precision, as set by `mpf_set_default_prec'.
662
File: gmp.info, Node: Converting Floats, Next: Float Arithmetic, Prev: Simultaneous Float Init & Assign, Up: Floating-point Functions
667
- Function: double mpf_get_d (mpf_t OP)
668
Convert OP to a `double'.
670
- Function: double mpf_get_d_2exp (signed long int EXP, mpf_t OP)
671
Find D and EXP such that D times 2 raised to EXP, with
672
0.5<=abs(D)<1, is a good approximation to OP. This is similar to
673
the standard C function `frexp'.
675
- Function: long mpf_get_si (mpf_t OP)
676
- Function: unsigned long mpf_get_ui (mpf_t OP)
677
Convert OP to a `long' or `unsigned long', truncating any fraction
678
part. If OP is too big for the return type, the result is
681
See also `mpf_fits_slong_p' and `mpf_fits_ulong_p' (*note
682
Miscellaneous Float Functions::).
684
- Function: char * mpf_get_str (char *STR, mp_exp_t *EXPPTR, int BASE,
685
size_t N_DIGITS, mpf_t OP)
686
Convert OP to a string of digits in base BASE. BASE can be 2 to
687
36. Up to N_DIGITS digits will be generated. Trailing zeros are
688
not returned. No more digits than can be accurately represented
689
by OP are ever generated. If N_DIGITS is 0 then that accurate
690
maximum number of digits are generated.
692
If STR is `NULL', the result string is allocated using the current
693
allocation function (*note Custom Allocation::). The block will be
694
`strlen(str)+1' bytes, that being exactly enough for the string and
697
If STR is not `NULL', it should point to a block of N_DIGITS + 2
698
bytes, that being enough for the mantissa, a possible minus sign,
699
and a null-terminator. When N_DIGITS is 0 to get all significant
700
digits, an application won't be able to know the space required,
701
and STR should be `NULL' in that case.
703
The generated string is a fraction, with an implicit radix point
704
immediately to the left of the first digit. The applicable
705
exponent is written through the EXPPTR pointer. For example, the
706
number 3.1416 would be returned as string "31416" and exponent 1.
708
When OP is zero, an empty string is produced and the exponent
711
A pointer to the result string is returned, being either the
712
allocated block or the given STR.
715
File: gmp.info, Node: Float Arithmetic, Next: Float Comparison, Prev: Converting Floats, Up: Floating-point Functions
720
- Function: void mpf_add (mpf_t ROP, mpf_t OP1, mpf_t OP2)
721
- Function: void mpf_add_ui (mpf_t ROP, mpf_t OP1, unsigned long int
723
Set ROP to OP1 + OP2.
725
- Function: void mpf_sub (mpf_t ROP, mpf_t OP1, mpf_t OP2)
726
- Function: void mpf_ui_sub (mpf_t ROP, unsigned long int OP1, mpf_t
728
- Function: void mpf_sub_ui (mpf_t ROP, mpf_t OP1, unsigned long int
730
Set ROP to OP1 - OP2.
732
- Function: void mpf_mul (mpf_t ROP, mpf_t OP1, mpf_t OP2)
733
- Function: void mpf_mul_ui (mpf_t ROP, mpf_t OP1, unsigned long int
735
Set ROP to OP1 times OP2.
737
Division is undefined if the divisor is zero, and passing a zero
738
divisor to the divide functions will make these functions intentionally
739
divide by zero. This lets the user handle arithmetic exceptions in
740
these functions in the same manner as other arithmetic exceptions.
742
- Function: void mpf_div (mpf_t ROP, mpf_t OP1, mpf_t OP2)
743
- Function: void mpf_ui_div (mpf_t ROP, unsigned long int OP1, mpf_t
745
- Function: void mpf_div_ui (mpf_t ROP, mpf_t OP1, unsigned long int
749
- Function: void mpf_sqrt (mpf_t ROP, mpf_t OP)
750
- Function: void mpf_sqrt_ui (mpf_t ROP, unsigned long int OP)
751
Set ROP to the square root of OP.
753
- Function: void mpf_pow_ui (mpf_t ROP, mpf_t OP1, unsigned long int
755
Set ROP to OP1 raised to the power OP2.
757
- Function: void mpf_neg (mpf_t ROP, mpf_t OP)
760
- Function: void mpf_abs (mpf_t ROP, mpf_t OP)
761
Set ROP to the absolute value of OP.
763
- Function: void mpf_mul_2exp (mpf_t ROP, mpf_t OP1, unsigned long int
765
Set ROP to OP1 times 2 raised to OP2.
767
- Function: void mpf_div_2exp (mpf_t ROP, mpf_t OP1, unsigned long int
769
Set ROP to OP1 divided by 2 raised to OP2.
772
File: gmp.info, Node: Float Comparison, Next: I/O of Floats, Prev: Float Arithmetic, Up: Floating-point Functions
777
- Function: int mpf_cmp (mpf_t OP1, mpf_t OP2)
778
- Function: int mpf_cmp_d (mpf_t OP1, double OP2)
779
- Function: int mpf_cmp_ui (mpf_t OP1, unsigned long int OP2)
780
- Function: int mpf_cmp_si (mpf_t OP1, signed long int OP2)
781
Compare OP1 and OP2. Return a positive value if OP1 > OP2, zero
782
if OP1 = OP2, and a negative value if OP1 < OP2.
784
- Function: int mpf_eq (mpf_t OP1, mpf_t OP2, unsigned long int op3)
785
Return non-zero if the first OP3 bits of OP1 and OP2 are equal,
786
zero otherwise. I.e., test of OP1 and OP2 are approximately equal.
788
Caution: Currently only whole limbs are compared, and only in an
789
exact fashion. In the future values like 1000 and 0111 may be
790
considered the same to 3 bits (on the basis that their difference
793
- Function: void mpf_reldiff (mpf_t ROP, mpf_t OP1, mpf_t OP2)
794
Compute the relative difference between OP1 and OP2 and store the
795
result in ROP. This is abs(OP1-OP2)/OP1.
797
- Macro: int mpf_sgn (mpf_t OP)
798
Return +1 if OP > 0, 0 if OP = 0, and -1 if OP < 0.
800
This function is actually implemented as a macro. It evaluates
801
its arguments multiple times.
804
File: gmp.info, Node: I/O of Floats, Next: Miscellaneous Float Functions, Prev: Float Comparison, Up: Floating-point Functions
806
Input and Output Functions
807
==========================
809
Functions that perform input from a stdio stream, and functions that
810
output to a stdio stream. Passing a `NULL' pointer for a STREAM
811
argument to any of these functions will make them read from `stdin' and
812
write to `stdout', respectively.
814
When using any of these functions, it is a good idea to include
815
`stdio.h' before `gmp.h', since that will allow `gmp.h' to define
816
prototypes for these functions.
818
- Function: size_t mpf_out_str (FILE *STREAM, int BASE, size_t
820
Print OP to STREAM, as a string of digits. Return the number of
821
bytes written, or if an error occurred, return 0.
823
The mantissa is prefixed with an `0.' and is in the given BASE,
824
which may vary from 2 to 36. An exponent then printed, separated
825
by an `e', or if BASE is greater than 10 then by an `@'. The
826
exponent is always in decimal. The decimal point follows the
827
current locale, on systems providing `localeconv'.
829
Up to N_DIGITS will be printed from the mantissa, except that no
830
more digits than are accurately representable by OP will be
831
printed. N_DIGITS can be 0 to select that accurate maximum.
833
- Function: size_t mpf_inp_str (mpf_t ROP, FILE *STREAM, int BASE)
834
Read a string in base BASE from STREAM, and put the read float in
835
ROP. The string is of the form `M@N' or, if the base is 10 or
836
less, alternatively `MeN'. `M' is the mantissa and `N' is the
837
exponent. The mantissa is always in the specified base. The
838
exponent is either in the specified base or, if BASE is negative,
839
in decimal. The decimal point expected is taken from the current
840
locale, on systems providing `localeconv'.
842
The argument BASE may be in the ranges 2 to 36, or -36 to -2.
843
Negative values are used to specify that the exponent is in
846
Unlike the corresponding `mpz' function, the base will not be
847
determined from the leading characters of the string if BASE is 0.
848
This is so that numbers like `0.23' are not interpreted as octal.
850
Return the number of bytes read, or if an error occurred, return 0.
853
File: gmp.info, Node: Miscellaneous Float Functions, Prev: I/O of Floats, Up: Floating-point Functions
855
Miscellaneous Functions
856
=======================
858
- Function: void mpf_ceil (mpf_t ROP, mpf_t OP)
859
- Function: void mpf_floor (mpf_t ROP, mpf_t OP)
860
- Function: void mpf_trunc (mpf_t ROP, mpf_t OP)
861
Set ROP to OP rounded to an integer. `mpf_ceil' rounds to the
862
next higher integer, `mpf_floor' to the next lower, and `mpf_trunc'
863
to the integer towards zero.
865
- Function: int mpf_integer_p (mpf_t OP)
866
Return non-zero if OP is an integer.
868
- Function: int mpf_fits_ulong_p (mpf_t OP)
869
- Function: int mpf_fits_slong_p (mpf_t OP)
870
- Function: int mpf_fits_uint_p (mpf_t OP)
871
- Function: int mpf_fits_sint_p (mpf_t OP)
872
- Function: int mpf_fits_ushort_p (mpf_t OP)
873
- Function: int mpf_fits_sshort_p (mpf_t OP)
874
Return non-zero if OP would fit in the respective C data type, when
875
truncated to an integer.
877
- Function: void mpf_urandomb (mpf_t ROP, gmp_randstate_t STATE,
878
unsigned long int NBITS)
879
Generate a uniformly distributed random float in ROP, such that 0
880
<= ROP < 1, with NBITS significant bits in the mantissa.
882
The variable STATE must be initialized by calling one of the
883
`gmp_randinit' functions (*Note Random State Initialization::)
884
before invoking this function.
886
- Function: void mpf_random2 (mpf_t ROP, mp_size_t MAX_SIZE, mp_exp_t
888
Generate a random float of at most MAX_SIZE limbs, with long
889
strings of zeros and ones in the binary representation. The
890
exponent of the number is in the interval -EXP to EXP. This
891
function is useful for testing functions and algorithms, since
892
this kind of random numbers have proven to be more likely to
893
trigger corner-case bugs. Negative random numbers are generated
894
when MAX_SIZE is negative.
added
removed
gmp3/gmp.info-3
