Provided by: libbobcat-dev_4.08.02-2build1_amd64 bug

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