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.last(); // --> 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. [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 left out when 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 left out when 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.