DayTime

This class encapsulates time of day calculations.

The goal is to describe a "day" (a 24-hour period) that starts at a specific time (other than midnight). In a calendar day view, this would look like this:

             startShift=0                          startShift='12:00'
      00:00  +-------+                      12:00  +-------+
             |       |                             |       |
      01:00  |- - - -|                      13:00  |- - - -|
                ...                                   ...
             |       |                             |       |
      08:00  |- - - -|   <-- timeStart -->  20:00  |- - - -|
             |       |                             |       |
      09:00  |- - - -|                      21:00  |- - - -|
             |       |                             |       |
      10:00  |- - - -|                      22:00  |- - - -|
             |       |                             |       |
      11:00  |- - - -|                      23:00  |- - - -|
             |       |                             |       |
      12:00  |- - - -|                      00:00  |- - - -|
             |       |                             |       |
      13:00  |- - - -|                      01:00  |- - - -|
             |       |                             |       |
      14:00  |- - - -|                      02:00  |- - - -|
             |       |                             |       |
      15:00  |- - - -|                      03:00  |- - - -|
             |       |                             |       |
      16:00  |- - - -|                      04:00  |- - - -|
             |       |                             |       |
      17:00  |- - - -|    <-- timeEnd -->   05:00  |- - - -|
             |       |                             |       |
                ...                                   ...
             |       |                             |       |
      23:00  |- - - -|                      11:00  |- - - -|
             |       |                             |       |
      00:00  +-------+                      12:00  +-------+

In a horizontal format with X for times to render:

 startShift = 0

     +---+---+---  --+---+---+---+--   --+---+---+---+--   --+---+
     |   |   |  ...  |   |XXX|XXX|  ...  |XXX|XXX|   |  ...  |   |
     +---+---+---  --+---+---+---+--   --+---+---+---+--   --+---+
     00  01  02      07  08  09  10      15  16  17  18      23  00
                         ^                       ^
                     timeStart               timeEnd

 startShift = '12:00'

     +---+---+---  --+---+---+---+--   --+---+---+---+--   --+---+
     |   |   |  ...  |   |XXX|XXX|X ... X|XXX|XXX|   |  ...  |   |
     +---+---+---  --+---+---+---+--   --+---+---+---+--   --+---+
     12  13  14      19  20  21  22      03  04  05  06      11  12
                         ^                       ^
                     timeStart               timeEnd

When the day wraps over midnight, it is describing this (note timeEnd < timeStart):

     +---+---+---  --+---+---+---+--   --+---+---+---+--   --+---+
     |XXX|XXX|X ... X|XXX|   |   |  ...  |   |   |XXX|X ... X|XXX|
     +---+---+---  --+---+---+---+--   --+---+---+---+--   --+---+
     00  01  02      04  05  06  07      18  19  20  21      23  00
                         ^                       ^
                     timeEnd                 timeStart

Configs

startShift: Number | String= 0

Either the hour number or a 24 hour HH:MM string denoting the start time for the day. This is midnight by default.

timeEnd: Number | String= 24

Either the hour number or a 24 hour HH:MM string denoting the last visible time of day. You can also set this value to a ms timestamp representing time from midnight.

timeStart: Number | String= 0

Either the hour number or a 24 hour HH:MM string denoting the first visible time of day. You can also set this value to a ms timestamp representing time from midnight.

Properties

MIDNIGHT: DayTimereadonlystatic

The DayTime instance representing a canonical calendar day (starting at midnight).

startTimeOffsetMs: Number

The number of milliseconds from the day's startShift to its timeStart.

today: Date

The Date object for the most recently started, shifted day. The time of this Date will be the startShift. It is possible for this date to be yesterday on a midnight-based calendar. For example, if the startShift is 6PM and the current time is 6AM on May 20, this value will be 6PM of May 19 (the most recently started day).

Functions

ceil

Returns Date object for the nearest (shifted) day ending after the given date. The time of this Date will be the startShift.

It is possible for this date to be in the next day on a midnight-based calendar. For example, if the startShift is 6PM and date is 7PM on May 20, this method will return 6PM of May 21 (the nearest day ending).

Parameter	Type	Description
`date`	Date	The date for which to find the nearest day ending.

Returns: Date

contains

Returns true if the time of day for the given date is between timeStart and timeEnd.

Parameter	Type	Description
`date`	Date \| Number \| String	The hour number, 'HH:MM' time or a `Date` instance to test.

Returns: Boolean

dateKey

Returns a "YYYY-MM-DD" string for the given date. This value will match the date if the time of day is at or after startShift, but will be the prior date otherwise.

Parameter	Type	Description
`date`	Date \| Number	The date from which to compute the 'YYYY-MM-DD' key.

Returns: String

dayOfDate

Returns a Date instance with startShift as the time of day and the Y/M/D of the given date.

Parameter	Type	Description
`date`	Date	The date's year, month, and day values.

Returns: Date

dayOfWeek

Returns the day of week (0-8) for the given date. This value will match the date if the time of day is at or after startShift, but will be the prior day otherwise.

Parameter	Type	Description
`date`	Date \| Number	The date from which to compute the day of week.

Returns: Number

delta

Returns the difference between the time of day of the given date and timeStart in the specified time unit.

Parameter	Type	Description
`date`	Date \| Number \| String	The hour number, 'HH:MM' time or a `Date` instance.
`unit`	String	The desired unit of time to return (see as).

Returns: Number

duration

Returns the duration of the visible day (between timeStart and timeEnd) in the specified time unit.

Parameter	Type	Description
`unit`	String	The desired unit of time to return (see as).

Returns: Number

equals

Returns true if this instance describes the same day as the other.

Parameter	Type	Description
`other`	DayTime	The other instance to which `this` instance should be tested for equality.

Returns: Boolean

intersects

Returns true if the times of day described by startDate and endDate intersect the visible time of this day.

Parameter	Type	Description
`startDate`	Date	The start date of the date range or an event record containing both startDate and endDate fields.
`endDate`	Date	The end date if `startDate` is not an event record.

Returns: Boolean

isInterDay

Returns true if the given date range or event crosses the day boundary.

Parameter	Type	Description
`startDate`	Date	The start date of the date range or an event record containing both startDate and endDate fields.
`endDate`	Date	The end date if `startDate` is not an event record.

Returns: Boolean

isIntraDay

Returns true if the given date range is contained within one day.

Parameter	Type	Description
`startDate`	Date	The start date of the date range or an event record containing both startDate and endDate fields.
`endDate`	Date	The end date if `startDate` is not an event record.

Returns: Boolean

outside

Returns -1, 0, or 1 based on whether the time of day for the given date is before timeStart (-1), or after timeEnd (1), or between these times (0).

Parameter	Type	Description
`date`	Date \| Number \| String	The hour number, 'HH:MM' time or a `Date` instance to test.

Returns: Number

shiftDate

Returns the given date shifted forward (direction > 0) or backward (direction < 0) by the startShift.

Parameter	Type	Description
`date`	Number \| Date	The date as a `Date` or the millisecond UTC epoch.
`direction`	Number	A value > 0 to shift `date` forward, or < 0 to shift it backwards.

Returns: Date

startOfDay

Returns Date object for the nearest started (shifted) day prior to the given date. The time of this Date will be the startShift.

It is possible for this date to be in the prior day on a midnight-based calendar. For example, if the startShift is 6PM and date is 6AM on May 20, this method will return 6PM of May 19 (the nearest started day).

Parameter	Type	Description
`date`	Date	The date for which to find the nearest started day.

Returns: Date

timeRange

Returns a range of times of day for the given date range.

Parameter	Type	Description
`startDate`	Date	The start date of the date range or an event record containing both `startDate` and `endDate` fields
`endDate`	Date	The end date if `startDate` is not an event record

Returns: Number[]