The SC.DateTime class is a wrapper around the native JavaScript Date object. You are encouraged to use SC.DateTime rather than the Date object since it provides much more functionality and flexibility. 

Creating dates

To create a SC.DateTime instance initialized to the current local time, simply call the create method:

var now = SC.DateTime.create(); 

To initialize the object to a specific date and time, pass a hash argument with the wanted values:

var date = SC.DateTime.create({

year: 1985,
month: 5,
day: 8,
hour: 1,
minute: 0,
second: 22,
millisecond: 925,
timezone: -120}); 

Omitted values will be defaulted to the current local date and time:

var todayAtFour = SC.DateTime.create({ hour: 16 }); 

Note that if you set the hour and none of the minute, second and millisecond, then they will be cascadingly reseted to 0. Similarly, if you set the minute and none of the second and millisecond, they will be cascadingly reseted to 0, etc. Therefore, the previous example returns an object initialized at exactly 16:00:00.0 of the current day.

A DateTime can also be created by parsing a string using the class method parse, the format parameters list can be found in the reference documentation:

var parsedDate = SC.DateTime.parse('08/05/1985 01:00:22', '%d/%m/%Y %H:%M:%S');

Finally, to create a UTC DateTime initialized with a certain amount of milliseconds since January, 1st 1970 00:00:00.0 UTC:

var date = SC.DateTime.create(484354822925);

If you want to specify the timezone as well:

var date = SC.DateTime.create({ milliseconds: 484354822925, timezone: -120 });

Manipulating dates

A date's components can be accessed with the get method:

var year = date.get('year');
var month = date.get('month');

More properties are available, the full list is in the generated docs. For example:

isLeapYear = date.get('isLeapYear');
monday = date.get('lastMonday');
n = february.get('daysInMonth');

However, none of these components can be modified with the set method. SC.DateTime implements the SC.Freezable and SC.Copyable mixins and its instances are all frozen for performance reasons. This means that DateTime instances are immutable and that any modification will in fact return a new object.

A new DateTime object obtained by modifying some components of another object is done with the adjust method:

firstOfTheMonthAt10 = today.adjust({ day: 1, hour: 10 });
noon = today.adjust({ hour: 12 });

Just like for the create method, the minute, second and millisecond are cascadingly reseted to 0. The advance method returns a new DateTime object advanced accordingly to the the given parameters:

tomorrow = now.advance({ day: 1 });
lastYear = now.advance({ year: -1 });

To test for equality, the ==, ===, != and !== should not be used. To compare or test for equality, use one of the following:

if (d1.isEqual(d2)) {
if (SC.compare(d1, d2) < 0) {
if (SC.DateTime.compareDate(d1, d2) >= 0) {

The last example only compares the date part of the DateTime object. Note that to make such a comparison, both objects must have the same timezone, otherwise an exception is thrown.

Similarly to the parse method, there is a toFormattedString method:

var str = date.toFormattedString('%Y-%m-%d %H:%M:%S %Z');

There is also a binding-ready transform for parsing/formatting dates through a binding:

valueBinding: SC.Binding.dateTime('%Y-%m-%d %H:%M:%S').from('MyApp.MyController.myDate');

Using dates as record attributes

The SC.DateTime class can be used as a record attribute. Declare your attribute like you would normally do:

createdAt: SC.Record.attr(SC.DateTime)

The default behaviour is to store dates as ISO 8601 strings (%Y-%m-%dT%H:%M:%S%Z). You can change the format by editing the SC.DateTime.recordFormat property, or, on a per-attribute basis with the format option:

frenchCreatedAt: SC.Record.attr(SC.DateTime, { format: '%d/%m/%Y %H:%M:%S' })  

By defining the format option, you allow SC.DateTime to create a new DateTime object from any date string provided by your data source. As noted above, see the reference documentation for format parameters.

Creating Records with SC.DateTime

When creating a record with SC.Store#createRecord() and implementing a SC.DateTime in one of its attributes, realize that createRecord() will write the object directly to the Data Hash and bypass all object formatting that was setup in the model record. Thus doing something like this will not return a formatted timestamp that was created in your model record:

var record = MyApp.store.createRecord(MyApp.Record, {created: SC.DateTime.create()});
MyApp.store.commitRecords();

var record = MyApp.store.createRecord(MyApp.Record);
record.set('created', SC.DateTime.create());
MyApp.store.commitRecords();