C++ class cTime representing Unix time

Published under MIT License

Repository documentation under docs/cTime.chm or (after download) docs/html/index.html.

Published under MIT License

##Introduction

This code provides the class 'cTime' within the namespace 'LibCpp'. This class simplifies the usage of date and time compared to the functions defined in 'time.h' and is based on those functions, only.
Each cTime instance stores the time as unix time, which are the seconds after 1.1.1970 00:00:00 UTC. This integer value is the only member variable of the object.
Basically you have access to the value itself or to a calendar representation. The term 'calendar' within this documentation always means calendar and time information together in a human understandable form of year, hour, minute and so on. either in numerical form within a struct or as string representation.

Time representations

#include "cTime.h"
using namespace LibCpp;

int main()
{
    cTime  timeNow = cTime::now();
    time_t value = timeNow.time();          // Unix time representation
    stCalendar cal = timeNow.calendar();    // Calendar time representation
    printf("Unix time is: %d\n", (int)value);
    printf("Calendar  is: %s\n", cTime::toString(cal).c_str());

    // Unix time is: 1695223058
    // Calendar  is: 2023-09-20#17:17:38#DST#+01:00
}

The calendar is denoted in the 'Geographic Zone Calendar (GZC) string'.
The term 'DST' means 'daylight saving time', a term 'STD' stands for standard time. In both cases '+01:00' stands for the geographic time zone the calendar data is given for. It is important to distinguish between the geographic time zone and the relative deviation of the given time with respect to the Coordinated Universal Time (UTC) (same as Greenwich Mean Time (GMT)).
It is a deliberate decision not to use the ISO8601 time format for the calendar string. The reason is the lack of ability to express the DST, which is of importance for a meaningful understanding of the date and time imformation. (C++ decided the same within the 'struct tm' within 'time.h'.)
To receive the relative Deviation from UTC (or UTC time offset), which is indicated by the DST value of -1 within the stCalendar struct, you can call:

Calendar representation as UTC formatted type

In case it is desired to represent the time using the UTC relative Deviation instead of the (geographical) time zone, you can use:

cal = timeNow.calendar(cTime::asUTC);
printf("Calendar  is: %s\n", cTime::toString(cal).c_str());

// Calendar  is: 2023-09-20#17:17:38#UTC#+02:00

Calendar representations within other time zones

It is also possible to "translate" date and time to another UTC relative time. (It is not possible to translate to other geographic time zones as this would require DST-infomation to correctly indicate the time. As the definition of the time range to use DST is individual for each country such operation would require access to data bases. This would contradict the desired feature of being Independent from other libraries.)

cal = timeNow.calendar(cTime::UTC);
printf("Calendar  is: %s\n", cTime::toString(cal).c_str());
// Calendar  is: 2023-09-20#15:17:38#UTC#+00:00

int8_t utcOffset = 5;
cal = timeNow.calendar(&utcOffset);
printf("Calendar  is: %s\n", cTime::toString(cal).c_str());
// Calendar  is: 2023-09-20#20:17:38#UTC#+05:00

Mathematical calculations and durations

It is also possible to calculate with cTime instances. First, there are quite a few static cTime::set() methods to create a cTime instance from different input values. Please refer to cTimeStd.cpp for complete information. We will set christmas day and continue to calculate the time duration we will have to wait till christmas day. As it doesn't make sence to interprete a time difference as a calendar date, we can represent a cTime instance as a time duration stored in a stDuration struct containing days, hours, minutes and so on. Using years or months doesn't make sence in a scientific calculation as these values have not constant durations. Take notice of how to access the year of our current time 'timeNow'.

cTime timeChristmas = cTime::set(timeNow.calendar().year, 12, 24, 18, 0, 0);
cTime timeWait = timeChristmas - timeNow;
stDuration duration = timeWait.duration();
printf("The wait time is: %s\n", cTime::toString(duration).c_str());
// The wait time is: D95#00:42:22

The 'D' indicates a duration, the time to wait is 95 days, 42 minutes and 22 seconds.

Time Zone and string conversions

There are two more important static methods concerning the time zone and UTC relative offset calculation and some interesting methods for conversion options.

printf("local time zone is: %+03d:00\n", (int)cTime::localTimeZone());
printf("UTC deviation is  : %+03d:00\n", (int)cTime::UTCdeviation(timeNow.calendar()));
cTime  time = cTime::set("2023-09-20#17:17:38#DST#+01:00");
printf("Calendar is       : %s\n", time.toString().c_str());
printf("Weekday is        : %s\n", weekdays[time.calendar().dayInWeek]);
printf("Wait time is      : %s\n", timeWait.toDurationString().c_str());

// local time zone is: +01:00
// UTC deviation is  : +02:00
// Calendar is       : 2023-09-20#20:17:38#DST#+01:00
// Weekday is        : Wednesday
// Wait time is      : D95#00:42:22

Installation

The following four files need to be included to your project. The folder structure is a bit complicated because the cTime class is part of a larger library.

• src/LibCpp/Time/cTime.h
• src/LibCpp/Time/cTimeStd.cpp
• src/LibOb/CommonCpp/LibOb_strptime.h
• src/LibOb/CommonCpp/LibOb_strptime.c

See also to the *src/main.cpp' file providing the previously described examples and some calendrical string formats being automatically parsable.