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

Functions for generating random dates.

Provides utilities to generate random dates, including dates relative to today,
dates within a custom range, birthdays, past and future dates. All functions
support both `Date` struct and ISO 8601 string output formats.

# `add`
*since 0.9.0* 

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

Generates a random date within a specified range relative to today.

By default, returns a date between 365 days before and 365 days after the current date.
The range parameter specifies the number of days to add or subtract from today.

## Parameters

- `range` - The range of days relative to today. Defaults to `-365..365`.
- `opts` - Keyword list of options:
  - `:format` - Specifies the output format. Defaults to `:struct`.

## Options

The values for `:format` can be:

- `:struct` - Returns a `Date` struct (default).
- `:iso8601` - Returns an ISO 8601 formatted string.

## Examples

    iex> NeoFaker.Date.add()
    ~D[2025-03-25]

    iex> NeoFaker.Date.add(0..31)
    ~D[2025-03-30]

    iex> NeoFaker.Date.add(0..31, format: :iso8601)
    "2025-03-25"

# `between`
*since 0.9.0* 

```elixir
@spec between(Date.t(), Date.t(), Keyword.t()) :: Date.t() | String.t()
```

Generates a random date between two given dates.

Both `start` and `finish` are inclusive. Defaults to a date between the Unix
epoch (`~D[1970-01-01]`) and today.

## Parameters

- `start` - The start date (inclusive). Defaults to `~D[1970-01-01]`.
- `finish` - The end date (inclusive). Defaults to today's date.
- `opts` - Keyword list of options:
  - `:format` - Specifies the output format. Defaults to `:struct`.

## Options

The values for `:format` can be:

- `:struct` - Returns a `Date` struct (default).
- `:iso8601` - Returns an ISO 8601 formatted string.

## Examples

    iex> NeoFaker.Date.between()
    ~D[2025-03-25]

    iex> NeoFaker.Date.between(~D[2020-01-01], ~D[2025-01-01])
    ~D[2022-08-17]

    iex> NeoFaker.Date.between(~D[2025-03-25], ~D[2025-03-25], format: :iso8601)
    "2025-03-25"

# `birthday`
*since 0.10.0* 

```elixir
@spec birthday(non_neg_integer(), non_neg_integer(), Keyword.t()) ::
  Date.t() | String.t()
```

Generates a random birthday within the specified age range.

Calculates the valid date window from the current date and `min_age`/`max_age`,
then returns a random date within that window.

## Parameters

- `min_age` - The minimum age in years. Defaults to `18`.
- `max_age` - The maximum age in years. Defaults to `65`.
- `opts` - Keyword list of options:
  - `:format` - Specifies the output format. Defaults to `:struct`.

## Options

The values for `:format` can be:

- `:struct` - Returns a `Date` struct (default).
- `:iso8601` - Returns an ISO 8601 formatted string.

## Examples

    iex> NeoFaker.Date.birthday()
    ~D[1997-01-02]

    iex> NeoFaker.Date.birthday(18, 65)
    ~D[1998-03-04]

    iex> NeoFaker.Date.birthday(18, 65, format: :iso8601)
    "1999-05-06"

# `future`
*since 0.9.0* 

```elixir
@spec future(pos_integer(), Keyword.t()) :: Date.t() | String.t()
```

Generates a random date in the future.

Returns a random date between today and `days` from now. Equivalent to
`add(0..days, opts)`.

## Parameters

- `days` - The number of days ahead to look. Defaults to `365`.
- `opts` - Keyword list of options:
  - `:format` - Specifies the output format. Defaults to `:struct`.

## Examples

    iex> NeoFaker.Date.future(30)
    ~D[2025-04-24]

    iex> NeoFaker.Date.future(365, format: :iso8601)
    "2026-03-25"

# `past`
*since 0.9.0* 

```elixir
@spec past(pos_integer(), Keyword.t()) :: Date.t() | String.t()
```

Generates a random date in the past.

Returns a random date between `days` ago and today. Equivalent to
`add(-days..0, opts)`.

## Parameters

- `days` - The number of days in the past to look back. Defaults to `365`.
- `opts` - Keyword list of options:
  - `:format` - Specifies the output format. Defaults to `:struct`.

## Examples

    iex> NeoFaker.Date.past(30)
    ~D[2025-02-25]

    iex> NeoFaker.Date.past(365, format: :iso8601)
    "2024-03-25"

# `today`
*since 0.9.0* 

```elixir
@spec today(Keyword.t()) :: Date.t() | String.t()
```

Returns today's local date.

A convenience wrapper that always returns the current date without any
randomisation.

## Parameters

- `opts` - Keyword list of options:
  - `:format` - Specifies the output format. Defaults to `:struct`.

## Examples

    iex> NeoFaker.Date.today()
    ~D[2025-03-25]

    iex> NeoFaker.Date.today(format: :iso8601)
    "2025-03-25"

---

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