Rudiments: datetime Class Reference

Rudiments

Public Member Functions | Static Public Member Functions | List of all members
datetime Class Reference

## Public Member Functions
| datetime ()
| ~datetime ()
bool | initialize (const char *tmstring)
bool | initialize (time_t seconds)
bool | initialize (time_t seconds, time_t microseconds)
bool | initialize (const void *tmstruct)
bool | getSystemDateAndTime ()
bool | getHardwareDateAndTime (const char *hwtz)
bool | getAdjustedHardwareDateAndTime (const char *hwtz)
bool | setSystemDateAndTime ()
bool | setHardwareDateAndTime (const char *hwtz)
int32_t | getHour () const
int32_t | getMinutes () const
int32_t | getSeconds () const
int32_t | getMicroseconds () const
int32_t | getMonth () const
const char * | getMonthName () const
const char * | getMonthAbbreviation () const
int32_t | getDayOfMonth () const
int32_t | getDayOfWeek () const
int32_t | getDayOfYear () const
int32_t | getWeekOfYear () const
int32_t | getYear () const
int32_t | getShortYear () const
int32_t | getCentury () const
bool | isDaylightSavingsTime () const
const char * | getTimeZoneString () const
int32_t | getTimeZoneOffset () const
bool | adjustTimeZone (const char *newtz)
bool | adjustTimeZone (const char *newtz, bool ignoredst)
bool | setSeconds (int32_t seconds)
bool | setMicroseconds (int32_t microseconds)
bool | setMinutes (int32_t minutes)
bool | setHours (int32_t hours)
bool | setDays (int32_t days)
bool | setMonths (int32_t months)
bool | setYears (int32_t years)
bool | addSeconds (int32_t seconds)
bool | addMicroseconds (int32_t microseconds)
bool | addMinutes (int32_t minutes)
bool | addHours (int32_t hours)
bool | addDays (int32_t days)
bool | addMonths (int32_t months)
bool | addYears (int32_t years)
const char * | getString ()
const char * | getString (bool microseconds)
const char * | getSqlString ()
const char * | getSqlString (bool microseconds)
time_t | getEpoch () const

## Static Public Member Functions
static const char *const * | getTimeZoneAbbreviations ()
static const int32_t * | getTimeZoneOffsets ()
static bool | validDateTime (const char *string)
static char * | getString (time_t seconds)
static char * | getString (time_t seconds, time_t microseconds)
static char * | getString (const void *tmstruct)
static time_t | getEpoch (const char *datestring)
static time_t | getEpoch (const void *tmstruct)
static bool | parse (const char *datetime, bool ddmm, bool yyyyddmm, const char *datedelimiters, int16_t *year, int16_t *month, int16_t *day, int16_t *hour, int16_t *minute, int16_t *second, int32_t *microsecond, bool *isnegative)
static char * | formatAs (const char *format, int16_t year, int16_t month, int16_t day, int16_t hour, int16_t minute, int16_t second, int32_t microsecond, bool isnegative)
static void | setTimeMutex (threadmutex *mtx)

## Detailed Description

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.

## Constructor & Destructor Documentation

## ◆ datetime()

datetime::datetime | ( |  | ) |

Creates an instance of the datetime class.

## ◆ ~datetime()

datetime::~datetime | ( |  | ) |

Destroys this instance of the datetime class.

## Member Function Documentation

## ◆ addDays()

bool datetime::addDays | ( | int32_t | days | ) |

Adds "days" to the date/time represented in the instance of the class.

## ◆ addHours()

bool datetime::addHours | ( | int32_t | hours | ) |

Adds "hours" to the date/time represented in the instance of the class.

## ◆ addMicroseconds()

bool datetime::addMicroseconds | ( | int32_t | microseconds | ) |

Adds "microseconds" to the date/time represented in the instance of the class.

## ◆ addMinutes()

bool datetime::addMinutes | ( | int32_t | minutes | ) |

Adds "minutes" to the date/time represented in the instance of the class.

## ◆ addMonths()

bool datetime::addMonths | ( | int32_t | months | ) |

Adds "months" to the date/time represented in the instance of the class.

## ◆ addSeconds()

bool datetime::addSeconds | ( | int32_t | seconds | ) |

Adds "seconds" to the date/time represented in the instance of the class.

## ◆ addYears()

bool datetime::addYears | ( | int32_t | years | ) |

Adds "years" to the date/time represented in the instance of the class.

## ◆ adjustTimeZone() [1/2]

bool datetime::adjustTimeZone | ( | const char * | newtz | ) |

Recalculates the time currently represented in the class to correspond to the time zone "newtz".

If, in the new timezone, daylight savings time is currently in effect, the time zone will be adjusted accordingly. Ie. if "newtz" = EST and daylight savings time is in effect in EST5EDT, then EDT will be used instead.

Returns true on success and false on failure.

## ◆ adjustTimeZone() [2/2]

bool datetime::adjustTimeZone | ( | const char * | newtz,
|  | bool | ignoredst
| ) |  |

Recalculates the time currently represented in the class to correspond to the time zone "newtz".

If ignoredst is false, this method works like adjustTimezone(const char *newtz). However if ignoredst is true, this method will not adjust EST to EDT if daylight savings time is in effect in EST5EDT.

Returns true on success and false on failure.

## ◆ formatAs()

static char* datetime::formatAs | ( | const char * | format,
|  | int16_t | year,
|  | int16_t | month,
|  | int16_t | day,
|  | int16_t | hour,
|  | int16_t | minute,
|  | int16_t | second,
|  | int32_t | microsecond,
|  | bool | isnegative
| ) |  |
| static

FIXME: document...

## ◆ getAdjustedHardwareDateAndTime()

bool datetime::getAdjustedHardwareDateAndTime | ( | const char * | hwtz | ) |

This method only works if your system has a working real-time clock at /dev/rtc.

Gets the date and time from the hardware clock, then adjusts it to the timezone used by the system.

Returns true on success and false on failure.

## ◆ getCentury()

int32_t datetime::getCentury | ( |  | ) | const

Returns the (one-based) century component of the date/time currently represented in the instance of the class.

## ◆ getDayOfMonth()

int32_t datetime::getDayOfMonth | ( |  | ) | const

Returns the day of the month component (1-31) of the date/time currently represented in the instance of the class.

## ◆ getDayOfWeek()

int32_t datetime::getDayOfWeek | ( |  | ) | const

Returns the day of the week component (1-7) of the date/time currently represented in the instance of the class.

## ◆ getDayOfYear()

int32_t datetime::getDayOfYear | ( |  | ) | const

Returns the day of the year component (1-365) of the date/time currently represented in the instance of the class.

## ◆ getEpoch() [1/3]

time_t datetime::getEpoch | ( |  | ) | const

Returns the number of seconds since 1970 (the epoch).

## ◆ getEpoch() [2/3]

static time_t datetime::getEpoch | ( | const char * | datestring | ) |
| static

Parses "datestring" which must be of the format: "mm/dd/yyyy hh:mm:ss TZN" and returns the number of seconds since 1970 (the epoch).

Note that TZN must be a valid timezone. Otherwise GMT is assumed.

## ◆ getEpoch() [3/3]

static time_t datetime::getEpoch | ( | const void * | tmstruct | ) |
| static

Takes "tmstruct", a pointer to a platform-specific time structure (struct tm * on unix) and returns the number of seconds since 1970 (the eopch).

Note that in "tmstruct", the timezone and GMT offset must be set to valid values. Otherwise GMT is assumed.

## ◆ getHardwareDateAndTime()

bool datetime::getHardwareDateAndTime | ( | const char * | hwtz | ) |

This method only works if your system has a working real-time clock at /dev/rtc.

Sets the date and time represented in the class to the date and time stored in the hardware clock.

"hwtz" must be set to the timezone that the hardware clock is using.

Returns true on success and false on failure.

## ◆ getHour()

int32_t datetime::getHour | ( |  | ) | const

Returns the hour component of the date/time currently represented in the instance of the class.

## ◆ getMicroseconds()

int32_t datetime::getMicroseconds | ( |  | ) | const

Returns the microseconds component of the date/time currently represented in the instance of the class.

## ◆ getMinutes()

int32_t datetime::getMinutes | ( |  | ) | const

Returns the minute component of the date/time currently represented in the instance of the class.

## ◆ getMonth()

int32_t datetime::getMonth | ( |  | ) | const

Returns the month component (1-12) of the date/time currently represented in the instance of the class.

## ◆ getMonthAbbreviation()

const char* datetime::getMonthAbbreviation | ( |  | ) | const

Returns the abbreviated name of the month component of the date/time currently represented in the instance of the class.

## ◆ getMonthName()

const char* datetime::getMonthName | ( |  | ) | const

Returns the full name of the month component of the date/time currently represented in the instance of the class.

## ◆ getSeconds()

int32_t datetime::getSeconds | ( |  | ) | const

Returns the seconds component of the date/time currently represented in the instance of the class.

## ◆ getShortYear()

int32_t datetime::getShortYear | ( |  | ) | const

Returns the year component, not including the century, of the date/time currently represented in the instance of the class.

## ◆ getSqlString() [1/2]

const char* datetime::getSqlString | ( |  | ) |

Returns a string of the format: "yyyy-mm-dd hh:mm:ss" for the date/time represented in the instance of the class.

(Note that this method returns a pointer to an internal string which will be deleted if the class instance is deleted.)

## ◆ getSqlString() [2/2]

const char* datetime::getSqlString | ( | bool | microseconds | ) |

Returns a string representing the date/time in the instance of the class.

If microseconds is false then the string is of the format: "yyyy-mm-dd hh:mm:ss"

If microseconds is true then the string is of the format: "yyyy-mm-dd hh:mm:ss.mmm"

(Note that this method returns a pointer to an internal string which will be deleted if the class instance is deleted.)

## ◆ getString() [1/5]

const char* datetime::getString | ( |  | ) |

Returns a string of the format: "mm/dd/yyyy hh:mm:ss TZN" for the date/time represented in the instance of the class.

(Note that this method returns a pointer to an internal string which will be deleted if the class instance is deleted.)

## ◆ getString() [2/5]

const char* datetime::getString | ( | bool | microseconds | ) |

Returns a string representing the date/time in the instance of the class.

If microseconds is false then the string is of the format: "mm/dd/yyyy hh:mm:ss TZN"

If microseconds is true then the string is of the format: "mm/dd/yyyy hh:mm:ss:uuu TZN"

(Note that this method returns a pointer to an internal string which will be deleted if the class instance is deleted.)

## ◆ getString() [3/5]

static char* datetime::getString | ( | const void * | tmstruct | ) |
| static

Takes "tmstruct", a pointer to a platform-specific time structure (struct tm * on unix) and returns a string in "mm/dd/yyyy hh:mm:ss TZN" format.

Note that this method allocates a buffer to return the string in which must be deleted by the calling program.

## ◆ getString() [4/5]

static char* datetime::getString | ( | time_t | seconds | ) |
| static

Takes "seconds" since the epoch (the number of seconds since 1970) and returns a string in "mm/dd/yyyy hh:mm:ss TZN" format.

Note that this method allocates a buffer to return the string in which must be deleted by the calling program.

## ◆ getString() [5/5]

static char* datetime::getString | ( | time_t | seconds,
|  | time_t | microseconds
| ) |  |
| static

Takes "seconds" since the epoch (the number of seconds since 1970) and "microseconds" and returns a string in "mm/dd/yyyy hh:mm:ss:uuu TZN" format.

Note that this method allocates a buffer to return the string in which must be deleted by the calling program.

## ◆ getSystemDateAndTime()

bool datetime::getSystemDateAndTime | ( |  | ) |

Sets the date and time represented in the class to the date and time stored in the system clock.

Returns true on success and false on failure.

## ◆ getTimeZoneAbbreviations()

static const char* const* datetime::getTimeZoneAbbreviations | ( |  | ) |
| static

Returns a NULL terminated array of timezone abbreviations.

## ◆ getTimeZoneOffset()

int32_t datetime::getTimeZoneOffset | ( |  | ) | const

Returns the offset from GMT in seconds

## ◆ getTimeZoneOffsets()

static const int32_t* datetime::getTimeZoneOffsets | ( |  | ) |
| static

Returns an array of timezone offsets from GMT (in seconds). Each element of this array corresponds to an element of the array returned b getTimeZoneAbbreviations().

## ◆ getTimeZoneString()

const char* datetime::getTimeZoneString | ( |  | ) | const

Returns a 3 character string representing the time zone

## ◆ getWeekOfYear()

int32_t datetime::getWeekOfYear | ( |  | ) | const

Returns the week of the year component (1-52) of the date/time currently represented in the instance of the class.

## ◆ getYear()

int32_t datetime::getYear | ( |  | ) | const

Returns the year component, including the century, of the date/time currently represented in the instance of the class.

## ◆ initialize() [1/4]

bool datetime::initialize | ( | const char * | tmstring | ) |

Parses "tmstring" and sets the date and time represented in the class to that time. "tmstring" must be of the format: "mm/dd/yyyy hh:mm:ss TZN".

Note that TZN must be a valid timezone. Otherwise GMT is assumed.

Returns true on success and false on failure.

## ◆ initialize() [2/4]

bool datetime::initialize | ( | const void * | tmstruct | ) |

Processes "tmstruct" and sets the date and time represented in the class to that time.

"tmstruct" should be a pointer to a platform-specific time structure (struct tm * on unix)

Note that in "tmstruct", the timezone and GMT offset must be set to valid values. Otherwise GMT is assumed.

Returns true on success and false on failure.

## ◆ initialize() [3/4]

bool datetime::initialize | ( | time_t | seconds | ) |

Processes "seconds" and sets the date and time represented in the class to that time. "seconds" is the number of seconds since 1970 (the epoch).

Returns true on success and false on failure.

## ◆ initialize() [4/4]

bool datetime::initialize | ( | time_t | seconds,
|  | time_t | microseconds
| ) |  |

Processes "seconds" and "microseconds" and sets the date and time represented in the class to that time. "seconds" is the number of seconds since 1970 (the epoch).

Returns true on success and false on failure.

## ◆ isDaylightSavingsTime()

bool datetime::isDaylightSavingsTime | ( |  | ) | const

Returns true if daylight savings time is currently in effect and false if it isn't

## ◆ parse()

static bool datetime::parse | ( | const char * | datetime,
|  | bool | ddmm,
|  | bool | yyyyddmm,
|  | const char * | datedelimiters,
|  | int16_t * | year,
|  | int16_t * | month,
|  | int16_t * | day,
|  | int16_t * | hour,
|  | int16_t * | minute,
|  | int16_t * | second,
|  | int32_t * | microsecond,
|  | bool * | isnegative
| ) |  |
| static

FIXME: document...

## ◆ setDays()

bool datetime::setDays | ( | int32_t | days | ) |

Sets the day-of-the-month component (1-31) of the date/time represented in the instance of the class to "days".

## ◆ setHardwareDateAndTime()

bool datetime::setHardwareDateAndTime | ( | const char * | hwtz | ) |

This method only works if your system has a working real-time clock at /dev/rtc.

Sets the hardware clock's date and time to the date and time currently represented in the class.

"hwtz" must be set to the timezone that the system clock using.

Returns true on success and false on failure.

## ◆ setHours()

bool datetime::setHours | ( | int32_t | hours | ) |

Sets the hours component of the date/time represented in the instance of the class to "hours".

## ◆ setMicroseconds()

bool datetime::setMicroseconds | ( | int32_t | microseconds | ) |

Sets the microseconds component of the date/time represented in the instance of the class to "microseconds".

## ◆ setMinutes()

bool datetime::setMinutes | ( | int32_t | minutes | ) |

Sets the minutes component of the date/time represented in the instance of the class to "minutes".

## ◆ setMonths()

bool datetime::setMonths | ( | int32_t | months | ) |

Sets the month component (1-12) of the date/time represented in the instance of the class to "months".

## ◆ setSeconds()

bool datetime::setSeconds | ( | int32_t | seconds | ) |

Sets the seconds component of the date/time represented in the instance of the class to "seconds".

## ◆ setSystemDateAndTime()

bool datetime::setSystemDateAndTime | ( |  | ) |

Sets the system clock's date and time to the date and time currently represented in the class.

Returns true on success and false on failure.

## ◆ setTimeMutex()

static void datetime::setTimeMutex | ( | threadmutex * | mtx | ) |
| static

Many of the functions that the datetime class uses internally are not reentrant and thus not thread-safe. Indeed, for some functions, there is no thread-safe version available on any platform.

If your application is multi-threaded, you must use this method to supply a mutex and ensure thread safety.

If you don't supply a mutex, the methods in the class will still work, but will not be thread-safe.

## ◆ setYears()

bool datetime::setYears | ( | int32_t | years | ) |

Sets the year component of the date/time represented in the instance of the class to "years".

## ◆ validDateTime()

static bool datetime::validDateTime | ( | const char * | string | ) |
| static

Returns true if string represents a valid date/time and false otherwise.

For this methods to return true, "string" must be formatted like: "00/00/0000 00:00:00" optionally followed by a space and a timezone.