Localize.Utils.Digits (Localize v0.22.0)

Abstract representation of number (integer, float, Decimal) in tuple form and functions for transformations on number parts.

Representing a number as a list of its digits, an integer representing where the decimal point is placed, and an integer representing the sign of the number allow more efficient transforms on the various parts of the number as happens during the formatting of a number for string output.

A number in integer, float or Decimal form can be converted to digit form with to_digits/1.

The digits can be converted back to normal form with Localize.Utils.Digits.to_integer/1, Localize.Utils.Digits.to_float/1 and Localize.Utils.Digits.to_decimal/1.

Summary

Types

t()

Defines a number in a tuple form of three parts

Functions

fraction_as_integer(number)

Returns the fractional part of an integer, float or Decimal as an integer.

fraction_as_integer(number, rounding)

Returns the fractional part of a float as an integer, rounding to the specified number of digits first.

number_of_digits(number)

Returns the number of decimal digits in a number (integer, float, Decimal).

number_of_integer_digits(number)

Returns the number of decimal digits in the integer part of a number.

number_of_leading_zeros(number)

Returns the number of leading zeros in the fractional part of a number.

number_of_trailing_zeros(number)

Returns the number of trailing zeros in an integer number.

remove_trailing_zeros(number)

Removes trailing zeros from the integer part of a number and returns the integer part without trailing zeros.

to_decimal(arg)

Converts a digit tuple to a Decimal.

to_digits(float_0)

Computes a list of the digits of the given IEEE 754 floating point number, together with the location of the decimal point as {digits, place, sign}.

to_float(arg)

Converts a digit tuple to a float.

to_integer(arg)

Converts a digit tuple to an integer.

to_number(digits, number)

Takes a list of digits and converts them back to a number of the same type as number.

to_tuple(number)

Converts given number to a list representation.

Types

t()

@type t() :: {[0..9, ...], non_neg_integer(), 1 | -1}

Defines a number in a tuple form of three parts:

A list of digits (0..9) representing the number.
A digit representing the place of the decimal point in the number.
A 1 or -1 representing the sign of the number.

Functions

fraction_as_integer(number)

@spec fraction_as_integer(number() | Decimal.t() | {list(), list(), 1 | -1}) ::
  integer()

Returns the fractional part of an integer, float or Decimal as an integer.

Arguments

number is a float, Decimal, integer, or a tuple of the form {integer_list, fraction_list, sign} as returned by to_tuple/1.

Returns

An integer representing the fractional digits.

Examples

iex> Localize.Utils.Digits.fraction_as_integer(123.456)
456

iex> Localize.Utils.Digits.fraction_as_integer(Decimal.new("123.456"))
456

iex> Localize.Utils.Digits.fraction_as_integer(1999)
0

fraction_as_integer(number, rounding)

@spec fraction_as_integer(float(), pos_integer()) :: integer()

Returns the fractional part of a float as an integer, rounding to the specified number of digits first.

Arguments

number is a float.
rounding is a positive integer specifying the number of fractional digits.

Returns

An integer representing the fractional digits.

Examples

iex> Localize.Utils.Digits.fraction_as_integer(1.456, 3)
456

number_of_digits(number)

@spec number_of_digits(
  number()
  | Decimal.t()
  | list()
  | {[integer(), ...], integer() | [integer(), ...], -1 | 1}
) :: integer()

Returns the number of decimal digits in a number (integer, float, Decimal).

Arguments

number is an integer, float, Decimal, or a list (which is assumed to contain digits).

Returns

An integer count of the total number of digits.

Examples

iex> Localize.Utils.Digits.number_of_digits(1234)
4

iex> Localize.Utils.Digits.number_of_digits(Decimal.new("123456789"))
9

iex> Localize.Utils.Digits.number_of_digits(1234.456)
7

iex> Localize.Utils.Digits.number_of_digits(1234.56789098765)
15

iex> Localize.Utils.Digits.number_of_digits(~c"12345")
5

number_of_integer_digits(number)

@spec number_of_integer_digits(
  number()
  | Decimal.t()
  | list()
  | {[integer(), ...], integer() | [integer(), ...], -1 | 1}
) :: integer()

Returns the number of decimal digits in the integer part of a number.

Arguments

number is an integer, float, Decimal, or a list (which is assumed to contain digits).

Returns

A non-negative integer count of integer digits.

Examples

iex> Localize.Utils.Digits.number_of_integer_digits(1234)
4

iex> Localize.Utils.Digits.number_of_integer_digits(Decimal.new("123456789"))
9

iex> Localize.Utils.Digits.number_of_integer_digits(1234.456)
4

iex> Localize.Utils.Digits.number_of_integer_digits(~c"12345")
5

number_of_leading_zeros(number)

@spec number_of_leading_zeros(number() | Decimal.t() | [integer(), ...]) :: integer()

Returns the number of leading zeros in the fractional part of a number.

Arguments

number is an integer, float, Decimal, or a list of digits.

Returns

An integer count of leading zeros.

Examples

iex> Localize.Utils.Digits.number_of_leading_zeros(Decimal.new("0.0001"))
3

number_of_trailing_zeros(number)

Returns the number of trailing zeros in an integer number.

Arguments

number is an integer or a list of digits.

Returns

An integer count of trailing zeros.

Examples

iex> Localize.Utils.Digits.number_of_trailing_zeros(123000)
3

remove_trailing_zeros(number)

@spec remove_trailing_zeros(number() | Decimal.t() | [integer(), ...]) ::
  number() | [integer()]

Removes trailing zeros from the integer part of a number and returns the integer part without trailing zeros.

Arguments

number is an integer, float, Decimal, or a list of digits.

Returns

An integer with trailing zeros removed, or a list with trailing zeros removed.

Examples

iex> Localize.Utils.Digits.remove_trailing_zeros(1234000)
1234

iex> Localize.Utils.Digits.remove_trailing_zeros(0)
0

to_decimal(arg)

Converts a digit tuple to a Decimal.

Arguments

digits is a tuple {digit_list, place, sign} as returned by to_digits/1.

Returns

A %Decimal{} struct.

Examples

iex> Localize.Utils.Digits.to_decimal({[1, 2, 3], 2, 1})
Decimal.new("12.3")

to_digits(float_0)

Computes a list of the digits of the given IEEE 754 floating point number, together with the location of the decimal point as {digits, place, sign}.

Given an IEEE 754 float, computes the shortest, correctly rounded list of digits that converts back to the same Double value when read back with String.to_float/1. Implements the algorithm from "Printing Floating-Point Numbers Quickly and Accurately" in Proceedings of the SIGPLAN '96 Conference on Programming Language Design and Implementation.

A "compact" representation is returned, so there may be fewer digits returned than the decimal point location.

Arguments

number is a float, integer, or Decimal.

Returns

A tuple {digits, place, sign} where digits is a list of integers 0..9, place is the decimal point position, and sign is 1 or -1.

Examples

iex> Localize.Utils.Digits.to_digits(0.0)
{[0], 1, 1}

iex> Localize.Utils.Digits.to_digits(123)
{[1, 2, 3], 3, 1}

to_float(arg)

Converts a digit tuple to a float.

Arguments

digits is a tuple {digit_list, place, sign} as returned by to_digits/1.

Returns

A float.

Examples

iex> Localize.Utils.Digits.to_float({[1, 2, 3, 4], 2, 1})
12.34

to_integer(arg)

Converts a digit tuple to an integer.

Arguments

digits is a tuple {digit_list, place, sign} as returned by to_digits/1.

Returns

An integer.

Examples

iex> Localize.Utils.Digits.to_integer({[1, 2, 3, 4], 4, 1})
1234

to_number(digits, number)

Takes a list of digits and converts them back to a number of the same type as number.

Arguments

digits is a tuple {digit_list, place, sign} as returned by to_digits/1.
number is a number or atom indicating the desired return type. Supported values are an integer, float, %Decimal{}, or the atoms :integer, :float, :decimal.

Returns

A number of the requested type.

Examples

iex> Localize.Utils.Digits.to_number({[1, 2, 3], 3, 1}, :integer)
123

iex> Localize.Utils.Digits.to_number({[1, 2, 3], 3, 1}, :float)
123.0

to_tuple(number)

@spec to_tuple(Decimal.t() | number()) :: {list(), list(), integer()}

Converts given number to a list representation.

Returns a tuple comprising a list for the integer part, a list for the fractional part, and an integer for the sign.

Arguments

number is a float, integer, or Decimal.

Returns

A tuple {integer_digits, fraction_digits, sign} where each digit list contains integers 0..9 and sign is 1 or -1.

Examples

iex> Localize.Utils.Digits.to_tuple(123.456)
{[1, 2, 3], [4, 5, 6], 1}