# Time Period

Introduction -- Header -- Construction -- Mutators -- Accessors -- Conversion To String -- Operators

Introduction

The class boost::posix_time::time_period provides direct representation for ranges between two 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.

The time periods example provides an example of using time periods.

Header

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

Construction

Syntax | Description
--- | ---
Example

    time_period(ptime,
                ptime)

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

    date d(2002,Jan,01);
    ptime t1(d, seconds(10)); //10 sec after midnight
    ptime t2(d, hours(10)); //10 hours after midnight
    time_period tp(t1, t2);

    time_period(ptime,
                time_duration)

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.

    date d(2002,Jan,01);
    ptime t(d, seconds(10)); //10 sec after midnight
    time_period tp(t, hours(3));

    time_period(time_period rhs)

Copy constructor

    time_period tp1(tp);

Mutators

Syntax | Description
--- | ---
Example

    time_period shift(time_duration)

Add duration to both begin and end.

    time_period tp(ptime(date(2005,Jan,1),hours(1)), hours(2));
    tp.shift(minutes(5));
    // tp == 2005-Jan-01 01:05:00 to 2005-Jan-01 03:05:00

    time_period expand(days)

Subtract duration from begin and add duration to end.

    time_period tp(ptime(date(2005,Jan,1),hours(1)), hours(2));
    tp.expand(minutes(5));
    // tp == 2005-Jan-01 00:55:00 to 2005-Jan-01 03:05:00

Accessors

Syntax | Description
--- | ---
Example

    ptime begin()

Return first time of period.

    date d(2002,Jan,01);
    ptime t1(d, seconds(10)); //10 sec after midnight
    ptime t2(d, hours(10)); //10 hours after midnight
    time_period tp(t1, t2);
    tp.begin(); // --> 2002-Jan-01 00:00:10

    ptime last()

Return last time in the period

    date d(2002,Jan,01);
    ptime t1(d, seconds(10)); //10 sec after midnight
    ptime t2(d, hours(10)); //10 hours after midnight
    time_period tp(t1, t2);
    tp.last();// --> 2002-Jan-01 09:59:59.999999999

    ptime end()

Return one past the last in period

    date d(2002,Jan,01);
    ptime t1(d, seconds(10)); //10 sec after midnight
    ptime t2(d, hours(10)); //10 hours after midnight
    time_period tp(t1, t2);
    tp.end(); // --> 2002-Jan-01 10:00:00

    time_duration length()

Return the length of the time period.

    date d(2002,Jan,01);
    ptime t1(d); //midnight
    time_period tp(t1, hours(1));
    tp.length() --> 1 hour

    bool is_null()

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

    date d(2002,Jan,01);
    ptime t1(d, hours(12)); // noon on Jan 1st
    ptime t2(d, hours(9)); // 9am on Jan 1st
    time_period tp(t1, t2);
    tp.is_null(); // true

    bool contains(ptime)

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

    date d(2002,Jan,01);
    ptime t1(d, seconds(10)); //10 sec after midnight
    ptime t2(d, hours(10)); //10 hours after midnight
    ptime t3(d, hours(2)); //2 hours after midnight
    time_period tp(t1, t2);
    tp.contains(t3); // true
    time_period tp2(t1, t1);
    tp2.contains(t1); // false

    bool contains(time_period)

True if period is within the period

    time_period tp1(ptime(d,hours(1)),
                    ptime(d,hours(12)));
    time_period tp2(ptime(d,hours(2)),
                    ptime(d,hours(4)));
    tp1.contains(tp2); // --> true
    tp2.contains(tp1); // --> false

    bool intersects(time_period)

True if periods overlap

    time_period tp1(ptime(d,hours(1)),
                    ptime(d,hours(12)));
    time_period tp2(ptime(d,hours(2)),
                    ptime(d,hours(4)));
    tp2.intersects(tp1); // --> true

    time_period intersection(time_period)

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

    time_period merge(time_period)

Returns union of two periods. Null if no intersection.

    time_period span(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).

Conversion To String

Syntax | Description
--- | ---
Example

    std::string
      to_simple_string(time_period dp)

To `[YYYY-mmm-DD hh:mm:ss.fffffffff/YYYY-mmm-DD hh:mm:ss.fffffffff]` string where `mmm` is 3 char month name and the fractional seconds are only included if non-zero.

    [2002-Jan-01 01:25:10.000000001/
                    2002-Jan-31 01:25:10.123456789]
    // string occupies one line

Operators

Syntax | Description
--- | ---
Example

    operator<<

Output streaming operator for time duration. Uses facet to output [date time_of_day/date time_of_day]. The default is format is `[YYYY-mmm-DD hh:mm:ss.fffffffff/YYYY-mmm-DD hh:mm:ss.fffffffff]` string where `mmm` is 3 char month name and the fractional seconds are only included if non-zero.

    [2002-Jan-01 01:25:10.000000001/ \
        2002-Jan-31 01:25:10.123456789]

    operator>>

Input streaming operator for time duration. Uses facet to read [date time_of_day/date time_of_day]. The default is format is `[YYYY-mmm-DD hh:mm:ss.fffffffff/YYYY-mmm-DD hh:mm:ss.fffffffff]` string where `mmm` is 3 char month name and the fractional seconds are only included if non-zero.

    [2002-Jan-01 01:25:10.000000001/ \
        2002-Jan-31 01:25:10.123456789]

    operator==, operator!=

Equality operators. Periods are equal if p1.begin == p2.begin && p1.last == p2.last

    if (tp1 == tp2) {...

    operator<

Ordering with no overlap. True if tp1.end() less than tp2.begin()

    if (tp1 < tp2) {...

    operator>

Ordering with no overlap. True if tp1.begin() greater than tp2.end()

    if (tp1 > tp2) {... etc

    operator<=, operator>=

Defined in terms of the other operators.