1
// Copyright 2008 The Closure Library Authors. All Rights Reserved.
2
//
3
// Licensed under the Apache License, Version 2.0 (the "License");
4
// you may not use this file except in compliance with the License.
5
// You may obtain a copy of the License at
6
//
7
//      http://www.apache.org/licenses/LICENSE-2.0
8
//
9
// Unless required by applicable law or agreed to in writing, software
10
// distributed under the License is distributed on an "AS-IS" BASIS,
11
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
// See the License for the specific language governing permissions and
13
// limitations under the License.
14

15
/**
16
 * @fileoverview Date range data structure. Based loosely on
17
 * com.google.common.util.DateRange.
18
 *
19
 * @author [email protected] (David P. Baker)
20
 */
21

22
goog.provide('goog.date.DateRange');
23
goog.provide('goog.date.DateRange.Iterator');
24
goog.provide('goog.date.DateRange.StandardDateRangeKeys');
25

26
goog.require('goog.date.Date');
27
goog.require('goog.date.Interval');
28
goog.require('goog.iter.Iterator');
29
goog.require('goog.iter.StopIteration');
30

31

32

33
/**
34
 * Constructs a date range.
35
 * @constructor
36
 * @struct
37
 * @param {goog.date.Date} startDate The first date in the range.
38
 * @param {goog.date.Date} endDate The last date in the range.
39
 * @final
40
 */
41
goog.date.DateRange = function(startDate, endDate) {
42
  /**
43
   * The first date in the range.
44
   * @type {goog.date.Date}
45
   * @private
46
   */
47
  this.startDate_ = startDate;
48

49
  /**
50
   * The last date in the range.
51
   * @type {goog.date.Date}
52
   * @private
53
   */
54
  this.endDate_ = endDate;
55
};
56

57

58
/**
59
 * The first possible day, as far as this class is concerned.
60
 * @type {goog.date.Date}
61
 */
62
goog.date.DateRange.MINIMUM_DATE = new goog.date.Date(0, 0, 1);
63

64

65
/**
66
 * The last possible day, as far as this class is concerned.
67
 * @type {goog.date.Date}
68
 */
69
goog.date.DateRange.MAXIMUM_DATE = new goog.date.Date(9999, 11, 31);
70

71

72
/**
73
 * @return {goog.date.Date} The first date in the range.
74
 */
75
goog.date.DateRange.prototype.getStartDate = function() {
76
  return this.startDate_;
77
};
78

79

80
/**
81
 * @return {goog.date.Date} The last date in the range.
82
 */
83
goog.date.DateRange.prototype.getEndDate = function() {
84
  return this.endDate_;
85
};
86

87

88
/**
89
 * Tests if a date falls within this range.
90
 *
91
 * @param {goog.date.Date} date The date to test.
92
 * @return {boolean} Whether the date is in the range.
93
 */
94
goog.date.DateRange.prototype.contains = function(date) {
95
  return date.valueOf() >= this.startDate_.valueOf() &&
96
      date.valueOf() <= this.endDate_.valueOf();
97
};
98

99

100
/**
101
 * @return {!goog.date.DateRange.Iterator} An iterator over the date range.
102
 */
103
goog.date.DateRange.prototype.iterator = function() {
104
  return new goog.date.DateRange.Iterator(this);
105
};
106

107

108
/**
109
 * Tests two {@link goog.date.DateRange} objects for equality.
110
 * @param {goog.date.DateRange} a A date range.
111
 * @param {goog.date.DateRange} b A date range.
112
 * @return {boolean} Whether |a| is the same range as |b|.
113
 */
114
goog.date.DateRange.equals = function(a, b) {
115
  // Test for same object reference; type conversion is irrelevant.
116
  if (a === b) {
117
    return true;
118
  }
119

120
  if (a == null || b == null) {
121
    return false;
122
  }
123

124
  return a.startDate_.equals(b.startDate_) && a.endDate_.equals(b.endDate_);
125
};
126

127

128
/**
129
 * Calculates a date that is a number of days after a date. Does not modify its
130
 * input.
131
 * @param {goog.date.Date} date The input date.
132
 * @param {number} offset Number of days.
133
 * @return {!goog.date.Date} The date that is |offset| days after |date|.
134
 * @private
135
 */
136
goog.date.DateRange.offsetInDays_ = function(date, offset) {
137
  var newDate = date.clone();
138
  newDate.add(new goog.date.Interval(goog.date.Interval.DAYS, offset));
139
  return newDate;
140
};
141

142

143
/**
144
 * Calculates a date that is a number of months after the first day in the
145
 * month that contains its input. Does not modify its input.
146
 * @param {goog.date.Date} date The input date.
147
 * @param {number} offset Number of months.
148
 * @return {!goog.date.Date} The date that is |offset| months after the first
149
 *     day in the month that contains |date|.
150
 * @private
151
 */
152
goog.date.DateRange.offsetInMonths_ = function(date, offset) {
153
  var newDate = date.clone();
154
  newDate.setDate(1);
155
  newDate.add(new goog.date.Interval(goog.date.Interval.MONTHS, offset));
156
  return newDate;
157
};
158

159

160
/**
161
 * Returns the range from yesterday to yesterday.
162
 * @param {goog.date.Date=} opt_today The date to consider today.
163
 *     Defaults to today.
164
 * @return {!goog.date.DateRange} The range that includes only yesterday.
165
 */
166
goog.date.DateRange.yesterday = function(opt_today) {
167
  var today = goog.date.DateRange.cloneOrCreate_(opt_today);
168
  var yesterday = goog.date.DateRange.offsetInDays_(today, -1);
169
  return new goog.date.DateRange(yesterday, yesterday.clone());
170
};
171

172

173
/**
174
 * Returns the range from today to today.
175
 * @param {goog.date.Date=} opt_today The date to consider today.
176
 *     Defaults to today.
177
 * @return {!goog.date.DateRange} The range that includes only today.
178
 */
179
goog.date.DateRange.today = function(opt_today) {
180
  var today = goog.date.DateRange.cloneOrCreate_(opt_today);
181
  return new goog.date.DateRange(today, today.clone());
182
};
183

184

185
/**
186
 * Returns the range that includes the seven days that end yesterday.
187
 * @param {goog.date.Date=} opt_today The date to consider today.
188
 *     Defaults to today.
189
 * @return {!goog.date.DateRange} The range that includes the seven days that
190
 *     end yesterday.
191
 */
192
goog.date.DateRange.last7Days = function(opt_today) {
193
  var today = goog.date.DateRange.cloneOrCreate_(opt_today);
194
  var yesterday = goog.date.DateRange.offsetInDays_(today, -1);
195
  return new goog.date.DateRange(
196
      goog.date.DateRange.offsetInDays_(today, -7), yesterday);
197
};
198

199

200
/**
201
 * Returns the range that starts the first of this month and ends the last day
202
 * of this month.
203
 * @param {goog.date.Date=} opt_today The date to consider today.
204
 *     Defaults to today.
205
 * @return {!goog.date.DateRange} The range that starts the first of this month
206
 *     and ends the last day of this month.
207
 */
208
goog.date.DateRange.thisMonth = function(opt_today) {
209
  var today = goog.date.DateRange.cloneOrCreate_(opt_today);
210
  return new goog.date.DateRange(
211
      goog.date.DateRange.offsetInMonths_(today, 0),
212
      goog.date.DateRange.offsetInDays_(
213
          goog.date.DateRange.offsetInMonths_(today, 1), -1));
214
};
215

216

217
/**
218
 * Returns the range that starts the first of last month and ends the last day
219
 * of last month.
220
 * @param {goog.date.Date=} opt_today The date to consider today.
221
 *     Defaults to today.
222
 * @return {!goog.date.DateRange} The range that starts the first of last month
223
 *     and ends the last day of last month.
224
 */
225
goog.date.DateRange.lastMonth = function(opt_today) {
226
  var today = goog.date.DateRange.cloneOrCreate_(opt_today);
227
  return new goog.date.DateRange(
228
      goog.date.DateRange.offsetInMonths_(today, -1),
229
      goog.date.DateRange.offsetInDays_(
230
          goog.date.DateRange.offsetInMonths_(today, 0), -1));
231
};
232

233

234
/**
235
 * Returns the seven-day range that starts on the first day of the week
236
 * (see {@link goog.i18n.DateTimeSymbols.FIRSTDAYOFWEEK}) on or before today.
237
 * @param {goog.date.Date=} opt_today The date to consider today.
238
 *     Defaults to today.
239
 * @return {!goog.date.DateRange} The range that starts the Monday on or before
240
 *     today and ends the Sunday on or after today.
241
 */
242
goog.date.DateRange.thisWeek = function(opt_today) {
243
  var today = goog.date.DateRange.cloneOrCreate_(opt_today);
244
  var iso = today.getIsoWeekday();
245
  var firstDay = today.getFirstDayOfWeek();
246
  var i18nFirstDay = (iso >= firstDay) ? iso - firstDay : iso + (7 - firstDay);
247
  var start = goog.date.DateRange.offsetInDays_(today, -i18nFirstDay);
248
  var end = goog.date.DateRange.offsetInDays_(start, 6);
249
  return new goog.date.DateRange(start, end);
250
};
251

252

253
/**
254
 * Returns the seven-day range that ends the day before the first day of
255
 * the week (see {@link goog.i18n.DateTimeSymbols.FIRSTDAYOFWEEK}) that
256
 * contains today.
257
 * @param {goog.date.Date=} opt_today The date to consider today.
258
 *     Defaults to today.
259
 * @return {!goog.date.DateRange} The range that starts seven days before the
260
 *     Monday on or before today and ends the Sunday on or before yesterday.
261
 */
262
goog.date.DateRange.lastWeek = function(opt_today) {
263
  var thisWeek = goog.date.DateRange.thisWeek(opt_today);
264
  var start = goog.date.DateRange.offsetInDays_(thisWeek.getStartDate(), -7);
265
  var end = goog.date.DateRange.offsetInDays_(thisWeek.getEndDate(), -7);
266
  return new goog.date.DateRange(start, end);
267
};
268

269

270
/**
271
 * Returns the range that starts seven days before the Monday on or before
272
 * today and ends the Friday before today.
273
 * @param {goog.date.Date=} opt_today The date to consider today.
274
 *     Defaults to today.
275
 * @return {!goog.date.DateRange} The range that starts seven days before the
276
 *     Monday on or before today and ends the Friday before today.
277
 */
278
goog.date.DateRange.lastBusinessWeek = function(opt_today) {
279
  // TODO(user): should be i18nized.
280
  var today = goog.date.DateRange.cloneOrCreate_(opt_today);
281
  var start =
282
      goog.date.DateRange.offsetInDays_(today, -7 - today.getIsoWeekday());
283
  var end = goog.date.DateRange.offsetInDays_(start, 4);
284
  return new goog.date.DateRange(start, end);
285
};
286

287

288
/**
289
 * Returns the range that includes all days between January 1, 1900 and
290
 * December 31, 9999.
291
 * @param {goog.date.Date=} opt_today The date to consider today.
292
 *     Defaults to today.
293
 * @return {!goog.date.DateRange} The range that includes all days between
294
 *     January 1, 1900 and December 31, 9999.
295
 */
296
goog.date.DateRange.allTime = function(opt_today) {
297
  return new goog.date.DateRange(
298
      goog.date.DateRange.MINIMUM_DATE, goog.date.DateRange.MAXIMUM_DATE);
299
};
300

301

302
/**
303
 * Standard date range keys. Equivalent to the enum IDs in
304
 * DateRange.java http://go/datarange.java
305
 *
306
 * @enum {string}
307
 */
308
goog.date.DateRange.StandardDateRangeKeys = {
309
  YESTERDAY: 'yesterday',
310
  TODAY: 'today',
311
  LAST_7_DAYS: 'last7days',
312
  THIS_MONTH: 'thismonth',
313
  LAST_MONTH: 'lastmonth',
314
  THIS_WEEK: 'thisweek',
315
  LAST_WEEK: 'lastweek',
316
  LAST_BUSINESS_WEEK: 'lastbusinessweek',
317
  ALL_TIME: 'alltime'
318
};
319

320

321
/**
322
 * @param {string} dateRangeKey A standard date range key.
323
 * @param {goog.date.Date=} opt_today The date to consider today.
324
 *     Defaults to today.
325
 * @return {!goog.date.DateRange} The date range that corresponds to that key.
326
 * @throws {Error} If no standard date range with that key exists.
327
 */
328
goog.date.DateRange.standardDateRange = function(dateRangeKey, opt_today) {
329
  switch (dateRangeKey) {
330
    case goog.date.DateRange.StandardDateRangeKeys.YESTERDAY:
331
      return goog.date.DateRange.yesterday(opt_today);
332

333
    case goog.date.DateRange.StandardDateRangeKeys.TODAY:
334
      return goog.date.DateRange.today(opt_today);
335

336
    case goog.date.DateRange.StandardDateRangeKeys.LAST_7_DAYS:
337
      return goog.date.DateRange.last7Days(opt_today);
338

339
    case goog.date.DateRange.StandardDateRangeKeys.THIS_MONTH:
340
      return goog.date.DateRange.thisMonth(opt_today);
341

342
    case goog.date.DateRange.StandardDateRangeKeys.LAST_MONTH:
343
      return goog.date.DateRange.lastMonth(opt_today);
344

345
    case goog.date.DateRange.StandardDateRangeKeys.THIS_WEEK:
346
      return goog.date.DateRange.thisWeek(opt_today);
347

348
    case goog.date.DateRange.StandardDateRangeKeys.LAST_WEEK:
349
      return goog.date.DateRange.lastWeek(opt_today);
350

351
    case goog.date.DateRange.StandardDateRangeKeys.LAST_BUSINESS_WEEK:
352
      return goog.date.DateRange.lastBusinessWeek(opt_today);
353

354
    case goog.date.DateRange.StandardDateRangeKeys.ALL_TIME:
355
      return goog.date.DateRange.allTime(opt_today);
356

357
    default:
358
      throw Error('no such date range key: ' + dateRangeKey);
359
  }
360
};
361

362

363
/**
364
 * Clones or creates new.
365
 * @param {goog.date.Date=} opt_today The date to consider today.
366
 *     Defaults to today.
367
 * @return {!goog.date.Date} cloned or new.
368
 * @private
369
 */
370
goog.date.DateRange.cloneOrCreate_ = function(opt_today) {
371
  return opt_today ? opt_today.clone() : new goog.date.Date();
372
};
373

374

375

376
/**
377
 * Creates an iterator over the dates in a {@link goog.date.DateRange}.
378
 * @constructor
379
 * @struct
380
 * @extends {goog.iter.Iterator<goog.date.Date>}
381
 * @param {goog.date.DateRange} dateRange The date range to iterate.
382
 * @final
383
 */
384
goog.date.DateRange.Iterator = function(dateRange) {
385
  /**
386
   * The next date.
387
   * @type {goog.date.Date}
388
   * @private
389
   */
390
  this.nextDate_ = dateRange.getStartDate().clone();
391

392
  /**
393
   * The end date, expressed as an integer: YYYYMMDD.
394
   * @type {number}
395
   * @private
396
   */
397
  this.endDate_ = Number(dateRange.getEndDate().toIsoString());
398
};
399
goog.inherits(goog.date.DateRange.Iterator, goog.iter.Iterator);
400

401

402
/** @override */
403
goog.date.DateRange.Iterator.prototype.next = function() {
404
  if (Number(this.nextDate_.toIsoString()) > this.endDate_) {
405
    throw goog.iter.StopIteration;
406
  }
407

408
  var rv = this.nextDate_.clone();
409
  this.nextDate_.add(new goog.date.Interval(goog.date.Interval.DAYS, 1));
410
  return rv;
411
};
412

413