NeoFaker.Date (neo_faker v0.15.0)

Copy Markdown View Source

Functions for generating random dates.

Provides utilities to generate random dates, including dates relative to today, dates within a custom range, birthdays, and past and future dates. Every function returns a Date struct; call Date.to_iso8601/1 yourself if you need a string.

Summary

Functions

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

Generates a random birthday within the specified age range.

Generates a random date in the future.

Generates a random date in the past.

Returns today's local date.

Functions

add(range \\ %{__struct__: Range, first: -365, last: 365, step: 1})

(since 0.9.0)
@spec add(Range.t()) :: Date.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. range specifies the number of days to add or subtract from today.

Examples

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

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

between(start \\ %{__struct__: Date, calendar: Calendar.ISO, day: 1, month: 1, year: 1970}, finish \\ Generator.local_date_now())

(since 0.9.0)
@spec between(Date.t(), Date.t()) :: Date.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.

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]

birthday(min_age \\ 18, max_age \\ 65)

(since 0.10.0)
@spec birthday(non_neg_integer(), non_neg_integer()) :: Date.t()

Generates a random birthday within the specified age range.

Calculates the valid date window from the current date and min_age/max_age (defaulting to 18 and 65 respectively), then returns a random date within that window.

Examples

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

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

future(days \\ 365)

(since 0.9.0)
@spec future(pos_integer()) :: Date.t()

Generates a random date in the future.

Returns a random date between today and days from now (defaults to 365). Equivalent to add(0..days).

Examples

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

past(days \\ 365)

(since 0.9.0)
@spec past(pos_integer()) :: Date.t()

Generates a random date in the past.

Returns a random date between days ago (defaults to 365) and today. Equivalent to add(-days..0).

Examples

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

today()

(since 0.9.0)
@spec today() :: Date.t()

Returns today's local date.

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

Examples

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