CalTime
caltime
is a Node.js package which provides objects, methods and functions
which help to generate, sort, add and subtract timespans. Operations which are
supported by the package include:
- query if timespans overlap with each other
- calculate the overlap (intersection) of timespans
- calculate the addition (union) of timespans
- calculate the remainder left after subtracting timespans
- calculate the difference between timespans
- merge the timespans in an array which overlap
- sort an array of timespans
- calculate the total duration of an array of timespans
- calculate the intersections between two arrays of timespans
A feature provided by caltime
is the ability to define time-based rules using
TimeRule
objects. This allows timespans to be generated according to a
specific period and within certain constraints. Examples of the timespans which
can be generated are:
- 2-3pm on Monday of every week in UTC timezone.
- 14:00-16:00 on the 24th of every month in New York timezone.
- 9-10am on the third Tuesday of every month in Delhi timezone.
- 9am-6pm on Friday and Saturday of every week in Dubai timezone.
caltime
does not attempt to provide functionality which is already provided by
packages such as Moment. For this reason, caltime
avoids converting dates or times to or from their string representation.
API Usage
The caltime
module provides a top-level object with several member functions
and objects. All of these functions and objects can be accessed by installing
the caltime
module.
$ cd <myproject>$ npm install --save caltime
Currently, the caltime
module provides three object constructors, five functions
and the constants object.
var caltime = ;// functional constructor to create TimeSpan objectsvar timespan = caltimetimeSpan;// function to merge TimeSpans in an arrayvar mergeTimeSpans = caltimemergeTimeSpans;// function to sort TimeSpans in an arrayvar sortTimeSpans = caltimesortTimeSpans;// functional constructor to create DateSpan objectsvar datespan = caltimedateSpan;// function to merge DateSpans in an arrayvar mergeDateSpans = caltimemergeDateSpans;// function to sort DateSpans in an arrayvar sortDateSpans = caltimesortDateSpans;// functional constructor to create TimeRule objectsvar timerule = caltimetimeRule;// Constants object provides all of the constants defined by the modulevar caltimeConstants = caltimeconstants;
TimeSpan
A TimeSpan
is an immutable object which defines an interval of time during
a single day. The interval starts at a defined time of the day and has a defined
duration. The TimeSpan
is not associated with any specific date or timezone.
TimeSpan
is deliberately not date specific. It does not take into
account factors such as the timezone, leap seconds or Daylight Savings Time.
If a date-specific timespan must be represented then it is better to use
DateSpan
.
The end time of a TimeSpan
does not form part of the timespan i.e. In
mathematical terms, the TimeSpan
object represents a half-open interval of
time where the end time is exclusive and the begin time is inclusive.
var caltime = ;// call the functional constructor. do not use the new operator.var timespanCtor = caltimetimeSpan;// create a TimeSpan object which represents 09:00am - 10:00am.var spanA = ;
timeSpan()
The timeSpan
function is a functional constructor therefore it should not be
called with the new
operator. The function accepts several arguments:
- inHours: Hour component of the start time of the
TimeSpan
(24 hour clock). Valid range is 0-23. - inMinute: Minutes component of the start time. Valid range is 0-59.
- inSeconds: Seconds component of the start time. Valid range is 0-59.
- inMilliseconds: Milliseconds component of the start time. Valid range is 0-999.
- inDurationMins: Minutes component of the duration of the
TimeSpan
in minutes. Durations can exceed one hour and in this case this argument can exceed the value 59. - inDurationSecs: Seconds component of the duration. Valid range is 0-59.
- inDurationMs: Milliseconds component of the duration. Valid range is 0-999.
getHours(), getMinutes, getSeconds() and getMilliseconds()
These methods return the various components of the start time of the TimeSpan
.
var caltime = ;var timespanCtor = caltimetimeSpan;// create a TimeSpan object which represents 09:01:30:444am - 09:31:30:444am.var spanA = ;spanA; // 9 hoursspanA; // 1 minutespanA; // 34 secondsspanA; // 444 milliseconds
getDurationMins(), getDurationSecs() and getDurationMs()
These methods return the various components of the duration of the TimeSpan
.
A TimeSpan
which is longer than 1 hour will have a duration of greater
than 60 minutes.
var caltime = ;var timespanCtor = caltimetimeSpan;// create a TimeSpan object which represents 09:00:0:000am - 09:04:05:006am.var spanA = ;spanA; // 4 minutesspanA; // 5 secondsspanA; // 6 milliseconds
getTotalDuration()
This method returns the total duration of the TimeSpan
in milliseconds.
var caltime = ;var timespanCtor = caltimetimeSpan;// create a TimeSpan object which represents 09:00:0:000am - 09:01:01:001am.var spanA = ;spanA; // 60000+1000+1 = 61001
isEqual()
Method returns true if two TimeSpan
objects have exactly the same start times
and total durations.
var caltime = ;var timespanCtor = caltimetimeSpan;// create a TimeSpan object which represents 09:00:0:000am - 09:01:01:001am.var spanA = ;var spanB = ;// create a TimeSpan object which represents 09:00:0:000am - 09:02:00:000am.var spanC = ;spanA; // truespanA; // false
isIntersect()
Method returns true if two TimeSpan
objects intersect each other i.e. they
overlap. Since the end time of a TimeSpan
is exclusive, overlapping the
beginning of one TimeSpan
with the end time of another does not count as
an intersection.
var caltime = ;var timespanCtor = caltimetimeSpan;// create a TimeSpan object which represents 09:30am - 10:00am.var spanA = ;// create a TimeSpan object which represents 09:45am - 10:00am.var spanB = ;// create a TimeSpan object which represents 10:00am - 10:15am.var spanC = ;spanA; // truespanA; // false
intersect()
Method calculates the intersection (overlap), if any, between two TimeSpan
objects
and returns a new TimeSpan
object or null if there is no intersection.
var caltime = ;var timespanCtor = caltimetimeSpan;// create a TimeSpan object which represents 09:30am - 10:00am.var spanA = ;// create a TimeSpan object which represents 09:45am - 10:00am.var spanB = ;// create a TimeSpan object which represents 10:00am - 10:15am.var spanC = ;// these two timespans do overlaplet newSpan = spanA;newSpan; // 9newSpan; // 45newSpan; // 15 minutes// these timespans do not overlapnewSpan = spanA; // null
An example of the intersection of two overlapping timespans:
union()
Method calculates the union between two intersecting TimeSpan
objects. It
returns a new TimeSpan
or null if there is no intersection.
var caltime = ;var timespanCtor = caltimetimeSpan;// create a TimeSpan object which represents 09:30am - 10:00am.var spanA = ;// create a TimeSpan object which represents 09:45am - 10:05am.var spanB = ;// create a TimeSpan object which represents 10:00am - 10:15am.var spanC = ;// these two timespans do overlaplet newSpan = spanA;newSpan; // 9newSpan; // 30newSpan; // 35 minutes// these timespans do not intersectnewSpan = spanA; // null
An example of the union of two overlapping timespans:
subtract()
Method calculates the remainder(s) after subtracting one TimeSpan
from
another. It returns an array containing one or two new TimeSpan
objects
which represent the remainders. The array is empty if there is an exact
overlap between the timespans and there is no remainder. The method returns
null if subtraction could not be performed because there wasn't sufficient
overlap.
var caltime = ;var timespanCtor = caltimetimeSpan;// create a TimeSpan object which represents 09:30am - 10:00am.var spanA = ;// create a TimeSpan object which represents 09:45am - 10:00am.var spanB = ;// create a TimeSpan object which represents 10:00am - 10:15am.var spanC = ;// these two timespans do intersectlet result = spanA;resultlength; // 1 element in arrayresult0; // 9result0; // 30result0; // 15 minutes// these timespans do not intersectresult = spanA; // nullresultlength; // 0
An example of the subtraction of two overlapping timespans:
difference()
Method calculates the part of one TimeSpan
(the primary) which does not
intersect with another TimeSpan
(the secondary). It returns an array
containing one or two new TimeSpan
objects which represent the non-overlapping
intervals. The array is empty if there is a complete overlap between the
timespans. The method returns the primary TimeSpan
if there is no overlap.
var caltime = ;var timespanCtor = caltimetimeSpan;// create a TimeSpan object which represents 09:30am - 10:00am.var spanA = ;// create a TimeSpan object which represents 09:45am - 10:30am.var spanB = ;// these two timespans do intersectlet result = spanA;resultlength; // 1 element in arrayresult0; // 9result0; // 30result0; // 15 minutes
An example of the difference between two partially overlapping timespans:
mergeTimeSpans()
Function is passed an Array of TimeSpan
objects and sorts the objects in
the array based on the start time. It then merges any of the TimeSpan
objects
which are overlapping. A new array is returned (merging is not in-situ) which
contains the merged and non-merged TimeSpan
objects.
var caltime = ;var timespanCtor = caltimetimeSpan;var mergeTimeSpans = caltimemergeTimeSpans;var spanList = null;// create TimeSpan objects which overlapconst timeSpanA = ; // 9:00-10:00const timeSpanB = ; // 9:30-10:30const timeSpanC = ; // 10:00-11:00// this TimeSpan does not overlap with othersconst timeSpanD = ; // 11:30-12:30// add TimeSpans to array in ascending orderconst list = timeSpanA timeSpanB timeSpanC timeSpanD;const result = ;resultlength; // 2result0; // 9 as merged TimeSpan is 9:00-11:00result0; // 0result0; // 120result1; // 11 as TimeSpan is not mergedresult1; // 30result1; // 60
sortTimeSpans()
Function takes an Array of TimeSpan
objects and returns a new Array which
contains the same TimeSpan
objects, sorted by their start time.
var caltime = ;var timespanCtor = caltimetimeSpan;var sortTimeSpans = caltimesortTimeSpans;var spanList = null;// create TimeSpan objectsconst timeSpanA = ; // 9:00-10:00const timeSpanB = ; // 10:00-11:00const timeSpanC = ; // 11:00-12:00const timeSpanD = ; // 12:00-13:00// add TimeSpans to array in ascending orderconst list = timeSpanA timeSpanB timeSpanC timeSpanD;// sort list in descending orderconst result = ;resultlength; // 4result0; // 12 (is timeSpanD)result1; // 11 (is timeSpanC)result2; // 10 (is timeSpanB)result3; // 9 (is timeSpanA)// sort list in ascending order againconst result = ;resultlength; // 4result0; // 9 (is timeSpanA)result1; // 10 (is timeSpanB)result2; // 11 (is timeSpanC)result3; // 12 (is timeSpanD)
toString()
Method returns a string which represents the state of the TimeSpan
. This
method is only intended to help debugging and the format of the string
can change between releases.
DateSpan
Similar to a TimeSpan
, a DateSpan
object specifies a start time and
duration, however the DateSpan
is tied to a specific date. This means that
it has a specific end time as factors such as clock changes for Daylight Savings
Time can be taken into account.
The end time of a DateSpan
does not form part of the time interval i.e. in
mathematical terms, the DateSpan
object represents a half-open interval of
time where the end time is exclusive and the begin time is inclusive.
dateSpan()
The dateSpan
function is a functional constructor therefore it should not be
called with the new
operator. The function accepts several arguments:
-
inBegin: A valid Date object which indicates the start time and date.
-
inEnd: Optional argument. A valid Date object which indicates the end time and date. Pass null when it is preferred to specify the duration.
-
inDurationMins: Minutes component of the duration of the
DateSpan
in minutes. Durations can exceed one hour and in this case this argument can exceed the value 59. The argument is optional and should not be passed if inEnd is specified. -
inDurationSecs: Seconds component of the duration. Valid range is 0-59. The argument is optional and should not be passed if inEnd is specified.
-
inDurationMs: Milliseconds component of the duration. Valid range is 0-999. The argument is optional and should not be passed if inEnd is specified.
var caltime = ;var datespanCtor = caltimedateSpan;// DateSpan object which represents 09:00:00:000am - 09:30:00:000am, 15.Nov.2017.var beginDate = 2017 10 15 9 0 0 0;var spanA = ;
getBegin()
This method returns the start time of the DateSpan
as a Date object.
var caltime = ;var datespanCtor = caltimedateSpan;// DateSpan object which represents 09:00:00:000am - 09:30:00:000am, 15.Nov.2017.var beginDate = 2017 10 15 9 0 0 0;var spanA = ;spanA; // Date object
getDurationMins(), getDurationSecs() and getDurationMs()
These methods return the various components of the duration of the DateSpan
.
A DateSpan
which is longer than 1 hour will have a duration which is
greater than 60 minutes.
var caltime = ;var datespanCtor = caltimedateSpan;// DateSpan object which represents 09:00:00:000am - 09:30:11:222am, 15.Nov.2017.var beginDate = 2017 10 15 9 0 0 0;var spanA = ;spanA; // 30 minutesspanA; // 11 secondsspanA; // 222 milliseconds
getTotalDuration()
Method returns the total duration of the DateSpan
in milliseconds.
var caltime = ;var datespanCtor = caltimedateSpan;// DateSpan object which represents 09:00:00:000am - 09:31:02:003am, 15.Nov.2017.var beginDate = 2017 10 15 9 0 0 0;var spanA = ;spanA; // (1*60000)+(2*1000)+(3) = 62003 milliseconds
getEnd()
This method returns the end time of the DateSpan
as a Date object.
var caltime = ;var datespanCtor = caltimedateSpan;// DateSpan object which represents 09:00:00:000am - 09:30:00:000am, 15.Nov.2017.var beginDate = 2017 10 15 9 0 0 0;var spanA = ;spanA; // Date object with time 09:30am
isEqual()
Method returns true if two DateSpan
objects have exactly the same start times
and durations.
var caltime = ;var datespanCtor = caltimedateSpan;// DateSpan object which represents 09:00am - 9:45:00am, 15.Nov.2017.var beginDate = 2017 10 15 9 0 0 0;var spanA = ;// create a DateSpan object with same start and durationvar spanB = ;// create a DateSpan object a different start timevar otherDate = 2017 10 15 10 0 0 0;var spanC = ;// create a DateSpan object with same start but different durationvar spanC = ;spanA; // truespanA; // truespanA; // falsespanA; // false
isIntersect
Method returns true if two DateSpan
objects intersect each other i.e. they
overlap. Since the end time of a DateSpan
is exclusive, overlapping the
beginning of one DateSpan
with the end time of another does not count as
an intersection.
var caltime = ;var datespanCtor = caltimedateSpan;// DateSpan object which represents 09:00am - 9:45:00am, 15.Nov.2017.var beginDate = 2017 10 15 9 0 0 0;var spanA = ;// create a DateSpan object which represents 09:30am - 10:00am.beginDate = 2017 10 15 9 30 0 0;var spanB = ;// create a DateSpan object which represents 10:00am - 10:15am.beginDate = 2017 10 15 10 0 0 0;var spanC = ;spanA; // truespanA; // false
intersect()
Method calculates the intersection, if any, between two DateSpan
objects
and returns a new DateSpan
object or null if there is no intersection.
var caltime = ;var datespanCtor = caltimedateSpan;// DateSpan object which represents 09:00am - 09:45am, 15.Nov.2017.var beginDate = 2017 10 15 9 0 0 0;var spanA = ;// create a DateSpan object which represents 09:30am - 10:00am.beginDate = 2017 10 15 9 30 0 0;var spanB = ;// create a DateSpan object which represents 10:00am - 10:15am.beginDate = 2017 10 15 10 0 0 0;var spanC = ;// date-spans with intersectionvar result = spanA;result; // 9:30amresult; // 09:45am// date-spans with no intersectionresult = spanA; // null
union()
Method calculates the union between two intersecting DateSpan
objects. It
returns a new DateSpan
or null if there is no intersection.
var caltime = ;var datespanCtor = caltimedateSpan;// DateSpan object which represents 09:00am - 09:45am, 15.Nov.2017.var beginDate = 2017 10 15 9 0 0 0;var spanA = ;// create a DateSpan object which represents 09:30am - 10:00am.beginDate = 2017 10 15 9 30 0 0;var spanB = ;// create a DateSpan object which represents 10:00am - 10:15am.beginDate = 2017 10 15 10 0 0 0;var spanC = ;// date-spans with intersectionvar result = spanA;result; // 9:00amresult; // 10:00am// date-spans with no intersectionresult = spanA; // null
subtract()
This method calculates the remainder(s) after subtracting one DateSpan
from
another. It returns an array containing one or two new DateSpan
objects
which represent the remainders. The array is empty if there is an exact
overlap between the date-spans and there is no remainder. The method returns
null if subtraction could not be performed because there wasn't sufficient
overlap.
var caltime = ;var datespanCtor = caltimedateSpan;// DateSpan object which represents 09:00am - 10:00am, 15.Nov.2017.var beginDate = 2017 10 15 9 0 0 0;var spanA = ;// create a DateSpan object which represents 09:30am - 09:45am.beginDate = 2017 10 15 9 30 0 0;var spanB = ;// create a DateSpan object which represents 10:00am - 10:15am.beginDate = 2017 10 15 10 0 0 0;var spanC = ;// date-spans with intersectionvar result = spanA;resultlength; // 2result0; // 9:00amresult0; // 09:30amresult1; // 9:45amresult1; // 10:00am// date-spans with no intersectionresult = spanA; // null
difference()
Method calculates the part of one DateSpan
(the primary) which does
not intersect with another DateSpan
(the secondary). It returns an array
containing one or two new DateSpan
objects which represent the non-overlapping
intervals. The array is empty if there is a complete overlap between the
date-spans. The method returns the primary DateSpan
if there is no overlap.
var caltime = ;var datespanCtor = caltimedateSpan;// DateSpan object which represents 09:00am - 10:00am, 15.Nov.2017.var beginDate = 2017 10 15 9 0 0 0;let dateSpanA = ;// DateSpan object which represents 09:30am - 10:30am, 15.Nov.2017.beginDate = 2017 10 15 9 30 0 0;let dateSpanB = ;// primary date-span starts before the secondarylet result = dateSpanA;resultlength; // 1result0; // 9:00result0; // 9:30
toString()
Method returns a string which represents the state of the DateSpan
. This
method is only intended to help debugging and the format of the string
can change between releases.
mergeDateSpans()
Function is passed an Array of DateSpan
objects and sorts the objects in
the array based on the start time. It then merges any of the DateSpan
objects
which are overlapping. A new array is returned (merging is not in-situ) which
contains the merged and non-merged DateSpan
objects.
var caltime = ;var datespanCtor = caltimedateSpan;var mergeDateSpans = caltimemergeDateSpans;var spanList = null;// DateSpan object which represents 09:00am - 09:45am, 15.Nov.2017.var beginDate = 2017 10 15 9 0 0 0;var spanA = ;// create a DateSpan object which represents 09:30am - 10:00am.beginDate = 2017 10 15 9 30 0 0;var spanB = ;// create a DateSpan object which represents 10:00am - 10:15am.beginDate = 2017 10 15 10 0 0 0;var spanC = ;spanList = spanA spanB spanC ;// merge the intersecting date-spansvar result = ;resultlength; // 2result0; // 9:00amresult0; // 10:00amresult1; // 10:00amresult1; // 10:15am
sortDateSpans()
Function takes an Array of DateSpan
objects and returns a new Array which
contains the same DateSpan
objects, sorted by their start time.
var caltime = ;var datespanCtor = caltimedateSpan;var sortDateSpans = caltimesortDateSpans;var spanList = null;// DateSpan object which represents 09:00am - 09:30am, 15.Nov.2017.var beginDate = 2017 10 15 9 0 0 0;var spanA = ;// create a DateSpan object which represents 09:30am - 10:00am.beginDate = 2017 10 15 9 30 0 0;var spanB = ;// create a DateSpan object which represents 10:00am - 10:15am.beginDate = 2017 10 15 10 0 0 0;var spanC = ;spanList = spanA spanB spanC ;// sort in descending ordervar result = ;resultlength; // 3result0; // 10:00amresult1; // 09:30amresult2; // 09:00am// sort in ascending ordervar result = ;resultlength; // 3result0; // 09:00amresult1; // 09:30amresult2; // 10:00am
measureDateSpans()
Function is passed an Array of DateSpan
objects, sorts the objects based on
their start time and then merges any which overlap. The function then examines
each remaining 'DateSpan' object and calculates the total duration. The duration
is calculated using one of many available rules. The simplest way to calculate
the duration is the raw number of milliseconds i.e. DURATION_RAW_MSECS
. Other
options round-up the duration based on the number of natural time units which
the DateSpan
objects overlap with.
A natural time unit is an interval of time within the boundaries defined by a clock or calendar. For example, a natural day is the interval of time between 00:00 midnight and the following midnight. A natural minute is the interval of clock time from when the millisecond count is zero until the following occurrence of zero milliseconds.
Natural durations can be useful when you need to know how many whole units of time are used by multiple time-spans. Rounding up the raw total duration is not possible as some some time-spans may overlap with the same natural time intervals. An example of this situation could be where a resource charges per day even where they are only partially utilised on some days.
The options (constants) available to control how the duration is calculated:
DURATION_RAW_MSECS
DURATION_NATURAL_SECS
DURATION_NATURAL_MINS
DURATION_NATURAL_HOURS
DURATION_NATURAL_DAYS
const caltime = ;const datespanCtor = caltimedateSpan;const measureDateSpans = caltimemeasureDateSpans;const spanList = ;// DateSpan object which represents 09:00am 15.Nov.2017 - 9:00am 16.Nov.2017.const dateA = 2017 10 15 9 0 0 0;const dateSpanA = tc; // 24 hoursspanList;// DateSpan object which represents 10:00am 16.Nov.2017 - 10:00am 17.Nov.2017.const dateB = 2017 10 16 10 0 0 0;const dateSpanB = tc; // 24 hoursspanList;tc; // 3 natural days
intersectDateSpans()
Function takes two Arrays of DateSpan
objects and returns a new Array which
contains new DateSpan
objects, each representing an intersection between
a DateSpan
object from each Array.
const caltime = ;const datespanCtor = caltimedateSpan;const intersectDateSpans = caltimeintersectDateSpans;let spanListA = null;let spanListB = null;// DateSpan object which represents 09:00am - 10:00am.var beginDate = 2017 10 15 9 0 0 0;var spanA = ;// create a DateSpan object which represents 10:00am - 11:00am.beginDate = 2017 10 15 10 0 0 0;var spanB = ;// create a DateSpan object which represents 10:00am - 10:30am.beginDate = 2017 10 15 10 0 0 0;var spanC = ;// create a DateSpan object which represents 14:00 - 15:00.beginDate = 2017 10 15 14 0 0 0;var spanD = ;// populate the arraysspanListA = spanA spanB ;spanListB = spanC spanD ;// sort in descending orderlet result = ;resultlength; // 1 overlap between spanB and spanCresult0; // 10:00amresult0; // 10:30am
TimeRule
The TimeRule
object allows logic to be defined which can then be used to
automatically generate DateSpan
objects for a range of time. Several types
of rules can be created. The constraint applied to the rule controls for which
days or dates the DateSpan
objects are created. Possible constraints are:
- The same day(s) of the week, every week e.g. every Monday from 9-10am.
- The same date every month e.g. 4th of every month from 1-2pm.
- The Nth weekday of every month e.g. 3rd Tuesday of the month from 9-10pm.
- The last weekday of every month e.g. last Friday of every month.
timeRule()
The timeRule
function is a functional constructor, therefore it should not be
called with the new
operator. The function accepts several arguments:
- inTimeSpan:
TimeSpan
object describing the start time and duration of theDateSpan
objects which will be generated by the rule. - inConstraint: Controls how the rule generates
DateSpan
objects. Constants for each type of constraint are provided by thecaltime
module's constants object. - inDay: Specifies the day of the week or day of the month. How this value is
interpreted depends on
inConstraint
. - inTZ: String defining the timezone used when generating the
DateSpan
objects. See https://www.iana.org/time-zones for valid timezone identifier strings. The timezone is required because theinTimeSpan
argument is timezone agnostic. - inBegin: Optional argument. Defines a start time before which the rule does
not apply and therefore does not generate any
DateSpan
objects. - inEnd: Optional argument. Defines an end time after which the rule does
not apply and therefore does not generate any
DateSpan
objects.
getTimeSpan()
Method returns a TimeSpan
object which defines the span of time during the day
which is used when generating the DateSpan
objects.
getDay()
Method returns the day (0 (Sunday) - 6 (Saturday) of the week or day of the month (1-31)
which indicates which days which the rule will generate a DateSpan
object.
getTZ()
Method returns a string which indicates the timezone used when generating the
DateSpan
objects.
getBegin()
This method returns the start time from which the rule begins generating
DateSpan
objects.
getEnd()
This method returns the end time up to which the rule generates DateSpan
objects.
generateDateSpans()
The method generates an Array of DateSpan
objects which meet all of the constraints
imposed by the TimeRule
.
var caltime = ;var timespanCtor = caltimetimeSpan;var timeruleCtor = caltimetimeRule;var modconstants = caltimeconstants;// Rule will generate date-spansvar spanA = ;var rule = ;// now generate DateSpan objects based on the rule constraintsvar beginDate = 2017 5 1 12 0 0 0 0; // 12:00, 1 June 2017var endDate = 2017 5 20 12 0 0 0 0; // 12:00, 20 June 2017var result = rule;resultlength; // 2result0; // 7 June 2017, 09:00-09:30am Eastern Daylight Time (-0400)result1; // 14 June 2017, 09:00-09:30am Eastern Daylight Time (-0400)
Constants
The module makes several constants available in the constants
object. Each
constant is a data member of this object. Constants are available which can
be used to convert values between different units of time.
Examples of constants for time conversion:
var caltime = ;var module_constants = caltimeconstants;module_constantsMSECS_PER_MIN; // milliseconds per minutemodule_constantsMSECS_PER_HOUR; // milliseconds per hourmodule_constantsMAX_MINS_PER_DAY; // maximum number of minutes in a 24 hour day
Constants are available which define the day of the week. These values are the
same as those used by the Javascript Date
object.
var caltime = ;var module_constants = caltimeconstants;module_constantsSUNDAY; // 0module_constantsMONDAY; // 1module_constantsTUESDAY; // 2module_constantsWEDNESDAY; // 3module_constantsTHURSDAY; // 4module_constantsFRIDAY; // 5module_constantsSATURDAY; // 6
Constants are available which define the months of the year. These values are
the same as those used by the Javascript Date
object.
var caltime = ;var module_constants = caltimeconstants;module_constantsJAN; // Januarymodule_constantsFEB; // Februarymodule_constantsMAR; // Marchmodule_constantsAPR; // Aprilmodule_constantsMAY; // Maymodule_constantsJUN; // Junemodule_constantsJUL; // Julymodule_constantsAUG; // Augustmodule_constantsSEPT; // Septembermodule_constantsOCT; // Octobermodule_constantsNOV; // Novembermodule_constantsDEC; // December
Constants are also available for use with the TimeRule
functional constructor.
These constants define more than one day of the week. They represent commonly
used working weeks and weekends from various cultures. They can be passed as
the inDay
argument to the timeRule
constructor.
var caltime = ;var module_constants = caltimeconstants;module_constantsWEEKDAYS_MON_FRI; // 5 days, Monday - Fridaymodule_constantsWEEKDAYS_SUN_THURS; // 5 days, Sunday - Thursdaymodule_constantsWEEKDAYS_MON_SAT; // 6 days, Monday - Saturdaymodule_constantsWEEKDAYS_MON_SUN; // 7 days, Monday - Sundaymodule_constantsWEEKDAYS_SUN_FRI; // 6 days, Sunday - Fridaymodule_constantsWEEKDAYS_SAT_WED; // 5 days, Sunday - Wednesday and Saturdaymodule_constantsWEEKDAYS_SAT_THURS; // 6 days, Sunday - Thursday and Saturdaymodule_constantsWEEKDAYS_BRUNEI; // 5 days, Monday - Thursday and Saturdaymodule_constantsWEEKDAYS_SAT_SUN; // 2 days, Saturday and Sundaymodule_constantsWEEKDAYS_FRI_SAT; // 2 days, Friday and Saturdaymodule_constantsWEEKDAYS_THURS_FRI; // 2 days, Thursday and Fridaymodule_constantsWEEKDAYS_BRUNEI_WEEKEND; // 2 days, Friday and Sunday
These constants define the type of constraint applied by the TimeRule
.
var caltime = ;var module_constants = caltimeconstants;module_constantsCONSTRAINT_DAY_OF_WEEK; // example: every Tuesdaymodule_constantsCONSTRAINT_DAY_OF_MONTH; // example: 4th day of every monthmodule_constantsCONSTRAINT_FIRST_OF_MONTH; // example: 1st Wed. of every monthmodule_constantsCONSTRAINT_SECOND_OF_MONTH; // example: 2nd Thurs. of every monthmodule_constantsCONSTRAINT_THIRD_OF_MONTH; // example: 3rd Sat. of every monthmodule_constantsCONSTRAINT_FOURTH_OF_MONTH; // example: 4th Monday of every monthmodule_constantsCONSTRAINT_FIFTH_OF_MONTH; // example: 5th Wed. of every monthmodule_constantsCONSTRAINT_LAST_OF_MONTH; // example: Last Monday of every month
API Documentation
Documentation describing the last major release of caltime
is available at
CalTime API.
The latest version of the API documentation can be generated using jsdoc
. The
documentation is created in the docs/
directory.
$ cd <caltime-git-clone>$ npm run -s doc
Support
Bug Reports and New Feature Requests should be reported at the CalTime GitHub Issues Page.
Dependencies
caltime
currently depends on two modules when in production. Other modules are
required to test or develop caltime
. The production dependencies are:
License
caltime
is copyright (c) 2017-2018 Michael McCarthy michael.mccarthy@ieee.org.
caltime
is free software, licensed under the MIT licence. See the file LICENSE
in this distribution for more information.