// Copyright (c) 2000-2002 David Muse
// See the COPYING file for more information.
#ifndef RUDIMENTS_DATETIME_H
#define RUDIMENTS_DATETIME_H
#include <rudiments/private/datetimeincludes.h>
// The datetime class provides methods for converting date/time formats and
// accessing various date/time values.
class datetime {
public:
// if you need a quick conversion, use one of these methods
static char *getString(time_t seconds);
static char *getString(const struct tm *tmstruct);
// returns "mm/dd/yyyy hh:mm:ss TZN"
// Note that this method allocates a buffer to return
// the string in which must be deleted by the calling
// program.
static time_t getEpoch(const char *datestring);
// parses "mm/dd/yyyy hh:mm:ss TZN" and returns the
// number of seconds since 1970.
//
// Note that TZN must be a valid timezone. Otherwise
// GMT is assumed.
//
static time_t getEpoch(const struct tm *tmstruct);
// converts "tmstruct" to the number of seconds
// since 1970.
//
// Note that in "tmstruct", the timezone and GMT offset
// must be set to valid values. Otherwise GMT is
// assumed.
// if you need anything other than a quick conversion,
// use these methods
datetime();
~datetime();
bool initialize(const char *tmstring);
// Parses "tmstring" and sets the date and time
// represented in the class to that time.
// Datestring must be "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.
bool 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;
// output by many standard time functions.
//
// Returns true on success and false on failure.
bool initialize(const struct tm *tmstruct);
// Processes "tmstruct" and sets the date and time
// represented in the class to that time.
// "tmstruct" is a (struct tm *); output by
// many standard time functions.
//
// 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.
bool 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.
bool 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.
bool 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.
bool 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.
bool 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.
// These methods return commonly needed time/date values
int getHour() const;
int getMinutes() const;
int getSeconds() const;
int getMonth() const;
int getDayOfMonth() const;
int getDayOfWeek() const;
int getDayOfYear() const;
int getYear() const;
bool isDaylightSavingsTime() const;
// returns 1 if daylight savings time is currently
// in effect and 0 if it isn't
char *getTimeZoneString() const;
// returns a 3 character string representing the
// time zone
long getTimeZoneOffset() const;
// returns the offset from GMT (in seconds)
bool adjustTimeZone(const char *newtz);
// Recalculates the time currently represented in the
// class to correspond to the time zone "newtz".
//
// Returns true on success and false on failure.
// These methods allow you to add discrete time intervals to
// the time currently represented in the class.
void addSeconds(int seconds);
void addMinutes(int minutes);
void addHours(int hours);
void addDays(int days);
void addMonths(int months);
void addYears(int years);
// These methods output conversions to other date/time
// formats.
char *getString();
// returns "mm/dd/yyyy hh:mm:ss TZN"
// (Note that this method returns a pointer to an
// internal string which will be deleted if the
// class instance is deleted.)
time_t getEpoch() const;
// returns the number of seconds since 1970
struct tm *getTm();
// returns a pointer to the internal "struct tm"
// These methods return timezone data
static char **getTimeZoneAbbreviations();
// Returns a NULL terminated array of timezone
// abbreviations.
static long *getTimeZoneOffsets();
// Returns an array of timezone offsets from
// GMT (in seconds). Each element of this
// array corresponds to an element of the
// array returned b getTimeZoneStrings().
#ifdef RUDIMENTS_HAS_THREADS
// 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. 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 this class
// will still work, but will not be thread-safe.
static void setTimeMutex(pthread_mutex_t *mutex);
// Allows you to supply a mutex to regulate
// access to the non-reentrant functions.
#endif
#include <rudiments/private/datetime.h>
};
#endif