I need some feedback regarding a feature I just added to the library, but I'm struggling to explain/document clearly and I'm not sure if others would find this useful.

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.