Fab.DateTime (fab v1.2.2)

Functions for generating random DateTime's.

Summary

Types

days_t()
from_t()
ref_date_t()
to_t()
unit_t()
years_t()

Functions

anytime(opts \\ [])

Generates a random date that can be in the past or future.

between(opts)

Generates a random date between two dates.

future(opts \\ [])

Generates a random date years in the future.

past(opts \\ [])

Generates a random date years in the past.

recent(opts \\ [])

Generates a random date days in the past.

soon(opts \\ [])

Generates a random date days in the future.

Types

days_t()

@type days_t() :: {:days, pos_integer()}

from_t()

@type from_t() :: {:from, DateTime.t()}

ref_date_t()

@type ref_date_t() :: {:ref_date, DateTime.t()}

to_t()

@type to_t() :: {:to, DateTime.t()}

unit_t()

@type unit_t() :: {:unit, :microsecond | :millisecond | :native | :second}

years_t()

@type years_t() :: {:years, pos_integer()}

Functions

anytime(opts \\ [])

(since 1.0.0) 
@spec anytime([ref_date_t() | unit_t()]) :: DateTime.t()

Generates a random date that can be in the past or future.

Options

  • :ref_date - DateTime used as the reference point for the newly generated date. Defaults to DateTime.utc_now/1.
  • :unit - Time unit used for the generated date. Can be :microsecond, :millisecond, :native or :second. Defaults to :native.

Examples

iex> Fab.DateTime.anytime()
~U[1523-04-23 21:41:18.532309Z]

iex> Fab.DateTime.anytime(unit: :second)
~U[1965-10-18 11:26:15Z]

between(opts)

(since 1.0.0) 
@spec between([from_t() | to_t() | unit_t()]) :: DateTime.t()

Generates a random date between two dates.

Options

  • :from - DateTime used as the early date boundary
  • :to - DateTime used as the late date boundary
  • :unit - Time unit used for the generated date. Can be :microsecond, :millisecond, :native or :second. Defaults to :native.

Examples

iex> Fab.DateTime.between(from: ~U[2025-05-04 18:21:38Z], to: ~U[2025-05-05 21:38:40Z])
~U[2025-05-05 21:38:28.112142Z]

iex> Fab.DateTime.between(from: ~U[2025-05-05 01:57:58Z], to: ~U[2025-05-06 10:34:09Z], unit: :second)
~U[2025-05-05 19:09:21Z]

future(opts \\ [])

(since 1.0.0) 
@spec future([ref_date_t() | unit_t() | years_t()]) :: DateTime.t()

Generates a random date years in the future.

Options

  • :ref_date - DateTime used as the reference point for the newly generated date. Defaults to DateTime.utc_now/1.
  • :unit - Time unit used for the generated date. Can be :microsecond, :millisecond, :native or :second. Defaults to :native.
  • :years - Number of years the date may be in the future. Defaults to 1.

Examples

iex> Fab.DateTime.future()
~U[2026-04-07 00:06:12.857101Z]

iex> Fab.DateTime.future(years: 10)
~U[2028-09-19 10:23:55.939960Z]

iex> Fab.DateTime.future(unit: :second)
~U[2026-03-24 06:13:08Z]

past(opts \\ [])

(since 1.0.0) 
@spec past([ref_date_t() | unit_t() | years_t()]) :: DateTime.t()

Generates a random date years in the past.

Options

  • :ref_date - DateTime used as the reference point for the newly generated date. Defaults to DateTime.utc_now/1.
  • :unit - Time unit used for the generated date. Can be :microsecond, :millisecond, :native or :second. Defaults to :native.
  • :years - Number of years the date may be in the past. Defaults to 1.

Examples

iex> Fab.DateTime.past()
~U[2025-01-24 16:01:23.564206Z]

iex> Fab.DateTime.past(years: 10)
~U[2023-04-24 03:50:54.545857Z]

iex> Fab.DateTime.past(unit: :second)
~U[2024-07-30 14:33:43Z]

recent(opts \\ [])

(since 1.0.0) 
@spec recent([days_t() | ref_date_t() | unit_t()]) :: DateTime.t()

Generates a random date days in the past.

Options

  • :days - Number of days the date may be in the past. Defaults to 1.
  • :ref_date - DateTime used as the reference point for the newly generated date. Defaults to DateTime.utc_now/1.
  • :unit - Time unit used for the generated date. Can be :microsecond, :millisecond, :native or :second. Defaults to :native.

Examples

iex> Fab.DateTime.recent()
~U[2025-05-05 04:53:03.098150Z]

iex> Fab.DateTime.recent(days: 10)
~U[2025-05-03 21:37:48.405103Z]

iex> Fab.DateTime.recent(unit: :second)
~U[2025-05-05 16:44:47Z]

soon(opts \\ [])

(since 1.0.0) 
@spec soon([days_t() | ref_date_t() | unit_t()]) :: DateTime.t()

Generates a random date days in the future.

Options

  • :days - Number of days the date may be in the future. Defaults to 1.
  • :ref_date - DateTime used as the reference point for the newly generated date. Defaults to DateTime.utc_now/1.
  • :unit - Time unit used for the generated date. Can be :microsecond, :millisecond, :native or :second. Defaults to :native.

Examples

iex> Fab.DateTime.soon()
~U[2025-05-05 19:38:07.213655Z]

iex> Fab.DateTime.soon(days: 10)
~U[2025-05-12 08:56:42.439410Z]

iex> Fab.DateTime.soon(unit: :second)
~U[2025-05-06 11:10:33Z]