townforge/date_time
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

initial version of xml docs

Browse Source 
[SVN r23219]
This commit is contained in:
Jeff Garland 2004-06-28 00:07:55 +00:00
parent fef15f220c
commit 531428121a
52 changed files with 16092 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
xmldoc/Jamfile.v2 Normal file
View File

@ -0,0 +1,18 @@
import toolset ;
toolset.using doxygen ;
boostbook date_time : date_time.xml ;
doxygen date_time_autodoc :
[ glob ../../../boost/date_time/*.hpp ]
;
doxygen date_time_gregorian_autodoc :
[ glob ../../../boost/date_time/gregorian/*.hpp ]
# [ glob ../../../boost/date_time/local_time/*.hpp ]
;
doxygen date_time_posix_time_autodoc :
[ glob ../../../boost/date_time/posix_time/*.hpp ]
;

33
xmldoc/README Normal file
View File

@ -0,0 +1,33 @@
I couldn't get the date_time.xml to validate, however, it works anyway.
The build process with fail with adequate error messages to fix
any errors.
/********************************/
Do not place a dtd declaration in the doc xml files.
Begin each file with:
<section ...
/********************************/
Including files into sections has some quirks to it. Unless there is a
section in the parent file, the first included file will display
instead of link.
Example.
In date_time.xml:
<xi:include href="subsection.xml" />
And in subsection/xml:
<section id="date_time.my_subsection"
xmlns:xi="http://www.w3.org/2001/XInclude">
<para>
...
</para>
<xi:include href="another.xml" />
/********************************/
To crosslink use:
<link linkend="date_time.section.subsection">optional text</link>
If you use '<link linkend="top">top</link>' the link will automatically
go to the top of the page it ends up in.

7
xmldoc/acknowledgements.xml Normal file
View File

@ -0,0 +1,7 @@
<section id="date_time.acknowledgements">
<title>Acknowledgements</title>
<para>
Many people have contributed to the development of this library. In particular Hugo Duncan and Joel de Guzman for help with porting to various compilers. For initial development of concepts and design Corwin Joy and Michael Kenniston deserve special thanks. Also extra thanks to Michael for writing up the theory and tradeoffs part of the documentation. Dave Zumbro for initial inspiration and sage thoughts. Many thanks to boost reviewers and users including: William Seymour, Kjell Elster, Beman Dawes, Gary Powell, Andrew Maclean, William Kempf, Peter Dimov, Chris Little, David Moore, Darin Adler, Gennadiy Rozental, Joachim Achtzehnter, Paul Bristow, Jan Langer, Mark Rodgers, Glen Knowles, Matthew Denman, and George Heintzelman.
</para>
</section>

81
xmldoc/buildinfo.xml Normal file
View File

@ -0,0 +1,81 @@
<section id="date_time.buildinfo">
<title>Build-Compiler Information</title>
<para>
<link linkend="overview">Overview</link> --
<link linkend="compile_options">Compilation Options</link> --
<link linkend="portability">Compiler/Portability Notes</link> --
<link linkend="dir_structure">Directory Structure</link> --
<link linkend="other_boost_libs">Required Boost Libraries</link>
</para>
<anchor id="overview" />
<bridgehead renderas="sect3">Overview</bridgehead>
<para>
The library has several functions that require the creation of a library file. The Jamfile in the build directory will produce a "static" library (libboost_date_time) and a "dynamic/shared" library (boost_date_time) that contains these functions.
</para>
<anchor id="compile_options" />
<bridgehead renderas="sect3">Compilation Options</bridgehead>
<para>
By default the posix_time system uses a 64 bit integer and a 32 bit integer internally to provide nano-second level resolutions. As an alternative, a single 64 bit integer can be used to provide a microsecond level resolution. This alternative implementation may provide better performance and more compact memory usage for many applications that do not require nano-second resolutions.
</para>
<para>
The variable BOOST_DATE_TIME_POSIX_TIME_STD_CONFIG, as defined in build/Jamfile, selects between these options. To select the 64 bit integer implementation simply remove this define from the Jamfile.
</para>
<anchor id="portability" />
<bridgehead renderas="sect3">Compiler/Portability Notes</bridgehead>
<para>
The Boost Date-Time library has been built and tested with many compilers. However, some compilers and standard libraries have issues. While some of these issues can be worked around, others are difficult to work around. The following compilers fully support all aspects of the library:
<itemizedlist mark="bullet">
<listitem>GCC 3.2-7 on Linux</listitem>
<listitem>GCC 2.95.3 with STLport-4.5.3 on Linux</listitem>
<listitem>GCC 3.1 (cygwin)</listitem>
<listitem>MSVC 7.1 </listitem>
</itemizedlist>
</para>
<para>
In particular, a lack of support for standard locales limits the ability of the library to support iostream based input output. For these compilers a set of more limited string based input-output is provided. The compilers/standard libraries with this limitation include:
<itemizedlist mark="bullet">
<listitem>GCC 2.9x on Linux</listitem>
<listitem>Borland 5.1.1 and 5.6</listitem>
<listitem>MSVC 6 SP5 </listitem>
</itemizedlist>
</para>
<para>
Other compilers such as Comeau and Metroworks have been tested successfully with earlier versions of the library.
</para>
<anchor id="dir_structure" />
<bridgehead renderas="sect3">Directory Structure</bridgehead>
<para>
The directory tree has the following structure:
<programlisting>
/boost/date_time -- common headers and template code
/boost/date_time/gregoran -- gregorian calendar system header files
/boost/date_time/posix_time -- posix time system headers
/libs/date_time/build -- build files and output directory
/libs/date_time/test -- test battery for generic code
/libs/date_time/test/gregorian -- test battery for the gregorian system
/libs/date_time/test/posix_time -- test battery for the posix_time system
/libs/date_time/examples/posix_time -- time example programs
/libs/date_time/examples/gregorian -- nifty example programs
/libs/date_time/src/gregorian -- cpp files for libboost_date_time
/libs/date_time/src/posix_time -- empty (one file, but no source code...)
</programlisting>
</para>
<anchor id="other_boost_libs" />
<bridgehead renderas="sect3">Required Boost Libraries</bridgehead>
<para>
The library depends on
<itemizedlist mark="bullet">
<listitem><ulink url="../../tokenizer/index.htm">boost.tokenizer</ulink> </listitem>
<listitem><ulink url="../../integer/cstdint.htm">boost.integer(cstdint)</ulink> </listitem>
<listitem><ulink url="../../utility/operators.htm">boost.operators</ulink> </listitem>
<listitem><ulink url="../../conversion/lexical_cast.htm">boost::lexical_cast </ulink> </listitem>
</itemizedlist>
so at least these libraries need to be installed.
</para>
</section>

84
xmldoc/calculations.xml Normal file
View File

@ -0,0 +1,84 @@
<section id="date_time.calculations">
<title>Calculations</title>
<para>
<link linkend="timepoints">Timepoints</link> --
<link linkend="durations">Durations</link> --
<link linkend="intervals">Intervals (Periods)</link> --
<link linkend="special_value_handling">Special Value Handling</link>
</para>
<anchor id="timepoints" />
<bridgehead renderas="sect3">Timepoints</bridgehead>
<para>
This section describes some of basic arithmetic rules that can be performed with timepoints. In general, Timepoints support basic arithmetic in conjunction with Durations as follows:
<programlisting>
Timepoint + Duration --> Timepoint
Timepoint - Duration --> Timepoint
Timepoint - Timepoint --> Duration
</programlisting>
Unlike regular numeric types, the following operations are undefined:
<programlisting>
Duration + Timepoint --> Undefined
Duration - Timepoint --> Undefined
Timepoint + Timepoint --> Undefined
</programlisting>
</para>
<anchor id="durations" />
<bridgehead renderas="sect3">Durations</bridgehead>
<para>
Durations represent a length of time and can have positive and negative values. It is frequently useful to be able to perform calculations with other durations and with simple integral values. The following describes these calculations:
<programlisting>
Duration + Duration --> Duration
Duration - Duration --> Duration
Duration * Integer --> Duration
Integer * Duration --> Duration
Duration / Integer --> Duration (Integer Division rules)
</programlisting>
</para>
<anchor id="intervals" />
<bridgehead renderas="sect3">Intervals (Periods)</bridgehead>
<para>
Interval logic is extremely useful for simplifying many 'calculations' for dates and times. The following describes the operations provided by periods which are based on half-open range. The following operations calculate new time periods based on two input time periods:
<programlisting>
Timeperiod intersection Timeperiod --> Timeperiod (null interval if no intersection)
Timeperiod merge Timeperiod --> Timeperiod (null interval if no intersection)
Timeperiod shift Duration --> Timeperiod (shift start and end by duration amount)
</programlisting>
In addition, periods support various queries that calculate boolean results. The first set is caluculations with other time periods:
<programlisting>
Timeperiod == Timeperiod --> bool
Timeperiod &lt; Timeperiod --> bool (true if lhs.last &lt;= rhs.begin)
Timeperiod intersects Timeperiod --> bool
Timeperiod contains Timeperiod --> bool
Timeperiod is_adjacent Timeperiod --> bool
</programlisting>
The following calculations are performed versus the Timepoint.
<programlisting>
Timeperiod contains Timepoint --> bool
Timeperiod is_before Timepoint --> bool
Timeperiod is_after Timepoint --> bool
</programlisting>
</para>
<anchor id="special_value_handling" />
<bridgehead renderas="sect3">Special Value Handling</bridgehead>
<para>
For many temporal problems it is useful for Duration and Timepoint types to support special values such as Not A Date Time (NADT) and infinity. In general special values such as Not A Date Time (NADT) and infinity should follow rules like floating point values. Note that it should be possible to configure NADT based systems to throw an exception instead of result in NADT.
<programlisting>
Timepoint(NADT) + Duration --> Timepoint(NADT)
Timepoint(&#8734;) + Duration --> Timepoint(&#8734;)
Timepoint + Duration(&#8734;) --> Timepoint(&#8734;)
Timepoint - Duration(&#8734;) --> Timepoint(-&#8734;)
</programlisting>
When performing operations on both positive and negative infinities, the library will produce results consistent with the following.
<programlisting>
Timepoint(+&#8734;) + Duration(-&#8734;) --> NADT
Duration(+&#8734;) + Duration(-&#8734;) --> NADT
Duration(&#177;&#8734;) * Zero --> NADT
Duration(&#8734;) * Integer(Not Zero) --> Duration(&#8734;)
Duration(+&#8734;) * -Integer --> Duration(-&#8734;)
Duration(&#8734;) / Integer --> Duration(&#8734;)
</programlisting>
</para>
</section>

9
xmldoc/catalog.xml Normal file
View File

@ -0,0 +1,9 @@
<?xml version="1.0"?>
<!DOCTYPE catalog
PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN"
"http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<rewriteURI uriStartString="http://www.boost.org/tools/boostbook/dtd/" rewritePrefix="file:///usr/local/src/bart/boost/tools/boostbook/dtd//"/>
<rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/current/" rewritePrefix="file:///usr/local/src/bart/DocBookXSL/"/>
<rewriteURI uriStartString="http://www.oasis-open.org/docbook/xml/4.2/" rewritePrefix="file:///usr/local/src/bart/DocBookDTD/"/>
</catalog>

188
xmldoc/changes.xml Normal file
View File

@ -0,0 +1,188 @@
<section id="date_time.changes">
<title>Change History</title>
<bridgehead renderas="sect3">Changes from Boost 1.30 to 1.3? (date_time 1.02 to 1.03--prerelease)</bridgehead>
<informaltable frame="all">
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>Feature</entry>
<entry>Output streaming now supports wide stream output on compiler / standard library combinations that support wide streams. This allows code like:
<programlisting>
std::wstringstream wss;
date d(2003,Aug,21);
wss &lt;&lt; d;</programlisting>
Thanks to Bart Garst for this change.
</entry>
</row>
<row>
<entry>Feature</entry>
<entry>Input streaming for dates and times types is now supported:
<programlisting>
std::stringstream ss("2000-FEB-29");
date d(not_a_date_time);
ss &lt;&lt; d; //Feb 29th, 2000</programlisting>
Thanks to Bart Garst for this change.
</entry>
</row>
<row>
<entry>Bug Fix</entry>
<entry>Fixed the special value constructor for date when constructing date(min_date_time) or date(max_date_time) the wrong value was constructed for these.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<bridgehead renderas="sect3">Changes from Boost 1.30 to 1.31 (date_time 1.01 to 1.02)</bridgehead>
<informaltable frame="all">
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>Bug Fix</entry>
<entry>Build configuration updated so dll, statically, and dynamically linkable library files are now produced with MSVC compilers. See <link linkend="date_time.buildinfo">Build/Compiler Information</link> for more details.</entry>
</row>
<row>
<entry>Bug Fix</entry>
<entry>Time_duration from_string is now correctly constructed from a negative value. (ie "-0:39:00.000") Code provided by Bart Garst.</entry>
</row>
<row>
<entry>Bug Fix</entry>
<entry>Fixed many MSVC compiler warnings when compiled with warning level 4.</entry>
</row>
<row>
<entry>Feature</entry>
<entry>Added prefix decrement operator (--) for date and time iterators. See <link linkend="date_time.posix_time.time_iterators">Time Iterators</link> and <link linkend="date_time.gregorian.date_iterators">Date Iterators</link> for more details. Code provided by Bart Garst.</entry>
</row>
<row>
<entry>Feature</entry>
<entry>Special_values functionality added for date_duration, time_duration and time classes. Code provided by Bart Garst.</entry>
</row>
<row>
<entry>Bug Fix</entry>
<entry>Fixed time_duration_traits calculation bug which was causing time duration to be limited to 32bit range even when 64 bits were available. Thanks to Joe de Guzman for tracking this down.</entry>
</row>
<row>
<entry>Bug Fix</entry>
<entry>Provided additional operators for duration types (eg: date_duration, time_duration). This includes divideable by integer and fixes to allow +=, -= operators. Thanks to Bart Garst for writing this code. Also, the documentation of <link linkend="date_time.calculations">Calculations</link> has been improved.</entry>
</row>
<row>
<entry>Bug Fix</entry>
<entry>Added typedefs to boost::gregorian gregorian_types.hpp various date_generator function classes.</entry>
</row>
<row>
<entry>Feature</entry>
<entry>Added from_time_t function to convert time_t to a ptime.</entry>
</row>
<row>
<entry>Feature</entry>
<entry>Added a span function for combining periods. See <link linkend="date_time.gregorian.date_period">date period</link> and <link linkend="date_time.posix_time.time_period">time period</link> docs.</entry>
</row>
<row>
<entry>Feature</entry>
<entry>Added a function to time_duration to get the total number of seconds in a duration truncating any fractional seconds. In addition, other resolutions were added to allow for easy conversions. For example
seconds(1).total_milliseconds() == 1000
seconds(1).total_microseconds() == 1000000
hours(1).total_milliseconds() == 3600*1000 //3600 sec/hour
seconds(1).total_nanoseconds() == 1000000000</entry>
</row>
<row>
<entry>Feature</entry>
<entry>Added output streaming operators for the <link linkend="date_time.gregorian.date_algorithms">date generator</link> classes - partial_date, first_kday_after, first_kday_before, etc. Thanks to Bart Garst for this work.</entry>
</row>
<row>
<entry>Feature</entry>
<entry>Added unary- operators for durations for reversing the sign of a time duration. For example:
<programlisting>
time_duration td(5,0,0); //5 hours
td = -td; //-5 hours</programlisting>
Thanks to Bart Garst for this work.</entry>
</row>
<row>
<entry>Feature</entry>
<entry>Added support for parsing strings with 'month names'. Thus creating a date object from string now accepts multiple formats ("2003-10-31","2003-Oct-31", and "2003-October-31"). Thus, date d = from_simple_string("2003-Feb-27") is now allowed. A bad month name string ( from_simple_string("2003-SomeBogusMonthName-27")) will cause a bad_month exception. On most compilers the string compare is case insensitive. Thanks to Bart Garst for this work.</entry>
</row>
<row>
<entry>Feature</entry>
<entry>In addition to support for month names or numbers, functions have been added to create date objects from multi-ordered date strings. Ex: "January-21-2002", "2002-Jan-21", and "21-Jan-2003". See <link linkend="date_time.gregorian.date">Date Class</link> for more details.</entry>
</row>
<row>
<entry>Bug-Fix</entry><!-- leave '-' so table cell doesn't wrap -->
<entry>Various documentation fixes. Thanks to Bart Garst for updates.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<bridgehead renderas="sect3">Changes from Boost 1.29 to 1.30 (date_time 1.00 to 1.01)</bridgehead>
<para>
Notice: The interface to the partial_date class (see <link linkend="date_time.gregorian.algorithms">date_algorithms</link>) was changed. The order of construction parameters was changed which will cause some code to fail execution. This change was made to facilitate more generic local time adjustment code. Thus instead of specifying partial_date pd(Dec,25) the code needs to be changed to partial_date pd(25, Dec);
</para>
<informaltable frame="all">
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>Bug Fix</entry>
<entry>Added new experimental feature for Daylight Savings Time calculations. This allows traits based specification of dst rules.</entry>
</row>
<row>
<entry>Feature</entry>
<entry>Added new interfaces to calculate julian day and modified julian day to the gregorian date class. See <link linkend="date_time.gregorian.date">boost::gregorian::date</link>.</entry>
</row>
<row>
<entry>Feature</entry>
<entry>Add new interface to calculate iso 8601 week number for a date. See <link linkend="date_time.gregorian.date">boost::gregorian::date</link>.</entry>
</row>
<row>
<entry>Feature</entry>
<entry>Add an iso 8601 time date-time format (eg: YYYYMMDDTHHHMMSS) parsing function. See <link linkend="date_time.posix_time.ptime">Class ptime</link> for more information.</entry>
</row>
<row>
<entry>Feature</entry>
<entry> Added a length function to the period template so that both date_periods and time_periods will now support this function.</entry>
</row>
<row>
<entry>Bug Fix</entry>
<entry>Split Jamfiles so that libs/date_time/build/Jamfile only builds library and /libs/date_time/libs/test/Jamfile which runs tests.</entry>
</row>
<row>
<entry>Bug Fix</entry>
<entry>Fixed many minor documentation issues.</entry>
</row>
<row>
<entry>Bug Fix</entry>
<entry>Removed the DATE_TIME_INLINE macro which was causing link errors. This macro is no longer needed in projects using the library.</entry>
</row>
<row>
<entry>Bug Fix</entry>
<entry>Added missing typedef for year_iterator to gregorian_types.hpp</entry>
</row>
<row>
<entry>Bug Fix</entry>
<entry>Fixed problem with gregorian ostream operators that prevented the use of wide streams.</entry>
</row>
<row>
<entry>Bug-Fix</entry><!-- leave '-' so table cell doesn't wrap -->
<entry>Tighten error handling for dates so that date(2002, 2, 29) will throw a bad_day_of_month exception. Previously the date would be incorrectly constructed. Reported by sourceforge bug: 628054 among others.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>

26
xmldoc/conceptual.xml Normal file
View File

@ -0,0 +1,26 @@
<section id="date_time.conceptual" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Conceptual</title>
<xi:include href="motivation.xml"/>
<xi:include href="domain_concepts.xml"/>
<xi:include href="design_concepts.xml"/>
<section id="date_time.conceptual.more_info">
<title>More Information</title>
<para>
The design of the library is currently being evolved using
Wiki and email discussions. You can find more information at:
<itemizedlist mark="bullet">
<listitem>
<ulink url="http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?GDTL">Boost Wiki GDTL Start Page</ulink>
</listitem>
<listitem>
<ulink url="http://www.crystalclearsoftware.com/libraries/gdtl/gdtl_ref_guide/index.html">Full Doxygen Reference Manual</ulink>
</listitem>
</itemizedlist>
</para>
</section>
</section>

99
xmldoc/date_algorithms.xml Normal file
View File

@ -0,0 +1,99 @@
<section id="date_time.gregorian.date_algorithms">
<title>Date Generators/Algorithms</title>
<link linkend="algo_intro">Introduction</link> --
<link linkend="algo_header">Header</link> --
<link linkend="algo_overview">Overview</link>
<anchor id="algo_intro" />
<bridgehead renderas="sect3">Introduction</bridgehead>
<para>
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.
</para>
<programlisting>
using namespace boost::gregorian;
typedef boost::date_time::nth_kday_of_month&lt;date> nkday;
nkday ldgen(nkday::first, Monday, Sep)); //US labor day
date labor_day = ldgen.get_date(2002); //Calculate labor day for 2002
</programlisting>
<para>
The <link linkend="date_time.examples.print_holidays">print holidays</link> example shows a detailed usage example.
</para>
<anchor id="algo_header" />
<bridgehead renderas="sect3">Header</bridgehead>
<para>
#include "boost/date_time/date_generators.hpp"
</para>
<anchor id="algo_overview" />
<bridgehead renderas="sect3">Overview</bridgehead>
<informaltable frame="all">
<tgroup cols="4">
<thead>
<row>
<entry>Class</entry>
<entry>Construction Parameters</entry>
<entry>get_date Parameter</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>first_kday_after</entry>
<entry> greg_day_of_week day_of_week</entry>
<entry>date start_day</entry>
<entry>Calculate something like First Sunday after Jan 1,2002</entry>
<entry>
first_kday_after fkaf(Monday);
date d = fkaf.get_date(date(2002,Jan,1));//2002-Jan-07
</entry>
</row>
<row>
<entry>first_kday_before</entry>
<entry> greg_day_of_week day_of_week</entry>
<entry>date start_day</entry>
<entry>Calculate something like First Monday before Feb 1,2002</entry>
<entry>
first_kday_before fkbf(Monday);
date d = fkbf.get_date(date(2002,Feb,1));//2002-Jan-28
</entry>
</row>
<row>
<entry>last_kday_of_month</entry>
<entry>greg_day_of_week day_of_week greg_month month</entry>
<entry>greg_year year</entry>
<entry>Calculate something like last Monday of January</entry>
<entry>
last_kday_of_month lkm(Monday,Jan);
date d = lkm.get_date(2002);//2002-Jan-28
</entry>
</row>
<row>
<entry>first_kday_of_month</entry>
<entry>greg_day_of_week day_of_week greg_month month</entry>
<entry>greg_year year</entry>
<entry>Calculate something like first Monday of January</entry>
<entry>
first_kday_of_month fkm(Monday,Jan);
date d = fkm.get_date(2002);//2002-Jan-07
</entry>
</row>
<row>
<entry>partial_date</entry>
<entry>greg_day day_of_month greg_month month</entry>
<entry>greg_year year</entry>
<entry>Generates a date by applying the year to the given month and day.</entry>
<entry>
partial_date pd(1,Jan);
date d = pd.get_date(2002);//2002-Jan-01
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<link linkend="top">top</link>
</section>

310
xmldoc/date_class.xml Normal file
View File

@ -0,0 +1,310 @@
<section id="date_time.gregorian.date_class">
<title>Date Class</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>
<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.
</para>
<para>
Other techniques for creating dates include <link linkend="date_time.gregorian.date_iterators">date iterators</link> and <link linkend="date_time.gregorian.date_algorithms">date algorithms or generators</link>.
</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="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>date(greg_year year, greg_month month, greg_day day)</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>
<entry>date d(2002,Jan,10)</entry>
</row>
<row>
<entry>date(date d)</entry>
<entry>Copy constructor</entry>
<entry>date d1(d)</entry>
</row>
<row>
<entry>date(special_values sv)</entry>
<entry>Constructor for infinities, not-a-date-time, max_date, and min_date</entry>
<entry>
date d1(neg_infin);
date d2(pos_infin);
date d3(not_a_date_time);
date d4(max_date);
date d5(min_date);</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<anchor id="date_construct_from_string" />
<bridgehead renderas="sect3">Construct from String</bridgehead>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>date from_string(const std::string&amp;)</entry>
<entry>From delimited date string where with order year-month-day eg: 2002-1-25</entry>
<entry>
std::string ds("2002/1/25");
date d(from_string(ds))</entry>
</row>
<row>
<entry>date from_undelimited_string(const std::string&amp;)</entry>
<entry>From iso type date string where with order year-month-day eg: 20020125</entry>
<entry>
std::string ds("20020125");
date d(from_undelimited_string(ds))</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<anchor id="date_construct_from_clock" />
<bridgehead renderas="sect3">Construct from Clock</bridgehead>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>day_clock::local_day()</entry>
<entry>Get the local day based on the time zone settings of the computer.</entry>
<entry>date d(day_clock::local_day())</entry>
</row>
<row>
<entry>day_clock::universal_day()</entry>
<entry>Get the UTC day.</entry>
<entry>date d(day_clock::universal_day())</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<anchor id="date_accessors" />
<bridgehead renderas="sect3">Accessors</bridgehead>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>greg_year year() const</entry>
<entry>Get the year part of the date.</entry>
<entry>
date d(2002,Jan,10);
d.year() --> 2002;</entry>
</row>
<row>
<entry>greg_month month() const</entry>
<entry>Get the month part of the date.</entry>
<entry>
date d(2002,Jan,10);
d.month() --> 1;</entry>
</row>
<row>
<entry>greg_day day() const</entry>
<entry> Get the day part of the date.</entry>
<entry>
date d(2002,Jan,10);
d.day() --> 10;</entry>
</row>
<row>
<entry>greg_ymd year_month_day() const</entry>
<entry>Return a year_month_day struct. More efficient when all 3 parts of the date are needed.</entry>
<entry>
date d(2002,Jan,10);
date::ymd_type ymd = d.year_month_day();
ymd.year --> 2002, ymd.month --> 1, ymd.day --> 10</entry>
</row>
<row>
<entry>greg_day_of_week day_of_week() const</entry>
<entry>Get the day of the week (eg: Sunday, Monday, etc.</entry>
<entry>
date d(2002,Jan,10);
d.day() --> Thursday;</entry>
</row>
<row>
<entry>bool is_infinity() const</entry>
<entry>Returns true if date is either positive or negative infinity</entry>
<entry>
date d(pos_infin);
d.is_infinity() --> true;</entry>
</row>
<row>
<entry>bool is_neg_infinity() const</entry>
<entry>Returns true if date is negative infinity</entry>
<entry>
date d(neg_infin);
d.is_neg_infinity() --> true;</entry>
</row>
<row>
<entry>bool is_pos_infinity() const</entry>
<entry>Returns true if date is positive infinity</entry>
<entry>
date d(neg_infin);
d.is_pos_infinity() --> true;</entry>
</row>
<row>
<entry>bool is_not_a_date() const</entry>
<entry>Returns true if value is not a date</entry>
<entry>
date d(not_a_date_time);
d.is_not_a_date() --> true;</entry>
</row>
<row>
<entry>long modjulian_day() const</entry>
<entry>Returns the modified julian day for the date.</entry>
<entry></entry>
</row>
<row>
<entry>long julian_day() const</entry>
<entry>Returns the julian day for the date.</entry>
<entry></entry>
</row>
<row>
<entry>int week_number() const</entry>
<entry>Returns the ISO 8601 week number for the date.</entry>
<entry></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<anchor id="date_convert_to_string" />
<bridgehead renderas="sect3">Convert to String</bridgehead>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>std::string to_simple_string(date d)</entry>
<entry>To YYYY-mmm-DD string where mmm 3 char month name.</entry>
<entry>2002-Jan-01</entry>
</row>
<row>
<entry>std::string to_iso_string(date d)</entry>
<entry>To YYYYMMDD where all components are integers.</entry>
<entry>20020131</entry>
</row>
<row>
<entry>std::string to_iso_extended_string(date d)</entry>
<entry> To YYYY-MM-DD where all components are integers.</entry>
<entry>2002-01-31</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<anchor id="date_operators" />
<bridgehead renderas="sect3">Operators</bridgehead>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>operator&lt;&lt;</entry>
<entry>Stream output operator</entry>
<entry>
date d(2002,Jan,1)
std::cout &lt;&lt; d &lt;&lt; std::endl;
</entry>
</row>
<row>
<entry>
operator==, operator!=,
operator>, operator&lt;
operator>=, operator&lt;=</entry>
<entry>A full complement of comparison operators</entry>
<entry>d1 == d2, etc</entry>
</row>
<row>
<entry>date operator+(date_duration) const</entry>
<entry>Return a date adding a day offset</entry>
<entry>
date d(2002,Jan,1);
date_duration dd(1);
date d2 = d + dd;
</entry>
</row>
<row>
<entry>date operator-(date_duration) const</entry>
<entry>Return a date by adding a day offset</entry>
<entry>
date d(2002,Jan,1);
date_duration dd(1);
date d2 = d - dd;
</entry>
</row>
<row>
<entry>date_duration operator-(date) const</entry>
<entry>Return a date duration by subtracting two dates</entry>
<entry>
date d1(2002,Jan,1);
date d2(2002,Jan,2);
date_duration dd = d2-d1;
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<link linkend="top">top</link>
</section>

121
xmldoc/date_duration.xml Normal file
View File

@ -0,0 +1,121 @@
<section id="date_time.gregorian.date_duration">
<title>Date Duration</title>
<link linkend="duration_intro">Introduction</link> --
<link linkend="duration_header">Header</link> --
<link linkend="duration_construction">Construction</link> --
<link linkend="duration_operators">Operators</link>
<anchor id="duration_intro" />
<bridgehead renderas="sect3">Introduction</bridgehead>
<para>
The class boost::gregorian::date_duration is a simple day count used for arithmetic with <link linkend="date_time.gregorian.date_class">gregorian::date</link>. A duration can be either positive or negative.
</para>
<anchor id="duration_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="duration_construction" />
<bridgehead renderas="sect3">Construction</bridgehead>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>date_duration(long)</entry>
<entry>Create a duration count.</entry>
<entry> date_duration dd(3); //3 days</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<anchor id="duration_accessors" />
<bridgehead renderas="sect3">Accessors</bridgehead>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>long days() const</entry>
<entry> Get the day count.</entry>
<entry>date_duration dd(3); dd.days() --> 3</entry>
</row>
<row>
<entry>bool is_negative() const</entry>
<entry>True if number of days is less than zero.</entry>
<entry>date_duration dd(-1); dd.is_negative() --> true</entry>
</row>
<row>
<entry>static date_duration unit()</entry>
<entry>Return smallest possible unit of duration type.</entry>
<entry>date_duration::unit() --> date_duration(1)</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<anchor id="duration_operators" />
<bridgehead renderas="sect3">Operators</bridgehead>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>
operator==, operator!=,
operator>, operator&lt;
operator>=, operator&lt;=
</entry>
<entry>A full complement of comparison operators</entry>
<entry>dd1 == dd2, etc</entry>
</row>
<row>
<entry>date_duration operator+(date_duration) const</entry>
<entry>Add date durations.</entry>
<entry>
date_duration dd1(3);
date_duration dd2(5);
date_duration dd3 = dd1 + dd2;
</entry>
</row>
<row>
<entry>date_duration operator-(date_duration) const</entry>
<entry>Subtract durations.</entry>
<entry>
date_duration dd1(3);
date_duration dd2(5);
date_duration dd3 = dd1 - dd2;
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<link linkend="top">top</link>
</section>

72
xmldoc/date_iterators.xml Normal file
View File

@ -0,0 +1,72 @@
<section id="date_time.gregorian.date_iterators">
<title>Date Iterators</title>
<link linkend="iterators_intro">Introduction</link> --
<link linkend="iterators_header">Header</link> --
<link linkend="iterators_overview">Overview</link>
<anchor id="iterators_intro" />
<bridgehead renderas="sect3">Introduction</bridgehead>
<para>
Date iterators provide a standard mechanism for iteration through dates. Date iterators are a model of <ulink url="http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</ulink> and can be used to populate collections with dates and other date generation tasks. For example, the <link linkend="date_time.examples.print_month">print month</link> example iterates through all the days in a month and prints them.
</para>
<para>
All of the iterators here derive from boost::gregorian::date_iterator.
</para>
<anchor id="iterators_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="iterators_overview" />
<bridgehead renderas="sect3">Overview</bridgehead>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Class</entry>
<entry>Construction Parameters</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>date_iterator</entry>
<entry></entry>
<entry>Common base class for all day level iterators.</entry>
</row>
<row>
<entry>day_iterator</entry>
<entry>date start_date, int day_count=1</entry>
<entry>Iterate day_count days at a time.</entry>
</row>
<row>
<entry>week_iterator</entry>
<entry> date start_date, int week_offset=1</entry>
<entry>Iterate week_offset weeks at a time.</entry>
</row>
<row>
<entry>month_iterator</entry>
<entry>date start_date, int month_offset=1</entry>
<entry>
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.
</entry>
</row>
<row>
<entry>year_iterator</entry>
<entry>date start_date, int year_offset=1</entry>
<entry>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).</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<link linkend="top">top</link>
</section>

270
xmldoc/date_period.xml Normal file
View File

@ -0,0 +1,270 @@
<section id="date_time.gregorian.date_period">
<title>Date Period</title>
<link linkend="period_intro">Introduction</link> --
<link linkend="period_header">Header</link> --
<link linkend="period_construction">Construction</link> --
<link linkend="period_accessors">Accessors</link> --
<link linkend="period_convert_to_string">Convert to String</link> --
<link linkend="period_operators">Operators</link>
<anchor id="period_intro" />
<bridgehead renderas="sect3">Introduction</bridgehead>
<para>
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 <link linkend="date_time.examples.period_calc">period calculation example</link> provides an example of this.
</para>
<para>
Date periods used in combination with infinity values have the ability to represent complex concepts such as 'until further notice'.
</para>
<anchor id="period_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="period_construction" />
<bridgehead renderas="sect3">Construction</bridgehead>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>date_period(date begin, date end)</entry>
<entry> Create a period as [begin, end). If last is &lt;= begin then the period will be defined as null.</entry>
<entry>date_period dp(date(2002,Jan,10), date(2002,Jan,12));</entry>
</row>
<row>
<entry>date_period(date start, date_duration len)</entry>
<entry> Create a period as [begin, begin+len). If len is &lt;= zero then the period will be defined as null.</entry>
<entry>date_period dp(date(2002,Jan,10), date_duration(2));</entry>
</row>
<row>
<entry>date_period(date_period rhs)</entry>
<entry> Copy constructor</entry>
<entry> date_period dp1(dp)</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<anchor id="period_accessors" />
<bridgehead renderas="sect3">Accessors</bridgehead>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>date begin() const</entry>
<entry> Return first day of period.</entry>
<entry>
date_period dp(date(2002,Jan,1), date(2002,Jan,10));
dp.begin() --> 2002-Jan-01
</entry>
</row>
<row>
<entry>date last() const</entry>
<entry>Return last date in the period</entry>
<entry>
date_period dp(date(2002,Jan,1), date(2002,Jan,10));
dp.last() --> 2002-Jan-09
</entry>
</row>
<row>
<entry>date end() const</entry>
<entry>Return one past the last in period</entry>
<entry>
date_period dp(date(2002,Jan,1), date(2002,Jan,10));
dp.end() --> 2002-Jan-10
</entry>
</row>
<row>
<entry>date_duration length() const</entry>
<entry>Return the length of the date_period</entry>
<entry>
date_period dp(date(2002,Jan,1), date_duration(2));
dp.length() --> 2
</entry>
</row>
<row>
<entry>bool is_null() const</entry>
<entry>True if period is not well formed. eg: start less than end</entry>
<entry>
date_period dp(date(2002,Jan,10), date(2002,Jan,1));
dp.begin() --> true
</entry>
</row>
<row>
<entry>bool contains(date) const</entry>
<entry>True if date is within the period</entry>
<entry>
date_period dp(date(2002,Jan,1), date(2002,Jan,10));
dp.contains(date(2002,Jan,2)) --> true
</entry>
</row>
<row>
<entry>bool contains(date_period) const</entry>
<entry>True if date period is within the period</entry>
<entry>
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
</entry>
</row>
<row>
<entry>bool intersects(date_period) const</entry>
<entry>True if periods overlap</entry>
<entry>
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
</entry>
</row>
<row>
<entry>date_period intersection(date_period) const</entry>
<entry>Calculate the intersection of 2 periods. Null if no intersection.</entry>
<entry>
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
</entry>
</row>
<row>
<entry>date_period is_adjacent(date_period) const</entry>
<entry>Check if two periods are adjacent, but not overlapping.</entry>
<entry>
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
</entry>
</row>
<row>
<entry>date_period is_after(date) const</entry>
<entry>Determine the period is after a given date.</entry>
<entry>
date_period dp1(date(2002,Jan,10), date(2002,Jan,30));
date d(2002,Jan,3);
dp1.is_after(d) --> true
</entry>
</row>
<row>
<entry>date_period is_before(date) const</entry>
<entry>Determine the period is before a given date.</entry>
<entry>
date_period dp1(date(2002,Jan,1), date(2002,Jan,3));
date d(2002,Jan,10);
dp1.is_before(d) --> true
</entry>
</row>
<row>
<entry>date_period merge(date_period) const</entry>
<entry>Returns union of two periods. Null if no intersection.</entry>
<entry>
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
</entry>
</row>
<row>
<entry>date_period span(date_period) const</entry>
<entry>Combines two periods and any gap between them such that start = min(p1.start, p2.start) and end = max(p1.end , p2.end)</entry>
<entry>
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
</entry>
</row>
<row>
<entry>date_period shift(date_duration)</entry>
<entry>Add duration to both start and end.</entry>
<entry>
date_period dp1(date(2002,Jan,1), date(2002,Jan,10));
dp1.shift(date_duration(1)); --> 2002-Jan-02/2002-Jan-11
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<anchor id="period_convert_to_string" />
<bridgehead renderas="sect3">Convert to String</bridgehead>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>std::string to_simple_string(date_period dp)</entry>
<entry>To [YYYY-mmm-DD/YYYY-mmm-DD] string where mmm is 3 char month name.</entry>
<entry>[2002-Jan-01/2002-Jan-31]</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<anchor id="period_operators" />
<bridgehead renderas="sect3">Operators</bridgehead>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>operator&lt;&lt;</entry>
<entry>ostream operator for date_period. Uses facet to format time points. Typical output: [2002-Jan-01/2002-Jan-31].</entry>
<entry>std::cout &lt;&lt; dp &lt;&lt; std::endl;</entry>
</row>
<row>
<entry>
operator==, operator!=,
operator>, operator&lt;
</entry>
<entry>A full complement of comparison operators</entry>
<entry> dp1 == dp2, etc</entry>
</row>
<row>
<entry>operator&lt;</entry>
<entry>True if dp1.end() less than dp2.begin()</entry>
<entry> dp1 &lt; dp2, etc</entry>
</row>
<row>
<entry>operator></entry>
<entry>True if dp1.begin() greater than dp2.end()</entry>
<entry>dp1 > dp2, etc</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<link linkend="top">top</link>
</section>

51
xmldoc/date_time.xml Normal file
View File

@ -0,0 +1,51 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"../../../tools/boostbook/dtd/boostbook.dtd">
<library name="Date Time" dirname="date_time"
xmlns:xi="http://www.w3.org/2001/XInclude" id="date_time"
last-revision="$Date$">
<libraryinfo>
<author>
<firstname>Jeff</firstname>
<surname>Garland</surname>
</author>
<copyright>
<year>2001</year>
<year>2002</year>
<year>2003</year>
<year>2004</year>
<holder>CrystalClear Software, Inc</holder>
</copyright>
<legalnotice>
<para>Use, modification and distribution is subject to the Boost
Software License, Version 1.0. (See accompanying file
<filename>LICENSE_1_0.txt</filename> or copy at <ulink
url="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</ulink>)</para>
</legalnotice>
<librarypurpose>A set of facilities to ease programming with dates and times.
</librarypurpose>
<librarycategory name="category:misc"/>
</libraryinfo>
<title>Boost.Date_Time</title>
<section id="date_time.intro">
<bridgehead renderas="sect3">Introduction</bridgehead>
<para>
A set of date-time libraries based on generic programming concepts.
</para>
</section>
<xi:include href="conceptual.xml"/>
<xi:include href="gregorian.xml"/>
<xi:include href="posix_time.xml"/>
<xi:include href="details.xml"/>
<xi:include href="examples.xml"/>
<!--<xi:include href="date_time.doxygen.boostbook"/> -->
<xi:include href="doxy.xml"/>
<!-- add more sections here -->
</library>

6609
xmldoc/date_time_autodoc.boostbook Normal file
View File

File diff suppressed because it is too large Load Diff

3911
xmldoc/date_time_gregorian_autodoc.boostbook Normal file
View File

File diff suppressed because it is too large Load Diff

1297
xmldoc/date_time_posix_time_autodoc.boostbook Normal file
View File

File diff suppressed because it is too large Load Diff

6
xmldoc/day_clock_class.xml Normal file
View File

@ -0,0 +1,6 @@
<section id="date_time.gregorian.day_clock_class">
<title>Class day_clock</title>
<link linkend="date_construct_from_clock">Class day_clock</link>
<!-- day_clock is documented as part of the date class.
This file serves as a link generator for day_clock -->
</section>

13
xmldoc/design_concepts.xml Normal file
View File

@ -0,0 +1,13 @@
<section id="date_time.design_concepts">
<title>Design Concepts</title>
<para>
A large part of the genesis of this library has been the observation that few date-time libraries are built in a fashion that allows customization and extension. A typical example, the calendar logic is built directly into the date class. Or the clock retrieval functions are built directly into the time class. These design decisions usually make it impossible to extend or change the library behavior. At a more fundamental level, there are usually assumptions about the resolution of time representation or the gregorian calendar.
</para>
<para>
Often times, the result is that a project must settle for a less than complete library because of a requirement for high resolution time representation or other assumptions that do not match the implementation of the library. This is extremely unfortunate because development of a library of this sort is far from a trivial task.
</para>
<para>
While the design is far from perfect the current design is far more flexible than any date-time library the author is aware of. It is expected that the various aspects of extensibility will be better documented in future versions. Information about the design goals of the library is <link linkend="date_time.design_goals">summarized here</link>.
</para>
</section>

123
xmldoc/design_goals.xml Normal file
View File

@ -0,0 +1,123 @@
<section id="date_time.design_goals">
<title>Design Goals</title>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Category</entry>
<entry>Description</entry>
<entry>Functions</entry>
</row>
</thead>
<tbody>
<row>
<entry>Interfaces</entry>
<entry>Provide concrete classes for manipulation of dates and times</entry>
<entry>
<itemizedlist mark="bullet">
<listitem>
date, time, date_duration, time_duration, date_period, time_period, etc
</listitem>
<listitem>
support for infinity - positive infinity, negative infinity
</listitem>
<listitem>
iterators over time and date ranges
</listitem>
<listitem>
allow date and time implemenations to be separate as much as possible
</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>Calculation</entry>
<entry>Provide a basis for performing efficient time calculations </entry>
<entry>
<itemizedlist mark="bullet">
<listitem>days between dates </listitem>
<listitem>durations of times </listitem>
<listitem>durations of dates and times together </listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>Representation Flexibility</entry>
<entry>Provide the maximum possible reusability and flexibility</entry>
<entry>
<itemizedlist mark="bullet">
<listitem>
traits based customization of internal
representations for size versus resolution control
</listitem>
<listitem>
Allowing the use of different epochs and resolution
(eg: seconds versus microseconds, dates starting at the
year 2000 versus dates starting in 1700)
</listitem>
<listitem>
Options for configuring unique calendar representations
(Gregorian + others)
</listitem>
<listitem>
the use of Julian Day number and the conversion between
this and the Gregorian/Julian calendar date
</listitem>
<listitem>Allow for flexible adjustments including
leap seconds
</listitem>
</itemizedlist>
</entry>
</row>
<row><entry>Date Calculations</entry>
<entry>Provide tools for date calculations</entry>
<entry>
<itemizedlist mark="bullet">
<listitem>provide basis for calculation of complex event specs like holidays</listitem>
<listitem>calendar to calendar conversions</listitem>
<listitem>provide for ability to extend to new calendar systems</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>Time Calculations</entry>
<entry>Provide concrete classes for manipulation of time</entry>
<entry>
<itemizedlist mark="bullet">
<listitem>provide the ability to handle cross time-zone issues</listitem>
<listitem>provide adjustments for daylight savings time (summer time)</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>Clock Interfaces</entry>
<entry>Provide classes for retrieving time current time</entry>
<entry>
<itemizedlist mark="bullet">
<listitem>access to a network / high resolution time sources </listitem>
<listitem>retrieving the current date time information to populate classes </listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>I/O Interfaces</entry>
<entry>Provide input and output for time including</entry>
<entry>
<itemizedlist mark="bullet">
<listitem>multi-lingual support </listitem>
<listitem>provide ISO8601 compliant time facet </listitem>
<listitem>use I/O facets for different local behavior </listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>

14
xmldoc/details.xml Normal file
View File

@ -0,0 +1,14 @@
<section id="date_time.details" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Details</title>
<xi:include href="changes.xml" />
<xi:include href="serialization.xml" />
<xi:include href="buildinfo.xml" />
<xi:include href="acknowledgements.xml" />
<xi:include href="tests.xml" />
<xi:include href="design_goals.xml" />
<xi:include href="tradeoffs.xml" />
<xi:include href="terminology.xml" />
<xi:include href="calculations.xml" />
<xi:include href="references.xml" />
</section>

52
xmldoc/domain_concepts.xml Normal file
View File

@ -0,0 +1,52 @@
<section id="date_time.domain_concepts">
<title>Domain Concepts</title>
<para>
The date time domain is rich in terminology and problems.
The following is a brief introduction to the concepts you
will find reflected in the library.
</para>
<para>
The library supports 3 basic temporal types:
<itemizedlist mark="bullet">
<listitem>
<emphasis role="strong">Time Point</emphasis> -- Specifier
for a location in the time continuum.
</listitem>
<listitem>
<emphasis role="strong">Time Duration</emphasis> -- A
length of time unattached to any point on the time continuum.
</listitem>
<listitem>
<emphasis role="strong">Time Interval</emphasis> -- A duration
of time attached to a specific point in the time continuum.
Also known as a time period.
</listitem>
</itemizedlist>
</para>
<para>
Each of these temporal types has a <emphasis role="strong">Resolution</emphasis> which is defined by the smallest representable duration. A <emphasis role="strong">Time system</emphasis> provides all these categories of temporal types as well as the rules for labeling and calculating with time points. <emphasis role="strong">Calendar Systems</emphasis> are simply time systems with a maximum resolution of one day. The <emphasis role="strong">Gregorian</emphasis> system is the most widely used calendar system today (the ISO system is basically a derivative of this). However, there are many other calendar systems as well. <emphasis role="strong">UTC (Coordinated Universal Time)</emphasis> is a widely used civil time system. UTC is adjusted for earth rotation at longitude 0 by the use of leap seconds (This is not predictable, only as necessary). Most <emphasis role="strong">local time</emphasis> systems are based on UTC but are also adjusted for earth rotation so that daylight hours are similar everywhere. In addition, some local times include <emphasis role="strong">daylight savings time (DST)</emphasis> adjustments to shift the daylight hours during the summer.
</para>
<para>
A <emphasis role="strong">Clock Device</emphasis> is software component (tied to some hardware) that provides the current date or time with respect to a time system. A clock can measure the current time to a known resolution which may be higher or lower than a particular time representation.
</para>
<para>
The library provides support for calculating with dates and times. However, time calculations are not quite the same as calculating with integers. If you are serious about the accuracy of your time calculations need to read about <link linkend="date_time.tradeoffs">Stability, Predictability, and Approximations</link>.
</para>
<para>
<itemizedlist mark="bullet">
<listitem>
<link linkend="date_time.terminology">Basic Terminology</link>
</listitem>
<listitem>
<link linkend="date_time.calculations">Calculations</link>
</listitem>
<listitem>
<link linkend="date_time.tradeoffs">Stability, Predictability, and Approximations</link>
</listitem>
<listitem>
<link linkend="date_time.references">References</link>
</listitem>
</itemizedlist>
</para>
</section>

26
xmldoc/doxy.xml Normal file
View File

@ -0,0 +1,26 @@
<section id="date_time.doxy" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Doxygen Generated Library Reference</title>
<para>
We added doxygen generated documentation. &lt;Reword this&gt;
</para>
<!--<ulink url="../../boost/date_time/html/index.html">Doxy docs</ulink>-->
<!--
<link linkend="dt">Date_time</link>
<link linkend="gt">Gregorian_time</link>
<link linkend="pt">Posix_time</link>
<anchor id="dt"/>
<xi:include href="date_time_autodoc.boostbook"/>
<anchor id="gt"/>
<xi:include href="date_time_gregorian_autodoc.boostbook"/>
<anchor id="pt"/>
<xi:include href="date_time_posix_time_autodoc.boostbook"/>
-->
<xi:include href="date_time_autodoc.boostbook"/>
<xi:include href="date_time_gregorian_autodoc.boostbook"/>
<xi:include href="date_time_posix_time_autodoc.boostbook"/>
</section>

90
xmldoc/ex_date_period_calc.xml Normal file
View File

@ -0,0 +1,90 @@
<section id="date_time.examples.date_period_calc">
<title>Date Period Calculations</title>
<para>
Calculates if a date is in an 'irregular' collection of periods using period calculation functions.
</para>
<programlisting>
<![CDATA[
/*
This example demonstrates a simple use of periods for the calculation
of date information.
The example calculates if a given date is a weekend or holiday
given an exclusion set. That is, each weekend or holiday is
entered into the set as a time interval. Then if a given date
is contained within any of the intervals it is considered to
be within the exclusion set and hence is a offtime.
Output:
Number Excluded Periods: 5
20020202/20020203
20020209/20020210
20020212/20020212
20020216/20020217
In Exclusion Period: 20020216 --> 20020216/20020217
20020223/20020224
*/
#include "boost/date_time/gregorian/gregorian.hpp"
#include <set>
#include <algorithm>
#include <iostream>
typedef std::set<boost::gregorian::date_period> date_period_set;
//Simple population of the exclusion set
date_period_set
generateExclusion()
{
using namespace boost::gregorian;
date_period periods_array[] =
{ date_period(date(2002,Feb,2), date(2002,Feb,4)),//weekend of 2nd-3rd
date_period(date(2002,Feb,9), date(2002,Feb,11)),
date_period(date(2002,Feb,16), date(2002,Feb,18)),
date_period(date(2002,Feb,23), date(2002,Feb,25)),
date_period(date(2002,Feb,12), date(2002,Feb,13))//a random holiday 2-12
};
const int num_periods = sizeof(periods_array)/sizeof(date_period);
date_period_set ps;
//insert the periods in the set
std::insert_iterator<date_period_set> itr(ps, ps.begin());
std::copy(periods_array, periods_array+num_periods, itr );
return ps;
}
int main()
{
using namespace boost::gregorian;
date_period_set ps = generateExclusion();
std::cout << "Number Excluded Periods: " << ps.size() << std::endl;
date d(2002,Feb,16);
date_period_set::const_iterator i = ps.begin();
//print the periods, check for containment
for (;i != ps.end(); i++) {
std::cout << to_iso_string(*i) << std::endl;
//if date is in exclusion period then print it
if (i->contains(d)) {
std::cout << "In Exclusion Period: "
<< to_iso_string(d) << " --> " << to_iso_string(*i)
<< std::endl;
}
}
return 0;
}
]]>
</programlisting>
<para>
<link linkend="top">top</link>
</para>
</section>

71
xmldoc/ex_dates_as_strings.xml Normal file
View File

@ -0,0 +1,71 @@
<section id="date_time.examples.dates_as_strings">
<title>Dates as Strings</title>
<para>
Various parsing and output of strings.
</para>
<programlisting>
<![CDATA[
/* The following is a simple example that shows conversion of dates
* to and from a std::string.
*
* Expected output:
* 2001-Oct-09
* 2001-10-09
* Tuesday October 9, 2001
* An expected exception is next:
* Exception: Month number is out of range 1..12
*/
#include "boost/date_time/gregorian/gregorian.hpp"
#include <iostream>
#include <string>
int
main()
{
using namespace boost::gregorian;
try {
// The following date is in ISO 8601 extended format (CCYY-MM-DD)
std::string s("2001-10-9"); //2001-October-09
date d(from_simple_string(s));
std::cout << to_simple_string(d) << std::endl;
//Read ISO Standard(CCYYMMDD) and output ISO Extended
std::string ud("20011009"); //2001-Oct-09
date d1(from_undelimited_string(ud));
std::cout << to_iso_extended_string(d1) << std::endl;
//Output the parts of the date - Tuesday October 9, 2001
date::ymd_type ymd = d1.year_month_day();
greg_weekday wd = d1.day_of_week();
std::cout << wd.as_long_string() << " "
<< ymd.month.as_long_string() << " "
<< ymd.day << ", " << ymd.year
<< std::endl;
//Let's send in month 25 by accident and create an exception
std::string bad_date("20012509"); //2001-??-09
std::cout << "An expected exception is next: " << std::endl;
date wont_construct(from_undelimited_string(bad_date));
//use wont_construct so compiler doesn't complain, but you wont get here!
std::cout << "oh oh, you shouldn't reach this line: "
<< to_iso_string(wont_construct) << std::endl;
}
catch(std::exception& e) {
std::cout << " Exception: " << e.what() << std::endl;
}
return 0;
}
]]>
</programlisting>
<para>
<link linkend="top">top</link>
</para>
</section>

52
xmldoc/ex_days_alive.xml Normal file
View File

@ -0,0 +1,52 @@
<section id="date_time.examples.days_alive">
<title>Days Alive</title>
<para>
Calculate the number of days you have been living using durations and dates.
</para>
<programlisting>
<![CDATA[
/* Short example that calculates the number of days since user was born.
* Demonstrates comparisons of durations, use of the day_clock,
* and parsing a date from a string.
*/
#include "boost/date_time/gregorian/gregorian.hpp"
#include <iostream>
int
main()
{
using namespace boost::gregorian;
std::string s;
std::cout << "Enter birth day YYYY-MM-DD (eg: 2002-02-01): ";
std::cin >> s;
try {
date birthday(from_simple_string(s));
date today = day_clock::local_day();
days days_alive = today - birthday;
days one_day(1);
if (days_alive == one_day) {
std::cout << "Born yesterday, very funny" << std::endl;
}
else if (days_alive < days(0)) {
std::cout << "Not born yet, hmm: " << days_alive.days()
<< " days" <<std::endl;
}
else {
std::cout << "Days alive: " << days_alive.days() << std::endl;
}
}
catch(...) {
std::cout << "Bad date entered: " << s << std::endl;
}
return 0;
}
]]>
</programlisting>
<para>
<link linkend="top">top</link>
</para>
</section>

43
xmldoc/ex_days_between_new_years.xml Normal file
View File

@ -0,0 +1,43 @@
<section id="date_time.examples.days_between_new_year">
<title>Days Between New Years</title>
<para>
Calculate the number of days till new years
</para>
<programlisting>
<![CDATA[
/* Provides a simple example of using a date_generator, and simple
* mathematical operatorations, to calculate the days since
* New Years day of this year, and days until next New Years day.
*
* Expected results:
* Adding together both durations will produce 366 (365 in a leap year).
*/
#include <iostream>
#include "boost/date_time/gregorian/gregorian.hpp"
int
main()
{
using namespace boost::gregorian;
date today = day_clock::local_day();
partial_date new_years_day(1,Jan);
//Subtract two dates to get a duration
days days_since_year_start = today - new_years_day.get_date(today.year());
std::cout << "Days since Jan 1: " << days_since_year_start.days()
<< std::endl;
days days_until_year_start = new_years_day.get_date(today.year()+1) - today;
std::cout << "Days until next Jan 1: " << days_until_year_start.days()
<< std::endl;
return 0;
};
]]>
</programlisting>
<para>
<link linkend="top">top</link>
</para>
</section>

53
xmldoc/ex_end_of_month_day.xml Normal file
View File

@ -0,0 +1,53 @@
<section id="date_time.examples.end_of_month_day">
<title>End of the Months</title>
<para>
Iterates accross the remaining months in a given year, always landing on the last day of the month.
</para>
<programlisting>
<![CDATA[
/* Simple program that uses the gregorian calendar to find the last
* day of the month and then display the last day of every month left
* in the year.
*/
#include "boost/date_time/gregorian/gregorian.hpp"
#include <iostream>
int
main()
{
using namespace boost::gregorian;
std::cout << " Enter Year(ex: 2002): ";
int year, month;
std::cin >> year;
std::cout << " Enter Month(1..12): ";
std::cin >> month;
try {
int day = gregorian_calendar::end_of_month_day(year,month);
date end_of_month(year,month,day);
//Iterate thru by months --
month_iterator mitr(end_of_month,1);
date start_of_next_year(year+1, Jan, 1);
//loop thru the days and print each one
while (mitr < start_of_next_year){
std::cout << to_simple_string(*mitr) << std::endl;
++mitr;
}
}
catch(...) {
std::cout << "Invalid Date Entered" << std::endl;
}
return 0;
}
]]>
</programlisting>
<para>
<link linkend="top">top</link>
</para>
</section>

97
xmldoc/ex_local_utc_conversion.xml Normal file
View File

@ -0,0 +1,97 @@
<section id="date_time.examples.local_utc_conversion">
<title>Local to UTC Conversion</title>
<para>
Demonstrate utc to local and local to utc calculations including dst.
</para>
<programlisting>
<![CDATA[
/* Demonstrate conversions between a local time and utc
* Output:
*
* UTC <--> New York while DST is NOT active (5 hours)
* 2001-Dec-31 19:00:00 in New York is 2002-Jan-01 00:00:00 UTC time
* 2002-Jan-01 00:00:00 UTC is 2001-Dec-31 19:00:00 New York time
*
* UTC <--> New York while DST is active (4 hours)
* 2002-May-31 20:00:00 in New York is 2002-Jun-01 00:00:00 UTC time
* 2002-Jun-01 00:00:00 UTC is 2002-May-31 20:00:00 New York time
*
* UTC <--> Arizona (7 hours)
* 2002-May-31 17:00:00 in Arizona is 2002-Jun-01 00:00:00 UTC time
*/
#include "boost/date_time/posix_time/posix_time.hpp"
#include "boost/date_time/local_time_adjustor.hpp"
#include "boost/date_time/c_local_time_adjustor.hpp"
#include <iostream>
int
main()
{
using namespace boost::posix_time;
using namespace boost::gregorian;
//This local adjustor depends on the machine TZ settings-- highly dangerous!
typedef boost::date_time::c_local_adjustor<ptime> local_adj;
ptime t10(date(2002,Jan,1), hours(7));
ptime t11 = local_adj::utc_to_local(t10);
std::cout << "UTC <--> Zone base on TZ setting" << std::endl;
std::cout << to_simple_string(t11) << " in your TZ is "
<< to_simple_string(t10) << " UTC time "
<< std::endl;
time_duration td = t11 - t10;
std::cout << "A difference of: "
<< to_simple_string(td) << std::endl;
//eastern timezone is utc-5
typedef boost::date_time::local_adjustor<ptime, -5, us_dst> us_eastern;
ptime t1(date(2001,Dec,31), hours(19)); //5 hours b/f midnight NY time
std::cout << "\nUTC <--> New York while DST is NOT active (5 hours)"
<< std::endl;
ptime t2 = us_eastern::local_to_utc(t1);
std::cout << to_simple_string(t1) << " in New York is "
<< to_simple_string(t2) << " UTC time "
<< std::endl;
ptime t3 = us_eastern::utc_to_local(t2);//back should be the same
std::cout << to_simple_string(t2) << " UTC is "
<< to_simple_string(t3) << " New York time "
<< "\n\n";
ptime t4(date(2002,May,31), hours(20)); //4 hours b/f midnight NY time
std::cout << "UTC <--> New York while DST is active (4 hours)" << std::endl;
ptime t5 = us_eastern::local_to_utc(t4);
std::cout << to_simple_string(t4) << " in New York is "
<< to_simple_string(t5) << " UTC time "
<< std::endl;
ptime t6 = us_eastern::utc_to_local(t5);//back should be the same
std::cout << to_simple_string(t5) << " UTC is "
<< to_simple_string(t6) << " New York time "
<< "\n" << std::endl;
//Arizona timezone is utc-7 with no dst
typedef boost::date_time::local_adjustor<ptime, -7, no_dst> us_arizona;
ptime t7(date(2002,May,31), hours(17));
std::cout << "UTC <--> Arizona (7 hours)" << std::endl;
ptime t8 = us_arizona::local_to_utc(t7);
std::cout << to_simple_string(t7) << " in Arizona is "
<< to_simple_string(t8) << " UTC time "
<< std::endl;
return 0;
}
]]>
</programlisting>
<para>
<link linkend="top">top</link>
</para>
</section>

155
xmldoc/ex_localization.xml Normal file
View File

@ -0,0 +1,155 @@
<section id="date_time.examples.localization">
<title>Localization Demonstration</title>
<para>
The boost::date_time library provides the ability to create customized locale facets. Date ordering, language, seperators, and abbreviations can be customized.
</para>
<programlisting>
<![CDATA[
/* The following shows the creation of a facet for the output of
* dates in German (please forgive me for any errors in my German --
* I'm not a native speaker).
*/
#include "boost/date_time/gregorian/gregorian.hpp"
#include <iostream>
/* Define a series of char arrays for short and long name strings to be
* associated with date output. */
const char* const de_short_month_names[] =
{
"Jan", "Feb", "Mar", "Apr", "Mai", "Jun",
"Jul", "Aug", "Sep", "Okt", "Nov", "Dez", "NAM"
};
const char* const de_long_month_names[] =
{
"Januar", "Februar", "Marz", "April", "Mai",
"Juni", "Juli", "August", "September", "Oktober",
"November", "Dezember", "NichtDerMonat"
};
const char* const de_special_value_names[] =
{
"NichtDatumzeit", "-unbegrenztheit", "+unbegrenztheit"
};
const char* const de_long_weekday_names[] =
{
"Sonntag", "Montag", "Dienstag", "Mittwoch",
"Donnerstag", "Freitag", "Samstag"
};
const char* const de_short_weekday_names[] =
{
"Son", "Mon", "Die","Mit", "Don", "Fre", "Sam"
};
const char* const us_short_month_names[] =
{
"Jan", "Feb", "Mar", "Apr", "May", "Jun",
"Jul", "Aug", "Sep", "Oct", "Nov", "Dec", "NAD"
};
const char* const us_long_month_names[] =
{
"January", "February", "March", "April", "May",
"June", "July", "August", "September", "October",
"November", "December", "Not-A-Date"
};
const char* const us_special_value_names[] =
{
"Not-A-Date", "-infinity", "+infinity"
};
const char* const us_long_weekday_names[] =
{
"Sunday", "Monday", "Tuesday", "Wenesday",
"Thursday", "Friday", "Saturday"
};
const char* const us_short_weekday_names[] =
{
"Sun", "Mon", "Tue","Wed", "Thu", "Fri", "Sat"
};
int
main()
{
#ifndef BOOST_DATE_TIME_NO_LOCALE
using namespace boost::gregorian;
typedef boost::date_time::all_date_names_put<greg_facet_config> date_facet;
//create a new local
std::locale default_locale;
std::locale german_dates1(default_locale,
new date_facet(de_short_month_names,
de_long_month_names,
de_special_value_names,
de_short_weekday_names,
de_long_weekday_names,
'.',
boost::date_time::ymd_order_dmy,
boost::date_time::month_as_integer));
date d1(2002, Oct, 1);
std::cout.imbue(german_dates1);
// output the date in German using short month names
std::cout << d1 << std::endl; //01.10.2002
std::locale german_dates2(default_locale,
new date_facet(de_short_month_names,
de_long_month_names,
de_special_value_names,
de_short_weekday_names,
de_long_weekday_names,
'.',
boost::date_time::ymd_order_dmy,
boost::date_time::month_as_long_string));
std::cout.imbue(german_dates2);
greg_month m = d1.month();
std::cout << m << std::endl; //Oktober
greg_weekday wd = d1.day_of_week();
std::cout << wd << std::endl; //Dienstag
//Numeric date format with US month/day/year ordering
std::locale usa_dates1(default_locale,
new date_facet(us_short_month_names,
us_long_month_names,
us_special_value_names,
us_short_weekday_names,
us_long_weekday_names,
'/',
boost::date_time::ymd_order_us,
boost::date_time::month_as_integer));
std::cout.imbue(usa_dates1);
std::cout << d1 << std::endl; // 10/01/2002
//English names, iso order (year-month-day), '-' separator
std::locale usa_dates2(default_locale,
new date_facet(us_short_month_names,
us_long_month_names,
us_special_value_names,
us_short_weekday_names,
us_long_weekday_names,
'-',
boost::date_time::ymd_order_iso,
boost::date_time::month_as_short_string));
std::cout.imbue(usa_dates2);
std::cout << d1 << std::endl; // 2002-Oct-01
#else
std::cout << "Sorry, localization is not supported by this compiler/library"
<< std::endl;
#endif
return 0;
}
]]>
</programlisting>
<para>
<link linkend="top">top</link>
</para>
</section>

113
xmldoc/ex_print_holidays.xml Normal file
View File

@ -0,0 +1,113 @@
<section id="date_time.examples.print_holidays">
<title>Print Holidays</title>
<para>
This is an example of using functors to define a holiday schedule
</para>
<programlisting>
<![CDATA[
/* Generate a set of dates using a collection of date generators
* Output looks like:
* Enter Year: 2002
* 2002-Jan-01 [Tue]
* 2002-Jan-21 [Mon]
* 2002-Feb-12 [Tue]
* 2002-Jul-04 [Thu]
* 2002-Sep-02 [Mon]
* 2002-Nov-28 [Thu]
* 2002-Dec-25 [Wed]
* Number Holidays: 7
*/
#include "boost/date_time/gregorian/gregorian.hpp"
#include <algorithm>
#include <functional>
#include <vector>
#include <iostream>
#include <set>
void
print_date(boost::gregorian::date d)
{
using namespace boost::gregorian;
#if defined(BOOST_DATE_TIME_NO_LOCALE)
std::cout << to_simple_string(d) << " [" << d.day_of_week() << "]\n";
#else
std::cout << d << " [" << d.day_of_week() << "]\n";
#endif
}
int
main() {
std::cout << "Enter Year: ";
int year;
std::cin >> year;
using namespace boost::gregorian;
//define a collection of holidays fixed by month and day
std::vector<partial_date> holidays;
holidays.push_back(partial_date(1,Jan)); //Western New Year
holidays.push_back(partial_date(4,Jul)); //US Independence Day
holidays.push_back(partial_date(25, Dec));//Christmas day
//define a shorthand for the nth_day_of_the_week_in_month function object
typedef nth_day_of_the_week_in_month nth_dow;
//define a collection of nth kday holidays
std::vector<nth_dow> more_holidays;
//US labor day
more_holidays.push_back(nth_dow(nth_dow::first, Monday, Sep));
//MLK Day
more_holidays.push_back(nth_dow(nth_dow::third, Monday, Jan));
//Pres day
more_holidays.push_back(nth_dow(nth_dow::second, Tuesday, Feb));
//Thanksgiving
more_holidays.push_back(nth_dow(nth_dow::fourth, Thursday, Nov));
typedef std::set<date> date_set;
date_set all_holidays;
#if (defined(BOOST_MSVC) && (_MSC_VER <= 1200)) // 1200 == VC++ 6.0
std::cout << "Sorry, this example temporarily disabled on VC 6.\n"
<< "The std::transform isn't accepted by the compiler\n"
<< "So if you hack up the example without std::transform\n"
<< "it should work\n"
<< std::endl;
#else
//generate a set of concrete dates from the 'partial_date' holidays
//by calling the get_date functions
std::transform(holidays.begin(), holidays.end(),
std::insert_iterator<date_set>(all_holidays, all_holidays.begin()),
std::bind2nd(std::mem_fun_ref(&partial_date::get_date),
year));
//Now add in the 'floating' holidays
std::transform(more_holidays.begin(), more_holidays.end(),
std::insert_iterator<date_set>(all_holidays, all_holidays.begin()),
std::bind2nd(std::mem_fun_ref(&nth_dow::get_date),
year));
//print the holidays to the screen
std::for_each(all_holidays.begin(), all_holidays.end(), print_date);
std::cout << "Number Holidays: " << all_holidays.size() << std::endl;
#endif
return 0;
}
]]>
</programlisting>
<para>
<link linkend="top">top</link>
</para>
</section>

60
xmldoc/ex_print_hours.xml Normal file
View File

@ -0,0 +1,60 @@
<section id="date_time.examples.print_hours">
<title>Print Hours</title>
<para>
Demonstrate time iteration, clock retrieval, and simple calculation.
</para>
<programlisting>
<![CDATA[
/* Print the remaining hours of the day
* Uses the clock to get the local time
* Use an iterator to iterate over the remaining hours
* Retrieve the date part from a time
*
* Expected Output something like:
*
* 2002-Mar-08 16:30:59
* 2002-Mar-08 17:30:59
* 2002-Mar-08 18:30:59
* 2002-Mar-08 19:30:59
* 2002-Mar-08 20:30:59
* 2002-Mar-08 21:30:59
* 2002-Mar-08 22:30:59
* 2002-Mar-08 23:30:59
* Time left till midnight: 07:29:01
*/
#include "boost/date_time/posix_time/posix_time.hpp"
#include <iostream>
int
main()
{
using namespace boost::posix_time;
using namespace boost::gregorian;
//get the current time from the clock -- one second resolution
ptime now = second_clock::local_time();
//Get the date part out of the time
date today = now.date();
date tommorrow = today + days(1);
ptime tommorrow_start(tommorrow); //midnight
//iterator adds by one hour
time_iterator titr(now,hours(1));
for (; titr < tommorrow_start; ++titr) {
std::cout << to_simple_string(*titr) << std::endl;
}
time_duration remaining = tommorrow_start - now;
std::cout << "Time left till midnight: "
<< to_simple_string(remaining) << std::endl;
return 0;
}
]]>
</programlisting>
<para>
<link linkend="top">top</link>
</para>
</section>

68
xmldoc/ex_print_month.xml Normal file
View File

@ -0,0 +1,68 @@
<section id="date_time.examples.print_month">
<title>Print Month</title>
<para>
Simple utility to print out days of the month with the days of a month. Demontstrates date iteration (date_time::date_itr).
</para>
<programlisting>
<![CDATA[
/* This example prints all the dates in a month. It demonstrates
* the use of iterators as well as functions of the gregorian_calendar
*
* Output:
* Enter Year: 2002
* Enter Month(1..12): 2
* 2002-Feb-01 [Fri]
* 2002-Feb-02 [Sat]
* 2002-Feb-03 [Sun]
* 2002-Feb-04 [Mon]
* 2002-Feb-05 [Tue]
* 2002-Feb-06 [Wed]
* 2002-Feb-07 [Thu]
*/
#include "boost/date_time/gregorian/gregorian.hpp"
#include <iostream>
int
main()
{
std::cout << "Enter Year: ";
int year, month;
std::cin >> year;
std::cout << "Enter Month(1..12): ";
std::cin >> month;
using namespace boost::gregorian;
try {
//Use the calendar to get the last day of the month
int eom_day = gregorian_calendar::end_of_month_day(year,month);
date endOfMonth(year,month,eom_day);
//construct an iterator starting with firt day of the month
day_iterator ditr(date(year,month,1));
//loop thru the days and print each one
for (; ditr <= endOfMonth; ++ditr) {
#if defined(BOOST_DATE_TIME_NO_LOCALE)
std::cout << to_simple_string(*ditr) << " ["
#else
std::cout << *ditr << " ["
#endif
<< ditr->day_of_week() << "]"
<< std::endl;
}
}
catch(std::exception& e) {
std::cout << "Error bad date, check your entry: \n"
<< " Details: " << e.what() << std::endl;
}
return 0;
}
]]>
</programlisting>
<para>
<link linkend="top">top</link>
</para>
</section>

42
xmldoc/ex_time_math.xml Normal file
View File

@ -0,0 +1,42 @@
<section id="date_time.examples.time_math">
<title>Time Math</title>
<para>
Various types of calculations with times and time durations.
</para>
<programlisting>
<![CDATA[
/* Some simple examples of constructing and calculating with times
* Output:
* 2002-Feb-01 00:00:00 - 2002-Feb-01 05:04:02.001000000 = -5:04:02.001000000
*/
#include "boost/date_time/posix_time/posix_time.hpp"
#include <iostream>
int
main()
{
using namespace boost::posix_time;
using namespace boost::gregorian;
date d(2002,Feb,1); //an arbitrary date
//construct a time by adding up some durations durations
ptime t1(d, hours(5)+minutes(4)+seconds(2)+millisec(1));
//construct a new time by subtracting some times
ptime t2 = t1 - hours(5)- minutes(4)- seconds(2)- millisec(1);
//construct a duration by taking the difference between times
time_duration td = t2 - t1;
std::cout << to_simple_string(t2) << " - "
<< to_simple_string(t1) << " = "
<< to_simple_string(td) << std::endl;
return 0;
}
]]>
</programlisting>
<para>
<link linkend="top">top</link>
</para>
</section>

65
xmldoc/ex_time_periods.xml Normal file
View File

@ -0,0 +1,65 @@
<section id="date_time.examples.time_periods">
<title>Time Periods</title>
<para>
Demonstrate some simple uses of time periods.
</para>
<programlisting>
<![CDATA[
/* Some simple examples of constructing and calculating with times
* Returns:
* [2002-Feb-01 00:00:00/2002-Feb-01 23:59:59.999999999] contains 2002-Feb-01 03:00:05
* [2002-Feb-01 00:00:00/2002-Feb-01 23:59:59.999999999] intersected with
* [2002-Feb-01 00:00:00/2002-Feb-01 03:00:04.999999999] is
* [2002-Feb-01 00:00:00/2002-Feb-01 03:00:04.999999999]
*/
#include "boost/date_time/posix_time/posix_time.hpp"
#include <iostream>
using namespace boost::posix_time;
using namespace boost::gregorian;
//Create a simple period class to contain all the times in a day
class day_period : public time_period
{
public:
day_period(date d) : time_period(ptime(d),//midnight
ptime(d,hours(24)))
{}
};
int
main()
{
date d(2002,Feb,1); //an arbitrary date
//a period that represents a day
day_period dp(d);
ptime t(d, hours(3)+seconds(5)); //an arbitray time on that day
if (dp.contains(t)) {
std::cout << to_simple_string(dp) << " contains "
<< to_simple_string(t) << std::endl;
}
//a period that represents part of the day
time_period part_of_day(ptime(d, hours(0)), t);
//intersect the 2 periods and print the results
if (part_of_day.intersects(dp)) {
time_period result = part_of_day.intersection(dp);
std::cout << to_simple_string(dp) << " intersected with\n"
<< to_simple_string(part_of_day) << " is \n"
<< to_simple_string(result) << std::endl;
}
return 0;
}
]]>
</programlisting>
<para>
<link linkend="top">top</link>
</para>
</section>

20
xmldoc/examples.xml Normal file
View File

@ -0,0 +1,20 @@
<section id="date_time.examples" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Examples</title>
<!-- gregorian examples -->
<xi:include href="usage_examples.xml"/>
<xi:include href="ex_dates_as_strings.xml"/>
<xi:include href="ex_days_alive.xml"/>
<xi:include href="ex_days_between_new_years.xml"/>
<xi:include href="ex_end_of_month_day.xml"/>
<xi:include href="ex_localization.xml"/>
<xi:include href="ex_date_period_calc.xml"/>
<xi:include href="ex_print_holidays.xml"/>
<xi:include href="ex_print_month.xml"/>
<!-- posix_time examples -->
<xi:include href="ex_time_math.xml"/>
<xi:include href="ex_print_hours.xml"/>
<xi:include href="ex_local_utc_conversion.xml"/>
<xi:include href="ex_time_periods.xml"/>
</section>

68
xmldoc/gregorian.xml Normal file
View File

@ -0,0 +1,68 @@
<section id="date_time.gregorian"
xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Gregorian</title>
<bridgehead renderas="sect2">Gregorian Date System</bridgehead>
<para>
<link linkend="greg_intro">Introduction</link> --
<link linkend="greg_ex">Usage Examples</link>
</para>
<anchor id="greg_intro" />
<bridgehead renderas="sect3">Introduction</bridgehead>
<para>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.
</para>
<para>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 <ulink url="http://emr.cs.iit.edu/home/reingold/calendar-book/second-edition">Calendrical Calculations</ulink> by Reingold &amp; Dershowitz for more details. Date information from Calendrical Calculations has been used to cross-test the correctness of the Gregorian calendar implementation.
</para>
<para>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.
</para>
<para>The class <link linkend="date_time.gregorian.date_class">boost::gregorian::date</link> 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 <link linkend="date_time.gregorian.date_algorithms">generators and algorithms page</link>.
</para>
<anchor id="greg_ex" />
<bridgehead renderas="sect3">Usage Examples</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="2">
<thead>
<row>
<entry>Example</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><link linkend="date_time.examples.days_alive">Days Alive</link> <link linkend="date_time.examples.days_till_new_year">Days Till New Year</link></entry>
<entry>Simple date arithmetic. Retrieve current day from clock.</entry>
</row>
<row>
<entry><link linkend="date_time.examples.dates_as_strings">Dates as strings</link></entry>
<entry>Simple parsing and formatting of dates from/to strings</entry>
</row>
<row>
<entry><link linkend="date_time.examples.date_period_calc">Date Period Calculations</link></entry>
<entry>See if a date is in a set of date periods (eg: is it a holiday/weekend)</entry>
</row>
<row>
<entry><link linkend="date_time.examples.print_month">Print a month</link></entry>
<entry>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.</entry>
</row>
<row>
<entry><link linkend="date_time.examples.print_holidays">Print Holidays</link></entry>
<entry>Uses date generators to convert abstract specification into concrete set of dates.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<xi:include href="date_class.xml" />
<xi:include href="date_duration.xml" />
<xi:include href="date_period.xml" />
<xi:include href="date_iterators.xml" />
<xi:include href="date_algorithms.xml" />
<xi:include href="gregorian_calendar.xml" />
<xi:include href="day_clock_class.xml" />
<link linkend="top">top</link>
</section>

73
xmldoc/gregorian_calendar.xml Normal file
View File

@ -0,0 +1,73 @@
<section id="date_time.gregorian.gregorian_calendar">
<title>Gregorian Calendar</title>
<link linkend="gregcal_intro">Introduction</link> --
<link linkend="gregcal_header">Header</link> --
<link linkend="gregcal_functions">Functions</link>
<anchor id="gregcal_intro" />
<bridgehead renderas="sect3">Introduction</bridgehead>
<para>
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.
</para>
<para>
For most purposes this class is simply accessed by <link linkend="date_time.gregorian.date_class">gregorian::date</link> 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.
</para>
<para>
The <link linkend="date_time.examples.print_month">print month</link> example demonstrates this.
</para>
<anchor id="gregcal_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="gregcal_functions" />
<bridgehead renderas="sect3">Functions</bridgehead>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>static short day_of_week(ymd_type)</entry>
<entry>Return the day of the week (0==Sunday, 1==Monday, etc)</entry>
<entry>See also <link linkend="date_time.gregorian.date_class">gregorian::date</link> day_of_week</entry>
</row>
<row>
<entry>static date_int_type day_number(ymd_type)</entry>
<entry> Convert a ymd_type into a day number. The day number is an absolute number of days since the epoch start.</entry>
<entry></entry>
</row>
<row>
<entry>static short end_of_month_day(year_type, month_type)</entry>
<entry>Given a year and month determine the last day of the month.</entry>
<entry></entry>
</row>
<row>
<entry>static ymd_type from_day_number(date_int_type)</entry>
<entry> Convert a day number to a ymd struct.</entry>
<entry></entry>
</row>
<row>
<entry>static bool is_leap_year(year_type)</entry>
<entry>Returns true if specified year is a leap year.</entry>
<entry>gregorian_calendar::is_leap_year(2000) --> true</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<link linkend="top">top</link>
</section>

35
xmldoc/license.xml Normal file
View File

@ -0,0 +1,35 @@
<?xml version="1.0" encoding="utf-8"?>
<section id="date_time.license">
<title>Boost Date-Time Library License</title>
<bridgehead renderas="sect2">Boost Date-Time Library License</bridgehead>
<!--
<ulink url="../../../index.htm">
<imagedata align="left"
format="GIF"
fileref="../../../c++boost.gif"
alt="C++ Boost" />
</ulink>-->
<!--hr /-->
<para>
The following is the overall license for the boost date_time
library. This notice is found in all source files related to the
library.
</para>
<para>
Copyright &#169; 2002 CrystalClear Software, Inc.
</para>
<para>
Permission to use, copy, modify, distribute and sell this software
and its documentation for any purpose is hereby granted without
fee, provided that the above copyright notice appear in all copies
and that both that copyright notice and this permission notice
appear in supporting documentation. CrystalClear Software makes no
representations about the suitability of this software for any
purpose. It is provided "as is" without express or implied
warranty.
</para>
<!--hr / -->
<ulink url="mailto:jeff@crystalclearsoftware.com">Jeff Garland</ulink>
&#169; 2000-2002
</section>

69
xmldoc/local_time_adjust.xml Normal file
View File

@ -0,0 +1,69 @@
<section id="date_time.posix_time.local_time_adjust">
<title>Local Time Adjustment</title>
<link linkend="local_utc_intro">Introduction</link> --
<link linkend="local_utc_header">Header</link> --
<link linkend="local_utc_overview">Overview</link>
<anchor id="local_utc_intro" />
<bridgehead renderas="sect3">Introduction</bridgehead>
<para>
A frequent problem in time representation is the conversion between various local time systems. In general this is accomplished by using a reference time system. The reference time system is typically UTC.
</para>
<para>
Since the posix_time system does no internal time adjustment it can be used to represent both local times and UTC times. However, the user is currently left to handle conversions and time zone knowledge explicitly.
</para>
<para>
The library offers two different ways to perform UTC to local conversions. The first is using the time zone settings of the computer. This is a useful solution for converting a UTC time for a user machine. This approach depends on the ctime API and will provide incorrect results if the environment is set incorrectly. The other approach allows conversion from any zone to UTC and back independent of the settings of the time zone settings of the computer. The <link linkend="date_time.examples.local_utc_conversion">local utc conversion example</link> demonstrates both of these techniques.
</para>
<anchor id="local_utc_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="local_utc_overview" />
<bridgehead renderas="sect3">Overview</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Class</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>date_time::c_local_adjustor&lt;ptime>::utc_to_local(ptime)</entry>
<entry>Calculate local machine time from a UTC time based on time zone settings and the C API.</entry>
<entry>
typedef boost::date_time::c_local_adjustor&lt;ptime> local_adj;
ptime t10(date(2002,Jan,1), hours(7));
ptime t11 = local_adj::utc_to_local(t10);
</entry>
</row>
<row>
<entry>date_time::local_adjustor&lt;ptime, utc_offset, dst_rules>::utc_to_local(ptime)</entry>
<entry>Calculate local machine time from a UTC time based daylight savings rules and utc offset</entry>
<entry><link linkend="date_time.examples.local_utc_conversion">example</link></entry>
</row>
<row>
<entry>date_time::local_adjustor&lt;ptime, utc_offset, dst_rules>::local_to_utc(ptime)</entry>
<entry>Calculate UTC time based on daylight savings rules and utc offset.</entry>
<entry><link linkend="date_time.examples.local_utc_conversion">example</link></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<link linkend="top">top</link>
</section>

15
xmldoc/motivation.xml Normal file
View File

@ -0,0 +1,15 @@
<?xml version="1.0" encoding="utf-8"?>
<section id="Motivation">
<title>Motivation</title>
<para>
The motivation for this library comes from working with and helping build several date-time libraries on several projects. Date-time libraries provide fundamental infrastructure for most development projects. However, most of them have limitations in their ability to calculate, format, convert, or perform some other functionality. For example, most libraries do not correctly handle leap seconds, provide concepts such as infinity, or provide the ability to use high resolution or network time sources. These libraries also tend to be rigid in their representation of dates and times. Thus customized policies for a project or subproject are not possible.
</para>
<para>
Programming with dates and times should be almost as simple and natural as programming with strings and integers. Applications with lots of temporal logic can be radically simplified by having a robust set of operators and calculation capabilities. Classes should provide the ability to compare dates and times, add lengths or time durations, retrieve dates and times from clocks, and work naturally with date and time intervals.
</para>
<para>
Another motivation for development of the library was to apply modern C++ library design techniques to the date-time domain. Really to build a framework for the construction of building temporal types. For example, by providing iterators and traits classes to control fundamental properties of the library. To the authors knowledge this library is the only substantial attempt to apply modern C++ to a date-time library.
</para>
</section>

57
xmldoc/posix_time.xml Normal file
View File

@ -0,0 +1,57 @@
<section id="date_time.posix_time"
xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Posix Time</title>
<bridgehead renderas="sect2">Posix Time System</bridgehead>
<para>
<link linkend="posix_intro">Introduction</link> --
<link linkend="posix_ex">Usage Examples</link>
</para>
<anchor id="posix_intro" />
<bridgehead renderas="sect3">Introduction</bridgehead>
<para>
Defines a non-adjusted time system with nano-second resolution and stable calculation properties. This time system uses the Gregorian calendar to implement the date portion of the time representation.
</para>
<anchor id="posix_ex" />
<bridgehead renderas="sect3">Usage Examples</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="2">
<thead>
<row>
<entry>Example</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><link linkend="date_time.examples.time_math">Time Math</link></entry>
<entry>A few simple calculations using ptime and time_durations.</entry>
</row>
<row>
<entry><link linkend="date_time.examples.print_hours">Print Hours</link></entry>
<entry>Retrieve time from clock, use a time_iterator.</entry>
</row>
<row>
<entry><link linkend="date_time.examples.local_utc_conversion">Local to UTC Conversion</link></entry>
<entry>Demonstrates a couple different ways to convert a local to UTC time including daylight savings rules.</entry>
</row>
<row>
<entry><link linkend="date_time.examples.time_periods">Time Periods</link></entry>
<entry>Some simple examples of intersection and display of time periods.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<xi:include href="ptime_class.xml" />
<xi:include href="time_duration.xml" />
<xi:include href="time_period.xml" />
<xi:include href="time_iterators.xml" />
<xi:include href="local_time_adjust.xml" />
<!-- includes here -->
</section>

300
xmldoc/ptime_class.xml Normal file
View File

@ -0,0 +1,300 @@
<section id="date_time.posix_time.ptime_class">
<title>Ptime Class</title>
<link linkend="ptime_intro">Introduction</link> --
<link linkend="ptime_header">Header</link> --
<link linkend="ptime_constr">Construction</link> --
<link linkend="ptime_from_string">Construct from String</link> --
<link linkend="ptime_from_clock">Construct from Clock</link> --
<link linkend="ptime_from_time_t">Construct from time_t</link> --
<link linkend="ptime_accessors">Accessors</link> --
<link linkend="ptime_to_string">Conversion To String</link> --
<link linkend="ptime_operators">Operators</link>
<anchor id="ptime_intro" />
<bridgehead renderas="sect3">Introduction</bridgehead>
<para>
The class boost::posix_time::ptime is the primary interface for time point manipulation. In general, the ptime class is immutable once constructed although it does allow assignment.
</para>
<para>
Class ptime is dependent on <link linkend="date_time.gregorian.date_class">gregorian::date</link> for the interface to the date portion of a time point.
</para>
<para>
Other techniques for creating times include <link linkend="date_time.posix_time.time_iterators">time iterators</link>.
</para>
<anchor id="ptime_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="ptime_constr" />
<bridgehead renderas="sect3">Construction</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>ptime(date,time_duration)</entry>
<entry>Construct from a date and offset</entry>
<entry>
ptime t1(date(2002,Jan,10), time_duration(1,2,3));
ptime t2(date(2002,Jan,10), hours(1)+nanosec(5));
</entry>
</row>
<row>
<entry>ptime(ptime)</entry>
<entry>Copy constructor</entry>
<entry>ptime t3(t1)</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<anchor id="ptime_from_string" />
<bridgehead renderas="sect3">Construct from String</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>ptime time_from_string(const std::string&amp;)</entry>
<entry>From delimited string.</entry>
<entry>std::string ts("2002-01-20 23:59:59.000");
ptime t(time_from_string(ts))</entry>
</row>
<row>
<entry>ptime from_iso_string(const std::string&amp;)</entry>
<entry>From non delimited iso form string.</entry>
<entry>std::string ts("20020131T235959");
ptime t(from_iso_string(ts))</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<anchor id="ptime_from_clock" />
<bridgehead renderas="sect3">Construct from Clock</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>static ptime second_clock::local_time();</entry>
<entry>Get the local time, second level resolution, based on the time zone settings of the computer.</entry>
<entry>ptime t(second_clock::local_time())</entry>
</row>
<row>
<entry>static ptime second_clock::universal_time()</entry>
<entry>Get the UTC time.</entry>
<entry>ptime t(second_clock::universal_day())</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<anchor id="ptime_from_time_t" />
<bridgehead renderas="sect3">Construct from time_t</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>ptime from_time_t(time_t t);</entry>
<entry>Converts a time_t into a ptime.</entry>
<entry>ptime t = from_time_t(tt);</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<anchor id="ptime_accessors" />
<bridgehead renderas="sect3">Accessors</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>date date() const</entry>
<entry>Get the date part of a time.</entry>
<entry>
date d(2002,Jan,10);
ptime t(d, hour(1));
t.date() --> 2002-Jan-10;
</entry>
</row>
<row>
<entry>time_duration time_of_day() const</entry>
<entry>Get the time offset in the day.</entry>
<entry>
date d(2002,Jan,10);
ptime t(d, hour(1));
t.time_of_day() --> 01:00:00;
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<anchor id="ptime_to_string" />
<bridgehead renderas="sect3">Conversion to String</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>std::string to_simple_string(ptime)</entry>
<entry>To YYYY-mmm-DD HH:MM:SS.fffffffff string where mmm 3 char month name. Fractional seconds only included if non-zero.</entry>
<entry>2002-Jan-01 10:00:01.123456789</entry>
</row>
<row>
<entry>std::string to_iso_string(ptime)</entry>
<entry>Convert to form YYYYMMDDTHHMMSS,fffffffff where T is the date-time separator</entry>
<entry>20020131T100001,123456789</entry>
</row>
<row>
<entry>std::string to_iso_extended_string(ptime)</entry>
<entry>Convert to form YYYY-MM-DDTHH:MM:SS,fffffffff where T is the date-time separator</entry>
<entry>2002-01-31T10:00:01,123456789</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<anchor id="ptime_operators" />
<bridgehead renderas="sect3">Operators</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>
operator==, operator!=,
operator>, operator&lt;
operator>=, operator&lt;=
</entry>
<entry>A full complement of comparison operators</entry>
<entry>t1 == t2, etc</entry>
</row>
<row>
<entry>ptime operator+(date_duration) const</entry>
<entry>Return a ptime adding a day offset</entry>
<entry>
date d(2002,Jan,1);
ptime t(d,minutes(5));
date_duration dd(1);
ptime t2 = t + dd;
</entry>
</row>
<row>
<entry>ptime operator-(date_duration) const</entry>
<entry>Return a ptime subtracting a day offset</entry>
<entry>
date d(2002,Jan,1);
ptime t(d,minutes(5));
date_duration dd(1);
ptime t2 = t - dd;
</entry>
</row>
<row>
<entry>ptime operator+(time_duration) const</entry>
<entry>Return a ptime adding a time duration</entry>
<entry>
date d(2002,Jan,1);
ptime t(d,minutes(5));
ptime t2 = t + hours(1) + minutes(2);
</entry>
</row>
<row>
<entry>ptime operator-(time_duration) const</entry>
<entry>Return a ptime subtracting a time duration</entry>
<entry>
date d(2002,Jan,1);
ptime t(d,minutes(5));
ptime t2 = t - minutes(2);
</entry>
</row>
<row>
<entry>time_duration operator-(ptime) const</entry>
<entry>Take the difference between two times.</entry>
<entry>
date d(2002,Jan,1);
ptime t1(d,minutes(5));
ptime t2(d,seconds(5));
time_duration t3 = t2 - t1;//negative result
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<link linkend="top">top</link>
</section>

114
xmldoc/references.xml Normal file
View File

@ -0,0 +1,114 @@
<section id="date_time.references">
<title>References</title>
<para>
<itemizedlist mark="bullet">
<listitem><link linkend="date_ref">Date References</link></listitem>
<listitem><link linkend="time_ref">Time References</link></listitem>
<listitem><link linkend="other_c_libs">Other C/C++ Libraries</link></listitem>
<listitem><link linkend="java_libs">JAVA Date-Time Libraries</link></listitem>
<listitem><link linkend="script_libs">Scripting Language Libraries</link></listitem>
<listitem><link linkend="related">Related Commercial and Fanciful Pages</link></listitem>
<listitem><link linkend="resolution">Resolution, Precision, and Accuracy</link></listitem>
</itemizedlist>
</para>
<anchor id="date_ref" />
<bridgehead renderas="sect3">Date Calendar References</bridgehead>
<para>
<itemizedlist mark="bullet">
<listitem>ISO 8601 date time standard -- <ulink url="http://www.cl.cam.ac.uk/~mgk25/iso-time.html">Summary by Markus Kuhn</ulink> </listitem>
<listitem><ulink url="http://emr.cs.iit.edu/home/reingold/calendar-book/second-edition/">Calendrical Calculations</ulink> book by Reingold &amp; Dershowitz</listitem>
<listitem><ulink url="http://www.tondering.dk/claus/calendar.html">Calendar FAQ by Claus Tøndering</ulink></listitem>
<listitem>Calendar zone <ulink url="http://www.calendarzone.com" /> </listitem>
<listitem><ulink url="http://www.w3.org/TR/xmlschema-2/#dateTime">XML schema for date time</ulink> </listitem>
<listitem>Will Linden's <ulink url="http://www.ecben.net/calendar.shtml">Calendar Links</ulink> </listitem>
<listitem><ulink url="http://www21.brinkster.com/lonwolve/melt/index.htm">XMAS calendar melt</ulink> </listitem>
</itemizedlist>
</para>
<anchor id="time_ref" />
<bridgehead renderas="sect3">Time</bridgehead>
<para>
<itemizedlist mark="bullet">
<listitem>Martin Folwer on time patterns
<itemizedlist override="opencircle">
<listitem><ulink url="http://www.aw.com/cseng/titles/0-201-89542-0/apsupp/events2-1.html">Recurring Events for Calendars</ulink> </listitem>
<listitem>Patterns for things that <ulink url="http://martinfowler.com/ap2/timeNarrative.html">Change with time</ulink> </listitem>
</itemizedlist>
</listitem>
<listitem>US National Institute of Standards and Technology <ulink url="http://nist.time.gov/exhibits.html">Time Exhibits</ulink> </listitem>
<listitem>Network Time Protocol at <ulink url="http://www.ntp.org/">NTP.org</ulink> </listitem>
<listitem>US Navy <ulink url="http://tycho.usno.navy.mil/systime.html">Systems of Time</ulink> </listitem>
<listitem><ulink url="http://www.bipm.fr/enus/5_Scientific/c_time/time_1.html">International Atomic Time</ulink> </listitem>
<listitem><ulink url="http://beta.zyprexia.com/docs/pgsql/user/datatype1130.htm">Date-Time type PostgreSQL</ulink> User Guide </listitem>
</itemizedlist>
</para>
<anchor id="other_c_libs" />
<bridgehead renderas="sect3">Other C/C++ Libraries</bridgehead>
<para>
<itemizedlist mark="bullet">
<listitem><ulink url="http://www.cplusplus.com/ref/ctime/index.html">ctime C</ulink> Standard library reference at cplusplus.com</listitem>
<listitem><ulink url="http://www.cl.cam.ac.uk/~mgk25/c-time/">XTime C extension</ulink> proposal</listitem>
<listitem><ulink url="http://david.tribble.com/text/c0xcalendar.html#author-info">Another C library extension proposal</ulink> by David Tribble</listitem>
<listitem><ulink url="http://cr.yp.to/libtai.html">libTAI</ulink> is a C based time library</listitem>
<listitem><ulink url="http://www.twinsun.com/tz/tz-link.htm">Time Zone Database</ulink> C library for managing timezones/places</listitem>
<listitem>International Components for Unicode by IBM (open source)
<itemizedlist override="opencircle">
<listitem><ulink url="http://oss.software.ibm.com/icu/userguide/dateCalendar.html">Calendar Class</ulink></listitem>
<listitem><ulink url="http://oss.software.ibm.com/icu/userguide/dateTime.html">Date Time Services</ulink></listitem>
<listitem><ulink url="http://oss.software.ibm.com/icu/userguide/dateTimezone.html">Time Zone Class</ulink></listitem>
<listitem><ulink url="http://oss.software.ibm.com/icu/userguide/formatDateTime.html">Date-Time Formatting</ulink></listitem>
</itemizedlist>
</listitem>
<listitem><ulink url="http://ringside.arc.nasa.gov/www/toolkits/julian_13/aareadme.html">Julian Library in C by Mark Showalter -- NASA</ulink></listitem>
</itemizedlist>
</para>
<anchor id="java_libs" />
<bridgehead renderas="sect3">JAVA Date &amp; Time Library Quick Reference</bridgehead>
<para>
<itemizedlist mark="bullet">
<listitem><ulink url="http://java.sun.com/products/jdk/1.1/docs/api/java.util.Calendar.html#_top_">Calendar class</ulink></listitem>
<listitem><ulink url="http://java.sun.com/products/jdk/1.1/docs/api/java.util.GregorianCalendar.html#_top_">Gregorian calendar</ulink></listitem>
<listitem><ulink url="http://java.sun.com/products/jdk/1.1/docs/api/java.util.Date.html">Date class</ulink></listitem>
<listitem><ulink url="http://java.sun.com/products/jdk/1.1/docs/api/java.sql.Time.html#_top_">sql.time class</ulink></listitem>
<listitem><ulink url="http://java.sun.com/products/jdk/1.1/docs/api/java.text.DateFormatSymbols.html#_top_">Date format symbols</ulink></listitem>
<listitem><ulink url="http://java.sun.com/products/jdk/1.1/docs/api/java.text.DateFormat.html#_top_">Date format</ulink></listitem>
<listitem><ulink url="http://java.sun.com/products/jdk/1.1/docs/api/java.text.SimpleDateFormat.html#_top_">Simple Date Format</ulink></listitem>
<listitem><ulink url="http://java.sun.com/products/jdk/1.1/docs/api/java.util.SimpleTimeZone.html#_top_">Simple Time Zone</ulink></listitem>
</itemizedlist>
</para>
<anchor id="script_libs" />
<bridgehead renderas="sect3">Scripting Language Libraries</bridgehead>
<para>
<itemizedlist mark="bullet">
<listitem>A python date library <ulink url="http://www.lemburg.com/files/python/mxDateTime.html">MX Date Time</ulink></listitem>
<listitem>Perl date-time
<itemizedlist override="opencircle">
<listitem><ulink url="http://search.cpan.org/Catalog/Data_and_Data_Type/Date">Date-Time packages at CPAN</ulink></listitem>
<listitem><ulink url="http://search.cpan.org/doc/TWEGNER/Date-Calc-4.3-bin56Mac/Calc.pm">Date::Calc</ulink> at CPAN</listitem>
<listitem><ulink url="http://search.cpan.org/doc/MORTY/DateConvert-0.16/Convert.pm">Date::Convert</ulink> calendar conversions at CPAN</listitem>
</itemizedlist>
</listitem>
<listitem>A PHP library <ulink url="http://vlib.activefish.com/docs/vlibDate.html">Vlib Date Library</ulink></listitem>
</itemizedlist>
</para>
<anchor id="related" />
<bridgehead renderas="sect3">Related Commercial and Fanciful Pages</bridgehead>
<para>
<itemizedlist mark="bullet">
<listitem><ulink url="http://www.leapsecond.com/java/gpsclock.htm">Leapsecond.com time</ulink> page</listitem>
<listitem><ulink url="http://www.worldtimeserver.com">World Time Server / TZ database</ulink></listitem>
<listitem><ulink url="http://www.longnow.org/10kclock/clock.htm">10000 year clock</ulink> at Long Now Foundation</listitem>
<listitem><ulink url="http://www.timezonesforpcs.com">Timezones for PCs</ulink></listitem>
</itemizedlist>
</para>
<anchor id="resolution" />
<bridgehead renderas="sect3">Resolution, Precision, and Accuracy</bridgehead>
<para>
<itemizedlist mark="bullet">
<listitem>Definitions with pictures from <ulink url="http://metrologyforum.tm.agilent.com/specs.shtml">Agilent Technologies</ulink></listitem>
<listitem>Another set of pictures from <ulink url="http://www.teamlabs.com/catalog/performance.asp">Team Labs</ulink></listitem>
<listitem>Definitions from <ulink url="http://www.solent.ac.uk/hydrography/notes/errorthe/accuracy.htm">Southampton Institute</ulink></listitem>
<listitem>Definitions from <ulink url="http://www.newport.com/Support/Tutorials/OptoMech/om4a.asp">Newport Corporation</ulink> in the context of instrumentation</listitem>
</itemizedlist>
</para>
</section>

77
xmldoc/serialization.xml Normal file
View File

@ -0,0 +1,77 @@
<section id="date_time.serialization">
<title>Serialization</title>
<para>
The boost::date_time library is compatible with the boost::serialization library (currently in review for final acceptance into boost). The list of classes that are serializable are:
</para>
<bridgehead renderas="sect3">boost::gregorian</bridgehead>
<informaltable frame="all" pgwide="1">
<tgroup cols="3">
<tbody>
<row>
<entry>date</entry>
<entry>date_duration</entry>
<entry>date_period</entry>
</row>
<row>
<entry>partial_date</entry>
<entry>nth_day_of_week_in_month</entry>
<entry>first_day_of_week_in_month</entry>
</row>
<row>
<entry>last_day_of_week_in_month</entry>
<entry>first_day_of_week_before</entry>
<entry>first_day_of_week_after</entry>
</row>
<row>
<entry>greg_month</entry>
<entry>greg_day</entry>
<entry>greg_weekday</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<bridgehead renderas="sect3">boost::posix_time</bridgehead>
<informaltable frame="all" pgwide="1">
<tgroup cols="3">
<tbody>
<row>
<entry>ptime</entry>
<entry>time_duration</entry>
<entry>time_period</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
Note* These classes have been tested with text_archives. The serialization routines were written with xml archives in mind, however, no tests are currently available (at time of writing xml archives were not parsed correctly). Xml archive tests will be added as soon as the problem is resolved.
</para>
<para>
No extra steps are required to build the date_time library for serialization use.
</para>
<para>
To use the date_time serialization code, the proper header files must be explicitly included. The header files are:
<programlisting>
boost/date_time/gregorian/greg_serialize.hpp
</programlisting>
and
<programlisting>
boost/date_time/posix_time/time_serialize.hpp
</programlisting>
</para>
<para>
Tests exist for serialization of the above mentioned classes but are not run by default. To run these test suites a global variable must be set on the command line.
<programlisting>
bjam “-sBOOST_DATE_TIME_SERIALIZATION=true” ...
</programlisting>
This will run the date_time_serialization suite along with the rest of the date_time tests.
</para>
</section>

51
xmldoc/terminology.xml Normal file
View File

@ -0,0 +1,51 @@
<section id="date_time.terminology">
<title>Terminology</title>
<para>
The following are a number of terms relevant to the date-time domain.
</para>
<para>
A taxonomy of temporal types:
<itemizedlist mark="bullet">
<listitem>Timepoint -- Specifier for a location in the time continuum. Similar to a number on a ruler.</listitem>
<listitem>Timelength -- A duration of time unattached to any point on the time continuum.</listitem>
<listitem>Timeinterval -- A duration of time attached to a specific point in the time continuum.</listitem>
</itemizedlist>
</para>
<para>
And some other terms:
<itemizedlist mark="bullet">
<listitem>Accuracy -- A measure of error, the difference between the reading of a clock and the true time.</listitem>
<listitem>Calendar System -- A system for labeling time points with day level resolution.</listitem>
<listitem>Clock Device -- A software component (tied to some hardware) that provides the current date or time with respect to a calendar or clock system.</listitem>
<listitem>Precision -- A measure of repeatability of a clock.</listitem>
<listitem>Resolution -- A specification of the smallest representable duration (eg: 1 second, 1 century) for a clock/calendar system or temporal type.</listitem>
<listitem>Stability -- The property of a class which says that the underlying representation (implementation) associated with a particular (abstract) value will never change.</listitem>
<listitem>Time System -- A system for labeling time points with higher resolution than day-level. </listitem>
</itemizedlist>
</para>
<para>
Some standard date-time terminology:
<itemizedlist mark="bullet">
<listitem>Epoch -- Starting time point of a calendar or clock system.</listitem>
<listitem>DST -- Daylight savings time - a local time adjustment made in some regions during the summer to shift the clock time of the daylight hours</listitem>
<listitem>Time zone -- A region of the earth that provides for a 'local time' defined by DST rules and UT offset.</listitem>
<listitem>UTC Time -- Coordinated Universal Time - Civil time system as measured at longitude zero. Kept adjusted to earth rotation by use of leap seconds. Also known as Zulu Time. Replaced the similar system known as Greenwich Mean Time. For more see <ulink url="http://aa.usno.navy.mil/faq/docs/UT.html" /></listitem>
<listitem>TAI Time -- A high-accuracy monotonic (need better term) time system measured to .1 microsecond resolution by atomic clocks around the world. Not adjusted to earth rotation. For more see <ulink url="http://www.bipm.fr/enus/5_Scientific/c_time/time_server.html" /></listitem>
</itemizedlist>
</para>
<para>
Some more experimental ones:
<itemizedlist mark="bullet">
<listitem>Local Time -- A time measured in a specific location of the universe.</listitem>
<listitem>Time Label -- A tuple that either completely or partially specifies a specific date-time with respect to a calendar or clock system. This is the year-month-day representation.</listitem>
<listitem>Adjusting Time Length -- A duration that represents varying physical durations depending on the moment in time. For example, a 1 month duration is typically not a fixed number of days and it depends on the date it is measured from to determine the actual length. </listitem>
</itemizedlist>
</para>
<para>
These are design sorts of terms:
<itemizedlist mark="bullet">
<listitem>Generation function -- A function that generates a specific set of time points, lengths, or intervals based on one or more parameters. </listitem>
</itemizedlist>
</para>
</section>

13
xmldoc/tests.xml Normal file
View File

@ -0,0 +1,13 @@
<section id="date_time.tests">
<title>Tests</title>
<para>
The library provides a large number of tests in the
<programlisting>
libs/date_time/test
libs/date_time/test/gregorian
libs/date_time/test/posix_time
</programlisting>
directories. Building and executing these tests assures that the installation is correct and that the library is functioning correctly. In addition, these tests facilitate the porting to new compilers. Finally, the tests provide examples of many functions not explicitly described in the usage examples.
</para>
</section>

310
xmldoc/time_duration.xml Normal file
View File

@ -0,0 +1,310 @@
<section id="date_time.posix_time.time_duration">
<title>Time Duration</title>
<link linkend="time_duration_intro">Introduction</link> --
<link linkend="time_duration_header">Header</link> --
<link linkend="time_duration_constr">Construction</link> --
<link linkend="time_duration_count_constr">Count Based Construction</link> --
<link linkend="time_duration_from_string">Construct from String</link> --
<link linkend="time_duration_accessors">Accessors</link> --
<link linkend="time_duration_to_string">Conversion To String</link> --
<link linkend="time_duration_operators">Operators</link>
<anchor id="time_duration_intro" />
<bridgehead renderas="sect3">Introduction</bridgehead>
<para>
The class boost::posix_time::time_duration the base type responsible for representing a length of time. A duration can be either positive or negative. The general time_duration class provides a constructor that takes a count of the number of hours, minutes, seconds, and fractional seconds count as shown in the code fragment below. The resolution of the time_duration is configureable at compile time. See <link linkend="date_time.buildinfo">Build-Compiler Information</link> for more information.
</para>
<para>
<programlisting>
using namespace boost::posix_time;
time_duration td(1,2,3,4); //01:02:03.000000004 when resolution is nano seconds
time_duration td(1,2,3,4); //01:02:03.000004 when resolution is micro seconds
</programlisting>
</para>
<para>
Several small helper classes that derive from a base time_duration, as shown below, to adjust for different resolutions. These classes can shorten code and make the intent clearer.
</para>
<imagedata fileref="../../libs/date_time/doc/time_duration_inherit.png" />
<para>
As an example:
<programlisting>
using namespace boost::posix_time;
time_duration td = hours(1) + seconds(10); //01:00:01
td = hours(1) + nanosec(5); //01:00:00.000000005
</programlisting>
Note that the existence of the higher resolution classes (eg: nanosec) depends on the installation of the library. See <link linkend="date_time.buildinfo">Build-Compiler Information</link> for more information.
</para>
<anchor id="time_duration_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="time_duration_constr" />
<bridgehead renderas="sect3">Construction</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>time_duration(hours,minutes,seconds,fractional_seconds)</entry>
<entry>Construct ad duration from the counts</entry>
<entry>time_duration td(1,2,3,9); //1 hr 2 min 3 sec 9 nanoseconds</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<anchor id="time_duration_count_constr" />
<bridgehead renderas="sect3">Count Based Construction</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>hours(long)</entry>
<entry>Number of hours</entry>
<entry>time_duration td = hours(3);</entry>
</row>
<row>
<entry>minutes(long)</entry>
<entry>Number of minutes</entry>
<entry>time_duration td = minutes(3);</entry>
</row>
<row>
<entry>seconds(long)</entry>
<entry> Number of seconds</entry>
<entry>time_duration td = seconds(3);</entry>
</row>
<row>
<entry>millisec(long)</entry>
<entry>Number of milliseconds.</entry>
<entry>time_duration td = millisec(3);</entry>
</row>
<row>
<entry>microsec(long)</entry>
<entry>Number of microseconds.</entry>
<entry>time_duration td = microsec(3);</entry>
</row>
<row>
<entry>nanosec(long)</entry>
<entry>Number of nanoseconds.</entry>
<entry>time_duration td = nanosec(3);</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<anchor id="time_duration_from_string" />
<bridgehead renderas="sect3">Construct from String</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>time_duration duration_from_string(const std::string&amp;)</entry>
<entry>From delimited string.</entry>
<entry>
std::string ts("23:59:59.000");
time_duraton td(duration_from_string(ts))
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<anchor id="time_duration_accessors" />
<bridgehead renderas="sect3">Accessors</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>long hours() const</entry>
<entry>Get the number of normalized hours.</entry>
<entry>time_duration td(1,2,3); td.hours() --> 1</entry>
</row>
<row>
<entry>long minutes() const</entry>
<entry>Get the number of minutes normalized (0..59).</entry>
<entry>time_duration td(1,2,3); td.minutes() --> 2</entry>
</row>
<row>
<entry>long seconds() const</entry>
<entry>Get the normalized number of second (0..59).</entry>
<entry>time_duration td(1,2,3); td.seconds() --> 3</entry>
</row>
<row>
<entry>long total_seconds() const</entry>
<entry>Get the total number of seconds truncating any fractional seconds.</entry>
<entry>
time_duration td(1,2,3,10);
td.total_seconds() --> (1*3600) + (2*60) + 3 == 3723
</entry>
</row>
<row>
<entry>long fractional_seconds() const</entry>
<entry>Get the number of fractional seconds.</entry>
<entry>time_duration td(1,2,3, 1000); td.fractional_seconds() --> 1000</entry>
</row>
<row>
<entry>bool is_negative() const</entry>
<entry>True if duration is negative.</entry>
<entry>time_duration td(-1,0,0); td.is_negative() --> true</entry>
</row>
<row>
<entry>time_duration invert_sign() const</entry>
<entry>Generate a new duration with the sign inverted/</entry>
<entry>time_duration td(-1,0,0); td.invert_sign() --> 01:00:00</entry>
</row>
<row>
<entry>static boost::date_time::time_resolutions resolution()</entry>
<entry>Describes the resolution capability of the time_duration class.</entry>
<entry>time_duration::resolution() --> nano</entry>
</row>
<row>
<entry>boost::int64_t ticks()</entry>
<entry>Return the raw count of the duration type.</entry>
<entry>time_duration td(0,0,0, 1000); td.ticks() --> 1000</entry>
</row>
<row>
<entry>static time_duration unit()</entry>
<entry>Return smallest possible unit of duration type (1 nanosecond).</entry>
<entry>time_duration::unit() --> time_duration(0,0,0,1)</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<anchor id="time_duration_to_string" />
<bridgehead renderas="sect3">Conversion To String</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>std::string to_simple_string(time_duration)</entry>
<entry>To HH:MM:SS.fffffffff were fff is fractional seconds that are only included if non-zero.</entry>
<entry>10:00:01.123456789</entry>
</row>
<row>
<entry>std::string to_iso_string(time_duration)</entry>
<entry>Convert to form HHMMSS,fffffffff.</entry>
<entry>100001,123456789</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<anchor id="time_duration_operators" />
<bridgehead renderas="sect3">Operators</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>
operator==, operator!=,
operator>, operator&lt;
operator>=, operator&lt;=
</entry>
<entry>A full complement of comparison operators</entry>
<entry>dd1 == dd2, etc</entry>
</row>
<row>
<entry>time_duration operator+(time_duration) const</entry>
<entry>Add durations.</entry>
<entry>
time_duration td1(hours(1)+minutes(2));
time_duration td2(seconds(10));
time_duration td3 = td1 + td2;
</entry>
</row>
<row>
<entry>time_duration operator-(time_duration) const</entry>
<entry>Subtract durations.</entry>
<entry>
time_duration td1(hours(1)+nanosec(2));
time_duration td2 = td1 - minutes(1);
</entry>
</row>
<row>
<entry>time_duration operator/(int) const</entry>
<entry>Divide the length of a duration by an integer value. Discards any remainder.</entry>
<entry>
hours(3)/2 == time_duration(1,30,0);
nanosec(3)/2 == nanosec(1)
</entry>
</row>
<row>
<entry>time_duration operator*(int) const</entry>
<entry>Multiply the length of a duration by an integer value.</entry>
<entry>hours(3)*2 == hours(6);</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<link linkend="top">top</link>
</section>

135
xmldoc/time_iterators.xml Normal file
View File

@ -0,0 +1,135 @@
<section id="date_time.posix_time.time_iterators">
<title>Time Iterators</title>
<link linkend="time_iter_intro">Introduction</link> --
<link linkend="time_iter_header">Header</link> --
<link linkend="time_iter_overview">Overview</link> --
<link linkend="time_iter_operators">Operators</link>
<anchor id="time_iter_intro" />
<bridgehead renderas="sect3">Introduction</bridgehead>
<para>
Time iterators provide a mechanism for iteration through times. Time iterators are similar to <ulink url="http://www.sgi.com/tech/stl/BidirectionalIterator.html">Bidirectional Iterators</ulink>. However, time_iterators are different than standard iterators in that there is no underlying sequence, just a calculation function. In addition, time_iterators are directly comparable against instances of <link linkend="date_time.posix_time.ptime_class">class ptime</link>. Thus a second iterator for the end point of the iteration is not required, but rather a point in time can be used directly. For example, the following code iterates using a 15 minute iteration interval. The <link linkend="date_time.examples.print_hours">print hours</link> example also illustrates the use of the time_iterator.
</para>
<para>
<programlisting>
<![CDATA[
#include "boost/date_time/posix_time/posix_time.hpp"
#include <iostream>
int
main()
{
using namespace boost::gregorian;
using namespace boost::posix_time;
date d(2000,Jan,20);
ptime start(d);
ptime end = start + hours(1);
time_iterator titr(start,minutes(15)); //increment by 15 minutes
//produces 00:00:00, 00:15:00, 00:30:00, 00:45:00
while (titr < end) {
std::cout << to_simple_string(*titr) << std::endl;
++titr;
}
std::cout << "Now backward" << std::endl;
//produces 01:00:00, 00:45:00, 00:30:00, 00:15:00
while (titr > start) {
std::cout << to_simple_string(*titr) << std::endl;
--titr;
}
}
]]>
</programlisting>
</para>
<anchor id="time_iter_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="time_iter_overview" />
<bridgehead renderas="sect3">Overview</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Class</entry>
<entry>Construction Parameters</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>time_iterator</entry>
<entry>ptime start_time, time_duration increment</entry>
<entry>Iterate incrementing by the specified duration.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<anchor id="time_iter_operators" />
<bridgehead renderas="sect3">Operators</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>
operator==(const ptime&amp; rhs),
operator!=(const ptime&amp; rhs),
operator>, operator&lt;
operator>=, operator&lt;=
</entry>
<entry>A full complement of comparison operators</entry>
<entry>
date d(2002,Jan,1);
ptime start_time(d, hours(1));
//increment by 10 minutes
time_iterator titr(start_time, minutes(10));
ptime end_time = start_time + hours(2);
if (titr == end_time) // false
if (titr != end_time) // true
if (titr >= end_time) // false
if (titr &lt;= end_time) // true
</entry>
</row>
<row>
<entry>prefix increment</entry>
<entry>Increment the iterator by the specified duration.</entry>
<entry>
//increment by 10 milli seconds
time_iterator titr(start_time, milliseconds(10));
++titr; // == start_time + 10 milliseconds
</entry>
</row>
<row>
<entry>prefix decrement</entry>
<entry>Decrement the iterator by the specified time duration.</entry>
<entry>Example time_iterator titr(start_time, time_duration(1,2,3));
--titr; // == start_time - 1 hour, 2 minutes, and 3 seconds</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<link linkend="top">top</link>
</section>

256
xmldoc/time_period.xml Normal file
View File

@ -0,0 +1,256 @@
<section id="date_time.posix_time.time_period">
<title>Time Period</title>
<link linkend="time_period_intro">Introduction</link> --
<link linkend="time_period_header">Header</link> --
<link linkend="time_period_constr">Construction</link> --
<link linkend="time_period_accessors">Accessors</link> --
<link linkend="time_period_to_string">Conversion To String</link> --
<link linkend="time_period_operators">Operators</link>
<anchor id="time_period_intro" />
<bridgehead renderas="sect3">Introduction</bridgehead>
<para>
The class boost::posix_time::time_period provides direct representation for ranges between two times. Periods provide the ability to simplify some types of calculations by simplifying the conditional logic of the program.
</para>
<para>
The <link linkend="date_time.examples.time_periods">time periods example</link> provides an example of using time periods.
</para>
<anchor id="time_period_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="time_period_constr" />
<bridgehead renderas="sect3">Construction</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>time_period(ptime begin, ptime end)</entry>
<entry> Create a period as [begin, end). If last is &lt;= begin then the period will be defined as null.</entry>
<entry>
date d(2002,Jan,01);
ptime t(d, seconds(10)); //10 sec after midnight
time_period tp(t, hours(3));
</entry>
</row>
<row>
<entry>time_period(ptime start, time_duration len)</entry>
<entry> Create a period as [begin, begin+len). If len is &lt;= zero then the period will be defined as null.</entry>
<entry>
date d(2002,Jan,01);
ptime t1(d, seconds(10)); //10 sec after midnight
ptime t2(d, hours(10)); //10 hours after midnight
time_period tp(t1, t2);
</entry>
</row>
<row>
<entry>time_period(time_period rhs)</entry>
<entry> Copy constructor</entry>
<entry>time_period tp1(tp)</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<anchor id="time_period_accessors" />
<bridgehead renderas="sect3">Accessors</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>ptime begin() const</entry>
<entry>Return first time of period.</entry>
<entry>
date d(2002,Jan,01);
ptime t1(d, seconds(10)); //10 sec after midnight
ptime t2(d, hours(10)); //10 hours after midnight
time_period tp(t1, t2); tp.begin() --> 2002-Jan-01 00:00:10
</entry>
</row>
<row>
<entry>ptime last() const</entry>
<entry>Return last time in the period</entry>
<entry>
date d(2002,Jan,01);
ptime t1(d, seconds(10)); //10 sec after midnight
ptime t2(d, hours(10)); //10 hours after midnight
time_period tp(t1, t2); tp.last() --> 2002-Jan-01 09:59:59.999999999
</entry>
</row>
<row>
<entry>ptime end() const</entry>
<entry> Return one past the last in period</entry>
<entry>
date d(2002,Jan,01);
ptime t1(d, seconds(10)); //10 sec after midnight
ptime t2(d, hours(10)); //10 hours after midnight
time_period tp(t1, t2); tp.last() --> 2002-Jan-01 10:00:00
</entry>
</row>
<row>
<entry>time_duration length() const</entry>
<entry>Return the length of the time period.</entry>
<entry>
date d(2002,Jan,01);
ptime t1(d); //midnight
time_period tp(t1, hours(1));
tp.length() --> 1 hour
</entry>
</row>
<row>
<entry>bool is_null() const</entry>
<entry>True if period is not well formed. eg: start less than end</entry>
<entry></entry>
</row>
<row>
<entry>bool contains(ptime) const</entry>
<entry>True if ptime is within the period</entry>
<entry>
date d(2002,Jan,01);
ptime t1(d, seconds(10)); //10 sec after midnight
ptime t2(d, hours(10)); //10 hours after midnight
ptime t3(d, hours(2)); //2 hours after midnight
time_period tp(t1, t2); tp.contains(t3) --> true
</entry>
</row>
<row>
<entry>bool contains(time_period) const</entry>
<entry>True if period is within the period</entry>
<entry>
time_period tp1(ptime(d,hours(1)), ptime(d,hours(12)));
time_period tp2(ptime(d,hours(2)), ptime(d,hours(4)));
tp1.contains(tp2) --> true
tp2.contains(tp1) --> false
</entry>
</row>
<row>
<entry>bool intersects(time_period) const</entry>
<entry> True if periods overlap</entry>
<entry>
time_period tp1(ptime(d,hours(1)), ptime(d,hours(12)));
time_period tp2(ptime(d,hours(2)), ptime(d,hours(4)));
tp2.intersects(tp1) --> true
</entry>
</row>
<row>
<entry>time_period intersection(time_period) const</entry>
<entry>Calculate the intersection of 2 periods. Null if no intersection.</entry>
<entry></entry>
</row>
<row>
<entry>time_period merge(time_period) const</entry>
<entry>Returns union of two periods. Null if no intersection.</entry>
<entry></entry>
</row>
<row>
<entry>time_period span(time_period) const</entry>
<entry>Combines two periods and any gap between them such that start = min(p1.start, p2.start) and end = max(p1.end , p2.end).</entry>
<entry></entry>
</row>
<row>
<entry>time_period shift(date_duration)</entry>
<entry>Add duration to both start and end.</entry>
<entry></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<anchor id="time_period_to_string" />
<bridgehead renderas="sect3">Conversion To String</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>std::string to_simple_string(time_period dp)</entry>
<entry>To [YYYY-mmm-DD hh:mm:ss.fffffffff/YYYY-mmm-DD hh:mm:ss.fffffffff] string where mmm is 3 char month name.</entry>
<entry>[2002-Jan-01 01:25:10.000000001/2002-Jan-31 01:25:10.123456789]</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<anchor id="time_period_operators" />
<bridgehead renderas="sect3">Operators</bridgehead>
<para>
<informaltable frame="all">
<tgroup cols="3">
<thead>
<row>
<entry>Syntax</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>operator&lt;&lt;</entry>
<entry>Output streaming operator for time duration. Uses facet to output [date time_of_day/date time_of_day]. The default is format is [YYYY-mmm-DD hh:mm:ss.fffffffff/YYYY-mmm-DD hh:mm:ss.fffffffff] string where mmm is 3 char month name.</entry>
<entry>[2002-Jan-01 01:25:10.000000001/2002-Jan-31 01:25:10.123456789]</entry>
</row>
<row>
<entry>operator==, operator!=</entry>
<entry>Equality operators. Periods are equal if p1.begin == p2.begin &amp;&amp; p1.last == p2.last</entry>
<entry>if (tp1 == tp2) {...</entry>
</row>
<row>
<entry>operator&lt;</entry>
<entry>Ordering with no overlap. True if tp1.end() less than tp2.begin()</entry>
<entry>if (tp1 &lt; tp2) {...</entry>
</row>
<row>
<entry>operator></entry>
<entry>Ordering with no overlap. True if tp1.begin() greater than tp2.end()</entry>
<entry>if (tp1 > tp2) {... etc</entry>
</row>
<row>
<entry>operator&lt;=, operator>=</entry>
<entry>Defined in terms of the other operators.</entry>
<entry></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<link linkend="top">top</link>
</section>

118
xmldoc/tradeoffs.xml Normal file
View File

@ -0,0 +1,118 @@
<section id="date_time.tradeoffs">
<title>Tradeoffs: Stability, Predictability, and Approximations</title>
<bridgehead renderas="sect2">
Unavoidable Trade-offs
</bridgehead>
<para>
The library does its best to provide everything a user could want, but there are certain inherent constraints that limit what <emphasis>any</emphasis> temporal library can do. Specifically, a user must choose which two of the following three capabilities are desired in any particular application:
<itemizedlist mark="bullet">
<listitem>exact agreement with wall-clock time</listitem>
<listitem>accurate math, e.g. duration calculations</listitem>
<listitem>ability to handle timepoints in the future</listitem>
</itemizedlist>
Some libraries may implicitly promise to deliver all three, but if you actually put them to the test, only two can be true at once. This limitation is not a deficiency in the design or implementation of any particular library; rather it is a consequence of the way different time systems are defined by international standards. Let's look at each of the three cases:
</para>
<para>
If you want exact agreement with wall-clock time, you must use either UTC or local time. If you compute a duration by subtracting one UTC time from another and you want an answer accurate to the second, the two times must not be too far in the future because leap seconds affect the count but are only determined about 6 months in advance. With local times a future duration calculation could be off by an entire hour, since legislatures can and do change DST rules at will.
</para>
<para>
If you want to handle wall-clock times in the future, you won't be able (in the general case) to calculate exact durations, for the same reasons described above.
</para>
<para>
If you want accurate calculations with future times, you will have to use TAI or an equivalent, but the mapping from TAI to UTC or local time depends on leap seconds, so you will not have exact agreement with wall-clock time.
</para>
<bridgehead renderas="sect2">
Stability, Predictability, and Approximations
</bridgehead>
<para>
Here is some underlying theory that helps to explain what's going on. Remember that a temporal type, like any abstract data type (ADT), is a set of values together with operations on those values.
</para>
<bridgehead renderas="sect3">
Stability
</bridgehead>
<para>
The representation of a type is <emphasis>stable</emphasis> if the bit pattern associated with a given value does not change over time. A type with an unstable representation is unlikely to be of much use to anyone, so we will insist that any temporal library use only stable representations.
</para>
<para>
An operation on a type is stable if the result of applying the operation to a particular operand(s) does not change over time.
</para>
<bridgehead renderas="sect3">
Predictability
</bridgehead>
<para>
Sets are most often classified into two categories: well-defined and ill-defined. Since a type is a set, we can extend these definitions to cover types. For any type T, there must be a predicate <emphasis>is_member( x )</emphasis> which determines whether a value x is a member of type T. This predicate must return <emphasis>true, false,</emphasis> or <emphasis>dont_know</emphasis>.
</para>
<para>
If for all x, is_member( x ) returns either true or false, we say the set T is <emphasis>well-defined</emphasis>.
</para>
<para>
If for any x, is_member( x ) returns dont_know, we say the set T is <emphasis>ill-defined</emphasis>.
</para>
<para>
Those are the rules normally used in math. However, because of the special characteristics of temporal types, it is useful to refine this view and create a third category as follows:
</para>
<para>
For any temporal type T, there must be a predicate <emphasis>is_member( x, t )</emphasis> which determines whether a value x is a member of T. The parameter t represents the time when the predicate is evaluated. For each x<subscript>i</subscript>, there must be a time t<subscript>i</subscript> and a value v such that:
<itemizedlist mark="bullet">
<listitem>v = true or v = false, and</listitem>
<listitem>for all t &lt; t<subscript>i</subscript>, is_member( x<subscript>i</subscript>, t ) returns dont_know, and</listitem>
<listitem>for all t >= t<subscript>i</subscript>, is_member( x<subscript>i</subscript>, t ) returns v.</listitem>
</itemizedlist>
t<subscript>i</subscript> is thus the time when we "find out" whether x<subscript>i</subscript> is a member of T. Now we can define three categories of temporal types:
</para>
<para>
If for all x<subscript>i</subscript>, t<subscript>i</subscript> = negative infinity, we say the type T is <emphasis>predictable</emphasis>.
</para>
<para>
If for some x<subscript>i</subscript>, t<subscript>i</subscript> = positive infinity, we say the type T is <emphasis>ill-formed</emphasis>.
</para>
<para>
Otherwise we say the type T is <emphasis>unpredictable</emphasis> (this implies that for some x<subscript>i</subscript>, t<subscript>i</subscript> is finite).
</para>
<para>
Ill-formed sets are not of much practical use, so we will not discuss them further. In plain english the above simply says that all the values of a predictable type are known ahead of time, but some values of an unpredictable type are not known until some particular time.
</para>
<bridgehead renderas="sect3">
Stability of Operations
</bridgehead>
<para>
Predictable types have a couple of important properties:
<itemizedlist mark="bullet">
<listitem>there is an order-preserving mapping from their elements onto a set of consecutive integers, and</listitem>
<listitem>duration operations on their values are stable</listitem>
</itemizedlist>
</para>
<para>
The practical effect of this is that duration calculations can be implemented with simple integer subtraction. Examples of predictable types are TAI timepoints and Gregorian dates.
</para>
<para>
Unpredictable types have exactly the opposite properties:
<itemizedlist mark="bullet">
<listitem>there is no order-preserving mapping from their elements onto a set of consecutive integers, and</listitem>
<listitem>duration operations on their values are not stable. </listitem>
</itemizedlist>
</para>
<para>
Examples of unpredictable types are UTC timepoints and Local Time timepoints.
</para>
<para>
We can refine this a little by saying that a range within an unpredicatable type can be predictable, and operations performed entirely on values within that range will be stable. For example, the range of UTC timepoints from 1970-01-01 through the present is predictable, so calculations of durations within that range will be stable.
</para>
<bridgehead renderas="sect3">
Approximations
</bridgehead>
<para>
These limitations are problematical, because important temporal types like UTC and Local Time are in fact unpredictable, and therefore operations on them are sometimes unstable. Yet as a practical matter we often want to perform this kind of operation, such as computing the duration between two timepoints in the future that are specified in Local Time.
</para>
<para>
The best the library can do is to provide an approximation, which is generally possible and for most purposes will be good enough. Of course the documentation must specify when an answer will be approximate (and thus unstable) and how big the error may be. In many respects calculating with unpredictable sets is analogous to the use of floating point numbers, for which results are expected to only be approximately correct. Calculating with predictable sets would then be analogous to the user of integers, where results are expected to be exact.
</para>
<para>
For situations where exact answers are required or instability cannot be tolerated, the user must be able to specify this, and then the library should throw an exception if the user requests a computation for which an exact, stable answer is not possible.
</para>
</section>

52
xmldoc/usage_examples.xml Normal file
View File

@ -0,0 +1,52 @@
<section id="date_time.examples.general_usage_examples">
<title>General Usage Examples</title>
<para>
The following provides some sample usage of dates.
See <link linkend="date_time.gregorian">Date Programming</link>
for more details.
<programlisting>
using namespace boost::gregorian;
date weekstart(2002,Feb,1);
date weekend (2002,Feb,7);
date_duration fiveDays(5);
date d3 = d1 + fiveDays;
date today = day_clock::local_day();
if (d3 &gt;= today) {} //date comparison operators
date_period thisWeek(d1,d2);
if (thisWeek.contains(today)) {}//do something
//iterate and print the week
day_iterator itr(weekstart);
for (; itr &lt;= weekend; ++itr) {
std::cout &lt;&lt; (*itr) &lt;&lt; std::endl;
}
</programlisting>
The following provides some example code using times.
See <link linkend="date_time.posix_time">Time Programming</link>
for more details.
<programlisting>
use namespace boost::posix_time;
date d(2002,Feb,1); //an arbitrary date
ptime t1(d, hours(5)+nanosec(100)); //date + time of day offset
ptime t2 = t1 - minutes(4)+seconds(2);
ptime now = second_clock::local_time(); //use the clock
date today = now.date(); //Get the date part out of the time
date tommorrow = today + date_duration(1);
ptime tommorrow_start(tommorrow); //midnight
//starting at current time iterator adds by one hour
time_iterator titr(now,hours(1));
for (; titr &lt; tommorrow_start; ++titr) {
std::cout &lt;&lt; to_simple_string(*titr) &lt;&lt; std::endl;
}
</programlisting>
</para>
<link linkend="top">top</link>
</section>