The lastest version of this document is available on Github > datetime-object

Others API Section

now

var dt=DateTime.now();

today

var dt=DateTime.today();

roundHours

DateTime.prototype.roundHours(nbHours,past=true) where (integer) nbHours : integer between 0 and 24 (boolean) past: if true, round in the past, else futur
round the date to the nearest hour
var m = new DateTime(); // 22:54:00 m.roundHours(2); // 22:00:00 m.roundHours(5); // 20:00:00 m.roundHours(1); // 22:00:00 m.roundHours(1,false); // 23:00:00

roundMinutes

DateTime.prototype.roundMinutes(nbMinutes,past=true) where (integer) nbMinutes : integer between 0 and 60 (boolean) past: if true, round in the past, else futur
round the date to the nearest minutes
var m = new DateTime(); // 22:54:25 m.roundMinutes(30); // 22:30:00 m.roundMinutes(15); // 22:45:00 m.roundMinutes(1); // 22:54:00 m.roundMinutes(1,false); // 22:55:00

roundSeconds

DateTime.prototype.roundSeconds(nbSeconds,past=true) where (integer) nbSeconds : integer between 0 and 60 (boolean) past: if true, round in the past, else futur
round the date to the nearest seconds
var m = new DateTime(); // 22:54:25 m.roundSeconds(30); // 22:54:00 m.roundSeconds(15); // 22:54:15 m.roundSeconds(1); // 22:54:25 m.roundSeconds(1,false); // 22:54:26

nearestSunday, nearestMonday, nearestTuesday, nearestWednesday, nearestThursday, nearestFriday, nearestSaturday

DateTime.prototype.nearestSunday(intDirection) DateTime.prototype.nearestMonday(intDirection) DateTime.prototype.nearestTuesday(intDirection) DateTime.prototype.nearestWednesday(intDirection) DateTime.prototype.nearestThursday(intDirection) DateTime.prototype.nearestFriday(intDirection) DateTime.prototype.nearestSaturday(intDirection)
returns the closest date corresponding to the day of the week, in the future or the past according to the parameter intDirection.
var dt = new DateTime("21/01/2018","DD/MM/YYYY"); ==> Sunday var nextSaturday=dt.nearestSaturday(1); var prevWenesday=dt.nearestWednesday(-1); var dt2=dt.nearestSunday(1) ==> "21/01/2018" ~dt var dt3=dt.nearestSunday(-1) ==> "14/01/2018"

isBefore

Check if a DateTime is before another DateTime.
new DateTime().isBefore(DateTime); new DateTime('2010-10-20').isBefore(new DateTime('2010-10-21'));

isSame

Check if a DateTime is the same as another DateTime.
new DateTime().isSame(DateTime); new DateTime('2010-10-20').isSame(new DateTime('2010-10-20'));

isAfter

Check if a DateTime is after another DateTime.
new DateTime().isAfter(DateTime); new DateTime('2010-10-20').isAfter(new DateTime('2010-10-19'));

isSameOrBefore

new DateTime().isSameOrBefore(DateTime);

isSameOrAfter

Check if a DateTime is same or after another DateTime. new DateTime().isSameOrAfter(DateTime); new DateTime('2010-10-20').isSameOrAfter(new DateTime('2010-10-19'));

isBetween

Check if a DateTime is between two other DateTimes, optionally looking at unit scale (minutes, hours, days, etc). The match is exclusive.
new DateTime().isBetween(DateTime1, DateTime2); new DateTime().isBetween(DateTime1, DateTime2, border); new DateTime('2010-10-20').isBetween(new DateTime('2010-10-19'), new DateTime('2010-10-25'));

border is 2 characters should be `[` or `]` If the first character is` [`, that indicates inclusion of the value, otherwise exclusion. If the second character is`]`, that indicates inclusion of the value, otherwise exclusion.

new DateTime('2016-10-30').isBetween(new DateTime('2016-10-30'), new DateTime('2016-12-30', '[]'); ==> `true` new DateTime('2016-10-30').isBetween(new DateTime('2016-10-30'), new DateTime('2016-12-30', '[['); ==> false new DateTime('2016-10-30').isBetween(new DateTime('2016-01-01'), new DateTime('2016-10-30', ']]'); ==> true new DateTime('2016-10-30').isBetween(new DateTime('2016-01-01'), new DateTime('2016-10-30', '[['); ==> false If the inclusivity parameter is not specified, DateTime will default to ` []`.

isLeapYear

returns `true` if that year is a leap year, else `false`. DateTime.isLeapYear(year)

daysInMonth

returns the number of days in the month & year DateTime.daysInMonth(month, year)

seconds

Set

DateTime.prototype.seconds(integer)
Set seconds of the instance DateTime to a value Accepts numbers from 0 to 59. If the range is exceeded, it will bubble up to the minutes.

Get

DateTime.prototype.seconds()
Get the seconds of the instance DateTime

milliseconds

Set

DateTime.prototype.milliseconds(integer)
Set milliseconds of the instance DateTime to a value Accepts numbers from 0 to 999. If the range is exceeded, it will bubble up to the seconds. var in500milliseconds=new DateTime().milliseconds(500);

Get

DateTime.prototype.milliseconds()
Get the milliseconds of the instance DateTime
var dt=new DateTime().milliseconds();

minutes

Set

DateTime.prototype.minutes(integer)
Set minutes of the instance DateTime to a value Accepts numbers from 0 to 59\. If the range is exceeded, it will bubble up to the hour. var in50minutes=new DateTime().minutes(50);

Get

DateTime.prototype.minutes()
Get the minutes of the instance DateTime
var currentMinutes=new DateTime().minutes();

hours

Set

DateTime.prototype.hours(integer)
Set hours of the instance DateTime to a value Accepts numbers from 0 to 23\. If the range is exceeded, it will bubble up to the day. var in12Hours=new DateTime().hours(12);

Get

DateTime.prototype.hours()
Get the hours of the instance DateTime
var currentHour=new DateTime().hours();

dayOfWeek

Set

DateTime.prototype.dayOfWeek(integer)
This method can be used to set the day of the week, with Sunday as 0 and Saturday as 6. If the range is exceeded, it will bubble up to other weeks. var nextMonday=new DateTime().dayOfWeek(1);

Get

DateTime.prototype.dayOfWeek()
Get the dayOfWeek of the instance DateTime new DateTime().day(-7); new DateTime().day(7); new DateTime().day(10); new DateTime().day(24);
var currentDay=new DateTime().dayOfWeek();

weekday (Locale Aware)

new DateTime().weekday(Number); new DateTime().weekday();

Gets or sets the day of the week according to the locale. If the locale assigns Monday as the first day of the week, `new DateTime().weekday(0)` will be Monday. If Sunday is the first day of the week, `new DateTime().weekday(0)` will be Sunday. As with `DateTime#day`, if the range is exceeded, it will bubble up to other weeks.

new DateTime().weekday(-7); new DateTime().weekday(7); new DateTime().weekday(-7); new DateTime().weekday(7);

isoWeekday

new DateTime().isoWeekday(Number); new DateTime().isoWeekday();

Gets or sets the ISO day of the week with `1` being Monday and `7` being Sunday. As with `DateTime#day`, if the range is exceeded, it will bubble up to other weeks.

new DateTime().isoWeekday(1); new DateTime().isoWeekday(7); A day name is also supported. This is parsed in the DateTime's current locale. new DateTime().isoWeekday("Sunday"); new DateTime().isoWeekday("Monday");

dayOfYear

new DateTime().dayOfYear(Number); new DateTime().dayOfYear();

Gets or sets the day of the year. Accepts numbers from 1 to 366\. If the range is exceeded, it will bubble up to the years.

week

new DateTime().week(Number); new DateTime().week(); Gets or sets the week of the year.

Because different locales define week of year numbering differently, DateTime.js added `DateTime#week` to get/set the localized week of the year. The week of the year varies depending on which day is the first day of the week (Sunday, Monday, etc), and which week is the first week of the year. For example, in the United States, Sunday is the first day of the week. The week with January 1st in it is the first week of the year. In France, Monday is the first day of the week, and the week with January 4th is the first week of the year. The output of `DateTime#week` will depend on the [locale](#/i18n) for that DateTime. When setting the week of the year, the day of the week is retained.

isoWeek

new DateTime().isoWeek(Number); new DateTime().isoWeek(); new DateTime().isoWeeks(Number); new DateTime().isoWeeks();

Gets or sets the ISO week of the year. When setting the week of the year, the day of the week is retained.

month

new DateTime().month(Number|String); new DateTime().month(); Gets or sets the month. Accepts numbers from 0 to 11\. If the range is exceeded, it will bubble up to the year. **Note:** Months are zero indexed, so January is month 0. a month name is also supported. This is parsed in the DateTime's current locale. new DateTime().month("January"); new DateTime().month("Feb"); new DateTime(2012, 0, 31).month(1).toString("YYYY-MM-DD"); new DateTime(2012, 0, 31).month(1).toString("YYYY-MM-DD");

year

new DateTime().year(Number); new DateTime().year(); Gets or sets the year. Accepts numbers from -270,000 to 270,000.

weekYear

new DateTime().weekYear(Number); new DateTime().weekYear();

Gets or sets the week-year according to the locale. Because the first day of the first week does not always fall on the first day of the year, sometimes the week-year will differ from the month year. For example, in the US, the week that contains Jan 1 is always the first week. In the US, weeks also start on Sunday. If Jan 1 was a Monday, Dec 31 would belong to the same week as Jan 1, and thus the same week-year as Jan 1. Dec 30 would have a different week-year than Dec 31.

isoWeekYear

new DateTime().isoWeekYear(Number); new DateTime().isoWeekYear(); Gets or sets the ISO week-year .

weeksInYear

Gets the number of weeks according to locale in the current DateTime's year.

isoWeeksInYear

new DateTime().isoWeeksInYear();

Gets the number of weeks in the current DateTime's year, according to ISO weeks .

lastDayOfMonth

Move DateTime instance to the last day of the month. Time will be "23:59:59".
new DateTime().lastDayOfMonth();

firstDayOfMonth

Move DateTime instance to the first day of the month. Time will be "00:00:00".
new DateTime().firstDayOfMonth();

addYears

new DateTime().addYears(number) var dt1=DateTime.now(); var dt2=dt1.addYears(5); This method returns a new DateTime.

addMonths

new DateTime().addMonths(number) var dt1=DateTime.now(); var dt2=dt1.addMonths(5); This method returns a new DateTime.

addDays

new DateTime().addDays(number) var dt1=DateTime.now(); var dt2=dt1.addDays(5); This method returns a new DateTime.

addHours

new DateTime().addHours(number) var dt1=DateTime.now(); var dt2=dt1.addHours(5); This method returns a new DateTime.

addMinutes

new DateTime().addMinutes(number) var dt1=DateTime.now(); var dt2=dt1.addMinutes(5); This method returns a new DateTime.

addSeconds

new DateTime().addSeconds(number) var dt1=DateTime.now(); var dt2=dt1.addSeconds(5); This method returns a new DateTime.

add

new DateTime().add(years, months, days, hours, minutes, seconds) var dt1=DateTime.now(); var dt2=dt1.add(0, 1, 2, 3, 4, 5); This method returns a new DateTime.

Special considerations for months and years

If the day of the month on the original date is greater than the number of days in the final month, the day of the month will change to the last day in the final month. new DateTime(2010, 0, 31); new DateTime(2010, 0, 31).addMonths(1);

There are also special considerations to keep in mind when adding time that crosses over daylight saving time. If you are adding years, months, weeks, or days, the original hour will always match the added hour. Alternatively, you can use [durations](#/durations) to add to DateTimes.

var duration = DateTime.duration({'days' : 1}); new DateTime( [2012, 0, 31]).add(duration);

when decimal values are passed for days and months, they are rounded to the nearest integer. Weeks, quarters, and years are converted to days or months, and then rounded to the nearest integer.

new DateTime().add(1.5, 'months') == new DateTime().add(2, 'months') new DateTime().add(.7, 'years') == new DateTime().add(8, 'months')

diff

new DateTime().diff(DateTime|String|Number|Date|Array); new DateTime().diff(DateTime|String|Number|Date|Array, String); new DateTime().diff(DateTime|String|Number|Date|Array, String, Boolean); To get the difference in milliseconds, use `DateTime#diff` like you would use `DateTime#from`. var a = new DateTime(2007, 0, 29); var b = new DateTime(2007, 0, 28); a.diff(b)

To get the difference in another unit of measurement, pass that measurement as the second argument.

var a = new DateTime(2007, 0, 29); var b = new DateTime(2007, 0, 28); a.diff(b, 'days')

The supported measurements are `years`, `months`, `weeks`, `days`, `hours`, `minutes`, and `seconds`. For ease of development,the singular forms are supported. Units of measurement other than milliseconds are available. By default, `DateTime#diff` will truncate the result to zero decimal places, returning an integer. If you want a floating point number, pass`true` as the third argument.

var a = new DateTime(2008, 9); var b = new DateTime(2007, 0); a.diff(b, 'years'); a.diff(b, 'years', true);

If the DateTime is earlier than the DateTime you are passing to `DateTime.fn.diff`, the return value will be negative.

var a = new DateTime(); var b = new DateTime().add(1, 'seconds'); a.diff(b) b.diff(a)

An easy way to think of this is by replacing `.diff(` with a minus operator.

a.diff(b) b.diff(a)

Month and year diffs

`DateTime#diff` has some special handling for month and year diffs. It is optimized to ensure that two months with the same date are always a whole number apart. So Jan 15 to Feb 15 should be exactly 1 month. Feb 28 to Mar 28 should be exactly 1 month. Feb 28 2011 to Feb 28 2012 should be exactly 1 year.