DayPilot.Date Class

Members

Notes

DayPilot uses a special class for representing a DateTime value on the client side.

Shared Instances

The DayPilot.Date class reuses instances for the same points in time.

Same strings

> new DayPilot.Date("2023-01-01T00:00:00") === new DayPilot.Date("2023-01-01T00:00:00");
true

Different strings representing the same date/time

> new DayPilot.Date("2023-01-01T00:00:00") === new DayPilot.Date("2023-01-01");
true

Direct Comparison

DayPilot.Date allows direct comparison using >, <, ==, === operators:

> new DayPilot.Date("2023-02-01") > new DayPilot.Date("2023-01-01");
true

The values are normalized:

> new DayPilot.Date("2023-01-01") === new DayPilot.Date("2023-01-01T00:00:00");
true

Immutability

The DayPilot.Date instances are immutable. The internal .ticks and .value properties are read-only. 

  • .value is implemented as a read-only property so you can see its value in Chrome console. 
  • .ticks remains internal, implemented using a getter.

Converting to a Date Object

  • Use .toDate() to get a Date object that stores the DayPilot.Date value as the GMT base.
  • Use .toDateLocal() to get a Date object that stores the DayPilot.Date value as the local part.
  • DayPilot.Date has the same methods as Date. You can use to get the component values (getYear(), getMonth(), etc.)

Converting from a Date Object

  • Use new DayPilot.Date(date) to create a DayPilot.Date object from the GMT base of the "date" object.
  • Use new DayPilot.Date(date, true) to create a DayPilot.Date object from the local representation of the "date" object.

ISO 8601

Calling toString() without parameters will return the ISO 8601 representation of the input value, e.g. "2023-05-27T13:15:00".

  • If the date doesn't have milliseconds set it is normalized as "yyyy-MM-ddTHH:mm:ss".
  • If the date has milliseconds set it is normalized as "yyyy-MM-ddTHH:mm:ss.fff".

No time zone identifier is used. See also the "Time Zones" section below.

Formatting

You can use toString(format) to get a locally formatted string.

See toString(format) for the list of supported format strings.

Example - sending the value to the server

> var date = new DayPilot.Date("2023-05-27T13:15:00");
> date.toString()
"2015-05-27T13:15:00"

Example - presenting the value to the user

> var date = new DayPilot.Date("2023-05-27T13:15:00");
> date.toString("M/d/yyyy HH:mm")
"5/27/2023 13:15"

Example - get a Date object that returns a correct string using .toString()

> var date = new DayPilot.Date("2023-05-27T13:15:00");
> date.toDateLocal().toString();
'Sat May 27 2023 13:15:00 GMT+0200 (Central European Summer Time)'

Time Zones

The controls (to be able to perform correct calculations) work with an idealized continuous timezone. 

  • Continuous = Unlike most local timezones it doesn't have daylight saving time, so there are no unexpected breaks.
  • Idealized = This timezone behaves like GMT and it uses GMT timezone internally but in a typical setup you will pretend that this is your local timezone. And ignore the fact that it is incorrect for events that span over the DST change date.

By calling toDateLocal() you say - I pretend the idealized timezone is my local timezone.

String Parsing

Use DayPilot.Date.parse(string, pattern, locale) to read the value from a custom-formatted string.

Date/Time Calculations

The following methods are available:

  • addMilliseconds()
  • addSeconds()
  • addMinutes()
  • addHours()
  • addDays()
  • addMonths()
  • addYears()
  • firstDayOfMonth()
  • lastDayOfMonth()
  • firstDayOfWeek()
  • firstDayOfYear()
  • getDatePart()
  • getTimePart()
  • daysInMonth()
  • daysInYear()
  • dayOfWeek()
  • dayOfYear()

The original DayPilot.Date object is not modified (instances are immutable).

Creating DayPilot.Date Objects

  • DayPilot.Date.now() - now, from local date representation
  • DayPilot.Date.today() - today, from local date representation
  • new DayPilot.Date(isoString) - from ISO 8601 string
  • DayPilot.Date.fromYearMonthDay(year[, month, [day]]) - from the specified year/month/day (missing month = 1, missing day = 1)
  • DayPilot.Date.parse(string, pattern[, locale]) - from string in the specified format (pattern)