NumericAnnex Reference (100% documented)

View on GitHub

Install in Dash

Rational

public struct Rational<T : SignedInteger> : Codable
where T : Codable & _ExpressibleByBuiltinIntegerLiteral,
  T.Magnitude : UnsignedInteger,
  T.Magnitude.Magnitude == T.Magnitude

A type to represent a rational value.

Note

Ratio is a type alias for Rational<Int>.

Create new instances of Rational<T> by using integer literals and the division (/) operator. For example:

let x = 1 / 3 as Ratio // `x` is of type `Rational<Int>`
let y = 2 as Ratio // `y` is of type `Rational<Int>`
let z: Ratio = 2 / 3 // `z` is also of type `Rational<Int>`

print(x + y + z) // Prints "3"

You can create an unreduced fraction by using the initializer Rational<T>.init(numerator:denominator:). For example:

let a = Ratio(numerator: 3, denominator: 3)
print(a) // Prints "3/3"

All arithmetic operations on values in canonical form (i.e. reduced to lowest terms) return results in canonical form. However, operations on values not in canonical form may or may not return results that are themselves in canonical form. The property canonicalized is the canonical form of any value.

Additional Considerations

Special Values

Rational<T> does not prohibit zero as a denominator. Any instance with a positive numerator and zero denominator represents (positive) infinity; any instance with a negative numerator and zero denominator represents negative infinity; and any instance with zero numerator and zero denominator represents NaN (not a number).

As with floating-point types, Rational<T>.infinity compares greater than every finite value and negative infinity, and -Rational<T>.infinity compares less than every finite value and positive infinity. Infinite values of the same sign compare equal to each other.

As with floating-point types, Rational<T>.nan does not compare equal to any other value, including another NaN. Use the property isNaN to test if a value is NaN. Rational<T> arithmetic operations are intended to propagate NaN in the same manner as analogous floating-point operations.

Numerical Limits

When a value of type Rational<T> is in canonical form, the sign of the numerator is the sign of the value; that is, in canonical form, the sign of the denominator is always positive. Therefore, -1 / T.min cannot be represented as a value of type Rational<T> because abs(T.min) cannot be represented as a value of type T.

To ensure that every representable value of type Rational<T> has a representable magnitude and reciprocal of the same type, an overflow trap occurs when the division (/) operator is used to create a value of type Rational<T> with numerator T.min.

Topics

Stored Properties

Initializers

Initializers (Constrained)

Static Properties

Static Methods

Computed Properties

Methods

ExpressibleByIntegerLiteral

CustomStringConvertible

Equatable

Hashable

Comparable

Strideable

Numeric

SignedNumeric

Stored Properties

  • numerator

    The numerator of the rational value.

    Declaration

    Swift

    public var numerator: T

  • denominator

    The denominator of the rational value.

    Declaration

    Swift

    public var denominator: T

Initializers

  • init(numerator:denominator:)

    Creates a new value from the given numerator and denominator without computing its canonical form (i.e., without reducing to lowest terms).

    To create a value reduced to lowest terms, use the division (/) operator. For example:

    let x = 3 / 3 as Rational<Int>
print(x) // Prints "1"
    Declaration

    Swift

    public init(numerator: T, denominator: T)
    Parameters
    numerator

    The new value’s numerator.

    denominator

    The new value’s denominator.

  • init(_:)

    Creates a new rational value from the given binary integer.

    If source or its magnitude is not representable as a numerator of type T, a runtime error may occur.

    Declaration

    Swift

    public init<Source : BinaryInteger>(_ source: Source)
    Parameters
    source

    A binary integer to convert to a rational value.

  • init(_:)

    Creates a new rational value from the given binary floating-point value.

    If source or its magnitude is not representable exactly as a ratio of two signed integers of type T, a runtime error may occur.

    Declaration

    Swift

    public init<Source : BinaryFloatingPoint>(_ source: Source)
    Parameters
    source

    A binary floating-point value to convert to a rational value.

Initializers (Constrained)

  • init(exactly:)

    Creates a new rational value from the given binary floating-point value, if it can be represented exactly.

    If source or its magnitude is not representable exactly as a ratio of two signed integers of type T, the result is nil.

    Note

    This initializer creates only instances of Rational<T> where T : FixedWidthInteger.

    Declaration

    Swift

    public init?<Source : BinaryFloatingPoint>(exactly source: Source)
    Parameters
    source

    A floating-point value to convert to a rational value.

Static Properties

  • infinity

    Positive infinity.

    Infinity compares greater than all finite numbers and equal to other (positive) infinite values.

    Declaration

    Swift

    public static var infinity: Rational

  • nan

    A quiet NaN (not a number).

    A NaN compares not equal, not greater than, and not less than every value, including itself. Passing a NaN to an operation generally results in NaN.

    Declaration

    Swift

    public static var nan: Rational

Static Methods

  • /(_:_:)

    Returns the quotient obtained by dividing the first value by the second, trapping in case of arithmetic overflow.

    Declaration

    Swift

    public static func / (lhs: Rational, rhs: Rational) -> Rational
    Parameters
    lhs

    The value to divide.

    rhs

    The value by which to divide lhs.

  • /=(_:_:)

    Divides the left-hand side by the right-hand side and stores the quotient in the left-hand side, trapping in case of arithmetic overflow.

    Declaration

    Swift

    public static func /= (lhs: inout Rational, rhs: Rational)
    Parameters
    lhs

    The value to divide.

    rhs

    The value by which to divide lhs.

Computed Properties

  • canonical

    The canonical representation of this value.

    Declaration

    Swift

    public var canonical: Rational

  • isCanonical

    A Boolean value indicating whether the instance’s representation is in canonical form.

    Declaration

    Swift

    public var isCanonical: Bool

  • isFinite

    A Boolean value indicating whether the instance is finite.

    All values other than NaN and infinity are considered finite.

    Declaration

    Swift

    public var isFinite: Bool

  • isInfinite

    A Boolean value indicating whether the instance is infinite.

    Note that isFinite and isInfinite do not form a dichotomy because NaN is neither finite nor infinite.

    Declaration

    Swift

    public var isInfinite: Bool

  • isNaN

    A Boolean value indicating whether the instance is NaN (not a number).

    Because NaN is not equal to any value, including NaN, use this property instead of the equal-to operator (==) or not-equal-to operator (!=) to test whether a value is or is not NaN.

    Declaration

    Swift

    public var isNaN: Bool

  • isProper

    A Boolean value indicating whether the instance is a proper fraction.

    A fraction is proper if and only if the absolute value of the fraction is less than 1.

    Declaration

    Swift

    public var isProper: Bool

  • isZero

    A Boolean value indicating whether the instance is equal to zero.

    Declaration

    Swift

    public var isZero: Bool

  • magnitude

    The magnitude (absolute value) of this value.

    Declaration

    Swift

    public var magnitude: Rational

  • mixed

    The mixed form representing this value.

    If the value is not finite, the mixed form has zero as its whole part and the value as its fractional part.

    Declaration

    Swift

    public var mixed: (whole: T, fractional: Rational)

  • sign

    The sign of this value.

    Declaration

    Swift

    public var sign: Sign

Methods

  • reciprocal()

    Returns the reciprocal (multiplicative inverse) of this value.

    Declaration

    Swift

    public func reciprocal() -> Rational

  • rounded(_:)

    Returns this value rounded to an integral value using the specified rounding rule.

    let x = 7 / 2 as Rational<Int>
print(x.rounded()) // Prints "4"
print(x.rounded(.towardZero)) // Prints "3"
print(x.rounded(.up)) // Prints "4"
print(x.rounded(.down)) // Prints "3"

    See the FloatingPointRoundingRule enumeration for more information about the available rounding rules.

    See also

    round(_:), RoundingRule

    Declaration

    Swift

    public func rounded(
    _ rule: RoundingRule = .toNearestOrAwayFromZero
  ) -> Rational
    Parameters
    rule

    The rounding rule to use.

  • round(_:)

    Rounds the value to an integral value using the specified rounding rule.

    var x = 7 / 2 as Rational<Int>
x.round() // x == 4

var x = 7 / 2 as Rational<Int>
x.round(.towardZero) // x == 3

var x = 7 / 2 as Rational<Int>
x.round(.up) // x == 4

var x = 7 / 2 as Rational<Int>
x.round(.down) // x == 3

    See the FloatingPointRoundingRule enumeration for more information about the available rounding rules.

    See also

    round(_:), RoundingRule

    Declaration

    Swift

    public mutating func round(_ rule: RoundingRule = .toNearestOrAwayFromZero)
    Parameters
    rule

    The rounding rule to use.

ExpressibleByIntegerLiteral

  • init(integerLiteral:)

    Declaration

    Swift

    public init(integerLiteral value: T)

CustomStringConvertible

  • description

    Declaration

    Swift

    public var description: String

Equatable

  • ==(_:_:)

    Declaration

    Swift

    public static func == (lhs: Rational, rhs: Rational) -> Bool

Hashable

  • hashValue

    Declaration

    Swift

    public var hashValue: Int

Comparable

  • <(_:_:)

    Declaration

    Swift

    public static func < (lhs: Rational, rhs: Rational) -> Bool

  • >(_:_:)

    Declaration

    Swift

    public static func > (lhs: Rational, rhs: Rational) -> Bool

  • <=(_:_:)

    Declaration

    Swift

    public static func <= (lhs: Rational, rhs: Rational) -> Bool

  • >=(_:_:)

    Declaration

    Swift

    public static func >= (lhs: Rational, rhs: Rational) -> Bool

Strideable

  • distance(to:)

    Declaration

    Swift

    public func distance(to other: Rational) -> Rational

  • advanced(by:)

    Declaration

    Swift

    public func advanced(by amount: Rational) -> Rational

Numeric

  • init(exactly:)

    Declaration

    Swift

    public init?<U>(exactly source: U) where U : BinaryInteger

  • +(_:_:)

    Declaration

    Swift

    public static func + (lhs: Rational, rhs: Rational) -> Rational

  • +=(_:_:)

    Declaration

    Swift

    public static func += (lhs: inout Rational, rhs: Rational)

  • -(_:_:)

    Declaration

    Swift

    public static func - (lhs: Rational, rhs: Rational) -> Rational

  • -=(_:_:)

    Declaration

    Swift

    public static func -= (lhs: inout Rational, rhs: Rational)

  • *(_:_:)

    Declaration

    Swift

    public static func * (lhs: Rational, rhs: Rational) -> Rational

  • *=(_:_:)

    Declaration

    Swift

    public static func *= (lhs: inout Rational, rhs: Rational)

SignedNumeric

  • -(_:)

    Declaration

    Swift

    public static prefix func - (operand: Rational) -> Rational

  • negate()

    Declaration

    Swift

    public mutating func negate()