{"_id":"useful-date","_rev":"26-5768641f73bd07db2db7afbe96d184cc","name":"useful-date","description":"useful date parsing and formatting library","dist-tags":{"latest":"0.0.6"},"versions":{"0.0.1":{"author":{"name":"constantology","email":"christos@muigui.com","url":"http://muigui.com"},"description":"useful date parsing and formatting library","dependencies":{"useful-type":"*","useful-util":"*"},"devDependencies":{"chai":"*","grunt":"*","grunt-contrib-concat":"*","mocha":"*"},"engines":{"node":">= 0.8.x"},"keywords":["date"],"licenses":[{"type":"MIT","url":"https://raw.github.com/muigui/useful-date/master/LICENSE"}],"main":"./index.js","name":"useful-date","repository":{"type":"git","url":"git@github.com:muigui/useful-date.git"},"scripts":{"test":"mocha -c --ignore-leaks -R spec -u tdd ./test/runner.js"},"version":"0.0.1","readme":"\n# useful-date\n\n useful date parsing and formatting library.\n\n useful-date extends the `Date` and `Date.prototype` using `Object.defineProperty` — it **will not** create new enumerable methods and properties and it will not over-write any existing methods.\n\n## Installation\n\n Install with [component(1)](http://component.io):\n\n $ component install muigui/useful-date\n\n Install with npm:\n\n $ npm install useful-date\n\n\n## API\n\n### Static methods\n\n#### isLeapYear( year:String ):Boolean\nReturns true if the passed **4 digit** year is a leap year.\n\n**NOTE:** This method is located in the locale file. If your calendar system does not contain leap years, you can simply change the method to only `return false`.\n\n#### getOrdinal( date:Number ):String\nReturns the ordinal for a given date.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n Date.getOrdinal( 1 ); // returns => \"st\"\n Date.getOrdinal( 10 ); // returns => \"th\"\n Date.getOrdinal( 22 ); // returns => \"nd\"\n Date.getOrdinal( 33 ); // returns => \"rd\"\n\n```\n\n**NOTE:** Ordinals and the `getOrdinal` This method is located in the locale file. You can simply change the `ordinal` Array to your specific language; overwrite the `getOrdinal` method or both.\n\n#### setLeapYear( date:Date ):Void\nSets the inlcuded locale's February day count to the correct number of days, based on whether or not the date is a leap year or not.\n\n**NOTE:** This method is located in the locale file. If your calendar system does not contain leap years, you can simply change the method to do nothing.\n\n#### coerce( date:String, format:String ):Date\nTakes a date String and a format String based on the **Date formatting and parsing options** described below and returns a – hopefully – correct and valid Date.\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n Date.coerce( 'Sunday, the 1st of January 2012', 'l, jS F Y' ); // returns => Date { Sun Jan 01 2012 00:00:00 GMT+0000 (GMT) }\n Date.coerce( '2012-01-01T00:00:00+00:00', Date.formats.ISO_8601 ); // returns => Date { Sun Jan 01 2012 00:00:00 GMT+0000 (GMT) }\n\n```\n\n### Static properties\n\n#### filters\nAn Object of all the available filters for formatting a Date.\n\n**IMPORTANT: Don't change these unless you know what you are doing!**\n\n#### formats\nAn Object containing some default date formats:\n\n\t\n\t\n\t\n\t\n\t\n
ISO_8601Y-m-dH:i:sP
ISO_8601_SHORTY-m-d
RFC_850l, d-M-y H:i:s T
RFC_2822D, d M Y H:i:s O
sortableY-m-d H:i:sO
\n\n### Instance methods\n\n#### adjust( interval:Object|String[, value:Number] ):Date\nYour one stop shop for all Date arithmetic. Adjusts the Date based on the passed `interval`, by the passed numeric `value`.\n\n**Note:** The method also accepts a single Object param where each key is the interval and each value is the number to adjust the Date by.\n\n**Valid intervals are:** year, month, week, day, hr, min, sec, ms.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n var date = new Date( 2012, 0, 1 ); // Date {Sun Jan 01 2012 00:00:00 GMT+0000 (GMT)}\n\n date.adjust( Date.DAY, 1 ); // Date {Mon Jan 02 2012 00:00:00 GMT+0000 (GMT)}\n date.adjust( Date.HOUR, -1 ); // Date {Sun Jan 01 2012 23:00:00 GMT+0000 (GMT)}\n date.adjust( {\n year : -1, month : -1, day : 24,\n hr : 1, sec : -1\n } ); // Date {Sat Dec 25 2010 23:59:59 GMT+0000 (GMT)}\n\n```\n\n#### between( date_lower:Date, date_higher:Date ):Boolean\nChecks to see if the Date instance is in between the two passed Dates.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n var date = new Date( 2012, 0, 1 );\n\n date.between( new Date( 2011, 0, 1 ), new Date( 2013, 0, 1 ) ); // returns => true;\n\n date.between( new Date( 2013, 0, 1 ), new Date( 2011, 0, 1 ) ); // returns => false;\n\n```\n\n#### clearTime():Date\nClears the time from the Date instance.\n\n#### clone():Date\nReturns a clone of the current Date.\n\n#### diff( [date:Date, exclude:String] ):Object\nReturns an Object describing the difference between the Date instance and now — or the optionally passed Date.\n\nThe Object will contain any or all of the following properties:\n\n\n\t\n\t\t\n\t\n\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\n
PropTypeDescription
tenseNumberThis will either be:\n\t\t\t
\n\t\t\t\t
-1
The Date instance is less than now or the passed Date, i.e. in the past
\n\t\t\t\t
0
The Date instance is equal to now or the passed Date, i.e. in the present.
NOTE: If tense is 0 then the Object will most probably have no other properties, except value, which will be zero.
\n\t\t\t\t
1
The Date instance is greater than now or the passed Date, i.e. in the future
\n\t\t\t
\n\t\t\tNOTE: To make the diff Object's values easier to work with all other properties will be positive Numbers. You should use the tense property as your reference for the diff being in the past, present or future.\n\t\t
valueNumberThe — absolute — number of milliseconds difference between the two Dates.
yearsNumberThe number of years the Date instance is ahead or behind the passed Date.
monthsNumberThe months of years the Date instance is ahead or behind the passed Date.
weeksNumberThe weeks of years the Date instance is ahead or behind the passed Date.
daysNumberThe days of years the Date instance is ahead or behind the passed Date.
hoursNumberThe hours of years the Date instance is ahead or behind the passed Date.
minutesNumberThe minutes of years the Date instance is ahead or behind the passed Date.
secondsNumberThe seconds of years the Date instance is ahead or behind the passed Date.
millisecondsNumberThe milliseconds of years the Date instance is ahead or behind the passed Date.
\n\n**NOTE:** If any property — other than `tense` & `value` — is zero it will be omitted from the `diff` Object.\n\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 1 ) ) // returns => { tense : 0 }\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 2 ) ) // returns => { tense : -1, value : 86400000, days : 1 }\n\n ( new Date( 2012, 0, 2 ) ).diff( new Date( 2012, 0, 1 ) ) // returns => { tense : 1, value : 86400000, days : 1 }\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2010, 9, 8, 7, 6, 5, 4 ) ) // returns => { tense : 1, value : 38858034996, years : 1, months : 2, weeks : 3, days : 3, hours : 17, minutes : 53, seconds : 54, ms : 995 }\n\n```\n\n**NOTE:** You can supply a **space delimited** String defining which properties you want to exclude from the result and `diff` will either pass the current calculation to the next time unit or, if there are none will round off — up if over .5 or down if less, uses `Math.round` to figure this out — to the previous time unit.\n\nExclusion codes:\n- `-` will exclude the time unit from the `diff` Object.\n- `+` will include the time unit in the `diff` Object. **Note:** this is the same as not including the time unit in the `exclusions` String.\n- `>` will exclude all time units from this time unit down from the `diff` Object.\n\n##### Example with exclusions:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 2 ), '-days' ) // returns => { tense : -1, value : 86400000, hours : 24 }\n\n ( new Date( 2012, 0, 2 ) ).diff( new Date( 2012, 0, 1 ), '-days' ) // returns => { tense : 1, value : 86400000, hours : 24 }\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2010, 9, 8, 7, 6, 5, 4 ), '-years -weeks >minutes' ) // returns => { tense : 1, value : 38858034996, months : 14, days : 29, hours : 18 }\n\n```\n\n#### format( format:String ):String\nReturns a string representation of the Date instance, based on the passed format. See the [Date formatting and parsing options](#date-formatting-and-parsing-options) below.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).format( 'c' ); // returns => \"2012-01-01T00:00:00.000Z\"\n // which is a short hand format for:\n ( new Date( 2012, 0, 1 ) ).format( 'Y-m-dH:i:s.u' ); // returns => \"2012-01-01T00:00:00.000Z\"\n\n ( new Date( 2012, 0, 1 ) ).format( 'l, nS F Y' ) // returns => \"Sunday, the 1st of January 2012\"\n\n```\n\nYou can use predefined formats found in `Date.formats`. **Hint:** You can do:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n console.dir( Date.formats );\n\n```\n\nwithin your browser's JavaScript console to see a list of available formats.\n\nPreviously used formats are also cached to save the overhead of having to create a `new Function` everytime you want to format a date.\n\n#### getDayOfYear():Number\nReturns the zero based day of the year.\n\n#### getFirstOfTheMonth():Date\nReturns a Date instance of the first day of this Date instance's month.\n\n#### getGMTOffset( [colon:Boolean] ):String\nReturns the Date instances offset from GMT.\n\n#### getISODay():Number\nReturns the ISO day of the week.\n\n#### getISODaysInYear():Number\nReturns the ISO number of days in the year.\n\n#### getISOFirstMondayOfYear():Date\nReturns the ISO first Monday of the year.\n\n#### getISOWeek():Number\nReturns the ISO week of the year\n\n#### getISOWeeksInYear():Number\nReturns the number of weeks in the ISO year.\n\n#### getLastOfTheMonth():Date\nReturns a Date instance of the last day of this Date instance's month.\n\n#### getWeek():Number\nReturns the week of the year, based on the `dayOfYear` divided by 7.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).getWeek(); // returns => 0\n ( new Date( 2012, 2, 13 ) ).getWeek(); // returns => 10\n ( new Date( 2012, 11, 31 ) ).getWeek(); // returns => 52\n\n```\n\n#### isDST():Boolean\nReturns true if the Date instance is within daylight savings time.\n\n#### isLeapYear():Boolean\nReturns true if the Date instance is a leap year.\n\n#### lexicalize( [now:Date, format:String] ):String\nReturns a String representation of the difference between the date instance and now, or the passed `Date`.\n\n#### Available formats\nThe default format is `approx`, however this can be over-written by changing the **locale** file and/ or by passing in the desired format to the method.\n\n\n\t\n\t\n
approxWill return an approximate difference. e.g. about 2 days ago; almost 1 and a half years from now.
exactWill return the exact difference, e.g. 2 days 3 hours and 5 minutes ago; 1 year, 4 months, 2 weeks, 1 day, 5 hours, 3 minutes and 7 seconds from now.
\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n\tvar date = new Date( 2012, 0, 1 );\n\n\tdate.clone().adjust( { hr : -3, day : -2 } ).lexicalize( date, 'approx' ); // returns => \"just over 2 days ago\"\n\tdate.clone().adjust( { hr : -3, day : -2 } ).lexicalize( date, 'exact' ); // returns => \"2 days and 3 hours ago\"\n\n\tdate.lexicalize( date.clone().adjust( { hr : -6, day : -2 } ), 'approx' ); // returns => \"almost 2 and a half days from now\"\n\tdate.lexicalize( date.clone().adjust( { hr : -6, day : -2 } ), 'exact' ); // returns => \"2 days and 6 hours from now\"\n\n```\n\n#### setWeek():Number(UnixTimeStamp)\nSets the week of the year from the 1st January.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n new Date( ( new Date( 2012, 0, 1 ) ).setWeek( 17 ) ); // returns => Date {Sun Apr 29 2012 00:00:00 GMT+0100 (BST)}\n\n ( new Date( 2012, 2, 13 ) ).setWeek( 17 ); // returns => 1335654000000 same as above\n\n ( new Date( 2012, 11, 31 ) ).setWeek( 17 ); // returns => 1335654000000\n\n```\n\n#### timezone():String\nReturns the JavaScript engine's Date.prototype.toString() timezone abbreviation.\n\n## Date formatting and parsing options\n\n### escaping characters\n\nIf you want to escape characters that are used by the Date parser you can wrap them between <>.\n\n#### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).format( 'l, jS F Y' ); // returns => \"Sunday, the 1st of January 2012\"\n\n```\n\n### day\n\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n
dDay of the month, 2 digits with leading zeros
DA textual representation of a day, three letters
jDay of the month without leading zeros
lA full textual representation of the day of the week
NISO-8601 numeric representation of the day of the week
SEnglish ordinal suffix for the day of the month, 2 characters
wNumeric representation of the day of the week
zThe day of the year (starting from 0)
\n### week\n\n\t\n
WISO-8601 week number of year, weeks starting on Monday
\n### month\n\n\t\n\t\n\t\n\t\n\t\n
FA full textual representation of a month
mNumeric representation of a month, with leading zeros
MA short textual representation of a month, three letters
nNumeric representation of a month, without leading zeros
tNumber of days in the given month
\n### year\n\n\t\n\t\n\t\n\t\n
LWhether it's a leap year
oISO-8601 year number. This has the same value as Y, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead.
YA full numeric representation of a year, 4 digits
yA two digit representation of a year
\n### time\n\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n
aLowercase Ante meridiem and Post meridiem
AUppercase Ante meridiem and Post meridiem
g12-hour format of an hour without leading zeros
G24-hour format of an hour without leading zeros
h12-hour format of an hour with leading zeros
H24-hour format of an hour with leading zeros
iMinutes with leading zeros
sSeconds, with leading zeros
uMilliseconds
\n### timezone\n\n\t\n\t\n\t\n\t\n
ODifference to Greenwich time (GMT) in hours
PDifference to Greenwich time (GMT) with colon between hours and minutes
TTimezone abbreviation
ZTimezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive.
\n### full date/time\n\n\t\n\t\n\t\n
cISO 8601 date
rRFC 2822 formatted date
USeconds since the Unix Epoch January 1 1970 00:00:00 GMT
\n### custom\n\n\t\n\t\n
ethis is a convenience for `date.lexicalize( 'exact' );`
xthis is a convenience for `date.lexicalize( 'approx' );`
\n\n## License\n\n(The MIT License)\n\nCopyright (c) 2011 christos \"constantology\" constandinou http://muigui.com\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n","readmeFilename":"Readme.md","bugs":{"url":"https://github.com/muigui/useful-date/issues"},"_id":"useful-date@0.0.1","dist":{"shasum":"397d42a969ea43c1e5ebfb2eeba946d075121488","tarball":"https://registry.npmjs.org/useful-date/-/useful-date-0.0.1.tgz","integrity":"sha512-tPCXytTE5/BONoYdfYIjako8ufmpgR9PmEpa7+SlKvIKSmCWL+Qy4IlVpOS+RgjfLYWd72UDG4AYVSRNrXsh8w==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCeSlrkevasC3FlHVhz89nUjL/0ESz3yhn0ZIpcchBQSgIhAObFUYecEYoq6PYU5JrAxmWhedPIN+ZYeYbKJlqPj/L9"}]},"_from":".","_npmVersion":"1.3.8","_npmUser":{"name":"constantology","email":"constantology@gmail.com"},"maintainers":[{"name":"constantology","email":"constantology@gmail.com"}]},"0.0.2":{"author":{"name":"constantology","email":"christos@muigui.com","url":"http://muigui.com"},"description":"useful date parsing and formatting library","dependencies":{"useful-type":"latest","useful-util":"latest"},"devDependencies":{"chai":"latest","grunt":"latest","grunt-contrib-concat":"latest","mocha":"latest"},"engines":{"node":">= 0.8.x"},"keywords":["date"],"licenses":[{"type":"MIT","url":"https://raw.github.com/muigui/useful-date/master/LICENSE"}],"main":"./index.js","name":"useful-date","repository":{"type":"git","url":"git@github.com:muigui/useful-date.git"},"scripts":{"test":"mocha -c --ignore-leaks -R spec -u tdd ./test/runner.js"},"version":"0.0.2","readme":"\n# useful-date\n\n useful date parsing and formatting library.\n\n useful-date extends the `Date` and `Date.prototype` using `Object.defineProperty` — it **will not** create new enumerable methods and properties and it will not over-write any existing methods.\n\n## Installation\n\n Install with [component(1)](http://component.io):\n\n $ component install muigui/useful-date\n\n Install with npm:\n\n $ npm install useful-date\n\n\n## API\n\n### Static methods\n\n#### isLeapYear( year:String ):Boolean\nReturns true if the passed **4 digit** year is a leap year.\n\n**NOTE:** This method is located in the locale file. If your calendar system does not contain leap years, you can simply change the method to only `return false`.\n\n#### getOrdinal( date:Number ):String\nReturns the ordinal for a given date.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n Date.getOrdinal( 1 ); // returns => \"st\"\n Date.getOrdinal( 10 ); // returns => \"th\"\n Date.getOrdinal( 22 ); // returns => \"nd\"\n Date.getOrdinal( 33 ); // returns => \"rd\"\n\n```\n\n**NOTE:** Ordinals and the `getOrdinal` This method is located in the locale file. You can simply change the `ordinal` Array to your specific language; overwrite the `getOrdinal` method or both.\n\n#### setLeapYear( date:Date ):Void\nSets the inlcuded locale's February day count to the correct number of days, based on whether or not the date is a leap year or not.\n\n**NOTE:** This method is located in the locale file. If your calendar system does not contain leap years, you can simply change the method to do nothing.\n\n#### coerce( date:String, format:String ):Date\nTakes a date String and a format String based on the **Date formatting and parsing options** described below and returns a – hopefully – correct and valid Date.\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n Date.coerce( 'Sunday, the 1st of January 2012', 'l, jS F Y' ); // returns => Date { Sun Jan 01 2012 00:00:00 GMT+0000 (GMT) }\n Date.coerce( '2012-01-01T00:00:00+00:00', Date.formats.ISO_8601 ); // returns => Date { Sun Jan 01 2012 00:00:00 GMT+0000 (GMT) }\n\n```\n\n### Static properties\n\n#### filters\nAn Object of all the available filters for formatting a Date.\n\n**IMPORTANT: Don't change these unless you know what you are doing!**\n\n#### formats\nAn Object containing some default date formats:\n\n\t\n\t\n\t\n\t\n\t\n
ISO_8601Y-m-dH:i:sP
ISO_8601_SHORTY-m-d
RFC_850l, d-M-y H:i:s T
RFC_2822D, d M Y H:i:s O
sortableY-m-d H:i:sO
\n\n### Instance methods\n\n#### adjust( interval:Object|String[, value:Number] ):Date\nYour one stop shop for all Date arithmetic. Adjusts the Date based on the passed `interval`, by the passed numeric `value`.\n\n**Note:** The method also accepts a single Object param where each key is the interval and each value is the number to adjust the Date by.\n\n**Valid intervals are:** year, month, week, day, hr, min, sec, ms.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n var date = new Date( 2012, 0, 1 ); // Date {Sun Jan 01 2012 00:00:00 GMT+0000 (GMT)}\n\n date.adjust( Date.DAY, 1 ); // Date {Mon Jan 02 2012 00:00:00 GMT+0000 (GMT)}\n date.adjust( Date.HOUR, -1 ); // Date {Sun Jan 01 2012 23:00:00 GMT+0000 (GMT)}\n date.adjust( {\n year : -1, month : -1, day : 24,\n hr : 1, sec : -1\n } ); // Date {Sat Dec 25 2010 23:59:59 GMT+0000 (GMT)}\n\n```\n\n#### between( date_lower:Date, date_higher:Date ):Boolean\nChecks to see if the Date instance is in between the two passed Dates.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n var date = new Date( 2012, 0, 1 );\n\n date.between( new Date( 2011, 0, 1 ), new Date( 2013, 0, 1 ) ); // returns => true;\n\n date.between( new Date( 2013, 0, 1 ), new Date( 2011, 0, 1 ) ); // returns => false;\n\n```\n\n#### clearTime():Date\nClears the time from the Date instance.\n\n#### clone():Date\nReturns a clone of the current Date.\n\n#### diff( [date:Date, exclude:String] ):Object\nReturns an Object describing the difference between the Date instance and now — or the optionally passed Date.\n\nThe Object will contain any or all of the following properties:\n\n\n\t\n\t\t\n\t\n\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\n
PropTypeDescription
tenseNumberThis will either be:\n\t\t\t
\n\t\t\t\t
-1
The Date instance is less than now or the passed Date, i.e. in the past
\n\t\t\t\t
0
The Date instance is equal to now or the passed Date, i.e. in the present.
NOTE: If tense is 0 then the Object will most probably have no other properties, except value, which will be zero.
\n\t\t\t\t
1
The Date instance is greater than now or the passed Date, i.e. in the future
\n\t\t\t
\n\t\t\tNOTE: To make the diff Object's values easier to work with all other properties will be positive Numbers. You should use the tense property as your reference for the diff being in the past, present or future.\n\t\t
valueNumberThe — absolute — number of milliseconds difference between the two Dates.
yearsNumberThe number of years the Date instance is ahead or behind the passed Date.
monthsNumberThe months of years the Date instance is ahead or behind the passed Date.
weeksNumberThe weeks of years the Date instance is ahead or behind the passed Date.
daysNumberThe days of years the Date instance is ahead or behind the passed Date.
hoursNumberThe hours of years the Date instance is ahead or behind the passed Date.
minutesNumberThe minutes of years the Date instance is ahead or behind the passed Date.
secondsNumberThe seconds of years the Date instance is ahead or behind the passed Date.
millisecondsNumberThe milliseconds of years the Date instance is ahead or behind the passed Date.
\n\n**NOTE:** If any property — other than `tense` & `value` — is zero it will be omitted from the `diff` Object.\n\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 1 ) ) // returns => { tense : 0 }\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 2 ) ) // returns => { tense : -1, value : 86400000, days : 1 }\n\n ( new Date( 2012, 0, 2 ) ).diff( new Date( 2012, 0, 1 ) ) // returns => { tense : 1, value : 86400000, days : 1 }\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2010, 9, 8, 7, 6, 5, 4 ) ) // returns => { tense : 1, value : 38858034996, years : 1, months : 2, weeks : 3, days : 3, hours : 17, minutes : 53, seconds : 54, ms : 995 }\n\n```\n\n**NOTE:** You can supply a **space delimited** String defining which properties you want to exclude from the result and `diff` will either pass the current calculation to the next time unit or, if there are none will round off — up if over .5 or down if less, uses `Math.round` to figure this out — to the previous time unit.\n\nExclusion codes:\n- `-` will exclude the time unit from the `diff` Object.\n- `+` will include the time unit in the `diff` Object. **Note:** this is the same as not including the time unit in the `exclusions` String.\n- `>` will exclude all time units from this time unit down from the `diff` Object.\n\n##### Example with exclusions:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 2 ), '-days' ) // returns => { tense : -1, value : 86400000, hours : 24 }\n\n ( new Date( 2012, 0, 2 ) ).diff( new Date( 2012, 0, 1 ), '-days' ) // returns => { tense : 1, value : 86400000, hours : 24 }\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2010, 9, 8, 7, 6, 5, 4 ), '-years -weeks >minutes' ) // returns => { tense : 1, value : 38858034996, months : 14, days : 29, hours : 18 }\n\n```\n\n#### format( format:String ):String\nReturns a string representation of the Date instance, based on the passed format. See the [Date formatting and parsing options](#date-formatting-and-parsing-options) below.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).format( 'c' ); // returns => \"2012-01-01T00:00:00.000Z\"\n // which is a short hand format for:\n ( new Date( 2012, 0, 1 ) ).format( 'Y-m-dH:i:s.u' ); // returns => \"2012-01-01T00:00:00.000Z\"\n\n ( new Date( 2012, 0, 1 ) ).format( 'l, nS F Y' ) // returns => \"Sunday, the 1st of January 2012\"\n\n```\n\nYou can use predefined formats found in `Date.formats`. **Hint:** You can do:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n console.dir( Date.formats );\n\n```\n\nwithin your browser's JavaScript console to see a list of available formats.\n\nPreviously used formats are also cached to save the overhead of having to create a `new Function` everytime you want to format a date.\n\n#### getDayOfYear():Number\nReturns the zero based day of the year.\n\n#### getFirstOfTheMonth():Date\nReturns a Date instance of the first day of this Date instance's month.\n\n#### getGMTOffset( [colon:Boolean] ):String\nReturns the Date instances offset from GMT.\n\n#### getISODay():Number\nReturns the ISO day of the week.\n\n#### getISODaysInYear():Number\nReturns the ISO number of days in the year.\n\n#### getISOFirstMondayOfYear():Date\nReturns the ISO first Monday of the year.\n\n#### getISOWeek():Number\nReturns the ISO week of the year\n\n#### getISOWeeksInYear():Number\nReturns the number of weeks in the ISO year.\n\n#### getLastOfTheMonth():Date\nReturns a Date instance of the last day of this Date instance's month.\n\n#### getWeek():Number\nReturns the week of the year, based on the `dayOfYear` divided by 7.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).getWeek(); // returns => 0\n ( new Date( 2012, 2, 13 ) ).getWeek(); // returns => 10\n ( new Date( 2012, 11, 31 ) ).getWeek(); // returns => 52\n\n```\n\n#### isDST():Boolean\nReturns true if the Date instance is within daylight savings time.\n\n#### isLeapYear():Boolean\nReturns true if the Date instance is a leap year.\n\n#### lexicalize( [now:Date, format:String] ):String\nReturns a String representation of the difference between the date instance and now, or the passed `Date`.\n\n#### Available formats\nThe default format is `approx`, however this can be over-written by changing the **locale** file and/ or by passing in the desired format to the method.\n\n\n\t\n\t\n
approxWill return an approximate difference. e.g. about 2 days ago; almost 1 and a half years from now.
exactWill return the exact difference, e.g. 2 days 3 hours and 5 minutes ago; 1 year, 4 months, 2 weeks, 1 day, 5 hours, 3 minutes and 7 seconds from now.
\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n\tvar date = new Date( 2012, 0, 1 );\n\n\tdate.clone().adjust( { hr : -3, day : -2 } ).lexicalize( date, 'approx' ); // returns => \"just over 2 days ago\"\n\tdate.clone().adjust( { hr : -3, day : -2 } ).lexicalize( date, 'exact' ); // returns => \"2 days and 3 hours ago\"\n\n\tdate.lexicalize( date.clone().adjust( { hr : -6, day : -2 } ), 'approx' ); // returns => \"almost 2 and a half days from now\"\n\tdate.lexicalize( date.clone().adjust( { hr : -6, day : -2 } ), 'exact' ); // returns => \"2 days and 6 hours from now\"\n\n```\n\n#### setWeek():Number(UnixTimeStamp)\nSets the week of the year from the 1st January.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n new Date( ( new Date( 2012, 0, 1 ) ).setWeek( 17 ) ); // returns => Date {Sun Apr 29 2012 00:00:00 GMT+0100 (BST)}\n\n ( new Date( 2012, 2, 13 ) ).setWeek( 17 ); // returns => 1335654000000 same as above\n\n ( new Date( 2012, 11, 31 ) ).setWeek( 17 ); // returns => 1335654000000\n\n```\n\n#### timezone():String\nReturns the JavaScript engine's Date.prototype.toString() timezone abbreviation.\n\n## Date formatting and parsing options\n\n### escaping characters\n\nIf you want to escape characters that are used by the Date parser you can wrap them between <>.\n\n#### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).format( 'l, jS F Y' ); // returns => \"Sunday, the 1st of January 2012\"\n\n```\n\n### day\n\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n
dDay of the month, 2 digits with leading zeros
DA textual representation of a day, three letters
jDay of the month without leading zeros
lA full textual representation of the day of the week
NISO-8601 numeric representation of the day of the week
SEnglish ordinal suffix for the day of the month, 2 characters
wNumeric representation of the day of the week
zThe day of the year (starting from 0)
\n### week\n\n\t\n
WISO-8601 week number of year, weeks starting on Monday
\n### month\n\n\t\n\t\n\t\n\t\n\t\n
FA full textual representation of a month
mNumeric representation of a month, with leading zeros
MA short textual representation of a month, three letters
nNumeric representation of a month, without leading zeros
tNumber of days in the given month
\n### year\n\n\t\n\t\n\t\n\t\n
LWhether it's a leap year
oISO-8601 year number. This has the same value as Y, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead.
YA full numeric representation of a year, 4 digits
yA two digit representation of a year
\n### time\n\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n
aLowercase Ante meridiem and Post meridiem
AUppercase Ante meridiem and Post meridiem
g12-hour format of an hour without leading zeros
G24-hour format of an hour without leading zeros
h12-hour format of an hour with leading zeros
H24-hour format of an hour with leading zeros
iMinutes with leading zeros
sSeconds, with leading zeros
uMilliseconds
\n### timezone\n\n\t\n\t\n\t\n\t\n
ODifference to Greenwich time (GMT) in hours
PDifference to Greenwich time (GMT) with colon between hours and minutes
TTimezone abbreviation
ZTimezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive.
\n### full date/time\n\n\t\n\t\n\t\n
cISO 8601 date
rRFC 2822 formatted date
USeconds since the Unix Epoch January 1 1970 00:00:00 GMT
\n### custom\n\n\t\n\t\n
ethis is a convenience for `date.lexicalize( 'exact' );`
xthis is a convenience for `date.lexicalize( 'approx' );`
\n\n## License\n\n(The MIT License)\n\nCopyright (c) 2011 christos \"constantology\" constandinou http://muigui.com\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n","readmeFilename":"Readme.md","bugs":{"url":"https://github.com/muigui/useful-date/issues"},"_id":"useful-date@0.0.2","dist":{"shasum":"46b4a3897665385420a4f84afbceb02d73d0e1a2","tarball":"https://registry.npmjs.org/useful-date/-/useful-date-0.0.2.tgz","integrity":"sha512-9FO7g2iT/bzBxpaGazTNMgBQ6d4VbTvi9VdpOn4hjiCqke8X0+NWrs/xvDoDIm/KeWPyHmweVm1tYwdxV11xcw==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIGL2SlujeIK394xtR4EMWfNAEm/x/DxQld1/VV9kiTugAiAniQiq7iZ1THmuJfXx3vdjGCRq+sKpIY1327eI2reNMA=="}]},"_from":".","_npmVersion":"1.3.8","_npmUser":{"name":"constantology","email":"constantology@gmail.com"},"maintainers":[{"name":"constantology","email":"constantology@gmail.com"}]},"0.0.3":{"author":{"name":"constantology","email":"christos@muigui.com","url":"http://muigui.com"},"description":"useful date parsing and formatting library","dependencies":{"useful-copy":"latest","useful-type":"latest","useful-util":"latest","useful-value":"latest"},"devDependencies":{"chai":"latest","grunt":"latest","grunt-contrib-concat":"latest","grunt-contrib-uglify":"latest","grunt-contrib-watch":"latest","grunt-lib-phantomjs":"latest","grunt-mocha":"latest","grunt-shell":"latest","mocha":"latest"},"engines":{"node":">= 0.8.x"},"keywords":["date"],"licenses":[{"type":"MIT","url":"https://raw.github.com/muigui/useful-date/master/LICENSE"}],"main":"./index.js","name":"useful-date","repository":{"type":"git","url":"git@github.com:muigui/useful-date.git"},"scripts":{"test":"mocha -c --ignore-leaks -R spec -u tdd ./test/runner.js"},"version":"0.0.3","readme":"\n# useful-date\n\n useful date parsing and formatting library.\n\n useful-date extends the `Date` and `Date.prototype` using `Object.defineProperty` — it **will not** create new enumerable methods and properties and it will not over-write any existing methods.\n\n## Installation\n\n Install with [component(1)](http://component.io):\n\n $ component install muigui/useful-date\n\n Install with npm:\n\n $ npm install useful-date\n\n\n## API\n\n### Static methods\n\n#### isLeapYear( year:String ):Boolean\nReturns true if the passed **4 digit** year is a leap year.\n\n**NOTE:** This method is located in the locale file. If your calendar system does not contain leap years, you can simply change the method to only `return false`.\n\n#### getOrdinal( date:Number ):String\nReturns the ordinal for a given date.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n Date.getOrdinal( 1 ); // returns => \"st\"\n Date.getOrdinal( 10 ); // returns => \"th\"\n Date.getOrdinal( 22 ); // returns => \"nd\"\n Date.getOrdinal( 33 ); // returns => \"rd\"\n\n```\n\n**NOTE:** Ordinals and the `getOrdinal` This method is located in the locale file. You can simply change the `ordinal` Array to your specific language; overwrite the `getOrdinal` method or both.\n\n#### setLeapYear( date:Date ):Void\nSets the inlcuded locale's February day count to the correct number of days, based on whether or not the date is a leap year or not.\n\n**NOTE:** This method is located in the locale file. If your calendar system does not contain leap years, you can simply change the method to do nothing.\n\n#### coerce( date:String, format:String ):Date\nTakes a date String and a format String based on the **Date formatting and parsing options** described below and returns a – hopefully – correct and valid Date.\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n Date.coerce( 'Sunday, the 1st of January 2012', 'l, jS F Y' ); // returns => Date { Sun Jan 01 2012 00:00:00 GMT+0000 (GMT) }\n Date.coerce( '2012-01-01T00:00:00+00:00', Date.formats.ISO_8601 ); // returns => Date { Sun Jan 01 2012 00:00:00 GMT+0000 (GMT) }\n\n```\n\n### Static properties\n\n#### filters\nAn Object of all the available filters for formatting a Date.\n\n**IMPORTANT: Don't change these unless you know what you are doing!**\n\n#### formats\nAn Object containing some default date formats:\n\n\t\n\t\n\t\n\t\n\t\n
ISO_8601Y-m-dH:i:sP
ISO_8601_SHORTY-m-d
RFC_850l, d-M-y H:i:s T
RFC_2822D, d M Y H:i:s O
sortableY-m-d H:i:sO
\n\n### Instance methods\n\n#### adjust( interval:Object|String[, value:Number] ):Date\nYour one stop shop for all Date arithmetic. Adjusts the Date based on the passed `interval`, by the passed numeric `value`.\n\n**Note:** The method also accepts a single Object param where each key is the interval and each value is the number to adjust the Date by.\n\n**Valid intervals are:** year, month, week, day, hr, min, sec, ms.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n var date = new Date( 2012, 0, 1 ); // Date {Sun Jan 01 2012 00:00:00 GMT+0000 (GMT)}\n\n date.adjust( Date.DAY, 1 ); // Date {Mon Jan 02 2012 00:00:00 GMT+0000 (GMT)}\n date.adjust( Date.HOUR, -1 ); // Date {Sun Jan 01 2012 23:00:00 GMT+0000 (GMT)}\n date.adjust( {\n year : -1, month : -1, day : 24,\n hr : 1, sec : -1\n } ); // Date {Sat Dec 25 2010 23:59:59 GMT+0000 (GMT)}\n\n```\n\n#### between( date_lower:Date, date_higher:Date ):Boolean\nChecks to see if the Date instance is in between the two passed Dates.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n var date = new Date( 2012, 0, 1 );\n\n date.between( new Date( 2011, 0, 1 ), new Date( 2013, 0, 1 ) ); // returns => true;\n\n date.between( new Date( 2013, 0, 1 ), new Date( 2011, 0, 1 ) ); // returns => false;\n\n```\n\n#### clearTime():Date\nClears the time from the Date instance.\n\n#### clone():Date\nReturns a clone of the current Date.\n\n#### diff( [date:Date, exclude:String] ):Object\nReturns an Object describing the difference between the Date instance and now — or the optionally passed Date.\n\nThe Object will contain any or all of the following properties:\n\n\n\t\n\t\t\n\t\n\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\n
PropTypeDescription
tenseNumberThis will either be:\n\t\t\t
\n\t\t\t\t
-1
The Date instance is less than now or the passed Date, i.e. in the past
\n\t\t\t\t
0
The Date instance is equal to now or the passed Date, i.e. in the present.
NOTE: If tense is 0 then the Object will most probably have no other properties, except value, which will be zero.
\n\t\t\t\t
1
The Date instance is greater than now or the passed Date, i.e. in the future
\n\t\t\t
\n\t\t\tNOTE: To make the diff Object's values easier to work with all other properties will be positive Numbers. You should use the tense property as your reference for the diff being in the past, present or future.\n\t\t
valueNumberThe — absolute — number of milliseconds difference between the two Dates.
yearsNumberThe number of years the Date instance is ahead or behind the passed Date.
monthsNumberThe months of years the Date instance is ahead or behind the passed Date.
weeksNumberThe weeks of years the Date instance is ahead or behind the passed Date.
daysNumberThe days of years the Date instance is ahead or behind the passed Date.
hoursNumberThe hours of years the Date instance is ahead or behind the passed Date.
minutesNumberThe minutes of years the Date instance is ahead or behind the passed Date.
secondsNumberThe seconds of years the Date instance is ahead or behind the passed Date.
millisecondsNumberThe milliseconds of years the Date instance is ahead or behind the passed Date.
\n\n**NOTE:** If any property — other than `tense` & `value` — is zero it will be omitted from the `diff` Object.\n\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 1 ) ) // returns => { tense : 0 }\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 2 ) ) // returns => { tense : -1, value : 86400000, days : 1 }\n\n ( new Date( 2012, 0, 2 ) ).diff( new Date( 2012, 0, 1 ) ) // returns => { tense : 1, value : 86400000, days : 1 }\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2010, 9, 8, 7, 6, 5, 4 ) ) // returns => { tense : 1, value : 38858034996, years : 1, months : 2, weeks : 3, days : 3, hours : 17, minutes : 53, seconds : 54, ms : 995 }\n\n```\n\n**NOTE:** You can supply a **space delimited** String defining which properties you want to exclude from the result and `diff` will either pass the current calculation to the next time unit or, if there are none will round off — up if over .5 or down if less, uses `Math.round` to figure this out — to the previous time unit.\n\nExclusion codes:\n- `-` will exclude the time unit from the `diff` Object.\n- `+` will include the time unit in the `diff` Object. **Note:** this is the same as not including the time unit in the `exclusions` String.\n- `>` will exclude all time units from this time unit down from the `diff` Object.\n\n##### Example with exclusions:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 2 ), '-days' ) // returns => { tense : -1, value : 86400000, hours : 24 }\n\n ( new Date( 2012, 0, 2 ) ).diff( new Date( 2012, 0, 1 ), '-days' ) // returns => { tense : 1, value : 86400000, hours : 24 }\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2010, 9, 8, 7, 6, 5, 4 ), '-years -weeks >minutes' ) // returns => { tense : 1, value : 38858034996, months : 14, days : 29, hours : 18 }\n\n```\n\n#### format( format:String ):String\nReturns a string representation of the Date instance, based on the passed format. See the [Date formatting and parsing options](#date-formatting-and-parsing-options) below.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).format( 'c' ); // returns => \"2012-01-01T00:00:00.000Z\"\n // which is a short hand format for:\n ( new Date( 2012, 0, 1 ) ).format( 'Y-m-dH:i:s.u' ); // returns => \"2012-01-01T00:00:00.000Z\"\n\n ( new Date( 2012, 0, 1 ) ).format( 'l, nS F Y' ) // returns => \"Sunday, the 1st of January 2012\"\n\n```\n\nYou can use predefined formats found in `Date.formats`. **Hint:** You can do:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n console.dir( Date.formats );\n\n```\n\nwithin your browser's JavaScript console to see a list of available formats.\n\nPreviously used formats are also cached to save the overhead of having to create a `new Function` everytime you want to format a date.\n\n#### getDayOfYear():Number\nReturns the zero based day of the year.\n\n#### getFirstOfTheMonth():Date\nReturns a Date instance of the first day of this Date instance's month.\n\n#### getGMTOffset( [colon:Boolean] ):String\nReturns the Date instances offset from GMT.\n\n#### getISODay():Number\nReturns the ISO day of the week.\n\n#### getISODaysInYear():Number\nReturns the ISO number of days in the year.\n\n#### getISOFirstMondayOfYear():Date\nReturns the ISO first Monday of the year.\n\n#### getISOWeek():Number\nReturns the ISO week of the year\n\n#### getISOWeeksInYear():Number\nReturns the number of weeks in the ISO year.\n\n#### getLastOfTheMonth():Date\nReturns a Date instance of the last day of this Date instance's month.\n\n#### getWeek():Number\nReturns the week of the year, based on the `dayOfYear` divided by 7.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).getWeek(); // returns => 0\n ( new Date( 2012, 2, 13 ) ).getWeek(); // returns => 10\n ( new Date( 2012, 11, 31 ) ).getWeek(); // returns => 52\n\n```\n\n#### isDST():Boolean\nReturns true if the Date instance is within daylight savings time.\n\n#### isLeapYear():Boolean\nReturns true if the Date instance is a leap year.\n\n#### lexicalize( [now:Date, format:String] ):String\nReturns a String representation of the difference between the date instance and now, or the passed `Date`.\n\n#### Available formats\nThe default format is `approx`, however this can be over-written by changing the **locale** file and/ or by passing in the desired format to the method.\n\n\n\t\n\t\n
approxWill return an approximate difference. e.g. about 2 days ago; almost 1 and a half years from now.
exactWill return the exact difference, e.g. 2 days 3 hours and 5 minutes ago; 1 year, 4 months, 2 weeks, 1 day, 5 hours, 3 minutes and 7 seconds from now.
\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n\tvar date = new Date( 2012, 0, 1 );\n\n\tdate.clone().adjust( { hr : -3, day : -2 } ).lexicalize( date, 'approx' ); // returns => \"just over 2 days ago\"\n\tdate.clone().adjust( { hr : -3, day : -2 } ).lexicalize( date, 'exact' ); // returns => \"2 days and 3 hours ago\"\n\n\tdate.lexicalize( date.clone().adjust( { hr : -6, day : -2 } ), 'approx' ); // returns => \"almost 2 and a half days from now\"\n\tdate.lexicalize( date.clone().adjust( { hr : -6, day : -2 } ), 'exact' ); // returns => \"2 days and 6 hours from now\"\n\n```\n\n#### setWeek():Number(UnixTimeStamp)\nSets the week of the year from the 1st January.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n new Date( ( new Date( 2012, 0, 1 ) ).setWeek( 17 ) ); // returns => Date {Sun Apr 29 2012 00:00:00 GMT+0100 (BST)}\n\n ( new Date( 2012, 2, 13 ) ).setWeek( 17 ); // returns => 1335654000000 same as above\n\n ( new Date( 2012, 11, 31 ) ).setWeek( 17 ); // returns => 1335654000000\n\n```\n\n#### timezone():String\nReturns the JavaScript engine's Date.prototype.toString() timezone abbreviation.\n\n## Date formatting and parsing options\n\n### escaping characters\n\nIf you want to escape characters that are used by the Date parser you can wrap them between <>.\n\n#### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).format( 'l, jS F Y' ); // returns => \"Sunday, the 1st of January 2012\"\n\n```\n\n### day\n\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n
dDay of the month, 2 digits with leading zeros
DA textual representation of a day, three letters
jDay of the month without leading zeros
lA full textual representation of the day of the week
NISO-8601 numeric representation of the day of the week
SEnglish ordinal suffix for the day of the month, 2 characters
wNumeric representation of the day of the week
zThe day of the year (starting from 0)
\n### week\n\n\t\n
WISO-8601 week number of year, weeks starting on Monday
\n### month\n\n\t\n\t\n\t\n\t\n\t\n
FA full textual representation of a month
mNumeric representation of a month, with leading zeros
MA short textual representation of a month, three letters
nNumeric representation of a month, without leading zeros
tNumber of days in the given month
\n### year\n\n\t\n\t\n\t\n\t\n
LWhether it's a leap year
oISO-8601 year number. This has the same value as Y, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead.
YA full numeric representation of a year, 4 digits
yA two digit representation of a year
\n### time\n\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n
aLowercase Ante meridiem and Post meridiem
AUppercase Ante meridiem and Post meridiem
g12-hour format of an hour without leading zeros
G24-hour format of an hour without leading zeros
h12-hour format of an hour with leading zeros
H24-hour format of an hour with leading zeros
iMinutes with leading zeros
sSeconds, with leading zeros
uMilliseconds
\n### timezone\n\n\t\n\t\n\t\n\t\n
ODifference to Greenwich time (GMT) in hours
PDifference to Greenwich time (GMT) with colon between hours and minutes
TTimezone abbreviation
ZTimezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive.
\n### full date/time\n\n\t\n\t\n\t\n
cISO 8601 date
rRFC 2822 formatted date
USeconds since the Unix Epoch January 1 1970 00:00:00 GMT
\n### custom\n\n\t\n\t\n
ethis is a convenience for `date.lexicalize( 'exact' );`
xthis is a convenience for `date.lexicalize( 'approx' );`
\n\n## License\n\n(The MIT License)\n\nCopyright (c) 2011 christos \"constantology\" constandinou http://muigui.com\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n","readmeFilename":"Readme.md","bugs":{"url":"https://github.com/muigui/useful-date/issues"},"_id":"useful-date@0.0.3","dist":{"shasum":"ccd6a9cc173861e7c84735eff522b4410a584890","tarball":"https://registry.npmjs.org/useful-date/-/useful-date-0.0.3.tgz","integrity":"sha512-o+kfGqL3pyyM3tYh8B8MM78MqFRt1NK1aBo4hazZHY0wpqxwNpZHPUPjKtZNUZoZqlOo3g8REdJS6wL44HEvFQ==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDG6IBVXQQ+JZPHRnPGOZhxt+YtNytqsV2QQXrYRFNiOQIgIEHFxJYmpHHOazYGoQlbb+MhPmSbz3g9QfljyPkUABY="}]},"_from":".","_npmVersion":"1.3.11","_npmUser":{"name":"constantology","email":"constantology@gmail.com"},"maintainers":[{"name":"constantology","email":"constantology@gmail.com"}]},"0.0.4":{"author":{"name":"constantology","email":"christos@muigui.com","url":"http://muigui.com"},"description":"useful date parsing and formatting library","dependencies":{"useful-copy":"latest","useful-type":"latest","useful-util":"latest","useful-value":"latest"},"devDependencies":{"chai":"latest","grunt":"latest","grunt-contrib-concat":"latest","grunt-contrib-uglify":"latest","grunt-contrib-watch":"latest","grunt-lib-phantomjs":"latest","grunt-mocha":"latest","grunt-shell":"latest","mocha":"latest"},"engines":{"node":">= 0.8.x"},"keywords":["date"],"licenses":[{"type":"MIT","url":"https://raw.github.com/muigui/useful-date/master/LICENSE"}],"main":"./index.js","name":"useful-date","repository":{"type":"git","url":"git@github.com:muigui/useful-date.git"},"scripts":{"test":"mocha -c --ignore-leaks -R spec -u tdd ./test/runner.js"},"version":"0.0.4","readme":"\n# useful-date\n\n useful date parsing and formatting library.\n\n useful-date extends the `Date` and `Date.prototype` using `Object.defineProperty` — it **will not** create new enumerable methods and properties and it will not over-write any existing methods.\n\n## Installation\n\n Install with [component(1)](http://component.io):\n\n $ component install muigui/useful-date\n\n Install with npm:\n\n $ npm install useful-date\n\n\n## API\n\n### Static methods\n\n#### localize( locale:String ):Date\nsets the underlying `locale`.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\trequire( 'useful-date/locale/en-US.js' );\n\n Date.localize( 'en-US' );\n\n Date.formats.short_date // returns => 'm/d/Y'\n\n Date.localize( 'en-GB' );\n\n Date.formats.short_date // returns => 'd/m/Y'\n\n```\n\n#### isLeapYear( year:String ):Boolean\nReturns true if the passed **4 digit** year is a leap year.\n\n**NOTE:** This method is located in the locale file. If your calendar system does not contain leap years, you can simply change the method to only `return false`.\n\n#### getOrdinal( date:Number ):String\nReturns the ordinal for a given date.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n Date.getOrdinal( 1 ); // returns => \"st\"\n Date.getOrdinal( 10 ); // returns => \"th\"\n Date.getOrdinal( 22 ); // returns => \"nd\"\n Date.getOrdinal( 33 ); // returns => \"rd\"\n\n```\n\n**NOTE:** Ordinals and the `getOrdinal` This method is located in the locale file. You can simply change the `ordinal` Array to your specific language; overwrite the `getOrdinal` method or both.\n\n#### setLeapYear( date:Date ):Void\nSets the inlcuded locale's February day count to the correct number of days, based on whether or not the date is a leap year or not.\n\n**NOTE:** This method is located in the locale file. If your calendar system does not contain leap years, you can simply change the method to do nothing.\n\n#### coerce( date:String, format:String ):Date\nTakes a date String and a format String based on the **Date formatting and parsing options** described below and returns a – hopefully – correct and valid Date.\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n Date.coerce( 'Sunday, the 1st of January 2012', 'l, jS F Y' ); // returns => Date { Sun Jan 01 2012 00:00:00 GMT+0000 (GMT) }\n Date.coerce( '2012-01-01T00:00:00+00:00', Date.formats.ISO_8601 ); // returns => Date { Sun Jan 01 2012 00:00:00 GMT+0000 (GMT) }\n\n```\n\n### Static properties\n\n#### filters\nAn Object of all the available filters for formatting a Date.\n\n**IMPORTANT: Don't change these unless you know what you are doing!**\n\n#### formats\nAn Object containing some default date formats:\n\n\t\n\t\n\t\n\t\n\t\n
ISO_8601Y-m-dH:i:sP
ISO_8601_SHORTY-m-d
RFC_850l, d-M-y H:i:s T
RFC_2822D, d M Y H:i:s O
sortableY-m-d H:i:sO
\n\n### Instance methods\n\n#### adjust( interval:Object|String[, value:Number] ):Date\nYour one stop shop for all Date arithmetic. Adjusts the Date based on the passed `interval`, by the passed numeric `value`.\n\n**Note:** The method also accepts a single Object param where each key is the interval and each value is the number to adjust the Date by.\n\n**Valid intervals are:** year, month, week, day, hr, min, sec, ms.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n var date = new Date( 2012, 0, 1 ); // Date {Sun Jan 01 2012 00:00:00 GMT+0000 (GMT)}\n\n date.adjust( Date.DAY, 1 ); // Date {Mon Jan 02 2012 00:00:00 GMT+0000 (GMT)}\n date.adjust( Date.HOUR, -1 ); // Date {Sun Jan 01 2012 23:00:00 GMT+0000 (GMT)}\n date.adjust( {\n year : -1, month : -1, day : 24,\n hr : 1, sec : -1\n } ); // Date {Sat Dec 25 2010 23:59:59 GMT+0000 (GMT)}\n\n```\n\n#### between( date_lower:Date, date_higher:Date ):Boolean\nChecks to see if the Date instance is in between the two passed Dates.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n var date = new Date( 2012, 0, 1 );\n\n date.between( new Date( 2011, 0, 1 ), new Date( 2013, 0, 1 ) ); // returns => true;\n\n date.between( new Date( 2013, 0, 1 ), new Date( 2011, 0, 1 ) ); // returns => false;\n\n```\n\n#### clearTime():Date\nClears the time from the Date instance.\n\n#### clone():Date\nReturns a clone of the current Date.\n\n#### diff( [date:Date, exclude:String] ):Object\nReturns an Object describing the difference between the Date instance and now — or the optionally passed Date.\n\nThe Object will contain any or all of the following properties:\n\n\n\t\n\t\t\n\t\n\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\n
PropTypeDescription
tenseNumberThis will either be:\n\t\t\t
\n\t\t\t\t
-1
The Date instance is less than now or the passed Date, i.e. in the past
\n\t\t\t\t
0
The Date instance is equal to now or the passed Date, i.e. in the present.
NOTE: If tense is 0 then the Object will most probably have no other properties, except value, which will be zero.
\n\t\t\t\t
1
The Date instance is greater than now or the passed Date, i.e. in the future
\n\t\t\t
\n\t\t\tNOTE: To make the diff Object's values easier to work with all other properties will be positive Numbers. You should use the tense property as your reference for the diff being in the past, present or future.\n\t\t
valueNumberThe — absolute — number of milliseconds difference between the two Dates.
yearsNumberThe number of years the Date instance is ahead or behind the passed Date.
monthsNumberThe months of years the Date instance is ahead or behind the passed Date.
weeksNumberThe weeks of years the Date instance is ahead or behind the passed Date.
daysNumberThe days of years the Date instance is ahead or behind the passed Date.
hoursNumberThe hours of years the Date instance is ahead or behind the passed Date.
minutesNumberThe minutes of years the Date instance is ahead or behind the passed Date.
secondsNumberThe seconds of years the Date instance is ahead or behind the passed Date.
millisecondsNumberThe number of milliseconds the Date instance is ahead or behind the passed Date or now.
\n\n**NOTE:** If any property — other than `tense` & `value` — is zero it will be omitted from the `diff` Object.\n\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 1 ) ) // returns => { tense : 0 }\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 2 ) ) // returns => { tense : -1, value : 86400000, days : 1 }\n\n ( new Date( 2012, 0, 2 ) ).diff( new Date( 2012, 0, 1 ) ) // returns => { tense : 1, value : 86400000, days : 1 }\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2010, 9, 8, 7, 6, 5, 4 ) ) // returns => { tense : 1, value : 38858034996, years : 1, months : 2, weeks : 3, days : 3, hours : 17, minutes : 53, seconds : 54, ms : 995 }\n\n```\n\n**NOTE:** You can supply a **space delimited** String defining which properties you want to exclude from the result and `diff` will either pass the current calculation to the next time unit or, if there are none will round off — up if over .5 or down if less, uses `Math.round` to figure this out — to the previous time unit.\n\nExclusion codes:\n- `-` will exclude the time unit from the `diff` Object.\n- `+` will include the time unit in the `diff` Object. **Note:** this is the same as not including the time unit in the `exclusions` String.\n- `>` will exclude all time units from this time unit down from the `diff` Object.\n\n##### Example with exclusions:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 2 ), '-days' ) // returns => { tense : -1, value : 86400000, hours : 24 }\n\n ( new Date( 2012, 0, 2 ) ).diff( new Date( 2012, 0, 1 ), '-days' ) // returns => { tense : 1, value : 86400000, hours : 24 }\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2010, 9, 8, 7, 6, 5, 4 ), '-years -weeks >minutes' ) // returns => { tense : 1, value : 38858034996, months : 14, days : 29, hours : 18 }\n\n```\n\n#### format( format:String ):String\nReturns a string representation of the Date instance, based on the passed format. See the [Date formatting and parsing options](#date-formatting-and-parsing-options) below.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).format( 'c' ); // returns => \"2012-01-01T00:00:00.000Z\"\n // which is a short hand format for:\n ( new Date( 2012, 0, 1 ) ).format( 'Y-m-dH:i:s.u' ); // returns => \"2012-01-01T00:00:00.000Z\"\n\n ( new Date( 2012, 0, 1 ) ).format( 'l, nS F Y' ) // returns => \"Sunday, the 1st of January 2012\"\n\n```\n\nYou can use predefined formats found in `Date.formats`. **Hint:** You can do:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n console.dir( Date.formats );\n\n```\n\nwithin your browser's JavaScript console to see a list of available formats.\n\nPreviously used formats are also cached to save the overhead of having to create a `new Function` everytime you want to format a date.\n\n#### getDayOfYear():Number\nReturns the zero based day of the year.\n\n#### getFirstOfTheMonth():Date\nReturns a Date instance of the first day of this Date instance's month.\n\n#### getGMTOffset( [colon:Boolean] ):String\nReturns the Date instances offset from GMT.\n\n#### getISODay():Number\nReturns the ISO day of the week.\n\n#### getISODaysInYear():Number\nReturns the ISO number of days in the year.\n\n#### getISOFirstMondayOfYear():Date\nReturns the ISO first Monday of the year.\n\n#### getISOWeek():Number\nReturns the ISO week of the year\n\n#### getISOWeeksInYear():Number\nReturns the number of weeks in the ISO year.\n\n#### getLastOfTheMonth():Date\nReturns a Date instance of the last day of this Date instance's month.\n\n#### getWeek():Number\nReturns the week of the year, based on the `dayOfYear` divided by 7.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).getWeek(); // returns => 0\n ( new Date( 2012, 2, 13 ) ).getWeek(); // returns => 10\n ( new Date( 2012, 11, 31 ) ).getWeek(); // returns => 52\n\n```\n\n#### isDST():Boolean\nReturns true if the Date instance is within daylight savings time.\n\n#### isLeapYear():Boolean\nReturns true if the Date instance is a leap year.\n\n#### lexicalize( [now:Date, format:String] ):String\nReturns a String representation of the difference between the date instance and now, or the passed `Date`.\n\n#### Available formats\nThe default format is `approx`, however this can be over-written by changing the **locale** file and/ or by passing in the desired format to the method.\n\n\n\t\n\t\n
approxWill return an approximate difference. e.g. about 2 days ago; almost 1 and a half years from now.
exactWill return the exact difference, e.g. 2 days 3 hours and 5 minutes ago; 1 year, 4 months, 2 weeks, 1 day, 5 hours, 3 minutes and 7 seconds from now.
\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n\tvar date = new Date( 2012, 0, 1 );\n\n\tdate.clone().adjust( { hr : -3, day : -2 } ).lexicalize( date, 'approx' ); // returns => \"just over 2 days ago\"\n\tdate.clone().adjust( { hr : -3, day : -2 } ).lexicalize( date, 'exact' ); // returns => \"2 days and 3 hours ago\"\n\n\tdate.lexicalize( date.clone().adjust( { hr : -6, day : -2 } ), 'approx' ); // returns => \"almost 2 and a half days from now\"\n\tdate.lexicalize( date.clone().adjust( { hr : -6, day : -2 } ), 'exact' ); // returns => \"2 days and 6 hours from now\"\n\n```\n\n#### setWeek():Number(UnixTimeStamp)\nSets the week of the year from the 1st January.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n new Date( ( new Date( 2012, 0, 1 ) ).setWeek( 17 ) ); // returns => Date {Sun Apr 29 2012 00:00:00 GMT+0100 (BST)}\n\n ( new Date( 2012, 2, 13 ) ).setWeek( 17 ); // returns => 1335654000000 same as above\n\n ( new Date( 2012, 11, 31 ) ).setWeek( 17 ); // returns => 1335654000000\n\n```\n\n#### timezone():String\nReturns the JavaScript engine's Date.prototype.toString() timezone abbreviation.\n\n## Date formatting and parsing options\n\n### escaping characters\n\nIf you want to escape characters that are used by the Date parser you can wrap them between <>.\n\n#### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).format( 'l, jS F Y' ); // returns => \"Sunday, the 1st of January 2012\"\n\n```\n\n### day\n\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n
dDay of the month, 2 digits with leading zeros
DA textual representation of a day, three letters
jDay of the month without leading zeros
lA full textual representation of the day of the week
NISO-8601 numeric representation of the day of the week
SEnglish ordinal suffix for the day of the month, 2 characters
wNumeric representation of the day of the week
zThe day of the year (starting from 0)
\n### week\n\n\t\n
WISO-8601 week number of year, weeks starting on Monday
\n### month\n\n\t\n\t\n\t\n\t\n\t\n
FA full textual representation of a month
mNumeric representation of a month, with leading zeros
MA short textual representation of a month, three letters
nNumeric representation of a month, without leading zeros
tNumber of days in the given month
\n### year\n\n\t\n\t\n\t\n\t\n
LWhether it's a leap year
oISO-8601 year number. This has the same value as Y, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead.
YA full numeric representation of a year, 4 digits
yA two digit representation of a year
\n### time\n\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n
aLowercase Ante meridiem and Post meridiem
AUppercase Ante meridiem and Post meridiem
g12-hour format of an hour without leading zeros
G24-hour format of an hour without leading zeros
h12-hour format of an hour with leading zeros
H24-hour format of an hour with leading zeros
iMinutes with leading zeros
sSeconds, with leading zeros
uMilliseconds
\n### timezone\n\n\t\n\t\n\t\n\t\n
ODifference to Greenwich time (GMT) in hours
PDifference to Greenwich time (GMT) with colon between hours and minutes
TTimezone abbreviation
ZTimezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive.
\n### full date/time\n\n\t\n\t\n\t\n
cISO 8601 date
rRFC 2822 formatted date
USeconds since the Unix Epoch January 1 1970 00:00:00 GMT
\n### custom\n\n\t\n\t\n
ethis is a convenience for `date.lexicalize( 'exact' );`
xthis is a convenience for `date.lexicalize( 'approx' );`
\n\n## License\n\n(The MIT License)\n\nCopyright (c) 2011 christos \"constantology\" constandinou http://muigui.com\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n","readmeFilename":"Readme.md","bugs":{"url":"https://github.com/muigui/useful-date/issues"},"_id":"useful-date@0.0.4","dist":{"shasum":"55503c1f8ad9bcc0412446581c1c11ab5e6affd5","tarball":"https://registry.npmjs.org/useful-date/-/useful-date-0.0.4.tgz","integrity":"sha512-qmb2k+2AtFfVGB3UzNqHtzFM8LGUzFK445fPQ+IIkSqXAR7LxivRaWmpKiYxGBWtbdodvDfTb3TaICNBoyCqrg==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCYp/3z5/Iv99ub1Ud+6j4lW9PWuoVXJSIAy48HzJYrAgIgRtrNdbRTpMmpTvcWRl55CQ5PmdQD+PEq3tr3srba2vA="}]},"_from":".","_npmVersion":"1.3.11","_npmUser":{"name":"constantology","email":"constantology@gmail.com"},"maintainers":[{"name":"constantology","email":"constantology@gmail.com"}]},"0.0.5":{"author":{"name":"constantology","email":"christos@muigui.com","url":"http://muigui.com"},"description":"useful date parsing and formatting library","dependencies":{"useful-copy":"latest","useful-iter":"latest","useful-type":"latest","useful-value":"latest"},"devDependencies":{"chai":"latest","grunt":"latest","grunt-contrib-concat":"latest","grunt-contrib-uglify":"latest","grunt-contrib-watch":"latest","grunt-lib-phantomjs":"latest","grunt-mocha":"latest","grunt-shell":"latest","mocha":"latest"},"engines":{"node":">= 0.8.x"},"keywords":["date"],"licenses":[{"type":"MIT","url":"https://raw.github.com/muigui/useful-date/master/LICENSE"}],"main":"./index.js","name":"useful-date","repository":{"type":"git","url":"git@github.com:muigui/useful-date.git"},"scripts":{"test":"mocha -c --ignore-leaks -R spec -u tdd ./test/runner.js"},"version":"0.0.5","readme":"\n# useful-date\n\n useful date parsing and formatting library.\n\n useful-date extends the `Date` and `Date.prototype` using `Object.defineProperty` — it **will not** create new enumerable methods and properties and it will not over-write any existing methods.\n\n## Installation\n\n Install with [component(1)](http://component.io):\n\n $ component install muigui/useful-date\n\n Install with npm:\n\n $ npm install useful-date\n\n\n## API\n\n### Static methods\n\n#### localize( locale:String ):Date\nsets the underlying `locale`.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\trequire( 'useful-date/locale/en-US.js' );\n\n Date.localize( 'en-US' );\n\n Date.formats.short_date // returns => 'm/d/Y'\n\n Date.localize( 'en-GB' );\n\n Date.formats.short_date // returns => 'd/m/Y'\n\n```\n\n#### isLeapYear( year:String ):Boolean\nReturns true if the passed **4 digit** year is a leap year.\n\n**NOTE:** This method is located in the locale file. If your calendar system does not contain leap years, you can simply change the method to only `return false`.\n\n#### getOrdinal( date:Number ):String\nReturns the ordinal for a given date.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n Date.getOrdinal( 1 ); // returns => \"st\"\n Date.getOrdinal( 10 ); // returns => \"th\"\n Date.getOrdinal( 22 ); // returns => \"nd\"\n Date.getOrdinal( 33 ); // returns => \"rd\"\n\n```\n\n**NOTE:** Ordinals and the `getOrdinal` This method is located in the locale file. You can simply change the `ordinal` Array to your specific language; overwrite the `getOrdinal` method or both.\n\n#### setLeapYear( date:Date ):Void\nSets the inlcuded locale's February day count to the correct number of days, based on whether or not the date is a leap year or not.\n\n**NOTE:** This method is located in the locale file. If your calendar system does not contain leap years, you can simply change the method to do nothing.\n\n#### coerce( date:String, format:String ):Date\nTakes a date String and a format String based on the **Date formatting and parsing options** described below and returns a – hopefully – correct and valid Date.\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n Date.coerce( 'Sunday, the 1st of January 2012', 'l, jS F Y' ); // returns => Date { Sun Jan 01 2012 00:00:00 GMT+0000 (GMT) }\n Date.coerce( '2012-01-01T00:00:00+00:00', Date.formats.ISO_8601 ); // returns => Date { Sun Jan 01 2012 00:00:00 GMT+0000 (GMT) }\n\n```\n\n### Static properties\n\n#### filters\nAn Object of all the available filters for formatting a Date.\n\n**IMPORTANT: Don't change these unless you know what you are doing!**\n\n#### formats\nAn Object containing some default date formats:\n\n\t\n\t\n\t\n\t\n\t\n
ISO_8601Y-m-dH:i:sP
ISO_8601_SHORTY-m-d
RFC_850l, d-M-y H:i:s T
RFC_2822D, d M Y H:i:s O
sortableY-m-d H:i:sO
\n\n### Instance methods\n\n#### adjust( interval:Object|String[, value:Number] ):Date\nYour one stop shop for all Date arithmetic. Adjusts the Date based on the passed `interval`, by the passed numeric `value`.\n\n**Note:** The method also accepts a single Object param where each key is the interval and each value is the number to adjust the Date by.\n\n**Valid intervals are:** year, month, week, day, hr, min, sec, ms.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n var date = new Date( 2012, 0, 1 ); // Date {Sun Jan 01 2012 00:00:00 GMT+0000 (GMT)}\n\n date.adjust( Date.DAY, 1 ); // Date {Mon Jan 02 2012 00:00:00 GMT+0000 (GMT)}\n date.adjust( Date.HOUR, -1 ); // Date {Sun Jan 01 2012 23:00:00 GMT+0000 (GMT)}\n date.adjust( {\n year : -1, month : -1, day : 24,\n hr : 1, sec : -1\n } ); // Date {Sat Dec 25 2010 23:59:59 GMT+0000 (GMT)}\n\n```\n\n#### between( date_lower:Date, date_higher:Date ):Boolean\nChecks to see if the Date instance is in between the two passed Dates.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n var date = new Date( 2012, 0, 1 );\n\n date.between( new Date( 2011, 0, 1 ), new Date( 2013, 0, 1 ) ); // returns => true;\n\n date.between( new Date( 2013, 0, 1 ), new Date( 2011, 0, 1 ) ); // returns => false;\n\n```\n\n#### clearTime():Date\nClears the time from the Date instance.\n\n#### clone():Date\nReturns a clone of the current Date.\n\n#### diff( [date:Date, exclude:String] ):Object\nReturns an Object describing the difference between the Date instance and now — or the optionally passed Date.\n\nThe Object will contain any or all of the following properties:\n\n\n\t\n\t\t\n\t\n\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\n
PropTypeDescription
tenseNumberThis will either be:\n\t\t\t
\n\t\t\t\t
-1
The Date instance is less than now or the passed Date, i.e. in the past
\n\t\t\t\t
0
The Date instance is equal to now or the passed Date, i.e. in the present.
NOTE: If tense is 0 then the Object will most probably have no other properties, except value, which will be zero.
\n\t\t\t\t
1
The Date instance is greater than now or the passed Date, i.e. in the future
\n\t\t\t
\n\t\t\tNOTE: To make the diff Object's values easier to work with all other properties will be positive Numbers. You should use the tense property as your reference for the diff being in the past, present or future.\n\t\t
valueNumberThe — absolute — number of milliseconds difference between the two Dates.
yearsNumberThe number of years the Date instance is ahead or behind the passed Date.
monthsNumberThe months of years the Date instance is ahead or behind the passed Date.
weeksNumberThe weeks of years the Date instance is ahead or behind the passed Date.
daysNumberThe days of years the Date instance is ahead or behind the passed Date.
hoursNumberThe hours of years the Date instance is ahead or behind the passed Date.
minutesNumberThe minutes of years the Date instance is ahead or behind the passed Date.
secondsNumberThe seconds of years the Date instance is ahead or behind the passed Date.
millisecondsNumberThe number of milliseconds the Date instance is ahead or behind the passed Date or now.
\n\n**NOTE:** If any property — other than `tense` & `value` — is zero it will be omitted from the `diff` Object.\n\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 1 ) ) // returns => { tense : 0 }\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 2 ) ) // returns => { tense : -1, value : 86400000, days : 1 }\n\n ( new Date( 2012, 0, 2 ) ).diff( new Date( 2012, 0, 1 ) ) // returns => { tense : 1, value : 86400000, days : 1 }\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2010, 9, 8, 7, 6, 5, 4 ) ) // returns => { tense : 1, value : 38858034996, years : 1, months : 2, weeks : 3, days : 3, hours : 17, minutes : 53, seconds : 54, ms : 995 }\n\n```\n\n**NOTE:** You can supply a **space delimited** String defining which properties you want to exclude from the result and `diff` will either pass the current calculation to the next time unit or, if there are none will round off — up if over .5 or down if less, uses `Math.round` to figure this out — to the previous time unit.\n\nExclusion codes:\n- `-` will exclude the time unit from the `diff` Object.\n- `+` will include the time unit in the `diff` Object. **Note:** this is the same as not including the time unit in the `exclusions` String.\n- `>` will exclude all time units from this time unit down from the `diff` Object.\n\n##### Example with exclusions:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 2 ), '-days' ) // returns => { tense : -1, value : 86400000, hours : 24 }\n\n ( new Date( 2012, 0, 2 ) ).diff( new Date( 2012, 0, 1 ), '-days' ) // returns => { tense : 1, value : 86400000, hours : 24 }\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2010, 9, 8, 7, 6, 5, 4 ), '-years -weeks >minutes' ) // returns => { tense : 1, value : 38858034996, months : 14, days : 29, hours : 18 }\n\n```\n\n#### format( format:String ):String\nReturns a string representation of the Date instance, based on the passed format. See the [Date formatting and parsing options](#date-formatting-and-parsing-options) below.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).format( 'c' ); // returns => \"2012-01-01T00:00:00.000Z\"\n // which is a short hand format for:\n ( new Date( 2012, 0, 1 ) ).format( 'Y-m-dH:i:s.u' ); // returns => \"2012-01-01T00:00:00.000Z\"\n\n ( new Date( 2012, 0, 1 ) ).format( 'l, nS F Y' ) // returns => \"Sunday, the 1st of January 2012\"\n\n```\n\nYou can use predefined formats found in `Date.formats`. **Hint:** You can do:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n console.dir( Date.formats );\n\n```\n\nwithin your browser's JavaScript console to see a list of available formats.\n\nPreviously used formats are also cached to save the overhead of having to create a `new Function` everytime you want to format a date.\n\n#### getDayOfYear():Number\nReturns the zero based day of the year.\n\n#### getFirstOfTheMonth():Date\nReturns a Date instance of the first day of this Date instance's month.\n\n#### getGMTOffset( [colon:Boolean] ):String\nReturns the Date instances offset from GMT.\n\n#### getISODay():Number\nReturns the ISO day of the week.\n\n#### getISODaysInYear():Number\nReturns the ISO number of days in the year.\n\n#### getISOFirstMondayOfYear():Date\nReturns the ISO first Monday of the year.\n\n#### getISOWeek():Number\nReturns the ISO week of the year\n\n#### getISOWeeksInYear():Number\nReturns the number of weeks in the ISO year.\n\n#### getLastOfTheMonth():Date\nReturns a Date instance of the last day of this Date instance's month.\n\n#### getWeek():Number\nReturns the week of the year, based on the `dayOfYear` divided by 7.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).getWeek(); // returns => 0\n ( new Date( 2012, 2, 13 ) ).getWeek(); // returns => 10\n ( new Date( 2012, 11, 31 ) ).getWeek(); // returns => 52\n\n```\n\n#### isDST():Boolean\nReturns true if the Date instance is within daylight savings time.\n\n#### isLeapYear():Boolean\nReturns true if the Date instance is a leap year.\n\n#### lexicalize( [now:Date, format:String] ):String\nReturns a String representation of the difference between the date instance and now, or the passed `Date`.\n\n#### Available formats\nThe default format is `approx`, however this can be over-written by changing the **locale** file and/ or by passing in the desired format to the method.\n\n\n\t\n\t\n
approxWill return an approximate difference. e.g. about 2 days ago; almost 1 and a half years from now.
exactWill return the exact difference, e.g. 2 days 3 hours and 5 minutes ago; 1 year, 4 months, 2 weeks, 1 day, 5 hours, 3 minutes and 7 seconds from now.
\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n\tvar date = new Date( 2012, 0, 1 );\n\n\tdate.clone().adjust( { hr : -3, day : -2 } ).lexicalize( date, 'approx' ); // returns => \"just over 2 days ago\"\n\tdate.clone().adjust( { hr : -3, day : -2 } ).lexicalize( date, 'exact' ); // returns => \"2 days and 3 hours ago\"\n\n\tdate.lexicalize( date.clone().adjust( { hr : -6, day : -2 } ), 'approx' ); // returns => \"almost 2 and a half days from now\"\n\tdate.lexicalize( date.clone().adjust( { hr : -6, day : -2 } ), 'exact' ); // returns => \"2 days and 6 hours from now\"\n\n```\n\n#### setWeek():Number(UnixTimeStamp)\nSets the week of the year from the 1st January.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n new Date( ( new Date( 2012, 0, 1 ) ).setWeek( 17 ) ); // returns => Date {Sun Apr 29 2012 00:00:00 GMT+0100 (BST)}\n\n ( new Date( 2012, 2, 13 ) ).setWeek( 17 ); // returns => 1335654000000 same as above\n\n ( new Date( 2012, 11, 31 ) ).setWeek( 17 ); // returns => 1335654000000\n\n```\n\n#### timezone():String\nReturns the JavaScript engine's Date.prototype.toString() timezone abbreviation.\n\n## Date formatting and parsing options\n\n### escaping characters\n\nIf you want to escape characters that are used by the Date parser you can wrap them between <>.\n\n#### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).format( 'l, jS F Y' ); // returns => \"Sunday, the 1st of January 2012\"\n\n```\n\n### day\n\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n
dDay of the month, 2 digits with leading zeros
DA textual representation of a day, three letters
jDay of the month without leading zeros
lA full textual representation of the day of the week
NISO-8601 numeric representation of the day of the week
SEnglish ordinal suffix for the day of the month, 2 characters
wNumeric representation of the day of the week
zThe day of the year (starting from 0)
\n### week\n\n\t\n
WISO-8601 week number of year, weeks starting on Monday
\n### month\n\n\t\n\t\n\t\n\t\n\t\n
FA full textual representation of a month
mNumeric representation of a month, with leading zeros
MA short textual representation of a month, three letters
nNumeric representation of a month, without leading zeros
tNumber of days in the given month
\n### year\n\n\t\n\t\n\t\n\t\n
LWhether it's a leap year
oISO-8601 year number. This has the same value as Y, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead.
YA full numeric representation of a year, 4 digits
yA two digit representation of a year
\n### time\n\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n
aLowercase Ante meridiem and Post meridiem
AUppercase Ante meridiem and Post meridiem
g12-hour format of an hour without leading zeros
G24-hour format of an hour without leading zeros
h12-hour format of an hour with leading zeros
H24-hour format of an hour with leading zeros
iMinutes with leading zeros
sSeconds, with leading zeros
uMilliseconds
\n### timezone\n\n\t\n\t\n\t\n\t\n
ODifference to Greenwich time (GMT) in hours
PDifference to Greenwich time (GMT) with colon between hours and minutes
TTimezone abbreviation
ZTimezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive.
\n### full date/time\n\n\t\n\t\n\t\n
cISO 8601 date
rRFC 2822 formatted date
USeconds since the Unix Epoch January 1 1970 00:00:00 GMT
\n### custom\n\n\t\n\t\n
ethis is a convenience for `date.lexicalize( 'exact' );`
xthis is a convenience for `date.lexicalize( 'approx' );`
\n\n## License\n\n(The MIT License)\n\nCopyright (c) 2011 christos \"constantology\" constandinou http://muigui.com\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n","readmeFilename":"Readme.md","bugs":{"url":"https://github.com/muigui/useful-date/issues"},"homepage":"https://github.com/muigui/useful-date","_id":"useful-date@0.0.5","dist":{"shasum":"8659e4341409b814357ffd0fc83b1ab5aaa0fe58","tarball":"https://registry.npmjs.org/useful-date/-/useful-date-0.0.5.tgz","integrity":"sha512-7Rd5YQEwigxwpnVzqa+kY2U+xgAJuc0i7+kVbt36BXhBBsx2sBqoy9YgeobJksUynnw4WSTjhm64vO67c+veIQ==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQD6QrnV4UHA2RfEj0S2ayeSce+wED04BasoPmxvltyruQIgTVzyil7AH0BB1kn6cIWwuEGb6j/q2DZ+R3fxkjRnLpI="}]},"_from":".","_npmVersion":"1.3.11","_npmUser":{"name":"constantology","email":"constantology@gmail.com"},"maintainers":[{"name":"constantology","email":"constantology@gmail.com"}]},"0.0.6":{"author":{"name":"constantology","email":"christos@muigui.com","url":"http://muigui.com"},"description":"useful date parsing and formatting library","dependencies":{"useful-copy":"latest","useful-iter":"latest","useful-type":"latest","useful-value":"latest"},"devDependencies":{"chai":"latest","grunt":"latest","grunt-contrib-concat":"latest","grunt-contrib-uglify":"latest","grunt-contrib-watch":"latest","grunt-lib-phantomjs":"latest","grunt-mocha":"latest","grunt-shell":"latest","mocha":"latest"},"engines":{"node":">= 0.8.x"},"keywords":["date"],"licenses":[{"type":"MIT","url":"https://raw.github.com/muigui/useful-date/master/LICENSE"}],"main":"./index.js","name":"useful-date","repository":{"type":"git","url":"git@github.com:muigui/useful-date.git"},"scripts":{"test":"mocha -c --ignore-leaks -R spec -u tdd ./test/runner.js"},"version":"0.0.6","readme":"\n# useful-date\n\n useful date parsing and formatting library.\n\n useful-date extends the `Date` and `Date.prototype` using `Object.defineProperty` — it **will not** create new enumerable methods and properties and it will not over-write any existing methods.\n\n## Installation\n\n Install with [component(1)](http://component.io):\n\n $ component install muigui/useful-date\n\n Install with npm:\n\n $ npm install useful-date\n\n\n## API\n\n### Static methods\n\n#### localize( locale:String ):Date\nsets the underlying `locale`.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\trequire( 'useful-date/locale/en-US.js' );\n\n Date.localize( 'en-US' );\n\n Date.formats.short_date // returns => 'm/d/Y'\n\n Date.localize( 'en-GB' );\n\n Date.formats.short_date // returns => 'd/m/Y'\n\n```\n\n#### isLeapYear( year:String ):Boolean\nReturns true if the passed **4 digit** year is a leap year.\n\n**NOTE:** This method is located in the locale file. If your calendar system does not contain leap years, you can simply change the method to only `return false`.\n\n#### getOrdinal( date:Number ):String\nReturns the ordinal for a given date.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n Date.getOrdinal( 1 ); // returns => \"st\"\n Date.getOrdinal( 10 ); // returns => \"th\"\n Date.getOrdinal( 22 ); // returns => \"nd\"\n Date.getOrdinal( 33 ); // returns => \"rd\"\n\n```\n\n**NOTE:** Ordinals and the `getOrdinal` This method is located in the locale file. You can simply change the `ordinal` Array to your specific language; overwrite the `getOrdinal` method or both.\n\n#### setLeapYear( date:Date ):Void\nSets the inlcuded locale's February day count to the correct number of days, based on whether or not the date is a leap year or not.\n\n**NOTE:** This method is located in the locale file. If your calendar system does not contain leap years, you can simply change the method to do nothing.\n\n#### coerce( date:String, format:String ):Date\nTakes a date String and a format String based on the **Date formatting and parsing options** described below and returns a – hopefully – correct and valid Date.\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n Date.coerce( 'Sunday, the 1st of January 2012', 'l, jS F Y' ); // returns => Date { Sun Jan 01 2012 00:00:00 GMT+0000 (GMT) }\n Date.coerce( '2012-01-01T00:00:00+00:00', Date.formats.ISO_8601 ); // returns => Date { Sun Jan 01 2012 00:00:00 GMT+0000 (GMT) }\n\n```\n\n### Static properties\n\n#### filters\nAn Object of all the available filters for formatting a Date.\n\n**IMPORTANT: Don't change these unless you know what you are doing!**\n\n#### formats\nAn Object containing some default date formats:\n\n\t\n\t\n\t\n\t\n\t\n
ISO_8601Y-m-dH:i:sP
ISO_8601_SHORTY-m-d
RFC_850l, d-M-y H:i:s T
RFC_2822D, d M Y H:i:s O
sortableY-m-d H:i:sO
\n\n### Instance methods\n\n#### adjust( interval:Object|String[, value:Number] ):Date\nYour one stop shop for all Date arithmetic. Adjusts the Date based on the passed `interval`, by the passed numeric `value`.\n\n**Note:** The method also accepts a single Object param where each key is the interval and each value is the number to adjust the Date by.\n\n**Valid intervals are:** year, month, week, day, hr, min, sec, ms.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n var date = new Date( 2012, 0, 1 ); // Date {Sun Jan 01 2012 00:00:00 GMT+0000 (GMT)}\n\n date.adjust( Date.DAY, 1 ); // Date {Mon Jan 02 2012 00:00:00 GMT+0000 (GMT)}\n date.adjust( Date.HOUR, -1 ); // Date {Sun Jan 01 2012 23:00:00 GMT+0000 (GMT)}\n date.adjust( {\n year : -1, month : -1, day : 24,\n hr : 1, sec : -1\n } ); // Date {Sat Dec 25 2010 23:59:59 GMT+0000 (GMT)}\n\n```\n\n#### between( date_lower:Date, date_higher:Date ):Boolean\nChecks to see if the Date instance is in between the two passed Dates.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n var date = new Date( 2012, 0, 1 );\n\n date.between( new Date( 2011, 0, 1 ), new Date( 2013, 0, 1 ) ); // returns => true;\n\n date.between( new Date( 2013, 0, 1 ), new Date( 2011, 0, 1 ) ); // returns => false;\n\n```\n\n#### clearTime():Date\nClears the time from the Date instance.\n\n#### clone():Date\nReturns a clone of the current Date.\n\n#### diff( [date:Date, exclude:String] ):Object\nReturns an Object describing the difference between the Date instance and now — or the optionally passed Date.\n\nThe Object will contain any or all of the following properties:\n\n\n\t\n\t\t\n\t\n\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\n
PropTypeDescription
tenseNumberThis will either be:\n\t\t\t
\n\t\t\t\t
-1
The Date instance is less than now or the passed Date, i.e. in the past
\n\t\t\t\t
0
The Date instance is equal to now or the passed Date, i.e. in the present.
NOTE: If tense is 0 then the Object will most probably have no other properties, except value, which will be zero.
\n\t\t\t\t
1
The Date instance is greater than now or the passed Date, i.e. in the future
\n\t\t\t
\n\t\t\tNOTE: To make the diff Object's values easier to work with all other properties will be positive Numbers. You should use the tense property as your reference for the diff being in the past, present or future.\n\t\t
valueNumberThe — absolute — number of milliseconds difference between the two Dates.
yearsNumberThe number of years the Date instance is ahead or behind the passed Date.
monthsNumberThe months of years the Date instance is ahead or behind the passed Date.
weeksNumberThe weeks of years the Date instance is ahead or behind the passed Date.
daysNumberThe days of years the Date instance is ahead or behind the passed Date.
hoursNumberThe hours of years the Date instance is ahead or behind the passed Date.
minutesNumberThe minutes of years the Date instance is ahead or behind the passed Date.
secondsNumberThe seconds of years the Date instance is ahead or behind the passed Date.
millisecondsNumberThe number of milliseconds the Date instance is ahead or behind the passed Date or now.
\n\n**NOTE:** If any property — other than `tense` & `value` — is zero it will be omitted from the `diff` Object.\n\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 1 ) ) // returns => { tense : 0 }\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 2 ) ) // returns => { tense : -1, value : 86400000, days : 1 }\n\n ( new Date( 2012, 0, 2 ) ).diff( new Date( 2012, 0, 1 ) ) // returns => { tense : 1, value : 86400000, days : 1 }\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2010, 9, 8, 7, 6, 5, 4 ) ) // returns => { tense : 1, value : 38858034996, years : 1, months : 2, weeks : 3, days : 3, hours : 17, minutes : 53, seconds : 54, ms : 995 }\n\n```\n\n**NOTE:** You can supply a **space delimited** String defining which properties you want to exclude from the result and `diff` will either pass the current calculation to the next time unit or, if there are none will round off — up if over .5 or down if less, uses `Math.round` to figure this out — to the previous time unit.\n\nExclusion codes:\n- `-` will exclude the time unit from the `diff` Object.\n- `+` will include the time unit in the `diff` Object. **Note:** this is the same as not including the time unit in the `exclusions` String.\n- `>` will exclude all time units from this time unit down from the `diff` Object.\n\n##### Example with exclusions:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 2 ), '-days' ) // returns => { tense : -1, value : 86400000, hours : 24 }\n\n ( new Date( 2012, 0, 2 ) ).diff( new Date( 2012, 0, 1 ), '-days' ) // returns => { tense : 1, value : 86400000, hours : 24 }\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2010, 9, 8, 7, 6, 5, 4 ), '-years -weeks >minutes' ) // returns => { tense : 1, value : 38858034996, months : 14, days : 29, hours : 18 }\n\n```\n\n#### format( format:String ):String\nReturns a string representation of the Date instance, based on the passed format. See the [Date formatting and parsing options](#date-formatting-and-parsing-options) below.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).format( 'c' ); // returns => \"2012-01-01T00:00:00.000Z\"\n // which is a short hand format for:\n ( new Date( 2012, 0, 1 ) ).format( 'Y-m-dH:i:s.u' ); // returns => \"2012-01-01T00:00:00.000Z\"\n\n ( new Date( 2012, 0, 1 ) ).format( 'l, nS F Y' ) // returns => \"Sunday, the 1st of January 2012\"\n\n```\n\nYou can use predefined formats found in `Date.formats`. **Hint:** You can do:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n console.dir( Date.formats );\n\n```\n\nwithin your browser's JavaScript console to see a list of available formats.\n\nPreviously used formats are also cached to save the overhead of having to create a `new Function` everytime you want to format a date.\n\n#### getDayOfYear():Number\nReturns the zero based day of the year.\n\n#### getFirstOfTheMonth():Date\nReturns a Date instance of the first day of this Date instance's month.\n\n#### getGMTOffset( [colon:Boolean] ):String\nReturns the Date instances offset from GMT.\n\n#### getISODay():Number\nReturns the ISO day of the week.\n\n#### getISODaysInYear():Number\nReturns the ISO number of days in the year.\n\n#### getISOFirstMondayOfYear():Date\nReturns the ISO first Monday of the year.\n\n#### getISOWeek():Number\nReturns the ISO week of the year\n\n#### getISOWeeksInYear():Number\nReturns the number of weeks in the ISO year.\n\n#### getLastOfTheMonth():Date\nReturns a Date instance of the last day of this Date instance's month.\n\n#### getWeek():Number\nReturns the week of the year, based on the `dayOfYear` divided by 7.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).getWeek(); // returns => 0\n ( new Date( 2012, 2, 13 ) ).getWeek(); // returns => 10\n ( new Date( 2012, 11, 31 ) ).getWeek(); // returns => 52\n\n```\n\n#### isDST():Boolean\nReturns true if the Date instance is within daylight savings time.\n\n#### isLeapYear():Boolean\nReturns true if the Date instance is a leap year.\n\n#### lexicalize( [now:Date, format:String] ):String\nReturns a String representation of the difference between the date instance and now, or the passed `Date`.\n\n#### Available formats\nThe default format is `approx`, however this can be over-written by changing the **locale** file and/ or by passing in the desired format to the method.\n\n\n\t\n\t\n
approxWill return an approximate difference. e.g. about 2 days ago; almost 1 and a half years from now.
exactWill return the exact difference, e.g. 2 days 3 hours and 5 minutes ago; 1 year, 4 months, 2 weeks, 1 day, 5 hours, 3 minutes and 7 seconds from now.
\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n\tvar date = new Date( 2012, 0, 1 );\n\n\tdate.clone().adjust( { hr : -3, day : -2 } ).lexicalize( date, 'approx' ); // returns => \"just over 2 days ago\"\n\tdate.clone().adjust( { hr : -3, day : -2 } ).lexicalize( date, 'exact' ); // returns => \"2 days and 3 hours ago\"\n\n\tdate.lexicalize( date.clone().adjust( { hr : -6, day : -2 } ), 'approx' ); // returns => \"almost 2 and a half days from now\"\n\tdate.lexicalize( date.clone().adjust( { hr : -6, day : -2 } ), 'exact' ); // returns => \"2 days and 6 hours from now\"\n\n```\n\n#### setWeek():Number(UnixTimeStamp)\nSets the week of the year from the 1st January.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n new Date( ( new Date( 2012, 0, 1 ) ).setWeek( 17 ) ); // returns => Date {Sun Apr 29 2012 00:00:00 GMT+0100 (BST)}\n\n ( new Date( 2012, 2, 13 ) ).setWeek( 17 ); // returns => 1335654000000 same as above\n\n ( new Date( 2012, 11, 31 ) ).setWeek( 17 ); // returns => 1335654000000\n\n```\n\n#### timezone():String\nReturns the JavaScript engine's Date.prototype.toString() timezone abbreviation.\n\n## Date formatting and parsing options\n\n### escaping characters\n\nIf you want to escape characters that are used by the Date parser you can wrap them between <>.\n\n#### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).format( 'l, jS F Y' ); // returns => \"Sunday, the 1st of January 2012\"\n\n```\n\n### day\n\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n
dDay of the month, 2 digits with leading zeros
DA textual representation of a day, three letters
jDay of the month without leading zeros
lA full textual representation of the day of the week
NISO-8601 numeric representation of the day of the week
SEnglish ordinal suffix for the day of the month, 2 characters
wNumeric representation of the day of the week
zThe day of the year (starting from 0)
\n### week\n\n\t\n
WISO-8601 week number of year, weeks starting on Monday
\n### month\n\n\t\n\t\n\t\n\t\n\t\n
FA full textual representation of a month
mNumeric representation of a month, with leading zeros
MA short textual representation of a month, three letters
nNumeric representation of a month, without leading zeros
tNumber of days in the given month
\n### year\n\n\t\n\t\n\t\n\t\n
LWhether it's a leap year
oISO-8601 year number. This has the same value as Y, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead.
YA full numeric representation of a year, 4 digits
yA two digit representation of a year
\n### time\n\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n
aLowercase Ante meridiem and Post meridiem
AUppercase Ante meridiem and Post meridiem
g12-hour format of an hour without leading zeros
G24-hour format of an hour without leading zeros
h12-hour format of an hour with leading zeros
H24-hour format of an hour with leading zeros
iMinutes with leading zeros
sSeconds, with leading zeros
uMilliseconds
\n### timezone\n\n\t\n\t\n\t\n\t\n
ODifference to Greenwich time (GMT) in hours
PDifference to Greenwich time (GMT) with colon between hours and minutes
TTimezone abbreviation
ZTimezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive.
\n### full date/time\n\n\t\n\t\n\t\n
cISO 8601 date
rRFC 2822 formatted date
USeconds since the Unix Epoch January 1 1970 00:00:00 GMT
\n### custom\n\n\t\n\t\n
ethis is a convenience for `date.lexicalize( 'exact' );`
xthis is a convenience for `date.lexicalize( 'approx' );`
\n\n## License\n\n(The MIT License)\n\nCopyright (c) 2011 christos \"constantology\" constandinou http://muigui.com\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n","readmeFilename":"Readme.md","bugs":{"url":"https://github.com/muigui/useful-date/issues"},"homepage":"https://github.com/muigui/useful-date","_id":"useful-date@0.0.6","dist":{"shasum":"88c45c496b6a5d7c02d00fe332e29cf2ca0092ef","tarball":"https://registry.npmjs.org/useful-date/-/useful-date-0.0.6.tgz","integrity":"sha512-yw+3qUm8qrevKVc8ScChJW4Dc3CPsVHYNltkdqZK0b2aJs73anPMt7K4CwLhoKuG9yDiX02iqJTTai8bAefpXg==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCADrKSf6r4Ft7cuy3Mq3W6hHxP82kQ1izKkFIiOE+hPQIhANbivjNK9+dDPI3UsswfEp8PjwbnHQjSqRtZbuItGsXV"}]},"_from":".","_npmVersion":"1.3.14","_npmUser":{"name":"constantology","email":"constantology@gmail.com"},"maintainers":[{"name":"constantology","email":"constantology@gmail.com"}]}},"readme":"\n# useful-date\n\n useful date parsing and formatting library.\n\n useful-date extends the `Date` and `Date.prototype` using `Object.defineProperty` — it **will not** create new enumerable methods and properties and it will not over-write any existing methods.\n\n## Installation\n\n Install with [component(1)](http://component.io):\n\n $ component install muigui/useful-date\n\n Install with npm:\n\n $ npm install useful-date\n\n\n## API\n\n### Static methods\n\n#### isLeapYear( year:String ):Boolean\nReturns true if the passed **4 digit** year is a leap year.\n\n**NOTE:** This method is located in the locale file. If your calendar system does not contain leap years, you can simply change the method to only `return false`.\n\n#### getOrdinal( date:Number ):String\nReturns the ordinal for a given date.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n Date.getOrdinal( 1 ); // returns => \"st\"\n Date.getOrdinal( 10 ); // returns => \"th\"\n Date.getOrdinal( 22 ); // returns => \"nd\"\n Date.getOrdinal( 33 ); // returns => \"rd\"\n\n```\n\n**NOTE:** Ordinals and the `getOrdinal` This method is located in the locale file. You can simply change the `ordinal` Array to your specific language; overwrite the `getOrdinal` method or both.\n\n#### setLeapYear( date:Date ):Void\nSets the inlcuded locale's February day count to the correct number of days, based on whether or not the date is a leap year or not.\n\n**NOTE:** This method is located in the locale file. If your calendar system does not contain leap years, you can simply change the method to do nothing.\n\n#### coerce( date:String, format:String ):Date\nTakes a date String and a format String based on the **Date formatting and parsing options** described below and returns a – hopefully – correct and valid Date.\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n Date.coerce( 'Sunday, the 1st of January 2012', 'l, jS F Y' ); // returns => Date { Sun Jan 01 2012 00:00:00 GMT+0000 (GMT) }\n Date.coerce( '2012-01-01T00:00:00+00:00', Date.formats.ISO_8601 ); // returns => Date { Sun Jan 01 2012 00:00:00 GMT+0000 (GMT) }\n\n```\n\n### Static properties\n\n#### filters\nAn Object of all the available filters for formatting a Date.\n\n**IMPORTANT: Don't change these unless you know what you are doing!**\n\n#### formats\nAn Object containing some default date formats:\n\n\t\n\t\n\t\n\t\n\t\n
ISO_8601Y-m-dH:i:sP
ISO_8601_SHORTY-m-d
RFC_850l, d-M-y H:i:s T
RFC_2822D, d M Y H:i:s O
sortableY-m-d H:i:sO
\n\n### Instance methods\n\n#### adjust( interval:Object|String[, value:Number] ):Date\nYour one stop shop for all Date arithmetic. Adjusts the Date based on the passed `interval`, by the passed numeric `value`.\n\n**Note:** The method also accepts a single Object param where each key is the interval and each value is the number to adjust the Date by.\n\n**Valid intervals are:** year, month, week, day, hr, min, sec, ms.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n var date = new Date( 2012, 0, 1 ); // Date {Sun Jan 01 2012 00:00:00 GMT+0000 (GMT)}\n\n date.adjust( Date.DAY, 1 ); // Date {Mon Jan 02 2012 00:00:00 GMT+0000 (GMT)}\n date.adjust( Date.HOUR, -1 ); // Date {Sun Jan 01 2012 23:00:00 GMT+0000 (GMT)}\n date.adjust( {\n year : -1, month : -1, day : 24,\n hr : 1, sec : -1\n } ); // Date {Sat Dec 25 2010 23:59:59 GMT+0000 (GMT)}\n\n```\n\n#### between( date_lower:Date, date_higher:Date ):Boolean\nChecks to see if the Date instance is in between the two passed Dates.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n var date = new Date( 2012, 0, 1 );\n\n date.between( new Date( 2011, 0, 1 ), new Date( 2013, 0, 1 ) ); // returns => true;\n\n date.between( new Date( 2013, 0, 1 ), new Date( 2011, 0, 1 ) ); // returns => false;\n\n```\n\n#### clearTime():Date\nClears the time from the Date instance.\n\n#### clone():Date\nReturns a clone of the current Date.\n\n#### diff( [date:Date, exclude:String] ):Object\nReturns an Object describing the difference between the Date instance and now — or the optionally passed Date.\n\nThe Object will contain any or all of the following properties:\n\n\n\t\n\t\t\n\t\n\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\n
PropTypeDescription
tenseNumberThis will either be:\n\t\t\t
\n\t\t\t\t
-1
The Date instance is less than now or the passed Date, i.e. in the past
\n\t\t\t\t
0
The Date instance is equal to now or the passed Date, i.e. in the present.
NOTE: If tense is 0 then the Object will most probably have no other properties, except value, which will be zero.
\n\t\t\t\t
1
The Date instance is greater than now or the passed Date, i.e. in the future
\n\t\t\t
\n\t\t\tNOTE: To make the diff Object's values easier to work with all other properties will be positive Numbers. You should use the tense property as your reference for the diff being in the past, present or future.\n\t\t
valueNumberThe — absolute — number of milliseconds difference between the two Dates.
yearsNumberThe number of years the Date instance is ahead or behind the passed Date.
monthsNumberThe months of years the Date instance is ahead or behind the passed Date.
weeksNumberThe weeks of years the Date instance is ahead or behind the passed Date.
daysNumberThe days of years the Date instance is ahead or behind the passed Date.
hoursNumberThe hours of years the Date instance is ahead or behind the passed Date.
minutesNumberThe minutes of years the Date instance is ahead or behind the passed Date.
secondsNumberThe seconds of years the Date instance is ahead or behind the passed Date.
millisecondsNumberThe milliseconds of years the Date instance is ahead or behind the passed Date.
\n\n**NOTE:** If any property — other than `tense` & `value` — is zero it will be omitted from the `diff` Object.\n\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 1 ) ) // returns => { tense : 0 }\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 2 ) ) // returns => { tense : -1, value : 86400000, days : 1 }\n\n ( new Date( 2012, 0, 2 ) ).diff( new Date( 2012, 0, 1 ) ) // returns => { tense : 1, value : 86400000, days : 1 }\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2010, 9, 8, 7, 6, 5, 4 ) ) // returns => { tense : 1, value : 38858034996, years : 1, months : 2, weeks : 3, days : 3, hours : 17, minutes : 53, seconds : 54, ms : 995 }\n\n```\n\n**NOTE:** You can supply a **space delimited** String defining which properties you want to exclude from the result and `diff` will either pass the current calculation to the next time unit or, if there are none will round off — up if over .5 or down if less, uses `Math.round` to figure this out — to the previous time unit.\n\nExclusion codes:\n- `-` will exclude the time unit from the `diff` Object.\n- `+` will include the time unit in the `diff` Object. **Note:** this is the same as not including the time unit in the `exclusions` String.\n- `>` will exclude all time units from this time unit down from the `diff` Object.\n\n##### Example with exclusions:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 2 ), '-days' ) // returns => { tense : -1, value : 86400000, hours : 24 }\n\n ( new Date( 2012, 0, 2 ) ).diff( new Date( 2012, 0, 1 ), '-days' ) // returns => { tense : 1, value : 86400000, hours : 24 }\n\n ( new Date( 2012, 0, 1 ) ).diff( new Date( 2010, 9, 8, 7, 6, 5, 4 ), '-years -weeks >minutes' ) // returns => { tense : 1, value : 38858034996, months : 14, days : 29, hours : 18 }\n\n```\n\n#### format( format:String ):String\nReturns a string representation of the Date instance, based on the passed format. See the [Date formatting and parsing options](#date-formatting-and-parsing-options) below.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).format( 'c' ); // returns => \"2012-01-01T00:00:00.000Z\"\n // which is a short hand format for:\n ( new Date( 2012, 0, 1 ) ).format( 'Y-m-dH:i:s.u' ); // returns => \"2012-01-01T00:00:00.000Z\"\n\n ( new Date( 2012, 0, 1 ) ).format( 'l, nS F Y' ) // returns => \"Sunday, the 1st of January 2012\"\n\n```\n\nYou can use predefined formats found in `Date.formats`. **Hint:** You can do:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n console.dir( Date.formats );\n\n```\n\nwithin your browser's JavaScript console to see a list of available formats.\n\nPreviously used formats are also cached to save the overhead of having to create a `new Function` everytime you want to format a date.\n\n#### getDayOfYear():Number\nReturns the zero based day of the year.\n\n#### getFirstOfTheMonth():Date\nReturns a Date instance of the first day of this Date instance's month.\n\n#### getGMTOffset( [colon:Boolean] ):String\nReturns the Date instances offset from GMT.\n\n#### getISODay():Number\nReturns the ISO day of the week.\n\n#### getISODaysInYear():Number\nReturns the ISO number of days in the year.\n\n#### getISOFirstMondayOfYear():Date\nReturns the ISO first Monday of the year.\n\n#### getISOWeek():Number\nReturns the ISO week of the year\n\n#### getISOWeeksInYear():Number\nReturns the number of weeks in the ISO year.\n\n#### getLastOfTheMonth():Date\nReturns a Date instance of the last day of this Date instance's month.\n\n#### getWeek():Number\nReturns the week of the year, based on the `dayOfYear` divided by 7.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).getWeek(); // returns => 0\n ( new Date( 2012, 2, 13 ) ).getWeek(); // returns => 10\n ( new Date( 2012, 11, 31 ) ).getWeek(); // returns => 52\n\n```\n\n#### isDST():Boolean\nReturns true if the Date instance is within daylight savings time.\n\n#### isLeapYear():Boolean\nReturns true if the Date instance is a leap year.\n\n#### lexicalize( [now:Date, format:String] ):String\nReturns a String representation of the difference between the date instance and now, or the passed `Date`.\n\n#### Available formats\nThe default format is `approx`, however this can be over-written by changing the **locale** file and/ or by passing in the desired format to the method.\n\n\n\t\n\t\n
approxWill return an approximate difference. e.g. about 2 days ago; almost 1 and a half years from now.
exactWill return the exact difference, e.g. 2 days 3 hours and 5 minutes ago; 1 year, 4 months, 2 weeks, 1 day, 5 hours, 3 minutes and 7 seconds from now.
\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n\tvar date = new Date( 2012, 0, 1 );\n\n\tdate.clone().adjust( { hr : -3, day : -2 } ).lexicalize( date, 'approx' ); // returns => \"just over 2 days ago\"\n\tdate.clone().adjust( { hr : -3, day : -2 } ).lexicalize( date, 'exact' ); // returns => \"2 days and 3 hours ago\"\n\n\tdate.lexicalize( date.clone().adjust( { hr : -6, day : -2 } ), 'approx' ); // returns => \"almost 2 and a half days from now\"\n\tdate.lexicalize( date.clone().adjust( { hr : -6, day : -2 } ), 'exact' ); // returns => \"2 days and 6 hours from now\"\n\n```\n\n#### setWeek():Number(UnixTimeStamp)\nSets the week of the year from the 1st January.\n\n##### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n new Date( ( new Date( 2012, 0, 1 ) ).setWeek( 17 ) ); // returns => Date {Sun Apr 29 2012 00:00:00 GMT+0100 (BST)}\n\n ( new Date( 2012, 2, 13 ) ).setWeek( 17 ); // returns => 1335654000000 same as above\n\n ( new Date( 2012, 11, 31 ) ).setWeek( 17 ); // returns => 1335654000000\n\n```\n\n#### timezone():String\nReturns the JavaScript engine's Date.prototype.toString() timezone abbreviation.\n\n## Date formatting and parsing options\n\n### escaping characters\n\nIf you want to escape characters that are used by the Date parser you can wrap them between <>.\n\n#### Example:\n\n```javascript\n\n\trequire( 'useful-date' );\n\trequire( 'useful-date/locale/en-GB.js' );\n\n ( new Date( 2012, 0, 1 ) ).format( 'l, jS F Y' ); // returns => \"Sunday, the 1st of January 2012\"\n\n```\n\n### day\n\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n
dDay of the month, 2 digits with leading zeros
DA textual representation of a day, three letters
jDay of the month without leading zeros
lA full textual representation of the day of the week
NISO-8601 numeric representation of the day of the week
SEnglish ordinal suffix for the day of the month, 2 characters
wNumeric representation of the day of the week
zThe day of the year (starting from 0)
\n### week\n\n\t\n
WISO-8601 week number of year, weeks starting on Monday
\n### month\n\n\t\n\t\n\t\n\t\n\t\n
FA full textual representation of a month
mNumeric representation of a month, with leading zeros
MA short textual representation of a month, three letters
nNumeric representation of a month, without leading zeros
tNumber of days in the given month
\n### year\n\n\t\n\t\n\t\n\t\n
LWhether it's a leap year
oISO-8601 year number. This has the same value as Y, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead.
YA full numeric representation of a year, 4 digits
yA two digit representation of a year
\n### time\n\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n\t\n
aLowercase Ante meridiem and Post meridiem
AUppercase Ante meridiem and Post meridiem
g12-hour format of an hour without leading zeros
G24-hour format of an hour without leading zeros
h12-hour format of an hour with leading zeros
H24-hour format of an hour with leading zeros
iMinutes with leading zeros
sSeconds, with leading zeros
uMilliseconds
\n### timezone\n\n\t\n\t\n\t\n\t\n
ODifference to Greenwich time (GMT) in hours
PDifference to Greenwich time (GMT) with colon between hours and minutes
TTimezone abbreviation
ZTimezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive.
\n### full date/time\n\n\t\n\t\n\t\n
cISO 8601 date
rRFC 2822 formatted date
USeconds since the Unix Epoch January 1 1970 00:00:00 GMT
\n### custom\n\n\t\n\t\n
ethis is a convenience for `date.lexicalize( 'exact' );`
xthis is a convenience for `date.lexicalize( 'approx' );`
\n\n## License\n\n(The MIT License)\n\nCopyright (c) 2011 christos \"constantology\" constandinou http://muigui.com\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n","maintainers":[{"name":"constantology","email":"constantology@gmail.com"}],"time":{"modified":"2022-06-28T06:42:26.997Z","created":"2013-08-20T12:56:44.947Z","0.0.1":"2013-08-20T12:56:48.200Z","0.0.2":"2013-08-22T11:28:20.193Z","0.0.3":"2013-09-30T21:51:23.918Z","0.0.4":"2013-10-01T09:22:07.736Z","0.0.5":"2013-10-02T22:40:25.077Z","0.0.6":"2013-11-25T10:11:01.559Z"},"author":{"name":"constantology","email":"christos@muigui.com","url":"http://muigui.com"},"repository":{"type":"git","url":"git@github.com:muigui/useful-date.git"},"users":{"muzzlefork":true,"eklem":true,"xgheaven":true,"waitfish":true,"erikvold":true}}