Update wmts-hidpi, add nicer-api-docs

nicer-api-docs/closure-library/closure/goog/date/datelike.js

@@ -0,0 +1,27 @@
+// Copyright 2010 The Closure Library Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS-IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @fileoverview Typedefs for working with dates.
+ *
+ * @author nicksantos@google.com (Nick Santos)
+ */
+
+goog.provide('goog.date.DateLike');
+
+
+/**
+ * @typedef {(Date|goog.date.Date)}
+ */
+goog.date.DateLike;

nicer-api-docs/closure-library/closure/goog/date/daterange.js

@@ -0,0 +1,413 @@
+// Copyright 2008 The Closure Library Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS-IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @fileoverview Date range data structure. Based loosely on
+ * com.google.common.util.DateRange.
+ *
+ */
+
+goog.provide('goog.date.DateRange');
+goog.provide('goog.date.DateRange.Iterator');
+goog.provide('goog.date.DateRange.StandardDateRangeKeys');
+
+goog.require('goog.date.Date');
+goog.require('goog.date.Interval');
+goog.require('goog.iter.Iterator');
+goog.require('goog.iter.StopIteration');
+
+
+
+/**
+ * Constructs a date range.
+ * @constructor
+ * @param {goog.date.Date} startDate The first date in the range.
+ * @param {goog.date.Date} endDate The last date in the range.
+ */
+goog.date.DateRange = function(startDate, endDate) {
+  /**
+   * The first date in the range.
+   * @type {goog.date.Date}
+   * @private
+   */
+  this.startDate_ = startDate;
+
+  /**
+   * The last date in the range.
+   * @type {goog.date.Date}
+   * @private
+   */
+  this.endDate_ = endDate;
+};
+
+
+/**
+ * The first possible day, as far as this class is concerned.
+ * @type {goog.date.Date}
+ */
+goog.date.DateRange.MINIMUM_DATE = new goog.date.Date(0000, 0, 1);
+
+
+/**
+ * The last possible day, as far as this class is concerned.
+ * @type {goog.date.Date}
+ */
+goog.date.DateRange.MAXIMUM_DATE = new goog.date.Date(9999, 11, 31);
+
+
+/**
+ * @return {goog.date.Date} The first date in the range.
+ */
+goog.date.DateRange.prototype.getStartDate = function() {
+  return this.startDate_;
+};
+
+
+/**
+ * @return {goog.date.Date} The last date in the range.
+ */
+goog.date.DateRange.prototype.getEndDate = function() {
+  return this.endDate_;
+};
+
+
+/**
+ * @return {goog.iter.Iterator} An iterator over the date range.
+ */
+goog.date.DateRange.prototype.iterator = function() {
+  return new goog.date.DateRange.Iterator(this);
+};
+
+
+/**
+ * Tests two {@link goog.date.DateRange} objects for equality.
+ * @param {goog.date.DateRange} a A date range.
+ * @param {goog.date.DateRange} b A date range.
+ * @return {boolean} Whether |a| is the same range as |b|.
+ */
+goog.date.DateRange.equals = function(a, b) {
+  // Test for same object reference; type conversion is irrelevant.
+  if (a === b) {
+    return true;
+  }
+
+  if (a == null || b == null) {
+    return false;
+  }
+
+  return a.startDate_.equals(b.startDate_) && a.endDate_.equals(b.endDate_);
+};
+
+
+/**
+ * Calculates a date that is a number of days after a date. Does not modify its
+ * input.
+ * @param {goog.date.Date} date The input date.
+ * @param {number} offset Number of days.
+ * @return {goog.date.Date} The date that is |offset| days after |date|.
+ * @private
+ */
+goog.date.DateRange.offsetInDays_ = function(date, offset) {
+  var newDate = date.clone();
+  newDate.add(new goog.date.Interval(goog.date.Interval.DAYS, offset));
+  return newDate;
+};
+
+
+/**
+ * Calculates the Monday before a date. If the input is a Monday, returns the
+ * input. Does not modify its input.
+ * @param {goog.date.Date} date The input date.
+ * @return {goog.date.Date} If |date| is a Monday, return |date|; otherwise
+ *     return the Monday before |date|.
+ * @private
+ */
+goog.date.DateRange.currentOrLastMonday_ = function(date) {
+  var newDate = date.clone();
+  newDate.add(new goog.date.Interval(goog.date.Interval.DAYS,
+      -newDate.getIsoWeekday()));
+  return newDate;
+};
+
+
+/**
+ * Calculates a date that is a number of months after the first day in the
+ * month that contains its input. Does not modify its input.
+ * @param {goog.date.Date} date The input date.
+ * @param {number} offset Number of months.
+ * @return {goog.date.Date} The date that is |offset| months after the first
+ *     day in the month that contains |date|.
+ * @private
+ */
+goog.date.DateRange.offsetInMonths_ = function(date, offset) {
+  var newDate = date.clone();
+  newDate.setDate(1);
+  newDate.add(new goog.date.Interval(goog.date.Interval.MONTHS, offset));
+  return newDate;
+};
+
+
+/**
+ * Returns the range from yesterday to yesterday.
+ * @param {goog.date.Date=} opt_today The date to consider today.
+ *     Defaults to today.
+ * @return {goog.date.DateRange} The range that includes only yesterday.
+ */
+goog.date.DateRange.yesterday = function(opt_today) {
+  var today = goog.date.DateRange.cloneOrCreate_(opt_today);
+  var yesterday = goog.date.DateRange.offsetInDays_(today, -1);
+  return new goog.date.DateRange(yesterday, yesterday);
+};
+
+
+/**
+ * Returns the range from today to today.
+ * @param {goog.date.Date=} opt_today The date to consider today.
+ *     Defaults to today.
+ * @return {goog.date.DateRange} The range that includes only today.
+ */
+goog.date.DateRange.today = function(opt_today) {
+  var today = goog.date.DateRange.cloneOrCreate_(opt_today);
+  return new goog.date.DateRange(today, today);
+};
+
+
+/**
+ * Returns the range that includes the seven days that end yesterday.
+ * @param {goog.date.Date=} opt_today The date to consider today.
+ *     Defaults to today.
+ * @return {goog.date.DateRange} The range that includes the seven days that
+ *     end yesterday.
+ */
+goog.date.DateRange.last7Days = function(opt_today) {
+  var today = goog.date.DateRange.cloneOrCreate_(opt_today);
+  var yesterday = goog.date.DateRange.offsetInDays_(today, -1);
+  return new goog.date.DateRange(goog.date.DateRange.offsetInDays_(today, -7),
+      yesterday);
+};
+
+
+/**
+ * Returns the range that starts the first of this month and ends the last day
+ * of this month.
+ * @param {goog.date.Date=} opt_today The date to consider today.
+ *     Defaults to today.
+ * @return {goog.date.DateRange} The range that starts the first of this month
+ *     and ends the last day of this month.
+ */
+goog.date.DateRange.thisMonth = function(opt_today) {
+  var today = goog.date.DateRange.cloneOrCreate_(opt_today);
+  return new goog.date.DateRange(
+      goog.date.DateRange.offsetInMonths_(today, 0),
+      goog.date.DateRange.offsetInDays_(
+          goog.date.DateRange.offsetInMonths_(today, 1),
+          -1));
+};
+
+
+/**
+ * Returns the range that starts the first of last month and ends the last day
+ * of last month.
+ * @param {goog.date.Date=} opt_today The date to consider today.
+ *     Defaults to today.
+ * @return {goog.date.DateRange} The range that starts the first of last month
+ *     and ends the last day of last month.
+ */
+goog.date.DateRange.lastMonth = function(opt_today) {
+  var today = goog.date.DateRange.cloneOrCreate_(opt_today);
+  return new goog.date.DateRange(
+      goog.date.DateRange.offsetInMonths_(today, -1),
+      goog.date.DateRange.offsetInDays_(
+          goog.date.DateRange.offsetInMonths_(today, 0),
+          -1));
+};
+
+
+/**
+ * Returns the seven-day range that starts on the first day of the week
+ * (see {@link goog.i18n.DateTimeSymbols.FIRSTDAYOFWEEK}) on or before today.
+ * @param {goog.date.Date=} opt_today The date to consider today.
+ *     Defaults to today.
+ * @return {goog.date.DateRange} The range that starts the Monday on or before
+ *     today and ends the Sunday on or after today.
+ */
+goog.date.DateRange.thisWeek = function(opt_today) {
+  var today = goog.date.DateRange.cloneOrCreate_(opt_today);
+  var iso = today.getIsoWeekday();
+  var firstDay = today.getFirstDayOfWeek();
+  var i18nFirstDay = (iso >= firstDay) ? iso - firstDay : iso + (7 - firstDay);
+  var start = goog.date.DateRange.offsetInDays_(today, -i18nFirstDay);
+  var end = goog.date.DateRange.offsetInDays_(start, 6);
+  return new goog.date.DateRange(start, end);
+};
+
+
+/**
+ * Returns the seven-day range that ends the day before the first day of
+ * the week (see {@link goog.i18n.DateTimeSymbols.FIRSTDAYOFWEEK}) that
+ * contains today.
+ * @param {goog.date.Date=} opt_today The date to consider today.
+ *     Defaults to today.
+ * @return {goog.date.DateRange} The range that starts seven days before the
+ *     Monday on or before today and ends the Sunday on or before yesterday.
+ */
+goog.date.DateRange.lastWeek = function(opt_today) {
+  var thisWeek = goog.date.DateRange.thisWeek(opt_today);
+  var start = goog.date.DateRange.offsetInDays_(thisWeek.getStartDate(), -7);
+  var end = goog.date.DateRange.offsetInDays_(thisWeek.getEndDate(), -7);
+  return new goog.date.DateRange(start, end);
+};
+
+
+/**
+ * Returns the range that starts seven days before the Monday on or before
+ * today and ends the Friday before today.
+ * @param {goog.date.Date=} opt_today The date to consider today.
+ *     Defaults to today.
+ * @return {goog.date.DateRange} The range that starts seven days before the
+ *     Monday on or before today and ends the Friday before today.
+ */
+goog.date.DateRange.lastBusinessWeek = function(opt_today) {
+  // TODO(user): should be i18nized.
+  var today = goog.date.DateRange.cloneOrCreate_(opt_today);
+  var start = goog.date.DateRange.offsetInDays_(today,
+      - 7 - today.getIsoWeekday());
+  var end = goog.date.DateRange.offsetInDays_(start, 4);
+  return new goog.date.DateRange(start, end);
+};
+
+
+/**
+ * Returns the range that includes all days between January 1, 1900 and
+ * December 31, 9999.
+ * @param {goog.date.Date=} opt_today The date to consider today.
+ *     Defaults to today.
+ * @return {goog.date.DateRange} The range that includes all days between
+ *     January 1, 1900 and December 31, 9999.
+ */
+goog.date.DateRange.allTime = function(opt_today) {
+  return new goog.date.DateRange(
+      goog.date.DateRange.MINIMUM_DATE,
+      goog.date.DateRange.MAXIMUM_DATE);
+};
+
+
+/**
+ * Standard date range keys. Equivalent to the enum IDs in
+ * DateRange.java http://go/datarange.java
+ *
+ * @enum {string}
+ */
+goog.date.DateRange.StandardDateRangeKeys = {
+  YESTERDAY: 'yesterday',
+  TODAY: 'today',
+  LAST_7_DAYS: 'last7days',
+  THIS_MONTH: 'thismonth',
+  LAST_MONTH: 'lastmonth',
+  THIS_WEEK: 'thisweek',
+  LAST_WEEK: 'lastweek',
+  LAST_BUSINESS_WEEK: 'lastbusinessweek',
+  ALL_TIME: 'alltime'
+};
+
+
+/**
+ * @param {string} dateRangeKey A standard date range key.
+ * @param {goog.date.Date=} opt_today The date to consider today.
+ *     Defaults to today.
+ * @return {goog.date.DateRange} The date range that corresponds to that key.
+ * @throws {Error} If no standard date range with that key exists.
+ */
+goog.date.DateRange.standardDateRange = function(dateRangeKey, opt_today) {
+  switch (dateRangeKey) {
+    case goog.date.DateRange.StandardDateRangeKeys.YESTERDAY:
+      return goog.date.DateRange.yesterday(opt_today);
+
+    case goog.date.DateRange.StandardDateRangeKeys.TODAY:
+      return goog.date.DateRange.today(opt_today);
+
+    case goog.date.DateRange.StandardDateRangeKeys.LAST_7_DAYS:
+      return goog.date.DateRange.last7Days(opt_today);
+
+    case goog.date.DateRange.StandardDateRangeKeys.THIS_MONTH:
+      return goog.date.DateRange.thisMonth(opt_today);
+
+    case goog.date.DateRange.StandardDateRangeKeys.LAST_MONTH:
+      return goog.date.DateRange.lastMonth(opt_today);
+
+    case goog.date.DateRange.StandardDateRangeKeys.THIS_WEEK:
+      return goog.date.DateRange.thisWeek(opt_today);
+
+    case goog.date.DateRange.StandardDateRangeKeys.LAST_WEEK:
+      return goog.date.DateRange.lastWeek(opt_today);
+
+    case goog.date.DateRange.StandardDateRangeKeys.LAST_BUSINESS_WEEK:
+      return goog.date.DateRange.lastBusinessWeek(opt_today);
+
+    case goog.date.DateRange.StandardDateRangeKeys.ALL_TIME:
+      return goog.date.DateRange.allTime(opt_today);
+
+    default:
+      throw Error('no such date range key: ' + dateRangeKey);
+  }
+};
+
+
+/**
+ * Clones or creates new.
+ * @param {goog.date.Date=} opt_today The date to consider today.
+ *     Defaults to today.
+ * @return {!goog.date.Date} cloned or new.
+ * @private
+ */
+goog.date.DateRange.cloneOrCreate_ = function(opt_today) {
+  return opt_today ? opt_today.clone() : new goog.date.Date();
+};
+
+
+
+/**
+ * Creates an iterator over the dates in a {@link goog.date.DateRange}.
+ * @constructor
+ * @extends {goog.iter.Iterator}
+ * @param {goog.date.DateRange} dateRange The date range to iterate.
+ */
+goog.date.DateRange.Iterator = function(dateRange) {
+  /**
+   * The next date.
+   * @type {goog.date.Date}
+   * @private
+   */
+  this.nextDate_ = dateRange.getStartDate().clone();
+
+  /**
+   * The end date, expressed as an integer: YYYYMMDD.
+   * @type {number}
+   * @private
+   */
+  this.endDate_ = Number(dateRange.getEndDate().toIsoString());
+};
+goog.inherits(goog.date.DateRange.Iterator, goog.iter.Iterator);
+
+
+/** @override */
+goog.date.DateRange.Iterator.prototype.next = function() {
+  if (Number(this.nextDate_.toIsoString()) > this.endDate_) {
+    throw goog.iter.StopIteration;
+  }
+
+  var rv = this.nextDate_.clone();
+  this.nextDate_.add(new goog.date.Interval(goog.date.Interval.DAYS, 1));
+  return rv;
+};

nicer-api-docs/closure-library/closure/goog/date/relative.js

@@ -0,0 +1,465 @@
+// Copyright 2009 The Closure Library Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS-IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @fileoverview Functions for formatting relative dates.  Such as "3 days ago"
+ * "3 hours ago", "14 minutes ago", "12 days ago", "Today", "Yesterday".
+ *
+ */
+
+goog.provide('goog.date.relative');
+
+goog.require('goog.i18n.DateTimeFormat');
+
+
+/**
+ * Number of milliseconds in a minute.
+ * @type {number}
+ * @private
+ */
+goog.date.relative.MINUTE_MS_ = 60000;
+
+
+/**
+ * Number of milliseconds in a day.
+ * @type {number}
+ * @private
+ */
+goog.date.relative.DAY_MS_ = 86400000;
+
+
+/**
+ * Enumeration used to identify time units internally.
+ * @enum {number}
+ * @private
+ */
+goog.date.relative.Unit_ = {
+  MINUTES: 0,
+  HOURS: 1,
+  DAYS: 2
+};
+
+
+/**
+ * Full date formatter.
+ * @type {goog.i18n.DateTimeFormat}
+ * @private
+ */
+goog.date.relative.fullDateFormatter_;
+
+
+/**
+ * Short time formatter.
+ * @type {goog.i18n.DateTimeFormat}
+ * @private
+ */
+goog.date.relative.shortTimeFormatter_;
+
+
+/**
+ * Month-date formatter.
+ * @type {goog.i18n.DateTimeFormat}
+ * @private
+ */
+goog.date.relative.monthDateFormatter_;
+
+
+/**
+ * Returns a date in month format, e.g. Mar 15.
+ * @param {Date} date The date object.
+ * @return {string} The formatted string.
+ * @private
+ */
+goog.date.relative.formatMonth_ = function(date) {
+  if (!goog.date.relative.monthDateFormatter_) {
+    goog.date.relative.monthDateFormatter_ =
+        new goog.i18n.DateTimeFormat('MMM dd');
+  }
+  return goog.date.relative.monthDateFormatter_.format(date);
+};
+
+
+/**
+ * Returns a date in short-time format, e.g. 2:50 PM.
+ * @param {Date|goog.date.DateTime} date The date object.
+ * @return {string} The formatted string.
+ * @private
+ */
+goog.date.relative.formatShortTime_ = function(date) {
+  if (!goog.date.relative.shortTimeFormatter_) {
+    goog.date.relative.shortTimeFormatter_ = new goog.i18n.DateTimeFormat(
+        goog.i18n.DateTimeFormat.Format.SHORT_TIME);
+  }
+  return goog.date.relative.shortTimeFormatter_.format(date);
+};
+
+
+/**
+ * Returns a date in full date format, e.g. Tuesday, March 24, 2009.
+ * @param {Date|goog.date.DateTime} date The date object.
+ * @return {string} The formatted string.
+ * @private
+ */
+goog.date.relative.formatFullDate_ = function(date) {
+  if (!goog.date.relative.fullDateFormatter_) {
+    goog.date.relative.fullDateFormatter_ = new goog.i18n.DateTimeFormat(
+        goog.i18n.DateTimeFormat.Format.FULL_DATE);
+  }
+  return goog.date.relative.fullDateFormatter_.format(date);
+};
+
+
+/**
+ * Accepts a timestamp in milliseconds and outputs a relative time in the form
+ * of "1 hour ago", "1 day ago", "in 1 hour", "in 2 days" etc.  If the date
+ * delta is over 2 weeks, then the output string will be empty.
+ * @param {number} dateMs Date in milliseconds.
+ * @return {string} The formatted date.
+ */
+goog.date.relative.format = function(dateMs) {
+  var now = goog.now();
+  var delta = Math.floor((now - dateMs) / goog.date.relative.MINUTE_MS_);
+
+  var future = false;
+
+  if (delta < 0) {
+    future = true;
+    delta *= -1;
+  }
+
+  if (delta < 60) { // Minutes.
+    return goog.date.relative.getMessage_(
+        delta, future, goog.date.relative.Unit_.MINUTES);
+
+  } else {
+    delta = Math.floor(delta / 60);
+    if (delta < 24) { // Hours.
+      return goog.date.relative.getMessage_(
+          delta, future, goog.date.relative.Unit_.HOURS);
+
+    } else {
+      // We can be more than 24 hours apart but still only 1 day apart, so we
+      // compare the closest time from today against the target time to find
+      // the number of days in the delta.
+      var midnight = new Date(goog.now());
+      midnight.setHours(0);
+      midnight.setMinutes(0);
+      midnight.setSeconds(0);
+      midnight.setMilliseconds(0);
+
+      // Convert to days ago.
+      delta = Math.ceil(
+          (midnight.getTime() - dateMs) / goog.date.relative.DAY_MS_);
+
+      if (future) {
+        delta *= -1;
+      }
+
+      // Uses days for less than 2-weeks.
+      if (delta < 14) {
+        return goog.date.relative.getMessage_(
+            delta, future, goog.date.relative.Unit_.DAYS);
+
+      } else {
+        // For messages older than 2 weeks do not show anything.  The client
+        // should decide the date format to show.
+        return '';
+      }
+    }
+  }
+};
+
+
+/**
+ * Accepts a timestamp in milliseconds and outputs a relative time in the form
+ * of "1 hour ago", "1 day ago".  All future times will be returned as 0 minutes
+ * ago.
+ *
+ * This is provided for compatibility with users of the previous incarnation of
+ * the above {@see #format} method who relied on it protecting against
+ * future dates.
+ *
+ * @param {number} dateMs Date in milliseconds.
+ * @return {string} The formatted date.
+ */
+goog.date.relative.formatPast = function(dateMs) {
+  var now = goog.now();
+  if (now < dateMs) {
+    dateMs = now;
+  }
+  return goog.date.relative.format(dateMs);
+};
+
+
+/**
+ * Accepts a timestamp in milliseconds and outputs a relative day. i.e. "Today",
+ * "Yesterday", "Tomorrow", or "Sept 15".
+ *
+ * @param {number} dateMs Date in milliseconds.
+ * @param {function(!Date):string=} opt_formatter Formatter for the date.
+ *     Defaults to form 'MMM dd'.
+ * @return {string} The formatted date.
+ */
+goog.date.relative.formatDay = function(dateMs, opt_formatter) {
+  var today = new Date(goog.now());
+
+  today.setHours(0);
+  today.setMinutes(0);
+  today.setSeconds(0);
+  today.setMilliseconds(0);
+
+  var yesterday = new Date(today.getTime() - goog.date.relative.DAY_MS_);
+  var tomorrow = new Date(today.getTime() + goog.date.relative.DAY_MS_);
+  var dayAfterTomorrow = new Date(today.getTime() +
+      2 * goog.date.relative.DAY_MS_);
+
+  var message;
+  if (dateMs >= tomorrow.getTime() && dateMs < dayAfterTomorrow.getTime()) {
+    /** @desc Tomorrow. */
+    var MSG_TOMORROW = goog.getMsg('Tomorrow');
+    message = MSG_TOMORROW;
+  } else if (dateMs >= today.getTime() && dateMs < tomorrow.getTime()) {
+    /** @desc Today. */
+    var MSG_TODAY = goog.getMsg('Today');
+    message = MSG_TODAY;
+  } else if (dateMs >= yesterday.getTime() && dateMs < today.getTime()) {
+    /** @desc Yesterday. */
+    var MSG_YESTERDAY = goog.getMsg('Yesterday');
+    message = MSG_YESTERDAY;
+  } else {
+    // If we don't have a special relative term for this date, then return the
+    // short date format (or a custom-formatted date).
+    var formatFunction = opt_formatter || goog.date.relative.formatMonth_;
+    message = formatFunction(new Date(dateMs));
+  }
+  return message;
+};
+
+
+/**
+ * Formats a date, adding the relative date in parenthesis.  If the date is less
+ * than 24 hours then the time will be printed, otherwise the full-date will be
+ * used.  Examples:
+ *   2:20 PM (1 minute ago)
+ *   Monday, February 27, 2009 (4 days ago)
+ *   Tuesday, March 20, 2005    // Too long ago for a relative date.
+ *
+ * @param {Date|goog.date.DateTime} date A date object.
+ * @param {string=} opt_shortTimeMsg An optional short time message can be
+ *     provided if available, so that it's not recalculated in this function.
+ * @param {string=} opt_fullDateMsg An optional date message can be
+ *     provided if available, so that it's not recalculated in this function.
+ * @return {string} The date string in the above form.
+ */
+goog.date.relative.getDateString = function(
+    date, opt_shortTimeMsg, opt_fullDateMsg) {
+  return goog.date.relative.getDateString_(
+      date, goog.date.relative.format, opt_shortTimeMsg, opt_fullDateMsg);
+};
+
+
+/**
+ * Formats a date, adding the relative date in parenthesis.   Functions the same
+ * as #getDateString but ensures that the date is always seen to be in the past.
+ * If the date is in the future, it will be shown as 0 minutes ago.
+ *
+ * This is provided for compatibility with users of the previous incarnation of
+ * the above {@see #getDateString} method who relied on it protecting against
+ * future dates.
+ *
+ * @param {Date|goog.date.DateTime} date A date object.
+ * @param {string=} opt_shortTimeMsg An optional short time message can be
+ *     provided if available, so that it's not recalculated in this function.
+ * @param {string=} opt_fullDateMsg An optional date message can be
+ *     provided if available, so that it's not recalculated in this function.
+ * @return {string} The date string in the above form.
+ */
+goog.date.relative.getPastDateString = function(
+    date, opt_shortTimeMsg, opt_fullDateMsg) {
+  return goog.date.relative.getDateString_(
+      date, goog.date.relative.formatPast, opt_shortTimeMsg, opt_fullDateMsg);
+};
+
+
+/**
+ * Formats a date, adding the relative date in parenthesis.  If the date is less
+ * than 24 hours then the time will be printed, otherwise the full-date will be
+ * used.  Examples:
+ *   2:20 PM (1 minute ago)
+ *   Monday, February 27, 2009 (4 days ago)
+ *   Tuesday, March 20, 2005    // Too long ago for a relative date.
+ *
+ * @param {Date|goog.date.DateTime} date A date object.
+ * @param {function(number) : string} relativeFormatter Function to use when
+ *     formatting the relative date.
+ * @param {string=} opt_shortTimeMsg An optional short time message can be
+ *     provided if available, so that it's not recalculated in this function.
+ * @param {string=} opt_fullDateMsg An optional date message can be
+ *     provided if available, so that it's not recalculated in this function.
+ * @return {string} The date string in the above form.
+ * @private
+ */
+goog.date.relative.getDateString_ = function(
+    date, relativeFormatter, opt_shortTimeMsg, opt_fullDateMsg) {
+  var dateMs = date.getTime();
+
+  var relativeDate = relativeFormatter(dateMs);
+
+  if (relativeDate) {
+    relativeDate = ' (' + relativeDate + ')';
+  }
+
+  var delta = Math.floor((goog.now() - dateMs) / goog.date.relative.MINUTE_MS_);
+  if (delta < 60 * 24) {
+    // TODO(user): this call raises an exception if date is a goog.date.Date.
+    return (opt_shortTimeMsg || goog.date.relative.formatShortTime_(date)) +
+        relativeDate;
+  } else {
+    return (opt_fullDateMsg || goog.date.relative.formatFullDate_(date)) +
+        relativeDate;
+  }
+};
+
+
+/*
+ * TODO(user):
+ *
+ * I think that this whole relative formatting should move to DateTimeFormat,
+ * make sure it treats plurals properly (now it does not), an so on.
+ * But we would have to wait for the next version of CLDR, which is cleaning
+ * the data for relative dates (even ICU has incomplete support for this).
+ *
+ * It also looks like this is not an object, and it does not save
+ * DateTimeSymbols at the time of creation, but uses the current value,
+ * whatever that is. So if one changes the global goog.i18n.DateTimeSymbols
+ * in between calls, then we get different results.
+ */
+/**
+ * Gets a localized relative date string for a given delta and unit.
+ * @param {number} delta Number of minutes/hours/days.
+ * @param {boolean} future Whether the delta is in the future.
+ * @param {goog.date.relative.Unit_} unit The units the delta is in.
+ * @return {string} The message.
+ * @private
+ */
+goog.date.relative.getMessage_ = function(delta, future, unit) {
+  // Convert to localized (native) digits
+  var localizedDelta =
+      goog.i18n.DateTimeFormat.prototype.localizeNumbers('' + delta);
+  if (!future && unit == goog.date.relative.Unit_.MINUTES) {
+    /**
+     * @desc Relative date indicating how many minutes ago something happened
+     * (singular).
+     */
+    var MSG_MINUTES_AGO_SINGULAR =
+        goog.getMsg('{$num} minute ago', {'num' : localizedDelta});
+
+    /**
+     * @desc Relative date indicating how many minutes ago something happened
+     * (plural).
+     */
+    var MSG_MINUTES_AGO_PLURAL =
+        goog.getMsg('{$num} minutes ago', {'num' : localizedDelta});
+
+    return delta == 1 ? MSG_MINUTES_AGO_SINGULAR : MSG_MINUTES_AGO_PLURAL;
+
+  } else if (future && unit == goog.date.relative.Unit_.MINUTES) {
+    /**
+     * @desc Relative date indicating in how many minutes something happens
+     * (singular).
+     */
+    var MSG_IN_MINUTES_SINGULAR =
+        goog.getMsg('in {$num} minute', {'num' : localizedDelta});
+
+    /**
+     * @desc Relative date indicating in how many minutes something happens
+     * (plural).
+     */
+    var MSG_IN_MINUTES_PLURAL =
+        goog.getMsg('in {$num} minutes', {'num' : localizedDelta});
+
+    return delta == 1 ? MSG_IN_MINUTES_SINGULAR : MSG_IN_MINUTES_PLURAL;
+
+  } else if (!future && unit == goog.date.relative.Unit_.HOURS) {
+    /**
+     * @desc Relative date indicating how many hours ago something happened
+     * (singular).
+     */
+    var MSG_HOURS_AGO_SINGULAR =
+        goog.getMsg('{$num} hour ago', {'num' : localizedDelta});
+
+    /**
+     * @desc Relative date indicating how many hours ago something happened
+     * (plural).
+     */
+    var MSG_HOURS_AGO_PLURAL =
+        goog.getMsg('{$num} hours ago', {'num' : localizedDelta});
+
+    return delta == 1 ? MSG_HOURS_AGO_SINGULAR : MSG_HOURS_AGO_PLURAL;
+
+  } else if (future && unit == goog.date.relative.Unit_.HOURS) {
+    /**
+     * @desc Relative date indicating in how many hours something happens
+     * (singular).
+     */
+    var MSG_IN_HOURS_SINGULAR =
+        goog.getMsg('in {$num} hour', {'num' : localizedDelta});
+
+    /**
+     * @desc Relative date indicating in how many hours something happens
+     * (plural).
+     */
+    var MSG_IN_HOURS_PLURAL =
+        goog.getMsg('in {$num} hours', {'num' : localizedDelta});
+
+    return delta == 1 ? MSG_IN_HOURS_SINGULAR : MSG_IN_HOURS_PLURAL;
+
+  } else if (!future && unit == goog.date.relative.Unit_.DAYS) {
+    /**
+     * @desc Relative date indicating how many days ago something happened
+     * (singular).
+     */
+    var MSG_DAYS_AGO_SINGULAR =
+        goog.getMsg('{$num} day ago', {'num' : localizedDelta});
+
+    /**
+     * @desc Relative date indicating how many days ago something happened
+     * (plural).
+     */
+    var MSG_DAYS_AGO_PLURAL =
+        goog.getMsg('{$num} days ago', {'num' : localizedDelta});
+
+    return delta == 1 ? MSG_DAYS_AGO_SINGULAR : MSG_DAYS_AGO_PLURAL;
+
+  } else if (future && unit == goog.date.relative.Unit_.DAYS) {
+    /**
+     * @desc Relative date indicating in how many days something happens
+     * (singular).
+     */
+    var MSG_IN_DAYS_SINGULAR =
+        goog.getMsg('in {$num} day', {'num' : localizedDelta});
+
+    /**
+     * @desc Relative date indicating in how many days something happens
+     * (plural).
+     */
+    var MSG_IN_DAYS_PLURAL =
+        goog.getMsg('in {$num} days', {'num' : localizedDelta});
+
+    return delta == 1 ? MSG_IN_DAYS_SINGULAR : MSG_IN_DAYS_PLURAL;
+
+  } else {
+    return '';
+  }
+};

nicer-api-docs/closure-library/closure/goog/date/utcdatetime.js

@@ -0,0 +1,179 @@
+// Copyright 2009 The Closure Library Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS-IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @fileoverview Locale independent date/time class.
+ *
+ */
+
+goog.provide('goog.date.UtcDateTime');
+
+goog.require('goog.date');
+goog.require('goog.date.Date');
+goog.require('goog.date.DateTime');
+goog.require('goog.date.Interval');
+
+
+
+/**
+ * Class representing a date/time in GMT+0 time zone, without daylight saving.
+ * Defaults to current date and time if none is specified. The get... and the
+ * getUTC... methods are equivalent.
+ *
+ * @param {number|Object=} opt_year Four digit UTC year or a date-like object.
+ *     If not set, the created object will contain the date determined by
+ *     goog.now().
+ * @param {number=} opt_month UTC month, 0 = Jan, 11 = Dec.
+ * @param {number=} opt_date UTC date of month, 1 - 31.
+ * @param {number=} opt_hours UTC hours, 0 - 23.
+ * @param {number=} opt_minutes UTC minutes, 0 - 59.
+ * @param {number=} opt_seconds UTC seconds, 0 - 59.
+ * @param {number=} opt_milliseconds UTC milliseconds, 0 - 999.
+ * @constructor
+ * @extends {goog.date.DateTime}
+ */
+goog.date.UtcDateTime = function(opt_year, opt_month, opt_date, opt_hours,
+                                 opt_minutes, opt_seconds, opt_milliseconds) {
+  var timestamp;
+  if (goog.isNumber(opt_year)) {
+    timestamp = Date.UTC(opt_year, opt_month || 0, opt_date || 1,
+                         opt_hours || 0, opt_minutes || 0, opt_seconds || 0,
+                         opt_milliseconds || 0);
+  } else {
+    timestamp = opt_year ? opt_year.getTime() : goog.now();
+  }
+  this.date_ = new Date(timestamp);
+};
+goog.inherits(goog.date.UtcDateTime, goog.date.DateTime);
+
+
+/**
+ * Creates a DateTime from a UTC datetime string expressed in ISO 8601 format.
+ *
+ * @param {string} formatted A date or datetime expressed in ISO 8601 format.
+ * @return {goog.date.UtcDateTime} Parsed date or null if parse fails.
+ */
+goog.date.UtcDateTime.fromIsoString = function(formatted) {
+  var ret = new goog.date.UtcDateTime(2000);
+  return goog.date.setIso8601DateTime(ret, formatted) ? ret : null;
+};
+
+
+/**
+ * Clones the UtcDateTime object.
+ *
+ * @return {!goog.date.UtcDateTime} A clone of the datetime object.
+ * @override
+ */
+goog.date.UtcDateTime.prototype.clone = function() {
+  var date = new goog.date.UtcDateTime(this.date_);
+  date.setFirstDayOfWeek(this.getFirstDayOfWeek());
+  date.setFirstWeekCutOffDay(this.getFirstWeekCutOffDay());
+  return date;
+};
+
+
+/** @override */
+goog.date.UtcDateTime.prototype.add = function(interval) {
+  if (interval.years || interval.months) {
+    var yearsMonths = new goog.date.Interval(interval.years, interval.months);
+    goog.date.Date.prototype.add.call(this, yearsMonths);
+  }
+  var daysAndTimeMillis = 1000 * (
+      interval.seconds + 60 * (
+          interval.minutes + 60 * (
+              interval.hours + 24 * interval.days)));
+  this.date_ = new Date(this.date_.getTime() + daysAndTimeMillis);
+};
+
+
+/** @override */
+goog.date.UtcDateTime.prototype.getTimezoneOffset = function() {
+  return 0;
+};
+
+
+/** @override */
+goog.date.UtcDateTime.prototype.getFullYear =
+    goog.date.DateTime.prototype.getUTCFullYear;
+
+
+/** @override */
+goog.date.UtcDateTime.prototype.getMonth =
+    goog.date.DateTime.prototype.getUTCMonth;
+
+
+/** @override */
+goog.date.UtcDateTime.prototype.getDate =
+    goog.date.DateTime.prototype.getUTCDate;
+
+
+/** @override */
+goog.date.UtcDateTime.prototype.getHours =
+    goog.date.DateTime.prototype.getUTCHours;
+
+
+/** @override */
+goog.date.UtcDateTime.prototype.getMinutes =
+    goog.date.DateTime.prototype.getUTCMinutes;
+
+
+/** @override */
+goog.date.UtcDateTime.prototype.getSeconds =
+    goog.date.DateTime.prototype.getUTCSeconds;
+
+
+/** @override */
+goog.date.UtcDateTime.prototype.getMilliseconds =
+    goog.date.DateTime.prototype.getUTCMilliseconds;
+
+
+/** @override */
+goog.date.UtcDateTime.prototype.getDay =
+    goog.date.DateTime.prototype.getUTCDay;
+
+
+/** @override */
+goog.date.UtcDateTime.prototype.setFullYear =
+    goog.date.DateTime.prototype.setUTCFullYear;
+
+
+/** @override */
+goog.date.UtcDateTime.prototype.setMonth =
+    goog.date.DateTime.prototype.setUTCMonth;
+
+
+/** @override */
+goog.date.UtcDateTime.prototype.setDate =
+    goog.date.DateTime.prototype.setUTCDate;
+
+
+/** @override */
+goog.date.UtcDateTime.prototype.setHours =
+    goog.date.DateTime.prototype.setUTCHours;
+
+
+/** @override */
+goog.date.UtcDateTime.prototype.setMinutes =
+    goog.date.DateTime.prototype.setUTCMinutes;
+
+
+/** @override */
+goog.date.UtcDateTime.prototype.setSeconds =
+    goog.date.DateTime.prototype.setUTCSeconds;
+
+
+/** @override */
+goog.date.UtcDateTime.prototype.setMilliseconds =
+    goog.date.DateTime.prototype.setUTCMilliseconds;