# Date

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

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 from another date. Techniques for creating dates include reading the current date from the clock, using date iterators, and date algorithms or generators.

Internally boost::gregorian::date is stored as a 32 bit integer type. The class is specifically designed to NOT contain virtual functions. This design allows for efficient calculation and memory usage with large collections of dates.

The construction of a date validates all input so that it is not possible to construct an 'invalid' date. That is 2001-Feb-29 cannot be constructed as a date. Various exceptions derived from std::out_of_range are thrown to indicate which aspect of the date input is invalid. Note that the special value not-a-date-time can be used as 'invalid' or 'null' date if so desired.

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, greg_month, greg_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(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(std::string)

From ISO 8601 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 (Sunday, Monday, etc.)

    date d(2002,Jan,10);
    d.day_of_week(); // --> Thursday

    greg_day_of_year day_of_year() const

Get the day of the year. Number from 1 to 366

    date d(2000,Jan,10);
    d.day_of_year(); // --> 10

    date end_of_month() const

Returns a `date` object set to the last day of the calling objects current month.

    date d(2000,Jan,10);
    d.end_of_month(); // --> 2000-Jan-31

    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(pos_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

    bool is_special() const

Returns true if date is any `special_value`

    date d(pos_infin);
    date d2(not_a_date_time);
    date d3(2005,Mar,1);
    d.is_special(); // --> true
    d2.is_special(); // --> true
    d3.is_special(); // --> false

    special_value as_special() const

Returns represented `special_value` or `not_special` if the represented date is a normal date.

    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.

    date end_of_month() const

Returns the last day of the month for the date.

    date d(2000,Feb,1);
    //gets Feb 29 -- 2000 was leap year
    date eom = d.end_of_month();

Convert to String

Syntax | Description
--- | ---
Example

    std::string to_simple_string(date d)

To `YYYY-mmm-DD` string where `mmm` is a 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>>

Stream input operator. Note: As of version 1.33, streaming operations have been greatly improved. See Date Time IO System for details on exceptions and error conditions.

    date d(not_a_date_time);
    stringstream ss("2002-Jan-01");
    ss >> d;

    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 substracting 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;

Struct tm Functions

Functions for converting a `date` object to, and from, a `tm` struct are provided.

Syntax | Description
--- | ---
Example

    tm to_tm(date)

A function for converting a `date` object to a `tm` struct. The fields: `tm_hour`, `tm_min`, and `tm_sec` are set to zero. The `tm_isdst` field is set to -1.

    date d(2005,Jan,1);
    tm d_tm = to_tm(d);
    /* tm_year => 105
       tm_mon  => 0
       tm_mday => 1
       tm_wday => 6 (Saturday)
       tm_yday => 0
       tm_hour => 0
       tm_min  => 0
       tm_sec  => 0
       tm_isdst => -1 */

    date date_from_tm(tm datetm)

A function for converting a `tm` struct to a `date` object. The fields: `tm_wday` , `tm_yday` , `tm_hour`, `tm_min`, `tm_sec`, and `tm_isdst` are ignored.

    tm d_tm;
    d_tm.tm_year = 105;
    d_tm.tm_mon  = 0;
    d_tm.tm_mday = 1;
    date d = date_from_tm(d_tm);
    // d => 2005-Jan-01