API Docs

Class: DateTime

PD. DateTime

Defines a specific data and time.

This class defaults to a standard year which always starts on a Monday and is not a leap year. If you assign it a specific year, then that may be a leap year and have an extra day.

The concept of the 'average' or standard year is quite important and needs some explanation. As a year with 365 days does not evenly divide into 52 weeks, each consecutive year starts on a different weekday. For example, the first day of the year in 2010 was a Friday, in 2009 it was a Thursday and in 2008 it was a Tuesday. This means that different years may contain a different number of weekends and/or holiday periods and these may occur at slightly different times within each season.

Whilst the effect of this on annual energy use is likely to be quite small, it is an arbitrary and unnecessary variation that may mask other effects that the designer is more interested in. It also presents a problem when designing annual operational or holiday schedules as these would need to be either manually edited to match each test year and locale-specific holiday sequence, or the logic required to apply generic schedules to any particular year and locale would be very complex and extensive indeed.

Thus, an 'average' or standard year is used, starting and finishing on a Monday. This is how dedicated energy analysis tools such as DOE-2 and EnergyPlus also work, allowing their users to arrange seven daily schedules into a set of characteristic weekly schedules, and then arrange 52 of these weekly schedules over the year.

This applies also to solar radiation calculations and daylighting where direct comparison between models or options is important without having to worry about slight variations in schedules resulting from different analysts using different years, etc.

new DateTime( [config])

Creates a new date/time value.

Parameters:
Name Type Argument Default Description
config object <optional>
 null

An optional configuration object.
Properties of config:
Name Type Argument Description
clockTime number <optional>

An optional local clock time, in decimal hours (0.0 to 24.0).
dayOfMonth number <optional>

An optional day of the month component of the date (1 to 31).
monthOfYear number <optional>

An optional month of the year component of the date (0 to 11).
year number <optional>

An optional 4 digit year component of the date (-4712 to 3500).
Author:
  • drajmarsh

Members

:number

clockTime

The local clock time, in decimal hours (0.0 to 24.0).

Type
  • number
:number

dayOfMonth

The day of the month component of the date (1 to 31).

Type
  • number
:number

dayOfYear

The ordinal day of the year (0 to 364/365).

Type
  • number
:boolean

isDateTime <readonly>

A flag identifying this object as a date/time.

Type
  • boolean
:number

monthOfYear

The month of the year component of the date (0 to 11).

Type
  • number
:number

timeOfDay

The local clock time, in decimal hours (0.0 to 24.0).

Type
  • number
:number

year

The 4 digit year component of the date.

Defaults to 2018, the last non-leap year starting on a Monday.

Type
  • number
:Array.<number>

DAYS_IN_MONTH <static>

An array containing the number of days in each month in a non-leap year.

Type
  • Array.<number>
:Array.<number>

DAY_INDEX <static>

An array containing the ordinal index of the first day of each month in a non-leap year.

Type
  • Array.<number>
:Array.<number>

DAY_INDEX_LEAP_YEAR <static>

An array containing the ordinal index of the first day of each month in a leap year.

Type
  • Array.<number>
:Array.<string>

MONTH_NAMES <static>

An array containing full month names.

Type
  • Array.<string>
:Array.<string>

MONTH_NAMES_LETTER <static>

An array containing just the first letter of each month name.

Type
  • Array.<string>
:Array.<string>

MONTH_NAMES_SHORT <static>

An array containing abbreviated month names.

Type
  • Array.<string>

Methods

copy(from)

Copy the given date/time to this date/time.

Parameters:
Name Type Description
from PD.DateTime

Another date/time instance to copy from.
Returns:

Returns this date/time instance to support method chaining.

Type
PD.DateTime

fromJSON(data)

Extracts date and/or time information from the given object.

Parameters:
Name Type Description
data object

An object that might contain date/time information.
Properties of data:
Name Type Argument Description
clockTime number <optional>

An optional local clock time, in decimal hours (0.0 to 24.0).
dayOfMonth number <optional>

An optional day of the month component of the date (1 to 31).
monthOfYear number <optional>

An optional month of the year component of the date (0 to 11).
dayOfYear number <optional>

An optional day of the year (0 to 364/5) that overrides the dayOfMonth and monthOfYear.
year number <optional>

An optional 4 digit year component of the date (-4712 to 3500).
Returns:

Returns this date/time instance to support method chaining.

Type
PD.DateTime

getDOY(dayOfMonth, monthOfYear)

Computes the ordinal number of the day within the year.

Parameters:
Name Type Description
dayOfMonth number

The ordinal day of the month (1 to 31).
monthOfYear number

The ordinal month of the year (0 to 11).
Returns:

Returns the ordinal number of the day within the year (0 to 364/5).

Type
number

getDateAsString()

Generates a string with the current date.

Returns:

Returns a string with the date in 'dd mmm' format.

Type
string

setDayOfYear(value)

Sets the day of the year (0 to 365).

Parameters:
Name Type Description
value number

The day of the year (0 to 365).

setTimeOfDay(value)

Sets the local clock time, in decimal hours (0.0 to 24.0).

Parameters:
Name Type Description
value number

The local clock time, in decimal hours (0.0 to 24.0).

toJSON( [data])

Converts object instance to a simple POJO for conversion to JSON.

This method is used to copy, store and save the data for ths object, so the returned object must have all the properties required be able to rebuild this instance in its entirety when passed to the class constructor.

Parameters:
Name Type Argument Description
data object <optional>

An optional parent object to append this data to.
Returns:

Returns a Plain Old Javascript Object (POJO).

Type
object

updateDate()

Update the month of the year and day of the month from the current day of the year.

Returns:

Returns this date/time instance to support method chaining.

Type
PD.DateTime

JSONSchema() <static>

Retrieves the JSON schema for a date/time object.

Returns:

Returns a JSON schema object.

Type
object

formatAsMMMDD(dayOfYear [, year]) <static>

Returns a string with the given day of the year in 'mmmdd' format.

This is mainly used in charts and graphs where space is limited. Some example returns would be Jan01, Apr15 or Dec25.

Parameters:
Name Type Argument Description
dayOfYear number

The ordinal day of the year (0-364/5).
year number <optional>

A four-digit year number (eg: 2010), defaults to a non-leap year.
Returns:

Returns a formatted date string.

Type
string

formatDate(dayOfYear [, year] [, includeYear]) <static>

Returns a string with the given day of the year in 'dd mmm' format.

If a valid year value is given and the include_year argument is true, it returns a string in 'dd mmm YYYY' format.

Some example returns would be 01 Jan, 15 Apr or 25 Dec. If the year is included, example returns would be 01 Jan 2014, 15 Apr 2015 or 25 Dec 2016.

Parameters:
Name Type Argument Default Description
dayOfYear number

The ordinal day of the year (0-364/5).
year number <optional>

A four-digit year number (eg: 2010), defaults to a non-leap year.
includeYear boolean <optional>
 false

Whether or not to include the year, if given.
Returns:

Returns a formatted date string.

Type
string

formatDuration(decimalHours [, seconds]) <static>

Returns a string with the given duration in 'HH:mm' or 'HH:mm:ss' format.

Parameters:
Name Type Argument Default Description
decimalHours number

The duration, in decimal hours.
seconds boolean <optional>
 false

When true it displays seconds value, otherwise just rounds to nearest minute.
Returns:

Returns the formatted duration string.

Type
string

formatMilliseconds(ms [, decimals]) <static>

Returns a string with formatted milliseconds.

Parameters:
Name Type Argument Description
ms number

The duration in milliseconds.
decimals number <optional>

The number of decimal places to show, defaults to 3.
Returns:

Returns the formatted duration string.

Type
string

formatMonthName(monthOfYear) <static>

Returns a string with the given month abbreviation.

Some example returns would be Jan, Apr or Dec.

Parameters:
Name Type Description
monthOfYear number

The ordinal month of the year (0-11).
Returns:

Returns a formatted month name string.

Type
string

formatTime(clockTime [, seconds]) <static>

Returns a string with the given time in 'HH:mm' or 'HH:mm:ss' format.

Parameters:
Name Type Argument Default Description
clockTime number

The local time of the day, in decimal hours (0-24).
seconds boolean <optional>
 false

When true it displays seconds value, otherwise just rounds to nearest minute.
Returns:

Returns the formatted time string.

Type
string

formatTimezone(decimalHours) <static>

Returns a string with the given duration in '±HH:mm' or '±HH:mm:ss' format.

Parameters:
Name Type Description
decimalHours number

The time period, in decimal hours (-14 to +14), defaults to current timezone.
Returns:

Returns the formatted timezone.

Type
string

generateDateAsFileNameSuffix( [date]) <static>

Generates a string of the form '2016-12-31-2359' based on the system date time.

This is primarily used as a file name suffix for uniquely identifying temporary files and automatically named exports.

Parameters:
Name Type Argument Description
date object <optional>

An optional Javascript Date() object, defaults to current date/time.
Returns:

Returns a string with the year, month, day and time.

Type
string

getDOY(dayOfMonth, month_of_year [, year]) <static>

Calculate the ordinal number of the day within the year (0-364/5).

Parameters:
Name Type Argument Description
dayOfMonth number

The ordinal day of the month (1 to 31).
month_of_year number

The ordinal month of the year (0 to 11).
year number <optional>

An optional four-digit year number (eg: 2010), defaults to a non-leap year.
Returns:

Returns the ordinal number of the day within the year (0-364/5).

Type
number

getDayAndMonth(dayOfYear [, year]) <static>

Returns an object containing day (1 to 31) and month (0 to 11) properties.

Parameters:
Name Type Argument Description
dayOfYear number

The ordinal day of the year (0-364/5).
year number <optional>

An optional four-digit year number (eg: 2010), defaults to a non-leap year.
Returns:

Returns an object with day (1 to 31) and month (0 to 11) properties.

Type
object

getDayIndexArray( [year]) <static>

Retrieves an array of ordinal day indexes for each month of the year.

NOTE: The reason for using this method is that day indices of each month after February will change during a leap year, so this method returns a different array if it detects that the given year is a leap year.

Parameters:
Name Type Argument Description
year number <optional>

A four-digit year number (eg: 2010), defaults to a non-leap year.
Returns:

Returns an array of 12 day indices.

Type
Array

getDayOfTheWeek(dayOfMonth, monthOfYear [, year]) <static>

Returns the day of the week index for the given day, month and year.

The day of the week index refers to Monday(0), Tuesday(1), Wednesday(2), Thursday(3), Friday(4), Saturday(5) and Sunday(6). This differs from the standard JavaScript Date.getDay() method which assumes the week starts on a Sunday. In order to group weekends and public holidays, most analysis tools use Monday as the first day of the week and Sunday as the last.

Parameters:
Name Type Argument Description
dayOfMonth number

The day of the month (1 to 31).
monthOfYear number

The month of the year (0 11).
year number <optional>

A four-digit year number (eg: 2010), defaults to a non-leap year.
Returns:

Returns the day of the week (0 to 6).

Type
number

getDaysInMonth(monthOfYear [, year]) <static>

Retrieves the number of days in the given month.

If the given month is outside the range zero to eleven, this method will return zero.

Parameters:
Name Type Argument Description
monthOfYear number

The ordinal month of the year (0-11).
year number <optional>

An optional four-digit year number (eg: 2010), defaults to a non-leap year.
Returns:

Returns a string with the first letter of the month name.

Type
string

getDaysInYear( [year]) <static>

Retrieves the number of days in the year.

NOTE: The reason for using this method is that the number of days in a leap year are different than a normal year, so this method returns 366 instead of 365 if it detects that the given year is a leap year.

Parameters:
Name Type Argument Description
year number <optional>

A four-digit year number (eg: 2010), defaults to a non-leap year.
Returns:

Returns the total number of days in the year (365 or 366).

Type
number

getMonthEndDay(monthOfYear [, year]) <static>

Retrieves the ordinal index of the end of the given month within the year.

Parameters:
Name Type Argument Description
monthOfYear number

The ordinal month of the year (0-11).
year number <optional>

A four-digit year number (eg: 2010), defaults to a non-leap year.
Returns:

Returns the ordinal number of the day within the year (0-364/5).

Type
number

getMonthName(monthOfYear) <static>

Retrieves the abbreviated name of the given month.

Parameters:
Name Type Description
monthOfYear number

The ordinal month of the year (0-11).
Returns:

Returns a string with the abbreviated month name.

Type
string

getMonthNameFull(monthOfYear) <static>

Retrieves the full name of the given month.

Parameters:
Name Type Description
monthOfYear number

The ordinal month of the year (0-11).
Returns:

Returns a string with the full month name.

Type
string

getMonthNameLetter(monthOfYear) <static>

Retrieves the first letter of the given month name.

Parameters:
Name Type Description
monthOfYear number

The ordinal month of the year (0-11).
Returns:

Returns a string with the first letter of the month name.

Type
string

getMonthStartDay(monthOfYear [, year]) <static>

Retrieves the ordinal index of the start of the given month within the year.

Parameters:
Name Type Argument Description
monthOfYear number

The ordinal month of the year (0-11).
year number <optional>

A four-digit year number (eg: 2010), defaults to a non-leap year.
Returns:

Returns the ordinal number of the day within the year (0-364/5).

Type
number

getNearestMonth(dayOfYear [, year]) <static>

Returns the index of the month the given day is in.

Parameters:
Name Type Argument Description
dayOfYear number

The ordinal day of the year (0-364/5).
year number <optional>

A four-digit year number (eg: 2010), defaults to a non-leap year.
Returns:

Returns the ordinal number of the month within the year (0-11).

Type
number

getSiteTime() <static>

Retrieves the global date and time used for the current site.

This method returns the PD.GlobalState.dateTime object that is used by several other classes as the default date/time for the current site.

Returns:

Returns the global date and time object.

Type
PD.DateTime

incrementDate(event, increment, dayOfYear [, year]) <static>

Returns the day of the year index incremented by the given value.

This method checks the event/key value to adjust the number of days to increment by, based on sensible defaults.

Parameters:
Name Type Argument Description
event object | PD.KEY

A mouse wheel/scroll event, or modifier key code.
increment number

The amount of increment, positive or negative.
dayOfYear number

The ordinal day of the year (0-364/5).
year number <optional>

A four-digit year number (eg: 2010), defaults to a non-leap year.
Returns:

Returns the ordinal number of the day within the year (0-364/5).

Type
number

incrementEvenlyOverMonth(increment, dayOfMonth, monthOfYear [, year]) <static>

Returns the day of the year index incremented by an even amount each month.

This method tries to start and end the incremented values exactly on month boundaries. If the increment is 3 days, then there are awkward single day steps at the end of each month that contains 31 days. If the increment is close to 4 days (and sometimes 3), then the steps are better, even when a month has just 28 days.

Parameters:
Name Type Argument Description
increment number

The amount of increment, positive or negative.
dayOfMonth number

The ordinal index of the day in the month (0-31).
monthOfYear number

The ordinal index of the month in the year (0-11).
year number <optional>

A four-digit year number (eg: 2010), defaults to a non-leap year.
Returns:

Returns the ordinal number of the day within the year (0-364/5).

Type
number

isBetweenDayRange(dayOfYear, range1, range1) <static>

Determines if the given day of the year is within the given range.

This method automatically sorts out whether the range passes over year start/end or is entirely within the bounds of the year.

Parameters:
Name Type Description
dayOfYear number

The ordinal day of the year (0-364/5).
range1 number

The ordinal day of the first range bounds (0-364/5).
range1 number

The ordinal day of the second range bounds (0-364/5).
Returns:

Returns tru if the day is within the range, otherwise false.

Type
boolean

isLeapYear(year) <static>

Whether or not the specified year is a leap year.

Parameters:
Name Type Description
year number

A four-digit year number (eg: 2010).
Returns:

Returns true if the year is a leap year.

Type
boolean

parseTime(timeString) <static>

Utility for more permissive time parsing.

This method should work with all of the following and more:

1:00 pm, 1:00 p.m., 1:00 p, 1:00pm, 1:00p.m., 1:00p, 1 pm, 1 p.m., 1 p, 1pm, 1p.m., 1p, 13:00 or even 13 and 1300.

Parameters:
Name Type Description
timeString string

A string containing some variant of a time specification.
Returns:

Returns a standard Date object with the parsed hours and minutes.

Type
Date

parseTimeToDecimalHours(timeString) <static>

Utility for permissive time parsing to decimal hours in the range 0 to 24.

This method should work with all of the following and more:

1:00 pm, 1:00 p.m., 1:00 p, 1:00pm, 1:00p.m., 1:00p, 1 pm, 1 p.m., 1 p, 1pm, 1p.m., 1p, 13:00 or even 13 and 1300.

Parameters:
Name Type Description
timeString string

A string containing some variant of a time specification.
Returns:

Returns a numerical value representing decimal hours in the range 0 to 24.

Type
number

snapToNearestMonth(dayOfYear [, year]) <static>

Returns the ordinal day of the year index at the start of the closest month.

Parameters:
Name Type Argument Description
dayOfYear number

The ordinal day of the year (0-364/5).
year number <optional>

A four-digit year number (eg: 2010), defaults to a non-leap year.
Returns:

Returns the ordinal number of the day within the year (0-364/5).

Type
number