| Home | Libraries | People | FAQ | More

## Class template local_date_time_base

boost::local_time::local_date_time_base — Representation of "wall-clock" time in a particular time zone.

## Synopsis

    // In header: <boost/date_time/local_time/local_date_time.hpp>

    template<typename utc_time_ = posix_time::ptime,
             typename tz_type = date_time::time_zone_base<utc_time_,char> >
    class local_date_time_base {
    public:
      // types
      typedef utc_time_                         utc_time_type;
      typedef utc_time_type::time_duration_type time_duration_type;
      typedef utc_time_type::date_type          date_type;
      typedef date_type::duration_type          date_duration_type;
      typedef utc_time_type::time_system_type   time_system_type;

      enum DST_CALC_OPTIONS { EXCEPTION_ON_ERROR, NOT_DATE_TIME_ON_ERROR };

      // construct/copy/destruct
      local_date_time_base(utc_time_type, boost::shared_ptr< tz_type >);
      local_date_time_base(date_type, time_duration_type,
                           boost::shared_ptr< tz_type >, bool);
      local_date_time_base(date_type, time_duration_type,
                           boost::shared_ptr< tz_type >, DST_CALC_OPTIONS);
      local_date_time_base(const local_date_time_base &);
      explicit local_date_time_base(const boost::date_time::special_values,
                                    boost::shared_ptr< tz_type > = boost::shared_ptr< tz_type >());
      ~local_date_time_base();

      // public member functions
      boost::shared_ptr< tz_type > zone() const;
      bool is_dst() const;
      utc_time_type utc_time() const;
      utc_time_type local_time() const;
      std::string to_string() const;
      local_date_time_base
      local_time_in(boost::shared_ptr< tz_type >,
                    time_duration_type = time_duration_type(0, 0, 0)) const;
      std::string zone_name(bool = false) const;
      std::string zone_abbrev(bool = false) const;
      std::string zone_as_posix_string() const;
      bool operator==(const local_date_time_base &) const;
      bool operator!=(const local_date_time_base &) const;
      bool operator<(const local_date_time_base &) const;
      bool operator<=(const local_date_time_base &) const;
      bool operator>(const local_date_time_base &) const;
      bool operator>=(const local_date_time_base &) const;
      local_date_time_base operator+(const date_duration_type &) const;
      local_date_time_base operator+=(const date_duration_type &);
      local_date_time_base operator-(const date_duration_type &) const;
      local_date_time_base operator-=(const date_duration_type &);
      local_date_time_base operator+(const time_duration_type &) const;
      local_date_time_base operator+=(const time_duration_type &);
      local_date_time_base operator-(const time_duration_type &) const;
      local_date_time_base operator-=(const time_duration_type &);
      time_duration_type operator-(const local_date_time_base &) const;

      // public static functions
      static time_is_dst_result
      check_dst(date_type, time_duration_type, boost::shared_ptr< tz_type >);

      // private member functions
      utc_time_type
      construction_adjustment(utc_time_type, boost::shared_ptr< tz_type >, bool);
      std::string zone_as_offset(const time_duration_type &, const std::string &) const;
    };

## Description

Representation of "wall-clock" time in a particular time zone Local_date_time_base holds a time value (date and time offset from 00:00) along with a time zone. The time value is stored as UTC and conversions to wall clock time are made as needed. This approach allows for operations between wall-clock times in different time zones, and daylight savings time considerations, to be made. Time zones are required to be in the form of a boost::shared_ptr<time_zone_base>.

### `local_date_time_base` public construct/copy/destruct

1.     local_date_time_base(utc_time_type t, boost::shared_ptr< tz_type > tz);

   This constructor interprets the passed time as a UTC time. So, for example, if the passed timezone is UTC-5 then the time will be adjusted back 5 hours. The time zone allows for automatic calculation of whether the particular time is adjusted for daylight savings, etc. If the time zone shared pointer is null then time stays unadjusted.

   Parameters:

   `t` | A UTC time
   `tz` | Timezone for to adjust the UTC time to.

2.     local_date_time_base(date_type d, time_duration_type td,
                            boost::shared_ptr< tz_type > tz, bool dst_flag);

   This constructs a local time -- the passed time information understood to be in the passed tz. The DST flag must be passed to indicate whether the time is in daylight savings or not.

   Throws: | -- time_label_invalid if the time passed does not exist in the given locale. The non-existent case occurs typically during the shift-back from daylight savings time. When the clock is shifted forward a range of times (2 am to 3 am in the US) is skipped and hence is invalid. dst_not_valid if the DST flag is passed for a period where DST is not active.

3.     local_date_time_base(date_type d, time_duration_type td,
                            boost::shared_ptr< tz_type > tz,
                            DST_CALC_OPTIONS calc_option);

   This constructs a local time -- the passed time information understood to be in the passed tz. The DST flag is calculated according to the specified rule.

4.     local_date_time_base(const local_date_time_base & rhs);

   Copy constructor.

5.     explicit local_date_time_base(const boost::date_time::special_values sv,
                                     boost::shared_ptr< tz_type > tz = boost::shared_ptr< tz_type >());

   Special values constructor.

6.     ~local_date_time_base();

   Simple destructor, releases time zone if last referrer.

### `local_date_time_base` public member functions

1.     boost::shared_ptr< tz_type > zone() const;

   returns time zone associated with calling instance

2.     bool is_dst() const;

   returns false is time_zone is NULL and if time value is a special_value

3.     utc_time_type utc_time() const;

   Returns object's time value as a utc representation.

4.     utc_time_type local_time() const;

   Returns object's time value as a local representation.

5.     std::string to_string() const;

   Returns string in the form "2003-Aug-20 05:00:00 EDT".

   Returns string in the form "2003-Aug-20 05:00:00 EDT". If time_zone is NULL the time zone abbreviation will be "UTC". The time zone abbrev will not be included if calling object is a special_value

6.     local_date_time_base
       local_time_in(boost::shared_ptr< tz_type > new_tz,
                     time_duration_type td = time_duration_type(0, 0, 0)) const;

   returns a `local_date_time_base` in the given time zone with the optional time_duration added.

7.     std::string zone_name(bool as_offset = false) const;

   Returns name of associated time zone or "Coordinated Universal Time".

   Optional bool parameter will return time zone as an offset (ie "+07:00" extended iso format). Empty string is returned for classes that do not use a time_zone

8.     std::string zone_abbrev(bool as_offset = false) const;

   Returns abbreviation of associated time zone or "UTC".

   Optional bool parameter will return time zone as an offset (ie "+0700" iso format). Empty string is returned for classes that do not use a time_zone

9.     std::string zone_as_posix_string() const;

   returns a posix_time_zone string for the associated time_zone. If no time_zone, "UTC+00" is returned.

10.     bool operator==(const local_date_time_base & rhs) const;

    Equality comparison operator.

    Equality comparison operator

11.     bool operator!=(const local_date_time_base & rhs) const;

    Non-Equality comparison operator.

12.     bool operator<(const local_date_time_base & rhs) const;

    Less than comparison operator.

13.     bool operator<=(const local_date_time_base & rhs) const;

    Less than or equal to comparison operator.

14.     bool operator>(const local_date_time_base & rhs) const;

    Greater than comparison operator.

15.     bool operator>=(const local_date_time_base & rhs) const;

    Greater than or equal to comparison operator.

16.     local_date_time_base operator+(const date_duration_type & dd) const;

    Local_date_time + date_duration.

17.     local_date_time_base operator+=(const date_duration_type & dd);

    Local_date_time += date_duration.

18.     local_date_time_base operator-(const date_duration_type & dd) const;

    Local_date_time - date_duration.

19.     local_date_time_base operator-=(const date_duration_type & dd);

    Local_date_time -= date_duration.

20.     local_date_time_base operator+(const time_duration_type & td) const;

    Local_date_time + time_duration.

21.     local_date_time_base operator+=(const time_duration_type & td);

    Local_date_time += time_duration.

22.     local_date_time_base operator-(const time_duration_type & td) const;

    Local_date_time - time_duration.

23.     local_date_time_base operator-=(const time_duration_type & td);

    Local_date_time -= time_duration.

24.     time_duration_type operator-(const local_date_time_base & rhs) const;

    local_date_time -= local_date_time --> time_duration_type

### `local_date_time_base` public static functions

1.     static time_is_dst_result
       check_dst(date_type d, time_duration_type td, boost::shared_ptr< tz_type > tz);

   Determines if given time label is in daylight savings for given zone.

   Determines if given time label is in daylight savings for given zone. Takes a date and time_duration representing a local time, along with time zone, and returns a time_is_dst_result object as result.

### `local_date_time_base` private member functions

1.     utc_time_type
       construction_adjustment(utc_time_type t, boost::shared_ptr< tz_type > z,
                               bool dst_flag);

   Adjust the passed in time to UTC?

2.     std::string zone_as_offset(const time_duration_type & td,
                                  const std::string & separator) const;

   Simple formatting code -- todo remove this?