Tempo.Microsecond (Tempo v0.20.0)

Copy Markdown View Source

Conversions for Tempo's sub-second component.

Tempo represents sub-second resolution with a :microsecond time component carrying the same {value, precision} shape used by Elixir's Time, NaiveDateTime, and DateTime structs:

  • value is an absolute microsecond count in the range 0..999_999.

  • precision is the number of significant fractional digits, in the range 0..6. It records the declared resolution and therefore the width of the implied interval — {120_000, 2} is the centisecond interval [.12, .13) whereas {120_000, 3} is the millisecond interval [.120, .121).

Because value is always normalised to microseconds, ordering two sub-second parts is a direct integer comparison of their values; precision plays no role in comparison, only in interval width and formatting.

The maximum precision is 6 (microsecond), matching Elixir. Fractional input carrying more than 6 digits is truncated to microsecond resolution.

Summary

Types

t()

A sub-second component: {microsecond_value, precision} where microsecond_value is 0..999_999 and precision is 0..6.

Functions

from_fraction(fraction_integer, digit_count)

Convert parsed fractional-second digits into a {value, precision} microsecond component.

to_digits_string(arg)

Render a microsecond component as its fractional-digit string, zero-padded to precision digits (no leading decimal separator).

valid?(arg1)

Return true when value is a well-formed microsecond component.

Types

t()

@type t() :: {0..999_999, 0..6}

A sub-second component: {microsecond_value, precision} where microsecond_value is 0..999_999 and precision is 0..6.

Functions

from_fraction(fraction_integer, digit_count)

@spec from_fraction(non_neg_integer(), non_neg_integer()) :: t()

Convert parsed fractional-second digits into a {value, precision} microsecond component.

Arguments

  • fraction_integer is the fractional digits parsed as an integer (for example the digits after the decimal separator in 45.0123 parse to 123).

  • digit_count is the number of fractional digits as written, including leading zeros (for 45.0123 it is 4). The digit count, not the integer, determines precision — leading zeros are significant.

Returns

  • A t/0 tuple {microsecond_value, precision}. When digit_count exceeds 6, the value is truncated to microsecond resolution and precision is capped at 6.

Examples

iex> Tempo.Microsecond.from_fraction(123, 3)
{123000, 3}

iex> Tempo.Microsecond.from_fraction(123, 4)
{12300, 4}

iex> Tempo.Microsecond.from_fraction(123456, 6)
{123456, 6}

iex> Tempo.Microsecond.from_fraction(1234567, 7)
{123456, 6}

to_digits_string(arg)

@spec to_digits_string(t()) :: String.t()

Render a microsecond component as its fractional-digit string, zero-padded to precision digits (no leading decimal separator).

Arguments

  • microsecond is a t/0 tuple {value, precision}.

Returns

  • A string of exactly precision digits, or the empty string when precision is 0.

Examples

iex> Tempo.Microsecond.to_digits_string({123000, 3})
"123"

iex> Tempo.Microsecond.to_digits_string({120000, 3})
"120"

iex> Tempo.Microsecond.to_digits_string({123, 6})
"000123"

iex> Tempo.Microsecond.to_digits_string({0, 0})
""

valid?(arg1)

@spec valid?(term()) :: boolean()

Return true when value is a well-formed microsecond component.

Arguments

  • value is any term.

Returns

  • true if value is a {microsecond_value, precision} tuple with microsecond_value in 0..999_999 and precision in 0..6; false otherwise.

Examples

iex> Tempo.Microsecond.valid?({123000, 3})
true

iex> Tempo.Microsecond.valid?({1_000_000, 6})
false

iex> Tempo.Microsecond.valid?({100, 7})
false