1
// Copyright 2006 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 Functions and objects for date representation and manipulation.
17
 *
18
 * @author [email protected] (Emil A Eklund)
19
 */
20

21
goog.provide('goog.date');
22
goog.provide('goog.date.Date');
23
goog.provide('goog.date.DateTime');
24
goog.provide('goog.date.Interval');
25
goog.provide('goog.date.month');
26
goog.provide('goog.date.weekDay');
27

28
goog.require('goog.asserts');
29
/** @suppress {extraRequire} */
30
goog.require('goog.date.DateLike');
31
goog.require('goog.i18n.DateTimeSymbols');
32
goog.require('goog.string');
33

34

35
/**
36
 * Constants for weekdays.
37
 * @enum {number}
38
 */
39
goog.date.weekDay = {
40
  MON: 0,
41
  TUE: 1,
42
  WED: 2,
43
  THU: 3,
44
  FRI: 4,
45
  SAT: 5,
46
  SUN: 6
47
};
48

49

50
/**
51
 * Constants for months.
52
 * @enum {number}
53
 */
54
goog.date.month = {
55
  JAN: 0,
56
  FEB: 1,
57
  MAR: 2,
58
  APR: 3,
59
  MAY: 4,
60
  JUN: 5,
61
  JUL: 6,
62
  AUG: 7,
63
  SEP: 8,
64
  OCT: 9,
65
  NOV: 10,
66
  DEC: 11
67
};
68

69

70
/**
71
 * Formats a month/year string.
72
 * Example: "January 2008"
73
 *
74
 * @param {string} monthName The month name to use in the result.
75
 * @param {number} yearNum The numeric year to use in the result.
76
 * @return {string} A formatted month/year string.
77
 */
78
goog.date.formatMonthAndYear = function(monthName, yearNum) {
79
  /** @desc Month/year format given the month name and the numeric year. */
80
  var MSG_MONTH_AND_YEAR = goog.getMsg(
81
      '{$monthName} {$yearNum}',
82
      {'monthName': monthName, 'yearNum': String(yearNum)});
83
  return MSG_MONTH_AND_YEAR;
84
};
85

86

87
/**
88
 * Regular expression for splitting date parts from ISO 8601 styled string.
89
 * Examples: '20060210' or '2005-02-22' or '20050222' or '2005-08'
90
 * or '2005-W22' or '2005W22' or '2005-W22-4', etc.
91
 * For explanation and more examples, see:
92
 * {@link http://en.wikipedia.org/wiki/ISO_8601}
93
 *
94
 * @type {RegExp}
95
 * @private
96
 */
97
goog.date.splitDateStringRegex_ = new RegExp(
98
    '^(\\d{4})(?:(?:-?(\\d{2})(?:-?(\\d{2}))?)|' +
99
    '(?:-?(\\d{3}))|(?:-?W(\\d{2})(?:-?([1-7]))?))?$');
100

101

102
/**
103
 * Regular expression for splitting time parts from ISO 8601 styled string.
104
 * Examples: '18:46:39.994' or '184639.994'
105
 *
106
 * @type {RegExp}
107
 * @private
108
 */
109
goog.date.splitTimeStringRegex_ =
110
    /^(\d{2})(?::?(\d{2})(?::?(\d{2})(\.\d+)?)?)?$/;
111

112

113
/**
114
 * Regular expression for splitting timezone parts from ISO 8601 styled string.
115
 * Example: The part after the '+' in '18:46:39+07:00'.  Or '09:30Z' (UTC).
116
 *
117
 * @type {RegExp}
118
 * @private
119
 */
120
goog.date.splitTimezoneStringRegex_ = /Z|(?:([-+])(\d{2})(?::?(\d{2}))?)$/;
121

122

123
/**
124
 * Regular expression for splitting duration parts from ISO 8601 styled string.
125
 * Example: '-P1Y2M3DT4H5M6.7S'
126
 *
127
 * @type {RegExp}
128
 * @private
129
 */
130
goog.date.splitDurationRegex_ = new RegExp(
131
    '^(-)?P(?:(\\d+)Y)?(?:(\\d+)M)?(?:(\\d+)D)?' +
132
    '(T(?:(\\d+)H)?(?:(\\d+)M)?(?:(\\d+(?:\\.\\d+)?)S)?)?$');
133

134

135
/**
136
 * Number of milliseconds in a day.
137
 * @type {number}
138
 */
139
goog.date.MS_PER_DAY = 24 * 60 * 60 * 1000;
140

141

142
/**
143
 * Returns whether the given year is a leap year.
144
 *
145
 * @param {number} year Year part of date.
146
 * @return {boolean} Whether the given year is a leap year.
147
 */
148
goog.date.isLeapYear = function(year) {
149
  // Leap year logic; the 4-100-400 rule
150
  return year % 4 == 0 && (year % 100 != 0 || year % 400 == 0);
151
};
152

153

154
/**
155
 * Returns whether the given year is a long ISO year.
156
 * See {@link http://www.phys.uu.nl/~vgent/calendar/isocalendar_text3.htm}.
157
 *
158
 * @param {number} year Full year part of date.
159
 * @return {boolean} Whether the given year is a long ISO year.
160
 */
161
goog.date.isLongIsoYear = function(year) {
162
  var n = 5 * year + 12 - 4 * (Math.floor(year / 100) - Math.floor(year / 400));
163
  n += Math.floor((year - 100) / 400) - Math.floor((year - 102) / 400);
164
  n += Math.floor((year - 200) / 400) - Math.floor((year - 199) / 400);
165

166
  return n % 28 < 5;
167
};
168

169

170
/**
171
 * Returns the number of days for a given month.
172
 *
173
 * @param {number} year Year part of date.
174
 * @param {number} month Month part of date.
175
 * @return {number} The number of days for the given month.
176
 */
177
goog.date.getNumberOfDaysInMonth = function(year, month) {
178
  switch (month) {
179
    case goog.date.month.FEB:
180
      return goog.date.isLeapYear(year) ? 29 : 28;
181
    case goog.date.month.JUN:
182
    case goog.date.month.SEP:
183
    case goog.date.month.NOV:
184
    case goog.date.month.APR:
185
      return 30;
186
  }
187
  return 31;
188
};
189

190

191
/**
192
 * Returns true if the 2 dates are in the same day.
193
 * @param {goog.date.DateLike} date The time to check.
194
 * @param {goog.date.DateLike=} opt_now The current time.
195
 * @return {boolean} Whether the dates are on the same day.
196
 */
197
goog.date.isSameDay = function(date, opt_now) {
198
  var now = opt_now || new Date(goog.now());
199
  return date.getDate() == now.getDate() && goog.date.isSameMonth(date, now);
200
};
201

202

203
/**
204
 * Returns true if the 2 dates are in the same month.
205
 * @param {goog.date.DateLike} date The time to check.
206
 * @param {goog.date.DateLike=} opt_now The current time.
207
 * @return {boolean} Whether the dates are in the same calendar month.
208
 */
209
goog.date.isSameMonth = function(date, opt_now) {
210
  var now = opt_now || new Date(goog.now());
211
  return date.getMonth() == now.getMonth() && goog.date.isSameYear(date, now);
212
};
213

214

215
/**
216
 * Returns true if the 2 dates are in the same year.
217
 * @param {goog.date.DateLike} date The time to check.
218
 * @param {goog.date.DateLike=} opt_now The current time.
219
 * @return {boolean} Whether the dates are in the same calendar year.
220
 */
221
goog.date.isSameYear = function(date, opt_now) {
222
  var now = opt_now || new Date(goog.now());
223
  return date.getFullYear() == now.getFullYear();
224
};
225

226

227
/**
228
 * Static function for week number calculation. ISO 8601 implementation.
229
 *
230
 * @param {number} year Year part of date.
231
 * @param {number} month Month part of date (0-11).
232
 * @param {number} date Day part of date (1-31).
233
 * @param {number=} opt_weekDay Cut off weekday, defaults to Thursday.
234
 * @param {number=} opt_firstDayOfWeek First day of the week, defaults to
235
 *     Monday.
236
 *     Monday=0, Sunday=6.
237
 * @return {number} The week number (1-53).
238
 */
239
goog.date.getWeekNumber = function(
240
    year, month, date, opt_weekDay, opt_firstDayOfWeek) {
241
  var d = new Date(year, month, date);
242

243
  // Default to Thursday for cut off as per ISO 8601.
244
  var cutoff = goog.isDef(opt_weekDay) ? opt_weekDay : goog.date.weekDay.THU;
245

246
  // Default to Monday for first day of the week as per ISO 8601.
247
  var firstday = opt_firstDayOfWeek || goog.date.weekDay.MON;
248

249
  // The d.getDay() has to be converted first to ISO weekday (Monday=0).
250
  var isoday = (d.getDay() + 6) % 7;
251

252
  // Position of given day in the picker grid w.r.t. first day of week
253
  var daypos = (isoday - firstday + 7) % 7;
254

255
  // Position of cut off day in the picker grid w.r.t. first day of week
256
  var cutoffpos = (cutoff - firstday + 7) % 7;
257

258
  // Unix timestamp of the midnight of the cutoff day in the week of 'd'.
259
  // There might be +-1 hour shift in the result due to the daylight saving,
260
  // but it doesn't affect the year.
261
  var cutoffSameWeek =
262
      d.valueOf() + (cutoffpos - daypos) * goog.date.MS_PER_DAY;
263

264
  // Unix timestamp of January 1 in the year of 'cutoffSameWeek'.
265
  var jan1 = new Date(new Date(cutoffSameWeek).getFullYear(), 0, 1).valueOf();
266

267
  // Number of week. The round() eliminates the effect of daylight saving.
268
  return Math.floor(
269
             Math.round((cutoffSameWeek - jan1) / goog.date.MS_PER_DAY) / 7) +
270
      1;
271
};
272

273

274
/**
275
 * @param {T} date1 A datelike object.
276
 * @param {S} date2 Another datelike object.
277
 * @return {T|S} The earlier of them in time.
278
 * @template T,S
279
 */
280
goog.date.min = function(date1, date2) {
281
  return date1 < date2 ? date1 : date2;
282
};
283

284

285
/**
286
 * @param {T} date1 A datelike object.
287
 * @param {S} date2 Another datelike object.
288
 * @return {T|S} The later of them in time.
289
 * @template T,S
290
 */
291
goog.date.max = function(date1, date2) {
292
  return date1 > date2 ? date1 : date2;
293
};
294

295

296
/**
297
 * Creates a DateTime from a datetime string expressed in ISO 8601 format.
298
 *
299
 * @param {string} formatted A date or datetime expressed in ISO 8601 format.
300
 * @return {goog.date.DateTime} Parsed date or null if parse fails.
301
 */
302
goog.date.fromIsoString = function(formatted) {
303
  var ret = new goog.date.DateTime(2000);
304
  return goog.date.setIso8601DateTime(ret, formatted) ? ret : null;
305
};
306

307

308
/**
309
 * Parses a datetime string expressed in ISO 8601 format. Overwrites the date
310
 * and optionally the time part of the given object with the parsed values.
311
 *
312
 * @param {!goog.date.DateTime} dateTime Object whose fields will be set.
313
 * @param {string} formatted A date or datetime expressed in ISO 8601 format.
314
 * @return {boolean} Whether the parsing succeeded.
315
 */
316
goog.date.setIso8601DateTime = function(dateTime, formatted) {
317
  formatted = goog.string.trim(formatted);
318
  var delim = formatted.indexOf('T') == -1 ? ' ' : 'T';
319
  var parts = formatted.split(delim);
320
  return goog.date.setIso8601DateOnly_(dateTime, parts[0]) &&
321
      (parts.length < 2 || goog.date.setIso8601TimeOnly_(dateTime, parts[1]));
322
};
323

324

325
/**
326
 * Sets date fields based on an ISO 8601 format string.
327
 *
328
 * @param {!goog.date.DateTime} d Object whose fields will be set.
329
 * @param {string} formatted A date expressed in ISO 8601 format.
330
 * @return {boolean} Whether the parsing succeeded.
331
 * @private
332
 */
333
goog.date.setIso8601DateOnly_ = function(d, formatted) {
334
  // split the formatted ISO date string into its date fields
335
  var parts = formatted.match(goog.date.splitDateStringRegex_);
336
  if (!parts) {
337
    return false;
338
  }
339

340
  var year = Number(parts[1]);
341
  var month = Number(parts[2]);
342
  var date = Number(parts[3]);
343
  var dayOfYear = Number(parts[4]);
344
  var week = Number(parts[5]);
345
  // ISO weekdays start with 1, native getDay() values start with 0
346
  var dayOfWeek = Number(parts[6]) || 1;
347

348
  d.setFullYear(year);
349

350
  if (dayOfYear) {
351
    d.setDate(1);
352
    d.setMonth(0);
353
    var offset = dayOfYear - 1;  // offset, so 1-indexed, i.e., skip day 1
354
    d.add(new goog.date.Interval(goog.date.Interval.DAYS, offset));
355
  } else if (week) {
356
    goog.date.setDateFromIso8601Week_(d, week, dayOfWeek);
357
  } else {
358
    if (month) {
359
      d.setDate(1);
360
      d.setMonth(month - 1);
361
    }
362
    if (date) {
363
      d.setDate(date);
364
    }
365
  }
366

367
  return true;
368
};
369

370

371
/**
372
 * Sets date fields based on an ISO 8601 week string.
373
 * See {@link http://en.wikipedia.org/wiki/ISO_week_date}, "Relation with the
374
 * Gregorian Calendar".  The first week of a new ISO year is the week with the
375
 * majority of its days in the new Gregorian year.  I.e., ISO Week 1's Thursday
376
 * is in that year.  ISO weeks always start on Monday. So ISO Week 1 can
377
 * contain a few days from the previous Gregorian year.  And ISO weeks always
378
 * end on Sunday, so the last ISO week (Week 52 or 53) can have a few days from
379
 * the following Gregorian year.
380
 * Example: '1997-W01' lasts from 1996-12-30 to 1997-01-05.  January 1, 1997 is
381
 * a Wednesday. So W01's Monday is Dec.30, 1996, and Sunday is January 5, 1997.
382
 *
383
 * @param {goog.date.DateTime} d Object whose fields will be set.
384
 * @param {number} week ISO week number.
385
 * @param {number} dayOfWeek ISO day of week.
386
 * @private
387
 */
388
goog.date.setDateFromIso8601Week_ = function(d, week, dayOfWeek) {
389
  // calculate offset for first week
390
  d.setMonth(0);
391
  d.setDate(1);
392
  var jsDay = d.getDay();
393
  // switch Sunday (0) to index 7; ISO days are 1-indexed
394
  var jan1WeekDay = jsDay || 7;
395

396
  var THURSDAY = 4;
397
  if (jan1WeekDay <= THURSDAY) {
398
    // was extended back to Monday
399
    var startDelta = 1 - jan1WeekDay;  // e.g., Thu(4) ==> -3
400
  } else {
401
    // was extended forward to Monday
402
    startDelta = 8 - jan1WeekDay;  // e.g., Fri(5) ==> +3
403
  }
404

405
  // find the absolute number of days to offset from the start of year
406
  // to arrive close to the Gregorian equivalent (pending adjustments above)
407
  // Note: decrement week multiplier by one because 1st week is
408
  // represented by dayOfWeek value
409
  var absoluteDays = Number(dayOfWeek) + (7 * (Number(week) - 1));
410

411
  // convert from ISO weekday format to Gregorian calendar date
412
  // note: subtract 1 because 1-indexed; offset should not include 1st of month
413
  var delta = startDelta + absoluteDays - 1;
414
  var interval = new goog.date.Interval(goog.date.Interval.DAYS, delta);
415
  d.add(interval);
416
};
417

418

419
/**
420
 * Sets time fields based on an ISO 8601 format string.
421
 * Note: only time fields, not date fields.
422
 *
423
 * @param {!goog.date.DateTime} d Object whose fields will be set.
424
 * @param {string} formatted A time expressed in ISO 8601 format.
425
 * @return {boolean} Whether the parsing succeeded.
426
 * @private
427
 */
428
goog.date.setIso8601TimeOnly_ = function(d, formatted) {
429
  // first strip timezone info from the end
430
  var parts = formatted.match(goog.date.splitTimezoneStringRegex_);
431

432
  var offset = 0;  // local time if no timezone info
433
  if (parts) {
434
    if (parts[0] != 'Z') {
435
      offset = Number(parts[2]) * 60 + Number(parts[3]);
436
      offset *= parts[1] == '-' ? 1 : -1;
437
    }
438
    offset -= d.getTimezoneOffset();
439
    formatted = formatted.substr(0, formatted.length - parts[0].length);
440
  }
441

442
  // then work out the time
443
  parts = formatted.match(goog.date.splitTimeStringRegex_);
444
  if (!parts) {
445
    return false;
446
  }
447

448
  d.setHours(Number(parts[1]));
449
  d.setMinutes(Number(parts[2]) || 0);
450
  d.setSeconds(Number(parts[3]) || 0);
451
  d.setMilliseconds(parts[4] ? Number(parts[4]) * 1000 : 0);
452

453
  if (offset != 0) {
454
    // adjust the date and time according to the specified timezone
455
    d.setTime(d.getTime() + offset * 60000);
456
  }
457

458
  return true;
459
};
460

461

462

463
/**
464
 * Class representing a date/time interval. Used for date calculations.
465
 * <pre>
466
 * new goog.date.Interval(0, 1) // One month
467
 * new goog.date.Interval(0, 0, 3, 1) // Three days and one hour
468
 * new goog.date.Interval(goog.date.Interval.DAYS, 1) // One day
469
 * </pre>
470
 *
471
 * @param {number|string=} opt_years Years or string representing date part.
472
 * @param {number=} opt_months Months or number of whatever date part specified
473
 *     by first parameter.
474
 * @param {number=} opt_days Days.
475
 * @param {number=} opt_hours Hours.
476
 * @param {number=} opt_minutes Minutes.
477
 * @param {number=} opt_seconds Seconds.
478
 * @constructor
479
 * @struct
480
 * @final
481
 */
482
goog.date.Interval = function(
483
    opt_years, opt_months, opt_days, opt_hours, opt_minutes, opt_seconds) {
484
  if (goog.isString(opt_years)) {
485
    var type = opt_years;
486
    var interval = /** @type {number} */ (opt_months);
487
    this.years = type == goog.date.Interval.YEARS ? interval : 0;
488
    this.months = type == goog.date.Interval.MONTHS ? interval : 0;
489
    this.days = type == goog.date.Interval.DAYS ? interval : 0;
490
    this.hours = type == goog.date.Interval.HOURS ? interval : 0;
491
    this.minutes = type == goog.date.Interval.MINUTES ? interval : 0;
492
    this.seconds = type == goog.date.Interval.SECONDS ? interval : 0;
493
  } else {
494
    this.years = /** @type {number} */ (opt_years) || 0;
495
    this.months = opt_months || 0;
496
    this.days = opt_days || 0;
497
    this.hours = opt_hours || 0;
498
    this.minutes = opt_minutes || 0;
499
    this.seconds = opt_seconds || 0;
500
  }
501
};
502

503

504
/**
505
 * Parses an XML Schema duration (ISO 8601 extended).
506
 * @see http://www.w3.org/TR/xmlschema-2/#duration
507
 *
508
 * @param  {string} duration An XML schema duration in textual format.
509
 *     Recurring durations and weeks are not supported.
510
 * @return {goog.date.Interval} The duration as a goog.date.Interval or null
511
 *     if the parse fails.
512
 */
513
goog.date.Interval.fromIsoString = function(duration) {
514
  var parts = duration.match(goog.date.splitDurationRegex_);
515
  if (!parts) {
516
    return null;
517
  }
518

519
  var timeEmpty = !(parts[6] || parts[7] || parts[8]);
520
  var dateTimeEmpty = timeEmpty && !(parts[2] || parts[3] || parts[4]);
521
  if (dateTimeEmpty || timeEmpty && parts[5]) {
522
    return null;
523
  }
524

525
  var negative = parts[1];
526
  var years = parseInt(parts[2], 10) || 0;
527
  var months = parseInt(parts[3], 10) || 0;
528
  var days = parseInt(parts[4], 10) || 0;
529
  var hours = parseInt(parts[6], 10) || 0;
530
  var minutes = parseInt(parts[7], 10) || 0;
531
  var seconds = parseFloat(parts[8]) || 0;
532
  return negative ?
533
      new goog.date.Interval(
534
          -years, -months, -days, -hours, -minutes, -seconds) :
535
      new goog.date.Interval(years, months, days, hours, minutes, seconds);
536
};
537

538

539
/**
540
 * Serializes goog.date.Interval into XML Schema duration (ISO 8601 extended).
541
 * @see http://www.w3.org/TR/xmlschema-2/#duration
542
 *
543
 * @param {boolean=} opt_verbose Include zero fields in the duration string.
544
 * @return {?string} An XML schema duration in ISO 8601 extended format,
545
 *     or null if the interval contains both positive and negative fields.
546
 */
547
goog.date.Interval.prototype.toIsoString = function(opt_verbose) {
548
  var minField = Math.min(
549
      this.years, this.months, this.days, this.hours, this.minutes,
550
      this.seconds);
551
  var maxField = Math.max(
552
      this.years, this.months, this.days, this.hours, this.minutes,
553
      this.seconds);
554
  if (minField < 0 && maxField > 0) {
555
    return null;
556
  }
557

558
  // Return 0 seconds if all fields are zero.
559
  if (!opt_verbose && minField == 0 && maxField == 0) {
560
    return 'PT0S';
561
  }
562

563
  var res = [];
564

565
  // Add sign and 'P' prefix.
566
  if (minField < 0) {
567
    res.push('-');
568
  }
569
  res.push('P');
570

571
  // Add date.
572
  if (this.years || opt_verbose) {
573
    res.push(Math.abs(this.years) + 'Y');
574
  }
575
  if (this.months || opt_verbose) {
576
    res.push(Math.abs(this.months) + 'M');
577
  }
578
  if (this.days || opt_verbose) {
579
    res.push(Math.abs(this.days) + 'D');
580
  }
581

582
  // Add time.
583
  if (this.hours || this.minutes || this.seconds || opt_verbose) {
584
    res.push('T');
585
    if (this.hours || opt_verbose) {
586
      res.push(Math.abs(this.hours) + 'H');
587
    }
588
    if (this.minutes || opt_verbose) {
589
      res.push(Math.abs(this.minutes) + 'M');
590
    }
591
    if (this.seconds || opt_verbose) {
592
      res.push(Math.abs(this.seconds) + 'S');
593
    }
594
  }
595

596
  return res.join('');
597
};
598

599

600
/**
601
 * Tests whether the given interval is equal to this interval.
602
 * Note, this is a simple field-by-field comparison, it doesn't
603
 * account for comparisons like "12 months == 1 year".
604
 *
605
 * @param {goog.date.Interval} other The interval to test.
606
 * @return {boolean} Whether the intervals are equal.
607
 */
608
goog.date.Interval.prototype.equals = function(other) {
609
  return other.years == this.years && other.months == this.months &&
610
      other.days == this.days && other.hours == this.hours &&
611
      other.minutes == this.minutes && other.seconds == this.seconds;
612
};
613

614

615
/**
616
 * @return {!goog.date.Interval} A clone of the interval object.
617
 */
618
goog.date.Interval.prototype.clone = function() {
619
  return new goog.date.Interval(
620
      this.years, this.months, this.days, this.hours, this.minutes,
621
      this.seconds);
622
};
623

624

625
/**
626
 * Years constant for the date parts.
627
 * @type {string}
628
 */
629
goog.date.Interval.YEARS = 'y';
630

631

632
/**
633
 * Months constant for the date parts.
634
 * @type {string}
635
 */
636
goog.date.Interval.MONTHS = 'm';
637

638

639
/**
640
 * Days constant for the date parts.
641
 * @type {string}
642
 */
643
goog.date.Interval.DAYS = 'd';
644

645

646
/**
647
 * Hours constant for the date parts.
648
 * @type {string}
649
 */
650
goog.date.Interval.HOURS = 'h';
651

652

653
/**
654
 * Minutes constant for the date parts.
655
 * @type {string}
656
 */
657
goog.date.Interval.MINUTES = 'n';
658

659

660
/**
661
 * Seconds constant for the date parts.
662
 * @type {string}
663
 */
664
goog.date.Interval.SECONDS = 's';
665

666

667
/**
668
 * @return {boolean} Whether all fields of the interval are zero.
669
 */
670
goog.date.Interval.prototype.isZero = function() {
671
  return this.years == 0 && this.months == 0 && this.days == 0 &&
672
      this.hours == 0 && this.minutes == 0 && this.seconds == 0;
673
};
674

675

676
/**
677
 * @return {!goog.date.Interval} Negative of this interval.
678
 */
679
goog.date.Interval.prototype.getInverse = function() {
680
  return this.times(-1);
681
};
682

683

684
/**
685
 * Calculates n * (this interval) by memberwise multiplication.
686
 * @param {number} n An integer.
687
 * @return {!goog.date.Interval} n * this.
688
 */
689
goog.date.Interval.prototype.times = function(n) {
690
  return new goog.date.Interval(
691
      this.years * n, this.months * n, this.days * n, this.hours * n,
692
      this.minutes * n, this.seconds * n);
693
};
694

695

696
/**
697
 * Gets the total number of seconds in the time interval. Assumes that months
698
 * and years are empty.
699
 * @return {number} Total number of seconds in the interval.
700
 */
701
goog.date.Interval.prototype.getTotalSeconds = function() {
702
  goog.asserts.assert(this.years == 0 && this.months == 0);
703
  return ((this.days * 24 + this.hours) * 60 + this.minutes) * 60 +
704
      this.seconds;
705
};
706

707

708
/**
709
 * Adds the Interval in the argument to this Interval field by field.
710
 *
711
 * @param {goog.date.Interval} interval The Interval to add.
712
 */
713
goog.date.Interval.prototype.add = function(interval) {
714
  this.years += interval.years;
715
  this.months += interval.months;
716
  this.days += interval.days;
717
  this.hours += interval.hours;
718
  this.minutes += interval.minutes;
719
  this.seconds += interval.seconds;
720
};
721

722

723

724
/**
725
 * Class representing a date. Defaults to current date if none is specified.
726
 *
727
 * Implements most methods of the native js Date object (except the time related
728
 * ones, {@see goog.date.DateTime}) and can be used interchangeably with it just
729
 * as if goog.date.Date was a synonym of Date. To make this more transparent,
730
 * Closure APIs should accept goog.date.DateLike instead of the real Date
731
 * object.
732
 *
733
 * @param {number|goog.date.DateLike=} opt_year Four digit year or a date-like
734
 *     object. If not set, the created object will contain the date
735
 *     determined by goog.now().
736
 * @param {number=} opt_month Month, 0 = Jan, 11 = Dec.
737
 * @param {number=} opt_date Date of month, 1 - 31.
738
 * @constructor
739
 * @struct
740
 * @see goog.date.DateTime
741
 */
742
goog.date.Date = function(opt_year, opt_month, opt_date) {
743
  /** @protected {!Date} The wrapped date or datetime. */
744
  this.date;
745
  // goog.date.DateTime assumes that only this.date is added in this ctor.
746
  if (goog.isNumber(opt_year)) {
747
    this.date = this.buildDate_(opt_year, opt_month || 0, opt_date || 1);
748
    this.maybeFixDst_(opt_date || 1);
749
  } else if (goog.isObject(opt_year)) {
750
    this.date = this.buildDate_(
751
        opt_year.getFullYear(), opt_year.getMonth(), opt_year.getDate());
752
    this.maybeFixDst_(opt_year.getDate());
753
  } else {
754
    this.date = new Date(goog.now());
755
    var expectedDate = this.date.getDate();
756
    this.date.setHours(0);
757
    this.date.setMinutes(0);
758
    this.date.setSeconds(0);
759
    this.date.setMilliseconds(0);
760
    // In some time zones there is no "0" hour on certain days during DST.
761
    // Adjust here, if necessary. See:
762
    // https://github.com/google/closure-library/issues/34.
763
    this.maybeFixDst_(expectedDate);
764
  }
765
};
766

767

768
/**
769
 * new Date(y, m, d) treats years in the interval [0, 100) as two digit years,
770
 * adding 1900 to them. This method ensures that calling the date constructor
771
 * as a copy constructor returns a value that is equal to the passed in
772
 * date value by explicitly setting the full year.
773
 * @private
774
 * @param {number} fullYear The full year (including century).
775
 * @param {number} month The month, from 0-11.
776
 * @param {number} date The day of the month.
777
 * @return {!Date} The constructed Date object.
778
 */
779
goog.date.Date.prototype.buildDate_ = function(fullYear, month, date) {
780
  var d = new Date(fullYear, month, date);
781
  if (fullYear >= 0 && fullYear < 100) {
782
    // Can't just setFullYear as new Date() can flip over for e.g. month = 13.
783
    d.setFullYear(d.getFullYear() - 1900);
784
  }
785
  return d;
786
};
787

788

789
/**
790
 * First day of week. 0 = Mon, 6 = Sun.
791
 * @type {number}
792
 * @private
793
 */
794
goog.date.Date.prototype.firstDayOfWeek_ =
795
    goog.i18n.DateTimeSymbols.FIRSTDAYOFWEEK;
796

797

798
/**
799
 * The cut off weekday used for week number calculations. 0 = Mon, 6 = Sun.
800
 * @type {number}
801
 * @private
802
 */
803
goog.date.Date.prototype.firstWeekCutOffDay_ =
804
    goog.i18n.DateTimeSymbols.FIRSTWEEKCUTOFFDAY;
805

806

807
/**
808
 * @return {!goog.date.Date} A clone of the date object.
809
 */
810
goog.date.Date.prototype.clone = function() {
811
  var date = new goog.date.Date(this.date);
812
  date.firstDayOfWeek_ = this.firstDayOfWeek_;
813
  date.firstWeekCutOffDay_ = this.firstWeekCutOffDay_;
814

815
  return date;
816
};
817

818

819
/**
820
 * @return {number} The four digit year of date.
821
 */
822
goog.date.Date.prototype.getFullYear = function() {
823
  return this.date.getFullYear();
824
};
825

826

827
/**
828
 * Alias for getFullYear.
829
 *
830
 * @return {number} The four digit year of date.
831
 * @see #getFullYear
832
 */
833
goog.date.Date.prototype.getYear = function() {
834
  return this.getFullYear();
835
};
836

837

838
/**
839
 * @return {goog.date.month} The month of date, 0 = Jan, 11 = Dec.
840
 */
841
goog.date.Date.prototype.getMonth = function() {
842
  return /** @type {goog.date.month} */ (this.date.getMonth());
843
};
844

845

846
/**
847
 * @return {number} The date of month.
848
 */
849
goog.date.Date.prototype.getDate = function() {
850
  return this.date.getDate();
851
};
852

853

854
/**
855
 * Returns the number of milliseconds since 1 January 1970 00:00:00.
856
 *
857
 * @return {number} The number of milliseconds since 1 January 1970 00:00:00.
858
 */
859
goog.date.Date.prototype.getTime = function() {
860
  return this.date.getTime();
861
};
862

863

864
/**
865
 * @return {number} The day of week, US style. 0 = Sun, 6 = Sat.
866
 */
867
goog.date.Date.prototype.getDay = function() {
868
  return this.date.getDay();
869
};
870

871

872
/**
873
 * @return {goog.date.weekDay} The day of week, ISO style. 0 = Mon, 6 = Sun.
874
 */
875
goog.date.Date.prototype.getIsoWeekday = function() {
876
  return /** @type {goog.date.weekDay} */ ((this.getDay() + 6) % 7);
877
};
878

879

880
/**
881
 * @return {number} The day of week according to firstDayOfWeek setting.
882
 */
883
goog.date.Date.prototype.getWeekday = function() {
884
  return (this.getIsoWeekday() - this.firstDayOfWeek_ + 7) % 7;
885
};
886

887

888
/**
889
 * @return {number} The four digit year of date according to universal time.
890
 */
891
goog.date.Date.prototype.getUTCFullYear = function() {
892
  return this.date.getUTCFullYear();
893
};
894

895

896
/**
897
 * @return {goog.date.month} The month of date according to universal time,
898
 *     0 = Jan, 11 = Dec.
899
 */
900
goog.date.Date.prototype.getUTCMonth = function() {
901
  return /** @type {goog.date.month} */ (this.date.getUTCMonth());
902
};
903

904

905
/**
906
 * @return {number} The date of month according to universal time.
907
 */
908
goog.date.Date.prototype.getUTCDate = function() {
909
  return this.date.getUTCDate();
910
};
911

912

913
/**
914
 * @return {number} The day of week according to universal time, US style.
915
 *     0 = Sun, 1 = Mon, 6 = Sat.
916
 */
917
goog.date.Date.prototype.getUTCDay = function() {
918
  return this.date.getDay();
919
};
920

921

922
/**
923
 * @return {number} The hours value according to universal time.
924
 */
925
goog.date.Date.prototype.getUTCHours = function() {
926
  return this.date.getUTCHours();
927
};
928

929

930
/**
931
 * @return {number} The minutes value according to universal time.
932
 */
933
goog.date.Date.prototype.getUTCMinutes = function() {
934
  return this.date.getUTCMinutes();
935
};
936

937

938
/**
939
 * @return {goog.date.weekDay} The day of week according to universal time, ISO
940
 *     style. 0 = Mon, 6 = Sun.
941
 */
942
goog.date.Date.prototype.getUTCIsoWeekday = function() {
943
  return /** @type {goog.date.weekDay} */ ((this.date.getUTCDay() + 6) % 7);
944
};
945

946

947
/**
948
 * @return {number} The day of week according to universal time and
949
 *     firstDayOfWeek setting.
950
 */
951
goog.date.Date.prototype.getUTCWeekday = function() {
952
  return (this.getUTCIsoWeekday() - this.firstDayOfWeek_ + 7) % 7;
953
};
954

955

956
/**
957
 * @return {number} The first day of the week. 0 = Mon, 6 = Sun.
958
 */
959
goog.date.Date.prototype.getFirstDayOfWeek = function() {
960
  return this.firstDayOfWeek_;
961
};
962

963

964
/**
965
 * @return {number} The cut off weekday used for week number calculations.
966
 *     0 = Mon, 6 = Sun.
967
 */
968
goog.date.Date.prototype.getFirstWeekCutOffDay = function() {
969
  return this.firstWeekCutOffDay_;
970
};
971

972

973
/**
974
 * @return {number} The number of days for the selected month.
975
 */
976
goog.date.Date.prototype.getNumberOfDaysInMonth = function() {
977
  return goog.date.getNumberOfDaysInMonth(this.getFullYear(), this.getMonth());
978
};
979

980

981
/**
982
 * @return {number} The week number.
983
 */
984
goog.date.Date.prototype.getWeekNumber = function() {
985
  return goog.date.getWeekNumber(
986
      this.getFullYear(), this.getMonth(), this.getDate(),
987
      this.firstWeekCutOffDay_, this.firstDayOfWeek_);
988
};
989

990

991
/**
992
 * @return {number} The day of year.
993
 */
994
goog.date.Date.prototype.getDayOfYear = function() {
995
  var dayOfYear = this.getDate();
996
  var year = this.getFullYear();
997
  for (var m = this.getMonth() - 1; m >= 0; m--) {
998
    dayOfYear += goog.date.getNumberOfDaysInMonth(year, m);
999
  }
1000

1001
  return dayOfYear;
1002
};
1003

1004

1005
/**
1006
 * Returns timezone offset. The timezone offset is the delta in minutes between
1007
 * UTC and your local time. E.g., UTC+10 returns -600. Daylight savings time
1008
 * prevents this value from being constant.
1009
 *
1010
 * @return {number} The timezone offset.
1011
 */
1012
goog.date.Date.prototype.getTimezoneOffset = function() {
1013
  return this.date.getTimezoneOffset();
1014
};
1015

1016

1017
/**
1018
 * Returns timezone offset as a string. Returns offset in [+-]HH:mm format or Z
1019
 * for UTC.
1020
 *
1021
 * @return {string} The timezone offset as a string.
1022
 */
1023
goog.date.Date.prototype.getTimezoneOffsetString = function() {
1024
  var tz;
1025
  var offset = this.getTimezoneOffset();
1026

1027
  if (offset == 0) {
1028
    tz = 'Z';
1029
  } else {
1030
    var n = Math.abs(offset) / 60;
1031
    var h = Math.floor(n);
1032
    var m = (n - h) * 60;
1033
    tz = (offset > 0 ? '-' : '+') + goog.string.padNumber(h, 2) + ':' +
1034
        goog.string.padNumber(m, 2);
1035
  }
1036

1037
  return tz;
1038
};
1039

1040

1041
/**
1042
 * Sets the date.
1043
 *
1044
 * @param {goog.date.Date} date Date object to set date from.
1045
 */
1046
goog.date.Date.prototype.set = function(date) {
1047
  this.date = new Date(date.getFullYear(), date.getMonth(), date.getDate());
1048
};
1049

1050

1051
/**
1052
 * Sets the year part of the date.
1053
 *
1054
 * @param {number} year Four digit year.
1055
 */
1056
goog.date.Date.prototype.setFullYear = function(year) {
1057
  this.date.setFullYear(year);
1058
};
1059

1060

1061
/**
1062
 * Alias for setFullYear.
1063
 *
1064
 * @param {number} year Four digit year.
1065
 * @see #setFullYear
1066
 */
1067
goog.date.Date.prototype.setYear = function(year) {
1068
  this.setFullYear(year);
1069
};
1070

1071

1072
/**
1073
 * Sets the month part of the date.
1074
 *
1075
 * TODO(nnaze): Update type to goog.date.month.
1076
 *
1077
 * @param {number} month The month, where 0 = Jan, 11 = Dec.
1078
 */
1079
goog.date.Date.prototype.setMonth = function(month) {
1080
  this.date.setMonth(month);
1081
};
1082

1083

1084
/**
1085
 * Sets the day part of the date.
1086
 *
1087
 * @param {number} date The day part.
1088
 */
1089
goog.date.Date.prototype.setDate = function(date) {
1090
  this.date.setDate(date);
1091
};
1092

1093

1094
/**
1095
 * Sets the value of the date object as expressed in the number of milliseconds
1096
 * since 1 January 1970 00:00:00.
1097
 *
1098
 * @param {number} ms Number of milliseconds since 1 Jan 1970.
1099
 */
1100
goog.date.Date.prototype.setTime = function(ms) {
1101
  this.date.setTime(ms);
1102
};
1103

1104

1105
/**
1106
 * Sets the year part of the date according to universal time.
1107
 *
1108
 * @param {number} year Four digit year.
1109
 */
1110
goog.date.Date.prototype.setUTCFullYear = function(year) {
1111
  this.date.setUTCFullYear(year);
1112
};
1113

1114

1115
/**
1116
 * Sets the month part of the date according to universal time.
1117
 *
1118
 * @param {number} month The month, where 0 = Jan, 11 = Dec.
1119
 */
1120
goog.date.Date.prototype.setUTCMonth = function(month) {
1121
  this.date.setUTCMonth(month);
1122
};
1123

1124

1125
/**
1126
 * Sets the day part of the date according to universal time.
1127
 *
1128
 * @param {number} date The UTC date.
1129
 */
1130
goog.date.Date.prototype.setUTCDate = function(date) {
1131
  this.date.setUTCDate(date);
1132
};
1133

1134

1135
/**
1136
 * Sets the first day of week.
1137
 *
1138
 * @param {number} day 0 = Mon, 6 = Sun.
1139
 */
1140
goog.date.Date.prototype.setFirstDayOfWeek = function(day) {
1141
  this.firstDayOfWeek_ = day;
1142
};
1143

1144

1145
/**
1146
 * Sets cut off weekday used for week number calculations. 0 = Mon, 6 = Sun.
1147
 *
1148
 * @param {number} day The cut off weekday.
1149
 */
1150
goog.date.Date.prototype.setFirstWeekCutOffDay = function(day) {
1151
  this.firstWeekCutOffDay_ = day;
1152
};
1153

1154

1155
/**
1156
 * Performs date calculation by adding the supplied interval to the date.
1157
 *
1158
 * @param {goog.date.Interval} interval Date interval to add.
1159
 */
1160
goog.date.Date.prototype.add = function(interval) {
1161
  if (interval.years || interval.months) {
1162
    // As months have different number of days adding a month to Jan 31 by just
1163
    // setting the month would result in a date in early March rather than Feb
1164
    // 28 or 29. Doing it this way overcomes that problem.
1165

1166
    // adjust year and month, accounting for both directions
1167
    var month = this.getMonth() + interval.months + interval.years * 12;
1168
    var year = this.getYear() + Math.floor(month / 12);
1169
    month %= 12;
1170
    if (month < 0) {
1171
      month += 12;
1172
    }
1173

1174
    var daysInTargetMonth = goog.date.getNumberOfDaysInMonth(year, month);
1175
    var date = Math.min(daysInTargetMonth, this.getDate());
1176

1177
    // avoid inadvertently causing rollovers to adjacent months
1178
    this.setDate(1);
1179

1180
    this.setFullYear(year);
1181
    this.setMonth(month);
1182
    this.setDate(date);
1183
  }
1184

1185
  if (interval.days) {
1186
    // Convert the days to milliseconds and add it to the UNIX timestamp.
1187
    // Taking noon helps to avoid 1 day error due to the daylight saving.
1188
    var noon = new Date(this.getYear(), this.getMonth(), this.getDate(), 12);
1189
    var result = new Date(noon.getTime() + interval.days * 86400000);
1190

1191
    // Set date to 1 to prevent rollover caused by setting the year or month.
1192
    this.setDate(1);
1193
    this.setFullYear(result.getFullYear());
1194
    this.setMonth(result.getMonth());
1195
    this.setDate(result.getDate());
1196

1197
    this.maybeFixDst_(result.getDate());
1198
  }
1199
};
1200

1201

1202
/**
1203
 * Returns ISO 8601 string representation of date.
1204
 *
1205
 * @param {boolean=} opt_verbose Whether the verbose format should be used
1206
 *     instead of the default compact one.
1207
 * @param {boolean=} opt_tz Whether the timezone offset should be included
1208
 *     in the string.
1209
 * @return {string} ISO 8601 string representation of date.
1210
 */
1211
goog.date.Date.prototype.toIsoString = function(opt_verbose, opt_tz) {
1212
  var str = [
1213
    this.getFullYear(), goog.string.padNumber(this.getMonth() + 1, 2),
1214
    goog.string.padNumber(this.getDate(), 2)
1215
  ];
1216

1217
  return str.join((opt_verbose) ? '-' : '') +
1218
      (opt_tz ? this.getTimezoneOffsetString() : '');
1219
};
1220

1221

1222
/**
1223
 * Returns ISO 8601 string representation of date according to universal time.
1224
 *
1225
 * @param {boolean=} opt_verbose Whether the verbose format should be used
1226
 *     instead of the default compact one.
1227
 * @param {boolean=} opt_tz Whether the timezone offset should be included in
1228
 *     the string.
1229
 * @return {string} ISO 8601 string representation of date according to
1230
 *     universal time.
1231
 */
1232
goog.date.Date.prototype.toUTCIsoString = function(opt_verbose, opt_tz) {
1233
  var str = [
1234
    this.getUTCFullYear(), goog.string.padNumber(this.getUTCMonth() + 1, 2),
1235
    goog.string.padNumber(this.getUTCDate(), 2)
1236
  ];
1237

1238
  return str.join((opt_verbose) ? '-' : '') + (opt_tz ? 'Z' : '');
1239
};
1240

1241

1242
/**
1243
 * Tests whether given date is equal to this Date.
1244
 * Note: This ignores units more precise than days (hours and below)
1245
 * and also ignores timezone considerations.
1246
 *
1247
 * @param {goog.date.Date} other The date to compare.
1248
 * @return {boolean} Whether the given date is equal to this one.
1249
 */
1250
goog.date.Date.prototype.equals = function(other) {
1251
  return !!(
1252
      other && this.getYear() == other.getYear() &&
1253
      this.getMonth() == other.getMonth() && this.getDate() == other.getDate());
1254
};
1255

1256

1257
/**
1258
 * Overloaded toString method for object.
1259
 * @return {string} ISO 8601 string representation of date.
1260
 * @override
1261
 */
1262
goog.date.Date.prototype.toString = function() {
1263
  return this.toIsoString();
1264
};
1265

1266

1267
/**
1268
 * Fixes date to account for daylight savings time in browsers that fail to do
1269
 * so automatically.
1270
 * @param {number} expected Expected date.
1271
 * @private
1272
 */
1273
goog.date.Date.prototype.maybeFixDst_ = function(expected) {
1274
  if (this.getDate() != expected) {
1275
    var dir = this.getDate() < expected ? 1 : -1;
1276
    this.date.setUTCHours(this.date.getUTCHours() + dir);
1277
  }
1278
};
1279

1280

1281
/**
1282
 * @return {number} Value of wrapped date.
1283
 * @override
1284
 */
1285
goog.date.Date.prototype.valueOf = function() {
1286
  return this.date.valueOf();
1287
};
1288

1289

1290
/**
1291
 * Compares two dates.  May be used as a sorting function.
1292
 * @see goog.array.sort
1293
 * @param {!goog.date.DateLike} date1 Date to compare.
1294
 * @param {!goog.date.DateLike} date2 Date to compare.
1295
 * @return {number} Comparison result. 0 if dates are the same, less than 0 if
1296
 *     date1 is earlier than date2, greater than 0 if date1 is later than date2.
1297
 */
1298
goog.date.Date.compare = function(date1, date2) {
1299
  return date1.getTime() - date2.getTime();
1300
};
1301

1302

1303

1304
/**
1305
 * Class representing a date and time. Defaults to current date and time if none
1306
 * is specified.
1307
 *
1308
 * Implements most methods of the native js Date object and can be used
1309
 * interchangeably with it just as if goog.date.DateTime was a subclass of Date.
1310
 *
1311
 * @param {number|Object=} opt_year Four digit year or a date-like object. If
1312
 *     not set, the created object will contain the date determined by
1313
 *     goog.now().
1314
 * @param {number=} opt_month Month, 0 = Jan, 11 = Dec.
1315
 * @param {number=} opt_date Date of month, 1 - 31.
1316
 * @param {number=} opt_hours Hours, 0 - 23.
1317
 * @param {number=} opt_minutes Minutes, 0 - 59.
1318
 * @param {number=} opt_seconds Seconds, 0 - 61.
1319
 * @param {number=} opt_milliseconds Milliseconds, 0 - 999.
1320
 * @constructor
1321
 * @struct
1322
 * @extends {goog.date.Date}
1323
 */
1324
goog.date.DateTime = function(
1325
    opt_year, opt_month, opt_date, opt_hours, opt_minutes, opt_seconds,
1326
    opt_milliseconds) {
1327
  if (goog.isNumber(opt_year)) {
1328
    this.date = new Date(
1329
        opt_year, opt_month || 0, opt_date || 1, opt_hours || 0,
1330
        opt_minutes || 0, opt_seconds || 0, opt_milliseconds || 0);
1331
  } else {
1332
    this.date = new Date(
1333
        opt_year && opt_year.getTime ? opt_year.getTime() : goog.now());
1334
  }
1335
};
1336
goog.inherits(goog.date.DateTime, goog.date.Date);
1337

1338

1339
/**
1340
 * @param {number} timestamp Number of milliseconds since Epoch.
1341
 * @return {!goog.date.DateTime}
1342
 */
1343
goog.date.DateTime.fromTimestamp = function(timestamp) {
1344
  var date = new goog.date.DateTime();
1345
  date.setTime(timestamp);
1346
  return date;
1347
};
1348

1349

1350
/**
1351
 * Creates a DateTime from a datetime string expressed in RFC 822 format.
1352
 *
1353
 * @param {string} formatted A date or datetime expressed in RFC 822 format.
1354
 * @return {goog.date.DateTime} Parsed date or null if parse fails.
1355
 */
1356
goog.date.DateTime.fromRfc822String = function(formatted) {
1357
  var date = new Date(formatted);
1358
  return !isNaN(date.getTime()) ? new goog.date.DateTime(date) : null;
1359
};
1360

1361

1362
/**
1363
 * Returns the hours part of the datetime.
1364
 *
1365
 * @return {number} An integer between 0 and 23, representing the hour.
1366
 */
1367
goog.date.DateTime.prototype.getHours = function() {
1368
  return this.date.getHours();
1369
};
1370

1371

1372
/**
1373
 * Returns the minutes part of the datetime.
1374
 *
1375
 * @return {number} An integer between 0 and 59, representing the minutes.
1376
 */
1377
goog.date.DateTime.prototype.getMinutes = function() {
1378
  return this.date.getMinutes();
1379
};
1380

1381

1382
/**
1383
 * Returns the seconds part of the datetime.
1384
 *
1385
 * @return {number} An integer between 0 and 59, representing the seconds.
1386
 */
1387
goog.date.DateTime.prototype.getSeconds = function() {
1388
  return this.date.getSeconds();
1389
};
1390

1391

1392
/**
1393
 * Returns the milliseconds part of the datetime.
1394
 *
1395
 * @return {number} An integer between 0 and 999, representing the milliseconds.
1396
 */
1397
goog.date.DateTime.prototype.getMilliseconds = function() {
1398
  return this.date.getMilliseconds();
1399
};
1400

1401

1402
/**
1403
 * Returns the day of week according to universal time, US style.
1404
 *
1405
 * @return {goog.date.weekDay} Day of week, 0 = Sun, 1 = Mon, 6 = Sat.
1406
 * @override
1407
 */
1408
goog.date.DateTime.prototype.getUTCDay = function() {
1409
  return /** @type {goog.date.weekDay} */ (this.date.getUTCDay());
1410
};
1411

1412

1413
/**
1414
 * Returns the hours part of the datetime according to universal time.
1415
 *
1416
 * @return {number} An integer between 0 and 23, representing the hour.
1417
 * @override
1418
 */
1419
goog.date.DateTime.prototype.getUTCHours = function() {
1420
  return this.date.getUTCHours();
1421
};
1422

1423

1424
/**
1425
 * Returns the minutes part of the datetime according to universal time.
1426
 *
1427
 * @return {number} An integer between 0 and 59, representing the minutes.
1428
 * @override
1429
 */
1430
goog.date.DateTime.prototype.getUTCMinutes = function() {
1431
  return this.date.getUTCMinutes();
1432
};
1433

1434

1435
/**
1436
 * Returns the seconds part of the datetime according to universal time.
1437
 *
1438
 * @return {number} An integer between 0 and 59, representing the seconds.
1439
 */
1440
goog.date.DateTime.prototype.getUTCSeconds = function() {
1441
  return this.date.getUTCSeconds();
1442
};
1443

1444

1445
/**
1446
 * Returns the milliseconds part of the datetime according to universal time.
1447
 *
1448
 * @return {number} An integer between 0 and 999, representing the milliseconds.
1449
 */
1450
goog.date.DateTime.prototype.getUTCMilliseconds = function() {
1451
  return this.date.getUTCMilliseconds();
1452
};
1453

1454

1455
/**
1456
 * Sets the hours part of the datetime.
1457
 *
1458
 * @param {number} hours An integer between 0 and 23, representing the hour.
1459
 */
1460
goog.date.DateTime.prototype.setHours = function(hours) {
1461
  this.date.setHours(hours);
1462
};
1463

1464

1465
/**
1466
 * Sets the minutes part of the datetime.
1467
 *
1468
 * @param {number} minutes Integer between 0 and 59, representing the minutes.
1469
 */
1470
goog.date.DateTime.prototype.setMinutes = function(minutes) {
1471
  this.date.setMinutes(minutes);
1472
};
1473

1474

1475
/**
1476
 * Sets the seconds part of the datetime.
1477
 *
1478
 * @param {number} seconds Integer between 0 and 59, representing the seconds.
1479
 */
1480
goog.date.DateTime.prototype.setSeconds = function(seconds) {
1481
  this.date.setSeconds(seconds);
1482
};
1483

1484

1485
/**
1486
 * Sets the milliseconds part of the datetime.
1487
 *
1488
 * @param {number} ms Integer between 0 and 999, representing the milliseconds.
1489
 */
1490
goog.date.DateTime.prototype.setMilliseconds = function(ms) {
1491
  this.date.setMilliseconds(ms);
1492
};
1493

1494

1495
/**
1496
 * Sets the hours part of the datetime according to universal time.
1497
 *
1498
 * @param {number} hours An integer between 0 and 23, representing the hour.
1499
 */
1500
goog.date.DateTime.prototype.setUTCHours = function(hours) {
1501
  this.date.setUTCHours(hours);
1502
};
1503

1504

1505
/**
1506
 * Sets the minutes part of the datetime according to universal time.
1507
 *
1508
 * @param {number} minutes Integer between 0 and 59, representing the minutes.
1509
 */
1510
goog.date.DateTime.prototype.setUTCMinutes = function(minutes) {
1511
  this.date.setUTCMinutes(minutes);
1512
};
1513

1514

1515
/**
1516
 * Sets the seconds part of the datetime according to universal time.
1517
 *
1518
 * @param {number} seconds Integer between 0 and 59, representing the seconds.
1519
 */
1520
goog.date.DateTime.prototype.setUTCSeconds = function(seconds) {
1521
  this.date.setUTCSeconds(seconds);
1522
};
1523

1524

1525
/**
1526
 * Sets the seconds part of the datetime according to universal time.
1527
 *
1528
 * @param {number} ms Integer between 0 and 999, representing the milliseconds.
1529
 */
1530
goog.date.DateTime.prototype.setUTCMilliseconds = function(ms) {
1531
  this.date.setUTCMilliseconds(ms);
1532
};
1533

1534

1535
/**
1536
 * @return {boolean} Whether the datetime is aligned to midnight.
1537
 */
1538
goog.date.DateTime.prototype.isMidnight = function() {
1539
  return this.getHours() == 0 && this.getMinutes() == 0 &&
1540
      this.getSeconds() == 0 && this.getMilliseconds() == 0;
1541
};
1542

1543

1544
/**
1545
 * Performs date calculation by adding the supplied interval to the date.
1546
 *
1547
 * @param {goog.date.Interval} interval Date interval to add.
1548
 * @override
1549
 */
1550
goog.date.DateTime.prototype.add = function(interval) {
1551
  goog.date.Date.prototype.add.call(this, interval);
1552

1553
  if (interval.hours) {
1554
    this.setUTCHours(this.date.getUTCHours() + interval.hours);
1555
  }
1556
  if (interval.minutes) {
1557
    this.setUTCMinutes(this.date.getUTCMinutes() + interval.minutes);
1558
  }
1559
  if (interval.seconds) {
1560
    this.setUTCSeconds(this.date.getUTCSeconds() + interval.seconds);
1561
  }
1562
};
1563

1564

1565
/**
1566
 * Returns ISO 8601 string representation of date/time.
1567
 *
1568
 * @param {boolean=} opt_verbose Whether the verbose format should be used
1569
 *     instead of the default compact one.
1570
 * @param {boolean=} opt_tz Whether the timezone offset should be included
1571
 *     in the string.
1572
 * @return {string} ISO 8601 string representation of date/time.
1573
 * @override
1574
 */
1575
goog.date.DateTime.prototype.toIsoString = function(opt_verbose, opt_tz) {
1576
  var dateString = goog.date.Date.prototype.toIsoString.call(this, opt_verbose);
1577

1578
  if (opt_verbose) {
1579
    return dateString + ' ' + goog.string.padNumber(this.getHours(), 2) + ':' +
1580
        goog.string.padNumber(this.getMinutes(), 2) + ':' +
1581
        goog.string.padNumber(this.getSeconds(), 2) +
1582
        (opt_tz ? this.getTimezoneOffsetString() : '');
1583
  }
1584

1585
  return dateString + 'T' + goog.string.padNumber(this.getHours(), 2) +
1586
      goog.string.padNumber(this.getMinutes(), 2) +
1587
      goog.string.padNumber(this.getSeconds(), 2) +
1588
      (opt_tz ? this.getTimezoneOffsetString() : '');
1589
};
1590

1591

1592
/**
1593
 * Returns XML Schema 2 string representation of date/time.
1594
 * The return value is also ISO 8601 compliant.
1595
 *
1596
 * @param {boolean=} opt_timezone Should the timezone offset be included in the
1597
 *     string?.
1598
 * @return {string} XML Schema 2 string representation of date/time.
1599
 */
1600
goog.date.DateTime.prototype.toXmlDateTime = function(opt_timezone) {
1601
  return goog.date.Date.prototype.toIsoString.call(this, true) + 'T' +
1602
      goog.string.padNumber(this.getHours(), 2) + ':' +
1603
      goog.string.padNumber(this.getMinutes(), 2) + ':' +
1604
      goog.string.padNumber(this.getSeconds(), 2) +
1605
      (opt_timezone ? this.getTimezoneOffsetString() : '');
1606
};
1607

1608

1609
/**
1610
 * Returns ISO 8601 string representation of date/time according to universal
1611
 * time.
1612
 *
1613
 * @param {boolean=} opt_verbose Whether the opt_verbose format should be
1614
 *     returned instead of the default compact one.
1615
 * @param {boolean=} opt_tz Whether the the timezone offset should be included
1616
 *     in the string.
1617
 * @return {string} ISO 8601 string representation of date/time according to
1618
 *     universal time.
1619
 * @override
1620
 */
1621
goog.date.DateTime.prototype.toUTCIsoString = function(opt_verbose, opt_tz) {
1622
  var dateStr = goog.date.Date.prototype.toUTCIsoString.call(this, opt_verbose);
1623

1624
  if (opt_verbose) {
1625
    return dateStr + ' ' + goog.string.padNumber(this.getUTCHours(), 2) + ':' +
1626
        goog.string.padNumber(this.getUTCMinutes(), 2) + ':' +
1627
        goog.string.padNumber(this.getUTCSeconds(), 2) + (opt_tz ? 'Z' : '');
1628
  }
1629

1630
  return dateStr + 'T' + goog.string.padNumber(this.getUTCHours(), 2) +
1631
      goog.string.padNumber(this.getUTCMinutes(), 2) +
1632
      goog.string.padNumber(this.getUTCSeconds(), 2) + (opt_tz ? 'Z' : '');
1633
};
1634

1635

1636
/**
1637
 * Returns RFC 3339 string representation of datetime in UTC.
1638
 *
1639
 * @return {string} A UTC datetime expressed in RFC 3339 format.
1640
 */
1641
goog.date.DateTime.prototype.toUTCRfc3339String = function() {
1642
  var date = this.toUTCIsoString(true).replace(' ', 'T');
1643
  var millis = this.getUTCMilliseconds();
1644
  return (millis ? date + '.' + millis : date) + 'Z';
1645
};
1646

1647

1648
/**
1649
 * Tests whether given datetime is exactly equal to this DateTime.
1650
 *
1651
 * @param {goog.date.Date} other The datetime to compare.
1652
 * @return {boolean} Whether the given datetime is exactly equal to this one.
1653
 * @override
1654
 */
1655
goog.date.DateTime.prototype.equals = function(other) {
1656
  return this.getTime() == other.getTime();
1657
};
1658

1659

1660
/**
1661
 * Overloaded toString method for object.
1662
 * @return {string} ISO 8601 string representation of date/time.
1663
 * @override
1664
 */
1665
goog.date.DateTime.prototype.toString = function() {
1666
  return this.toIsoString();
1667
};
1668

1669

1670
/**
1671
 * Generates time label for the datetime, e.g., '5:30 AM'.
1672
 * By default this does not pad hours (e.g., to '05:30') and it does add
1673
 * an am/pm suffix.
1674
 * TODO(user): i18n -- hardcoding time format like this is bad.  E.g., in CJK
1675
 *               locales, need Chinese characters for hour and minute units.
1676
 * @param {boolean=} opt_padHours Whether to pad hours, e.g., '05:30' vs '5:30'.
1677
 * @param {boolean=} opt_showAmPm Whether to show the 'am' and 'pm' suffix.
1678
 * @param {boolean=} opt_omitZeroMinutes E.g., '5:00pm' becomes '5pm',
1679
 *                                      but '5:01pm' remains '5:01pm'.
1680
 * @return {string} The time label.
1681
 */
1682
goog.date.DateTime.prototype.toUsTimeString = function(
1683
    opt_padHours, opt_showAmPm, opt_omitZeroMinutes) {
1684
  var hours = this.getHours();
1685

1686
  // show am/pm marker by default
1687
  if (!goog.isDef(opt_showAmPm)) {
1688
    opt_showAmPm = true;
1689
  }
1690

1691
  // 12pm
1692
  var isPM = hours == 12;
1693

1694
  // change from 1-24 to 1-12 basis
1695
  if (hours > 12) {
1696
    hours -= 12;
1697
    isPM = true;
1698
  }
1699

1700
  // midnight is expressed as "12am", but if am/pm marker omitted, keep as '0'
1701
  if (hours == 0 && opt_showAmPm) {
1702
    hours = 12;
1703
  }
1704

1705
  var label = opt_padHours ? goog.string.padNumber(hours, 2) : String(hours);
1706
  var minutes = this.getMinutes();
1707
  if (!opt_omitZeroMinutes || minutes > 0) {
1708
    label += ':' + goog.string.padNumber(minutes, 2);
1709
  }
1710

1711
  // by default, show am/pm suffix
1712
  if (opt_showAmPm) {
1713
    label += isPM ? ' PM' : ' AM';
1714
  }
1715
  return label;
1716
};
1717

1718

1719
/**
1720
 * Generates time label for the datetime in standard ISO 24-hour time format.
1721
 * E.g., '06:00:00' or '23:30:15'.
1722
 * @param {boolean=} opt_showSeconds Whether to shows seconds. Defaults to TRUE.
1723
 * @return {string} The time label.
1724
 */
1725
goog.date.DateTime.prototype.toIsoTimeString = function(opt_showSeconds) {
1726
  var hours = this.getHours();
1727
  var label = goog.string.padNumber(hours, 2) + ':' +
1728
      goog.string.padNumber(this.getMinutes(), 2);
1729
  if (!goog.isDef(opt_showSeconds) || opt_showSeconds) {
1730
    label += ':' + goog.string.padNumber(this.getSeconds(), 2);
1731
  }
1732
  return label;
1733
};
1734

1735

1736
/**
1737
 * @return {!goog.date.DateTime} A clone of the datetime object.
1738
 * @override
1739
 */
1740
goog.date.DateTime.prototype.clone = function() {
1741
  var date = new goog.date.DateTime(this.date);
1742
  date.setFirstDayOfWeek(this.getFirstDayOfWeek());
1743
  date.setFirstWeekCutOffDay(this.getFirstWeekCutOffDay());
1744
  return date;
1745
};
1746

1747