API Docs

Class: DateTimeIterator

PD. DateTimeIterator

A class to iterate over a date/time range.

new DateTimeIterator( [config] [, solar])

Create a new date/time iterator.

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).
callbackCalculate function <optional>

A function called on each iteration with (iterator, options) as parameters.
callbackOnTimeout function <optional>

A function called on each timeout with (iterator, options) as parameters.
callbackOnComplete function <optional>

A function called when all the iterations are complete, with just (options) as its parameter.
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 options, the solar position to copy the location data from.
Author:
  • drajmarsh

Extends

Members

:function

callbackCalculate

A function called on each iteration with (iterator, options) as parameters.

Type
  • function
:function

callbackOnComplete

A function called when all the iterations are complete, with just (options) as its parameter.

Type
  • function
:function

callbackOnTimeout

A function called on each timeout with (iterator, options) as parameters.

Type
  • function
:boolean

cancelled

Whether or not to cancel processing.

Type
  • boolean
:number

currentDay

The current ordinal day of the year, when in progress.

Type
  • number
:number

currentTime

The current time on the current day, when in progress.

Type
  • number
:number

dayEndsAt

The time that sunset occurs on the current day.

Type
  • number
:number

dayStartsAt

The time that sunrise occurs on the current day.

Type
  • number
:number

daysInTheYear

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

Type
  • number
Inherited From:
Overrides:
:number

fromDay

The ordinal day of the year the period starts.

Type
  • number
Inherited From:
Overrides:
:number

fromTime

The starting time of day, in decimal hours.

Type
  • number
Inherited From:
Overrides:
:boolean

isDateTimeIterator <readonly>

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

Type
  • boolean
:boolean

isDateTimeRange <readonly>

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

Type
  • boolean
Inherited From:
Overrides:
:PD.DateTimeIterator

iterator

Allow this to be its own iterator when used with throttled calculations.

Type
:number

progress

The current number of days already processed, when in progress.

Type
  • number
:number

progressMax

The total number of days in the period, when in progress.

Type
  • number
:PD.SolarPosition

solar

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

Type
Inherited From:
Overrides:
:boolean

sunriseToSunset

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

Type
  • boolean
Inherited From:
Overrides:
:number

timeStep

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

Type
  • number
Inherited From:
Overrides:
:number

toDay

The ordinal day of the year the period ends.

Type
  • number
Inherited From:
Overrides:
:number

toTime

The ending time of day, in decimal hours.

Type
  • number
Inherited From:
Overrides:
:boolean

working

Whether or not the range is currently being processed.

Type
  • boolean

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).
Inherited From:
Overrides:
Returns:

Returns this date/time instance to support method chaining.

Type
PD.DateTime

getProgress()

Retrieves the current progress as a fraction (0 to 1).

Returns:

Returns the current progress as a fraction (0 to 1).

Type
number

next()

Increments to the next iteration.

Returns:

Returns this iterator to continue, or null to cancel or when complete.

Type
PD.DateTimeIterator | null

reset(config [, solar])

(Re)Initialises the information required for a iterative 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).
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 options, the solar position to copy the location data from.
Returns:

Returns this iterator to support method chaining.

Type
PD.DateTimeIterator

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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:
Returns:

Returns a Plain Old Javascript Object (POJO).

Type
object