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

Click here to view the latest version of this page.
PrevUpHomeNext

Gregorian

Date Class
Date Duration (aka Days)
Date Period
Date Iterators
Date Generators/Algorithms
Gregorian Calendar
Class day_clock

Gregorian Date System

Introduction -- Usage Examples

Introduction

The gregorian date system provides a date programming system based the Gregorian Calendar. The first introduction of the Gregorian calendar was in 1582 to fix an error in the Julian Calendar. However, many local jurisdictions did not adopt this change until much later. Thus there is potential confusion with historical dates.

The implemented calendar is a "propleptic Gregorian calendar" which extends dates back prior to the Gregorian Calendar's first adoption in 1582. The current implementation supports dates in the range 1400-Jan-01 to 10000-Jan-01. Many references will represent dates prior to 1582 using the Julian Calendar, so caution is in order if accurate calculations are required on historic dates. See Calendrical Calculations by Reingold & Dershowitz for more details. Date information from Calendrical Calculations has been used to cross-test the correctness of the Gregorian calendar implementation.

All types for the gregorian system are found in namespace boost::gregorian. The library supports a convenience header boost/date_time/gregorian/gregorian_types.hpp that will include all the classes of the library with no input/output dependency. Another header boost/date_time/gregorian/gregorian.hpp will include the types and the input/output code.

The class boost::gregorian::date is the primary temporal type for users. If you are interested in learning about writing programs do specialized date calculations such as finding the "first sunday in april" see the date generators and algorithms page.

Usage Examples

Example Description
Days AliveDays Till New Year Simple date arithmetic. Retrieve current day from clock.
Dates as strings Simple parsing and formatting of dates from/to strings
Date Period Calculations See if a date is in a set of date periods (eg: is it a holiday/weekend)
Print a month Small utility program which prints out all the days in a month from command line. Need to know if 1999-Jan-1 was a Friday or a Saturday? This program shows how to do it.
Print Holidays Uses date generators to convert abstract specification into concrete set of dates.

Date Class

Introduction -- Header -- Construction -- Construct from String -- Construct from Clock -- Accessors -- Convert to String -- Operators

Introduction

The class boost::gregorian::date is the primary interface for date programming. In general, the date class is immutable once constructed although it does allow assignment.

Other techniques for creating dates include date iterators and date algorithms or generators.

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(greg_year year, greg_month month, greg_day day) Construct from parts of date. Throws bad_year, bad_day_of_month, or bad_day_month (derivatives of std::out_of_range) if the year, month or day are out of range. date d(2002,Jan,10)
date(date d) Copy constructor date d1(d)
date(special_values sv) Constructor for infinities, not-a-date-time, max_date_time, and min_date_time date d1(neg_infin); date d2(pos_infin); date d3(not_a_date_time); date d4(max_date_time); date d5(min_date_time);
date; Default constructor. Creates a date object initialized to not_a_date_time. NOTE: this constructor can be disabled by defining DATE_TIME_NO_DEFAULT_CONSTRUCTOR (see compiler_config.hpp) date d; // d => not_a_date_time

Construct from String

Syntax Description Example
date from_string(const std::string&) From delimited date string where with order year-month-day eg: 2002-1-25 std::string ds("2002/1/25"); date d(from_string(ds))
date from_undelimited_string(const std::string&) From iso type date string where with order year-month-day eg: 20020125 std::string ds("20020125"); date d(from_undelimited_string(ds))

Construct from Clock

Syntax Description Example
day_clock::local_day() Get the local day based on the time zone settings of the computer. date d(day_clock::local_day())
day_clock::universal_day() Get the UTC day. date d(day_clock::universal_day())

Accessors

Syntax Description Example
greg_year year() const Get the year part of the date. date d(2002,Jan,10); d.year() --> 2002;
greg_month month() const Get the month part of the date. date d(2002,Jan,10); d.month() --> 1;
greg_day day() const Get the day part of the date. date d(2002,Jan,10); d.day() --> 10;
greg_ymd year_month_day() const Return a year_month_day struct. More efficient when all 3 parts of the date are needed. date d(2002,Jan,10); date::ymd_type ymd = d.year_month_day(); ymd.year --> 2002, ymd.month --> 1, ymd.day --> 10
greg_day_of_week day_of_week() const Get the day of the week (eg: Sunday, Monday, etc. date d(2002,Jan,10); d.day() --> Thursday;
bool is_infinity() const Returns true if date is either positive or negative infinity date d(pos_infin); d.is_infinity() --> true;
bool is_neg_infinity() const Returns true if date is negative infinity date d(neg_infin); d.is_neg_infinity() --> true;
bool is_pos_infinity() const Returns true if date is positive infinity date d(neg_infin); d.is_pos_infinity() --> true;
bool is_not_a_date() const Returns true if value is not a date date d(not_a_date_time); d.is_not_a_date() --> true;
long modjulian_day() const Returns the modified julian day for the date.
long julian_day() const Returns the julian day for the date.
int week_number() const Returns the ISO 8601 week number for the date.

Convert to String

Syntax Description Example
std::string to_simple_string(date d) To YYYY-mmm-DD string where mmm 3 char month name. 2002-Jan-01
std::string to_iso_string(date d) To YYYYMMDD where all components are integers. 20020131
std::string to_iso_extended_string(date d) To YYYY-MM-DD where all components are integers. 2002-01-31

Operators

Syntax Description Example
operator<< Stream output operator date d(2002,Jan,1) std::cout << d << std::endl;
operator==, operator!=, operator>, operator< operator>=, operator<= A full complement of comparison operators d1 == d2, etc
date operator+(date_duration) const Return a date adding a day offset date d(2002,Jan,1); date_duration dd(1); date d2 = d + dd;
date operator-(date_duration) const Return a date by adding a day offset date d(2002,Jan,1); date_duration dd(1); date d2 = d - dd;
date_duration operator-(date) const Return a date duration by subtracting two dates date d1(2002,Jan,1); date d2(2002,Jan,2); date_duration dd = d2-d1;
top

Date Duration (aka Days)

Introduction -- Header -- Construction -- Operators

Introduction

As of version 1_32 the date_duration class has been typdefed as days in the boost::gregorian namespace. Throughout the examples you will find days used instead of date_duration.

The class boost::gregorian::date_duration is a simple day count used for arithmetic with gregorian::date. A duration can be either positive or negative.

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_duration(long) Create a duration count. date_duration dd(3); //3 days

Accessors

Syntax Description Example
long days() const Get the day count. date_duration dd(3); dd.days() --> 3
bool is_negative() const True if number of days is less than zero. date_duration dd(-1); dd.is_negative() --> true
static date_duration unit() Return smallest possible unit of duration type. date_duration::unit() --> date_duration(1)

Operators

Syntax Description Example
operator==, operator!=, operator>, operator< operator>=, operator<= A full complement of comparison operators dd1 == dd2, etc
date_duration operator+(date_duration) const Add date durations. date_duration dd1(3); date_duration dd2(5); date_duration dd3 = dd1 + dd2;
date_duration operator-(date_duration) const Subtract durations. date_duration dd1(3); date_duration dd2(5); date_duration dd3 = dd1 - dd2;
top

Date Period

Introduction -- Header -- Construction -- 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 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.hull(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

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==, 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
top

Date Iterators

Introduction -- Header -- Overview

Introduction

Date iterators provide a standard mechanism for iteration through dates. Date iterators are a model of Input Iterator and can be used to populate collections with dates and other date generation tasks. For example, the print month example iterates through all the days in a month and prints them.

All of the iterators here derive from boost::gregorian::date_iterator.

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
    

Overview

Class Construction Parameters Description
date_iterator Common base class for all day level iterators.
day_iterator date start_date, int day_count=1 Iterate day_count days at a time.
week_iterator date start_date, int week_offset=1 Iterate week_offset weeks at a time.
month_iterator date start_date, int month_offset=1 Iterate month_offset months. There are special rules for handling the end of the month. These are: if start date is last day of the month, always adjust to last day of the month. If date is beyond the end of the month (eg: jan 31 + 1 month) adjust back to end of month.
year_iterator date start_date, int year_offset=1 Iterate year_offset years. The year_iterator will always land on the day of the date parameter except when date is Feb 28 in a non-leap year. In this case the iterator will return Feb 29 for leap years (eg: 2003-Feb-28, 2004-Feb-29, 2005-Feb-28).
top

Date Generators/Algorithms

Date Generators/Algorithms

Introduction -- Header -- Class Overview -- Function Overview

Introduction

Date algorithms or generators are tools for generating other dates or schedules of dates. A generator function starts with some part of a date such as a month and day and is supplied another part to then generate a concrete date. This allows the programmer to represent concepts such as "The first Sunday in February" and then create a concrete set of dates when provided with one or more years. Note: As of boost version 1_31_0, date generator names have been changed. Old names are still available but are no longer documented and may someday be deprecated

Also provided are stand-alone functions for generating a date, or calculation a duration of days. These functions take a date object and a weekday object as parameters.

All date generator classes and functions are in the boost::gregorian namespace.

The print holidays example shows a detailed usage example.

Header

#include "boost/date_time/date_generators.hpp"

Overview

Class Construction Parameters get_date Parameter Description Example
year_based_generator abstract base class greg_year year A unifying date_generator base type for: partial_date, nth_day_of_the_week_in_month, first_day_of_the_week_in_month, and last_day_of_the_week_in_month The print holidays example shows a detailed usage example.
last_day_of_the_week_in_month greg_weekday or weekday, greg_month or month greg_year or year Calculate something like last Monday of January last_day_of_the_week_in_month lwdm(Monday,Jan); date d = lwdm.get_date(2002);//2002-Jan-28
first_day_of_the_week_in_month greg_weekday or weekday, greg_month or month greg_year or year Calculate something like first Monday of January first_day_of_the_week_in_month fdm(Monday,Jan); date d = fdm.get_date(2002);//2002-Jan-07
partial_date greg_day, greg_month or month greg_year Generates a date by applying the year to the given month and day. partial_date pd(1,Jan); date d = pd.get_date(2002);//2002-Jan-01
first_day_of_the_week_after greg_weekday or weekday date Calculate something like First Sunday after Jan 1,2002 first_day_of_the_week_after fdaf(Monday); date d = fdaf.get_date(date(2002,Jan,1));//2002-Jan-07
first_day_of_the_week_before greg_weekday or weekday date Calculate something like First Monday before Feb 1,2002 first_day_of_the_week_before fdbf(Monday); date d = fdbf.get_date(date(2002,Feb,1));//2002-Jan-28

Function Overview

Function Prototype Description Example
days days_until_weekday (const date&, const greg_weekday&) Calculates the number of days from given date until given weekday. date d(2004,Jun,1); // Tuesday greg_weekday gw(Friday); days_until_weekday(d, gw); // 3 days
days days_before_weekday (const date&, const greg_weekday&) Calculates the number of day from given date to previous given weekday. date d(2004,Jun,1); // Tuesday greg_weekday gw(Friday); days_before_weekday(d, gw); // 4 days
date next_weekday (const date&, const greg_weekday&) Generates a date object representing the date of the following weekday from the given date. date d(2004,Jun,1); // Tuesday greg_weekday gw(Friday); next_weekday(d, gw); // 2004-Jun-4
date previous_weekday (const date&, const greg_weekday&) Generates a date object representing the date of the previous weekday from the given date. date d(2004,Jun,1); // Tuesday greg_weekday gw(Friday); previous_weekday(d, gw); // 2004-May-28
top

Gregorian Calendar

Introduction -- Header -- Functions

Introduction

The class boost::gregorian::gregorian_calendar implements the functions necessary to create the gregorian date system. It converts to the year-month-day form of a date to a day number representation and back.

For most purposes this class is simply accessed by gregorian::date and is not used directly by the user. However, there are useful functions that might be of use such as the end_of_month_day function.

The print month example demonstrates this.

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
    

Functions

Syntax Description Example
static short day_of_week(ymd_type) Return the day of the week (0==Sunday, 1==Monday, etc) See also gregorian::date day_of_week
static date_int_type day_number(ymd_type) Convert a ymd_type into a day number. The day number is an absolute number of days since the epoch start.
static short end_of_month_day(year_type, month_type) Given a year and month determine the last day of the month.
static ymd_type from_day_number(date_int_type) Convert a day number to a ymd struct.
static bool is_leap_year(year_type) Returns true if specified year is a leap year. gregorian_calendar::is_leap_year(2000) --> true
top

Class day_clock

Class day_clock
top
Copyright 2001-2004 CrystalClear Software, Inc

PrevUpHomeNext