This class allows the programmer to manipulate date and time
values. Individual time fields can be requested or modified, returning
`sanitized' times (e.g., a date like march 33 or a time like 56 hours will
never be returned). Times may be specified in local time or in Universal
Time Coordinated (UTC) values. It is also possible to add or subtract
seconds or struct tm structures to or from DateTime objects. This
operation keeps the current time zone (UTC, local or another time
zone). Conversions between time zones and UTC are also supported.
The class DateTime supports various ways to initialize objects. Time may
be specified in UTC, as local time or using any other offset from UTC. When a
non-UTC and non-local time offset is required the time offsets are specified
as an int value representing the time offset in minutes, with time zones
East of Greenwich using positive time offsets and time zones West of Greenwich
using negative time offsets. Time zone offsets are truncated to multiples of
30 minutes and are always computed modulo 12 * 60, as no time zone has a shift
exceeding the (absolute) shift of 12 * 60. Daylight saving times are in effect
in many time zones. Except for the local time zone DateTime may not be
able to show the correct daylight saving time correction.
There are various ways to construct DateTime objects: time in seconds
since the beginning of the `era' (midnight Jan 1, 1970 UTC), a struct tm,
or a textual time representations may be used. These values may themselves be
corrected using display zone shifts. A display zone shift determines the
difference between the UTC time and the local time zone to be used when
displaying time or returning time fields. Sometimes a UTC zone shift may be
provided correcting a provided local time to UTC.
If a display zone shift is explicitly specified no additional daylight saving
time (DST) zone shift is added to the display time. If the actual local time
is requested (specified by the TimeType value LOCALTIME) a DST
correction is automatically applied when appropriate.
Members of the class DateTime should only be used if operator bool()
returns true. The member error() can also be used if operator
bool() returns false.
Handling time is complex. The C function time(2) returns the time in
seconds. This time is normally represented in UTC. The function gmtime(3)
when provided with time()'s output returns the broken down time in a
struct tm. Remarkably (and confusingly), when this struct tm is then
passed to the mktime(3) function the latter function does not return
the UTC-time in seconds, but a time that differs from the time in UTC by the
current local time shift. E.g., the program
#include <ctime>
#include <iostream>
using namespace std;
int main()
{
time_t utc = time(0);
struct tm *ts;
time_t local = mktime(ts = gmtime(&utc));
cout << ts->tm_hour << ' ' << utc - local << endl;
return 0;
}
displays the current UTC clock's hour setting, but reports the
difference in seconds between the local time and the UTC time (e.g., the
difference between CET and UTC is one hour, and the program displays 3600).
To obtain the time in UTC-seconds from mktime(3) the function
localtime(3) must be used to obtain the struct tm values:
#include <ctime>
#include <iostream>
using namespace std;
int main()
{
time_t utc = time(0);
struct tm *ts;
time_t local = mktime(ts = localtime(&utc));
cout << ts->tm_hour << ' ' << utc - local << endl;
return 0;
}
The above program displays the local clock's hour value, but a difference
of 0 for the recomputed time in seconds.
The class DateTime assumes that the time() function returns the UTC
time in seconds, which is the way computers should have configured their
hardware clock.
NAMESPACE
FBB
All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace FBB.
INHERITS FROM
-
ENUMS defined in DateTime
DateTime::Month
This enumeration has the following values which are ordered using the
default C++enum values:
JANUARY,
FEBRUARY,
MARCH,
APRIL,
MAY,
JUNE,
JULY,
AUGUST,
SEPTEMBER,
OCTOBER,
NOVEMBER,
DECEMBER.
DateTime::Relative
This enumeration is used with the setMonth() member (see below).
It has the following values:
THIS_WEEK,
THIS_YEAR,
LAST,
NEXT
DateTime::TimeFields
This enumeration has the following values which can be bit_or-ed
when calling the member setFields():
SECONDS
MINUTES
HOURS
MONTHDAY
MONTH
YEAR
DateTime::TimeType
This enumeration has the following values:
LOCALTIME: the time is broken down as the local time,
UTC: the time is broken down as Universal Time Coordinated.
DateTime::TriVal
This enumeration has the following values, returned by the dst()
member (see below):
UNKNOWN, returned when no information about the Daylight
Saving Time is available,
NO, returned when Daylight Saving Time is not active,
YES, returned when Daylight Saving Time is active.
DateTime::Weekday
This enumeration has the following values which are ordered using the
default C++enum values:
SUNDAY,
MONDAY,
TUESDAY,
WEDNESDAY,
THURSDAY,
FRIDAY,
SATURDAY.
STANDARD TEXTUAL TIME REPRESENTATIONS
DateTime objects may be initialized using textual
time-representations. Also, the time represented by a DateTime object may
be altered using text which can be extracted from a stream using
the extraction operator.
Time specifications may be formatted as follows:
Sun Nov 2 13:29:11 2008, as displayed by the C function
asctime();
Sun Nov 2 13:29:11 CET 2008, as displayed by the date(1) program;
Sun, Nov 2 13:29:11 2008 +0100, as displayed by the date -R
command (and the rfc2822() member, see below);
2008-11-02 13:29:11+01:00, as displayed by the date
--rfc-3339=seconds command (and the rfc3339() member, see below).
The time zone time shift specifications (+0100, +01:00) are required as they
are part of the rfc specifications but are ignored for the actual local time
construction as the DateTime object determines the time zone specification
from the computer's current time zone setting.
CONSTRUCTORS
DateTime(TimeType type = UTC):
The default constructor, initializing the object to the current date
and time. The argument specifies the way the time is displayed by the
DateTime object using either (by default) time in UTC or using local time.
DateTime(int displayZoneShift):
This constructor initializes the object to the date and time at offset
displayZoneShift (in minutes) from UTC.
DateTime(time_t time, TimeType type):
Initializes a DateTime object with information stored in the
provided time_t value. The object's time in UTC is defined as time (in
seconds). The second argument specifies the way the time is displayed by the
DateTime object using either time in UTC or using local time.
DateTime(time_t time, int displayZoneShift):
Initializes a DateTime object with information stored in the
provided time_t value. This value is interpreted as a time in UTC. The
second argument specifies the way the time is displayed by the DateTime
object, adding displayZoneShift (in minutes) to the time in UTC.
DateTime(struct tm const &tm, TimeType type = UTC):
Initializes a DateTime object with information stored in the
provided struct tm value. It is assumed that the tm parameter points
to a struct tm representing the broken down UTC time fields. The second
argument specifies the way the time is displayed by the object using either
(by default) time in UTC or using local time. The struct tm is defined as
follows:
struct tm
{
int tm_sec; // seconds 0..59, or 60: leap second
int tm_min; // minutes 0..59
int tm_hour; // hours 0..23
int tm_mday; // day of the month 1..31
int tm_mon; // month 0..11
int tm_year; // year since 1900
int tm_wday; // day of the week 0..6
int tm_yday; // day in the year 0..365
int tm_isdst; // daylight saving time
// > 0: yes, 0: no, < 0: unknown
};
Values outside of these ranges may sometimes be used (with various
set..() members, see below) to compute a point in time in the future or in the
past. E.g., by specifying 30 for the hour-setting DateTime objects
a point in time in the next day will be used.
DateTime(struct tm const &tm, int displayZoneShift):
Initializes a DateTime object with information stored in the
provided struct tm value. It is assumed that the tm parameter points
to a struct tm representing the broken down UTC time fields. The second
argument specifies the way the time is displayed by the object, adding
displayZoneShift (in minutes) to the time in UTC.
DateTime(std::string const &timeStr, TimeType type = UTC, int
utcZoneShift = 0):
Initializes a DateTime object with information stored in the provided
std::string which is interpreted as the time in the current (local) time
zone. To obtain the time in UTC the DateTime object subtracts the current
difference between the local time zone and UTC from the provided time and adds
utcZoneShift. The second argument specifies the way the time is
displayed by the DateTime object: either as time UTC or using the current
display zone offset. E.g., if the current time zone is UTC + 1 hour then the
time displayed by
is Sun Nov 2 17:29:11 2008: the object computes the UTC hour value as
13 - 1 (current zone offset) + 2 (utc Zone shift in hours) = 14. To this a
current display zone shift of 1 hour will be added, resulting in a displayed
hour value 15.
The time contained in the timeStr parameter should be formatted as
described in section STANDARD TEXTUAL TIME REPRESENTATIONS.
DateTime(std::string const &timeStr, int displayZoneShift,
int utcZoneShift = 0):
Initializes a DateTime object with information stored in the
provided std::string which is interpreted as the time in the current
(local) time zone. To obtain the time in UTC the DateTime object subtracts
the current difference between the local time zone and UTC from the provided
time and adds utcZoneShift.
The second argument specifies the way the time is displayed by the
DateTime object, adding displayZoneShift (in minutes) to the time in
UTC. E.g., if the current time zone is UTC + 1 hour then the time displayed
by
is Sun Nov 2 17:29:11 2008: the object computes the UTC hour
value as 13 - 1 (current zone offset) + 2 (utc Zone shift in hours) =
14. To this a display zone shift of 3 hours will be added, resulting
in a displayed hour value 17.
The time contained in the timeStr parameter should be formatted as
described in section STANDARD TEXTUAL TIME REPRESENTATIONS.
DateTime(DateTime const &other):
The copy constructor is available.
OVERLOADED OPERATORS
All class-less overloaded operators are defined in the FBB namespace,
except for the overloaded insertion operator, which is defined in the std
namespace.
std::ostream &std::operator<<(std::ostream &str, FBB::DateTime
const &dt):
Inserts a standard textual representation (without the trailing
newline), of the time represented in the DateTime object into the
indicated ostream. The time will be displayed according to the latest
displayZoneShift or TimeType specification (LOCALTIME or UTC).
std::istream &std::operator>>(std::istream &str, FBB::DateTime &dt):
Extracts a textual date/time representation into the DateTime
object using the current displayZoneShift and utcZoneShift values and
assuming the same zone shift values for the textual time representation.
The time to extract should be formatted as described in section
STANDARD TEXTUAL TIME REPRESENTATIONS. As documented in that section, time
zone time shift specifications (+0100, +01:00) are ignored and may be omitted.
If a time zone specification is provided it is extracted but ignored.
If the time could not be determined from a textual string representing the
time (cf. section CONSTRUCTORS) then errno() returns 0,
operator bool() returns false, and the time stored in the object
remains unchanged.
The following overloaded operators modify the time as stored in UTC
seconds within objects. Note that the time as displayed by the object will be
corrected for any display zone shift that may have been defined for those
objects.
DateTime const operator+(DateTime const &left, time_t seconds):
Returns a copy of left to which seconds have been added.
DateTime const operator+(DateTime const &left,
struct tm const &fields):
Returns a copy of left displaying left's time to which the
tm_sec, tm_min, tm_hour, tm_mday, tm_mon and tm_year fields of
fields have been added.
DateTime operator+=(time_t seconds):
Adds the number of seconds to the DateTime object.
DateTime &operator+=(struct tm const &fields):
Adds the tm_sec, tm_min, tm_hour, tm_mday, tm_mon and tm_year
fields of fieldsto the current object's display time.
DateTime const operator-(DateTime const &left, time_t seconds):
Returns a copy of left from which time seconds have been
subtracted.
DateTime const operator-(DateTime const &left,
struct tm const &fields):
Returns a copy of left displaying left's time from which the
tm_sec, tm_min, tm_hour, tm_mday, tm_mon and tm_year fields of
fields have been subtracted.
DateTime operator-=(time_t seconds):
Subtracts the number of seconds from the time stored in the
DateTime object.
DateTime &operator-=(struct tm const &fields):
Subtracts the tm_sec, tm_min, tm_hour, tm_mday, tm_mon and
tm_year fields of fields from the current object's display time.
E.g., the following
code fragment will display midnight, January 1, 1970:
time_t seconds = time(0);
tm timeStruct = *gmtime(&seconds);
DateTime tmp(timeStruct);
cout << tmp << endl;
--timeStruct.tm_mday; // days start at 1: subtract 1 less than
// the current day number to get '01'
timeStruct.tm_year -= (1970 - 1900); // era starts at 1970, tm_year
// is relative to 1900.
tmp -= timeStruct;
cout << tmp << endl;
The following overloaded operators can be used to compare the UTC time as
represented by DateTime objects. Note that these comparisons are
independent of any display zone shift that may have been defined for the
objects.
bool operator==(DateTime const &left, DateTime const &right):
Returns true if the current DateTime object represents the same
UTC time as the time represented by left, DateTime const &right.
bool operator!=(DateTime const &left, DateTime const &right):
Returns true if the current DateTime object represents a
different UTC time as the time represented by other.
bool operator<(DateTime const &left, DateTime const &right):
Returns true if the current DateTime object represents an
earlier UTC time than the UTC time represented by other.
bool operator<=(DateTime const &left, DateTime const &right):
Returns true if the current DateTime object represents an
earlier or equal UTC time than the UTC time represented by other.
bool operator>(DateTime const &left, DateTime const &right):
Returns true if the current DateTime object represents a
later UTC time than the UTC time represented by other.
bool operator>=(DateTime const &left, DateTime const &right):
Returns true if the current DateTime object represents an
equal or later UTC time than the UTC time represented by other.
Additional overloaded operators:
operator bool() const:
Returns true if the time decomposition could be performed without
error. DateTime object use localtime_r(3) or gmtime_r(3)
functions to break down the time_t values into elements. If the time
could not be broken down, the error() member returns the error number
(errno) associated with the error. When the time could not be determined
from a textual string representing the time (cf. section CONSTRUCTORS)
then errno() returns 0 and operator bool() returns false.
Except for the member error() the members of the class DateTime
will not return meaningfull values if operator bool() returns
false.
DateTime &operator=(DateTime const &other):
The overloaded asignment operator is available.
MEMBER FUNCTIONS
All members returning a time-element do so according to the latest
time-representation (i.e., UTC, LOCALTIME, or using an explicitly set
display zone shift value). All members returning numerical values use 0 as
their smallest return value, except for the ...Nr() members, which start
at 1.
int displayZoneShift() const:
Returns the object's current display zone shift value in minutes.
DayTime::TriVal dst() const:
Returns an indication of an active Daylight Saving Time (DST) state
for the (local) time represented in the DateTime object. When DST is
active, the local time is one hour later as compared to the situation where
DST is not active.
size_t error() const:
Returns the errno value after the DateTime object.
construction. It can be interpreted by, e.g., FBB::Errno.
size_t hours() const:
Returns the number of hours of the time stored in a DateTime
object (0-23).
DateTime localTime() const:
Returns a copy of the DateTime object representing its local
time. If the object does not define a local time or display zone shift the
returned object merely copies the orginal object's UTC time.
DateTime localTime(int displayZoneShift) const:
Returns a copy of the DateTime object representing its time using
the display zone shift provided by the member's argument.
size_t minutes() const:
Returns the number of minutes of the time stored in a DateTime
object (0-59).
Month month() const:
Returns the Month value of the time stored in a DateTime
object.
size_t monthDayNr() const:
Returns the number of the day in the month of the time stored in a
DateTime object (1-31).
string rfc2822() const:
Returns the date displayed according to the format specified in RFC
2822. This format is used, e.g., by the date -R command
(cf. date(1)). For example:
Mon, 17 Dec 2007 13:49:10 +0100
string rfc3339() const:
Returns the date displayed according to the format specified in RFC
3339. This format is used, e.g., by the date --rfc-3339=seconds command
(cf. date(1)). For example:
2008-11-02 13:29:11+01:00
size_t seconds() const:
Returns the number of seconds of the time stored in a DateTime
object (0-59, but 60 and 61 may occur due to possible leap seconds).
bool setDay(int days):
Reassigns the number of days of the current month set in the
DateTime object. Non positive values are allowed to compute time in an
earlier month. The object date is revalidated so that its days()
member returns a value fitting the object's month. If the assignment resulted
in a new (valid) time true is returned. Otherwise false is returned.
bool setFields(struct tm const &timeStruct, int fields):
Reassigns the time represented by the DateTime object to the time
in which the fields specified by a bit_or combination of TimeField
values will be given the values specified in timeStruct. All other fields
in timeStruct will be ignored and will be kept at their internal values.
The values will be normalized, though. E.g., if the current month day number
is 31 and month June is requested then the resulting month will be July
and the day number will be 1. The timeStruct fields are expected as values
in the time zone used by the DateTime object. If the assignment resulted
in a new (valid) time true is returned. Otherwise false is returned.
bool setHours(int hours):
Reassigns the number of hours set in the DateTime object.
Negative values are allowed to compute time in a previous day. The object date
is revalidated so that its hours() member returns a value between 0 and
23. If the assignment resulted in a new (valid) time true is
returned. Otherwise false is returned.
bool setMinutes(int minutes):
Reassigns the number of minutes set in the DateTime
object. Negative values are allowed to compute time in a previous hour. The
object date is revalidated so that its minutes() member returns a value
between 0 and 59. If the assignment resulted in a new (valid) time true
is returned. Otherwise false is returned.
bool setMonth(DateTime::Month month, DateTime::Relative where =
THIS_YEAR):
Reassigns the month set in the DateTime object. The object date is
revalidated so that its month() member returns a value between JANUARY
and DECEMBER. By default the month will be set in the current
year. DateTime::LAST may be specified to ensure that the requested month
will be before the current month (e.g., the current month: JUNE,
requesting AUGUST, LAST will decrement the object's year, but MAY,
LAST won't). Analogously, DateTime::NEXT may be specified to ensure that
the requested month will be following the current month. If another value for
where is specified an Errno exception is thrown. If the assignment
resulted in a new (valid) time true is returned. Otherwise false is
returned.
bool setMonth(int month):
Reassigns the month set in the DateTime object. Negative values
are allowed to compute time in a previous year. The object date is revalidated
so that its month() member returns a value between JANUARY and
DECEMBER. If the assignment resulted in a new (valid) time true is
returned. Otherwise false is returned.
bool setSeconds(int seconds):
Reassigns the number of seconds set in the DateTime
object. Negative values are allowed to compute time in a previous minute. The
object date is revalidated so that its seconds() member returns a value
between 0 and 59. If the assignment resulted in a new (valid) time true is
returned. Otherwise false is returned.
bool setTime(time_t time):
Reassigns the number of seconds set in the DateTime object. The
object date is revalidated. Time value 0 represents Jan, 1, 1970, 0:00:00
hours. If the assignment resulted in a new (valid) time true is
returned. Otherwise false is returned.
void setValid():
Resets the object's internal state to valid. This member can be used
following a failed action that did not modify the (valid) time stored
by the object.
bool setWeekday(Weekday day, Relative where = NEXT):
Reassigns the number of seconds set in the DateTime object based
on reassignment of the day in the week (at most 7 days from now, weeks
starting at Sunday and ending at Saturday). By default the day will be in the
future. By specifying LAST for where the day will be in the past. It
is also possible to specify where as THIS_WEEK in which case the day
will be computed in the current week. If another value for where is
specified an Errno exception is thrown. If the current weekday is
specified with where equal to either NEXT or LAST the time will be
set to either one week ahead or one week in the past. The object date is
revalidated. Time value 0 represents Jan, 1, 1970, 0:00:00 hours. If the
assignment resulted in a new (valid) time true is returned. Otherwise
false is returned.
bool setYear(size_t year):
Reassigns the year set in the DateTime object. The date is
revalidated so that its year() member returns a value of at least 1970. If
the assignment resulted in a new (valid) time true is returned. Otherwise
false is returned.
time_t time() const:
Returns the (UTC) time_t value (in seconds) stored in the
DateTime object.
struct tm const *timeStruct() const:
Returns a pointer to the objects latest struct tm values,
representing the time as displayed by, e.g., the insertion operator.
DateTime to(DateTime::TimeType type) const:
Returns a copy of the DateTime object representing its time in
UTC if DateTime::UTC was specified, and in local time if
DateTime::LOCALTIME was specified.
DateTime utc() const:
Returns a copy of the DateTime object representing its time in
UTC.
bool valid() const:
Returns true if no errors were detected during the object's
construction (same semantics as operator bool()).
Weekday weekday() const:
Returns the Weekday value of the time stored in a
DateTime object.
size_t year() const:
Returns the year element of the time stored in a DateTime
object.
size_t yearDay() const:
Returns the day within the year of the time stored in a
DateTime object. January 1 is returned as 0.
size_t yearDayNr() const:
Returns the day within the year of the time stored in a
DateTime object. January 1 is returned as 1.
Whenever a set...() member is used in such a way that the resulting
date would be invalid the original DateTime object's value is unaltered.
EXAMPLE
An extensive example illustrating the use of all of DateTime's members
is provided in the file bobcat/datetime/driver/driver.cc found in the
source archive.