gregorian::date_period Documentation

# gregorian::date_period

Overall Index -- Gregorian Index -- Posix Time Index

Date Period Documentation

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

## Introduction

The class boost::gregorian::date_period provides direct representation for ranges between two dates. Periods provide the ability to simplify some types of calculations by simplifying the conditional logic of the program. For example, testing if a date is within an irregular schedule such as a weekend or holiday can be accomplished using collections of date periods. This is facilitated by several methods that allow evaluation if a date_period intersects with another date period, and to generate the period resulting from the intersection. The period calculation example provides an example of this.

Date periods used in combination with infinity values have the ability to represent complex concepts such as 'until further notice'.

## Header

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

## Construction

Syntax | Description | Example
date_period(date begin, date end) | Create a period as [begin, end). If last is <= begin then the period will be defined as null. | date_period dp(date(2002,Jan,10), date(2002,Jan,12));
date_period(date start, date_duration len) | Create a period as [begin, begin+len). If len is <= zero then the period will be defined as null. | date_period dp(date(2002,Jan,10), date_duration(2));
date_period(date_period rhs) | Copy constructor | date_period dp1(dp)

## Accessors

Syntax | Description | Example
date begin() const | Return first day of period. | date_period dp(date(2002,Jan,1), date(2002,Jan,10)); dp.begin() --> 2002-Jan-01
date last() const | Return last date in the period | date_period dp(date(2002,Jan,1), date(2002,Jan,10)); dp.last() --> 2002-Jan-09
date end() const | Return one past the last in period | date_period dp(date(2002,Jan,1), date(2002,Jan,10)); dp.end() --> 2002-Jan-10
date_duration length() const | Return the length of the date_period | date_period dp(date(2002,Jan,1), date_duration(2)); dp.length() --> 2
bool is_null() const | True if period is not well formed. eg: start less than end | date_period dp(date(2002,Jan,10), date(2002,Jan,1)); dp.begin() --> true
bool contains(date) const | True if date is within the period | date_period dp(date(2002,Jan,1), date(2002,Jan,10)); dp.contains(date(2002,Jan,2)) --> true
bool contains(date_period) const | True if date period is within the period | date_period dp1(date(2002,Jan,1), date(2002,Jan,10)); date_period dp2(date(2002,Jan,2), date(2002,Jan,3)); dp1.contains(dp2) --> true dp2.contains(dp1) --> false
bool intersects(date_period) const | True if periods overlap | date_period dp1(date(2002,Jan,1), date(2002,Jan,10)); date_period dp2(date(2002,Jan,2), date(2002,Jan,3)); dp2.intersects(dp1) --> true
date_period intersection(date_period) const | Calculate the intersection of 2 periods. Null if no intersection. | date_period dp1(date(2002,Jan,1), date(2002,Jan,10)); date_period dp2(date(2002,Jan,2), date(2002,Jan,3)); dp2.intersection(dp1) --> dp2
date_period is_adjacent(date_period) const | Check if two periods are adjacent, but not overlapping. | date_period dp1(date(2002,Jan,1), date(2002,Jan,3)); date_period dp2(date(2002,Jan,3), date(2002,Jan,10)); dp2.is_adjacent(dp1) --> true
date_period is_after(date) const | Determine the period is after a given date. | date_period dp1(date(2002,Jan,10), date(2002,Jan,30)); date d(2002,Jan,3); dp1.is_after(d) --> true
date_period is_before(date) const | Determine the period is before a given date. | date_period dp1(date(2002,Jan,1), date(2002,Jan,3)); date d(2002,Jan,10); dp1.is_before(d) --> true
date_period merge(date_period) const | Returns union of two periods. Null if no intersection. | date_period dp1(date(2002,Jan,1), date(2002,Jan,10)); date_period dp2(date(2002,Jan,9), date(2002,Jan,31)); dp2.merge(dp1) --> 2002-Jan-01/2002-Jan-31
date_period span(date_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) | date_period dp1(date(2002,Jan,1), date(2002,Jan,5)); date_period dp2(date(2002,Jan,9), date(2002,Jan,31)); dp2.span(dp1) --> 2002-Jan-01/2002-Jan-31
date_period shift(date_duration) | Add duration to both start and end. | date_period dp1(date(2002,Jan,1), date(2002,Jan,10)); dp1.shift(date_duration(1)); --> 2002-Jan-02/2002-Jan-11

## Conversion To String

Syntax | Description | Example
std::string to_simple_string(date_period dp) | To [YYYY-mmm-DD/YYYY-mmm-DD] string where mmm is 3 char month name. | [2002-Jan-01/2002-Jan-31]

## Operators

Syntax | Description | Example
operator<< | ostream operator for date_period. Uses facet to format time points. Typical output: [2002-Jan-01/2002-Jan-31]. | std::cout << dp << std::endl;
operator==, operator!=, operator>, operator< | A full complement of comparison operators | dp1 == dp2, etc
operator< | True if dp1.end() less than dp2.begin() | dp1 < dp2, etc
operator> | True if dp1.begin() greater than dp2.end() | dp1 > dp2, etc