# Date Period

Introduction -- Header -- Construction -- Mutators -- Accessors -- Convert 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 date period calculation example provides an example of this.

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.

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, date)

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

    date_period dp(date(2002,Jan,10),
                   date(2002,Jan,12));

    date_period(date, days)

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

    date_period dp(date(2002,Jan,10),
                   days(2));

    date_period(date_period)

Copy constructor

    date_period dp1(dp);

Mutators

Syntax | Description
--- | ---
Example

    date_period shift(days)

Add duration to both begin and end.

    date_period dp(date(2005,Jan,1), days(3));
    dp.shift(days(3));
    // dp == 2005-Jan-04 to 2005-Jan-07

    date_period expand(days)

Subtract duration from begin and add duration to end.

    date_period dp(date(2005,Jan,2), days(2));
    dp.expand(days(1));
    // dp == 2005-Jan-01 to 2005-Jan-04

Accessors

Syntax | Description
--- | ---
Example

    date begin()

Return first day of period.

    date_period dp(date(2002,Jan,1),
                   date(2002,Jan,10));
    dp.begin() --> 2002-Jan-01

    date last()

Return last date in the period

    date_period dp(date(2002,Jan,1),
                   date(2002,Jan,10));
    dp.last() --> 2002-Jan-09

    date end()

Return one past the last in period

    date_period dp(date(2002,Jan,1),
                   date(2002,Jan,10));
    dp.end() --> 2002-Jan-10

    days length()

Return the length of the date_period

    date_period dp(date(2002,Jan,1),
                   days(2));
    dp.length() --> 2

    bool is_null()

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

    date_period dp(date(2002,Jan,10),
                   date(2002,Jan,1));
    dp.is_null() --> true

    bool contains(date)

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

    date d(2002,Jan,1);
    date_period dp(d, date(2002,Jan,10));
    dp.contains(date(2002,Jan,2));// true
    date_period dp2(d, d);
    dp.contains(date(2002,Jan,1));// false

    bool contains(date_period)

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)

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)

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)

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)

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)

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)

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)

Combines two periods and any gap between them such that begin = min(p1.begin, p2.begin) 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(days)

Add duration to both begin and end.

    date_period dp1(date(2002,Jan,1),
                    date(2002,Jan,10));
    dp1.shift(days(1));
    // 2002-Jan-02/2002-Jan-11

    date_period expand(days)

Subtract duration from begin and add duration to end.

    date_period dp1(date(2002,Jan,4),
                    date(2002,Jan,10));
    dp1.expand(days(2));
    // 2002-Jan-02/2002-Jan-12

Convert 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>>

istream operator for date_period. Uses facet to parse time points.

    "[2002-Jan-01/2002-Jan-31]"

    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