| Home | Libraries | People | FAQ | More

## Class template period

boost::date_time::period — Provides generalized period type useful in date-time systems.

## Synopsis

    // In header: <boost/date_time/period.hpp>

    template<typename point_rep, typename duration_rep>
    class period : private boost::less_than_comparable< period< point_rep, duration_rep >, boost::equality_comparable< period< point_rep, duration_rep > > >
    {
    public:
      // types
      typedef point_rep    point_type;
      typedef duration_rep duration_type;

      // construct/copy/destruct
      period(point_rep, point_rep);
      period(point_rep, duration_rep);

      // public member functions
      BOOST_CXX14_CONSTEXPR point_rep begin() const;
      BOOST_CXX14_CONSTEXPR point_rep end() const;
      BOOST_CXX14_CONSTEXPR point_rep last() const;
      BOOST_CXX14_CONSTEXPR duration_rep length() const;
      BOOST_CXX14_CONSTEXPR bool is_null() const;
      BOOST_CXX14_CONSTEXPR bool operator==(const period &) const;
      BOOST_CXX14_CONSTEXPR bool operator<(const period &) const;
      BOOST_CXX14_CONSTEXPR void shift(const duration_rep &);
      BOOST_CXX14_CONSTEXPR void expand(const duration_rep &);
      BOOST_CXX14_CONSTEXPR bool contains(const point_rep &) const;
      BOOST_CXX14_CONSTEXPR bool contains(const period &) const;
      BOOST_CXX14_CONSTEXPR bool intersects(const period &) const;
      BOOST_CXX14_CONSTEXPR bool is_adjacent(const period &) const;
      BOOST_CXX14_CONSTEXPR bool is_before(const point_rep &) const;
      BOOST_CXX14_CONSTEXPR bool is_after(const point_rep &) const;
      BOOST_CXX14_CONSTEXPR period intersection(const period &) const;
      BOOST_CXX14_CONSTEXPR period merge(const period &) const;
      BOOST_CXX14_CONSTEXPR period span(const period &) const;
    };

## Description

This template uses a class to represent a time point within the period and another class to represent a duration. As a result, this class is not appropriate for use when the number and duration representation are the same (eg: in the regular number domain).

A period can be specified by providing either the begining point and a duration or the begining point and the end point( end is NOT part of the period but 1 unit past it. A period will be "invalid" if either end_point <= begin_point or the given duration is <= 0. Any valid period will return false for is_null().

Zero length periods are also considered invalid. Zero length periods are periods where the begining and end points are the same, or, the given duration is zero. For a zero length period, the last point will be one unit less than the begining point.

In the case that the begin and last are the same, the period has a length of one unit.

The best way to handle periods is usually to provide a begining point and a duration. So, day1 + 7 days is a week period which includes all of the first day and 6 more days (eg: Sun to Sat).

### `period` public construct/copy/destruct

1.     period(point_rep first_point, point_rep end_point);

   create a period from begin to last eg: [begin,end)

   If end <= begin then the period will be invalid

2.     period(point_rep first_point, duration_rep len);

   create a period as [begin, begin+len)

   If len is <= 0 then the period will be invalid

### `period` public member functions

1.     BOOST_CXX14_CONSTEXPR point_rep begin() const;

   Return the first element in the period.

2.     BOOST_CXX14_CONSTEXPR point_rep end() const;

   Return one past the last element.

3.     BOOST_CXX14_CONSTEXPR point_rep last() const;

   Return the last item in the period.

4.     BOOST_CXX14_CONSTEXPR duration_rep length() const;

   Return the length of the period.

5.     BOOST_CXX14_CONSTEXPR bool is_null() const;

   True if period is ill formed (length is zero or less)

6.     BOOST_CXX14_CONSTEXPR bool operator==(const period & rhs) const;

   Equality operator.

7.     BOOST_CXX14_CONSTEXPR bool operator<(const period & rhs) const;

   Strict as defined by rhs.last <= lhs.last.

8.     BOOST_CXX14_CONSTEXPR void shift(const duration_rep & d);

   Shift the start and end by the specified amount.

9.     BOOST_CXX14_CONSTEXPR void expand(const duration_rep & d);

   Expands the size of the period by the duration on both ends.

   So before expand

               [-------]
       ^   ^   ^   ^   ^   ^  ^
       1   2   3   4   5   6  7

   After expand(2)

       [----------------------]
       ^   ^   ^   ^   ^   ^  ^
       1   2   3   4   5   6  7

10.     BOOST_CXX14_CONSTEXPR bool contains(const point_rep & point) const;

    True if the point is inside the period, zero length periods contain no points.

11.     BOOST_CXX14_CONSTEXPR bool contains(const period & other) const;

    True if this period fully contains (or equals) the other period.

12.     BOOST_CXX14_CONSTEXPR bool intersects(const period & other) const;

    True if the periods overlap in any way.

13.     BOOST_CXX14_CONSTEXPR bool is_adjacent(const period & other) const;

    True if periods are next to each other without a gap.

14.     BOOST_CXX14_CONSTEXPR bool is_before(const point_rep & point) const;

    True if all of the period is prior to the passed point or end <= t.

15.     BOOST_CXX14_CONSTEXPR bool is_after(const point_rep & point) const;

    True if all of the period is prior or t < start.

16.     BOOST_CXX14_CONSTEXPR period intersection(const period & other) const;

    Returns the period of intersection or invalid range no intersection.

17.     BOOST_CXX14_CONSTEXPR period merge(const period & other) const;

    Returns the union of intersecting periods – or null period.

18.     BOOST_CXX14_CONSTEXPR period span(const period & other) const;

    Combine two periods with earliest start and latest end.

    Combines two periods and any gap between them such that start = min(p1.start, p2.start) end = max(p1.end , p2.end)

               [---p1---)
                              [---p2---)
        result:
               [-----------p3----------)