--- /dev/null
+# date #
+
+Date utilities.
+
+
+## dayOfTheYear(date):Number
+
+How many days elapsed since begining of the year (following gregorian
+calendar).
+
+```js
+// Jan 1st
+dayOfTheYear(new Date(2013, 0, 1)); // 1
+// Dec 31th
+dayOfTheYear(new Date(2013, 11, 31)); // 364
+```
+
+
+
+## diff(date1, date2, [unitName]):Number
+
+Calculate the difference between dates (range).
+
+The returned value is always positive. The default `unitName` is `"ms"`.
+
+Available units: `year`, `month`, `week`, `day`, `hour`, `minute`, `second`,
+`millisecond`.
+
+See: [`time/convert()`](time.html#convert)
+
+```js
+var d1 = new Date(2012, 4, 5);
+var d2 = new Date(2013, 4, 8);
+diff(d1, d2); // 31795200000
+diff(d1, d2, 'hour'); // 8832
+diff(d1, d2, 'week'); // 52.57142857142857
+diff(d1, d2, 'month'); // 12.096774193548388
+diff(d1, d2, 'year'); // 1.0082191780821919
+```
+
+
+
+## isLeapYear(fullYear|date):Boolean
+
+Checks if it's a [leap year](http://en.wikipedia.org/wiki/Leap_year) according
+to the Gregorian calendar.
+
+see: [`totalDaysInMonth()`](#totalDaysInMonth)
+
+```js
+isLeapYear(2012); // true
+isLeapYear(2013); // false
+isLeapYear(new Date(2012, 2, 28)); // true
+```
+
+
+## isSame(date1, date2[, period]):Boolean
+
+Check if both dates are the "same".
+
+You can pass an optional *period* used to set the comparisson precision.
+
+Available periods: `year`, `month`, `week`, `day`, `hour`, `minute`, `second`.
+
+```js
+var date1 = new Date(2013, 1, 3);
+var date2 = new Date(2013, 2, 9);
+isSame(date1, date2); // false
+isSame(date1, date2, 'day'); // false
+isSame(date1, date2, 'month'); // false
+isSame(date1, date2, 'year'); // true
+```
+
+
+
+## parseIso(str):Number
+
+Parses an [ISO8601](http://en.wikipedia.org/wiki/Iso8601) date and returns the
+number of milliseconds since January 1, 1970, 00:00:00 UTC, or `NaN` if it is
+not a valid ISO8601 date.
+
+This parses *all* ISO8601 dates, including dates without times, [ordinal
+dates](https://en.wikipedia.org/wiki/ISO_8601#Ordinal_dates), and the compact
+representation (omitting delimeters). The only exception is [ISO week
+dates](https://en.wikipedia.org/wiki/ISO_week_date), which are not parsed.
+
+If no time zone offset is specified, it assumes UTC time.
+
+```js
+// Jan 01, 1970 00:00 GMT
+parseIso('1970-01-01T00:00:00') // 0
+parseIso('1970-001') // 0
+parseIso('1970-01-01') // 0
+parseIso('19700101T000000.00') // 0
+parseIso('1970-01-01T02:00+02:00') // 0
+
+// Jan 02, 2000 20:10 GMT+04:00
+parseIso('2000-01-02T20:10+04:00') // 946829400000
+```
+
+
+## quarter(date):Number
+
+Get a number between 1 to 4 that represents the quarter of the year.
+
+```js
+quarter(new Date(2013, 1, 19)); // 1
+quarter(new Date(2013, 4, 12)); // 2
+quarter(new Date(2013, 7, 25)); // 3
+quarter(new Date(2013, 10, 8)); // 4
+```
+
+
+## startOf(date, period):Date
+
+Get a new Date at the start of the period.
+
+Available periods: `year`, `month`, `week`, `day`, `hour`, `minute`, `second`.
+
+```js
+// Apr 05 2013 11:27:43
+var date = new Date(2013, 3, 5, 11, 27, 43, 123);
+startOf(date, 'year'); // Jan 01 2013 00:00:00
+startOf(date, 'month'); // Apr 01 2013 00:00:00
+startOf(date, 'day'); // Apr 05 2013 00:00:00
+startOf(date, 'hour'); // Apr 05 2013 11:00:00
+```
+
+
+
+## strftime(date, format, [l10n]):String
+
+Format date based on strftime format.
+
+Replaced tokens:
+
+<dl>
+<dt>%a</dt><dd> locale's abbreviated weekday name.</dd>
+<dt>%A</dt><dd> locale's full weekday name.</dd>
+<dt>%b</dt><dd> locale's abbreviated month name.</dd>
+<dt>%B</dt><dd> locale's full month name.</dd>
+<dt>%c</dt><dd> locale's appropriate date and time representation.</dd>
+<dt>%C</dt><dd> century number (the year divided by 100 and truncated
+to an integer) as a decimal number [00..99].</dd>
+<dt>%d</dt><dd> day of the month as a decimal number [01..31].</dd>
+<dt>%D</dt><dd>same as %m/%d/%y.</dd>
+<dt>%e</dt><dd> day of the month as a decimal number [1..31];
+a single digit is preceded by a space.</dd>
+<dt>%F</dt><dd>The ISO 8601 date format (%Y-%m-%d)</dd>
+<dt>%h</dt><dd>same as %b.</dd>
+<dt>%H</dt><dd> hour (24-hour clock) as a decimal number [00..23].</dd>
+<dt>%I</dt><dd> hour (12-hour clock) as a decimal number [01..12].</dd>
+<dt>%j</dt><dd> day of the year as a decimal number [001..366].</dd>
+<dt>%l</dt><dd> hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank</dd>
+<dt>%L</dt><dd> zero-padded milliseconds [000..999]</dd>
+<dt>%m</dt><dd> month as a decimal number [01..12].</dd>
+<dt>%M</dt><dd> minute as a decimal number [00..59].</dd>
+<dt>%n</dt><dd> newline character.</dd>
+<dt>%p</dt><dd> locale's equivalent of either "am" or "pm"</dd>
+<dt>%P</dt><dd> locale's equivalent of either "AM" or "PM"</dd>
+<dt>%r</dt><dd> time in a.m. and
+p.m. notation; in the POSIX locale this is equivalent to %I:%M:%S %p.</dd>
+<dt>%R</dt><dd> time in 24 hour notation (%H:%M).</dd>
+<dt>%s</dt><dd> seconds since Epoch (1970-01-01 00:00:00 UTC)</dd>
+<dt>%S</dt><dd> second as a decimal number [00..60].</dd>
+<dt>%t</dt><dd> tab character.</dd>
+<dt>%T</dt><dd> time (%H:%M:%S).</dd>
+<dt>%u</dt><dd> weekday as a decimal number [1..7], with 1 representing
+Monday.</dd>
+<dt>%U</dt><dd> week number of the year (Sunday as the first day of
+the week) as a decimal number [00..53].</dd>
+<del><dt>%V</dt><dd> week number of the year (Monday as the first day of the
+week) as a decimal number [01..53]. If the week containing 1 January has
+four or more days in the new year, then it is considered week 1. Otherwise,
+it is the last week of the previous year, and the next week is week 1.</dd></del>
+<dt>%w</dt><dd> weekday as a decimal number [0..6], with 0 representing
+Sunday.</dd>
+<dt>%W</dt><dd> week number of the year (Monday as the first day of
+the week) as a decimal number [00..53]. All days in a new year preceding
+the first Monday are considered to be in week 0.</dd>
+<dt>%x</dt><dd> locale's appropriate date representation.</dd>
+<dt>%X</dt><dd> locale's appropriate time representation.</dd>
+<dt>%y</dt><dd> year without century as a decimal number [00..99].</dd>
+<dt>%Y</dt><dd> year with century as a decimal number.</dd>
+<dt>%Z</dt><dd> timezone name or abbreviation, or by no bytes
+if no timezone information exists.</dd>
+<dt>%%</dt><dd>is replaced by %.</dd>
+</dl>
+
+```js
+var date = new Date(2013, 3, 8, 9, 2, 4);
+strftime(date, '%Y-%m-%d'); // "2013-04-08"
+strftime(date, '%R'); // "09:02"
+strftime(date, '%Y-%m-%dT%H:%M:%S%z'); // "2013-04-08T09:02:04+0000"
+```
+
+You can also set a custom locale:
+
+```js
+var ptBr = require('mout/date/i18n/pt-BR');
+strftime(date, '%a, %d %b', ptBr); // 'Seg, 08 Abr'
+strftime(date, '%A, %d %B', ptBr); // 'Segunda, 08 Abril'
+```
+
+To set it globally:
+
+```js
+require('mout/date/i18n_').set( customLocaleData );
+```
+
+See [date/i18n](https://github.com/mout/mout/tree/master/src/date/i18n)
+for localization examples.
+
+
+
+## timezoneAbbr(date):String
+
+Return timezone abbreviation or similar data.
+
+The result will vary based on the OS/browser since some environments doesn't
+provide enough info about the current locale.
+
+```js
+// IE 7-8
+timezoneAbbr(new Date()); // "-0500"
+// Chrome, FF, V8
+timezoneAbbr(new Date()); // "EST"
+```
+
+
+
+## timezoneOffset(date):String
+
+Return time zone as hour and minute offset from UTC (e.g. +0900).
+
+It's important to note that JavaScript Date object will use the system locale
+info to determinate the [timezone
+offset](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Date/getTimezoneOffset)
+and that daylight saving time affects the result.
+
+```js
+// if system locale is EST
+timezoneOffset(new Date()); // -0500
+```
+
+
+
+## totalDaysInMonth(fullYear, monthIndex):Number
+
+Returns the amount of days in the month taking into consideration leap years
+(following Gregorian calendar).
+
+see: [`isLeapYear()`](#isLeapYear)
+
+```js
+totalDaysInMonth(2008, 1); // 29 (leap year)
+totalDaysInMonth(2009, 1); // 28
+
+// you can also pass a Date object as single argument
+totalDaysInMonth( new Date(2013, 0, 1) ); // 31
+```
+
+
+## totalDaysInYear(fullYear):Number
+
+Returns the amount of days in the year taking into consideration leap years
+(following Gregorian calendar).
+
+see: [`isLeapYear()`](#isLeapYear), [`totalDaysInMonth()`](#totalDaysInMonth)
+
+```js
+totalDaysInYear(2008); // 366 (leap year)
+totalDaysInYear(2009); // 365
+
+// you can also pass a Date object as single argument
+totalDaysInYear( new Date(2013, 0, 1) ); // 365
+```
+
+
+
+## weekOfTheYear(date, [firstDayOfWeek]):Number
+
+Returns how many weeks elapsed since start of the year (`0..53`).
+
+`firstDayOfWeek` can be `0` (Sunday) or `1` (Monday). By default weeks start at
+Sunday.
+
+It will return `0` if `date` is before the first `firstDayOfWeek` of the year.
+
+```js
+// Tue Jan 01 2013
+weekOfTheYear( new Date(2013,0,1) ); // 0
+// Wed Jan 09 2013
+weekOfTheYear( new Date(2013,0,9) ); // 1
+// Sun Jan 01 2012
+weekOfTheYear( new Date(2012,0,1) ); // 1
+// Mon Jan 09 2012
+weekOfTheYear( new Date(2012,0,9) ); // 2
+```
+
+
+
+-------------------------------------------------------------------------------
+
+For more usage examples check specs inside `/tests` folder. Unit tests are the
+best documentation you can get...
+