posix_time::time_period Documentation

# posix_time::time_period

Overall Index -- Gregorian Index -- Posix Time Index

Time Period Documentation

Header -- Construction -- 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.

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 begin, ptime end) | Create a period as [begin, end). If last is <= begin then the period will be defined as null. | date d(2002,Jan,01); ptime t(d, seconds(10)); //10 sec after midnight time_period tp(t, hours(3));
time_period(ptime start, time_duration len) | Create a period as [begin, begin+len). If len is <= zero then the period will be defined as null. | 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(time_period rhs) | Copy constructor | time_period tp1(tp)

## Accessors

Syntax | Description | Example
ptime begin() const | 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() const | 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() const | 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.last() --> 2002-Jan-01 10:00:00
time_duration length() const | 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() const | True if period is not well formed. eg: start less than end |
bool contains(ptime) const | True if ptime is within 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 ptime t3(d, hours(2)); //2 hours after midnight time_period tp(t1, t2); tp.contains(t3) --> true
bool contains(time_period) const | 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) const | 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) const | Calculate the intersection of 2 periods. Null if no intersection. |
time_period merge(time_period) const | Returns union of two periods. Null if no intersection. |
time_period span(time_period) const | Combines two periods and any gap between them such that start = min(p1.start, p2.start) and end = max(p1.end , p2.end). |
time_period shift(date_duration) | Add duration to both start and 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. | [2002-Jan-01 01:25:10.000000001/2002-Jan-31 01:25:10.123456789]

## 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. | [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. |