Provided by: libbobcat-dev_4.08.02-2build1_amd64 
NAME
FBB::DateTime - Performs Date and Time Computations
SYNOPSIS
#include <bobcat/datetime>
Linking option: -lbobcat
DESCRIPTION
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 an explicit time offset is
requested it is specified as an int value representing the time offset in minutes, with
time zones time zones West of Greenwich using negative time offsets and East of Greenwich
using positive 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:
o JANUARY,
o FEBRUARY,
o MARCH,
o APRIL,
o MAY,
o JUNE,
o JULY,
o AUGUST,
o SEPTEMBER,
o OCTOBER,
o NOVEMBER,
o DECEMBER.
DateTime::Relative
This enumeration is used with the setMonth() member (see below). It has the following
values:
o THIS_WEEK,
o THIS_YEAR,
o LAST,
o NEXT
DateTime::TimeFields
This enumeration has the following values which can be bit_or-ed when calling the member
setFields():
o SECONDS
o MINUTES
o HOURS
o MONTHDAY
o MONTH
o YEAR
DateTime::TimeType
This enumeration has the following values:
o LOCALTIME: the time is broken down as the local time,
o 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):
o UNKNOWN, returned when no information about the Daylight Saving Time is available,
o NO, returned when Daylight Saving Time is not active,
o 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:
o SUNDAY,
o MONDAY,
o TUESDAY,
o WEDNESDAY,
o THURSDAY,
o FRIDAY,
o 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:
o Sun Nov 2 13:29:11 2008, as displayed by the C function asctime();
o Sun Nov 2 13:29:11 CET 2008, as displayed by the date(1) program;
o Sun, Nov 2 13:29:11 2008 +0100, as displayed by the date -R command (and the
rfc2822() member, see below);
o 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
o 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 the computer’s time zone shift is used to
determine the current local time.
o DateTime(int tzShift):
This constructor initializes the object to a local time which is at UTC + tzShift
(in minutes).
o DateTime(time_t time, TimeType type):
Initializes a DateTime object with information stored in the provided time_t value
(time in seconds since the beginning of the era). The specified time is considered
UTC or local time, depending on the type specification.
o DateTime(time_t time, int tzShift):
Initializes a DateTime object with information stored in the provided time_t value
(time is UTC time in seconds since the beginning of the era). The DateTime object
defines its time as local time UTC + tzShift (in minutes).
The following constructors ignore the DST, day of the year, and day of the week fields of
the struct tm passed to the constructors:
o 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 time in either UTC or local time. If local time is requested the the
computer’s time zone shift is used. 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.
o DateTime(struct tm const &tm, int timeShift):
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 time fields in UTC. To this time shift tzShift (in minutes) is added to
obtain the actually used local time.
The final constructors convert textual time specifications formatted as described in
section STANDARD TEXTUAL TIME REPRESENTATIONS (the day of the week specification is
ignored by the time conversion).
o DateTime(std::string const &timeStr, TimeType type = UTC):
Initializes a DateTime object with information stored in the provided std::string
which is interpreted as time specified in UTC or as a local time in the current
time zone, depending on the specified time type.
o DateTime(std::string const &timeStr, int tzShift):
Initializes a DateTime object with a local time computed by adding a locate
timezone shift (tzShift) in minutes to the UTC time specification found in
timeStr.
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.
o 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).
o std::istream &std::operator>>(std::istream &str, FBB::DateTime &dt):
Extracts a textual date/time representation into the DateTime object using the
tzShift value currently set for the DateTime object into which the time string is
extracted.
The istream from which the time is extracted must contain time formatted as
described in section STANDARD TEXTUAL TIME REPRESENTATIONS. As documented in that
section, time shift and time zone specifications (+0100, +01:00, CET) are ignored
and may be omitted. They are ignored when specified. The object will merely
interpret the date/time specification as a specification in the object’s currently
active time zone.
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.
o DateTime const operator+(DateTime const &left, time_t seconds):
Returns a copy of left to which seconds have been added.
o 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.
o DateTime operator+=(time_t seconds):
Adds the number of seconds to the DateTime object.
o 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.
o DateTime const operator-(DateTime const &left, time_t seconds):
Returns a copy of left from which time seconds have been subtracted.
o 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.
o DateTime operator-=(time_t seconds):
Subtracts the number of seconds from the time stored in the DateTime object.
o 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.
o 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.
o 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.
o 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.
o 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.
o 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.
o 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:
o 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
meaningful values if operator bool() returns false.
o 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.
o int displayZoneShift() const:
Returns the object’s current display zone shift value in minutes.
o 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.
o size_t error() const:
Returns the errno value after the DateTime object. construction. It can be
interpreted by, e.g., FBB::Exception.
o size_t hours() const:
Returns the number of hours of the time stored in a DateTime object (0-23).
o 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 original object’s UTC time.
o 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.
o size_t minutes() const:
Returns the number of minutes of the time stored in a DateTime object (0-59).
o Month month() const:
Returns the Month value of the time stored in a DateTime object.
o size_t monthDayNr() const:
Returns the number of the day in the month of the time stored in a DateTime object
(1-31).
o 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
o 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
o 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).
o 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.
o 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.
o 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.
o 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.
o 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 Exception exception is thrown. If the assignment resulted in a new
(valid) time true is returned. Otherwise false is returned.
Caveat: When setting the month the month may inadvertently be set to the next
month. This happens when the current day number exceeds the number of days in the
target month. Example: assume it is December 31st and the intent is to change the
date to June 21st. The first example sets the date to July 21st since `June 31st’
is converted to `July 1st’. The second example sets the date to June 21st, as
intended.
DateTime dt; // assume set at December 31
dt.setMonth(DateTime::JUNE); // becomes JULY
dt.setDay(21); // Now July 21st
DateTime dt; // assume set at December 31
dt.setDay(21); // Now December 21st
dt.setMonth(DateTime::JUNE); // OK: June 21st
o 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.
o 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.
o 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.
o 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.
o 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 Exception 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.
o 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.
o time_t time() const:
Returns the (UTC) time_t value (in seconds) stored in the DateTime object.
o 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.
o 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.
o DateTime utc() const:
Returns a copy of the DateTime object representing its time in UTC.
o bool valid() const:
Returns true if no errors were detected during the object’s construction (same
semantics as operator bool()).
o Weekday weekday() const:
Returns the Weekday value of the time stored in a DateTime object.
o size_t year() const:
Returns the year element of the time stored in a DateTime object.
o size_t yearDay() const:
Returns the day within the year of the time stored in a DateTime object. January 1
is returned as 0.
o 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.
FILES
bobcat/datetime defines the class interface.
SEE ALSO
bobcat(7), Exception(3bobcat), asctime_r(3), gmtime_r(3), localtime_r(3), time(2),
mktime(3),
BUGS
The class DateTime assumes that time(2) returns the time in UTC.
English is used / expected when specifying named date components.
DISTRIBUTION FILES
o bobcat_4.08.02-x.dsc: detached signature;
o bobcat_4.08.02-x.tar.gz: source archive;
o bobcat_4.08.02-x_i386.changes: change log;
o libbobcat1_4.08.02-x_*.deb: debian package holding the libraries;
o libbobcat1-dev_4.08.02-x_*.deb: debian package holding the libraries, headers and
manual pages;
o http://sourceforge.net/projects/bobcat: public archive location;
BOBCAT
Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.
COPYRIGHT
This is free software, distributed under the terms of the GNU General Public License
(GPL).
AUTHOR
Frank B. Brokken (f.b.brokken@rug.nl).