|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204 |
- # dateformat
-
- A node.js package for Steven Levithan's excellent [dateFormat()][dateformat] function.
-
- [](https://travis-ci.org/felixge/node-dateformat)
-
- ## Modifications
-
- - Removed the `Date.prototype.format` method. Sorry folks, but extending native prototypes is for suckers.
- - Added a `module.exports = dateFormat;` statement at the bottom
- - Added the placeholder `N` to get the ISO 8601 numeric representation of the day of the week
-
- ## Installation
-
- ```bash
- $ npm install dateformat
- $ dateformat --help
- ```
-
- ## Usage
-
- As taken from Steven's post, modified to match the Modifications listed above:
-
- ```js
- var dateFormat = require("dateformat");
- var now = new Date();
-
- // Basic usage
- dateFormat(now, "dddd, mmmm dS, yyyy, h:MM:ss TT");
- // Saturday, June 9th, 2007, 5:46:21 PM
-
- // You can use one of several named masks
- dateFormat(now, "isoDateTime");
- // 2007-06-09T17:46:21
-
- // ...Or add your own
- dateFormat.masks.hammerTime = 'HH:MM! "Can\'t touch this!"';
- dateFormat(now, "hammerTime");
- // 17:46! Can't touch this!
-
- // You can also provide the date as a string
- dateFormat("Jun 9 2007", "fullDate");
- // Saturday, June 9, 2007
-
- // Note that if you don't include the mask argument,
- // dateFormat.masks.default is used
- dateFormat(now);
- // Sat Jun 09 2007 17:46:21
-
- // And if you don't include the date argument,
- // the current date and time is used
- dateFormat();
- // Sat Jun 09 2007 17:46:22
-
- // You can also skip the date argument (as long as your mask doesn't
- // contain any numbers), in which case the current date/time is used
- dateFormat("longTime");
- // 5:46:22 PM EST
-
- // And finally, you can convert local time to UTC time. Simply pass in
- // true as an additional argument (no argument skipping allowed in this case):
- dateFormat(now, "longTime", true);
- // 10:46:21 PM UTC
-
- // ...Or add the prefix "UTC:" or "GMT:" to your mask.
- dateFormat(now, "UTC:h:MM:ss TT Z");
- // 10:46:21 PM UTC
-
- // You can also get the ISO 8601 week of the year:
- dateFormat(now, "W");
- // 42
-
- // and also get the ISO 8601 numeric representation of the day of the week:
- dateFormat(now, "N");
- // 6
- ```
-
- ### Mask options
-
- | Mask | Description |
- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | `d` | Day of the month as digits; no leading zero for single-digit days. |
- | `dd` | Day of the month as digits; leading zero for single-digit days. |
- | `ddd` | Day of the week as a three-letter abbreviation. |
- | `DDD` | "Ysd", "Tdy" or "Tmw" if date lies within these three days. Else fall back to ddd. |
- | `dddd` | Day of the week as its full name. |
- | `DDDD` | "Yesterday", "Today" or "Tomorrow" if date lies within these three days. Else fall back to dddd. |
- | `m` | Month as digits; no leading zero for single-digit months. |
- | `mm` | Month as digits; leading zero for single-digit months. |
- | `mmm` | Month as a three-letter abbreviation. |
- | `mmmm` | Month as its full name. |
- | `yy` | Year as last two digits; leading zero for years less than 10. |
- | `yyyy` | Year represented by four digits. |
- | `h` | Hours; no leading zero for single-digit hours (12-hour clock). |
- | `hh` | Hours; leading zero for single-digit hours (12-hour clock). |
- | `H` | Hours; no leading zero for single-digit hours (24-hour clock). |
- | `HH` | Hours; leading zero for single-digit hours (24-hour clock). |
- | `M` | Minutes; no leading zero for single-digit minutes. |
- | `MM` | Minutes; leading zero for single-digit minutes. |
- | `N` | ISO 8601 numeric representation of the day of the week. |
- | `o` | GMT/UTC timezone offset, e.g. -0500 or +0230. |
- | `p` | GMT/UTC timezone offset, e.g. -05:00 or +02:30. |
- | `s` | Seconds; no leading zero for single-digit seconds. |
- | `ss` | Seconds; leading zero for single-digit seconds. |
- | `S` | The date's ordinal suffix (st, nd, rd, or th). Works well with `d`. |
- | `l` | Milliseconds; gives 3 digits. |
- | `L` | Milliseconds; gives 2 digits. |
- | `t` | Lowercase, single-character time marker string: a or p. |
- | `tt` | Lowercase, two-character time marker string: am or pm. |
- | `T` | Uppercase, single-character time marker string: A or P. |
- | `TT` | Uppercase, two-character time marker string: AM or PM. |
- | `W` | ISO 8601 week number of the year, e.g. 4, 42 |
- | `WW` | ISO 8601 week number of the year, leading zero for single-digit, e.g. 04, 42 |
- | `Z` | US timezone abbreviation, e.g. EST or MDT. For non-US timezones, the GMT/UTC offset is returned, e.g. GMT-0500 |
- | `'...'`, `"..."` | Literal character sequence. Surrounding quotes are removed. |
- | `UTC:` | Must be the first four characters of the mask. Converts the date from local time to UTC/GMT/Zulu time before applying the mask. The "UTC:" prefix is removed. |
-
- ### Named Formats
-
- | Name | Mask | Example |
- | ----------------- | ------------------------------ | ------------------------ |
- | `default` | `ddd mmm dd yyyy HH:MM:ss` | Sat Jun 09 2007 17:46:21 |
- | `shortDate` | `m/d/yy` | 6/9/07 |
- | `paddedShortDate` | `mm/dd/yyyy` | 06/09/2007 |
- | `mediumDate` | `mmm d, yyyy` | Jun 9, 2007 |
- | `longDate` | `mmmm d, yyyy` | June 9, 2007 |
- | `fullDate` | `dddd, mmmm d, yyyy` | Saturday, June 9, 2007 |
- | `shortTime` | `h:MM TT` | 5:46 PM |
- | `mediumTime` | `h:MM:ss TT` | 5:46:21 PM |
- | `longTime` | `h:MM:ss TT Z` | 5:46:21 PM EST |
- | `isoDate` | `yyyy-mm-dd` | 2007-06-09 |
- | `isoTime` | `HH:MM:ss` | 17:46:21 |
- | `isoDateTime` | `yyyy-mm-dd'T'HH:MM:sso` | 2007-06-09T17:46:21+0700 |
- | `isoUtcDateTime` | `UTC:yyyy-mm-dd'T'HH:MM:ss'Z'` | 2007-06-09T22:46:21Z |
-
- ### Localization
-
- Day names, month names and the AM/PM indicators can be localized by
- passing an object with the necessary strings. For example:
-
- ```js
- var dateFormat = require("dateformat");
- dateFormat.i18n = {
- dayNames: [
- "Sun",
- "Mon",
- "Tue",
- "Wed",
- "Thu",
- "Fri",
- "Sat",
- "Sunday",
- "Monday",
- "Tuesday",
- "Wednesday",
- "Thursday",
- "Friday",
- "Saturday",
- ],
- monthNames: [
- "Jan",
- "Feb",
- "Mar",
- "Apr",
- "May",
- "Jun",
- "Jul",
- "Aug",
- "Sep",
- "Oct",
- "Nov",
- "Dec",
- "January",
- "February",
- "March",
- "April",
- "May",
- "June",
- "July",
- "August",
- "September",
- "October",
- "November",
- "December",
- ],
- timeNames: ["a", "p", "am", "pm", "A", "P", "AM", "PM"],
- };
- ```
-
- > Notice that only one language is supported at a time and all strings
- > _must_ be present in the new value.
-
- ### Breaking change in 2.1.0
-
- - 2.1.0 was published with a breaking change, for those using localized strings.
- - 2.2.0 has been published without the change, to keep packages refering to ^2.0.0 to continue working. This is now branch v2_2.
- - 3.0.\* contains the localized AM/PM change.
-
- ## License
-
- (c) 2007-2009 Steven Levithan [stevenlevithan.com][stevenlevithan], MIT license.
-
- [dateformat]: http://blog.stevenlevithan.com/archives/date-time-format
- [stevenlevithan]: http://stevenlevithan.com/
|
