API Docs

Class: DateTimeRange

PD. DateTimeRange

A class that specified some period of the year and times of the day.

new DateTimeRange( [config] [, solar])

Create a new date/time range instance.

Parameters:
Name Type Argument Description
config object <optional>

A configuration object with the following properties.
Properties of config:
Name Type Argument Description
fromDay number <optional>

The day of the year to start calculating, inclusive (0 to 365/6).
toDay number <optional>

The day of the year to end calculating, inclusive (0 to 365/6).
fromTime number <optional>

The hour of each day to start calculating, in decimal hours (0.0 to 24.0).
toTime number <optional>

The hour of each day to stop calculating, in decimal hours (0.0 to 24.0).
timeStep number <optional>

The fractional hour for each calculation step (0 to 1).
sunriseToSunset boolean <optional>

Whether or not to use daily sunrise and sunset as from/to times, defaults to false.
solar number <optional>

The solar position to copy the location data from, if not given as an argument.
solar PD.SolarPosition <optional>

If not part of config, the solar position to copy the location data from.
Author:
  • drajmarsh
Example
let day, hour;
let sunrise, sunset;
const period = new PD.DateTimeRange({
    fromDay: 91,
    toDay: 187,
    fromTime: 9.0,
    toTime: 17.5,
    timeStep: 10 / 60.0,
    solar: solar
});

period.sanityCheck();

const from_day = period.fromDay;
const to_day = period.toDay;
if (from_day > to_day) {
    period.toDay += period.daysInTheYear;
}

const from_time = period.fromTime;
const to_time = period.toTime;
if (from_time > to_time) {
    to_time += 24.0;
}

for (let dd = from_day; dd <= to_day; ++dd) {

    /// Check to wrap day-of-year index.
    day = (dd >= period.daysInTheYear) ? dd - period.daysInTheYear : dd;
    solar.setDayOfYear(day);

    /// Get sunrise and sunset times.
    sunrise = solar.sunriseTime();
    sunset = solar.sunsetTime();

    for (let tt = from_time; tt < to_time; tt += period.timeStep) {

        /// Check to wrap clock time.
        hour = (tt >= 24.0) ? tt - 24.0 : tt;
        if ((hour >= sunrise) && (hour < sunset)) {

           solar.setTimeOfDay(hour);

           /// TODO: Do stuff..

         }

     }

 }

Members

:number

daysInTheYear

Stores the number of days in the current year (365 or 366).

Type
  • number
:number

fromDay

The ordinal day of the year the period starts.

Type
  • number
:number

fromTime

The starting time of day, in decimal hours.

Type
  • number
:boolean

isDateTimeRange <readonly>

A flag identifying this object as a date/time range.

Type
  • boolean
:PD.SolarPosition

solar

Stores the solar position object used to check days in the year.

Type
:boolean

sunriseToSunset

Whether or not to use daily sunrise and sunset as from/to times.

Type
  • boolean
:number

timeStep

The incremental time step, in decimal hours (1/60 to 24.0).

Type
  • number
:number

toDay

The ordinal day of the year the period ends.

Type
  • number
:number

toTime

The ending time of day, in decimal hours.

Type
  • number

Methods

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

sanityCheck( [solar])

Checks the period data and ensures that values are reasonable and within range.

Parameters:
Name Type Argument Description
solar PD.SolarPosition <optional>

An optional solar position object to check for a leap year.
Returns:

Returns this date/time range object to support method chaining.

Type
PD.DateTimeRange

set(config [, solar])

Initialises the information required for a calculation.

Parameters:
Name Type Argument Description
config object

A configuration object with the following properties.
Properties of config:
Name Type Argument Description
fromDay number <optional>

The day of the year to start calculating, inclusive (0 to 365/6).
toDay number <optional>

The day of the year to end calculating, inclusive (0 to 365/6).
fromTime number <optional>

The hour of each day to start calculating, in decimal hours (0.0 to 24.0).
toTime number <optional>

The hour of each day to stop calculating, in decimal hours (0.0 to 24.0).
timeStep number <optional>

The fractional hour for each calculation step (0 to 1).
sunriseToSunset boolean <optional>

Whether or not to use daily sunrise and sunset as from/to times, defaults to false.
solar number <optional>

An optional solar position to check for a leap year, if not given as an argument.
solar PD.SolarPosition <optional>

If not part of options, the solar position to check for a leap year.
Returns:

Returns this date/time range object to support method chaining.

Type
PD.DateTimeRange

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