# abstract struct Number

## Overview

The top-level number type.

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.

## Macro Summary

, , , , , ,

, , , , , ,

,

### Instance methods inherited from class Object

, , , , , , , , , , , , , , , , , , , , , , , , , ,

,

## Constructor Detail

Returns the additive identity of this type.

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

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

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 : 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]

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 : 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, *, 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, *, 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 #

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)

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

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)

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)

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)