# struct BigRational

- BigRational
- Number
- Value
- Object

##
Overview

Rational numbers are represented as the quotient of arbitrarily large numerators and denominators. Rationals are canonicalized such that the denominator and the numerator have no common factors, and that the denominator is positive. Zero has the unique representation 0/1.

NOTE To use `BigRational`, you must explicitly import it with `require "big"`

    require "big"

    r = BigRational.new(7.to_big_i, 3.to_big_i)
    r.to_s # => "7/3"

    r = BigRational.new(3, -9)
    r.to_s # => "-1/3"

It is implemented under the hood with GMP.

##
Included Modules

- Comparable(BigDecimal)
- Comparable(Float)
- Comparable(Int)
- Comparable(BigRational)

##
Defined in:

big.cr
big/big_decimal.cr
big/big_rational.cr
big/number.cr

##
Constructors

- .new(numerator : Int, denominator : Int)

  Creates a new `BigRational`.

- .new(num : Int)

  Creates a new `BigRational` with num as the numerator and 1 for denominator.

- .new(num : Float::Primitive)

  Creates an exact representation of float as rational.

- .new(num : BigFloat)

  Creates an exact representation of float as rational.

- .new(num : BigRational)

  Creates a `BigRational` from the given num.

- .new(num : BigDecimal)

  Creates a `BigRational` from the given num.

##
Instance Method Summary

- #%(other : BigRational) : BigRational
- #%(other : Int) : BigRational
- #*(other : BigRational) : BigRational
- #*(other : Int) : BigRational
- #**(other : Int) : BigRational

  Raises the rational to the otherth power

- #+(other : BigRational) : BigRational
- #+(other : Int) : BigRational
- #-(other : BigRational) : BigRational
- #-(other : Int) : BigRational
- #- : BigRational
- #/(other : BigRational) : BigRational
- #/(other : BigInt) : BigRational
- #/(other : BigFloat) : BigRational
- #/(other : BigDecimal) : BigRational
- #/(other : Int8) : BigRational
- #/(other : UInt8) : BigRational
- #/(other : Int16) : BigRational
- #/(other : UInt16) : BigRational
- #/(other : Int32) : BigRational
- #/(other : UInt32) : BigRational
- #/(other : Int64) : BigRational
- #/(other : UInt64) : BigRational
- #/(other : Int128) : BigRational
- #/(other : UInt128) : BigRational
- #/(other : Float32) : BigRational
- #/(other : Float64) : BigRational
- #//(other : BigRational) : BigRational
- #//(other : Int) : BigRational
- #<<(other : Int) : BigRational

  Multiplies the rational by (2 ** other)

- #<=>(other : BigRational)
- #<=>(other : Float::Primitive)
- #<=>(other : BigFloat)
- #<=>(other : BigInt)
- #<=>(other : Int)
- #<=>(other : BigDecimal)

  The comparison operator.

- #==(other : BigRational) : Bool
- #>>(other : Int) : BigRational

  Divides the rational by (2 ** other)

- #abs : BigRational

  Returns the absolute value of this number.

- #ceil : BigRational
- #clone
- #denominator : BigInt
- #floor : BigRational
- #format(io : IO, separator = '.', delimiter = ',', decimal_places : Int | Nil = nil, *, group : Int = 3, only_significant : Bool = false) : Nil

  Prints this number as a `String` using a customizable format.

- #inspect(io : IO) : Nil

  Prints to io an unambiguous and information-rich string representation of this object, typically intended for developers.

- #inspect : String

  Returns an unambiguous and information-rich string representation of this object, typically intended for developers.

- #integer? : Bool

  Returns `true` if `self` is an integer.

- #inv : BigRational

  Returns a new `BigRational` as 1/r.

- #numerator : BigInt
- #remainder(other : BigRational) : BigRational
- #remainder(other : Int) : BigRational
- #round_away : BigRational
- #round_even : BigRational
- #tdiv(other : BigRational) : BigRational
- #tdiv(other : Int) : BigRational
- #to_big_d : BigDecimal

  Converts `self` to `BigDecimal`.

- #to_big_f : BigFloat
- #to_big_i : BigInt
- #to_big_r : BigRational

  Returns `self`.

- #to_f : Float64

  Returns the `Float64` representing this rational.

- #to_f! : Float64
- #to_f32 : Float32
- #to_f32! : Float32
- #to_f64 : Float64
- #to_f64! : Float64
- #to_i16(*args, **options)
- #to_i16(*args, **options, &)
- #to_i32(*args, **options)
- #to_i32(*args, **options, &)
- #to_i64(*args, **options)
- #to_i64(*args, **options, &)
- #to_i8(*args, **options)
- #to_i8(*args, **options, &)
- #to_s(base : Int = 10) : String

  Returns the string representing this rational.

- #to_s(io : IO, base : Int = 10) : Nil

  Prints a nicely readable and concise string representation of this object, typically intended for users, to io.

- #to_u16(*args, **options)
- #to_u16(*args, **options, &)
- #to_u32(*args, **options)
- #to_u32(*args, **options, &)
- #to_u64(*args, **options)
- #to_u64(*args, **options, &)
- #to_u8(*args, **options)
- #to_u8(*args, **options, &)
- #to_unsafe
- #trunc : BigRational

### Instance methods inherited from module `Comparable(BigDecimal)`

<(other : T) : Bool <, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) : Bool >, >=(other : T) >=, clamp(min, max)
clamp(range : Range) clamp

### Instance methods inherited from module `Comparable(Float)`

<(other : T) : Bool <, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) : Bool >, >=(other : T) >=, clamp(min, max)
clamp(range : Range) clamp

### Instance methods inherited from module `Comparable(Int)`

<(other : T) : Bool <, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) : Bool >, >=(other : T) >=, clamp(min, max)
clamp(range : Range) clamp

### Instance methods inherited from module `Comparable(BigRational)`

<(other : T) : Bool <, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) : Bool >, >=(other : T) >=, clamp(min, max)
clamp(range : Range) clamp

### Instance methods inherited from struct `Number`

*(other : BigFloat) : BigFloat
*(other : Complex) : Complex *, +(other : BigFloat)
+(other : Complex) : Complex
+ +, -(other : BigFloat)
-(other : Complex) : Complex -, /(other : BigFloat) : BigFloat
/(other : Complex) : Complex /, //(other) //, <=>(other) : Int32 | Nil <=>, ==(other : Complex) ==, abs : self abs, abs2 abs2, cis : Complex cis, divmod(number) divmod, format(io : IO, separator = '.', delimiter = ',', decimal_places : Int | Nil = nil, *, group : Int = 3, only_significant : Bool = false) : Nil
format(separator = '.', delimiter = ',', decimal_places : Int | Nil = nil, *, group : Int = 3, only_significant : Bool = false) : String format, hash(hasher) hash, humanize(io : IO, precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, unit_separator = nil, prefixes : Indexable = SI_PREFIXES) : Nil
humanize(io : IO, precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, unit_separator = nil, prefixes : Proc) : Nil
humanize(precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, unit_separator = nil, prefixes = SI_PREFIXES) : String
humanize(io : IO, precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, unit_separator = nil, &prefixes : Int32, Float64 -> Tuple(Int32, _) | Tuple(Int32, _, Bool)) : Nil
humanize(precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, unit_separator = nil, &) : String
humanize(precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, unit_separator = nil, prefixes : Proc) : String humanize, i : Complex i, integer? : Bool integer?, negative? : Bool negative?, positive? : Bool positive?, round(mode : RoundingMode = :ties_even) : self
round(digits : Number, base = 10, *, mode : RoundingMode = :ties_even) round, sign : Int32 sign, significant(digits, base = 10) significant, step(*, to limit = nil, exclusive : Bool = false, &) : Nil
step(*, to limit = nil, exclusive : Bool = false) step, to_big_f : BigFloat to_big_f, to_c : Complex to_c, to_yaml(yaml : YAML::Nodes::Builder) : Nil to_yaml, zero? : Bool zero?

### Constructor methods inherited from struct `Number`

additive_identity : self additive_identity, multiplicative_identity : self multiplicative_identity, zero : self zero

### Class methods inherited from struct `Number`

si_prefix(magnitude : Int, prefixes = SI_PREFIXES) : Char | Nil si_prefix

### Macros inherited from struct `Number`

[](*nums) [], slice(*nums, read_only = false) slice, static_array(*nums) static_array

### Instance methods inherited from module `Comparable(BigFloat)`

<(other : T) : Bool <, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) : Bool >, >=(other : T) >=, clamp(min, max)
clamp(range : Range) clamp

### Instance methods inherited from module `Steppable`

step(*, to limit = nil, by step, exclusive : Bool = false, &) : Nil
step(*, to limit = nil, by step, exclusive : Bool = false) step

### Instance methods inherited from module `Comparable(Number)`

<(other : T) : Bool <, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) : Bool >, >=(other : T) >=, clamp(min, max)
clamp(range : Range) clamp

### Instance methods inherited from struct `Value`

==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, dup dup

### Instance methods inherited from class `Object`

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash hash, in?(collection : Object) : Bool
in?(*values : Object) : Bool in?, inspect(io : IO) : Nil
inspect : String inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO) : Nil
to_json : String to_json, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil to_pretty_json, to_s(io : IO) : Nil
to_s : String to_s, to_yaml(io : IO) : Nil
to_yaml : String to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

### Class methods inherited from class `Object`

from_json(string_or_io, root : String)
from_json(string_or_io) from_json, from_yaml(string_or_io : String | IO) from_yaml

### Macros inherited from class `Object`

class_getter(*names, &block) class_getter, class_getter!(*names) class_getter!, class_getter?(*names, &block) class_getter?, class_property(*names, &block) class_property, class_property!(*names) class_property!, class_property?(*names, &block) class_property?, class_setter(*names) class_setter, def_clone def_clone, def_equals(*fields) def_equals, def_equals_and_hash(*fields) def_equals_and_hash, def_hash(*fields) def_hash, delegate(*methods, to object) delegate, forward_missing_to(delegate) forward_missing_to, getter(*names, &block) getter, getter!(*names) getter!, getter?(*names, &block) getter?, property(*names, &block) property, property!(*names) property!, property?(*names, &block) property?, setter(*names) setter

##
Constructor Detail

def self.new(numerator : Int, denominator : Int) #

Creates a new `BigRational`.

If denominator is 0, this will raise an exception.

def self.new(num : Int) #

Creates a new `BigRational` with num as the numerator and 1 for denominator.

def self.new(num : Float::Primitive) #

Creates an exact representation of float as rational.

Raises `ArgumentError` if num is not finite.

def self.new(num : BigFloat) #

Creates an exact representation of float as rational.

def self.new(num : BigRational) #

Creates a `BigRational` from the given num.

def self.new(num : BigDecimal) #

Creates a `BigRational` from the given num.

##
Instance Method Detail

def %(other : BigRational) : BigRational #
def %(other : Int) : BigRational #
def *(other : BigRational) : BigRational #
def *(other : Int) : BigRational #
def **(other : Int) : BigRational #

Raises the rational to the otherth power

This will raise `DivisionByZeroError` if rational is 0 and other is negative.

    require "big"

    BigRational.new(2, 3) ** 2  # => 4/9
    BigRational.new(2, 3) ** -1 # => 3/2

def +(other : BigRational) : BigRational #
def +(other : Int) : BigRational #
def -(other : BigRational) : BigRational #
def -(other : Int) : BigRational #
def - : BigRational #
def /(other : BigRational) : BigRational #
def /(other : BigInt) : BigRational #
def /(other : BigFloat) : BigRational #
def /(other : BigDecimal) : BigRational #
def /(other : Int8) : BigRational #
def /(other : UInt8) : BigRational #
def /(other : Int16) : BigRational #
def /(other : UInt16) : BigRational #
def /(other : Int32) : BigRational #
def /(other : UInt32) : BigRational #
def /(other : Int64) : BigRational #
def /(other : UInt64) : BigRational #
def /(other : Int128) : BigRational #
def /(other : UInt128) : BigRational #
def /(other : Float32) : BigRational #
def /(other : Float64) : BigRational #
def //(other : BigRational) : BigRational #
def //(other : Int) : BigRational #
def <<(other : Int) : BigRational #

Multiplies the rational by (2 ** other)

    require "big"

    BigRational.new(2, 3) << 2 # => 8/3

def <=>(other : BigRational) #
def <=>(other : Float::Primitive) #
def <=>(other : BigFloat) #
def <=>(other : BigInt) #
def <=>(other : Int) #
def <=>(other : BigDecimal) #
Description copied from module Comparable(BigDecimal)

The comparison operator. Returns `0` if the two objects are equal, a negative number if this object is considered less than other, a positive number if this object is considered greater than other, or `nil` if the two objects are not comparable.

Subclasses define this method to provide class-specific ordering.

The comparison operator is usually used to sort values:

    # Sort in a descending way:
    [3, 1, 2].sort { |x, y| y <=> x } # => [3, 2, 1]

    # Sort in an ascending way:
    [3, 1, 2].sort { |x, y| x <=> y } # => [1, 2, 3]

def ==(other : BigRational) : Bool #
def >>(other : Int) : BigRational #

Divides the rational by (2 ** other)

    require "big"

    BigRational.new(2, 3) >> 2 # => 1/6

def abs : BigRational #
Description copied from struct Number

Returns the absolute value of this number.

    123.abs  # => 123
    -123.abs # => 123

def ceil : BigRational #
def clone #
def denominator : BigInt #
def floor : BigRational #
def format(io : IO, separator = '.', delimiter = ',', decimal_places : Int | Nil = nil, *, group : Int = 3, only_significant : Bool = false) : Nil #

Prints this number as a `String` using a customizable format.

separator is used as decimal separator, delimiter as thousands delimiter between batches of group digits.

If decimal_places is `nil`, all significant decimal places are printed (similar to `#to_s`). If the argument has a numeric value, the number of visible decimal places will be fixed to that amount.

Trailing zeros are omitted if only_significant is `true`.

    123_456.789.format                                            # => "123,456.789"
    123_456.789.format(',', '.')                                  # => "123.456,789"
    123_456.789.format(decimal_places: 2)                         # => "123,456.79"
    123_456.789.format(decimal_places: 6)                         # => "123,456.789000"
    123_456.789.format(decimal_places: 6, only_significant: true) # => "123,456.789"

def inspect(io : IO) : Nil #
Description copied from class Object

Prints to io an unambiguous and information-rich string representation of this object, typically intended for developers.

It is similar to `#to_s(IO)`, but often provides more information. Ideally, it should contain sufficient information to be able to recreate an object with the same value (given an identical environment).

For types that don't provide a custom implementation of this method, default implementation delegates to `#to_s(IO)`. This said, it is advisable to have an appropriate `#inspect` implementation on every type. Default implementations are provided by `Struct#inspect` and `Reference#inspect`.

`::p` and `::p!` use this method to print an object in `STDOUT`.

def inspect : String #
Description copied from class Object

Returns an unambiguous and information-rich string representation of this object, typically intended for developers.

This method should usually not be overridden. It delegates to `#inspect(IO)` which can be overridden for custom implementations.

Also see `#to_s`.

def integer? : Bool #

Returns `true` if `self` is an integer.

Non-integer types may return `true` as long as `self` denotes a finite value without any fractional parts.

    1.integer?       # => true
    1.0.integer?     # => true
    1.2.integer?     # => false
    (1 / 0).integer? # => false
    (0 / 0).integer? # => false

def inv : BigRational #

Returns a new `BigRational` as 1/r.

This will raise an exception if rational is 0.

def numerator : BigInt #
def remainder(other : BigRational) : BigRational #
def remainder(other : Int) : BigRational #
def round_away : BigRational #
def round_even : BigRational #
def tdiv(other : BigRational) : BigRational #
def tdiv(other : Int) : BigRational #
def to_big_d : BigDecimal #

Converts `self` to `BigDecimal`.

def to_big_f : BigFloat #
def to_big_i : BigInt #
def to_big_r : BigRational #

Returns `self`.

    require "big"

    BigRational.new(4, 5).to_big_r # => 4/5

def to_f : Float64 #

Returns the `Float64` representing this rational.

def to_f! : Float64 #
def to_f32 : Float32 #
def to_f32! : Float32 #
def to_f64 : Float64 #
def to_f64! : Float64 #
def to_i16(*args, **options) #
def to_i16(*args, **options, &) #
def to_i32(*args, **options) #
def to_i32(*args, **options, &) #
def to_i64(*args, **options) #
def to_i64(*args, **options, &) #
def to_i8(*args, **options) #
def to_i8(*args, **options, &) #
def to_s(base : Int = 10) : String #

Returns the string representing this rational.

Optionally takes a radix base (2 through 36).

    require "big"

    r = BigRational.new(8243243, 562828882)
    r.to_s     # => "8243243/562828882"
    r.to_s(16) # => "7dc82b/218c1652"
    r.to_s(36) # => "4woiz/9b3djm"

def to_s(io : IO, base : Int = 10) : Nil #
Description copied from class Object

Prints a nicely readable and concise string representation of this object, typically intended for users, to io.

This method is called when an object is interpolated in a string literal:

    "foo #{bar} baz" # calls bar.to_io with the builder for this string

`IO#<<` calls this method to append an object to itself:

    io << bar # calls bar.to_s(io)

Thus implementations must not interpolate `self` in a string literal or call `io << self` which both would lead to an endless loop.

Also see `#inspect(IO)`.

def to_u16(*args, **options) #
def to_u16(*args, **options, &) #
def to_u32(*args, **options) #
def to_u32(*args, **options, &) #
def to_u64(*args, **options) #
def to_u64(*args, **options, &) #
def to_u8(*args, **options) #
def to_u8(*args, **options, &) #
def to_unsafe #
def trunc : BigRational #