mtime 1.3.0
Loading...
Searching...
No Matches
libmtime C language bindings
Collaboration diagram for libmtime C language bindings:

Files

file  mtime_calendar.h
 Singleton Calendar connecting all supported calendar types.
 
file  mtime_date.h
 Date and some operations supported on Date.
 
file  mtime_datetime.h
 DateTime and some operations supported on DateTime.
 
file  mtime_eventHandling.h
 Definition of the basic event type and its methods. Definition of Even-Groups which contains a list of events.
 
file  mtime_julianDay.h
 Julian Day Calendar and some operations supported on julian dates.
 
file  mtime_time.h
 Time and some operations supported on Time.
 
file  mtime_timedelta.h
 TimeDelta and some operations supported on TimeDelta.
 
file  mtime_utilities.h
 Support for handling ISO 8601:2004 repeated time interval strings.
 

Data Structures

struct  _date
 struct _date containing usual date parameters. More...
 
struct  _datetime
 struct _datetime contains a struct _date and a struct _time element. More...
 
struct  _eventGroup
 struct _eventGroup defines an Event-group. Each event group has an associated list of events. Event group is a place holder to 'group' events based on some user defined charteristics. More...
 
struct  _event
 struct _event defines events. Events are set to be triggered at pre-specified intervals. More...
 
struct  _julianday
 Struct _julianday containing julian day parameters. More...
 
struct  _time
 struct _time containing usual time parameters. More...
 
struct  _timedelta
 Struct _timedelta containing timedelta and sign of year parameter. More...
 
struct  _divisionquotienttimespan
 Struct _divisionquotienttimespan is used for storing division of two time-delta results. More...
 

Macros

#define NO_OF_DAYS_IN_A_MONTH_FOR_CAL_TYPE360   30
 
#define NO_OF_MONTHS_IN_A_YEAR   12
 
#define NO_OF_HOURS_IN_A_DAY   24
 
#define NO_OF_DAYS_IN_A_YEAR_FOR_CAL_TYPE360   360
 
#define NO_OF_DAYS_IN_A_YEAR_FOR_CAL_TYPE365   365
 
#define NO_OF_DAYS_IN_A_LEAP_YEAR   366
 
#define NO_OF_DAYS_IN_400_YEARS   146097
 
#define YEAR_UPPER_BOUND   2147483647
 
#define YEAR_LOWER_BOUND   -2147483648
 
#define POSIXSTRING_DAY_LOWER_BOUND   15
 
#define POSIXSTRING_MONTH_LOWER_BOUND   10
 
#define POSIXSTRING_YEAR_LOWER_BOUND   1582
 
#define POSIXSTRING_YEAR_UPPER_BOUND   9999
 
#define MAX_CALENDAR_STR_LEN   32
 provides a string length for toString.
 
#define MAX_DATETIME_STR_LEN   32
 
#define MAX_DATE_STR_LEN   32
 
#define MAX_TIME_STR_LEN   32
 
#define MAX_TIMEDELTA_STR_LEN   32
 
#define MAX_JULIANDAY_STR_LEN   32
 
#define MAX_EVENT_STR_LEN   132
 provides a Maximum string length for Group Names.
 
#define MAX_GROUPNAME_STR_LEN   132
 provides a Maximum string length for Group Names.
 
#define MAX_EVENTNAME_STR_LEN   132
 provides a Maximum string length for Event names.
 
#define _MTIME_INDEFINETLY   -1
 
#define MAX_REPETITION_STR_LEN   32
 provides a string length for repeated time interval components.
 

Enumerations

enum  compare_return_val { equal_to = 0 , greater_than = 1 , less_than = -1 , compare_error = -128 }
 
enum  calendarType { CALENDAR_NOT_SET = 0 , PROLEPTIC_GREGORIAN = 1 , YEAR_OF_365_DAYS = 2 , YEAR_OF_360_DAYS = 3 }
 enum calendarType lists the calendarTypes supported. The values are used for selecting calendars. More...
 

Functions

void initCalendar (calendarType ct)
 To initialize a new calendar.
 
void freeCalendar (void)
 called to discard the selected calendar type.
 
calendarType getCalendarType (void)
 To query the current calendar type.
 
char * calendarToString (char *calendar)
 convert the calendar identifier into a human readable string.
 
struct _datenewDate (const char *ds)
 Construct new Date using an ISO 8601 conforming string.
 
struct _datenewRawDate (int64_t _year, int _month, int _day)
 Construct new Date using 'raw' numerical values.
 
struct _dateconstructAndCopyDate (struct _date *d)
 Copy the values and construct a new date.
 
void deallocateDate (struct _date *d)
 Destructor of Date. Free the Date object.
 
struct _datereplaceDate (struct _date *, struct _date *)
 COPY a Date object.
 
char * dateToString (struct _date *, char *ds)
 Get Date as an extended string.
 
char * dateToBasicString (struct _date *, char *ds)
 Get Date as a basic string.
 
char * dateToPosixString (struct _date *d, char *toStr, char *fmtString)
 Get Date in 'struct tm' format and return as a string.
 
struct _datetimenewDateTime (const char *datetime_string)
 Construct new DateTime using an ISO 8601 conforming string.
 
struct _datetimenewRawDateTime (int64_t _year, int _month, int _day, int _hour, int _minute, int _second, int _ms)
 Construct new DateTime using 'raw' numerical values.
 
struct _datetimeconstructAndCopyDateTime (struct _datetime *dt)
 Copy the values and construct a new datetime.
 
void deallocateDateTime (struct _datetime *dt)
 Destructor of DateTime.
 
compare_return_val compareDatetime (struct _datetime *dt1, struct _datetime *dt2)
 Compare two datetimes and return (dt1 > dt2) OR (dt1 = dt2) OR (dt1 < dt2).
 
struct _datetimereplaceDatetime (struct _datetime *dtsrc, struct _datetime *dtdest)
 COPY a DateTime object.
 
char * datetimeToString (struct _datetime *dt, char *toStr)
 Get DateTime as a string.
 
char * datetimeToBasicString (struct _datetime *dt, char *toStr)
 Get DateTime as a basic string.
 
char * datetimeToPosixString (struct _datetime *dt, char *toStr, char *fmtString)
 Get DateTime in 'struct tm' format and return as a string.
 
int getNoOfDaysInMonthDateTime (struct _datetime *dt)
 Get nod (number of Days) in the month of DateTime.
 
int getNoOfDaysInYearDateTime (struct _datetime *dt)
 Get number of days in the Year of DateTime.
 
int getDayOfYearFromDateTime (struct _datetime *currentdt)
 Get the 'day-of-year' value of a DateTime.
 
int64_t getNoOfSecondsElapsedInMonthDateTime (struct _datetime *dt)
 Get number of seconds elapsed in the month of DateTime.
 
int getNoOfSecondsElapsedInDayDateTime (struct _datetime *dt)
 Get number of seconds elapsed in the day of DateTime.
 
struct _juliandaygetJulianDayFromDateTime (struct _datetime *dt, struct _julianday *jd)
 Get the Julian Day from DateTime.
 
struct _datetimegetDateTimeFromJulianDay (struct _julianday *jd, struct _datetime *dt)
 Get the DateTime from Julian Day.
 
compare_return_val getDateTimeIsInRange (struct _datetime *dtRef, struct _datetime *dtStart, struct _datetime *dtEnd)
 
struct _eventGroupnewEventGroup (const char *_eventGroupName)
 Construct new event-Group using a string.
 
void deallocateEventGroup (struct _eventGroup *eg)
 Destructor of EventGroup.
 
bool addNewEventToEventGroup (struct _event *e, struct _eventGroup *eg)
 Add new event to an eventgroup.
 
bool removeEventFromEventGroup (char *eventName, struct _eventGroup *eg)
 Remove event from eventgroup. CRITICAL: Also, deallocate the event.
 
int64_t getEventGroupId (struct _eventGroup *eg)
 
char * getEventGroupName (struct _eventGroup *eg, char *gname)
 
struct _eventgetEventGroupRootEvent (struct _eventGroup *eg)
 
struct _eventnewEvent (const char *_eventName, const char *_eventReferenceDate, const char *_eventFirstDate, const char *_eventLastDate, const char *_eventInterval, const char *_eventOffset)
 Construct new event using strings.
 
struct _eventnewEventWithDataType (const char *_eventName, struct _datetime *_eventReferenceDate, struct _datetime *_eventFirstDate, struct _datetime *_eventLastDate, struct _timedelta *_eventInterval, struct _timedelta *_eventOffset)
 Construct new event using data-types.
 
void deallocateEvent (struct _event *e)
 Destructor of Event.
 
struct _eventconstructAndCopyEvent (struct _event *e)
 
bool isCurrentEventActive (struct _event *e, struct _datetime *current_dt, struct _timedelta *plus_slack, struct _timedelta *minus_slack)
 Check if this event is active by comparing event's trigger time with current_dt.
 
bool iseventNextInNextDay (struct _event *e)
 
bool iseventNextInNextMonth (struct _event *e)
 
bool iseventNextInNextYear (struct _event *e)
 
char * eventToString (struct _event *e, char *string)
 Get Event as a string.
 
struct _datetimegetTriggerNextEventAtDateTime (struct _event *e, struct _datetime *dt_current, struct _datetime *dt_return)
 Get the Datetime when 'this' event will be triggered next.
 
struct _datetimegetTriggeredPreviousEventAtDateTime (struct _event *e, struct _datetime *dt_return)
 Get the Datetime when 'this' event was triggered last.
 
struct _eventgetNextEventInGroup (struct _event *e)
 
int64_t getEventId (struct _event *e)
 
char * getEventName (struct _event *e, char *ename)
 
struct _datetimegetEventReferenceDateTime (struct _event *e)
 
struct _datetimegetEventFirstDateTime (struct _event *e)
 
struct _datetimegetEventLastDateTime (struct _event *e)
 
struct _timedeltagetEventInterval (struct _event *e)
 
bool getNextEventIsFirst (struct _event *e)
 
bool getEventisFirstInDay (struct _event *e)
 
bool getEventisFirstInMonth (struct _event *e)
 
bool getEventisFirstInYear (struct _event *e)
 
bool getEventisLastInDay (struct _event *e)
 
bool getEventisLastInMonth (struct _event *e)
 
bool getEventisLastInYear (struct _event *e)
 
struct _juliandaynewJulianDay (int64_t _day, int64_t _ms)
 Construct new Julian-Date object.
 
void deallocateJulianDay (struct _julianday *jd)
 Destructor of Julian-Date.
 
struct _juliandelta * newJulianDelta (char _sign, int64_t _day, int64_t _ms)
 
void deallocateJulianDelta (struct _juliandelta *jd)
 
struct _juliandayaddJulianDeltaToJulianDay (struct _julianday *jd1, struct _juliandelta *jd2, struct _julianday *jd)
 
struct _juliandaysubtractJulianDeltaFromJulianDay (struct _julianday *jd1, struct _juliandelta *jd2, struct _julianday *jd)
 
char * juliandayToString (struct _julianday *jd, char *toStr)
 Get Julian as a string.
 
struct _timenewTime (const char *time_string)
 Construct new Time using an ISO 8601 conforming string.
 
struct _timenewRawTime (int _hour, int _minute, int _second, int _ms)
 Construct new Time using 'raw' numerical values.
 
struct _timeconstructAndCopyTime (struct _time *t)
 Copy the values and construct a new Time.
 
void deallocateTime (struct _time *t)
 Destructor of Time.
 
struct _timereplaceTime (struct _time *, struct _time *)
 COPY a time object.
 
char * timeToString (struct _time *, char *)
 Get time as an extended string.
 
char * timeToBasicString (struct _time *, char *)
 Get time as a basic string.
 
char * timeToPosixString (struct _time *t, char *toStr, char *fmtString)
 Get Time in 'struct tm' format and return as a string.
 
struct _timedeltanewTimeDelta (const char *timedelta_string)
 Construct new TimeDelta using an ISO 8601 conforming string.
 
struct _timedeltanewRawTimeDelta (char _sign, int64_t _year, int _month, int _day, int _hour, int _minute, int _second, int _ms)
 Construct new TimeDelta using 'raw' numerical values.
 
struct _timedeltaconstructAndCopyTimeDelta (struct _timedelta *td)
 Copy the values and construct a new TimeDelta.
 
void deallocateTimeDelta (struct _timedelta *td)
 Destructor of TimeDelta.
 
compare_return_val compareTimeDelta (struct _timedelta *td1, struct _timedelta *td2)
 Compare two timedelta and return (td1 > td2) OR (td1 = td2) OR (td1 < td2).
 
struct _timedeltareplaceTimeDelta (struct _timedelta *tdsrc, struct _timedelta *tddest)
 COPY a TimeDelta object.
 
struct _juliandelta * timeDeltaToJulianDelta (struct _timedelta *td, struct _datetime *dt, struct _juliandelta *jd)
 
struct _timedeltajulianDeltaToTimeDelta (struct _juliandelta *jd, struct _datetime *dt, struct _timedelta *td_return)
 
struct _divisionquotienttimespandivideTimeDeltaInSeconds (struct _timedelta *dividend, struct _timedelta *divisor, struct _divisionquotienttimespan *quo_ret)
 
struct _divisionquotienttimespandivideTwoDatetimeDiffsInSeconds (struct _datetime *dt1_dividend, struct _datetime *dt2_dividend, struct _datetime *dt1_divisor, struct _datetime *dt2_divisor, int64_t *denominator_ret, struct _divisionquotienttimespan *quo_ret)
 division of two differences in datetimes.
 
struct _divisionquotienttimespandivideDatetimeDifferenceInSeconds (struct _datetime *dt1, struct _datetime *dt2, struct _timedelta *divisor, struct _divisionquotienttimespan *quo_ret)
 division by an interval given in of seconds.
 
struct _timedeltagetTimeDeltaFromDate (struct _date *, struct _date *, struct _timedelta *)
 Get the TimeDelta between two Dates d1 and d2 as (d1-d2).
 
struct _timedeltagetTimeDeltaFromDateTime (struct _datetime *dt1, struct _datetime *dt2, struct _timedelta *td_return)
 Get the TimeDelta between two DateTimes dt1 and dt2 as (dt1-dt2).
 
int64_t getTotalMilliSecondsTimeDelta (struct _timedelta *td, struct _datetime *dt)
 Get total number of milliseconds in timedelta.
 
int64_t getTotalSecondsTimeDelta (struct _timedelta *td, struct _datetime *dt)
 Get total number of seconds in timedelta.
 
char * timedeltaToString (struct _timedelta *td, char *toString)
 Get TimeDelta as an extended string.
 
struct _dateaddTimeDeltaToDate (struct _date *dt, struct _timedelta *td, struct _date *dt_return)
 Add timedelta to Date.
 
struct _datetimeaddTimeDeltaToDateTime (struct _datetime *dt, struct _timedelta *td, struct _datetime *dt_return)
 Add timedelta to DateTime.
 
struct _timedeltamoduloTimeDeltaFromDateTime (struct _datetime *start_dt, struct _timedelta *timestep, struct _datetime *current_dt, struct _timedelta *modulo_td)
 Get the timedelta between current_dt and start_dt plus next integral-multiple-of-timestep (timedelta).
 
struct _timedeltaelementwiseScalarMultiplyTimeDelta (struct _timedelta *base_td, int64_t lambda, struct _timedelta *scaled_td)
 Return the element-wise product of a scalar and a timedelta.
 
struct _timedeltaelementwiseAddTimeDeltatoTimeDelta (struct _timedelta *td1, struct _timedelta *td2, struct _timedelta *td_return)
 Return the element-wise sum of two timedeltas.
 
int64_t moduloTimedelta (struct _timedelta *a, struct _timedelta *p, int64_t *quot)
 Returns the remainder of timedelta a modulo timedelta p.
 
char * getPTStringFromMS (int64_t _ms, char *PTstr)
 Return a PT String corresponding to arbitrary number of milliseconds.
 
char * getPTStringFromSeconds (int64_t _s, char *PTstr)
 Return a PT String corresponding to arbitrary number of seconds.
 
char * getPTStringFromSecondsFloat (float _s, char *PTstr)
 Return a PT String corresponding to arbitrary number of seconds.
 
char * getPTStringFromSecondsDouble (double _s, char *PTstr)
 Return a PT String corresponding to arbitrary number of seconds.
 
char * getPTStringFromMinutes (int64_t _m, char *PTstr)
 Return a PT String corresponding to arbitrary number of minutes.
 
char * getPTStringFromHours (int64_t _h, char *PTstr)
 Return a PT String corresponding to arbitrary number of Hours.
 
void splitRepetitionString (const char *recurringTimeInterval, char *repetitor, char *start, char *end, char *duration)
 Split ISO 8601:2004 repeated time interval strings into base components.
 
int getRepetitions (const char *repetitionString)
 Extract number of repetitions from repetition string part.
 

Variables

const int NO_OF_SEC_IN_A_DAY
 
const int NO_OF_SEC_IN_A_HOUR
 
const int NO_OF_SEC_IN_A_MINUTE
 
const int NO_OF_MS_IN_A_DAY
 
const int NO_OF_MS_IN_HALF_DAY
 
const int NO_OF_MS_IN_A_HOUR
 
const int NO_OF_MS_IN_A_MINUTE
 
const int NO_OF_MS_IN_A_SECOND
 
const char initDummyTDString []
 
const char initDummyDString []
 
const char initDummyDTString []
 
const int nofDaysAfterARGMonthsInLeapYear [13]
 
const int nofDaysAfterARGMonthsInNonLeapYear [13]
 
const int nofDaysInARGMonthInLeapYear []
 
const int nofDaysInARGMonthIn365DayYear []
 
const int nofDaysInARGMonthIn360DayYear []
 
const int monthSpecificDeltaInMonthsLeapyear [12][13]
 
const int monthSpecificDeltaInMonths365 [12][13]
 
const int monthSpecificDeltaInMonths360 [12][13]
 
struct _julianday *(* date2julian )(struct _datetime *date, struct _julianday *julian)
 Function pointer connecting the Calendar to Julian routine. The pointed-to Function depends on the selected Calendar type.
 
struct _datetime *(* julian2date )(struct _julianday *julian, struct _datetime *date)
 Function pointer connecting Julian to Calendar routine. The pointed to Function depends on the selected Calendar type.
 

Detailed Description

This module documents the C language bindings


Data Structure Documentation

◆ _date

struct _date

struct _date containing usual date parameters.

Data Fields
int day day of date.
int month Month of date.
int64_t year Year of date. Can be both positive and negative.

◆ _datetime

struct _datetime

struct _datetime contains a struct _date and a struct _time element.

Collaboration diagram for _datetime:
Data Fields
struct _date date Date elements.
struct _time time Time elements.

◆ _eventGroup

struct _eventGroup

struct _eventGroup defines an Event-group. Each event group has an associated list of events. Event group is a place holder to 'group' events based on some user defined charteristics.

Collaboration diagram for _eventGroup:
Data Fields
int64_t eventGroupId Event Group's ID.
char * eventGroupName Event Group's name.
struct _event * rootEvent Pointer to a List of events in this group.

◆ _event

struct _event

struct _event defines events. Events are set to be triggered at pre-specified intervals.

Collaboration diagram for _event:
Data Fields
struct _datetime * eventFirstDateTime Start datetime of the event. Can be NULL; Initialized to 0-01-01T00:00:00.000.
int64_t eventId Auto generated. (For future use. Not in use yet).
struct _timedelta * eventInterval TimeDelta between succesive triggers. MUST be specified.
bool eventisFirstInDay Is the event being triggered (i.e event when triggerCurrentEvent is true) First-In-Day?
bool eventisFirstInMonth Is the event being triggered (i.e event when triggerCurrentEvent is true) First-In-Month?
bool eventisFirstInYear Is the event being triggered (i.e event when triggerCurrentEvent is true) First-In-Year?
bool eventisLastInDay Is the event being triggered (i.e event when triggerCurrentEvent is true) Last-In-Day?
bool eventisLastInMonth Is the event being triggered (i.e event when triggerCurrentEvent is true) Last-In-Month?
bool eventisLastInYear Is the event being triggered (i.e event when triggerCurrentEvent is true) Last-In-Year?
struct _datetime * eventLastDateTime Last datetime of the event. Can be NULL; stays a NULL pointer: Logically NULL.
char * eventName Event's name.
struct _timedelta * eventOffset Shift eventReferenceDateTime by 'eventOffset' . Can be NULL; stays a NULL pointer: Logically 0.
struct _datetime * eventReferenceDateTime Anchor datetime. Can be NULL; Initialized to eventFirstDateTime. .
struct _datetime * eventsLastEvaluationDateTime Last evaluation datetime to allow for multiple queries.
bool lastEventWasFinal Was the previously triggered event final?
bool neverTriggerEvent for cases an event is set by an interval of 0
struct _event * nextEventInGroup Pointer to the next event in a given Event Group.
bool nextEventIsFirst Is the next scheduled event the first to be triggered?
bool triggerCurrentEvent is this event active?
struct _datetime * triggeredPreviousEventDateTime Last Trigger event happened at this DT. Initialized with "0-01-01T00:00:00.000".
struct _datetime * triggerNextEventDateTime Trigger the event next at this DT.

◆ _julianday

struct _julianday

Struct _julianday containing julian day parameters.

Data Fields
int64_t day the actual Julian day.
int64_t ms the milisecond on that particular day.

◆ _time

struct _time

struct _time containing usual time parameters.

Data Fields
int hour hour part of time.
int minute minute part of time.
int ms milli-second part of time. 0<=ms<=999.
int second second part of time.

◆ _timedelta

struct _timedelta

Struct _timedelta containing timedelta and sign of year parameter.

Data Fields
int day Day part of timedelta.
int flag_std_form Is timedelta formatted in standard form (eg. PT30M10S) or long form (eg. PT3000S)?
int hour Hour part of timedelta.
int minute Minute part of timedelta.
int month Month part of timedelta.
int ms Milli-Second part of timedelta.
int second Second part of timedelta.
char sign sign of time delta. Sign can be '+' or '-'.
int64_t year Year part of timedelta.

◆ _divisionquotienttimespan

struct _divisionquotienttimespan

Struct _divisionquotienttimespan is used for storing division of two time-delta results.

Data Fields
int64_t quotient Quotient of two timedeltas.
int64_t remainder_in_ms Remainder in milli seconds of two timedeltas division.

Enumeration Type Documentation

◆ calendarType

enum calendarType lists the calendarTypes supported. The values are used for selecting calendars.

Enumerator
CALENDAR_NOT_SET 

calendar is not defined yet.

PROLEPTIC_GREGORIAN 

proleptic Gregorian calendar.

YEAR_OF_365_DAYS 

365 day year without leap years.

YEAR_OF_360_DAYS 

360 day year with 30 day months.

Function Documentation

◆ addNewEventToEventGroup()

bool addNewEventToEventGroup ( struct _event * e,
struct _eventGroup * eg )

Add new event to an eventgroup.

Parameters
eA pointer to struct _event. The event to be added.
egA pointer to struct _eventGroup. The eventGroup where the event is added.
Returns
bool true/false indicating success or failure of addition.

◆ addTimeDeltaToDate()

struct _date * addTimeDeltaToDate ( struct _date * d,
struct _timedelta * td,
struct _date * d_return )

Add timedelta to Date.

Routine addTimeDeltaToDate adds a timedelta to a Date and returns the new Date. Both Date and TimeDetla are first converted to corresponding values on the Julian axis. Addition is performed on the julian axis and the resulting Julian Date is converted back to the corrsponding Date.

The library assumes the following definition: Let A denote an anchor date and P a timedelta. For a positive P, A + P = B where date B > A. Consequently, for a negative P, A + P = B where A > B. Also, when P is positive, a delta of 1 month has as many days as in the month of anchor DateTime; a delta of 2 months corresponds to the number of days in the anchor date month and the next month and so on. When P is negative, a delta of 1 month corresponds to as many days as in the month before the anchor date month; a delta of 2 month corresponds to as many days as in the month before the anchor date month and the month before that and so on.

Parameters
dA pointer to struct _date. The base date.
tdA pointer to struct _timedelta. The time delta to be added to d.
d_returnA pointer to struct _date. The result of addition is copied here.
Returns
d_return A pointer to the struct _date contianing the result of addition.

◆ addTimeDeltaToDateTime()

struct _datetime * addTimeDeltaToDateTime ( struct _datetime * dt,
struct _timedelta * td,
struct _datetime * dt_return )

Add timedelta to DateTime.

Routine addTimeDeltaToDateTime adds a timedelta to a DateTime and returns the new DateTime. Both DateTime and TimeDetla are first converted to corresponding values on the Julian axis. Addition is performed on the julian axis and the resulting Julian Date is converted back to the corrsponding DateTime.

The library assumes the following definition: Let A denote an anchor date and P a timedelta. For a positive P, A + P = B where date B > A. Consequently, for a negative P, A + P = B where A > B. Also, when P is positive, a delta of 1 month has as many days as in the month of anchor DateTime; a delta of 2 months corresponds to the number of days in the anchor date month and the next month and so on. When P is negative, a delta of 1 month corresponds to as many days as in the month before the anchor date month; a delta of 2 month corresponds to as many days as in the month before the anchor date month and the month before that and so on.

Parameters
dtA pointer to struct _datetime. The base datetime.
tdA pointer to struct _timedelta. The time delta to be added to dt.
dt_returnA pointer to struct _datetime. The result of addition is copied here.
Returns
dt_return A pointer to the struct _datetime contianing the result of addition.

◆ calendarToString()

char * calendarToString ( char * calendar)

convert the calendar identifier into a human readable string.

Gets a string describing the calendar in use.

Parameters
calendarA pointer to char. A string where the currently set calendar type will be written.

◆ compareDatetime()

compare_return_val compareDatetime ( struct _datetime * dt1,
struct _datetime * dt2 )

Compare two datetimes and return (dt1 > dt2) OR (dt1 = dt2) OR (dt1 < dt2).

Parameters
dt1A pointer to struct _datetime.
dt2A pointer to struct _datetime.
Returns
boolean if (dt1 > dt2), return greater_than. If (dt1 == dt2), return equal_to. If (dt1 < dt2), return less_than. Return compare_error indicating error.

◆ compareTimeDelta()

compare_return_val compareTimeDelta ( struct _timedelta * td1,
struct _timedelta * td2 )

Compare two timedelta and return (td1 > td2) OR (td1 = td2) OR (td1 < td2).

Parameters
td1A pointer to struct _timedelta.
td2A pointer to struct _timedelta.
Returns
boolean if (td1 > td2), return greater_than. If (td1 == td2), return equal_to. If (td1 < td2), return less_than. Return compare_error indicating error.

◆ constructAndCopyDate()

struct _date * constructAndCopyDate ( struct _date * d)

Copy the values and construct a new date.

Parameters
dA pointer to struct _date. Values of d are used to initialize the new date object being created.
Returns
_d A pointer to an initialized Date object.

◆ constructAndCopyDateTime()

struct _datetime * constructAndCopyDateTime ( struct _datetime * dt)

Copy the values and construct a new datetime.

Parameters
dtA pointer to struct _datetime. Values of dt are used to initialize the new datetime being created.
Returns
_dt A pointer to an initialized DateTime.

◆ constructAndCopyTime()

struct _time * constructAndCopyTime ( struct _time * t)

Copy the values and construct a new Time.

Parameters
tA pointer to struct _time. Values of t are used to initialize the new time being created.
Returns
_t A pointer to an initialized Time object.

◆ constructAndCopyTimeDelta()

struct _timedelta * constructAndCopyTimeDelta ( struct _timedelta * td)

Copy the values and construct a new TimeDelta.

Parameters
tdA pointer to struct _timedelta. Values of td are used to initialize the new timedelta being created.
Returns
_td A pointer to an initialized TimeDelta object.

◆ datetimeToBasicString()

char * datetimeToBasicString ( struct _datetime * dt,
char * toStr )

Get DateTime as a basic string.

datetimeToBasicString returns a string in IS08601 compliant format.

Parameters
dtA pointer to struct _datetime. The datetime to be converted to string.
toStrA pointer to char. String where datetime is to be written.
Returns
toStr A pointer to the string containing datetime.

◆ datetimeToPosixString()

char * datetimeToPosixString ( struct _datetime * dt,
char * toStr,
char * fmtString )

Get DateTime in 'struct tm' format and return as a string.

Only dates between and including 1582-10-15 TO 9999-12-31 supported.

Parameters
dtA pointer to struct _datetime. The datetime to be converted to string.
toStrA pointer to char. String where datetime is to be written.
fmtStringA pointer to char. Desired Format string. CRITICAL: Inappropriate fmt string will cause dump.
Returns
toStr A pointer to the string containing datetime.

◆ datetimeToString()

char * datetimeToString ( struct _datetime * dt,
char * toStr )

Get DateTime as a string.

datetimeToString returns a string in IS08601 compliant (and extended) format.

Parameters
dtA pointer to struct _datetime. The datetime to be converted to string.
toStrA pointer to char. String where datetime is to be written.
Returns
toStr A pointer to the string containing datetime.

◆ dateToBasicString()

char * dateToBasicString ( struct _date * d,
char * toStr )

Get Date as a basic string.

DateToBasicString returns a string in IS08601 compliant format.

Parameters
dA pointer to struct _date. The date to be converted to string.
toStrA pointer to char. String where date is to be written.
Returns
toStr A pointer to the string containing date.

◆ dateToPosixString()

char * dateToPosixString ( struct _date * d,
char * toStr,
char * fmtString )

Get Date in 'struct tm' format and return as a string.

Only dates between and including 1582-10-15 TO 9999-12-31 supported.

Parameters
dA pointer to struct _date. The date to be converted to string.
toStrA pointer to char. String where date is to be written.
fmtStringA pointer to char. Desired Format string. CRITICAL: Inappropriate fmt string will cause dump.
Returns
toStr A pointer to the string containing date.

◆ dateToString()

char * dateToString ( struct _date * d,
char * toStr )

Get Date as an extended string.

DateToString returns a string in IS08601 compliant (and extended) format.

Parameters
dA pointer to struct _date. The date to be converted to string.
toStrA pointer to char. String where date is to be written.
Returns
toStr A pointer to the string containing date.

◆ deallocateDate()

void deallocateDate ( struct _date * d)

Destructor of Date. Free the Date object.

Parameters
dA pointer to struct _date. d is deallocated.

◆ deallocateDateTime()

void deallocateDateTime ( struct _datetime * dt)

Destructor of DateTime.

Parameters
dtA pointer to struct _datetime. dt is deallocated.

◆ deallocateEvent()

void deallocateEvent ( struct _event * e)

Destructor of Event.

Parameters
eA pointer to struct _event. e is deallocated.

◆ deallocateEventGroup()

void deallocateEventGroup ( struct _eventGroup * eg)

Destructor of EventGroup.

Parameters
egA pointer to struct _eventGroup. eg is deallocated.

◆ deallocateJulianDay()

void deallocateJulianDay ( struct _julianday * jd)

Destructor of Julian-Date.

Parameters
jdA pointer to struct _julianday. jd is deallocated.

◆ deallocateTime()

void deallocateTime ( struct _time * t)

Destructor of Time.

Parameters
tA pointer to struct _time. t is deallocated.

◆ deallocateTimeDelta()

void deallocateTimeDelta ( struct _timedelta * td)

Destructor of TimeDelta.

Parameters
tdA pointer to struct _timedelta. td is deallocated.

◆ divideDatetimeDifferenceInSeconds()

struct _divisionquotienttimespan * divideDatetimeDifferenceInSeconds ( struct _datetime * dt1,
struct _datetime * dt2,
struct _timedelta * divisor,
struct _divisionquotienttimespan * quo_ret )

division by an interval given in of seconds.

Parameters
refdtReference date (a pointer to struct _datetime).
dtA pointer to struct _datetime.
intvlsecInterval given in seconds.
Returns
result of division. NULL indicates error.

◆ divideTwoDatetimeDiffsInSeconds()

struct _divisionquotienttimespan * divideTwoDatetimeDiffsInSeconds ( struct _datetime * dt1_dividend,
struct _datetime * dt2_dividend,
struct _datetime * dt1_divisor,
struct _datetime * dt2_divisor,
int64_t * denominator_ret,
struct _divisionquotienttimespan * quo_ret )

division of two differences in datetimes.

Parameters
dt1_dividend,dt2_dividend,dt1_divisor,dt2_divisorReference date (a pointer to struct _datetime).
intvlsecInterval given in seconds.
Returns
result of division. NULL indicates error.

◆ elementwiseAddTimeDeltatoTimeDelta()

struct _timedelta * elementwiseAddTimeDeltatoTimeDelta ( struct _timedelta * td1,
struct _timedelta * td2,
struct _timedelta * td_return )

Return the element-wise sum of two timedeltas.

elementwiseAddTimeDeltatoTimeDelta adds two timedeltas elementwise and returns the result. Timedeltas being added must be of the same sign; Subtraction is not supported. The timedelta can not have days,months or years however: Only Timedeltas upto hours should call this routine. Also td_return->hour >= 24 will lead to an error.

Parameters
td1A pointer to struct _timedelta.
td2A pointer to struct _timedelta.
td_returnA pointer to struct _timedelta. The element-wise sum of td1 and td2 is stored here.
Returns
td_return A pointer to struct _timedelta. The filled structure containing the added timedelta values.

◆ elementwiseScalarMultiplyTimeDelta()

struct _timedelta * elementwiseScalarMultiplyTimeDelta ( struct _timedelta * base_td,
int64_t lambda,
struct _timedelta * scaled_td )

Return the element-wise product of a scalar and a timedelta.

elementwiseScalarMultiplyTimeDelta multiplies scalar lambda with each element of timedelta and returns the result in scaled_td. Scalar can be both positive and negative and so can the timedelta. The timedelta can not have days,months or years however: Only Timedeltas upto hours should call this routine. Also scaled_td->hour >= 24 will lead to an error.

Parameters
base_tdA pointer to struct _timedelta. The base timedelta.
lambdaA scalar to be multiplied.
scaled_tdA pointer to struct _timedelta. The element-wise product of lambda and base_td is stored here.
Returns
scaled_td A pointer to struct _timedelta. The filled structure containing the scaled timedelta values.

◆ eventToString()

char * eventToString ( struct _event * e,
char * string )

Get Event as a string.

Parameters
eA pointer to struct _event. The event to be converted to string.
stringA pointer to char. String where event is to be written.
Returns
string A pointer to the string containing event description.

◆ freeCalendar()

void freeCalendar ( void )

called to discard the selected calendar type.

RESETs the calendar. Should be performed ONLY at exit! WARNING: Freeing the calendar and re-assigning a new calendar type not supported.

◆ getCalendarType()

calendarType getCalendarType ( void )

To query the current calendar type.

Gets the calendarType.

Returns
_calendar_type A member of enum calendarType. Denotes the currently set calendar type.

◆ getDateTimeFromJulianDay()

struct _datetime * getDateTimeFromJulianDay ( struct _julianday * jd,
struct _datetime * dt )

Get the DateTime from Julian Day.

The routine getDateTimeFromJulianDay returns the equivalent DateTime to Julian date. Internally it calls translation routines based on Calendar type.

Parameters
jdA pointer to struct _julianday. The JD's value is converted to julian day value.
dtA pointer to struct _datetime. The DT where the converted value is stored.
Returns
jd A pointer to struct _datetime containing a copy of the DT value corresponding to the JD.

◆ getDayOfYearFromDateTime()

int getDayOfYearFromDateTime ( struct _datetime * dt)

Get the 'day-of-year' value of a DateTime.

Routine getDayOfYearFromDateTime returns Day of Year for the DateTime. This routine supports all Calendar types.

For eg. the day of year value for 2001-10-15T00:00:00.000 will be 288 for Gregorian Calendar. Similarly, this value will be 285 for Calendar of type 360 day-Calendar.

Parameters
dtA pointer to struct _datetime. Retrieve the 'day-of-year' from this DT object.
Returns
doy Integer value of doy. The value depends on the calendar type. Zero indicates error.

◆ getJulianDayFromDateTime()

struct _julianday * getJulianDayFromDateTime ( struct _datetime * dt,
struct _julianday * jd )

Get the Julian Day from DateTime.

The routine getJulianDayFromDateTime returns the equivalent Julian date to DateTime. Internally it calls translation routines based on Calendar type.

Parameters
dtA pointer to struct _datetime. The DT's value is converted to julian day value.
jdA pointer to struct _julianday. JD where the converted value is stored.
Returns
jd A pointer to struct _julianday containing a copy of the JD value corresponding to the DT.

◆ getNoOfDaysInMonthDateTime()

int getNoOfDaysInMonthDateTime ( struct _datetime * dt)

Get nod (number of Days) in the month of DateTime.

Routine getNoOfDaysInMonthDateTime returns number of days in the month of DateTime. This routine supports all calendar types.

For eg. the number of days for 2001-10-15T00:00:00.000 will be 31 for Gregorian Calendar. Similarly, this value will be 30 for Calendar of type 360 day-Calendar.

Parameters
dtA pointer to struct _datetime.
Returns
nod Integer value of nod. The value depends on the month and the calendar type. Zero indicates error.

◆ getNoOfDaysInYearDateTime()

int getNoOfDaysInYearDateTime ( struct _datetime * dt)

Get number of days in the Year of DateTime.

Routine getNoOfDaysInYearDateTime returns number of days in the Year of DateTime. This routine supports all calendar types.

Number of days returned will depend on the calendar type and if applicable, leap v/s non leap year.

Parameters
dtA pointer to struct _datetime.
Returns
nod Integer value of nod. The value depends on the year and the calendar type. Zero indicates error.

◆ getNoOfSecondsElapsedInDayDateTime()

int getNoOfSecondsElapsedInDayDateTime ( struct _datetime * dt)

Get number of seconds elapsed in the day of DateTime.

Parameters
dtA pointer to struct _datetime.
Returns
no_of_seconds int value of no_of_seconds. -1 indicates error.

◆ getNoOfSecondsElapsedInMonthDateTime()

int64_t getNoOfSecondsElapsedInMonthDateTime ( struct _datetime * dt)

Get number of seconds elapsed in the month of DateTime.

Parameters
dtA pointer to struct _datetime.
Returns
no_of_seconds int64_t value of no_of_seconds. -1 indicates error.

◆ getPTStringFromHours()

char * getPTStringFromHours ( int64_t _h,
char * PTstr )

Return a PT String corresponding to arbitrary number of Hours.

getPTStringFromHours() translates hour values to ISO 8601 compliant timedelta string. Conversion of h >= 24 and ms <= -24 not supported.

Parameters
_hAn int64_t value to be translated.
PTstrA pointer to char. Translated string is written here.
Returns
PTstr A pointer to char. The translated TimeDelta string.

◆ getPTStringFromMinutes()

char * getPTStringFromMinutes ( int64_t _m,
char * PTstr )

Return a PT String corresponding to arbitrary number of minutes.

getPTStringFromMinutes() translates minutes values to ISO 8601 compliant timedelta string. Conversion of m >= 1440 and m <= -1440 not supported.

Parameters
_mAn int64_t value to be translated.
PTstrA pointer to char. Translated string is written here.
Returns
PTstr A pointer to char. The translated TimeDelta string.

◆ getPTStringFromMS()

char * getPTStringFromMS ( int64_t _ms,
char * PTstr )

Return a PT String corresponding to arbitrary number of milliseconds.

getPTStringFromMS() translates ms values to ISO 8601 compliant timedelta string. Conversion of ms >= 86400000 and ms <= -86400000 not supported.

Parameters
_msAn int64_t value to be translated.
PTstrA pointer to char. Translated string is written here.
Returns
PTstr A pointer to char. The translated TimeDelta string.

◆ getPTStringFromSeconds()

char * getPTStringFromSeconds ( int64_t _s,
char * PTstr )

Return a PT String corresponding to arbitrary number of seconds.

getPTStringFromSeconds() translates second values to ISO 8601 compliant timedelta string. Conversion of s >= 86400 and s <= -86400 not supported.

Parameters
_sAn int64_t value to be translated.
PTstrA pointer to char. Translated string is written here.
Returns
PTstr A pointer to char. The translated TimeDelta string.

◆ getPTStringFromSecondsDouble()

char * getPTStringFromSecondsDouble ( double _s,
char * PTstr )

Return a PT String corresponding to arbitrary number of seconds.

getPTStringFromSecondsDouble() translates second values to ISO 8601 compliant timedelta string. Conversion of s >= 86400 and s <= -86400 not supported. Returned PT string has a precision of 3 digits.

Parameters
_sDouble value to be translated.
PTstrA pointer to char. Translated string is written here.
Returns
PTstr A pointer to char. The translated TimeDelta string.

◆ getPTStringFromSecondsFloat()

char * getPTStringFromSecondsFloat ( float _s,
char * PTstr )

Return a PT String corresponding to arbitrary number of seconds.

getPTStringFromSecondsFloat() translates second values to ISO 8601 compliant timedelta string. Conversion of s >= 86400 and s <= -86400 not supported. Returned PT string has a precision of 3 digits.

Parameters
_sFloat value to be translated.
PTstrA pointer to char. Translated string is written here.
Returns
PTstr A pointer to char. The translated TimeDelta string.

◆ getRepetitions()

int getRepetitions ( const char * repetitionString)

Extract number of repetitions from repetition string part.

Parameters
[in]repetitionStringA pointer to char. A repetition string starting with 'R'. A string literal can be accepted.
Returns
r An int representing the number of repetitions.

◆ getTimeDeltaFromDate()

struct _timedelta * getTimeDeltaFromDate ( struct _date * d1,
struct _date * d2,
struct _timedelta * td_return )

Get the TimeDelta between two Dates d1 and d2 as (d1-d2).

Routine getTimeDeltaFromDate 'subtracts' two Dates and returns the TimeDelta between them. Internally, Dates are converted to DateTimes and then delta is calculated using getTimeDeltaFromDateTime().

This routine handles all supported Calendar types; i.e. the translation from Calendar date to Julian date and conversion from Julian Delta to normal TimeDetla is Calendar-type dependent. For eg. for Calendar type Gregorian, the TimeDelta between 2001-02-01 and 2001-01-01 will be 1 month. Similarly, for Calendar of type 360-Day-Calendar, the TimeDelta will be 1 month. It must be noted however, that the two dates differ by 31 and 30 days respectively.

Parameters
d1A pointer to struct _date.
d2A pointer to struct _date.
td_returnA pointer to struct _timedelta. Copy the result of (d1 - d2) in td_return.
Returns
td_return A pointer to TimeDelta containing the result of subtraction.

◆ getTimeDeltaFromDateTime()

struct _timedelta * getTimeDeltaFromDateTime ( struct _datetime * dt1,
struct _datetime * dt2,
struct _timedelta * td_return )

Get the TimeDelta between two DateTimes dt1 and dt2 as (dt1-dt2).

Routine getTimeDeltaFromDateTime 'subtracts' two DateTime's and returns the TimeDelta between them. Each datetime is converted to an equivalent Julian Date. Subtraction is then performed on Julian axis. The "Julian delta" is finally converted back to normal calendar delta.

This routine handles all supported Calendar types; i.e. the translation from Calendar date to Julian date and conversion from Julian Delta to normal TimeDetla is Calendar-type dependent. For eg. for Calendar type Gregorian, the TimeDelta between 2001-02-01T00:00:00.000 and 2001-01-01T00:00:00.000 will be 1 month. Similarly, for Calendar of type 360-Day-Calendar, the TimeDelta will be 1 month. It must be noted however, that the two dates differ by 31 and 30 days respectively.

Parameters
dt1A pointer to struct _datetime.
dt2A pointer to struct _datetime.
td_returnA pointer to struct _timedelta. Copy the result of (dt1 - dt2) in td_return.
Returns
td_return A pointer to TimeDelta containing the result of subtraction.

◆ getTotalMilliSecondsTimeDelta()

int64_t getTotalMilliSecondsTimeDelta ( struct _timedelta * td,
struct _datetime * base_dt )

Get total number of milliseconds in timedelta.

Routine getTotalMilliSecondsTimeDelta returns the total number of milliseconds in TimeDelta. Notice that TimeDelta is not uniquely defined but depends on the definition of corresponding DateTime. TimeDelta is first converted to corresponding delta on the Julian axis. Julian delta is finally converted to the correct millisecond value.

Parameters
tdA pointer to struct _timedelta. Retrieve the number of milliseconds in this TD object.
base_dtA pointer to struct _datetime. Reference Datetime for the TD.
Returns
totalmilliSeconds Integer value of totalmilliSeconds. 0 indicates error. TODO on Luis: Is this ok?

◆ getTotalSecondsTimeDelta()

int64_t getTotalSecondsTimeDelta ( struct _timedelta * td,
struct _datetime * base_dt )

Get total number of seconds in timedelta.

Routine getTotalSecondsTimeDelta returns the total number of seconds in TimeDelta. Notice that TimeDelta is not uniquely defined but depends on the definition of corresponding DateTime. Internally, number of seconds is calculated by calling the routine getTotalMilliSecondsTimeDelta() and then converting the millisecond value to seconds by dividing it by 1000.

Parameters
tdA pointer to struct _timedelta. Retrieve the number of seconds in this TD object.
base_dtA pointer to struct _datetime. Reference Datetime for the TD.
Returns
totalSeconds Integer value of totalSeconds. 0 indicates error.

◆ getTriggeredPreviousEventAtDateTime()

struct _datetime * getTriggeredPreviousEventAtDateTime ( struct _event * e,
struct _datetime * dt_return )

Get the Datetime when 'this' event was triggered last.

Parameters
eA pointer to struct _event. This is the event being queried.
dt_returnA pointer to struct _datetime. The last trigger datetime is copied here.
Returns
dt_return A pointer to DT with previous-trigger datetime.

◆ getTriggerNextEventAtDateTime()

struct _datetime * getTriggerNextEventAtDateTime ( struct _event * e,
struct _datetime * current_dt,
struct _datetime * dt_return )

Get the Datetime when 'this' event will be triggered next.

WARNING: The value returned is with-respect-to current_dt and not a true copy of triggerNextEventDateTime in the event data structure.

Parameters
eA pointer to struct _event. This is the event being queried.
dt_returnA pointer to struct _datetime. The next trigger datetime is copied here.
Returns
dt_return A pointer to DateTime with next-trigger datetime.

◆ initCalendar()

void initCalendar ( calendarType ct)

To initialize a new calendar.

Calendar init is done at the very begining to use this calendar lib. Init intializes the calendar to:

  • PROLEPTIC_GREGORIAN
  • YEAR_OF_365_DAYS
  • OR YEAR_OF_360_DAYS Calendar.

The calendar type and hence it's behaviour (Calendar to Julian conversion and vice versa) is fixed for the lifetime of the calendar object. Attempts to change the calendar type at runtime is discouraged. The lib has built-in checks to reject change attempts. Calendar can be "re-initialized" after calling freeCalendar() but is not advised. MANTRA: Know what you are doing before you do it and do it right the first time.

Parameters
ctAn object of struct calendarType. ct 'fixes' the calendar type by setting function pointers to point to functions designed to work with that calendarType.

◆ isCurrentEventActive()

bool isCurrentEventActive ( struct _event * event,
struct _datetime * current_dt,
struct _timedelta * plus_slack,
struct _timedelta * minus_slack )

Check if this event is active by comparing event's trigger time with current_dt.

   The current_dt must lie in event's trigger time
   (subject to optional specified slack: [Trigger_time - minus_slack, Trigger_time + plus_slack]. Slacks can be NULL. Always

inclusive.) The lib has no built-in clock but relies on isCurrentEventActive(.) being called (polled) from the application at fixed intervals.

Parameters
eventA pointer to struct _event. This is the event being tested.
current_dtA pointer to struct _datetime. This is the 'current' datetime of the system.
plus_slackA pointer to struct _timedelta. Events are triggered between [actual_trigger_time, actual_trigger_time + plus_slack]. Can be NULL; logically 0. Sign MUST be '+'
minus_slackA pointer to struct _timedelta. Events are triggered between [actual_trigger_time - minus_slack, actual_trigger_time]. Can be NULL; logically 0. Sign MUST be '+'
Returns
bool true/false indicating if the event is active.

◆ juliandayToString()

char * juliandayToString ( struct _julianday * jd,
char * toStr )

Get Julian as a string.

juliandayToString returns a string in Day.MS format.

Parameters
jdA pointer to struct _julianday. The julian value to be converted to string.
toStrA pointer to char. String where julian value is to be written.
Returns
toStr A pointer to the string containing julian value.

◆ moduloTimedelta()

int64_t moduloTimedelta ( struct _timedelta * a,
struct _timedelta * p,
int64_t * quot )

Returns the remainder of timedelta a modulo timedelta p.

moduloTimedelta(struct _timedelta *a, struct _timdelta *p) returns the remainder of a modulo p. The function is restricted to input timedeltas less than 29 days.

Parameters
aa valid timedelta objact < P29D.
pa valid timedelta objact < P29D.
pon return contains the quotient
Returns
rem returns remainder of the division of the numerator a by the denominator p. quotient * p + rem shall equal a.

◆ moduloTimeDeltaFromDateTime()

struct _timedelta * moduloTimeDeltaFromDateTime ( struct _datetime * start_dt,
struct _timedelta * timestep,
struct _datetime * current_dt,
struct _timedelta * modulo_td )

Get the timedelta between current_dt and start_dt plus next integral-multiple-of-timestep (timedelta).

Routine moduloTimeDeltaFromDateTime returns the timedelta between the current DateTime (current_dt) and the event's next-trigger time. The next trigger time is defined as the the Anchor DateTime (start_dt) + N * TimeDelta(timestep) where N is the minimum positive integer for which this sum is >= Current DateTime. In case Anchor DateTime > Current DateTime, TimeDelta is calculated as start_dt - current_dt.

Notice that this TimeDelta will always be positive.

Parameters
start_dtA pointer to struct _datetime. The base datetime.
timestepA pointer to struct _timedelta. delta between two consecutive triggers.
current_dtA pointer to struct _datetime. The Current Date time.
modulo_tdA pointer to struct _timedelta. The timedelta between 'current datetime' and 'Start Datetime plus next integral-multiple-of-timestep' is copied here.
Returns
modulo_td A pointer to the struct _timedelta contianing the modulo timedelta. If Start time is in the future, returns on start_time
  • current_time.

◆ newDate()

struct _date * newDate ( const char * ds)

Construct new Date using an ISO 8601 conforming string.

    MAX allowed year = 2147483647 and MIN allowed year = -2147483648.

    Strings of the following form are valid:

    <table>
    <tr><th>Extended Format:  <th>
    <tr><td> +/-([Y]+)-MM-DD  <td> [Y]+ stands for year and can be of any char length (>= 1)
                                    but must be in range: [MIN allowed year, MAX allowed year].
                                    Sign can be +/- or emtpy with default +
    <tr><td> +/-([Y]+)-MM     <td>
    </table>

    <table>
    <tr><th>Basic Format:     <th>
    <tr><td> +/-YYYYMMDD      <td> Note that Year is 4 char long.
                                   Sign can be +/- or empty with default +
    </table>

    In essence, strings follow the guidelines in ISO8601 standard (but do not support all formats).
Parameters
dsA pointer to char. The string should contain parameters with which Date object is to be created. A string literal can be accepted.
Returns
d A pointer to an initialized date object.

◆ newDateTime()

struct _datetime * newDateTime ( const char * dts)

Construct new DateTime using an ISO 8601 conforming string.

   MAX allowed year = 2147483647 and MIN allowed year = -2147483648.

    Strings of the following form are valid:

    <table>
    <tr><th> Extended Format: <th>
    <tr><td> +/-([Y]+)-MM-DDTHH:MM:SS.SSS  <td> [Y]+ stands for year can be of any char length (>= 1)
                                                but must be in range: [MIN allowed year, MAX allowed year].
                                                Sign can be +/- or empty with default +.
                                                Also, .SSS can be of length 1-3
    <tr><td> +/-([Y]+)-MM-DDTHH:MM:SS      <td>
    <tr><td> +/-([Y]+)-MM-DDTHH:MM         <td>
    <tr><td> +/-([Y]+)-MM-DDTHH            <td>
    <tr><td> +/-([Y]+)-MM-DD               <td>
    <tr><td> +/-([Y]+)-MM                  <td>
    </table>

    <table>
    <tr><th> Basic Format: <th>
    <tr><td> +/-YYYYMMDDTHHMMSS.SSS        <td> Note that Year is 4 char long.
                                                Sign can be +/- or empty with default +.
                                                Also, .SSS can be of length 1-3
    <tr><td> +/-YYYYMMDDTHHMMSS            <td>
    <tr><td> +/-YYYYMMDDTHHMM              <td>
    <tr><td> +/-YYYYMMDDTHH                <td>
    <tr><td> +/-YYYYMMDD                   <td>
    </table>

    In essence, strings follow the guidelines in ISO8601 standard (but do not support all formats).
Parameters
dtsA pointer to char. The string should contain parameters with which DateTime is created. A string literal can be accepted.
Returns
dt A pointer to a filled datetime.

◆ newEvent()

struct _event * newEvent ( const char * _en,
const char * _eventReferenceDT,
const char * _eventFirstDT,
const char * _eventLastDT,
const char * _eventInterval,
const char * _eventOffset )

Construct new event using strings.

To initialize an event, the event name and event interval must be specified. The reference date (also known as the anchor-date), start date and event last date are optional. If first date is not specified, first date is initialized as 0-01-01T00:00:00.000. If reference date is not specified, first date is copied to reference date. If event last date is not defined, it is left as NULL and is logically equivalent to Infinity.

Notice that events trigger every _eventReferenceDT + Integral multiple of _eventInterval strictly in [_eventFirstDT,_eventLastDT].

Parameters
_enA pointer to char. This string contains the name of event. String name must be defined.
_eventReferenceDTA pointer to char. This string contains the Anchor date. Events are triggered at Anchor date + (N * eventInterval) where N is in Z. This can be NULL in which case Anchor Date = First Date.
_eventFirstDTA pointer to char. This string contains the Starting datetime (A) of the DateTime range [A-B] in which trigger is allowed. Can be NULL.
_eventLastDTA pointer to char. This string contains the Ending datetime (B) of the DateTime range [A-B] in which trigger is allowed. Can be NULL. If defined, events will not trigger beyond this point. Else, equivalent to infinity.
_eventOffsetA pointer to char. Adds a logical shift to _eventReferenceDT and the sifted value is used as the anchor date. Can be NULL; Logically equivalent to 0 shift.
_eventIntervalA pointer to char. This string contains the timestep. This must be defined for every event.
Returns
e A pointer to an initialized event.

◆ newEventGroup()

struct _eventGroup * newEventGroup ( const char * egn)

Construct new event-Group using a string.

Parameters
egnA pointer to char. This string contains the name of event group.
Returns
eg A pointer to a initialized event-Group.

◆ newEventWithDataType()

struct _event * newEventWithDataType ( const char * _en,
struct _datetime * _eventReferenceDT,
struct _datetime * _eventFirstDT,
struct _datetime * _eventLastDT,
struct _timedelta * _eventInterval,
struct _timedelta * _eventOffset )

Construct new event using data-types.

To initialize an event, the event name and event interval must be specified. The reference date (also known as the anchor-date), start date and event last date are optional. If first date is not specified, first date is initialized as 0-01-01T00:00:00.000. If reference date is not specified, first date is copied to reference date. If event last date is not defined, it is left as NULL and is logically equivalent to Infinity.

Notice that events trigger every _eventReferenceDT + Integral multiple of _eventInterval strictly in [_eventFirstDT,_eventLastDT].

Parameters
_enA pointer to char. This string contains the name of event.
_eventReferenceDTA pointer to struct _datetime. This pointer contains the First Reference date also called anchor date. This can be NULL, but if defined acts as the true starting datetime overriding e->eventFirstDateTime.
_eventFirstDTA pointer to struct _datetime. This pointer contains the Starting datetime. This must be defined for every Event.
_eventLastDTA pointer to struct _datetime. This pointer contains the Ending datetime. This can be NULL. If defined, events will not trigger beyond this point.
_eventIntervalA pointer to struct _timedelta. This pointer contains the timestep. This must be defined for every event.
Returns
e A pointer to an initialized event.

◆ newJulianDay()

struct _julianday * newJulianDay ( int64_t _day,
int64_t _ms )

Construct new Julian-Date object.

Parameters
_dayAn "int64_t" value denoting the Day part of JD.
_msAn "int64_t" value denoting the milli-second part of Date.
Returns
jd A pointer to a initialized Julian-Date object.

◆ newRawDate()

struct _date * newRawDate ( int64_t _year,
int _month,
int _day )

Construct new Date using 'raw' numerical values.

MAX allowed year = 2147483647 and MIN allowed year = -2147483648.

Parameters
_yearAn "int64_t" value denoting the year part of Date.
_monthAn "int" value denoting the month part of Date.
_dayAn "int" value denoting the day part of Date.
Returns
d A pointer to an initialized Date object.

◆ newRawDateTime()

struct _datetime * newRawDateTime ( int64_t _year,
int _month,
int _day,
int _hour,
int _minute,
int _second,
int _ms )

Construct new DateTime using 'raw' numerical values.

Parameters
_yearAn "int64_t" value denoting the year part of DateTime.
_monthAn "int" value denoting the month part of DateTime.
_dayAn "int" value denoting the day part of DateTime.
_hourAn "int" value denoting the hour part of DateTime.
_minuteAn "int" value denoting the minute part of DateTime.
_secondAn "int" value denoting the second part of DateTime.
_msAn "int" value denoting the milli-second part of DateTime.
Returns
dt A pointer to a filled DateTime.

◆ newRawTime()

struct _time * newRawTime ( int _hour,
int _minute,
int _second,
int _ms )

Construct new Time using 'raw' numerical values.

Parameters
_hourAn "int" value denoting the hour part of time.
_minuteAn "int" value denoting the minute part of time.
_secondAn "int" value denoting the second part of time.
_msAn "int" value denoting the milli-second part of time.
Returns
t A pointer to a filled Time.

◆ newRawTimeDelta()

struct _timedelta * newRawTimeDelta ( char _sign,
int64_t _year,
int _month,
int _day,
int _hour,
int _minute,
int _second,
int _ms )

Construct new TimeDelta using 'raw' numerical values.

Parameters
_signAn char value denoting positive('+') or negative('-') TimeDelta.
_yearAn "int64_t" value denoting the year part of TimeDelta.
_monthAn "int" value denoting the month part of TimeDelta.
_dayAn "int" value denoting the day part of TimeDelta.
_hourAn "int" value denoting the hour part of TimeDelta.
_minuteAn "int" value denoting the minute part of TimeDelta.
_secondAn "int" value denoting the second part of TimeDelta.
_msAn "int" value denoting the milli-second part of TimeDelta.
Returns
td A pointer to a filled TimeDelta.

◆ newTime()

struct _time * newTime ( const char * ts)

Construct new Time using an ISO 8601 conforming string.

    Strings of the following form are valid:

    <table>
    <tr><th> Extended Format: <th>
    <tr><td> HH:MM:SS.SSS <td> .SSS can be of length 1-3
    <tr><td> HH:MM:SS     <td>
    <tr><td> HH:MM        <td>
    <tr><td> HH           <td>
    </table>

    <table>
    <tr><th> Basic Format: </th>
    <tr><td> HHMMSS.SSS  <td> .SSS can be of length 1-3
    <tr><td> HHMMSS      <td>
    <tr><td> HHMM        <td>
    <tr><td> HH          <td>
    </table>

    In essence, strings follow the guidelines in ISO8601 standard (but do not support all formats).
Parameters
tsA pointer to char. The string contains parameters with which Time is created.
Returns
t A pointer to a filled Time.

◆ newTimeDelta()

struct _timedelta * newTimeDelta ( const char * tds)

Construct new TimeDelta using an ISO 8601 conforming string.

Parameters
tdsA pointer to char. The string should contain parameters with which TimeDelta is to be created.
Returns
td A pointer to a filled TimeDelta.

◆ removeEventFromEventGroup()

bool removeEventFromEventGroup ( char * en,
struct _eventGroup * eg )

Remove event from eventgroup. CRITICAL: Also, deallocate the event.

Parameters
enA pointer to char. The name of event to be removed.
egA pointer to struct _eventGroup. The eventGroup to which this event belongs.
Returns
bool true/false indicating success or failure of removal.

◆ replaceDate()

struct _date * replaceDate ( struct _date * dsrc,
struct _date * ddest )

COPY a Date object.

Routine replaceDate copies the contents of source Date into a Destination Date object.

Parameters
dsrcA pointer to struct _date. Copy "FROM" Date object.
ddestA pointer to struct _date. Copy "TO" Date object.
Returns
ddest A pointer to 'copied' Date Object.

◆ replaceDatetime()

struct _datetime * replaceDatetime ( struct _datetime * dtsrc,
struct _datetime * dtdest )

COPY a DateTime object.

Routine replaceDateTime copies the contents of source DateTime into a Destination DateTime object.

Parameters
dtsrcA pointer to struct _datetime. Copy "FROM" DateTime object.
dtdestA pointer to struct _datetime. Copy "TO" DateTime object.
Returns
dtdest A pointer to 'copied' DateTime Object.

◆ replaceTime()

struct _time * replaceTime ( struct _time * tsrc,
struct _time * tdest )

COPY a time object.

Routine replaceTime copies the contents of source Time into a Destination Time object.

Parameters
tsrcA pointer to struct _time. Copy "FROM" time object.
tdestA pointer to struct _time. Copy "TO" time object.
Returns
tdest A pointer to 'copied' time Object.

◆ replaceTimeDelta()

struct _timedelta * replaceTimeDelta ( struct _timedelta * tdsrc,
struct _timedelta * tddest )

COPY a TimeDelta object.

Routine replaceTimeDelta copies the contents of source TimeDelta into a Destination TimeDelta object.

Parameters
tdsrcA pointer to struct _timedelta. Copy "FROM" TimeDelta object.
tddestA pointer to struct _timedelta. Copy "TO" TimeDelta object.
Returns
tddest A pointer to 'copied' TimeDelta Object.

◆ splitRepetitionString()

void splitRepetitionString ( const char * recurringTimeInterval,
char * repetitor,
char * start,
char * end,
char * duration )

Split ISO 8601:2004 repeated time interval strings into base components.

Parameters
[in]recurringTimeIntervalA pointer to char. The string should contain an ISO 8601:2004 repeated time interval string. A string literal can be accepted.
[out]repetitorA string. Contains the repetitor part of the input string.
[out]startA string. Contains the start date part of the input string.
[out]endA string. Contains the end date part of the input string.
[out]durationA string. Contains the duration part of the input string.
Returns
n/a

◆ timedeltaToString()

char * timedeltaToString ( struct _timedelta * td,
char * toStr )

Get TimeDelta as an extended string.

timedeltaToString returns a string in IS08601 compliant (and extended) format.

Parameters
tdA pointer to struct _timedelta. The timedelta to be converted to string.
toStrA pointer to char. String where timedelta is to be written.
Returns
toStr A pointer to the string containing timedelta.

◆ timeToBasicString()

char * timeToBasicString ( struct _time * t,
char * toStr )

Get time as a basic string.

timetoString returns a string in IS08601 compliant format.

Parameters
tA pointer to struct _time. The time to be converted to string.
toStrA pointer to char. String where time is to be written.
Returns
toStr A pointer to the string containing time.

◆ timeToPosixString()

char * timeToPosixString ( struct _time * t,
char * toStr,
char * fmtString )

Get Time in 'struct tm' format and return as a string.

Parameters
tA pointer to struct _time. The time to be converted to string.
toStrA pointer to char. String where time is to be written.
fmtStringA pointer to char. Desired Format string. CRITICAL: Inappropriate fmt string will cause dump.
Returns
toStr A pointer to the string containing time.

◆ timeToString()

char * timeToString ( struct _time * t,
char * toStr )

Get time as an extended string.

timetoString returns a string in IS08601 compliant (and extended) format.

Parameters
tA pointer to struct _time. The time to be converted to string.
toStrA pointer to char. String where time is to be written.
Returns
toStr A pointer to the string containing time.