# `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). All functions support both `Time` struct and ISO 8601 string output.

# `add`
*since 0.10.0* 

```elixir
@spec add(Range.t(), Keyword.t()) :: Time.t() | String.t()
```

Generates a random time offset from now.

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

## Options

- `:unit` - Unit of the range. One of `:hour` (default), `:minute`, or `:second`.
- `:format` - Output format. Either `:struct` (default) or `:iso8601`.

## Examples

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

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

    iex> NeoFaker.Time.add(0..10, format: :iso8601)
    "15:22:10"

# `afternoon`
*since 0.10.0* 

```elixir
@spec afternoon(Keyword.t()) :: Time.t() | String.t()
```

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

## Options

- `:format` - Output format. Either `:struct` (default) or `:iso8601`.

## Examples

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

    iex> NeoFaker.Time.afternoon(format: :iso8601)
    "15:45:22"

# `between`
*since 0.10.0* 

```elixir
@spec between(Time.t(), Time.t(), Keyword.t()) :: Time.t() | String.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]`).

## Parameters

- `start` - Start time, inclusive. Defaults to `~T[00:00:00]`.
- `finish` - End time, inclusive. Defaults to `~T[23:59:59]`.
- `opts` - Keyword list of options:
  - `:format` - Output format. Either `:struct` (default) or `:iso8601`.

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

    iex> NeoFaker.Time.between(~T[00:00:00], ~T[23:59:59], format: :iso8601)
    "15:22:10"

# `evening`
*since 0.10.0* 

```elixir
@spec evening(Keyword.t()) :: Time.t() | String.t()
```

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

## Options

- `:format` - Output format. Either `:struct` (default) or `:iso8601`.

## Examples

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

    iex> NeoFaker.Time.evening(format: :iso8601)
    "21:45:22"

# `morning`
*since 0.10.0* 

```elixir
@spec morning(Keyword.t()) :: Time.t() | String.t()
```

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

## Options

- `:format` - Output format. Either `:struct` (default) or `:iso8601`.

## Examples

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

    iex> NeoFaker.Time.morning(format: :iso8601)
    "09:45:22"

# `night`
*since 0.10.0* 

```elixir
@spec night(Keyword.t()) :: Time.t() | String.t()
```

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

## Options

- `:format` - Output format. Either `:struct` (default) or `:iso8601`.

## Examples

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

    iex> NeoFaker.Time.night(format: :iso8601)
    "03:45:22"

# `now`
*since 0.10.0* 

```elixir
@spec now(Keyword.t()) :: Time.t() | String.t()
```

Returns the current UTC time.

A convenience wrapper that returns `Time.utc_now()` with optional formatting.

## Options

- `:format` - Output format. Either `:struct` (default) or `:iso8601`.

## Examples

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

    iex> NeoFaker.Time.now(format: :iso8601)
    "15:22:10"

# `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*