.TH "FBB::DateTime" "3bobcat" "2005\-2020" "libbobcat\-dev_5\&.07\&.00" "Date and Time" .PP .SH "NAME" FBB::DateTime \- Performs Date and Time Computations .PP .SH "SYNOPSIS" \fB#include \fP .br Linking option: \fI\-lbobcat\fP .PP .SH "DESCRIPTION" .PP \fBFBB::DateTime\fP objects contain and represent date and time values\&. Individual date and time fields can be requested or modified, returning `sanitized\(cq\& times (e\&.g\&., a date like March 33 or a time like 56 hours are never returned; instead the next month or day is returned)\&. Times may be specified in local time (according to the computer\(cq\&s idea of what the local time is), in \fIUniversal Time Coordinated\fP (\fIUTC\fP) time values, as a time in a named timezone, or as a time in a user\-defined timezone\&. Refer to the section \fBTIMEZONES\fP below for a detailed description of how timezones can be specified\&. .PP Dates/times represented by \fIDateTime\fP objects may be modified by adding, subtracting, or setting (\fIstd::chrono\fP) seconds, minutes, or hours, or by specifying (a selection of) fields of \fItm structs\fP\&. .PP Date/time modificationsthese are always performed relative to the \fIDateTime\fP object\(cq\&s current timezone (which may be \fIUTC\fP, local or another timezone)\&. Conversions between timezones (including the \fIUTC\fP `timezone\(cq\&) are also supported\&. .PP \fIDateTime\fP objects can be constructed in many ways\&. Dates and times may be specified as UTC time, as local time, as (\fIstd::chrono::minutes\fP) shifts with respect to UTC time, or as a date and time in other (user defined) time zones\&. Negative time offsets refer to timezones West of Greenwich, and positive offsets refer to timezones East of Greenwich: these offsets represent the zones\(cq\& local time differences with UTC time\&. Timezone offsets are always computed modulo 12 hours, as timezones may at most differ 12 hours from UTC\&. .PP \fIDateTime\fP objects always contain date and time points in seconds since the beginning of the `epoch\(cq\& (midnight Jan 1, 1970 UTC)\&. The \fBC\fP function \fBtime\fP(2) returns this value for the current date and time (assuming that the computer\(cq\&s clock has properly been synchronized)\&. .PP Daylight Saving Time (DST), when defined for \fIDateTime\fP objects\(cq\& zones is automatically applied when DST is active\&. E\&.g\&., when a \fIDateTime\fP object\(cq\&s time represents 12:00 hr\&., and it zone\(cq\&s DST (using a standard +1 hour shift) becomes active tomorrow, then the object\(cq\&s time shows 13:00 hr\&. when 1 day is added to its current date/time\&. .PP Handling time is complex\&. The \fBC\fP function \fBtime\fP(2) returns the time in seconds since the beginning of the epoch\&. Beyond that, simplicity ends, and the reader is referred to Eric S\&. Raymond\(cq\&s (2007) coverage of the complexities of handling time: see http://www\&.catb\&.org/esr/time\-programming (this document is also included in bobcat\(cq\&s repository)\&. .PP .SH "TIMEZONES" .PP \fIDateTime\(cq\&s\fP nested class \fIZone\fP is used to specify time zones\&. Time zones have various configurable components: .IP o The time shift itself\&. E\&.g\&., Central European Time (CET) uses a shift of one hour: when UTC time is noon, then it\(cq\&s 13:00 h\&. CET\&. The time shift doesn\(cq\&t have to be multiples of full hours\&. E\&.g\&., India uses a time shift of +5:30 h relative to UTC\&. .IP o Maybe a Daylight Saving Time\&. Most timezones use a +1 hour DST shift: when in the previous example DST is active then CET\(cq\&s local time is 14:00 h\&. Some countries do not use DST shifts\&. E\&.g\&., Afghanistan doesn\(cq\&t use a DST shift\&. .IP o A date\-interval in which the DST is used may be standard\&. E\&.g\&., it starts at 02:00 h\&. (local time, becoming 03:00 DST), the last Sunday in March, and ends at 02:00 h\&. (local time, resetting DST 03:00 to 02:00) the last Sunday in October\&. .IP o Other calendar intervals may apply\&. E\&.g\&., in 2019 New Zealand\(cq\&s DST starts September 29, and ends April 7th\&. .IP o In practice, DST shifts are equal to 1 hour, although there\(cq\&s no formal requirement for that\&. .PP \fIDataTime::Zone\(cq\&s\fP class offers a variety of means for specifying time zones with or without support for DST\&. Time shifts can be positive or negative and are specified in hours and optionally minutes\&. E\&.g\&., \-8 or \-8:00 for a timezone 8 hours earlier than UTC (noon at UTC becomes 04:00 in this timezone) or +5:30 for a time zone later than UTC (noon at UTC becomes 17:30 in that timezone)\&. Timezones can be given names (which may or may not be the names of the `standard\(cq\& time zones like CET or PST) but can also be constructed by providing .IP o a mere shift relative to UTC, no DST\&. .IP o a shift relative to UTC, using a standard DST (1 hour) time shift\&. In this case the computer\(cq\&s idea of the calendar interval in which DST is active is used; .IP o a shift relative to UTC, using a specified DST time shift as well as a specified calendar interval, optionally specifying the time when the DST calendar interval starts and/or ends\&. .PP .SH "NAMESPACE" \fBFBB\fP .br All constructors, members, operators and manipulators, mentioned in this man\-page, are defined in the namespace \fBFBB\fP\&. .PP .SH "INHERITS FROM" \- .PP .SH "ENUMS" .PP The class \fIDateTime\fP defines the following enums: .PP \fBDateTime::Month\fP .br This enumeration has the following values which are ordered using the default \fBC++\fP \fIenum\fP values: .IP o \fBJANUARY\fP, .IP o \fBFEBRUARY\fP, .IP o \fBMARCH\fP, .IP o \fBAPRIL\fP, .IP o \fBMAY\fP, .IP o \fBJUNE\fP, .IP o \fBJULY\fP, .IP o \fBAUGUST\fP, .IP o \fBSEPTEMBER\fP, .IP o \fBOCTOBER\fP, .IP o \fBNOVEMBER\fP, .IP o \fBDECEMBER\fP\&. .PP Standard 3\-letter abbreviations can also be used (e\&.g\&., \fIDateTime::Jul\fP): .IP o \fBJan\fP, .IP o \fBFeb\fP, .IP o \fBMar\fP, .IP o \fBApr\fP, .IP o \fBMay \fP, .IP o \fBJun\fP, .IP o \fBJul\fP, .IP o \fBAug\fP, .IP o \fBSep\fP, .IP o \fBOct\fP, .IP o \fBNov\fP, .IP o \fBDec\fP\&. .PP \fBDateTime::Relative\fP .br This enumeration is used with the \fIsetMonth()\fP member (see below)\&. It has the following values: .IP o \fBTHIS_WEEK\fP, .IP o \fBTHIS_YEAR\fP, .IP o \fBLAST\fP, .IP o \fBNEXT\fP .PP \fBDateTime::TimeFields\fP .br This enumeration has the following values which can be \fIbit_or\fP\-ed when calling the member \fIsetFields()\fP: .IP o \fBSECONDS\fP .IP o \fBMINUTES\fP .IP o \fBHOURS\fP .IP o \fBMONTHDAY\fP .IP o \fBMONTH\fP .IP o \fBYEAR\fP .PP \fBDateTime::TimeType\fP .br This enumeration has the following values: .IP o \fBLOCALTIME\fP: the \fIDateTime\fP object\(cq\&s date and time use a shift relative to UTC according to the object\(cq\&s configured time zone\&. .IP o \fBUTC\fP: the object\(cq\&s date and time represent the Universal Time Coordinated\&. .PP \fBDateTime::Weekday\fP .br This enumeration has the following values which are ordered using the default \fBC++\fP \fIenum\fP values: .PP .IP o \fBSUNDAY\fP, .IP o \fBMONDAY\fP, .IP o \fBTUESDAY\fP, .IP o \fBWEDNESDAY\fP, .IP o \fBTHURSDAY\fP, .IP o \fBFRIDAY\fP, .IP o \fBSATURDAY\fP\&. .PP Standard 3\-letter abbreviations can also be used (e\&.g\&., \fIDateTime::Wed\fP): .IP o \fBSun\fP, .IP o \fBMon\fP, .IP o \fBTue\fP, .IP o \fBWed\fP, .IP o \fBThu\fP, .IP o \fBFri\fP, .IP o \fBSat\fP\&. .PP .SH "TEXTUAL TIME REPRESENTATIONS" .PP \fIDateTime\fP objects may also be defined using textual time\-representations\&. In addition, the date/time represented by \fIDateTime\fP objects may be altered using textual time representations extracted from \fIistreams\fP\&. .PP The following time formats (shown by example) are recognized: .IP o \fIMon Dec 3 13:29:11 2018\fP, as displayed by \fIput_time(\&.\&.\&., \(dq\&%c\(dq\&)\fP; .IP .IP o \fIMon Dec 3 13:29:11 CET 2018\fP, as displayed by the \fBdate\fP(1) program\&. When this format is used the specified zone name must have been defined\&. \fICET\fP is defined by default, other time zones can easily be defined using, e\&.g\&., the member \fIDateTime::Zone::read\fP (see section \fBZONE MEMBERS\fP)\&. .IP .IP o \fIMon, 03 Dec 2018 13:29:11 +0100\fP, as displayed by the \fIdate \-R\fP command (and the \fIrfc2822()\fP member, see below); .IP .IP o \fI2018\-12\-03 13:29:11+01:00\fP, as displayed by the \fIdate \-\-rfc\-3339=seconds\fP command\&. .PP .SH "ZONE CONSTRUCTORS" .PP The class \fIDateTime::Zone\fP defines how time zones can be defined and used\&. Time zone objects are expected by several \fIDateTime\fP constructors and by the \fIDateTime::setZone\fP member\&. The class \fIDateTime::Zone\fP supports the following constructors: .PP .IP o \fBZone(std::string const &name)\fP: .br The argument \fIname\fP refers to a predefined zone name\&. By default the zone \fICET\fP is available\&. Other zone names can be defined using the members \fIDateTime::Zone::read\fP and \fIDateTime::Zone::store\fP; .IP .IP o \fBZone(std::string const &specification)\fP: .br The argument \fIspecification\fP refers to a zone specification that\(cq\&s available under the directory referred to by \fI/etc/localtime\fP (e\&.g\&., \fI/usr/share/zoneinfo\fP)\&. The specification must start with a colon, followed by the name of an entry that is found below \fI/usr/share/zoneinfo\fP\&. E\&.g, to specify the \fIEurope/Amsterdam\fP zone use \fIDateTime::Zone{ \(dq\&:Europe/Amsterdam\(dq\& }\fP\&. If the specified zone uses DST then a +1 hour DST shift is used; .IP .IP o \fBZone(std::string const &shift)\fP: .br The argument \fIshift\fP defines the zone\(cq\&s shift in hours and minutes relative to UTC\&. Shift\(cq\&s format is \fI[+\-]hh[:mm]\fP, where negative time shifts refer to time zones West of Greenwich and positive time shifts to time zones East of Greenwich\&. No DST is used; .IP .IP o \fBZone(std::string const &shift, string const &dstSpec)\fP: .br The argument \fIshift\fP defines the zone\(cq\&s shift in hours and minutes relative to UTC\&. Shift\(cq\&s format is \fI[+\-]hh[:mm]\fP, where negative time shifts refer to time zones West of Greenwich and positive time shifts to time zones East of Greenwich\&. The \fIdstSpec\fP argument defines the time shift to use when DST is active\&. It uses the same format as \fIshift\fP, or \fI=\fP may be specified, in which case the (standard) DST shift of +1:00 hour is used; .IP .IP o \fBZone(std::string const &shift, std::string const &dstSpec, std::string const &beginDST, std::string const &endDST)\fP: .br Like the previous constructor, but in addition \fIbeginDST\fP and \fIendDST\fP are used to define the date/time interval in which the DST is active\&. These arguments use the following format: .nf Mon, weekSpec Day [hh[:mm]] .fi For \fIMon\fP a standard 3\-letter month specification is used, like \fI\(dq\&Jan\(dq\&\fP for January, for \fIDay\fP a standard 3\-letter day specification is used, like \fI\(dq\&Sun\(dq\&\fP for Sunday (cf\&. the standard 3\-letter abbreviations listed in the section \fIENUMS\fP)\&. .IP The \fIweekSpec\fP defines the number of the week of the month containing \fIDay\fP\&. Use \fI1st, 2nd, 3rd, 4th, 5th\fP or \fIlast\fP\&. Here, \fI1st\fP refers to the first week having day \fIDay\fP, while \fIlast\fP and \fI5th\fP refer to the last week (so not necessarily the 5th week) having day \fIDay\fP\&. .IP The time specification defines the time when the DST starts or ends\&. Some examples: .nf Mar, last Sunday 02:00 Oct, 1st Monday 03:00 .fi .PP Copy and move constructors as well as assignment operators are available\&. .PP .SH "ZONE MEMBERS" .IP o \fBstd::string const &spec() const\fP: .br The constructors\(cq\& zone specifications are converted to a form recognized by the function \fBtzset\fP(3)\&. This member returns the converted string; .IP .IP o \fBint dstSeconds() const\fP: .br If DST is active for a local date/time point then the DST shift in seconds is returned by this member\&. Use the member \fIDateTime::dst()\fP to determine whether or not DST is active\&. .IP .IP o \fBint zoneSeconds() const\fP: .br The zone\(cq\&s time shift relative to UTC in seconds\&. Negative values represent zone shifts West of Greenwich, positive values represent zone shifts East of Greenwich\&. .PP .SH "ZONE STATIC MEMBERS" .PP .IP o \fBDateTime::Zone const &DateTime::Zone::get(std::string const &name)\fP: .br The time zone object named \fIname\fP is returned\&. E\&.g\&., to retrieve the time zone object for \fICET\fP use \fIDateTime::Zone::get(\(dq\&CET\(dq\&)\fP\&. If the named zone has not been defined an \fIstd::exception\fP is thrown; .IP .IP o \fBDateTime::Zone const &DateTime::Zone::store(std::string const &name, \&.\&.\&.)\fP: .br A time zone object is defined and stored as zone \fIname\fP\&. Zone names must consists of (at least three) letters\&. The ellipsis should be replaced by the arguments of the \fIZone\fP constructors (except for the arguments of the first, copy, and move constructors)\&. A reference to the newly defined \fIZone\fP object is returned; .IP .IP o \fBstd::string const &DateTime::Zone::defaultTZ()\fP: .br The TZ specification that is active when the program using \fIDateTime\fP objects starts\&. It returns the return value of \fIgetenv(\(dq\&TZ\(dq\&)\fP or an empty string if the \fITZ\fP environment variable was not defined; .IP .IP o \fBvoid DateTime::Zone::read(std::string const &fname)\fP: .br Time zone specifications as expected by the above \fIstore\fP member are read from the file named \fIfname\fP (one specification per line, using blanks between the elements, and inserting \fIuntil\fP between the \fIdstBegin\fP and \fIdstEnd\fP specifications (if provided))\&. For cosmetic reasons a colon may be appended to zone names\&. Examples: .nf ccu: +5:50 nyc: \-5:00 +1:00 cal: \-8:00 = eet: +2:00 +1:00 Mar, last Sun 02:00 until Oct, last Sun 02:00 same: +2:00 = Mar, last Sun 02:00 until Oct, last Sun 02:00 .fi If the first character on a line is a hash\-tag (\fI#\fP) or if a line only contains blanks it is ignored; .IP .IP o \fBtime_t DateTime::Zone::thisZoneShift()\fP: .br Returns this computer\(cq\&s zone shift in seconds\&. .PP .SH "DATETIME CONSTRUCTORS" .PP .IP o \fBDateTime(TimeType type = UTC)\fP: .br The object\(cq\&s date/time is initialized to the current date and time\&. By default UTC time (no zone\-shift or dst correction) is used\&. When specifying \fILOCALTIME\fP, the computer\(cq\&s timezone and DST correction are used; .IP .IP o \fBDateTime(std::chrono::minutes zoneMinutes)\fP: .br The object\(cq\&s local time is initialized to the current UTC time to which a zone shift of zoneMinutes minutes is added\&. DST is not used\&. Note that by specifying a zone shift in, e\&.g\&., \fIstd::chrono::hours\fP a conversion to minutes is automatically applied; .IP .IP o \fBDateTime(Datetime::Zone const &zone)\fP: .br The object\(cq\&s local time is initialized to the the current UTC time to which a zone shift defined by the \fIZone\fP argument is added; .IP .IP o \fBDateTime(time_t time, TimeType type = UTC)\fP: .br The object uses \fItime\fP to set its UTC time in seconds since the epoch\&. When \fILOCALTIME\fP is specified its local time is obtained by applying the computer\(cq\&s timezone and DST correction; .IP .IP o \fBDateTime(time_t time, std::chrono::minutes zoneMinutes)\fP: .br The object\(cq\&s uses \fItime\fP to set its UTC time in seconds since the epoch\&. Its local time is then obtained by adding a zone shift of zoneMinutes minutes\&. DST is not used\&.; .IP .IP o \fBDateTime(time_t time, Datetime::Zone const &zone)\fP: .br The object\(cq\&s uses \fItime\fP to set its UTC time in seconds since the epoch\&. Its local time is then obtained by adding a zone shift as defined by the \fIZone\fP argument\&. .IP .IP o \fBDateTime(tm const &ts, TimeType type = UTC)\fP: .br The \fItm\fP argument is a struct defined as: .nf 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 see below!! 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 }; .fi Values outside of these ranges may be specified to compute points in time in the future or in the past\&. E\&.g\&., \fItm_hour == 30\fP is normalized to \fItm_hour == 6\fP of the next day\&. .IP Note that functions like \fBmktime\fP(3) expect \fItm_year\fP to be specified relative to 1900\&. The \fIDateTime\fP constructor does \fInot\fP expect this: the \fItm_year\fP field should be the specified as the (calendar) year, e\&.g\&., 2019\&. .IP Using \fItm\(cq\&s\fP fields the object\(cq\&s date/time is initialized to either UTC or LOCALTIME\&. The DST, day of the year, and day of the week fields of the \fItm\fP argument are ignored; .IP .IP o \fBDateTime(tm const &ts, Datetime::Zone const &zone)\fP: .br The fields of \fIts\fP (see the previous constructor) define a \fILOCALTIME\fP time point in the specified \fIZone\fP\&. .IP .IP o \fBDateTime(std::string const &timeStr, TimeType type = UTC)\fP: .br The object\(cq\&s date/time is initialized to either UTC or LOCALTIME using \fIDateTime\(cq\&s\fP supported textual time representations\&. The time representation without explicit timezone shift (e\&.g\&., \fIMon Dec 3 13:29:11 2018\fP is interpreted as UTC time when \fItype == UTC\fP is specified, otherwise as local time (\fItype == LOCALTIME\fP), using the computer\(cq\&s time zone and DST correction)\&. The other textual time representations provide zone specifications which are used to obtain the requested time representation (e\&.g\&., when UTC is requested, and the textual time specification contains \fI13:29:11 +0100\fP then the object\(cq\&s (UTC) time is set to \fI12:29:11\fP)\&. DST specifications are ignored, except when named time zones are used, as in \fIon Dec 3 13:29:11 CET 2018\fP; .IP .IP o \fBDateTime(std::istream &in, TimeType type = UTC)\fP: .br The object\(cq\&s date/time is initialized to either UTC or LOCALTIME extracting a supported textual time representation from \fIin\fP as destribed at the \fIDateTime(std::string const &timeStr, \&.\&.\&.)\fP constructor\&. The \fIstd::istream &in\fP stream may also be a rvalue reference\&. .PP Copy and move constructors are available\&. .PP .SH "OVERLOADED OPERATORS" .PP All class\-less overloaded operators are defined in the \fIFBB\fP namespace\&. All overloaded operators modifying \fIDateTime\fP objects support `commit or roll\-back\(cq\&: if the operation cannot be performed an exception is thrown, without modifying the destination object\&. .PP .IP o \fBstd::ostream &std::operator<<(std::ostream &str, DateTime const &dt)\fP: .br Inserts \fIdt\(cq\&s\fP date/time into \fIstr\fP using the zone\-less supported textual time representation (e\&.g\&., \fIMon Dec 3 13:29:11 2018\fP); .IP .IP o \fBstd::istream &std::operator>>(std::istream &str, DateTime &dt)\fP: .br Extracts a supported textual time representation from \fIstr\fP and assigns the implied date/time point to \fIdt\fP; .IP .IP o \fBbool operator==(DateTime const &left, DateTime const &right)\fP: .br Returns \fItrue\fP if \fIleft\fP represents the same UTC time as \fIright\fP; .IP .IP o \fBbool operator!=(DateTime const &left, DateTime const &right)\fP: .br Returns \fItrue\fP if \fIleft\fP represents a different UTC time as \fIright\fP; .IP .IP o \fBbool operator<(DateTime const &left, DateTime const &right)\fP: .br Returns \fItrue\fP if \fIleft\fP represents an earlier UTC time as \fIright\fP; .IP .IP o \fBbool operator<=(DateTime const &left, DateTime const &right)\fP: .br Returns \fItrue\fP if \fIleft\fP represents an earlier or equal UTC time as \fIright\fP; .IP .IP o \fBbool operator>(DateTime const &left, DateTime const &right)\fP: .br Returns \fItrue\fP if \fIleft\fP represents a later UTC time as \fIright\fP; .IP .IP o \fBbool operator>=(DateTime const &left, DateTime const &right)\fP: .br Returns \fItrue\fP if \fIleft\fP represents a later or equal UTC time as \fIright\fP\&. .IP .IP o \fBDateTime operator+(DateTime const &obj, std::chrono::seconds seconds)\fP: .br Returns a copy of \fIobj\fP to which \fIseconds\fP were added; .IP .IP o \fBDateTime operator+(DateTime const &obj, tm const &ts)\fP: .br Returns a copy of \fIobj\fP to which the \fItm_sec, tm_min, tm_hour, tm_mday, tm_mon\fP and \fItm_year\fP fields of \fIts\fP were added; .IP Caveat: note that this is an \fIaddition\fP operation: if you want to add 1 year specify \fIts\&.tm_year = 1\fP, and not the finally expected calendar year! .IP .IP o \fBDateTime &operator+=(std::chrono::seconds seconds)\fP: .br Adds \fIseconds\fP to the time represented by the current object; .IP .IP o \fBDateTime &operator+=(tm const &ts)\fP: .br Adds the \fItm_sec, tm_min, tm_hour, tm_mday, tm_mon\fP and \fItm_year\fP fields of \fIts\fP to the time represented by the current object\&. .IP Caveat: note that this is an \fIaddition\fP operation: if you want to add 1 year specify \fIts\&.tm_year = 1\fP, and not the finally expected calendar year! .IP .IP o \fBDateTime operator\-(DateTime const &obj, std::chrono::seconds seconds)\fP: .br Returns a copy of \fIobj\fP to which \fIseconds\fP were subtracted; .IP .IP o \fBDateTime operator\-(DateTime const &obj, tm const &ts)\fP: .br Returns a copy of \fIobj\fP to which the \fItm_sec, tm_min, tm_hour, tm_mday, tm_mon\fP and \fItm_year\fP fields of \fIts\fP were subtracted\&. .IP Caveat: note that this is an \fIaddition\fP operation: if you want to subtract 1 year specify \fIts\&.tm_year = 1\fP, and not the finally expected calendar year! .IP .IP o \fBDateTime &operator\-=(std::chrono::seconds seconds)\fP: .br Subtracts \fIseconds\fP from the time represented by the current object; .IP .IP o \fBDateTime &operator\-=(tm const &ts)\fP: .br Subtracts the \fItm_sec, tm_min, tm_hour, tm_mday, tm_mon\fP and \fItm_year\fP fields of \fIts\fP from the time represented by the current object\&. .IP Caveat: note that this is an \fIaddition\fP operation: if you want to subtract 1 year specify \fIts\&.tm_year = 1\fP, and not the finally expected calendar year! .IP E\&.g\&., the following program fragment displays midnight, December 31, 1969: .nf DateTime dt{ 0, DateTime::UTC }; // set UTC at begin of era tm era{ 0 }; // define a tm with tm_mday == 1 era\&.tm_mday = 1; dt \-= era; // subtract from dt and display cout << dt << endl; .fi .IP Copy and move assignment operators are available\&. .PP .SH "MEMBER FUNCTIONS" .PP All members returning a time\-element do so according to the latest time\-representation (i\&.e\&., \fIUTC\fP, \fILOCALTIME\fP, or using an explicitly set display zone shift value)\&. All members returning numeric values use 0 as their smallest return value, except for the \fB\&.\&.\&.Nr()\fP members, which start at 1\&. .PP .IP o \fBbool dst() const\fP: .br Returns \fItrue\fP if the current object\(cq\&s time includes a DST shift, otherwise \fIfalse\fP is returned\&. .IP .IP o \fBunsigned hours() const\fP: .br Returns the number of hours represented by the current object\(cq\&s time (0\-23); .IP .IP o \fBunsigned minutes() const\fP: .br Returns the number of minutes represented by the current object (0\-59); .IP .IP o \fBDateTime::Month month() const\fP: .br Returns the \fIMonth\fP represented by the current object; .IP .IP o \fBunsigned monthDayNr() const\fP: .br Returns the day number of the month represented by the current object\(cq\&s date (1\-31); .IP .IP o \fBstring rfc2822() const\fP: .br Returns the current object\(cq\&s date/time displayed according to the RFC 2822 format\&. This format is used, e\&.g\&., by the \fIdate \-R\fP command (cf\&. \fBdate\fP(1))\&. For example: .nf Mon, 3 Dec 2018 13:49:10 +0100 .fi .IP .IP o \fBstring rfc3339() const\fP: .br Returns the current object\(cq\&s date/time displayed according to the the RFC 3339 format\&. This format is used, e\&.g\&., by the \fIdate \-\-rfc\-3339=seconds\fP command (cf\&. \fBdate\fP(1))\&. For example: .nf 2018\-12\-03 13:29:11+01:00 .fi .IP .IP o \fBunsigned seconds() const\fP: .br Returns the number of seconds represented by the current object\(cq\&s time (0\-59, but 60 and 61 may occur at leap seconds); .IP .IP o \fBvoid setDay(int dayNr)\fP: .br Assigns \fIdayNr\fP to the day number of the object\(cq\&s current month\&. .IP Caveat: since day numbers start at 1, passing 0 or negative values to \fIsetDay\fP results in resetting the objects date to an earlier month; .IP .IP o \fBvoid setFields(tm const &ts, DateTime::TimeFields fields)\fP: .br Assigns the fields of \fIts\fP indicated by a \fIbit_or\fP combination of \fITimeFields fields\(cq\&\fP value to the corresponding current object\(cq\&s date/time \fItm\fP fields; .IP .IP o \fBvoid setHours(int hours)\fP: .br Assigns \fIhours\fP to the number of hours of the current object\(cq\&s time; .IP .IP o \fBvoid setMinutes(int minutes)\fP: .br Assigns \fIminutes\fP to the number of minutes of the current object\(cq\&s time; .IP .IP o \fBvoid setMonth(int month)\fP: .br Assigns \fImonth\fP to the current object\(cq\&s month\&. January is represented by 0, December by 11\&. Smaller or larger values refer to previous or future years; .IP .IP o \fBvoid setMonth(DateTime::Month month)\fP: .br Assigns \fImonth\fP to the current object\(cq\&s month; .IP .IP o \fBvoid setMonth(DateTime::Month month, DateTime::Relative where = THIS_YEAR)\fP: .br Assigns \fImonth\fP to the current object\(cq\&s month\&. By default the month of the current year is updated (\fIwhere == THIS_YEAR\fP)\&. Use \fILAST\fP to ensure that the month is set before the current object\(cq\&s month (e\&.g\&., if the current month is \fIJUNE\fP, then requesting \fIAUGUST, LAST\fP will decrement the object\(cq\&s year, but requesting \fIMAY, LAST\fP won\(cq\&t)\&. Analogously, when specifying \fIDateTime::NEXT\fP the resulting month is set after the current object\(cq\&s month\&. .IP Caveat: If the day number of the current month exceeds the number of days in the requested month, the object\(cq\&s month and day number are updated to the next month\&. E\&.g\&., if the current day number equals 31, and \fINOVEMBER\fP is requested, then the object\(cq\&s date is updated to December 1; .IP .IP o \fBvoid setSeconds(int seconds)\fP: .br Assigns \fIseconds\fP to the number of seconds of the current object\(cq\&s time; .IP .IP o \fBvoid setUTCseconds(time_t utcSeconds)\fP: .br Assigns \fIutcSeconds\fP as the number of seconds since the epoch to the current object\(cq\&s UTC time; .IP .IP o \fBvoid setWeekday(Weekday day, Relative where = NEXT)\fP: .br Assigns \fIday\fP to the current object\(cq\&s day of the week\&. By default (\fIwhere == NEXT\fP) the day will be the next occurrence of \fIday\fP (maybe the current week, maybe in the next week: if the current day equals Monday and Friday is specified, the current week is used\&. If the current day equals Friday and Monday is requested the next week is used)\&. By specifying \fIwhere = LAST\fP the day will be most recent occurrence of \fIday\fP: if the current day equals Friday and Monday is requested, the current week is used\&. By specifying \fIwhere = THIS_WEEK\fP then \fIday\fP is selected in the current week; .PP .IP o \fBvoid setYear(unsigned year)\fP: .br Assigns \fIyear\fP to the current object\(cq\&s date\&. Note that \fIyear\fP is the actual calendar year, and not, e\&.g\&., the year relative to the beginning of the epoch or 1900; .PP .IP o \fBvoid setZone(Datetime::Zone const &zone)\fP: .br The current object\(cq\&s time zone is set to \fIzone\fP\&. This does not alter the object\(cq\&s UTC time, but merely its time zone\&. If the object represented UTC time before calling \fIsetZone\fP it will represent a local time after calling \fIsetZone\fP; .PP .IP o \fBvoid swap(DateTime &other)\fP: .br Swaps the current and other \fIDateTime\fP object; .PP .IP o \fBDateTime thisTime() const\fP: .br Returns a \fIDateTime\fP object using the current object\(cq\&s UTC time, applying the computer\(cq\&s default time zone; .PP .IP o \fBtm const *timeStruct() const\fP: .br Returns a pointer to the object\(cq\&s current \fItm\fP representing its object\(cq\&s broken down time elements\&. If the object holds a local time the \fItm\fP struct represents the local time (if applicable: including a DST shift), otherwise it represents UTC; .PP .IP o \fBDateTime utc() const\fP: .br Returns a copy of the current object representing its UTC time; .PP .IP o \fBtime_t utcSeconds() const\fP: .br Returns the current object\(cq\&s (UTC) time in seconds since the epoch; .PP .IP o \fBDateTime::Weekday weekday() const\fP: .br Returns the current object\(cq\&s \fIWeekday\fP value; .PP .IP o \fBunsigned weekNr() const\fP: .br Returns the week number of the current object\(cq\&s date\&. Week numbers are numbers of complete weeks\&. If Jan 1st is a Sunday then the week numbers of Jan 1st through Jan 6th are returned as 1, otherwise the week numbers of Jan 1st through the date of the first Saturday of the year (which could very well be Jan 1st) are returned as 52; .PP .IP o \fBunsigned year() const\fP: .br Returns the year of the current object\(cq\&s date (note: this is the actual calendar year, not the year since the epoch or relative to 1900); .PP .IP o \fBunsigned yearDay() const\fP: .br Returns the day in the year of the current object\(cq\&s date\&. January 1st is returned as 0; .PP .IP o \fBunsigned yearDayNr() const\fP: .br Returns the day in the year of the current object\(cq\&s date\&. January 1 is returned as 1; .PP .IP o \fBDateTime::Zone const &zone() const\fP: .br Returns the current object\(cq\&s \fIZone\fP object\&. ) .PP .SH "STATIC MEMBER" .PP .IP o \fBvoid tm2cout(char const *label, TM const &ts)\fP: .br This static member is primarily used for debugging purposes\&. It displays the values of \fIts\(cq\&s\fP fields, preceded by \fIlabel\fP and \fI\(dq\&: \(dq\&\fP\&. .PP .SH "EXAMPLES" .PP Many examples illustrating the use of \fIDateTime\fP objects are provided in the source archive\(cq\&s \fIbobcat/datetime/driver\fP directory\&. Here is an example: .nf #include #include \(dq\&\&.\&./datetime\(dq\& using namespace std; using namespace FBB; void show(DateTime const &dt, char const *label) { cout << label << \(dq\&: \(dq\& << dt << \(dq\&\en\(dq\& \(dq\&dst: \(dq\& << dt\&.dst() << \(dq\&\en\(dq\& \(dq\&hh:mm:ss: \(dq\& << dt\&.hours() << \(cq\&:\(cq\& << dt\&.minutes() << \(cq\&:\(cq\& << dt\&.seconds() << \(dq\&\en\(dq\& \(dq\&year\-month\-monthdaynr: \(dq\& << dt\&.year() << \(cq\&\-\(cq\& << dt\&.month() << \(cq\&\-\(cq\& << dt\&.monthDayNr() << \(dq\&\en\(dq\& \(dq\&weekday/weeknr/yearday/yeardaynr: \(dq\& << dt\&.weekday() << \(cq\&/\(cq\& << dt\&.weekNr() << \(cq\&/\(cq\& << dt\&.yearDay() << \(cq\&/\(cq\& << dt\&.yearDayNr() << \(dq\&\en\(dq\& \(dq\&\en\(dq\&; } int main() { time_t now = time(0); DateTime utc{ now, DateTime::UTC }; show(utc, \(dq\&Current UTC time\(dq\&); DateTime local{ utc\&.thisTime() }; cout << \(dq\&The COMPUTER\(cq\&S LOCAL TIME: \(dq\& << local << \(cq\&\en\(cq\&; DateTime dt{ now, DateTime::LOCALTIME }; show(dt, \(dq\&Current LOCAL TIME\(dq\&); DateTime utc2{ dt\&.utc() }; cout << \(dq\&UTC obtained from LOCAL TIME: \(dq\& << utc2 << \(cq\&\en\(cq\&; DateTime jan1{ \(dq\&2019\-01\-01 13:00:00+01:00\(dq\&, DateTime::LOCALTIME }; cout << \(dq\&Jan 1, 1919, 13:00h: \(dq\& << jan1 << \(cq\&\en\(cq\&; show(jan1, \(dq\&Jan 1, details:\(dq\&); cout << \(dq\&\enOptionally rerun specifying another time zone specification\en\(dq\& \(dq\&\en\(dq\&; } .fi .PP .SH "FILES" \fIbobcat/datetime\fP defines the class interface\&. .PP .SH "SEE ALSO" \fBbobcat\fP(7), \fBException\fP(3bobcat), \fBgmtime_r\fP(3), \fBlocaltime_r\fP(3), \fBmktime\fP(3), \fBtime\fP(2), \fBtzset\fP(3), .br \fBhttp://www\&.catb\&.org/esr/time\-programming\fP, .br \fBhttps://www\&.timeanddate\&.com/time/dst/events\&.html\fP .PP .SH "BUGS" See bobcat\(cq\&s changelog file for an overview of members that were discontinued at release 5\&.00\&.00\&. .br The class \fIDateTime\fP assumes that \fBtime\fP(2) returns the time in UTC\&. .br English is used/expected when specifying named date components\&. .PP .SH "BOBCAT PROJECT FILES" .PP .IP o \fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page; .IP o \fIbobcat_5\&.07\&.00\-x\&.dsc\fP: detached signature; .IP o \fIbobcat_5\&.07\&.00\-x\&.tar\&.gz\fP: source archive; .IP o \fIbobcat_5\&.07\&.00\-x_i386\&.changes\fP: change log; .IP o \fIlibbobcat1_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the libraries; .IP o \fIlibbobcat1\-dev_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the libraries, headers and manual pages; .PP .SH "BOBCAT" Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&. .PP .SH "COPYRIGHT" This is free software, distributed under the terms of the GNU General Public License (GPL)\&. .PP .SH "AUTHOR" Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&. .PP