The new .same() function will compare two date objects to determine if they occur on/in exactly the same instance of the given date part. (...like I said, I'm having a hard time explaining this one).

It's easier to understand with code...

Scenario: Determine if the two dates occur on the same day.

Example

var d1 = Date.today(); // today at 00:00
var d2 = new Date();   // exactly now.

// Do they occur on the same day?
d1.same().day(d2); // true

// What if it's the same day, but one year apart?
var nextYear = Date.today().add(1).year();

d1.same().day(nextYear); // false, because the dates must occur on the exact same day.

When comparing the dates in the same above, the .same() function will test that the year, month, and day match. Because we're only interested in whether the day is the same, the hour, minute, second & millisecond values are ignored.

Using the same d1 & d2 values from above, determine if the two dates occur on the same hour.

Example

// Do they occur on the same hour?
d1.same().hour(d2); // false, unless d2 hour is '00' (< 1:00 am).

If no date is passed as a parameter, by default the .same() function will use 'Now' (new Date()) as the default date to compare against.

Example

Date.today().same().day(); // true, 'today' occurs on 'today'
Date.today().same().hour(); // false, unless 'now' is '00' minutes (< 1:00am)

What do think? Would you find this functionality useful?

I do... because I'm often trying to determine if some date object occurs during today. The following samples demonstrate various ways to determine if a date object occurs today.

Example (native JavaScript, without Datejs)

var temp = new Date();
temp.setHours(0);
temp.setMinutes(0);
temp.setSeconds(0);
temp.setMilliseconds(0);

var today = new Date(someDate.getTime()); // clone original instance so we don't actually change the original date.
var today.setHours(0);
var today.setMinutes(0);
var today.setSeconds(0);
var today.setMilliseconds(0);

(today == temp); // true|false

Example (with Datejs)

// with Datejs, but without .same
someDate.clone().clearTime().equals(Date.today());

// New
someDate.same().day();

// Or,
someDate.is().today();

Checking if a given date object occurs today is easy enough with Datejs and would not really justify adding the new .same() functionality, but things can get nasty when you need to compare against a date other than 'today'.

Scenario: Determine if a given date occurs during some week period 2 months from now.

Example

// New
var future = Date.today().add(2).months();

return someDate.same().week(future); // true|false;

The .same() function adds a third context to .second() within the library, which enables the following interesting (but freakishly cryptic) logic.

Example

Date.jan().second().monday().add(1).second().same().second();

The .same() functionality has been added to sugarpak.js and is available from SVN.

Any feedback is appreciated.

But... we need some help. One area where we have not received much feedback is testing the Parser with cultures/languages outside of English.

The Datejs library should properly parse month and day names (both full and abbreviated strings) in over 150 different cultures.

The variations of German, Spanish, French and most European culture parsing seem good.

The big unknown cultures are Arabic and Chinese.

Haven't heard much feedback from India either.

The following list details the cultures we're most interested in receiving feedback:

• Arabic (Saudi Arabia) date-ar-SA.js (or any other Arabic culture)
• Chinese (People's Republic of China) date-zh-CN.js
• Punjabi (India) date-pa-IN.js
• Russian (Russia) date-ru-RU.js
• Thai (Thailand) date-th-TH.js

If any developers could confirm the Datejs Parser is working (or not) in any of the above cultures, we would really appreciate the thumbs up/down. By "working", we're specifically interested in whether the Parser is correctly parsing Day and Month names in each culture and whether the expected date format for that culture parses properly.

If the following strings (translated into the appropriate language) return the proper date, things should be good.

Example

Date.parse('July 2008');
Date.parse('Sat July 3, 2004');
Date.parse('Dec');
Date.parse('monday');

The parser ships with some date phrase support (eg. 'today', 'next march'), although those strings may require translation. A couple cultures have already been translated by the community and available for download from the Datejs forums.

• français-French (France)
• espanol-Spanish (Spain)

To test your culture, download a culture-specific file from SVN /trunk/build/ and add to any web page. If you are using FireFox, the easiest way run test scripts is with FireBug.

Thanks for the help.

One recommendation from Guy was to hold a reference to the Date.prototype in a local var, thereby saving characters and simplifying access to the prototype.

Example

(function () {
    // Store prototype in local variable making
    // syntax shorter and access faster.
    var $P = Date.prototype;

    // Old
    // Date.prototype.clearTime = function() {

    // New
    $P.clearTime = function () {
        this.setHours(0);
        this.setMinutes(0);
        this.setSeconds(0);
        this.setMilliseconds(0);
        return this;
    };
}());

After changing everything over we were able to shave a little over 1k off the total library size and our performance tests did register an improvement. Great advice, and Datejs is now better (and faster!).

All this has been checked into SVN for public consumption.

The launch went well and community feedback has been steady and very much appreciated. As defects are discovered we're doing our best to fix immediately and commit the new code to SVN.

If you're interested in following along as we commit code to the source repository, you might want to subscribe to the Datejs-commits Discussion Group. The Datejs-commits Group automagically catches all the SVN commit log messages and creates a feed which is then easily consumed into your favourite news reader. We're doing our best to always ensure the SVN log notes give plenty of detail regarding all new code and/or revisions.

A spoonful of SugarPak

For developers partial to the RememberTheMilk.com date input options we added the following API functions and abbreviations.

Date.tod();       // Date.today()
Date.tomorrow();
Date.tom();
Date.yesterday();
Date.yes();

Added a new .at() function which accepts a Time string or Time config object.

Date.today().at("6:15 PM");
Date.today().at({hour: 18, minute: 15});

Added .next() and .last() as static functions to the Date object, so you no longer need to instantiate a Date object first before calling .next() or .last().

// Existing
Date.today().next().friday();
Date.today().last().march();

// New
// The above code still works,
// but if you want to be relative to 'today',
// the following code is tighter.
Date.next().friday();
Date.last().march();

Date logic actually gets fun to write when you start combining the functions to build amazingly readable Date expressions.

Date.next().friday().at("6:15 PM");

[Use Case] Schedule a reminder to be sent a week before the start of the next month at 9 in the morning.

(1).week().before(Date.next().month()).at("9:00 am");

Hope this helps.