Time occurrence

The time occurrence I interface is for calculating time occurrences based on rules given by a recurring master. This helps calculating time stamps for events like calendar appointments, scheduled events, and similar use cases. The library doesn’t take care about time zones. It simply calculates the occurrences. So it is recommended to give the start and end time for the recurring master in UTC time and transfer the calculated value to a specified time zone using the ITimezone interface (which also takes care about daylight saving time).

An recurring master actually is a set of base information need to define a series and calculate calculate each occurrence. This information will be the start time, and end time or a maximum number of occurrences (also no end time can be given to have a never ending series), an intervall and the rule for the calculation. A rule can be one of the following options:

• Daily: This is for series that will occure each day.
• Weekly: This is for series that will occure weekly. A weekly series can occure on each day in a week. This will be defined by passing a set of days. There are also predefined sets for week days and weekend days available.
• Monthly (absolute): This is for a monthly series with an absolute date inside the month (like every 15th day of a month).
• Monthly (relative): This is for monthly series with a relative day to occure (like every second Monday of a month or every fourth weekend day).
• Yearly (absolute): This is for series that will occure once a year at the given date.
• Yearlc (relative): This is for series that will occure once a year for a relative day for a month.

Note: yearly recurring masters (absolute and relative) technically are the same as monthly occurrences with an interval of 12 month. The difference is, that the month for the occurrence can be defined for the yearly occurrence, while using a monthly occurrence with an interval of 12 will use the month of the given start date

File information

Functions

Little helpers

inline recurring_days_t IntToDays(int days);
inline recurring_month_t IntToMonth(int month)

Classes

TimeOccurrence

class TimeOccurrence {
public:
    TimeOccurrence();
    ~TimeOccurrence();

    void SetDailyMaster(long64 start, long64 end = RD_NO_END_DATE, dword interval = 1, dword maxOccurrences = RD_NO_LIMIT);
    void SetWeeklyMaster(dword days, long64 start, long64 end = RD_NO_END_DATE, dword interval = 1, dword maxOccurrences = RD_NO_LIMIT);
    void SetMonthlyMaster(dword dayNum, recurring_days_t day, long64 start, long64 end = RD_NO_END_DATE, dword interval = 1, dword maxOccurrences = RD_NO_LIMIT);
    void SetYearlyMaster(dword dayNum, recurring_days_t day, recurring_month_t month, long64 start, long64 end = RD_NO_END_DATE, dword interval = 1, dword maxOccurrences = RD_NO_LIMIT);

    void SetWeekDays(word weekDays);
    void SetWeekEndDays(word weekEndDays);

    bool Empty() { return this->resultCount == 0; }
    size_t Count() { return this->resultCount; }
    long64 Result(size_t index);
    long64 operator[] (size_t index) { return this->Result(index); }

    void Calculate(long64 timePeriodStart = 0, long64 timePeriodEnd = RD_NO_END_DATE, dword maxResults = RD_NO_LIMIT);
    void Calculate(UTimeOccurrence * user, long64 timePeriodStart = 0, long64 timePeriodEnd = RD_NO_END_DATE);
    long64 CalculateFirstOccurrence(long64 timePeriodStart = 0);
    long64 CalculateLastOccurrence(dword numOfOccurrences = 0);
};

Public functions

UTimeOccurrence

class UTimeOccurrence {
public:
    UTimeOccurrence() {}
    virtual ~UTimeOccurrence() {}
    virtual bool TimeOccurrenceResult(class TimeOccurrence * timeOccurrence, long64 timeStamp) { return false; }
};

The User can be passed to one of the TimeOccurrence::Calculat() function. For each occurrence calculated, UTimeOccurrence::TimeOccurrenceResult() will be called. The function should made what ever needed with the given timestamp and decide, whether to continue the calculation or not by returning ture or false.

Public functions

Parameters

Data types

Defines / Statics

recurring_days_t

typedef enum {
    RD_NO_DAY = 0x0000,
    RD_SUNDAY = 0x0001,
    RD_MONDAY = 0x0002,
    RD_TUESDAY = 0x0004,
    RD_WEDNESDAY = 0x0008,
    RD_THURSDAY = 0x0010,
    RD_FRIDAY = 0x0020,
    RD_SATURDAY = 0x0040,
    // The recurring types can also day, week day or weekend day (like: 3rd day of month, 2nd weekday our 1st weekend day)
    RD_DAY = 0x0080,
    RD_WEEK_DAY = 0x0100,
    RD_WEEKEND_DAY = 0x0200
} recurring_days_t;

Values

recurring_month_t

typedef enum {
    RM_JANUARY,
    RM_FEBRURARY,
    RM_MARCH,
    RM_APRIL,
    RM_MAY,
    RM_JUNE,
    RM_JULY,
    RM_AUGUST,
    RM_SEPTEMBER,
    RM_OCTOBER,
    RM_NOVEMBER,
    RM_DECEMBER,
    RM_NO_MONTH = 0xFFFF
} recurring_month_t;

Values

Code examples

constexpr long64 THREE_DAYS_MS = 259200000;
char buf[30];
TimeOccurrence timeOccurrence;

// Let' sassume the returned date will be Thuesday, the 5th of March 2019.
long64 t = ITime::TimeStampMilliseconds();
ITime::FormatTimeStampISO(buf, sizeof(buf), t);

debug->printf("Now: %s", buf); // Now: 2019-03-05T14:00:00

timeOccurrence.SetWeeklyMaster(RD_MONDAY | RD_THURSDAY, t - THREE_DAYS_MS);
timeOccurrence.Calculate(t, RD_NO_END_DATE, 3);

// The loop will produce the following output:
//
// Occurrence #1: 2019-03-07T14:00:00
// Occurrence #2: 2019-03-11T14:00:00
// Occurrence #3: 2019-03-14T14:00:00
//
for (int i = 0; i < timeOccurrence.Count(); ++i) {
    ITime::FormatTimeStampISO(buf, sizeof(buf), timeOccurrence[i]);
    debug->printf("Occurrence #%i: %s", i + 1, buf);
}