525 lines
16 KiB
XML
525 lines
16 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
|
|
"../../../tools/boostbook/dtd/boostbook.dtd">
|
|
|
|
<!-- Copyright (c) 2001-2007 CrystalClear Software, Inc.
|
|
Subject to the Boost Software License, Version 1.0.
|
|
(See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)
|
|
-->
|
|
|
|
<section id="date_time.gregorian.date_class">
|
|
<title>Date</title>
|
|
|
|
<link linkend="date_intro">Introduction</link> --
|
|
<link linkend="date_header">Header</link> --
|
|
<link linkend="date_construction">Construction</link> --
|
|
<link linkend="date_construct_from_string">Construct from String</link> --
|
|
<link linkend="date_construct_from_clock">Construct from Clock</link> --
|
|
<link linkend="date_accessors">Accessors</link> --
|
|
<link linkend="date_convert_to_string">Convert to String</link> --
|
|
<link linkend="date_operators">Operators</link> --
|
|
<link linkend="date_tm_funcs">Struct tm Functions</link>
|
|
|
|
<anchor id="date_intro" />
|
|
<bridgehead renderas="sect3">Introduction</bridgehead>
|
|
<para>
|
|
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
|
|
<link linkend="date_construct_from_clock">current date from the clock</link>,
|
|
using <link linkend="date_time.gregorian.date_iterators">date iterators</link>, and
|
|
<link linkend="date_time.gregorian.date_algorithms">date algorithms or generators</link>.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<anchor id="date_header" />
|
|
<bridgehead renderas="sect3">Header</bridgehead>
|
|
<para>
|
|
<programlisting>#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</programlisting>
|
|
</para>
|
|
|
|
<anchor id="date_construction" />
|
|
<bridgehead renderas="sect3">Construction</bridgehead>
|
|
<informaltable frame="all">
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry valign="top" morerows="1">Syntax</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Example</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>date(greg_year, greg_month, greg_day)</screen></entry>
|
|
<entry>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.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d(2002,Jan,10);</screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>date(date d)</screen></entry>
|
|
<entry>Copy constructor</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d1(d);</screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>date(special_values sv)</screen></entry>
|
|
<entry>Constructor for infinities, not-a-date-time, max_date_time, and min_date_time</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d1(neg_infin);
|
|
date d2(pos_infin);
|
|
date d3(not_a_date_time);
|
|
date d4(max_date_time);
|
|
date d5(min_date_time);</screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>date()</screen></entry>
|
|
<entry>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)</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d; // d => not_a_date_time</screen></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<anchor id="date_construct_from_string" />
|
|
<bridgehead renderas="sect3">Construct from String</bridgehead>
|
|
<informaltable frame="all">
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry valign="top" morerows="1">Syntax</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Example</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>date from_string(std::string)</screen></entry>
|
|
<entry>From delimited date string where with order year-month-day eg: 2002-1-25</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>std::string ds("2002/1/25");
|
|
date d(from_string(ds));</screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>date from_undelimited_string(std::string)</screen></entry>
|
|
<entry>From iso type date string where with order year-month-day eg: 20020125</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>std::string ds("20020125");
|
|
date d(from_undelimited_string(ds));</screen></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<anchor id="date_construct_from_clock" />
|
|
<bridgehead renderas="sect3">Construct from Clock</bridgehead>
|
|
<informaltable frame="all">
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry valign="top" morerows="1">Syntax</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Example</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>day_clock::local_day()</screen></entry>
|
|
<entry>Get the local day based on the time zone settings of the computer.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d(day_clock::local_day());</screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>day_clock::universal_day()</screen></entry>
|
|
<entry>Get the UTC day.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d(day_clock::universal_day());</screen></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<anchor id="date_accessors" />
|
|
<bridgehead renderas="sect3">Accessors</bridgehead>
|
|
<informaltable frame="all">
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry valign="top" morerows="1">Syntax</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Example</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>greg_year year() const</screen></entry>
|
|
<entry>Get the year part of the date.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d(2002,Jan,10);
|
|
d.year(); // --> 2002</screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>greg_month month() const</screen></entry>
|
|
<entry>Get the month part of the date.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d(2002,Jan,10);
|
|
d.month(); // --> 1</screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>greg_day day() const</screen></entry>
|
|
<entry> Get the day part of the date.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d(2002,Jan,10);
|
|
d.day(); // --> 10</screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>greg_ymd year_month_day() const</screen></entry>
|
|
<entry>Return a year_month_day struct. More efficient when all 3 parts of the date are needed.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d(2002,Jan,10);
|
|
date::ymd_type ymd = d.year_month_day();
|
|
// ymd.year --> 2002,
|
|
// ymd.month --> 1,
|
|
// ymd.day --> 10</screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>greg_day_of_week day_of_week() const</screen></entry>
|
|
<entry>Get the day of the week (Sunday, Monday, etc.)</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d(2002,Jan,10);
|
|
d.day_of_week(); // --> Thursday</screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>greg_day_of_year day_of_year() const</screen></entry>
|
|
<entry>Get the day of the year. Number from 1 to 366 </entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d(2000,Jan,10);
|
|
d.day_of_year(); // --> 10</screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>date end_of_month() const</screen></entry>
|
|
<entry>Returns a <code>date</code> object set to the last day of the calling objects current month.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d(2000,Jan,10);
|
|
d.end_of_month(); // --> 2000-Jan-31</screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>bool is_infinity() const</screen></entry>
|
|
<entry>Returns true if date is either positive or negative infinity</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d(pos_infin);
|
|
d.is_infinity(); // --> true</screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>bool is_neg_infinity() const</screen></entry>
|
|
<entry>Returns true if date is negative infinity</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d(neg_infin);
|
|
d.is_neg_infinity(); // --> true</screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>bool is_pos_infinity() const</screen></entry>
|
|
<entry>Returns true if date is positive infinity</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d(pos_infin);
|
|
d.is_pos_infinity(); // --> true</screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>bool is_not_a_date() const</screen></entry>
|
|
<entry>Returns true if value is not a date</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d(not_a_date_time);
|
|
d.is_not_a_date(); // --> true</screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>bool is_special() const</screen></entry>
|
|
<entry>Returns true if date is any <code>special_value</code></entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>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</screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>special_value as_special() const</screen></entry>
|
|
<entry>Returns represented <code>special_value</code> or <code>not_special</code> if the represented date is a normal date.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen></screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>long modjulian_day() const</screen></entry>
|
|
<entry>Returns the modified julian day for the date.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen></screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>long julian_day() const</screen></entry>
|
|
<entry>Returns the julian day for the date.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen></screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>int week_number() const</screen></entry>
|
|
<entry>Returns the ISO 8601 week number for the date.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen></screen></entry>
|
|
</row>
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>date end_of_month() const</screen></entry>
|
|
<entry>Returns the last day of the month for the date.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d(2000,Feb,1);
|
|
//gets Feb 29 -- 2000 was leap year
|
|
date eom = d.end_of_month();</screen></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<anchor id="date_convert_to_string" />
|
|
<bridgehead renderas="sect3">Convert to String</bridgehead>
|
|
<informaltable frame="all">
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry valign="top" morerows="1">Syntax</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Example</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>std::string to_simple_string(date d)</screen></entry>
|
|
<entry>To <code>YYYY-mmm-DD</code> string where <code>mmm</code> is a 3 char month name.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>"2002-Jan-01"</screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>std::string to_iso_string(date d)</screen></entry>
|
|
<entry>To <code>YYYYMMDD</code> where all components are integers.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>"20020131"</screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>std::string to_iso_extended_string(date d)</screen></entry>
|
|
<entry> To <code>YYYY-MM-DD</code> where all components are integers.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>"2002-01-31"</screen></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<anchor id="date_operators" />
|
|
<bridgehead renderas="sect3">Operators</bridgehead>
|
|
<informaltable frame="all">
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry valign="top" morerows="1">Syntax</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Example</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>operator<<</screen></entry>
|
|
<entry>Stream output operator</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d(2002,Jan,1);
|
|
std::cout << d << std::endl;</screen>
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>operator>></screen></entry>
|
|
<entry>Stream input operator. <emphasis role="strong">Note:</emphasis> As of version 1.33, streaming operations have been greatly improved. See <link linkend="date_time.date_time_io">Date Time IO System</link> for details on exceptions and error conditions.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d(not_a_date_time);
|
|
stringstream ss("2002-Jan-01");
|
|
ss >> d;</screen>
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>operator==, operator!=,
|
|
operator>, operator<,
|
|
operator>=, operator<=</screen></entry>
|
|
<entry>A full complement of comparison operators</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>d1 == d2, etc</screen></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>date operator+(date_duration) const</screen></entry>
|
|
<entry>Return a date adding a day offset</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d(2002,Jan,1);
|
|
date_duration dd(1);
|
|
date d2 = d + dd;</screen>
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>date operator-(date_duration) const</screen></entry>
|
|
<entry>Return a date by substracting a day offset</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d(2002,Jan,1);
|
|
date_duration dd(1);
|
|
date d2 = d - dd;</screen>
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>date_duration operator-(date) const</screen></entry>
|
|
<entry>Return a date_duration by subtracting two dates</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>date d1(2002,Jan,1);
|
|
date d2(2002,Jan,2);
|
|
date_duration dd = d2-d1;</screen>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<anchor id="date_tm_funcs" />
|
|
<bridgehead renderas="sect3">Struct tm Functions</bridgehead>
|
|
<para>Functions for converting a <code>date</code> object to, and from, a <code>tm</code> struct are provided.</para>
|
|
<informaltable frame="all">
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry valign="top" morerows="1">Syntax</entry>
|
|
<entry>Description</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Example</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>tm to_tm(date)</screen></entry>
|
|
<entry>A function for converting a <code>date</code> object to a <code>tm</code> struct. The fields: <code>tm_hour</code>, <code>tm_min</code>, and <code>tm_sec</code> are set to zero. The <code>tm_isdst</code> field is set to -1.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>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_isddst => -1 */</screen>
|
|
</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry valign="top" morerows="1"><screen>date date_from_tm(tm datetm)</screen></entry>
|
|
<entry>A function for converting a <code>tm</code> struct to a <code>date</code> object. The fields: <code>tm_wday </code>, <code>tm_yday </code>, <code>tm_hour</code>, <code>tm_min</code>, <code>tm_sec</code>, and <code>tm_isdst</code> are ignored.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><screen>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</screen>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
</section>
|