# `Tempo.Microsecond`
[🔗](https://github.com/kipcole9/tempo/blob/v0.20.0/lib/tempo/microsecond.ex#L1)

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.

# `t`

```elixir
@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`.

# `from_fraction`

```elixir
@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: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`

```elixir
@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: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?`

```elixir
@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

---

*Consult [api-reference.md](api-reference.md) for complete listing*