CLASS TEMPLATE PER(3)

NAME
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 {
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
  point_rep begin() const;
  point_rep end() const;
  point_rep last() const;
  duration_rep length() const;
  bool is_null() const;
  bool operator==(const period &) const;
  bool operator<(const period &) const;
  void shift(const duration_rep &);
  void expand(const duration_rep &);
  bool contains(const point_rep &) const;
  bool contains(const period &) const;
  bool intersects(const period &) const;
  bool is_adjacent(const period &) const;
  bool is_before(const point_rep &) const;
  bool is_after(const point_rep &) const;
  period intersection(const period &) const;
  period merge(const period &) const;
  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.

    point_rep begin() const;
    Return the first element in the period. .RE

        2.

        point_rep end() const;
        Return one past the last element. .RE

            3.

            point_rep last() const;
            Return the last item in the period. .RE

                4.

                duration_rep length() const;
                Return the length of the period. .RE

                    5.

                    bool is_null() const;
                    True if period is ill formed (length is zero or less) .RE

                        6.

                        bool operator==(const period & rhs) const;
                        Equality operator. .RE

                            7.

                            bool operator<(const period & rhs) const;
                            Strict as defined by rhs.last <= lhs.last. .RE

                                8.

                                void shift(const duration_rep & d);
                                Shift the start and end by the specified amount. .RE

                                    9.

                                    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.

                                    bool contains(const point_rep & point) const;
                                    True if the point is inside the period, zero length periods contain no points. .RE

                                        11.

                                        bool contains(const period & other) const;
                                        True if this period fully contains (or equals) the other period. .RE

                                            12.

                                            bool intersects(const period & other) const;
                                            True if the periods overlap in any way. .RE

                                                13.

                                                bool is_adjacent(const period & other) const;
                                                True if periods are next to each other without a gap. .RE

                                                    14.

                                                    bool is_before(const point_rep & point) const;
                                                    True if all of the period is prior to the passed point or end <= t. .RE

                                                        15.

                                                        bool is_after(const point_rep & point) const;
                                                        True if all of the period is prior or t < start. .RE

                                                            16.

                                                            period intersection(const period & other) const;
                                                            Returns the period of intersection or invalid range no intersection. .RE

                                                                17.

                                                                period merge(const period & other) const;
                                                                Returns the union of intersecting periods -- or null period. .RE

                                                                    18.

                                                                    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----------)
                                                                           *