abstract struct Number

Overview

The top-level number type.

Included Modules

Direct Known Subclasses

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

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) >=

Instance methods inherited from module Comparable(Number)

<(other : T) <, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) >, >=(other : T) >=

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) =~, class class, dup dup, hash(hasher)
hash
hash
, inspect(io : IO) : Nil
inspect : String
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(&block) 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(&block) try, unsafe_as(type : T.class) forall T unsafe_as

Constructor methods inherited from class Object

from_json(string_or_io, root : String) : self
from_json(string_or_io) : self
from_json
, from_yaml(string_or_io : String | IO) : self 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 clamp(range : Range) #

Clamps a value within range.

5.clamp(10..100)   # => 10
50.clamp(10..100)  # => 50
500.clamp(10..100) # => 100

5.clamp(10..)  # => 10
50.clamp(10..) # => 50

5.clamp(..10)  # => 5
50.clamp(..10) # => 10

def clamp(min, max) #

Clamps a value between min and max.

5.clamp(10, 100)   # => 10
50.clamp(10, 100)  # => 50
500.clamp(10, 100) # => 100

5.clamp(10, nil)  # => 10
50.clamp(10, nil) # => 50

5.clamp(nil, 10)  # => 5
50.clamp(nil, 10) # => 10

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(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, UNDERSCORE) | Tuple(Int32, UNDERSCORE, 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, &block) : 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) : 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, &block) #

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)