# `NeoFaker.Time`
[🔗](https://github.com/muzhawir/neo_faker/blob/main/lib/neo_faker/time.ex#L1)

Functions for generating random times.

Provides utilities to generate random times, including times relative to now,
times within a specific range, time zones, and named periods (morning, afternoon,
evening, night). Every function returns a `Time` struct; call `Time.to_iso8601/1`
yourself if you need a string.

# `add`
*since 0.10.0* 

```elixir
@spec add(Range.t(), keyword()) :: Time.t()
```

Generates a random time offset from now.

Adds a random number of units (hours by default) drawn from `range` to the current time.
`range` defaults to `-24..24`.

## Options

  * `:unit` (`:hour`, `:minute`, or `:second`) - the unit of the range. Defaults to `:hour`.

## Examples

    iex> NeoFaker.Time.add()
    ~T[15:22:10]

    iex> NeoFaker.Time.add(-2..2, unit: :minute)
    ~T[07:23:10]

# `afternoon`
*since 0.10.0* 

```elixir
@spec afternoon() :: Time.t()
```

Generates a random afternoon time (12:00–17:59).

## Examples

    iex> NeoFaker.Time.afternoon()
    ~T[14:30:15]

# `between`
*since 0.10.0* 

```elixir
@spec between(Time.t(), Time.t()) :: Time.t()
```

Generates a random time between two times.

Both `start` and `finish` are inclusive. Defaults to the full day
(`~T[00:00:00]`–`~T[23:59:59]`).

## Examples

    iex> NeoFaker.Time.between()
    ~T[15:22:10]

    iex> NeoFaker.Time.between(~T[00:00:00], ~T[23:59:59])
    ~T[19:30:11]

# `evening`
*since 0.10.0* 

```elixir
@spec evening() :: Time.t()
```

Generates a random evening time (18:00–23:59).

## Examples

    iex> NeoFaker.Time.evening()
    ~T[20:30:15]

# `morning`
*since 0.10.0* 

```elixir
@spec morning() :: Time.t()
```

Generates a random morning time (06:00–11:59).

## Examples

    iex> NeoFaker.Time.morning()
    ~T[08:30:15]

# `night`
*since 0.10.0* 

```elixir
@spec night() :: Time.t()
```

Generates a random night time (00:00–05:59).

## Examples

    iex> NeoFaker.Time.night()
    ~T[02:30:15]

# `now`
*since 0.10.0* 

```elixir
@spec now() :: Time.t()
```

Returns the current UTC time.

A thin convenience wrapper around `Time.utc_now/0`.

## Examples

    iex> NeoFaker.Time.now()
    ~T[15:22:10.123456]

# `time_zone`
*since 0.10.0* 

```elixir
@spec time_zone() :: String.t()
```

Generates a random time zone string.

Returns an IANA time zone name from a predefined list, such as
`"Asia/Makassar"` or `"America/New_York"`.

## Examples

    iex> NeoFaker.Time.time_zone()
    "Asia/Makassar"

---

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