Instance Methods - abritinthebay/datejs GitHub Wiki

Instance Methods

---

add

.add ( Object config ) : DateAdds (or subtracts) to the value of the year, month, day, hour, minute, second, millisecond of the date instance using given configuration object. Positive and Negative values allowed.

Parameters

• {Object config} Configuration object containing attributes (months, days, etc.)#### Return Value{Date} this#### Example

Date.today().add({ days: 5, months: 1 }); new Date().add({ years: -1, hours: -6 }); The following details all the options for .add(). #### Example

// returns Jul 26 2009 18:45:30 given today as 11-Jan-2008 Date.today().add({     milliseconds: 500,     seconds: 30,     minutes: 45,     hours: 18,     days: 15,     months: 6,     years: 1     });   // as one line Date.today().add({milliseconds: 500, seconds: 30, minutes: 45, hours: 18, days: 15, months: 6, years: 1});

// as separate config object var config = {milliseconds: 500, seconds: 30, minutes: 45, hours: 18, days: 15, months: 6, years: 1}; Date.today().add(config);#### See Also

• set .

addMilliseconds

.addMilliseconds ( Number milliseconds ) : DateAdds the specified number of milliseconds to this instance.

Parameters

• {Number milliseconds} The number of milliseconds to add. The number can be positive or negative. required#### Return Value{Date} this#### Example

Date.today().addMilliseconds(500); Date.today().addMilliseconds(-500); .

addSeconds

.addSeconds ( Number seconds ) : DateAdds the specified number of seconds to this instance given the number of seconds to add. The number can be positive or negative.

Parameters

• {Seconds} The number of seconds to add. The number can be positive or negative. required#### Return Value{Date} this#### Example

Date.today().addSeconds(30); Date.today().addSeconds(-30); .

addMinutes

.addMinutes ( Number minutes ) : DateAdds the specified number of minutes to this instance given the number of minutes to add. The number can be positive or negative.

Parameters

• {Number minutes} The number of seconds to add. The number can be positive or negative. required#### Return Value{Date} this#### Example

Date.today().addMinutes(45); Date.today().addMinutes(-45); .

addHours

.addHours ( Number hours ) : DateAdds the specified number of hours to this instance given the number of hours to add. The number can be positive or negative.

Parameters

• {Number hours} The number of hours to add. The number can be positive or negative. required#### Return Value{Date} this#### Example

Date.today().addHours(6); Date.today().addHours(-6); .

addDays

.addDays ( Number days ) : DateAdds the specified number of days to this instance. The number can be positive or negative.

Parameters

• {Number days} The number of days to add. The number can be positive or negative. required#### Return Value{Date} this#### Example

Date.today().addDays(1); Date.today().addDays(-1); .

addWeeks

.addWeeks ( Number weeks ) : DateAdds the specified number of weeks to this instance given the number of weeks to add. The number can be positive or negative.

Parameters

• {Number weeks} The number of weeks to add. The number can be positive or negative. required#### Return Value{Date} this#### Example

Date.today().addWeeks(1); Date.today().addWeeks(-1); .

addMonths

.addMonths ( Number months ) : DateAdds the specified number of months to this instance given the number of months to add. The number can be positive or negative.

Parameters

• {Number months} The number of months to add. The number can be positive or negative. required#### Return Value{Date} this#### Example

Date.today().addMonths(6); Date.today().addMonths(-6); .

addYears

.addYears ( Number years ) : DateAdds the specified number of years to this instance given the number of years to add. The number can be positive or negative.

Parameters

• {Number years} The number of years to add. The number can be positive or negative. required#### Return Value{Date} this#### Example

Date.today().addYears(10); Date.today().addYears(-10); .

clearTime

.clearTime ( ) : DateResets the time of this Date object to 12:00 AM (00:00), which is the start of the day.

ParametersNone#### Return Value{Date} this#### Example

new Date().clearTime(); // same as Date.today() .

setTimeToNow

.setTimeToNow ( ) : DateResets the time of this Date object to the current time ('now').

Parameters

None#### Return Value{Date} this#### Example

Date.today().setTimeToNow(); .

clone

.clone ( ) : DateReturns a new Date object that is an exact date and time copy of the original instance.

ParametersNone#### Return Value{Date} A new Date instance#### Example

// Wrong way var d1 = new Date(2007, 0, 1); // 1-Jan-2007 var d2 = d1; d2.add(6).days();

console.log(d1); // 7-Jan-2007 console.log(d2); // 7-Jan-2007   // Correct way var d1 = new Date(2007, 0, 1); // 1-Jan-2007 var d2 = d1.clone(); d2.add(6).days();

console.log(d1); // 1-Jan-2007 console.log(d2); // 7-Jan-2007 .

between

.between ( Date startDate, Date endDate ) : BooleanDetermines if this instance is between a range of two dates or equal to either the start or end dates.

Parameters

• {Date startDate} Start of range. required* {Date endDate} End of range. required#### Return Value{Boolean} true is this is between or equal to the start and end dates, else false#### Example

var past = new Date(2000, 4, 5); var future = new Date(2010, 11, 25) Date.today().between(past, future); // true|false#### See Also

• compareTo* equals* isAfter* isBefore .

compareTo

.compareTo ( Date date ) : NumberCompares this instance to a Date object and returns an number indication of their relative values. -1 = this is lessthan date. 0 = values are equal. 1 = this is greaterthan date.

Parameters

• {Date date} Date object to compare. required#### Return Value{Number} -1 = this is lessthan date. 0 = values are equal. 1 = this is greaterthan date.

Example

var past = Date.today().add(-6).days(); var future = Date.today().add(6).days();

Date.today().compareTo(future);                 // -1 Date.today().compareTo(new Date().clearTime()); // 0 Date.today().compareTo(past);                   // 1#### See Also

• between* equals* isAfter* isBefore .

equals

.equals ( Date date ) : BooleanCompares this instance to another Date object and returns true if they are equal, otherwise false.

Parameters

• {Date date} Date object to compare. required#### Return Value{Boolean} true if dates are equal. false if they are not equal.

Example

Date.today().compareTo(new Date().clearTime()); // true

var d1 = Date.today(); var d2 = Date.today().addHours(5); d1.equals(d2); // false#### See Also

• between* compareTo* isAfter* isBefore .

isAfter

.isAfter ( Date date ) : BooleanDetermines if this date occurs after the date to compare to.

Parameters

• {Date date} Date object to compare. If no date to compare, new Date() ("now") is used.#### Return Value{Boolean} true if this date instance is greater than the date to compare to (or "now"), otherwise false.#### Example

var tomorrow = new Date().add(1).day(); Date.today().isAfter(tomorrow); // false Date.today().isBefore(tomorrow); // true

var yesterday = new Date().add(-1).day(); Date.today().isAfter(yesterday); // true Date.today().isBefore(yesterday); // false

// No date to compare to...     Date.today().isAfter(); // false Date.today().isBefore(); // true#### See Also

• compareTo* between* equals* isBefore .

isBefore

.isBefore ( Date date ) : BooleanDetermines if this date occurs before the date to compare to.

Parameters

• {Date date} Date object to compare. If no date to compare, new Date() ("now") is used.#### Return Value{Boolean} true if this date instance is greater than the date to compare to (or "now"), otherwise false.#### Example

var tomorrow = new Date().add(1).day(); Date.today().isAfter(tomorrow); // false Date.today().isBefore(tomorrow); // true

var yesterday = new Date().add(-1).day(); Date.today().isAfter(yesterday); // true Date.today().isBefore(yesterday); // false

// No date to compare to...     Date.today().isAfter(); // false Date.today().isBefore(); // true#### See Also

• compareTo* between* equals* isAfter .

getOrdinalNumber

.getOrdinalNumber ( ) : NumberGet the Ordinal day (numeric day number) of the year, adjusted for leap year. Returns 1 through 365 (366 in leap years).

ParametersNone#### Return Value{Number} 1 through 365 (366 in leap years)#### Example

Date.today().getDayOfYear();         // 323 new Date(2000, 0, 1).getDayOfYear(); // 1 .

getTimezone

.getTimezone ( ) : StringGet the timezone abbreviation of the current date.

ParametersNone#### Return Value{String} The abbreviated time zone name (e.g. "EST")#### Example

Date.today().getTimezone(); .

getUTCOffset

.getUTCOffset ( ) : UTCOffsetGet the offset from UTC of the current date. Returns the 4-character offset string prefixed with + or - (e.g. "-0500").

ParametersNone#### Return Value{String} The 4-character offset string prefixed with + or - (e.g. "-0500")#### Example

Date.today().getUTCOffset(); // "-0600" .

getWeek

.getWeek ( ) : NumberGet the week number. Week one (1) is the week which contains the first Thursday of the year. Monday is considered the first day of the week.

The .getWeek() function does NOT convert the date to UTC. The local datetime is used. Please use .getISOWeek() to get the week of the UTC converted date. #### ParametersNone#### Return Value{Number} 1 to 53#### Example

Date.today().getWeek(); // 7#### See Also

• getISOWeek* setWeek .

getISOWeek

.getISOWeek ( ) : StringGet the ISO 8601 week number. Week one ("01") is the week which contains the first Thursday of the year. Monday is considered the first day of the week.The .getISOWeek() function does convert the date to it's UTC value. Please use .getWeek() to get the week of the local date.

ParametersNone#### Return Value{String} "01" to "53"#### Example

Date.today().getISOWeek(); // "07"#### See Also

• getWeek* setWeek* toISOString .

setWeek

.setWeek ( Number week ) : Date

Moves the date to Monday of the week set. Week one (1) is the week which contains the first Thursday of the year. #### Parameters

• {Number week} A Number (1 to 53) that represents the week of the year. #### Return Value{Date} this#### Example

Date.today().setWeek(7); // Returns a Date set to the Monday of the week specified#### See Also

• getWeek* getISOWeek .

getOrdinalNumber

.getOrdinalNumber ( ) : NumberGet the Ordinal day (numeric day number) of the year, adjusted for leap year. Return a number 1 through 365 (366 in leap years).

ParametersNone#### Return Value{Number} 1 through 365 (366 in leap years)#### Example

Date.today().getOrdinalNumber(); // 46 .

hasDaylightSavingTime

.hasDaylightSavingTime ( ) : BooleanIndicates whether Daylight Saving Time is observed in the current time zone.

ParametersNone#### Return Value{Boolean} true|false#### Example

Date.today().hasDaylightSavingTime(); // true|false#### See Also

• isDaylightSavingTime .

isDaylightSavingTime

.isDaylightSavingTime ( ) : BooleanIndicates whether this Date instance is within the Daylight Saving Time range for the current time zone.

ParametersNone#### Return Value{Boolean} true|false#### Example

Date.today().isDaylightSavingTime(); // true|false#### See Also

• hasDaylightSavingTime .

moveToDayOfWeek

.moveToDayOfWeek ( Number dayOfWeek, Number direction ) : DateMove to the next or previous dayOfWeek. Whether to move into the future (+1) or past (-1) is controlled by the optional direction parameter.

Parameters

• {Number dayOfWeek} The dayOfWeek to move to* {Number direction} Forward (+1) or Back (-1). Defaults to +1. optional#### Return Value{Date} this#### Example

Date.today().moveToDayOfWeek(0);     // move to next Sunday Date.today().moveToDayOfWeek(0, -1); // move to last Sunday .

moveToFirstDayOfMonth

.moveToFirstDayOfMonth ( ) : DateMoves the date to the first day of the month.

ParametersNone#### Return Value{Date} this#### Example

new Date(2007, 10, 19).moveToFirstDayOfMonth(); // 1-Nov-2007 .

moveToLastDayOfMonth

.moveToLastDayOfMonth ( ) : DateMoves the date to the last day of the month.

ParametersNone#### Return Value{Date} this#### Example

new Date(2007, 10, 19).moveToLastDayOfMonth(); // 30-Nov-2007 .

moveToMonth

.moveToMonth ( Number month, Number direction ) : DateMove to the next or previous month. Whether to move into the future (+1) or past (-1) is controlled by the optional direction parameter.

Parameters

• {Number month} The month to move to. 0 = January, 11 = December* {Number direction} Forward (+1) or Back (-1). Defaults to +1. optional#### Return Value{Date} this#### Example

Date.today().moveToMonth(0);     // move to next January Date.today().moveToMonth(0, -1); // move to last January .

moveToNthOccurrence

.moveToNthOccurrence ( Number dayOfWeek, Number occurrence ) : DateMoves the date to the next n'th occurrence of the dayOfWeek starting from the beginning of the month. The number (-1) is a magic number and will return the last occurrence of the dayOfWeek in the month.

Parameters

• {Number dayOfWeek} The dayOfWeek to move to* {Number occurrence} The n'th occurrence to move to. Use (-1) to return the last occurrence in the month#### Return Value{Date} this#### Example

Date.today().moveToNthOccurrence(0, 1);     // First Sunday of the month Date.today().moveToNthOccurrence(0, 3);     // Third Sunday of the month Date.today().moveToNthOccurrence(0, -1);    // Last Sunday of the month .

set

.set ( Object config ) : DateSet the value of year, month, day, hour, minute, second, millisecond of date instance using given configuration object.

Parameters

• {Object config} Configuration object containing attributes (month, day, etc.)#### Return Value{Date} this#### Example

Date.today().set({ day: 15, hour: 8 }); // Sets the day to the 15th day of the current month and the hour to 8 (AM).The following list all property options for .set().

Example

// returns Jul 15 2008 18:45:30 Date.today().set({     millisecond: 500,     second: 30,     minute: 45,     hour: 18,     day: 15,     month: 6,     year: 2008     });   // as one line Date.today().set({millisecond: 500, second: 30, minute: 45, hour: 18, day: 15, month: 6, year: 2008});

// as separate config object var config = {millisecond: 500, second: 30, minute: 45, hour: 18, day: 15, month: 6, year: 2008}; Date.today().set(config);#### See Also

• add .

setTimezone

.setTimezone ( String timezoneAbbreviation ) : DateSet the timezone for the current date using a culture-specific timezone abbreviation ("PST"). Note that in most JavaScript implementations, this will appear to change the time since the timezone is always based on the locale.

Parameters

• {String timezoneAbbreviation} The timezone abbreviation.#### Return Value{Date} this#### Example

Date.today().setTimezone("PST"); .

setTimezoneOffset

.setTimezoneOffset ( Number timezoneOffset ) : DateSet the timezone for the current date using an offset (-0700). Note that in most JavaScript implementations, this will appear to change the time since the timezone is always based on the locale.

Parameters

• {Number timezoneOffset} The timezone offset#### Return Value{Date} this#### Example

Date.today().setTimezoneOffset(-0700); .

toISOString

.toISOString ( ) : StringConverts the current date instance into a string with an ISO 8601 format. The date is converted to it's UTC value. As per the ISO 8601 specification, the string will be wrapped with double quotation marks (").

ParametersNone#### Return Value{String} ISO 8601 string of date#### Example

new Date().toISOString();  // ""2008-04-13T10:07:15Z"" The local time version of ISO 8601 formatted string can be created by passing a custom format to the .toString() function. #### Example

new Date().toString("yyyy-MM-ddTHH:mm:ssZ");  // "2008-04-13T04:11:05Z"#### See Also

• toString .

toString

.toString ( String format ) : StringConverts the value of the current Date object to its equivalent string representation. Use format argument to specify format (optional). See FormatSpecifiers for more info.

Parameters

• {String format} A format string consisting of one or more format specifiers. optional#### Return Value{String} A string representation of the current Date object.

Example

Date.today().toString();           // native .toString() functionality Date.today().toString("M/d/yyyy"); // 11/19/2007 Date.today().toString("d-MMM-yyyy"); // 19-Nov-2007 new Date().toString("HH:mm");      // 18:45#### See Also

• toISOString