# Local Time Period

Introduction -- Header -- Construction -- Accessors -- Operators

Introduction

The class `boost::local_time::local_time_period` provides direct representation for ranges between two local times. Periods provide the ability to simplify some types of calculations by simplifying the conditional logic of the program.

A period that is created with beginning and end points being equal, or with a duration of zero, is known as a zero length period. Zero length periods are considered invalid (it is perfectly legal to construct an invalid period). For these periods, the `last` point will always be one unit less that the `begin` point.

Header

    #include "boost/date_time/local_time/local_time.hpp" //include all types plus i/o
    or
    #include "boost/date_time/local_time/local_time_types.hpp" //no i/o just types

Construction

Syntax | Description
--- | ---
Example

    local_time_period(...)
      Parameters:
        local_date_time beginning
        local_date_time end

Create a period as [begin, end). If end is <= begin then the period will be defined as invalid.

    time_zone_ptr
      zone(new posix_time_zone("MST-07"));
    local_date_time
      beg(ptime(date(2005,Jan,1),hours(0)), zone);
    local_date_time
      end(ptime(date(2005,Feb,1),hours(0)), zone);
    // period for the entire month of Jan 2005
    local_time_period ltp(beg, end);

    local_time_period(...)
      Parameters:
        local_date_time beginning
        time_duration length

Create a period as [begin, begin+len) where end would be begin+len. If len is <= zero then the period will be defined as invalid.

    time_zone_ptr
      zone(new posix_time_zone("MST-07"));
    local_date_time
      beg(ptime(date(2005,Jan,1),hours(0)), zone);
    // period for the whole day of 2005-Jan-01
    local_time_period ltp(beg, hours(24));

    local_time_period(local_time_period rhs)

Copy constructor

    local_time_period ltp1(ltp);

Accessors

Syntax | Description
--- | ---
Example

    local_date_time begin()

Return first local_date_time of the period.

    time_zone_ptr
      zone(new posix_time_zone("MST-07"));
    local_date_time
      ldt((ptime(date(2005,Jan,1)),hours(0)), zone);
    local_time_period ltp(ldt, hours(2));
    ltp.begin(); // => 2005-Jan-01 00:00:00

    local_date_time last()

Return last local_date_time in the period

    time_zone_ptr
      zone(new posix_time_zone("MST-07"));
    local_date_time
      ldt((ptime(date(2005,Jan,1),hours(0))), zone);
    local_time_period ltp(ldt, hours(2));
    ltp.last(); // => 2005-Jan-01 01:59:59.999999999

    local_date_time end()

Return one past the last in period

    time_zone_ptr
      zone(new posix_time_zone("MST-07"));
    local_date_time
      ldt((ptime(date(2005,Jan,1),hours(0))), zone);
    local_time_period ltp(ldt, hours(2));
    ltp.end(); // => 2005-Jan-01 02:00:00

    time_duration length()

Return the length of the local_time period.

    time_zone_ptr
      zone(new posix_time_zone("MST-07"));
    local_date_time
      ldt((ptime(date(2005,Jan,1),hours(0))), zone);
    local_time_period ltp(ldt, hours(2));
    ltp.length(); // => 02:00:00

    bool is_null()

True if period is not well formed. eg: end less than or equal to begin.

    time_zone_ptr
      zone(new posix_time_zone("MST-07"));
    local_date_time
      beg((ptime(date(2005,Feb,1),hours(0))), zone);
    local_date_time
      end((ptime(date(2005,Jan,1),hours(0))), zone);
    local_time_period ltp(beg, end);
    ltp.is_null(); // => true

    bool contains(local_date_time)

True if local_date_time is within the period. Zero length periods cannot contain any points

    time_zone_ptr
      zone(new posix_time_zone("MST-07"));
    local_date_time
      beg((ptime(date(2005,Jan,1),hours(0))), zone);
    local_date_time
      end((ptime(date(2005,Feb,1),hours(0))), zone);
    local_time_period jan_mst(beg, end);

    local_date_time
    ldt((ptime(date(2005,Jan,15),hours(12))), zone);
    jan_mst.contains(ldt); // => true

    local_time_period zero(beg, beg);
    zero.contains(beg); // false

    bool contains(local_time_period)

True if period is within the period

    // using jan_mst period from previous example

    local_date_time
      beg((ptime(date(2005,Jan,7),hours(0))), zone);
    local_time_period ltp(beg, hours(24));

    jan_mst.contains(ltp); // => true

    bool intersects(local_time_period)

True if periods overlap

    // using jan_mst period from previous example

    local_date_time
      beg((ptime(date(2005,Jan,7),hours(0))), zone);
    local_date_time
      end((ptime(date(2005,Feb,7),hours(0))), zone);
    local_time_period ltp(beg, end);

    jan_mst.intersects(ltp); // => true

    local_time_period intersection(local_time_period)

Calculate the intersection of 2 periods. Null if no intersection.

    // using jan_mst period from previous example

    local_date_time
      beg((ptime(date(2005,Jan,7),hours(0))), zone);
    local_date_time
      end((ptime(date(2005,Feb,7),hours(0))), zone);
    local_time_period ltp(beg, end);

    local_time_period res(jan_mst.intersection(ltp));
    // res => 2005-Jan-07 00:00:00 through
    // 2005-Jan-31 23:59:59.999999999 (inclusive)

    local_time_period merge(local_time_period)

Returns union of two periods. Null if no intersection.

    // using jan_mst period from previous example

    local_date_time
      beg((ptime(date(2005,Jan,7),hours(0))), zone);
    local_date_time
      end((ptime(date(2005,Feb,7),hours(0))), zone);
    local_time_period ltp(beg, end);

    local_time_period res(jan_mst.merge(ltp));
    // res => 2005-Jan-07 00:00:00 through
    // 2005-Feb-06 23:59:59.999999999 (inclusive)

    local_time_period span(local_time_period)

Combines two periods and any gap between them such that begin = min(p1.begin, p2.begin) and end = max(p1.end , p2.end).

    // using jan_mst period from previous example

    local_date_time
      beg((ptime(date(2005,Mar,1),hours(0))), zone);
    local_date_time
      end((ptime(date(2005,Apr,1),hours(0))), zone);
    local_time_period mar_mst(beg, end);

    local_time_period res(jan_mst.span(mar_mst));
    // res => 2005-Jan-01 00:00:00 through
    // 2005-Mar-31 23:59:59.999999999 (inclusive)

    void shift(time_duration)

Add duration to both begin and end.

    local_date_time
      beg((ptime(date(2005,Mar,1),hours(0))), zone);
    local_date_time
      end((ptime(date(2005,Apr,1),hours(0))), zone);
    local_time_period mar_mst(beg, end);

    mar_mst.shift(hours(48));
    // mar_mst => 2005-Mar-03 00:00:00 through
    // 2005-Apr-02 23:59:59.999999999 (inclusive)

Operators

Syntax | Description
--- | ---
Example

    operator==, operator!=

Equality operators. Periods are equal if ltp1.begin == ltp2.begin && ltp1.last == ltp2.last

    if (ltp1 == ltp2) {...

    operator<

Ordering with no overlap. True if ltp1.end() less than ltp2.begin()

    if (ltp1 < ltp2) {...

    operator>

Ordering with no overlap. True if ltp1.begin() greater than ltp2.end()

    if (ltp1 > ltp2) {... etc

    operator<=, operator>=

Defined in terms of the other operators.