# Constant gmp_mpfr_sys::C::GMP::Rational_Number_Functions [−][src]

pub const Rational_Number_Functions: ();

This constant is a place-holder for documentation; do not use it in code.

Next: Floating-point Functions, Previous: Integer Functions, Up: Top [Index]

## 6 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 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.

- 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.

• Initializing Rationals | ||

• Rational Conversions | ||

• Rational Arithmetic | ||

• Comparing Rationals | ||

• Applying Integer Functions | ||

• I/O of Rationals |

Next: Rational Conversions, Previous: Rational Number Functions, Up: Rational Number Functions [Index]

### 6.1 Initialization and Assignment Functions

- Function:
*void***mpq_init***(mpq_t*`x`) 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.

- Function:
*void***mpq_inits***(mpq_t*`x`, ...) Initialize a NULL-terminated list of

`mpq_t`

variables, and set their values to 0/1.

- Function:
*void***mpq_clear***(mpq_t*`x`) Free the space occupied by

`x`. Make sure to call this function for all`mpq_t`

variables when you are done with them.

- Function:
*void***mpq_clears***(mpq_t*`x`, ...) Free the space occupied by a NULL-terminated list of

`mpq_t`

variables.

- Function:
*void***mpq_set***(mpq_t*`rop`, const mpq_t`op`) - Function:
*void***mpq_set_z***(mpq_t*`rop`, const 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:
*int***mpq_set_str***(mpq_t*`rop`, const char *`str`, int`base`) 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 Assigning Integers). 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.

- Function:
*void***mpq_swap***(mpq_t*`rop1`, mpq_t`rop2`) Swap the values

`rop1`and`rop2`efficiently.

Next: Rational Arithmetic, Previous: Initializing Rationals, Up: Rational Number Functions [Index]

### 6.2 Conversion Functions

- Function:
*double***mpq_get_d***(const mpq_t*`op`) 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.

- Function:
*void***mpq_set_d***(mpq_t*`rop`, double`op`) - Function:
*void***mpq_set_f***(mpq_t*`rop`, const mpf_t`op`) Set

`rop`to the value of`op`. There is no rounding, this conversion is exact.

- Function:
*char ****mpq_get_str***(char **`str`, int`base`, const mpq_t`op`) 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 beingmpz_sizeinbase (mpq_numref(

`op`),`base`) + mpz_sizeinbase (mpq_denref(`op`),`base`) + 3The 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: Comparing Rationals, Previous: Rational Conversions, Up: Rational Number Functions [Index]

### 6.3 Arithmetic Functions

- Function:
*void***mpq_add***(mpq_t*`sum`, const mpq_t`addend1`, const mpq_t`addend2`) Set

`sum`to`addend1`+`addend2`.

- Function:
*void***mpq_sub***(mpq_t*`difference`, const mpq_t`minuend`, const mpq_t`subtrahend`) Set

`difference`to`minuend`-`subtrahend`.

- Function:
*void***mpq_mul***(mpq_t*`product`, const mpq_t`multiplier`, const mpq_t`multiplicand`) Set

`product`to.`multiplier`times`multiplicand`

- Function:
*void***mpq_mul_2exp***(mpq_t*`rop`, const mpq_t`op1`, mp_bitcnt_t`op2`) Set

`rop`to.`op1`times 2 raised to`op2`

- Function:
*void***mpq_div***(mpq_t*`quotient`, const mpq_t`dividend`, const mpq_t`divisor`) -
Set

`quotient`to`dividend`/`divisor`.

- Function:
*void***mpq_div_2exp***(mpq_t*`rop`, const mpq_t`op1`, mp_bitcnt_t`op2`) Set

`rop`to.`op1`divided by 2 raised to`op2`

- Function:
*void***mpq_neg***(mpq_t*`negated_operand`, const mpq_t`operand`) Set

`negated_operand`to -`operand`.

- Function:
*void***mpq_abs***(mpq_t*`rop`, const mpq_t`op`) Set

`rop`to the absolute value of`op`.

- Function:
*void***mpq_inv***(mpq_t*`inverted_number`, const mpq_t`number`) Set

`inverted_number`to 1/`number`. If the new denominator is zero, this routine will divide by zero.

Next: Applying Integer Functions, Previous: Rational Arithmetic, Up: Rational Number Functions [Index]

### 6.4 Comparison Functions

- Function:
*int***mpq_cmp***(const mpq_t*`op1`, const mpq_t`op2`) - Function:
*int***mpq_cmp_z***(const mpq_t*`op1`, const mpz_t`op2`) Compare

`op1`and`op2`. Return a positive value if, zero if`op1`>`op2`, and a negative value if`op1`=`op2`.`op1`<`op2`To determine if two rationals are equal,

`mpq_equal`

is faster than`mpq_cmp`

.

- Macro:
*int***mpq_cmp_ui***(const mpq_t*`op1`, unsigned long int`num2`, unsigned long int`den2`) - Macro:
*int***mpq_cmp_si***(const mpq_t*`op1`, long int`num2`, unsigned long int`den2`) Compare

`op1`and`num2`/`den2`. Return a positive value if, zero if`op1`>`num2`/`den2`, and a negative value if`op1`=`num2`/`den2`.`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.

- Macro:
*int***mpq_sgn***(const mpq_t*`op`) -
Return

*+1*if, 0 if`op`> 0, and`op`= 0*-1*if.`op`< 0This function is actually implemented as a macro. It evaluates its argument multiple times.

- Function:
*int***mpq_equal***(const mpq_t*`op1`, const 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.

Next: I/O of Rationals, Previous: Comparing Rationals, Up: Rational Number Functions [Index]

### 6.5 Applying Integer Functions to Rationals

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`

.

- Macro:
*mpz_t***mpq_numref***(const mpq_t*`op`) - Macro:
*mpz_t***mpq_denref***(const 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.

- Function:
*void***mpq_get_num***(mpz_t*`numerator`, const mpq_t`rational`) - Function:
*void***mpq_get_den***(mpz_t*`denominator`, const mpq_t`rational`) - Function:
*void***mpq_set_num***(mpq_t*`rational`, const mpz_t`numerator`) - Function:
*void***mpq_set_den***(mpq_t*`rational`, const mpz_t`denominator`) 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, Up: Rational Number Functions [Index]

### 6.6 Input and Output Functions

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.

- Function:
*size_t***mpq_out_str***(FILE **`stream`, int`base`, const mpq_t`op`) 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.

- Function:
*size_t***mpq_inp_str***(mpq_t*`rop`, FILE *`stream`, int`base`) 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*.

Previous: Applying Integer Functions, Up: Rational Number Functions [Index]