Debian Codegraph @

closure-library/closure/goog/date/daterange.js

raw
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 new 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 };