FBB::DateTime(3bobcat)

Date and Time
(libbobcat-dev_6.04.00)

2005-2023

NAME

FBB::DateTime - Performs Date and Time Computations

SYNOPSIS

#include <bobcat/datetime>
Linking option: -lbobcat

DESCRIPTION

FBB::DateTime objects contain and represent date and time values. Individual date and time fields can be requested or modified, returning `sanitized' 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's idea of what the local time is), in Universal Time Coordinated (UTC) time values, as a time in a named timezone, or as a time in a user-defined timezone. Refer to the section TIMEZONES below for a detailed description of how timezones can be specified.

Dates/times represented by DateTime objects may be modified by adding, subtracting, or setting (std::chrono) seconds, minutes, or hours, or by specifying (a selection of) fields of tm structs.

Date/time modificationsthese are always performed relative to the DateTime object's current timezone (which may be UTC, local or another timezone). Conversions between timezones (including the UTC `timezone') are also supported.

DateTime objects can be constructed in many ways. Dates and times may be specified as UTC time, as local time, as (std::chrono::minutes) 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' local time differences with UTC time. Timezone offsets are always computed modulo 12 hours, as timezones may at most differ 12 hours from UTC.

DateTime objects always contain date and time points in seconds since the beginning of the `epoch' (midnight Jan 1, 1970 UTC). The C function time(2) returns this value for the current date and time (assuming that the computer's clock has properly been synchronized).

Daylight Saving Time (DST), when defined for DateTime objects' zones is automatically applied when DST is active. E.g., when a DateTime object's time represents 12:00 hr., and it zone's DST (using a standard +1 hour shift) becomes active tomorrow, then the object's time shows 13:00 hr. when 1 day is added to its current date/time.

Handling time is complex. The C function time(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's (2007) coverage of the complexities of handling time: see http://www.catb.org/esr/time-programming (this document is also included in bobcat's repository).

TIMEZONES

DateTime's nested class Zone is used to specify time zones. Time zones have various configurable components:

DataTime::Zone's 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' time zones like CET or PST) but can also be constructed by providing

NAMESPACE

FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace FBB.

INHERITS FROM

-

ENUMS

The class DateTime defines the following enums:

DateTime::Month
This enumeration has the following values which are ordered using the default C++ enum values:

Standard 3-letter abbreviations can also be used (e.g., DateTime::Jul):

DateTime::Relative
This enumeration is used with the setMonth() member (see below). It has the following values:

DateTime::TimeFields
This enumeration has the following values which can be bit_or-ed when calling the member setFields():

DateTime::TimeType
This enumeration has the following values:

DateTime::Weekday
This enumeration has the following values which are ordered using the default C++ enum values:

Standard 3-letter abbreviations can also be used (e.g., DateTime::Wed):

TEXTUAL TIME REPRESENTATIONS

DateTime objects may also be defined using textual time-representations. In addition, the date/time represented by DateTime objects may be altered using textual time representations extracted from istreams.

The following time formats (shown by example) are recognized:

ZONE CONSTRUCTORS

The class DateTime::Zone defines how time zones can be defined and used. Time zone objects are expected by several DateTime constructors and by the DateTime::setZone member. The class DateTime::Zone supports the following constructors:

Copy and move constructors as well as assignment operators are available.

ZONE MEMBERS

ZONE STATIC MEMBERS

DATETIME CONSTRUCTORS

Copy and move constructors are available.

OVERLOADED OPERATORS

All class-less overloaded operators are defined in the FBB namespace. All overloaded operators modifying DateTime objects support `commit or roll-back': if the operation cannot be performed an exception is thrown, without modifying the destination object.

Copy and move assignment operators are 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 numeric values use 0 as their smallest return value, except for the ...Nr() members, which start at 1.

STATIC MEMBER

EXAMPLES

Many examples illustrating the use of DateTime objects are provided in the source archive's bobcat/datetime/driver directory. Here is an example:

#include <iostream>

#include "../datetime"

using namespace std;
using namespace FBB;

void show(DateTime const &dt, char const *label)
{
    cout <<
        label << ": " << dt << "\n"
        "dst: " << dt.dst() << "\n"
        "hh:mm:ss: " << dt.hours() << ':' << dt.minutes() << ':' <<
                        dt.seconds() << "\n"
        "year-month-monthdaynr: " << dt.year() << '-' << dt.month() << '-' <<
                                     dt.monthDayNr() << "\n"
        "weekday/weeknr/yearday/yeardaynr: " <<
            dt.weekday() << '/' << dt.weekNr() << '/' <<
            dt.yearDay() << '/' << dt.yearDayNr() << "\n"
        "\n";
}

int main()
{
    time_t now = time(0);

    DateTime utc{ now, DateTime::UTC };
    show(utc, "Current UTC time");

    DateTime local{ utc.thisTime() };

    cout << "The COMPUTER'S LOCAL TIME: " << local << '\n';

    DateTime dt{ now, DateTime::LOCALTIME };
    show(dt, "Current LOCAL TIME");

    DateTime utc2{ dt.utc() };
    cout << "UTC obtained from LOCAL TIME: " << utc2 << '\n';

    DateTime jan1{ "2019-01-01 13:00:00+01:00", DateTime::LOCALTIME };
    cout << "Jan 1, 1919, 13:00h: " << jan1 << '\n';
    show(jan1, "Jan 1, details:");

    cout << "\nOptionally rerun specifying another time zone specification\n"
            "\n";
}

FILES

bobcat/datetime defines the class interface.

SEE ALSO

bobcat(7), Exception(3bobcat), gmtime_r(3), localtime_r(3), mktime(3), time(2), tzset(3),
http://www.catb.org/esr/time-programming,
https://www.timeanddate.com/time/dst/events.html

BUGS

See bobcat's changelog file for an overview of members that were discontinued at release 5.00.00.
The class DateTime assumes that time(2) returns the time in UTC.
English is used/expected when specifying named date components.

BOBCAT PROJECT FILES

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).