Number - Crystal 1.10.1

# abstract struct Number

- Number
- Value
- Object

##
Overview

The top-level number type.

##
Included Modules

- Comparable(BigFloat)
- Comparable(Number)
- Steppable

##
Direct Known Subclasses

- BigDecimal
- BigRational
- Float
- Int

##
Defined in:

big/big_float.cr
complex.cr
humanize.cr
number.cr
yaml/to_yaml.cr

##
Constant Summary

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

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

##
Constructors

- .additive_identity : self

  Returns the additive identity of this type.

- .multiplicative_identity : self

  Returns the multiplicative identity of this type.

- .zero : self

  Returns the value zero in the respective type.

##
Class Method Summary

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

  Returns the SI prefix for magnitude.

##
Instance Method Summary

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

  Returns `self`.

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

  Divides `self` by other using floored division.

- #<=>(other) : Int32 | Nil

  The comparison operator.

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

  Returns the absolute value of this number.

- #abs2

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

- #cis : Complex
- #divmod(number)

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

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

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

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

- #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 : 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, &) : String

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

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

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

- #i : Complex
- #negative? : Bool

  Returns `true` if `self` is less than zero.

- #positive? : Bool

  Returns `true` if `self` is greater than zero.

- #round(mode : RoundingMode = :ties_even) : self

  Rounds `self` to an integer value using rounding mode.

- #round(digits : Number, base = 10, *, mode : RoundingMode = :ties_even)

  Rounds this number to a given precision.

- #sign : Int32

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

- #significant(digits, base = 10)

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

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

  Performs a `#step` in the direction of the limit.

- #step(*, to limit = nil, exclusive : Bool = false)

  Performs a `#step` in the direction of the limit.

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

  Returns `true` if `self` 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) : 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

##
Constructor Detail

def self.additive_identity : self #

Returns the additive identity of this type.

For numerical types, it is the value `0` expressed in the respective type.

    Int32.additive_identity   # => 0
    Float64.additive_identity # => 0.0

def self.multiplicative_identity : self #

Returns the multiplicative identity of this type.

For numerical types, it is the value `1` expressed in the respective type.

    Int32.multiplicative_identity   # => 1
    Float64.multiplicative_identity # => 1.0

def self.zero : self #

Returns the value zero in the respective type.

    Int32.zero   # => 0
    Float64.zero # => 0.0

##
Class Method Detail

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

Returns the SI prefix for magnitude.

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

##
Instance Method Detail

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

Returns `self`.

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

Divides `self` by other using floored division.

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

def <=>(other) : Int32 | Nil #

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 : self #

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 : Complex #
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(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 format(separator = '.', delimiter = ',', decimal_places : Int | Nil = 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 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(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 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 : 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, &) : 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(precision = 3, separator = '.', delimiter = ',', *, base = 10 ** 3, significant = true, prefixes : Proc) : 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 i : Complex #
def negative? : Bool #

Returns `true` if `self` is less than zero.

    -1.negative? # => true
    0.negative?  # => false
    1.negative?  # => false

def positive? : Bool #

Returns `true` if `self` is greater than zero.

    -1.positive? # => false
    0.positive?  # => false
    1.positive?  # => true

def round(mode : RoundingMode = :ties_even) : self #

Rounds `self` to an integer value using rounding mode.

The rounding mode controls the direction of the rounding. The default is `RoundingMode::TIES_EVEN` which rounds to the nearest integer, with ties (fractional value of `0.5`) being rounded to the even neighbor (Banker's rounding).

def round(digits : Number, base = 10, *, mode : RoundingMode = :ties_even) #

Rounds this number to a given precision.

Rounds to the specified number of digits after the decimal place, (or before if negative), in base base.

The rounding mode controls the direction of the rounding. The default is `RoundingMode::TIES_EVEN` which rounds to the nearest integer, with ties (fractional value of `0.5`) being rounded to the even neighbor (Banker's rounding).

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

def sign : Int32 #

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 significant 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 limit = nil, exclusive : Bool = false, &) : Nil #

Performs a `#step` in the direction of the limit. For instance:

    10.step(to: 5).to_a # => [10, 9, 8, 7, 6, 5]
    5.step(to: 10).to_a # => [5, 6, 7, 8, 9, 10]

def step(*, to limit = nil, exclusive : Bool = false) #

Performs a `#step` in the direction of the limit. For instance:

    10.step(to: 5).to_a # => [10, 9, 8, 7, 6, 5]
    5.step(to: 10).to_a # => [5, 6, 7, 8, 9, 10]

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

Returns `true` if `self` 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)

This is similar to an array literal of the same item type:

    Int64[1, 2, 3, 4]     # : Array(Int64)
    [1, 2, 3, 4] of Int64 # : 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)

This is a convenient alternative to `Slice.[]` for designating a specific item type which also considers autocasting.

    Int64.slice(1, 2, 3, 4)           # : Slice(Int64)
    Slice[1_i64, 2_i64, 3_i64, 4_i64] # : 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)

This is a convenvenient alternative to `StaticArray.[]` for designating a specific item type which also considers autocasting.

    Int64.static_array(1, 2, 3, 4)          # : StaticArray(Int64)
    StaticArray[1_i64, 2_i64, 3_i64, 4_i64] # : StaticArray(Int64)