123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524 |
- <?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>
|