@version 17.7.0
@date 2017-07-14
@stability 2 - Unstable
Date format – 
A small library for parsing and formatting dates that extends native Date object.
Install
npm install date-format-lite –save
require("date-format-lite")
Format Dates
date-format-lite adds format(mask, [zone]) method to native Date.prototype.
- mask
String- Output format, e.g.hh:mm:ss. - zone
Number, optional- UTC offset in hours, e.g.-6.5.
var now = new Date() // Date {Wed Jul 10 2013 16:47:36 GMT+0300 (EEST)}
now.format("iso") // 2013-07-10T13:47:36Z
now.format("hh:mm") // 16:47 (local time)
now.format("UTC:hh:mm") // 13:47
now.format("hh:mm", 2.5) // 16:17
Mutate Dates
date-format-lite adds add(amount, [unit]) method to native Date.prototype.
- amount
Number- Time to add, negative number will be subtracted. - unit
String, optional- e.g. seconds, minutes, hours, days, weeks, months, years.
now.format("iso") // 2013-07-10T13:47:36Z
now.add(1, "days").format("iso") // 2013-07-11T13:47:36Z
now.add(-2, "hours").format("iso") // 2013-07-11T11:47:36Z
Parse Dates
date-format-lite adds date([outFormat], [outZone], [inZone]) method
to native String.prototype and Number.prototype.
- outFormat
String, optional- Output format, e.g.hh:mm:ss. Returns date object when format not specified. - outZone
Number, optional- UTC offset for output in hours, e.g.-6.5. - inZone
Number, optional- UTC offset in input in hours, e.g.-6.5.
"2013-07-10".date() // Date {Wed Jul 10 2013 03:00:00 GMT+0300 (EEST)}
"2013-07-10T13:47:36Z".date() // Date {Wed Jul 10 2013 16:47:36 GMT+0300 (EEST)}
"10/07/2013".date() // Date {Wed Jul 10 2013 03:00:00 GMT+0300 (EEST)}
Date.middleEndian = true
"10/07/2013".date() // Date {Mon Oct 07 2013 03:00:00 GMT+0300 (EEST)}
// Change format
"10/07/2013".date("YYYY-MM-DD")// 2013-07-10
Add custom formats
Date.masks.my = '"DayNo "D'
now.format("my") // DayNo 10
Change default format
Date.masks.default = 'YYYY-MM-DD hh:mm:ss'
now.format() // 2013-07-10 13:47:36
Change language
// Add to estonian-lang.js
Date.names = "Jaan Veeb Märts Apr Mai Juuni Juuli Aug Sept Okt Nov Dets jaanuar veebruar märts aprill mai juuni juuli august september oktoober november detsember P E T K N R L pühapäev esmaspäev teisipäev kolmapäev neljapäev reede laupäev".split(" ")
// Change AM and PM
Date.am = "a.m."
Date.pm = "p.m."
See tests for more examples
Syntax
- Y - A two digit representation of a year without leading zeros. Examples: 99 or 3
- YY - A two digit representation of a year. Examples: 99 or 03
- YYYY - A full numeric representation of a year, 4 digits. Examples: 1999 or 2003
- M - Numeric representation of a month, without leading zeros. 1 through 12
- MM - Numeric representation of a month, with leading zeros. 01 through 12
- MMM - A short textual representation of a month, three letters. Jan through Dec
- MMMM - A full textual representation of a month, such as January or March. January through December
- D - Day of the month without leading zeros. 1 to 31
- DD - Day of the month, 2 digits with leading zeros. 01 to 31
- DDD - A textual representation of a day, three letters. Mon through Sun
- DDDD - A full textual representation of the day of the week. Sunday through Saturday
- H - 12-hour format of an hour without leading zeros. 1 through 12
- HH - 12-hour format of an hour with leading zeros. 01 through 12
- h - 24-hour format of an hour without leading zeros. 0 through 23
- hh - 24-hour format of an hour with leading zeros. 00 through 23
- m - Minutes without leading zeros. 0 through 59
- mm - Minutes with leading zeros. 00 to 59
- s - Seconds without leading zeros. 0 through 59
- ss - Seconds with leading zeros. 00 to 59
- S - Milliseconds without leading zeros. 0 through 999
- SS - Milliseconds with leading zeros. 000 to 999
- U - Milliseconds since the Unix Epoch (January 1 1970 00:00:00 GMT)
- u - Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)
- A - Ante meridiem and Post meridiem. AM or PM
- “text” - text, quotes should be escaped, eg ‘“a \“quoted text\”” YYYY’
Time zone designators
- Z - Time offsets from UTC in the form ±hh[:mm] Examples: +02, +02:30
- ZZ - Time offsets from UTC in the form ±hh[mm] Examples: +02, +0230
- ZZZ - Time offsets from UTC in the form ±hh:mm Examples: +02:00, +02:30
- ZZZZ - Time offsets from UTC in the form ±hhmm Examples: +0200, +0230
ISO-8601
- w - Day of the week. 1 (for Monday) through 7 (for Sunday)
- W - Week number of year, first week is the week with 4 January in it
- o - ISO-8601 year number. This has the same value as YYYY, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead
Notes
- If no UTC relation information is given with a time representation, the time is assumed to be in local time.
- If the time is in UTC, add a Z directly after the time without a space.
ToDo
- Add timezone support for Date.format
Browser Support
It should work IE6 and up but automated testing is currently broken.
Links
Licence
Copyright (c) 2012-2016 Lauri Rooden <lauri@rooden.ee>
The MIT License
Have an update or suggestion for this note? You can edit it and send me a pull request.
