From: Tim Wood Date: Fri, 3 Feb 2012 18:44:42 +0000 (-0800) Subject: Building docs X-Git-Tag: 1.4.0~4 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ad152bb2eeedd971efed7440ff47b90b87e84586;p=thirdparty%2Fmoment.git Building docs #156 #154 #148 #133 --- diff --git a/site/docs/index.html b/site/docs/index.html index 31260c0f3..368efa1c9 100644 --- a/site/docs/index.html +++ b/site/docs/index.html @@ -1,4 +1,4 @@ -Moment.js Documentation

Moment.js Documentation

A lightweight javascript date library for parsing, manipulating, and formatting dates.

Where to get it

Github

Production Version 1.3.03.3kb minified & gzippedDevelopment Version 1.3.022.5kb full source + comments

You can also clone the project with Git by running:

git clone git://github.com/timrwood/moment

npm

npm install moment

Where to use it

Moment was designed to work in both the browser and in NodeJS. All code will work in both environments. All unit tests are run in both environments.

In NodeJS

var moment = require('moment');
+Moment.js Documentation
Moment.js Documentation
A lightweight javascript date library for parsing, manipulating, and formatting dates.
Where to get it
Github
Production Version 1.3.03.3kb minified & gzippedDevelopment Version 1.3.022.5kb full source + comments
You can also clone the project with Git by running:
git clone git://github.com/timrwood/moment
npm
npm install moment
Where to use it
Moment was designed to work in both the browser and in NodeJS. All code will work in both environments. All unit tests are run in both environments.
In NodeJS
var moment = require('moment');
 moment().add('hours', 1).fromNow(); // "1 hour ago"
 
In the browser
<script src="moment.min.js"></script>
 moment().add('hours', 1).fromNow(); // "1 hour ago"
@@ -28,8 +28,20 @@ var day = moment([2010, 6]); // July 1st
 var day = moment([2010, 6, 10]); // July 10th
 
Construction with an array will create a date in the current timezone. To create a date from an array at UTC, you can use the following.
var array = [2010, 1, 14, 15, 25, 50, 125];
 var day = moment(Date.UTC.apply({}, array));
-
Manipulation
Once you have a Moment.js wrapper object, you may want to manipulate it in some way. There are a number of moment.fnmethods to help with this.
-
All manipulation methods are chainable, so you can do crazy things like this.
moment().add('days', 7).subtract('months', 1).year(2009).hours(0).minutes(0).seconds(0);
Adding Time
This is a pretty robust function for adding time to an existing date. To add time, pass the key of what time you want to add, and the amount you want to add.
+

ASP.NET style json dates

ASP.NET returns dates in json in the following formats. /Date(1198908717056)/ or +/Date(1198908717056-0700)/

If a string that matches this format is passed in, it will be parsed correctly.

moment("/Date(1198908717056-0700)/").valueOf(); // 1198908717056

Cloning

All moments are mutable. If you want a clone of a moment, you can do so explicitly or implicitly.

Calling moment() on a moment will clone it. +

var a = moment([2012]);
+var b = moment(a);
+a.year(2000);
+b.year(); // 2012
+

Additionally, you can call moment.fn.clone to clone a moment. +

var a = moment([2012]);
+var b = a.clone();
+a.year(2000);
+b.year(); // 2012
+

Manipulation

Once you have a Moment.js wrapper object, you may want to manipulate it in some way. There are a number of moment.fn methods to help with this. +

All manipulation methods are chainable, so you can do crazy things like this.

moment().add('days', 7).subtract('months', 1).year(2009).hours(0).minutes(0).seconds(0);

It should be noted that moments are mutable. Calling any of the manipulation methods will change the original moment.

If you want to create a copy and manipulate it, you should use moment.fn.clone before manipulating the moment. +More info on cloning.

Adding Time

This is a pretty robust function for adding time to an existing date. To add time, pass the key of what time you want to add, and the amount you want to add. 

moment().add('days', 7);

There are some shorthand keys as well if you're into that whole brevity thing.

moment().add('d', 7);
KeyShorthand
yearsy
monthsM
weeksw
daysd
hoursh
minutesm
secondss
millisecondsms

If you want to add multiple different keys at the same time, you can pass them in as an object literal.

moment().add('days', 7).add('months', 1); // with chaining 
 moment().add({days:7,months:1}); // with object literal

There are no upper limits for the amounts, so you can overload any of the parameters.

moment().add('milliseconds', 1000000); // a million milliseconds 
@@ -57,13 +69,14 @@ moment().milliseconds() === new Date().getMilliseconds();
 moment().day(7); // set to next Sunday (0 + 7)
 moment().day(10); // set to next Wednesday (3 + 7)
 moment().day(24); // set to 3 Wednesdays from now (3 + 7 + 7 + 7)
-

Month

Accepts numbers from 0 to 11

moment().month(5); // set the month to June

Year

moment().year(1984); // set the year to 1984

Start of Day

moment().sod(); // set the time to last midnight

End of Day

moment().eod(); // set the time to 11:59:59.999 pm tonight

Display

Once parsing and manipulation are done, you need some way to display the moment. Moment.js offers many ways of doing that.

Formatted Date

The most robust display option is moment.fn.format. It takes a string of tokens and replaces them with their corresponding values from the Date object. +

Month

Accepts numbers from 0 to 11

moment().month(5); // set the month to June

Year

moment().year(1984); // set the year to 1984

Start of Day

moment().sod(); // set the time to last midnight

This is essentially the same as the following.

moment().hours(0).minutes(0).seconds(0).milliseconds(0);

End of Day

moment().eod(); // set the time to 11:59:59.999 pm tonight

This is essentially the same as the following.

moment().hours(23).minutes(59).seconds(59).milliseconds(999);

Display

Once parsing and manipulation are done, you need some way to display the moment. Moment.js offers many ways of doing that.

Formatted Date

The most robust display option is moment.fn.format. It takes a string of tokens and replaces them with their corresponding values from the Date object. 

var date = new Date(2010, 1, 14, 15, 25, 50, 125);
 moment(date).format("dddd, MMMM Do YYYY, h:mm:ss a"); // "Sunday, February 14th 2010, 3:25:50 pm"
 moment(date).format("ddd, hA");                       // "Sun, 3PM"
TokenOutput
Month
M1 2 ... 11 12
Mo1st 2nd ... 11th 12th
MM01 02 ... 11 12
MMMJan Feb ... Nov Dec
MMMMJanuary February ... November December
Day of Month
D1 2 ... 30 30
Do1st 2nd ... 30th 31st
DD01 02 ... 30 31
Day of Year
DDD1 2 ... 364 365
DDDo1st 2nd ... 364th 365th
DDDD001 002 ... 364 365
Day of Week
d0 1 ... 5 6
do0th 1st ... 5th 6th
dddSun Mon ... Fri Sat
ddddSunday Monday ... Friday Saturday
Week of Year
w1 2 ... 52 53
wo1st 2nd ... 52nd 53rd
ww01 02 ... 52 53
Year
YY70 71 ... 29 30
YYYY1970 1971 ... 2029 2030
AM/PM
AAM PM
aam pm
Hour
H0 1 ... 22 23
HH00 01 ... 22 23
h1 2 ... 11 12
hh01 02 ... 11 12
Minute
m0 1 ... 58 59
mm00 01 ... 58 59
Second
s0 1 ... 58 59
ss00 01 ... 58 59
Timezone
z or zz (lowercase)EST CST ... MST PST
Z-07:00 -06:00 ... +06:00 +07:00
ZZ-0700 -0600 ... +0600 +0700
Localized date format
LT8:30 PM
L07/10/1986
LLJuly 10 1986
LLLJuly 10 1986 8:30 PM
LLLLSaturday, July 10 1986 8:30 PM

To escape characters in format strings, you can use a backslash before any character. NOTE: if you are using a string literal, you will need to escape the backslash, hence the double backslash below.

moment().format('\\L'); // outputs 'L'

To escape multiple characters, you can wrap the characters in square brackets.

moment().format('[today] DDDD'); // 'today Sunday'

While these date formats are very similar to LDML date formats, there are a few minor differences regarding day of month, day of year, and day of week.

For a breakdown of a few different date formatting tokens, see this chart of date formatting tokens.

To compare moment.js date formatting speeds against other libraries, check out http://jsperf.com/date-formatting .

Note: Baron Schwartz wrote a pretty cool date formatter that caches formatting functions to avoid expensive regex or string splitting. It's so much faster than any of the other libraries, that it's best to compare it on its own, rather than pollute the "best of the uncompiled" formatting libs.

Here's the moment.js vs xaprb performance tests, and here is the -article describing his methods.

Time from another moment

Another common way of displaying time, sometimes called timeago, is handled by moment.fn.from. +article describing his methods.

If you are more comfortable working with strftime instead of LDML-like parsing tokens, you can use Ben Oakes' plugin moment-strftime . +

It is available on npm.

npm install moment-strftime

The repository is located at benjaminoakes/moment-strftime

Time from another moment

Another common way of displaying time, sometimes called timeago, is handled by moment.fn.from. 

var a = moment([2007, 0, 29]);
 var b = moment([2007, 0, 28]);
 a.from(b) // "a day ago"
@@ -108,8 +121,10 @@ a.diff(b, 'days') // 1
 var b = moment([2008, 5]);
 a.diff(b, 'years')       // 1
 a.diff(b, 'years', true) // 1.5
-

Native Date

To get the native Date object that Moment.js wraps, use moment.fn.native. -

moment([2007, 0, 29]).native(); // returns native Date object

Value

moment.fn.valueOfsimply outputs the unix timestamp. +

Native Javascript Date

To get the native Date object that Moment.js wraps, use moment.fn.toDate. +

moment([2007, 0, 29]).toDate(); // returns native Date object

Note: moment.fn.native has been replaced by +moment.fn.toDate and will be depreciated in the future. +

Value

moment.fn.valueOfsimply outputs the unix timestamp. 

moment(1318874398806).valueOf(); // 1318874398806

Milliseconds

These are the getters mentioned in the Manipulationsection above.

These map to the corresponding function on the native Dateobject. 

moment().milliseconds() === new Date().getMilliseconds();
moment().milliseconds(); // get the milliseconds (0 - 999)

Seconds

moment().minutes(); // get the seconds (0 - 59)

Minutes

moment().minutes(); // get the minutes (0 - 59)

Hours

moment().hours(); // get the hours (0 - 23)

Date

moment().date(); // get the date of the month (1 - 31)

Day

moment().day(); // get the day of the week (0 - 6)

Month

moment().month(); // get the month (0 - 11)

Year

moment().year(); // get the four digit year

Leap Year

moment.fn.isLeapYearreturns true if that year is a leap year, and false if it is not. @@ -250,7 +265,8 @@ moment(1316116057189).fromNow(); // il y a une heure (b === 2) ? 'nd' : (b === 3) ? 'rd' : 'th'; }; -

For more information on ordinal numbers, see wikipedia