# abstract struct Number

- Number
- Value
- Object

##
Overview

The top-level number type.

##
Included Modules

- Comparable(BigFloat)
- Comparable(Number)

##
Direct Known Subclasses

- BigDecimal
- BigRational
- Float
- Int

##
Defined in:

##
Constant Summary

SI_PREFIXES = `{ {'y', 'z', 'a', 'f', 'p', 'n', 'µ', 'm'}, {nil, 'k', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y'} }`

  Default SI prefixes ordered by magnitude.

SI_PREFIXES_PADDED = `->(magnitude : Int32, _number : Float64) do magnitude = Number.prefix_index(magnitude) {magnitude, ( magnitude == 0 ? " " : si_prefix(magnitude))} end`

  SI prefixes used by `#humanize`. Equal to `SI_PREFIXES` but prepends the prefix with a space charater.

##
Constructors

- .zero : self

##
Class Method Summary

- .si_prefix(magnitude : Int, prefixes = SI_PREFIXES) : Char?

  Returns the SI prefix for magnitude.

##
Instance Method Summary

- #*(other : Complex)
- #*(other : BigFloat)
- #+(other : BigFloat)
- #+(other : Complex)
- #+

  Returns self.

- #-(other : Complex)
- #-(other : BigFloat)
- #/(other : Complex)
- #/(other : BigFloat)
- #//(other)

  Divides `self` by other using floored division.

- #<=>(other : BigFloat)

  The comparison operator.

- #<=>(other) : Int32?

  The comparison operator.

- #==(other : Complex)
- #abs

  Returns the absolute value of this number.

- #abs2

  Returns the square of `self` (`self * self`).

- #cis
- #divmod(number)

  Returns a `Tuple` of two elements containing the quotient and modulus obtained by dividing `self` by number.

- #format(separator = '.', delimiter = ',', decimal_places : Int? = nil, *, group : Int = 3, only_significant : Bool = false) : String

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

- #format(io : IO, separator = '.', delimiter = ',', decimal_places : Int? = nil, *, group : Int = 3, only_significant : Bool = false) : Nil

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

- #humanize(io : IO, precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, prefixes : Indexable = SI_PREFIXES) : Nil

  Pretty prints this number as a `String` in a human-readable format.

- #humanize(precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, prefixes : Proc) : Nil

  Pretty prints this number as a `String` in a human-readable format.

- #humanize(precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, &) : String

  Pretty prints this number as a `String` in a human-readable format.

- #humanize(io : IO, precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, &prefixes : Int32, Float64 -> Tuple(Int32, _) | Tuple(Int32, _, Bool)) : Nil

  Pretty prints this number as a `String` in a human-readable format.

- #humanize(precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, prefixes = SI_PREFIXES) : String

  Pretty prints this number as a `String` in a human-readable format.

- #humanize(io : IO, precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, prefixes : Proc) : Nil

  Pretty prints this number as a `String` in a human-readable format.

- #i
- #round(digits = 0, base = 10)

  Rounds this number to a given precision in decimal digits.

- #sign

  Returns the sign of this number as an `Int32`.

- #significant(digits, base = 10)

  Keeps digits significants digits of this number in the given base.

- #step(*, to = nil, by = 1)
- #step(*, to = nil, by = 1, &)

  Invokes the given block with the sequence of numbers starting at `self`, incremented by by on each call, and with an optional to.

- #to_big_f
- #to_c
- #to_yaml(yaml : YAML::Nodes::Builder)
- #zero? : Bool

  Returns `true` if value is equal to zero.

##
Macro Summary

- [](*nums)

  Creates an `Array` of `self` with the given values, which will be casted to this type with the `new` method (defined in each `Number` type).

- slice(*nums, read_only = false)

  Creates a `Slice` of `self` with the given values, which will be casted to this type with the `new` method (defined in each `Number` type).

- static_array(*nums)

  Creates a `StaticArray` of `self` with the given values, which will be casted to this type with the `new` method (defined in each `Number` type).

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

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

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

<(other : T) <, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) >, >=(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`

!=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, __crystal_pseudo_! : Bool __crystal_pseudo_!, __crystal_pseudo_as(type : Class) __crystal_pseudo_as, __crystal_pseudo_as?(type : Class) __crystal_pseudo_as?, __crystal_pseudo_is_a?(type : Class) : Bool __crystal_pseudo_is_a?, __crystal_pseudo_nil? : Bool __crystal_pseudo_nil?, __crystal_pseudo_responds_to?(name : Symbol) : Bool __crystal_pseudo_responds_to?, class class, dup dup, hash(hasher)
hash hash, inspect : String
inspect(io : IO) : Nil inspect, itself itself, not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, tap(&) tap, to_json(io : IO)
to_json to_json, to_pretty_json(indent : String = " ")
to_pretty_json(io : IO, indent : String = " ") to_pretty_json, to_s : String
to_s(io : IO) : Nil to_s, to_yaml(io : IO)
to_yaml 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

##
Constructor Detail

def self.zero : self #

##
Class Method Detail

def self.si_prefix(magnitude : Int, prefixes = SI_PREFIXES) : Char? #

Returns the SI prefix for magnitude.

    Number.si_prefix(3) # => 'k'

##
Instance Method Detail

def *(other : Complex) #
def *(other : BigFloat) #
def +(other : BigFloat) #
def +(other : Complex) #
def + #

Returns self.

def -(other : Complex) #
def -(other : BigFloat) #
def /(other : Complex) #
def /(other : BigFloat) #
def //(other) #

Divides `self` by other using floored division.

The result will be of the same type as `self`.

def <=>(other : BigFloat) #
Description copied from module Comparable(BigFloat)

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 greter 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) : Int32? #

The comparison operator.

Returns:

- `-1` if `self` is less than other
- `0` if `self` is equal to other
- `-1` if `self` is greater than other
- `nil` if self is `NaN` or other is `NaN`, because `NaN` values are not comparable

def ==(other : Complex) #
def abs #

Returns the absolute value of this number.

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

def abs2 #

Returns the square of `self` (`self * self`).

    4.abs2   # => 16
    1.5.abs2 # => 2.25

def cis #
def divmod(number) #

Returns a `Tuple` of two elements containing the quotient and modulus obtained by dividing `self` by number.

    11.divmod(3)  # => {3, 2}
    11.divmod(-3) # => {-4, -1}

def format(separator = '.', delimiter = ',', decimal_places : Int? = nil, *, group : Int = 3, only_significant : Bool = false) : String #

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 format(io : IO, separator = '.', delimiter = ',', decimal_places : Int? = 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 humanize(io : IO, precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, prefixes : Indexable = SI_PREFIXES) : Nil #

Pretty prints this number as a `String` in a human-readable format.

This is particularly useful if a number can have a wide value range and the exact value is less relevant.

It rounds the number to the nearest thousands magnitude with precision number of significant digits. The order of magnitude is expressed with an appended quantifier. By default, SI prefixes are used (see `SI_PREFIXES`).

    1_200_000_000.humanize # => "1.2G"
    0.000_000_012.humanize # => "12.0n"

If significant is `false`, the number of precision digits is preserved after the decimal separator.

    1_234.567_890.humanize(precision: 2)                     # => "1.2k"
    1_234.567_890.humanize(precision: 2, significant: false) # => "1.23k"

separator describes the decimal separator, delimiter the thousands delimiter (see `#format`).

See `Int#humanize_bytes` to format a file size.

def humanize(precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, prefixes : Proc) : Nil #

Pretty prints this number as a `String` in a human-readable format.

This is particularly useful if a number can have a wide value range and the exact value is less relevant.

It rounds the number to the nearest thousands magnitude with precision number of significant digits. The order of magnitude is expressed with an appended quantifier. By default, SI prefixes are used (see `SI_PREFIXES`).

    1_200_000_000.humanize # => "1.2G"
    0.000_000_012.humanize # => "12.0n"

If significant is `false`, the number of precision digits is preserved after the decimal separator.

    1_234.567_890.humanize(precision: 2)                     # => "1.2k"
    1_234.567_890.humanize(precision: 2, significant: false) # => "1.23k"

separator describes the decimal separator, delimiter the thousands delimiter (see `#format`).

This methods yields the order of magnitude and `self` and expects the block to return a `Tuple(Int32, _)` containing the (adjusted) magnitude and unit. The magnitude is typically adjusted to a multiple of `3`.

    def humanize_length(number)
      number.humanize do |magnitude, number|
        case magnitude
        when -2, -1 then {-2, " cm"}
        when .>=(4)
          {3, " km"}
        else
          magnitude = Number.prefix_index(magnitude)
          {magnitude, " #{Number.si_prefix(magnitude)}m"}
        end
      end
    end

    humanize_length(1_420) # => "1.42 km"
    humanize_length(0.23)  # => "23.0 cm"

See `Int#humanize_bytes` to format a file size.

def humanize(precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, &) : String #

Pretty prints this number as a `String` in a human-readable format.

This is particularly useful if a number can have a wide value range and the exact value is less relevant.

It rounds the number to the nearest thousands magnitude with precision number of significant digits. The order of magnitude is expressed with an appended quantifier. By default, SI prefixes are used (see `SI_PREFIXES`).

    1_200_000_000.humanize # => "1.2G"
    0.000_000_012.humanize # => "12.0n"

If significant is `false`, the number of precision digits is preserved after the decimal separator.

    1_234.567_890.humanize(precision: 2)                     # => "1.2k"
    1_234.567_890.humanize(precision: 2, significant: false) # => "1.23k"

separator describes the decimal separator, delimiter the thousands delimiter (see `#format`).

This methods yields the order of magnitude and `self` and expects the block to return a `Tuple(Int32, _)` containing the (adjusted) magnitude and unit. The magnitude is typically adjusted to a multiple of `3`.

    def humanize_length(number)
      number.humanize do |magnitude, number|
        case magnitude
        when -2, -1 then {-2, " cm"}
        when .>=(4)
          {3, " km"}
        else
          magnitude = Number.prefix_index(magnitude)
          {magnitude, " #{Number.si_prefix(magnitude)}m"}
        end
      end
    end

    humanize_length(1_420) # => "1.42 km"
    humanize_length(0.23)  # => "23.0 cm"

See `Int#humanize_bytes` to format a file size.

def humanize(io : IO, precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, &prefixes : Int32, Float64 -> Tuple(Int32, _) | Tuple(Int32, _, Bool)) : Nil #

Pretty prints this number as a `String` in a human-readable format.

This is particularly useful if a number can have a wide value range and the exact value is less relevant.

It rounds the number to the nearest thousands magnitude with precision number of significant digits. The order of magnitude is expressed with an appended quantifier. By default, SI prefixes are used (see `SI_PREFIXES`).

    1_200_000_000.humanize # => "1.2G"
    0.000_000_012.humanize # => "12.0n"

If significant is `false`, the number of precision digits is preserved after the decimal separator.

    1_234.567_890.humanize(precision: 2)                     # => "1.2k"
    1_234.567_890.humanize(precision: 2, significant: false) # => "1.23k"

separator describes the decimal separator, delimiter the thousands delimiter (see `#format`).

This methods yields the order of magnitude and `self` and expects the block to return a `Tuple(Int32, _)` containing the (adjusted) magnitude and unit. The magnitude is typically adjusted to a multiple of `3`.

    def humanize_length(number)
      number.humanize do |magnitude, number|
        case magnitude
        when -2, -1 then {-2, " cm"}
        when .>=(4)
          {3, " km"}
        else
          magnitude = Number.prefix_index(magnitude)
          {magnitude, " #{Number.si_prefix(magnitude)}m"}
        end
      end
    end

    humanize_length(1_420) # => "1.42 km"
    humanize_length(0.23)  # => "23.0 cm"

See `Int#humanize_bytes` to format a file size.

def humanize(precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, prefixes = SI_PREFIXES) : String #

Pretty prints this number as a `String` in a human-readable format.

This is particularly useful if a number can have a wide value range and the exact value is less relevant.

It rounds the number to the nearest thousands magnitude with precision number of significant digits. The order of magnitude is expressed with an appended quantifier. By default, SI prefixes are used (see `SI_PREFIXES`).

    1_200_000_000.humanize # => "1.2G"
    0.000_000_012.humanize # => "12.0n"

If significant is `false`, the number of precision digits is preserved after the decimal separator.

    1_234.567_890.humanize(precision: 2)                     # => "1.2k"
    1_234.567_890.humanize(precision: 2, significant: false) # => "1.23k"

separator describes the decimal separator, delimiter the thousands delimiter (see `#format`).

See `Int#humanize_bytes` to format a file size.

def humanize(io : IO, precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, prefixes : Proc) : Nil #

Pretty prints this number as a `String` in a human-readable format.

This is particularly useful if a number can have a wide value range and the exact value is less relevant.

It rounds the number to the nearest thousands magnitude with precision number of significant digits. The order of magnitude is expressed with an appended quantifier. By default, SI prefixes are used (see `SI_PREFIXES`).

    1_200_000_000.humanize # => "1.2G"
    0.000_000_012.humanize # => "12.0n"

If significant is `false`, the number of precision digits is preserved after the decimal separator.

    1_234.567_890.humanize(precision: 2)                     # => "1.2k"
    1_234.567_890.humanize(precision: 2, significant: false) # => "1.23k"

separator describes the decimal separator, delimiter the thousands delimiter (see `#format`).

This methods yields the order of magnitude and `self` and expects the block to return a `Tuple(Int32, _)` containing the (adjusted) magnitude and unit. The magnitude is typically adjusted to a multiple of `3`.

    def humanize_length(number)
      number.humanize do |magnitude, number|
        case magnitude
        when -2, -1 then {-2, " cm"}
        when .>=(4)
          {3, " km"}
        else
          magnitude = Number.prefix_index(magnitude)
          {magnitude, " #{Number.si_prefix(magnitude)}m"}
        end
      end
    end

    humanize_length(1_420) # => "1.42 km"
    humanize_length(0.23)  # => "23.0 cm"

See `Int#humanize_bytes` to format a file size.

def i #
def round(digits = 0, base = 10) #

Rounds this number to a given precision in decimal digits.

    -1763.116.round(2) # => -1763.12

def sign #

Returns the sign of this number as an `Int32`.

- `-1` if this number is negative
- `0` if this number is zero
- `1` if this number is positive

    123.sign # => 1
    0.sign   # => 0
    -42.sign # => -1

def significant(digits, base = 10) #

Keeps digits significants digits of this number in the given base.

    1234.567.significant(1) # => 1000
    1234.567.significant(2) # => 1200
    1234.567.significant(3) # => 1230
    1234.567.significant(4) # => 1235
    1234.567.significant(5) # => 1234.6
    1234.567.significant(6) # => 1234.57
    1234.567.significant(7) # => 1234.567
    1234.567.significant(8) # => 1234.567

    15.159.significant(1, base = 2) # => 16

def step(*, to = nil, by = 1) #
def step(*, to = nil, by = 1, &) #

Invokes the given block with the sequence of numbers starting at `self`, incremented by by on each call, and with an optional to.

    3.step(to: 10, by: 2) do |n|
      puts n
    end

Output:

    3
    5
    7
    9

def to_big_f #
def to_c #
def to_yaml(yaml : YAML::Nodes::Builder) #
def zero? : Bool #

Returns `true` if value is equal to zero.

    0.zero? # => true
    5.zero? # => false

##
Macro Detail

macro [](*nums) #

Creates an `Array` of `self` with the given values, which will be casted to this type with the `new` method (defined in each `Number` type).

    floats = Float64[1, 2, 3, 4]
    floats.class # => Array(Float64)

    ints = Int64[1, 2, 3]
    ints.class # => Array(Int64)

macro slice(*nums, read_only = false) #

Creates a `Slice` of `self` with the given values, which will be casted to this type with the `new` method (defined in each `Number` type).

The slice is allocated on the heap.

    floats = Float64.slice(1, 2, 3, 4)
    floats.class # => Slice(Float64)

    ints = Int64.slice(1, 2, 3)
    ints.class # => Slice(Int64)

macro static_array(*nums) #

Creates a `StaticArray` of `self` with the given values, which will be casted to this type with the `new` method (defined in each `Number` type).

    floats = Float64.static_array(1, 2, 3, 4)
    floats.class # => StaticArray(Float64, 4)

    ints = Int64.static_array(1, 2, 3)
    ints.class # => StaticArray(Int64, 3)