datetime-utils

build/gallery-datetime-utils/gallery-datetime-utils-debug.js

@@ -0,0 +1,331 @@
+YUI.add('gallery-datetime-utils', function(Y) {
+
+"use strict";
+
+/**
+ * @module gallery-datetime-utils
+ */
+
+/**********************************************************************
+ * Utility functions work working with dates and times.
+ * 
+ * @main gallery-datetime-utils
+ * @class DateTimeUtils
+ */
+
+function pad2(n)
+{
+	var s = n.toString();
+	if (s.length < 2)
+	{
+		s = '0' + s;
+	}
+	return s;
+}
+
+function validInteger(v)
+{
+	return /^\d+$/.test(v);
+}
+
+Y.DateTimeUtils =
+{
+	/**
+	 * Position of the year in a string representation of a date: 1,2,3
+	 *
+	 * @property YEAR_POSITION
+	 * @type {Number}
+	 * @default 1
+	 * @static
+	 */
+	YEAR_POSITION: 1,
+
+	/**
+	 * Position of the month in a string representation of a date: 1,2,3
+	 *
+	 * @property MONTH_POSITION
+	 * @type {Number}
+	 * @default 2
+	 * @static
+	 */
+	MONTH_POSITION: 2,
+
+	/**
+	 * Position of the day in a string representation of a date: 1,2,3
+	 *
+	 * @property DAY_POSITION
+	 * @type {Number}
+	 * @default 3
+	 * @static
+	 */
+	DAY_POSITION: 3,
+
+	/**
+	 * Delimiter of fields in a string representation of a date.
+	 *
+	 * @property DATE_FIELD_DELIMITER
+	 * @type {String}
+	 * @default "-"
+	 * @static
+	 */
+	DATE_FIELD_DELIMITER: '-',
+
+	/**
+	 * Delimiter of fields in a string representation of a time.
+	 *
+	 * @property TIME_FIELD_DELIMITER
+	 * @type {String}
+	 * @default ":"
+	 * @static
+	 */
+	TIME_FIELD_DELIMITER: ':',
+
+	/**
+	 * Antemeridian string.
+	 *
+	 * @property AM_STRING
+	 * @type {String}
+	 * @default "AM"
+	 * @static
+	 */
+	AM_STRING: 'AM',
+
+	/**
+	 * Postmeridian string.
+	 *
+	 * @property PM_STRING
+	 * @type {String}
+	 * @default "PM"
+	 * @static
+	 */
+	PM_STRING: 'PM',
+
+	/**
+	 * How hours should be displayed to the user by classes in the DateTime
+	 * family: 12hr or 24hr.  (Internal values are always 24hr.)  This is
+	 * global because your app should be consistent about how it displays
+	 * times.
+	 * 
+	 * @property CLOCK_DISPLAY_TYPE
+	 * @type {Number} 12 or 24
+	 * @default 24
+	 * @static
+	 */
+	CLOCK_DISPLAY_TYPE: 24,
+
+	/**
+	 * Normalizes the given object by converting date_str into
+	 * year,month,day, converting time_str into hour,minute (or adding in
+	 * hour,minute from default_time), and adding date (instanceof Date).
+	 * Individual fields take precedence over strings.
+	 * 
+	 * If input is a Date object, then the result contains a breakdown of
+	 * the values.
+	 * 
+	 * @method normalize
+	 * @static
+	 * @param input {Object}
+	 *	Can be specified either as instance of Date or as an object defining
+	 *	date_str or year,month,day and (optional) either time_str or
+	 *	hour,minute.
+	 * @param default_time {Object} Default hour and minute to use if input only has date.
+	 * @return {Object} normalized object defining date and time
+	 */
+	normalize: function(input, default_time)
+	{
+		if (input instanceof Date)
+		{
+			var result =
+			{
+				year:   input.getFullYear(),
+				month:  input.getMonth()+1,
+				day:    input.getDate(),
+				hour:   input.getHours(),
+				minute: input.getMinutes(),
+				date:   input
+			};
+			return result;
+		}
+
+		var result = Y.clone(input);
+		if (result.date_str)
+		{
+			if (Y.Lang.isUndefined(result.year) &&
+				Y.Lang.isUndefined(result.month) &&
+				Y.Lang.isUndefined(result.day))
+			{
+				Y.mix(result, self.parseDate(result.date_str));
+			}
+			delete result.date_str;
+		}
+
+		if (result.time_str)
+		{
+			if (Y.Lang.isUndefined(result.hour) &&
+				Y.Lang.isUndefined(result.minute))
+			{
+				Y.mix(result, self.parseTime(result.time_str));
+			}
+			delete result.time_str;
+		}
+		else if (Y.Lang.isUndefined(result.hour))
+		{
+			result.hour   = default_time.hour;
+			result.minute = default_time.minute;
+		}
+
+		result.date = new Date(result.year, result.month-1, result.day, result.hour, result.minute);
+		return result;
+	},
+
+	/**
+	 * Format the date portion of a Date object.
+	 * 
+	 * @method formatDate
+	 * @static
+	 * @param date {Mixed} string (returned as-is), Date, or object specifying day,month,year
+	 * @return {String} formatted date, using positions and delimiated
+	 */
+	formatDate: function(date)
+	{
+		if (!date)
+		{
+			return '';
+		}
+		else if (Y.Lang.isString(date))
+		{
+			return date;
+		}
+
+		var a = [];
+		if (date instanceof Date)
+		{
+			a[ self.YEAR_POSITION-1 ]  = date.getFullYear().toString();
+			a[ self.MONTH_POSITION-1 ] = pad2(date.getMonth()+1);
+			a[ self.DAY_POSITION-1 ]   = pad2(date.getDate());
+		}
+		else
+		{
+			a[ self.YEAR_POSITION-1 ]  = date.year.toString();
+			a[ self.MONTH_POSITION-1 ] = pad2(date.month);
+			a[ self.DAY_POSITION-1 ]   = pad2(date.day);
+		}
+
+		return a.join(self.DATE_FIELD_DELIMITER);
+	},
+
+	/**
+	 * Inverse of formatDate().  Extracts year, month, and day from the string.
+	 * 
+	 * @method parseDate
+	 * @static
+	 * @param date {String} string from DateTimeUtils.formatDate()
+	 * @return {Object} year,month,day
+	 */
+	parseDate: function(date)
+	{
+		if (!date)
+		{
+			return null;
+		}
+		else if (!Y.Lang.isString(date))
+		{
+			return date;
+		}
+
+		var d = date.split(self.DATE_FIELD_DELIMITER);
+		if (d.length != 3 || !Y.every(d, validInteger))
+		{
+			throw Error('Unparseable date format.');
+		}
+
+		var result =
+		{
+			year:  parseInt(d[ self.YEAR_POSITION-1 ], 10),
+			month: parseInt(d[ self.MONTH_POSITION-1 ], 10),
+			day:   parseInt(d[ self.DAY_POSITION-1 ], 10)
+		};
+		return result;
+	},
+
+	/**
+	 * Format the time portion of a Date object.
+	 * 
+	 * @method formatTime
+	 * @static
+	 * @param time {Mixed} string (returned as-is), Date, or object specifying hour,minute
+	 * @return {String} formatted date, using positions and delimiated
+	 */
+	formatTime: function(time)
+	{
+		if (!time)
+		{
+			return '';
+		}
+		else if (Y.Lang.isString(time))
+		{
+			return time;
+		}
+		else if (self.CLOCK_DISPLAY_TYPE == 12)
+		{
+			var s = self.TIME_FIELD_DELIMITER + pad2(time.minute) + ' ';
+			return (time.hour > 12 ?
+					(time.hour - 12) + s + self.PM_STRING :
+					time.hour + s + self.AM_STRING);
+		}
+		else
+		{
+			return time.hour + self.TIME_FIELD_DELIMITER + pad2(time.minute);
+		}
+	},
+
+	/**
+	 * Inverse of formatTime().  Extracts hour and minute from the string.
+	 * 
+	 * @method parseTime
+	 * @static
+	 * @param time {String} string from DateTimeUtils.formatTime()
+	 * @return {Object} hour,minute
+	 */
+	parseTime: function(
+		/* string */	time)
+	{
+		if (!time)
+		{
+			return null;
+		}
+		else if (!Y.Lang.isString(time))
+		{
+			return time;
+		}
+
+		var offset = 0;
+		if (time.indexOf(self.AM_STRING) > 0)
+		{
+			time = Y.Lang.trim(time.replace(self.AM_STRING, ''));
+		}
+		else if (time.indexOf(self.PM_STRING) > 0)
+		{
+			time   = Y.Lang.trim(time.replace(self.PM_STRING, ''));
+			offset = 12;
+		}
+
+		var t = time.split(self.TIME_FIELD_DELIMITER);
+		if (t.length != 2 || !Y.every(t, validInteger))
+		{
+			throw Error('Unparseable time format.');
+		}
+
+		var result =
+		{
+			hour:   parseInt(t[0], 10) + offset,
+			minute: parseInt(t[1], 10)
+		};
+		return result;
+	}
+};
+
+var self = Y.DateTimeUtils;	// shortcut
+
+
+}, '@VERSION@' ,{requires:['gallery-funcprog']});