Next: Floating-point Functions, Previous: Integer Functions, Up: GNU MP [Index]
This chapter describes the GMP functions for performing arithmetic on rational
numbers. These functions start with the prefix mpq_
.
Rational numbers are stored in objects of type mpq_t
.
All rational arithmetic functions assume operands have a canonical form, and canonicalize their result. The canonical form means that the denominator and the numerator have no common factors, and that the denominator is positive. Zero has the unique representation 0/1.
Pure assignment functions do not canonicalize the assigned variable. It is the responsibility of the user to canonicalize the assigned variable before any arithmetic operations are performed on that variable.
Remove any factors that are common to the numerator and denominator of op, and make the denominator positive.
Next: Conversion Functions, Previous: Rational Number Functions, Up: Rational Number Functions [Index]
Initialize x and set it to 0/1. Each variable should normally only be
initialized once, or at least cleared out (using the function mpq_clear
)
between each initialization.
Initialize a NULL-terminated list of mpq_t
variables, and set their
values to 0/1.
Free the space occupied by x. Make sure to call this function for all
mpq_t
variables when you are done with them.
Free the space occupied by a NULL-terminated list of mpq_t
variables.
Assign rop from op.
Set the value of rop to op1/op2. Note that if op1 and
op2 have common factors, rop has to be passed to
mpq_canonicalize
before any operations are performed on rop.
Set rop from a null-terminated string str in the given base.
The string can be an integer like “41” or a fraction like “41/152”. The
fraction must be in canonical form (see Rational Number Functions), or if
not then mpq_canonicalize
must be called.
The numerator and optional denominator are parsed the same as in
mpz_set_str
(see Assignment Functions). White space is allowed in
the string, and is simply ignored. The base can vary from 2 to 62, or
if base is 0 then the leading characters are used: 0x
or 0X
for hex,
0b
or 0B
for binary,
0
for octal, or decimal otherwise. Note that this is done separately
for the numerator and denominator, so for instance 0xEF/100
is 239/100,
whereas 0xEF/0x100
is 239/256.
The return value is 0 if the entire string is a valid number, or -1 if not.
Swap the values rop1 and rop2 efficiently.
Next: Arithmetic Functions, Previous: Initialization and Assignment Functions, Up: Rational Number Functions [Index]
Convert op to a double
, truncating if necessary (i.e. rounding
towards zero).
If the exponent from the conversion is too big or too small to fit a
double
then the result is system dependent. For too big an infinity is
returned when available. For too small 0.0 is normally returned.
Hardware overflow, underflow and denorm traps may or may not occur.
Set rop to the value of op. There is no rounding, this conversion is exact.
Convert op to a string of digits in base base. The base argument may vary from 2 to 62 or from -2 to -36. The string will be of the form ‘num/den’, or if the denominator is 1 then just ‘num’.
For base in the range 2..36, digits and lower-case letters are used; for -2..-36, digits and upper-case letters are used; for 37..62, digits, upper-case letters, and lower-case letters (in that significance order) are used.
If str is NULL
, the result string is allocated using the current
allocation function (see Custom Allocation). The block will be
strlen(str)+1
bytes, that being exactly enough for the string and
null-terminator.
If str is not NULL
, it should point to a block of storage large
enough for the result, that being
mpz_sizeinbase (mpq_numref(op), base) + mpz_sizeinbase (mpq_denref(op), base) + 3
The three extra bytes are for a possible minus sign, possible slash, and the null-terminator.
A pointer to the result string is returned, being either the allocated block, or the given str.
Next: Comparison Functions, Previous: Conversion Functions, Up: Rational Number Functions [Index]
Set sum to addend1 + addend2.
Set difference to minuend - subtrahend.
Set product to multiplier times multiplicand.
Set rop to op1 times 2 raised to op2.
Set quotient to dividend/divisor.
Set rop to op1 divided by 2 raised to op2.
Set negated_operand to -operand.
Set rop to the absolute value of op.
Set inverted_number to 1/number. If the new denominator is zero, this routine will divide by zero.
Next: Applying Integer Functions to Rationals, Previous: Arithmetic Functions, Up: Rational Number Functions [Index]
Compare op1 and op2. Return a positive value if op1 > op2, zero if op1 = op2, and a negative value if op1 < op2.
To determine if two rationals are equal, mpq_equal
is faster than
mpq_cmp
.
Compare op1 and num2/den2. Return a positive value if op1 > num2/den2, zero if op1 = num2/den2, and a negative value if op1 < num2/den2.
num2 and den2 are allowed to have common factors.
These functions are implemented as a macros and evaluate their arguments multiple times.
Return +1 if op > 0, 0 if op = 0, and -1 if op < 0.
This function is actually implemented as a macro. It evaluates its argument multiple times.
Return non-zero if op1 and op2 are equal, zero if they are
non-equal. Although mpq_cmp
can be used for the same purpose, this
function is much faster.
Next: Input and Output Functions, Previous: Comparison Functions, Up: Rational Number Functions [Index]
The set of mpq
functions is quite small. In particular, there are few
functions for either input or output. The following functions give direct
access to the numerator and denominator of an mpq_t
.
Note that if an assignment to the numerator and/or denominator could take an
mpq_t
out of the canonical form described at the start of this chapter
(see Rational Number Functions) then mpq_canonicalize
must be
called before any other mpq
functions are applied to that mpq_t
.
Return a reference to the numerator and denominator of op, respectively.
The mpz
functions can be used on the result of these macros.
Get or set the numerator or denominator of a rational. These functions are
equivalent to calling mpz_set
with an appropriate mpq_numref
or
mpq_denref
. Direct use of mpq_numref
or mpq_denref
is
recommended instead of these functions.
Previous: Applying Integer Functions to Rationals, Up: Rational Number Functions [Index]
Functions that perform input from a stdio stream, and functions that output to
a stdio stream, of mpq
numbers. Passing a NULL
pointer for a
stream argument to any of these functions will make them read from
stdin
and write to stdout
, respectively.
When using any of these functions, it is a good idea to include stdio.h before gmp.h, since that will allow gmp.h to define prototypes for these functions.
See also Formatted Output and Formatted Input.
Output op on stdio stream stream, as a string of digits in base base. The base argument may vary from 2 to 62 or from -2 to -36. Output is in the form ‘num/den’ or if the denominator is 1 then just ‘num’.
For base in the range 2..36, digits and lower-case letters are used; for -2..-36, digits and upper-case letters are used; for 37..62, digits, upper-case letters, and lower-case letters (in that significance order) are used.
Return the number of bytes written, or if an error occurred, return 0.
Read a string of digits from stream and convert them to a rational in rop. Any initial white-space characters are read and discarded. Return the number of characters read (including white space), or 0 if a rational could not be read.
The input can be a fraction like ‘17/63’ or just an integer like
‘123’. Reading stops at the first character not in this form, and white
space is not permitted within the string. If the input might not be in
canonical form, then mpq_canonicalize
must be called (see Rational Number Functions).
The base can be between 2 and 62, or can be 0 in which case the leading
characters of the string determine the base, ‘0x’ or ‘0X’ for
hexadecimal, 0b
and 0B
for binary, ‘0’ for octal, or
decimal otherwise. The leading characters
are examined separately for the numerator and denominator of a fraction, so
for instance ‘0x10/11’ is 16/11, whereas ‘0x10/0x11’ is
16/17.
Next: Floating-point Functions, Previous: Integer Functions, Up: GNU MP [Index]