Rational Number Functions

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 from 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. Note that this is an incompatible change from version 1 of the library.

Function: void mpq_canonicalize (mpq_t op)
Remove any factors that are common to the numerator and denominator of op, and make the denominator positive.

Initialization and Assignment Functions

Function: void mpq_init (mpq_t dest_rational)
Initialize dest_rational 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.

Function: void mpq_clear (mpq_t rational_number)
Free the space occupied by rational_number. Make sure to call this function for all mpq_t variables when you are done with them.

Function: void mpq_set (mpq_t rop, mpq_t op)
Function: void mpq_set_z (mpq_t rop, mpz_t op)
Assign rop from op.

Function: void mpq_set_ui (mpq_t rop, unsigned long int op1, unsigned long int op2)
Function: void mpq_set_si (mpq_t rop, signed long int op1, unsigned long int op2)
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.

Function: void mpq_swap (mpq_t rop1, mpq_t rop2)
Swap the values rop1 and rop2 efficiently.

Arithmetic Functions

Function: void mpq_sub (mpq_t difference, mpq_t minuend, mpq_t subtrahend)
Set difference to minuend - subtrahend.

Function: void mpq_mul (mpq_t product, mpq_t multiplier, mpq_t multiplicand)
@ifnottex Set product to multiplier times multiplicand.

Function: void mpq_div (mpq_t quotient, mpq_t dividend, mpq_t divisor)
Set quotient to dividend/divisor.

Function: void mpq_neg (mpq_t negated_operand, mpq_t operand)
Set negated_operand to -operand.

Function: void mpq_inv (mpq_t inverted_number, mpq_t number)
Set inverted_number to 1/number. If the new denominator is zero, this routine will divide by zero.

Comparison Functions

Function: int mpq_cmp (mpq_t op1, mpq_t op2)
@ifnottex 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.

Macro: int mpq_cmp_ui (mpq_t op1, unsigned long int num2, unsigned long int den2)
@ifnottex 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.

This routine allows that num2 and den2 have common factors.

This function is actually implemented as a macro. It evaluates its arguments multiple times.

Macro: int mpq_sgn (mpq_t op)
@ifnottex 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 arguments multiple times.

Function: int mpq_equal (mpq_t op1, mpq_t op2)
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.

Applying Integer Functions to Rationals

The set of mpq functions is quite small. In particular, there are few functions for either input or output. But there are two macros that allow us to apply any mpz function on the numerator or denominator of a rational number. If these macros are used to assign to the rational number, mpq_canonicalize normally need to be called afterwards.

Macro: mpz_t mpq_numref (mpq_t op)
Macro: mpz_t mpq_denref (mpq_t op)
Return a reference to the numerator and denominator of op, respectively. The mpz functions can be used on the result of these macros.

Input and Output Functions

Functions that perform input from a stdio stream, and functions that output to a stdio stream. 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.

Function: size_t mpq_out_str (FILE *stream, int base, mpq_t op)
Output op on stdio stream stream, as a string of digits in base base. The base may vary from 2 to 36. Output is in the form `num/den' or if the denominator is 1 then just `num'.

Return the number of bytes written, or if an error occurred, return 0.

Miscellaneous Functions

Function: double mpq_get_d (mpq_t op)
Convert op to a double.

Function: void mpq_set_d (mpq_t rop, double d)
Set rop to the value of d, without rounding.

These functions assign between either the numerator or denominator of a rational, and an integer. Instead of using these functions, it is preferable to use the more general mechanisms mpq_numref and mpq_denref, together with mpz_set.

Function: void mpq_set_num (mpq_t rational, mpz_t numerator)
Copy numerator to the numerator of rational. When this risks to make the numerator and denominator of rational have common factors, you have to pass rational to mpq_canonicalize before any operations are performed on rational.

This function is equivalent to mpz_set (mpq_numref (rational), numerator).

Function: void mpq_set_den (mpq_t rational, mpz_t denominator)
Copy denominator to the denominator of rational. When this risks to make the numerator and denominator of rational have common factors, or if the denominator might be negative, you have to pass rational to mpq_canonicalize before any operations are performed on rational.

In version 1 of the library, negative denominators were handled by copying the sign to the numerator. That is no longer done.

This function is equivalent to mpz_set (mpq_denref (rational), denominators).

Function: void mpq_get_num (mpz_t numerator, mpq_t rational)
Copy the numerator of rational to the integer numerator, to prepare for integer operations on the numerator.

This function is equivalent to mpz_set (numerator, mpq_numref (rational)).

Function: void mpq_get_den (mpz_t denominator, mpq_t rational)
Copy the denominator of rational to the integer denominator, to prepare for integer operations on the denominator.

This function is equivalent to mpz_set (denominator, mpq_denref (rational)).