Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of boost. Click here for the latest Boost documentation.
PrevUpHomeNext

Class template period

boost::date_time::period —

Provides generalized period type useful in date-time systems.

Synopsis

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 &) ;
  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 starting point and a duration or the starting point and the end point( end is NOT part of the period but 1 unit past it. A period will be "invalid" if either start_point >= end_point or the given duration is < 0. Any valid period will return false for is_null().

Zero length periods are considered valid. In this case the start point is exactly 1 unit less than the end point, in other words start is equal to last.

In the case that the begin and last are the same, the period has a length of zero units. For example, suppose this is a period of days. That is, each time-point represents a single day. If the start and the last is the same day then the period is zero length.

The best way to handle periods is usually to provide a start 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 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.

  2. point_rep end() const;

    Return one past the last element.

  3. point_rep last() const;

    Return the last item in the period.

  4. duration_rep length() const;

    Return the length of the period.

  5. bool is_null() const;

    True if period is ill formed (length less than zero).

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

    Equality operator.

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

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

  8. void shift(const duration_rep & d) ;

    Shift the start and end by the specified amount.

  9. bool contains(const point_rep & point) const;

    True if the point is inside the period.

  10. bool contains(const period & other) const;

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

  11. bool intersects(const period & other) const;

    True if the periods overlap in any way.

  12. bool is_adjacent(const period & other) const;

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

  13. bool is_before(const point_rep & point) const;

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

  14. bool is_after(const point_rep & point) const;

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

  15. period intersection(const period & other) const;

    Returns the period of intersection or invalid range no intersection.

  16. period merge(const period & other) const;

    Returns the union of intersecting periods -- or null period.

  17. 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----------) 
       *
    
Copyright © 2001-2004 CrystalClear Software, Inc

PrevUpHomeNext