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) 


265
266
267
268
 
# File 'lib/active_date_range/date_range.rb', line 265

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) 


258
259
260
261
 
# File 'lib/active_date_range/date_range.rb', line 258

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
133
134
 
# File 'lib/active_date_range/date_range.rb', line 130

def begin_at_beginning_of_month?
  memoize(:@begin_at_beginning_of_month) do
    self.begin.present? && self.begin.day == 1
  end
end

#begin_at_beginning_of_quarter? ⇒ Boolean

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

Returns:

  • (Boolean) 


137
138
139
140
141
 
# File 'lib/active_date_range/date_range.rb', line 137

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

#begin_at_beginning_of_week? ⇒ Boolean

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

Returns:

  • (Boolean) 


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

def begin_at_beginning_of_week?
  memoize(:@begin_at_beginning_of_week) do
    self.begin.present? && self.begin == self.begin.at_beginning_of_week
  end
end

#begin_at_beginning_of_year? ⇒ Boolean

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

Returns:

  • (Boolean) 


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

def begin_at_beginning_of_year?
  memoize(:@begin_at_beginning_of_year) do
    self.begin.present? && begin_at_beginning_of_month? && self.begin.month == 1
  end
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) 


193
194
195
196
197
 
# File 'lib/active_date_range/date_range.rb', line 193

def full_month?
  memoize(:@full_month) do
    begin_at_beginning_of_month? && self.end.present? && self.end == self.end.at_end_of_month
  end
end

#full_quarter? ⇒ Boolean Also known as: full_quarters?

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

Returns:

  • (Boolean) 


202
203
204
205
206
 
# File 'lib/active_date_range/date_range.rb', line 202

def full_quarter?
  memoize(:@full_quarter) do
    begin_at_beginning_of_quarter? && self.end.present? && self.end == self.end.at_end_of_quarter
  end
end

#full_week? ⇒ Boolean Also known as: full_weeks?

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

Returns:

  • (Boolean) 


220
221
222
223
224
 
# File 'lib/active_date_range/date_range.rb', line 220

def full_week?
  memoize(:@full_week) do
    begin_at_beginning_of_week? && self.end.present? && self.end == self.end.at_end_of_week
  end
end

#full_year? ⇒ Boolean Also known as: full_years?

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

Returns:

  • (Boolean) 


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

def full_year?
  memoize(:@full_year) do
    begin_at_beginning_of_year? && self.end.present? && self.end == self.end.at_end_of_year
  end
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



276
277
278
279
280
281
282
283
284
285
286
287
288
 
# File 'lib/active_date_range/date_range.rb', line 276

def granularity
  memoize(:@granularity) do
    if one_year?
      :year
    elsif one_quarter?
      :quarter
    elsif one_month?
      :month
    elsif one_week?
      :week
    end
  end
end

#humanize(format: :short) ⇒ Object

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



393
394
395
 
# File 'lib/active_date_range/date_range.rb', line 393

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:



382
383
384
385
386
387
388
389
390
 
# File 'lib/active_date_range/date_range.rb', line 382

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) 


403
404
405
 
# File 'lib/active_date_range/date_range.rb', line 403

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

#intersection(other) ⇒ Object

Returns the intersection of the current and the other date range



398
399
400
401
 
# File 'lib/active_date_range/date_range.rb', line 398

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:



357
358
359
360
361
362
363
364
365
366
367
368
369
370
 
# File 'lib/active_date_range/date_range.rb', line 357

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

  end_date = if granularity
    self.end + periods.send(granularity)
  elsif full_month?
    in_groups_of(:month).last.next(periods * months).end
  else
    self.end + (periods * days).days
  end
  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) 


158
159
160
161
162
163
164
 
# File 'lib/active_date_range/date_range.rb', line 158

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

#one_quarter? ⇒ Boolean

Returns true when the range is exactly one quarter long

Returns:

  • (Boolean) 


167
168
169
170
171
172
173
 
# File 'lib/active_date_range/date_range.rb', line 167

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

#one_week? ⇒ Boolean

Returns:

  • (Boolean) 


184
185
186
187
188
189
190
 
# File 'lib/active_date_range/date_range.rb', line 184

def one_week?
  memoize(:@one_week) do
    days == 7 &&
      begin_at_beginning_of_week? &&
      self.end == self.begin.at_end_of_week
  end
end

#one_year? ⇒ Boolean

Returns true when the range is exactly one year long

Returns:

  • (Boolean) 


176
177
178
179
180
181
182
 
# File 'lib/active_date_range/date_range.rb', line 176

def one_year?
  memoize(:@one_year) do
    (365..366).cover?(days) &&
      begin_at_beginning_of_year? &&
      self.end == self.begin.at_end_of_year
  end
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:



336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
 
# File 'lib/active_date_range/date_range.rb', line 336

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.



293
294
295
296
297
298
299
300
301
 
# File 'lib/active_date_range/date_range.rb', line 293

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

#same_year? ⇒ Boolean

Returns true when begin and end are in the same year

Returns:

  • (Boolean) 


229
230
231
232
233
 
# File 'lib/active_date_range/date_range.rb', line 229

def same_year?
  memoize(:@same_year) do
    !boundless? && self.begin.year == self.end.year
  end
end

#this_month? ⇒ Boolean

Return true when the range is equal to the current month

Returns:

  • (Boolean) 


236
237
238
239
240
 
# File 'lib/active_date_range/date_range.rb', line 236

def this_month?
  memoize(:@this_month) do
    self == DateRange.this_month
  end
end

#this_quarter? ⇒ Boolean

Return true when the range is equal to the current quarter

Returns:

  • (Boolean) 


243
244
245
246
247
 
# File 'lib/active_date_range/date_range.rb', line 243

def this_quarter?
  memoize(:@this_quarter) do
    self == DateRange.this_quarter
  end
end

#this_year? ⇒ Boolean

Return true when the range is equal to the current year

Returns:

  • (Boolean) 


250
251
252
253
254
 
# File 'lib/active_date_range/date_range.rb', line 250

def this_year?
  memoize(:@this_year) do
    self == DateRange.this_year
  end
end

#to_datetime_range ⇒ Object

Returns a Range with begin and end as DateTime instances.



323
324
325
 
# File 'lib/active_date_range/date_range.rb', line 323

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"



313
314
315
316
317
318
319
320
 
# File 'lib/active_date_range/date_range.rb', line 313

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 



327
328
329
 
# File 'lib/active_date_range/date_range.rb', line 327

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