Class: Faker::Date

Inherits:
Base
  • Object
show all
Defined in:
lib/faker/default/date.rb

Constant Summary collapse

DAYS_OF_WEEK = 
%i[sunday monday tuesday wednesday thursday friday saturday].freeze

Constants inherited from Base

Base::LLetters, Base::Letters, Base::NOT_GIVEN, Base::Numbers, Base::ULetters

Class Method Summary collapse

Methods inherited from Base

bothify, disable_enforce_available_locales, fetch, fetch_all, flexible, generate, letterify, method_missing, numerify, parse, rand, rand_in_range, regexify, resolve, respond_to_missing?, sample, shuffle, shuffle!, translate, unique, with_locale

Class Method Details

.backward(days: 365) ⇒ Date

Produce a random date in the past (up to N days).

Examples:

Faker::Date.backward(days: 14) #=> #<Date: 2019-09-12>

Parameters:

  • days (Integer) (defaults to: 365) —

    The maximum number of days to go into the past.

Returns:

Available since:

  • 1.0.0



90
91
92
93
94
95
 
# File 'lib/faker/default/date.rb', line 90

def backward(days: 365)
  from = ::Date.today - days
  to   = ::Date.today - 1

  between(from: from, to: to).to_date
end

.between(from:, to:) ⇒ Date

Produce a random date between two dates.

Examples:

if used with or without Rails (Active Support)

Faker::Date.between(from: '2014-09-23', to: '2014-09-25') #=> #<Date: 2014-09-24>

if used with Rails (Active Support)

Faker::Date.between(from: 2.days.ago, to: Date.today) #=> #<Date: 2014-09-24>

Parameters:

  • from (Date, String) —

    The start of the usable date range.

  • to (Date, String) —

    The end of the usable date range.

Returns:

Available since:

  • 1.0.0



22
23
24
25
26
27
 
# File 'lib/faker/default/date.rb', line 22

def between(from:, to:)
  from = get_date_object(from)
  to   = get_date_object(to)

  Faker::Base.rand_in_range(from, to)
end

.between_except(from:, to:, excepted:) ⇒ Date

Produce a random date between two dates.

Examples:

if used with or without Rails (Active Support)

Faker::Date.between_except(from: '2014-09-23', to: '2015-09-25', excepted: '2015-01-24') #=> #<Date: 2014-10-03>

if used with Rails (Active Support)

Faker::Date.between_except(from: 1.year.ago, to: 1.year.from_now, excepted: Date.today) #=> #<Date: 2014-10-03>

Parameters:

  • from (Date, String) —

    The start of the usable date range.

  • to (Date, String) —

    The end of the usable date range.

  • excepted (Date, String) —

    A date to exclude.

Returns:

Raises:

  • (ArgumentError)

Available since:

  • 1.6.2



44
45
46
47
48
49
50
51
52
53
 
# File 'lib/faker/default/date.rb', line 44

def between_except(from:, to:, excepted:)
  raise ArgumentError, 'From date, to date and excepted date must not be the same' if from == to && to == excepted

  excepted = get_date_object(excepted)

  loop do
    date = between(from: from, to: to)
    break date.to_date if date != excepted
  end
end

.birthday(min_age: 18, max_age: 65) ⇒ Date

Produce a random date in the past (up to N days).

Examples:

Faker::Date.birthday(min_age: 18, max_age: 65) #=> #<Date: 1986-03-28>

Parameters:

  • min_age (Integer) (defaults to: 18) —

    The minimum age that the birthday would imply.

  • max_age (Integer) (defaults to: 65) —

    The maximum age that the birthday would imply.

Returns:

Available since:

  • 1.4.3



108
109
110
111
112
113
114
115
 
# File 'lib/faker/default/date.rb', line 108

def birthday(min_age: 18, max_age: 65)
  t = ::Date.today

  from = birthday_date(t, max_age)
  to   = birthday_date(t, min_age)

  between(from: from, to: to).to_date
end

.forward(from: ::Date.today, days: 365) ⇒ Date

Produce a random date in the future (up to N days).

Examples:

if used with or without Rails (Active Support)

Faker::Date.forward(days: 23) #=> #<Date: 2014-10-03>

if used with Rails (Active Support)

Faker::Date.forward(from: Date.current, days: 17) #=> #<Date: 2022-06-22>

if used with or without Rails (Active Support)

Faker::Date.forward(from: '2022-06-03', days: 10) #=> #<Date: 2022-10-13>

Parameters:

  • from (Integer) (defaults to: ::Date.today) —

    The start of the usable forward date range.

  • days (Integer) (defaults to: 365) —

    The maximum number of days to go into the future.

Returns:

Available since:

  • 1.0.0



72
73
74
75
76
77
78
 
# File 'lib/faker/default/date.rb', line 72

def forward(from: ::Date.today, days: 365)
  start_date = get_date_object(from)
  since = start_date + 1
  to = start_date + days

  between(from: since, to: to).to_date
end

.in_date_period(month: nil, year: ::Date.today.year) ⇒ Date

Produces a date in the year and/or month specified.

Examples:

Faker::Date.in_date_period #=> #<Date: 2019-09-01>
Faker::Date.in_date_period(year: 2018, month: 2) #=> #<Date: 2018-02-26>
Faker::Date.in_date_period(month: 2) #=> #<Date: 2019-02-26>

Parameters:

  • month (Integer) (defaults to: nil) —

    represents the month of the date

  • year (Integer) (defaults to: ::Date.today.year) —

    represents the year of the date

Returns:

Available since:

  • 2.13.0



134
135
136
137
138
139
 
# File 'lib/faker/default/date.rb', line 134

def in_date_period(month: nil, year: ::Date.today.year)
  from = ::Date.new(year, month || 1, 1)
  to = ::Date.new(year, month || 12, ::Date.civil(year, month || 12, -1).day)

  between(from: from, to: to).to_date
end

.on_day_of_week_between(day:, from:, to:) ⇒ Date

Produce a random date at given day(s) of the week between two dates.

Examples:

if used with or without Rails (Active Support)

Faker::Date.on_day_of_week_between(day: :tuesday, from: '2023-01-01', to: '2023-02-01') #=> #<Date: 2032-01-10>

if used with Rails (Active Support)

Faker::Date.on_day_of_week_between(day: [:saturday, :sunday], from: 1.month.ago, to: Date.today) #=> #<Date: 2014-09-24>

Parameters:

  • day (Symbol, Array<Symbol>) —

    # The day(s) of the week. See DAYS_OF_WEEK.

  • from (Date, String) —

    The start of the usable date range.

  • to (Date, String) —

    The end of the usable date range.

Returns:

Raises:

  • (ArgumentError)

Available since:

  • next



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/faker/default/date.rb', line 156

def on_day_of_week_between(day:, from:, to:)
  days = [day].flatten
  raise ArgumentError, 'Day of week cannot be empty' if days.empty?

  # Convert given days of the week to numbers used by `Date#wday` method
  numeric_weekdays = days.map do |d|
    DAYS_OF_WEEK.index(d.to_sym.downcase) || raise(ArgumentError, "#{d} is not a valid day of the week")
  end

  from = get_date_object(from)
  to   = get_date_object(to)
  date = Faker::Base.rand_in_range(from, to)

  # If the initial date is not on one of the wanted days of the week...
  unless numeric_weekdays.include? date.wday
    # ...pick a date nearby that is on one of the wanted days of the week instead
    date += sample(numeric_weekdays) - date.wday

    # Move date 1 week earlier or later if the adjusted date is now outside the date range
    date += 7 if date < from
    date -= 7 if date > to

    if date > to || date < from
      raise ArgumentError,
            "There is no #{DAYS_OF_WEEK[date.wday].capitalize} between #{from} and #{to}. Increase the from/to date range or choose a different day of the week."
    end
  end

  date
end