firstworks Programming with Rudiments using the datetime class

Using the datetime class

- Introduction
- Output Formats
- Date/Time Sources
- Date Math
- Timezones

### Introduction

The datetime class represents a date/time combination and provides methods for getting and setting dates and times, converting date/time formats and accessing various date/time values.

Dealing with dates and times is classically one of the most difficult things to do on a computer. The "standard" functions and structures associated with dates and times are complex, vary widely from platform to platform and in many cases are not thread safe. The datetime class attempts to rectify this situation.

### Output Formats

The datetime class provides basic methods for getting the system date and time, and returning it in various formats.

> #include <rudiments/datetime.h>
> #include <rudiments/stdio.h>
> int main(int argc, const char **argv) {
> // initialize an instance of datetime to the current system date/time
> datetime dt;
> dt.getSystemDateAndTime();
> // the components of the date/time are avaialble in various formats...
> // as a string
> stdoutput.printf("date/time: %s\n\n",dt.getString());
> // including microseconds
> stdoutput.printf("date/time: %s\n\n",dt.getString(true));
> // as the number of seconds since 1970
> stdoutput.printf("seconds since 1970: %d\n\n",dt.getEpoch());
> // broken down
> stdoutput.write("date/time: ");
> stdoutput.printf("%02d/%02d/%04d %02d:%02d:%02d.%06d %s (%d)\n\n",
> dt.getMonth(),dt.getDayOfMonth(),dt.getYear(),
> dt.getHour(),dt.getMinutes(),dt.getSeconds(),
> dt.getMicroseconds(),
> dt.getTimeZoneString(),dt.getTimeZoneOffset());
> // additional date information
> stdoutput.write("date: ");
> stdoutput.printf("%s (%s) %d, %04d "
> "(day %d of year) (day %d of week)\n\n",
> dt.getMonthName(),dt.getMonthAbbreviation(),
> dt.getDayOfMonth(),dt.getYear(),dt.getDayOfYear(),
> dt.getDayOfWeek());
> }

### Date/Time Sources

An instance of the datetime class can be initialized from many different sources: the system clock, a formatted string, or from the number of seconds (and optionally microseconds) since 1970.

> #include <rudiments/datetime.h>
> #include <rudiments/stdio.h>
> int main(int argc, const char **argv) {
> datetime dt;
> // initialize from system date/time
> dt.getSystemDateAndTime();
> stdoutput.printf("system date/time: %s\n\n",dt.getString(true));
> // initialize from a formatted string
> dt.initialize("01/02/2000 03:04:05 EDT");
> stdoutput.printf("formatted string: %s\n\n",dt.getString(true));
> // initialize from the number of seconds since 1970
> dt.initialize(40000000);
> stdoutput.printf("seconds since 1970: %s\n\n",dt.getString(true));
> // initialize from the number of seconds and microseconds since 1970
> dt.initialize(40000000,100);
> stdoutput.printf("sec/usec since 1970: %s\n\n",dt.getString(true));
> }

### Date Math

The datetime class also provides methods for doing date math.

> #include <rudiments/datetime.h>
> #include <rudiments/stdio.h>
> int main(int argc, const char **argv) {
> datetime dt;
> // initialize from system date/time
> dt.getSystemDateAndTime();
> stdoutput.printf("current date/time: %s\n\n",dt.getString(true));
> // add three years, months, days,
> // hours, minutes, seconds, and microseconds
> dt.addYears(3);
> dt.addMonths(3);
> dt.addDays(3);
> dt.addHours(3);
> dt.addMinutes(3);
> dt.addSeconds(3);
> dt.addMicroseconds(3);
> stdoutput.printf("new date/time: %s\n\n",dt.getString(true));
> // subtract three years, months, days,
> // hours, minutes, seconds, and microseconds
> dt.addYears(-3);
> dt.addMonths(-3);
> dt.addDays(-3);
> dt.addHours(-3);
> dt.addMinutes(-3);
> dt.addSeconds(-3);
> dt.addMicroseconds(-3);
> stdoutput.printf("original date/time: %s\n\n",dt.getString(true));
> }

### Timezones

The datetime class also provides methods for getting information about timezones and converting date/times between timezones.

> #include <rudiments/datetime.h>
> #include <rudiments/stdio.h>
> int main(int argc, const char **argv) {
> datetime dt;
> // initialize from system date/time
> dt.getSystemDateAndTime();
> stdoutput.printf("local time: %s\n\n",dt.getString());
> // get time zone abbreviations and offsets
> const char * const *tzabbr=datetime::getTimeZoneAbbreviations();
> const int32_t *tzoff=datetime::getTimeZoneOffsets();
> // show the current time in different timezones around the world...
> while (*tzabbr && *tzabbr[0]) {
> // convert timezone
> dt.adjustTimeZone(*tzabbr);
> stdoutput.printf("% 14s (% 6d sec from GMT): %s\n",
> *tzabbr,*tzoff,dt.getString());
> tzabbr++;
> tzoff++;
> }
> }