Class: ActiveDateRange::DateRange

Inherits:
Range
  • Object
show all
Defined in:
lib/active_date_range/date_range.rb

Overview

Provides a DateRange with parsing, calculations and query methods

Constant Summary collapse

SHORTHANDS = 
{
  this_month: -> { DateRange.new(Time.zone.today.all_month) },
  prev_month: -> { DateRange.new(1.month.ago.to_date.all_month) },
  next_month: -> { DateRange.new(1.month.from_now.to_date.all_month) },
  this_quarter: -> { DateRange.new(Time.zone.today.all_quarter) },
  prev_quarter: -> { DateRange.new(3.months.ago.to_date.all_quarter) },
  next_quarter: -> { DateRange.new(3.months.from_now.to_date.all_quarter) },
  this_year: -> { DateRange.new(Time.zone.today.all_year) },
  prev_year: -> { DateRange.new(12.months.ago.to_date.all_year) },
  next_year: -> { DateRange.new(12.months.from_now.to_date.all_year) },
  this_week: -> { DateRange.new(Time.zone.today.all_week) },
  prev_week: -> { DateRange.new(1.week.ago.to_date.all_week) },
  next_week: -> { DateRange.new(1.week.from_now.to_date.all_week) }
}.freeze
RANGE_PART_REGEXP = 
%r{\A(?<year>((1\d|2\d)\d\d))-?(?<month>0[1-9]|1[012])-?(?<day>[0-2]\d|3[01])?\z}

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(begin_date, end_date = nil) ⇒ DateRange

Initializes a new DateRange. Accepts both a begin and end date or a range of dates. Make sures the begin date is before the end date.

Raises:



65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/active_date_range/date_range.rb', line 65

def initialize(begin_date, end_date = nil)
  begin_date, end_date = begin_date.begin, begin_date.end if begin_date.kind_of?(Range)
  begin_date, end_date = begin_date.first, begin_date.last if begin_date.kind_of?(Array)
  begin_date = begin_date.to_date if begin_date.kind_of?(Time)
  end_date = end_date.to_date if end_date.kind_of?(Time)

  raise InvalidDateRange, "Date range invalid, begin should be a date" if begin_date && !begin_date.kind_of?(Date)
  raise InvalidDateRange, "Date range invalid, end should be a date" if end_date && !end_date.kind_of?(Date)
  raise InvalidDateRange, "Date range invalid, begin #{begin_date} is after end #{end_date}" if begin_date && end_date && begin_date > end_date

  super(begin_date, end_date)
end

Class Method Details

.parse(input) ⇒ Object

Parses a date range string to a DateRange instance. Valid formats are:

  • A relative shorthand: this_month, prev_month, next_month, etc.

  • A begin and end date: YYYYMMDD..YYYYMMDD

  • A begin and end month: YYYYMM..YYYYMM

Raises:



33
34
35
36
37
38
39
40
41
 
# File 'lib/active_date_range/date_range.rb', line 33

def self.parse(input)
  return DateRange.new(input) if input.kind_of?(Range)
  return SHORTHANDS[input.to_sym].call if SHORTHANDS.key?(input.to_sym)

  begin_date, end_date = input.split("..")
  raise InvalidDateRangeFormat, "#{input} doesn't have a begin..end format" if begin_date.blank? && end_date.blank?

  DateRange.new(parse_date(begin_date), parse_date(end_date, last: true))
end

Instance Method Details

#+(other) ⇒ Object

Adds two date ranges together. Fails when the ranges are not subsequent.

Raises:



79
80
81
82
83
 
# File 'lib/active_date_range/date_range.rb', line 79

def +(other)
  raise InvalidAddition if self.end != (other.begin - 1.day)

  DateRange.new(self.begin, other.end)
end

#<=>(other) ⇒ Object

Sorts two date ranges by the begin date.



86
87
88
 
# File 'lib/active_date_range/date_range.rb', line 86

def <=>(other)
  self.begin <=> other.begin
end

#after?(date) ⇒ Boolean

Returns true when the date range is after the given date. Accepts both a Date and DateRange as input.

Returns:

  • (Boolean) 


218
219
220
221
 
# File 'lib/active_date_range/date_range.rb', line 218

def after?(date)
  date = date.end if date.kind_of?(DateRange)
  self.begin.present? && self.begin.after?(date)
end

#before?(date) ⇒ Boolean

Returns true when the date range is before the given date. Accepts both a Date and DateRange as input.

Returns:

  • (Boolean) 


211
212
213
214
 
# File 'lib/active_date_range/date_range.rb', line 211

def before?(date)
  date = date.begin if date.kind_of?(DateRange)
  self.end.present? && self.end.before?(date)
end

#begin_at_beginning_of_month? ⇒ Boolean

Returns true when begin of the range is at the beginning of the month

Returns:

  • (Boolean) 


130
131
132
 
# File 'lib/active_date_range/date_range.rb', line 130

def begin_at_beginning_of_month?
  self.begin.present? && self.begin.day == 1
end

#begin_at_beginning_of_quarter? ⇒ Boolean

Returns true when begin of the range is at the beginning of the quarter

Returns:

  • (Boolean) 


135
136
137
 
# File 'lib/active_date_range/date_range.rb', line 135

def begin_at_beginning_of_quarter?
  self.begin.present? && begin_at_beginning_of_month? && [1, 4, 7, 10].include?(self.begin.month)
end

#begin_at_beginning_of_week? ⇒ Boolean

Returns true when begin of the range is at the beginning of the week

Returns:

  • (Boolean) 


145
146
147
 
# File 'lib/active_date_range/date_range.rb', line 145

def begin_at_beginning_of_week?
  self.begin.present? && self.begin == self.begin.at_beginning_of_week
end

#begin_at_beginning_of_year? ⇒ Boolean

Returns true when begin of the range is at the beginning of the year

Returns:

  • (Boolean) 


140
141
142
 
# File 'lib/active_date_range/date_range.rb', line 140

def begin_at_beginning_of_year?
  self.begin.present? && begin_at_beginning_of_month? && self.begin.month == 1
end

#boundless? ⇒ Boolean

Returns:

  • (Boolean) 


90
91
92
 
# File 'lib/active_date_range/date_range.rb', line 90

def boundless?
  self.begin.nil? || self.end.nil?
end

#days ⇒ Object

Returns the number of days in the range



95
96
97
98
99
 
# File 'lib/active_date_range/date_range.rb', line 95

def days
  return if boundless?

  @days ||= (self.end - self.begin).to_i + 1
end

#full_month? ⇒ Boolean Also known as: full_months?

Returns true when the range is exactly one or more months long

Returns:

  • (Boolean) 


177
178
179
 
# File 'lib/active_date_range/date_range.rb', line 177

def full_month?
  begin_at_beginning_of_month? && self.end.present? && self.end == self.end.at_end_of_month
end

#full_quarter? ⇒ Boolean Also known as: full_quarters?

Returns true when the range is exactly one or more quarters long

Returns:

  • (Boolean) 


184
185
186
 
# File 'lib/active_date_range/date_range.rb', line 184

def full_quarter?
  begin_at_beginning_of_quarter? && self.end.present? && self.end == self.end.at_end_of_quarter
end

#full_week? ⇒ Boolean Also known as: full_weeks?

Returns true when the range is exactly one or more weeks long

Returns:

  • (Boolean) 


198
199
200
 
# File 'lib/active_date_range/date_range.rb', line 198

def full_week?
  begin_at_beginning_of_week? && self.end.present? && self.end == self.end.at_end_of_week
end

#full_year? ⇒ Boolean Also known as: full_years?

Returns true when the range is exactly one or more years long

Returns:

  • (Boolean) 


191
192
193
 
# File 'lib/active_date_range/date_range.rb', line 191

def full_year?
  begin_at_beginning_of_year? && self.end.present? && self.end == self.end.at_end_of_year
end

#granularity ⇒ Object

Returns the granularity of the range. Returns either :year, :quarter or :month based on if the range has exactly this length.

DateRange.this_month.granularity    # => :month
DateRange.this_quarter.granularity  # => :quarter
DateRange.this_year.granularity     # => :year



229
230
231
232
233
234
235
236
237
238
239
 
# File 'lib/active_date_range/date_range.rb', line 229

def granularity
  if one_year?
    :year
  elsif one_quarter?
    :quarter
  elsif one_month?
    :month
  elsif one_week?
    :week
  end
end

#humanize(format: :short) ⇒ Object

Returns a human readable format for the date range. See DateRange::Humanizer for options.



336
337
338
 
# File 'lib/active_date_range/date_range.rb', line 336

def humanize(format: :short)
  Humanizer.new(self, format: format).humanize
end

#in_groups_of(granularity, amount: 1) ⇒ Object

Returns an array with date ranges containing full months/quarters/years in the current range. Comes in handy when you need to have columns by month for a given range: ‘DateRange.this_year.in_groups_of(:months)`

Always returns full months/quarters/years, from the first to the last day of the period. The first and last item in the array can have a partial month/quarter/year, depending on the date range.

DateRange.parse("202101..202103").in_groups_of(:month) # => [DateRange.parse("202001..202001"), DateRange.parse("202002..202002"), DateRange.parse("202003..202003")]
DateRange.parse("202101..202106").in_groups_of(:month, amount: 2) # => [DateRange.parse("202001..202002"), DateRange.parse("202003..202004"), DateRange.parse("202005..202006")]

Raises:



325
326
327
328
329
330
331
332
333
 
# File 'lib/active_date_range/date_range.rb', line 325

def in_groups_of(granularity, amount: 1)
  raise BoundlessRangeError, "Can't group date range without a begin." if self.begin.nil?

  if boundless?
    grouped_collection(granularity, amount: amount)
  else
    grouped_collection(granularity, amount: amount).to_a
  end
end

#include?(other) ⇒ Boolean

Returns:

  • (Boolean) 


346
347
348
 
# File 'lib/active_date_range/date_range.rb', line 346

def include?(other)
  cover?(other)
end

#intersection(other) ⇒ Object

Returns the intersection of the current and the other date range



341
342
343
344
 
# File 'lib/active_date_range/date_range.rb', line 341

def intersection(other)
  intersection = self.to_a.intersection(other.to_a).sort
  DateRange.new(intersection) if intersection.any?
end

#months ⇒ Object

Returns the number of months in the range or nil when range is no full month



102
103
104
105
106
 
# File 'lib/active_date_range/date_range.rb', line 102

def months
  return nil unless full_month?

  ((self.end.year - self.begin.year) * 12) + (self.end.month - self.begin.month + 1)
end

#next(periods = 1) ⇒ Object

Returns the period next to the current period. periods can be raised to return more than 1 next period.

DateRange.this_month.next # => DateRange.next_month
DateRange.this_month.next(2) # => DateRange.next_month + DateRange.next_month.next

Raises:



306
307
308
309
310
311
312
313
 
# File 'lib/active_date_range/date_range.rb', line 306

def next(periods = 1)
  raise BoundlessRangeError, "Can't calculate next for boundless range" if boundless?

  end_date = self.end + (granularity ? periods.send(granularity) : days.days)
  end_date = end_date.at_end_of_month if full_month?

  DateRange.new(self.end + 1.day, end_date)
end

#one_month? ⇒ Boolean

Returns true when the range is exactly one month long

Returns:

  • (Boolean) 


150
151
152
153
154
 
# File 'lib/active_date_range/date_range.rb', line 150

def one_month?
  (28..31).cover?(days) &&
    begin_at_beginning_of_month? &&
    self.end == self.begin.at_end_of_month
end

#one_quarter? ⇒ Boolean

Returns true when the range is exactly one quarter long

Returns:

  • (Boolean) 


157
158
159
160
161
 
# File 'lib/active_date_range/date_range.rb', line 157

def one_quarter?
  (90..92).cover?(days) &&
    begin_at_beginning_of_quarter? &&
    self.end == self.begin.at_end_of_quarter
end

#one_week? ⇒ Boolean

Returns:

  • (Boolean) 


170
171
172
173
174
 
# File 'lib/active_date_range/date_range.rb', line 170

def one_week?
  days == 7 &&
    begin_at_beginning_of_week? &&
    self.end == self.begin.at_end_of_week
end

#one_year? ⇒ Boolean

Returns true when the range is exactly one year long

Returns:

  • (Boolean) 


164
165
166
167
168
 
# File 'lib/active_date_range/date_range.rb', line 164

def one_year?
  (365..366).cover?(days) &&
    begin_at_beginning_of_year? &&
    self.end == self.begin.at_end_of_year
end

#previous(periods = 1) ⇒ Object

Returns the period previous to the current period. periods can be raised to return more than 1 previous period.

DateRange.this_month.previous # => DateRange.prev_month
DateRange.this_month.previous(2) # => DateRange.prev_month.previous + DateRange.prev_month

Raises:



285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
 
# File 'lib/active_date_range/date_range.rb', line 285

def previous(periods = 1)
  raise BoundlessRangeError, "Can't calculate previous for boundless range" if boundless?

  begin_date = if granularity
    self.begin - periods.send(granularity)
  elsif full_month?
    in_groups_of(:month).first.previous(periods * months).begin
  else
    (self.begin - (periods * days).days)
  end

  begin_date = begin_date.at_beginning_of_month if full_month?

  DateRange.new(begin_date, self.begin - 1.day)
end

#quarters ⇒ Object

Returns the number of quarters in the range or nil when range is no full quarter



109
110
111
112
113
 
# File 'lib/active_date_range/date_range.rb', line 109

def quarters
  return nil unless full_quarter?

  months / 3
end

#relative_param ⇒ Object

Returns a string representation of the date range relative to today. For example a range of 2021-01-01..2021-12-31 will return this_year when the current date is somewhere in 2021.



244
245
246
247
248
249
250
 
# File 'lib/active_date_range/date_range.rb', line 244

def relative_param
  @relative_param ||= SHORTHANDS
    .select { |key, _| key.end_with?(granularity.to_s) }
    .find { |key, range| self == range.call }
    &.first
    &.to_s
end

#same_year? ⇒ Boolean

Returns true when begin and end are in the same year

Returns:

  • (Boolean) 


205
206
207
 
# File 'lib/active_date_range/date_range.rb', line 205

def same_year?
  !boundless? && self.begin.year == self.end.year
end

#to_datetime_range ⇒ Object

Returns a Range with begin and end as DateTime instances.



272
273
274
 
# File 'lib/active_date_range/date_range.rb', line 272

def to_datetime_range
  Range.new(self.begin.to_datetime.at_beginning_of_day, self.end.to_datetime.at_end_of_day)
end

#to_param(relative: true) ⇒ Object

Returns a param representation of the date range. When relative is true, the relative_param is returned when available. This allows for easy bookmarking of URL’s that always return the current month/quarter/year for the end user.

When relative is false, a YYYYMMDD..YYYYMMDD or YYYYMM..YYYYMM format is returned. The output of to_param is compatible with the parse method.

DateRange.parse("202001..202001").to_param                  # => "202001..202001"
DateRange.parse("20200101..20200115").to_param              # => "20200101..20200115"
DateRange.parse("202001..202001").to_param(relative: true)  # => "this_month"



262
263
264
265
266
267
268
269
 
# File 'lib/active_date_range/date_range.rb', line 262

def to_param(relative: true)
  if relative && relative_param
    relative_param
  else
    format = full_month? ? "%Y%m" : "%Y%m%d"
    "#{self.begin&.strftime(format)}..#{self.end&.strftime(format)}"
  end
end

#to_s ⇒ Object 



276
277
278
 
# File 'lib/active_date_range/date_range.rb', line 276

def to_s
  "#{self.begin.strftime('%Y%m%d')}..#{self.end.strftime('%Y%m%d')}"
end

#weeks ⇒ Object

Returns the number of weeks on the range or nil when range is no full week



123
124
125
126
127
 
# File 'lib/active_date_range/date_range.rb', line 123

def weeks
  return nil unless full_week?

  days / 7
end

#years ⇒ Object

Returns the number of years on the range or nil when range is no full year



116
117
118
119
120
 
# File 'lib/active_date_range/date_range.rb', line 116

def years
  return nil unless full_year?

  months / 12
end