abstract struct Number

Overview

The top-level number type.

Included Modules

Direct Known Subclasses

Defined in:

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

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

Constructors

Class Method Summary

Instance Method Summary

Macro Summary

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

! : 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?(*values : Object) : Bool
in?(collection) : Bool
in?
, inspect : String
inspect(io : IO) : Nil
inspect
, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, 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)
to_json
to_json
, to_pretty_json(io : IO, indent : String = " ")
to_pretty_json(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.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

[View source]
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

[View source]
def self.zero : self #

Returns the value zero in the respective type.

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

[View source]

Class Method Detail

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

Returns the SI prefix for magnitude.

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

[View source]

Instance Method Detail

def *(other : Complex) #

[View source]
def *(other : BigFloat) #

[View source]
def +(other : BigFloat) #

[View source]
def +(other : Complex) #

[View source]
def + #

Returns self.


[View source]
def -(other : Complex) #

[View source]
def -(other : BigFloat) #

[View source]
def /(other : Complex) #

[View source]
def /(other : BigFloat) #

[View source]
def //(other) #

Divides self by other using floored division.

The result will be of the same type as self.


[View source]
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 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]

[View source]
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

[View source]
def ==(other : Complex) #

[View source]
def abs #

Returns the absolute value of this number.

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

[View source]
def abs2 #

Returns the square of self (self * self).

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

[View source]
def cis #

[View source]
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}

[View source]
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"

[View source]
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"

[View source]
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.


[View source]
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.


[View source]
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.


[View source]
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.


[View source]
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.


[View source]
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.


[View source]
def i #

[View source]
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

[View source]
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).


[View source]
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

[View source]
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

[View source]
def step(*, to limit = nil, exclusive : Bool = false) #

Iterates from self to limit incrementing by the amount of step on each iteration. If exclusive is true, limit is excluded from the iteration.

ary = [] of Int32
1.step(to: 4, by: 2) do |x|
  ary << x
end
ary                                        # => [1, 3]
1.step(to: 4, by: 2).to_a                  # => [1, 3]
1.step(to: 4, by: 1).to_a                  # => [1, 2, 3, 4]
1.step(to: 4, by: 1, exclusive: true).to_a # => [1, 2, 3]

The type of each iterated element is typeof(self + step).

If to is nil, iteration is open ended.

The starting point (self) is always iterated as first element, with two exceptions:

  • if self and to don't compare (i.e. (self <=> to).nil?). Example: 1.0.step(Float::NAN)
  • if the direction of to differs from the direction of by. Example: 1.step(to: 2, by: -1)

In those cases the iteration is empty.


[View source]
def step(*, to limit = nil, by step, exclusive : Bool = false) #

Iterates from self to limit incrementing by the amount of step on each iteration. If exclusive is true, limit is excluded from the iteration.

ary = [] of Int32
1.step(to: 4, by: 2) do |x|
  ary << x
end
ary                                        # => [1, 3]
1.step(to: 4, by: 2).to_a                  # => [1, 3]
1.step(to: 4, by: 1).to_a                  # => [1, 2, 3, 4]
1.step(to: 4, by: 1, exclusive: true).to_a # => [1, 2, 3]

The type of each iterated element is typeof(self + step).

If to is nil, iteration is open ended.

The starting point (self) is always iterated as first element, with two exceptions:

  • if self and to don't compare (i.e. (self <=> to).nil?). Example: 1.0.step(Float::NAN)
  • if the direction of to differs from the direction of by. Example: 1.step(to: 2, by: -1)

In those cases the iteration is empty.


[View source]
def step(*, to limit = nil, exclusive : Bool = false, &) : Nil #

Iterates from self to limit incrementing by the amount of step on each iteration. If exclusive is true, limit is excluded from the iteration.

ary = [] of Int32
1.step(to: 4, by: 2) do |x|
  ary << x
end
ary                                        # => [1, 3]
1.step(to: 4, by: 2).to_a                  # => [1, 3]
1.step(to: 4, by: 1).to_a                  # => [1, 2, 3, 4]
1.step(to: 4, by: 1, exclusive: true).to_a # => [1, 2, 3]

The type of each iterated element is typeof(self + step).

If to is nil, iteration is open ended.

The starting point (self) is always iterated as first element, with two exceptions:

  • if self and to don't compare (i.e. (self <=> to).nil?). Example: 1.0.step(Float::NAN)
  • if the direction of to differs from the direction of by. Example: 1.step(to: 2, by: -1)

In those cases the iteration is empty.


[View source]
def step(*, to limit = nil, by step, exclusive : Bool = false, &) : Nil #

Iterates from self to limit incrementing by the amount of step on each iteration. If exclusive is true, limit is excluded from the iteration.

ary = [] of Int32
1.step(to: 4, by: 2) do |x|
  ary << x
end
ary                                        # => [1, 3]
1.step(to: 4, by: 2).to_a                  # => [1, 3]
1.step(to: 4, by: 1).to_a                  # => [1, 2, 3, 4]
1.step(to: 4, by: 1, exclusive: true).to_a # => [1, 2, 3]

The type of each iterated element is typeof(self + step).

If to is nil, iteration is open ended.

The starting point (self) is always iterated as first element, with two exceptions:

  • if self and to don't compare (i.e. (self <=> to).nil?). Example: 1.0.step(Float::NAN)
  • if the direction of to differs from the direction of by. Example: 1.step(to: 2, by: -1)

In those cases the iteration is empty.


[View source]
def to_big_f #

[View source]
def to_c #

[View source]
def to_yaml(yaml : YAML::Nodes::Builder) #

[View source]
def zero? : Bool #

Returns true if value is equal to zero.

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

[View source]

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)

[View source]
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)

[View source]
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)

[View source]