| 1 | <html> |
|---|
| 2 | <head> |
|---|
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
|---|
| 4 | <title>Chapter 3. Boost.Date_Time</title> |
|---|
| 5 | <link rel="stylesheet" href="boostbook.css" type="text/css"> |
|---|
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.69.1"> |
|---|
| 7 | <link rel="start" href="index.html" title="The Boost C++ Libraries"> |
|---|
| 8 | <link rel="up" href="libraries.html" title="Part I. The Boost C++ Libraries"> |
|---|
| 9 | <link rel="prev" href="SignedInteger.html" title="Concept SignedInteger"> |
|---|
| 10 | <link rel="next" href="date_time/examples/general_usage_examples.html" title="General Usage Examples"> |
|---|
| 11 | </head> |
|---|
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
|---|
| 13 | <table cellpadding="2" width="100%"> |
|---|
| 14 | <td valign="top"><img alt="boost.png (6897 bytes)" width="277" height="86" src="../../boost.png"></td> |
|---|
| 15 | <td align="center"><a href="../../index.htm">Home</a></td> |
|---|
| 16 | <td align="center"><a href="../../libs/libraries.htm">Libraries</a></td> |
|---|
| 17 | <td align="center"><a href="../../people/people.htm">People</a></td> |
|---|
| 18 | <td align="center"><a href="../../more/faq.htm">FAQ</a></td> |
|---|
| 19 | <td align="center"><a href="../../more/index.htm">More</a></td> |
|---|
| 20 | </table> |
|---|
| 21 | <hr> |
|---|
| 22 | <div class="spirit-nav"> |
|---|
| 23 | <a accesskey="p" href="SignedInteger.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="libraries.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="date_time/examples/general_usage_examples.html"><img src="images/next.png" alt="Next"></a> |
|---|
| 24 | </div> |
|---|
| 25 | <div class="chapter" lang="en"> |
|---|
| 26 | <div class="titlepage"><div> |
|---|
| 27 | <div><h2 class="title"> |
|---|
| 28 | <a name="date_time"></a>Chapter 3. Boost.Date_Time</h2></div> |
|---|
| 29 | <div><div class="author"><h3 class="author"> |
|---|
| 30 | <span class="firstname">Jeff</span> <span class="surname">Garland</span> |
|---|
| 31 | </h3></div></div> |
|---|
| 32 | <div><p class="copyright">Copyright © 2001-2005 CrystalClear Software, Inc</p></div> |
|---|
| 33 | <div><div class="legalnotice"> |
|---|
| 34 | <a name="id2579432"></a><p>Subject to the Boost Software License, Version 1.0. (See accompanying file |
|---|
| 35 | <code class="filename">LICENSE_1_0.txt</code> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)</p> |
|---|
| 36 | </div></div> |
|---|
| 37 | </div></div> |
|---|
| 38 | <div class="toc"> |
|---|
| 39 | <p><b>Table of Contents</b></p> |
|---|
| 40 | <dl> |
|---|
| 41 | <dt><span class="section"><a href="date_time.html#date_time.conceptual">Conceptual</a></span></dt> |
|---|
| 42 | <dd><dl> |
|---|
| 43 | <dt><span class="section"><a href="date_time.html#Motivation">Motivation</a></span></dt> |
|---|
| 44 | <dt><span class="section"><a href="date_time.html#date_time.domain_concepts">Domain Concepts</a></span></dt> |
|---|
| 45 | <dt><span class="section"><a href="date_time.html#date_time.design_concepts">Design Concepts</a></span></dt> |
|---|
| 46 | </dl></dd> |
|---|
| 47 | <dt><span class="section"><a href="date_time/examples/general_usage_examples.html">General Usage Examples</a></span></dt> |
|---|
| 48 | <dt><span class="section"><a href="date_time/gregorian.html">Gregorian</a></span></dt> |
|---|
| 49 | <dd><dl> |
|---|
| 50 | <dt><span class="section"><a href="date_time/gregorian.html#date_time.gregorian.date_class">Date</a></span></dt> |
|---|
| 51 | <dt><span class="section"><a href="date_time/gregorian.html#date_time.gregorian.date_duration">Date Duration (aka Days)</a></span></dt> |
|---|
| 52 | <dt><span class="section"><a href="date_time/gregorian.html#date_time.gregorian.date_period">Date Period</a></span></dt> |
|---|
| 53 | <dt><span class="section"><a href="date_time/gregorian.html#date_time.gregorian.date_iterators">Date Iterators</a></span></dt> |
|---|
| 54 | <dt><span class="section"><a href="date_time/gregorian.html#date_time.gregorian.date_algorithms">Date Generators/Algorithms</a></span></dt> |
|---|
| 55 | <dt><span class="section"><a href="date_time/gregorian.html#date_time.gregorian.gregorian_calendar">Gregorian Calendar</a></span></dt> |
|---|
| 56 | </dl></dd> |
|---|
| 57 | <dt><span class="section"><a href="date_time/posix_time.html">Posix Time</a></span></dt> |
|---|
| 58 | <dd><dl> |
|---|
| 59 | <dt><span class="section"><a href="date_time/posix_time.html#date_time.posix_time.ptime_class">Ptime</a></span></dt> |
|---|
| 60 | <dt><span class="section"><a href="date_time/posix_time.html#date_time.posix_time.time_duration">Time Duration</a></span></dt> |
|---|
| 61 | <dt><span class="section"><a href="date_time/posix_time.html#date_time.posix_time.time_period">Time Period</a></span></dt> |
|---|
| 62 | <dt><span class="section"><a href="date_time/posix_time.html#date_time.posix_time.time_iterators">Time Iterators</a></span></dt> |
|---|
| 63 | </dl></dd> |
|---|
| 64 | <dt><span class="section"><a href="date_time/local_time.html">Local Time</a></span></dt> |
|---|
| 65 | <dd><dl> |
|---|
| 66 | <dt><span class="section"><a href="date_time/local_time.html#date_time.local_time.time_zone_base">Time Zone (abstract)</a></span></dt> |
|---|
| 67 | <dt><span class="section"><a href="date_time/local_time.html#date_time.local_time.posix_time_zone">Posix Time Zone</a></span></dt> |
|---|
| 68 | <dt><span class="section"><a href="date_time/local_time.html#date_time.local_time.tz_database">Time Zone Database</a></span></dt> |
|---|
| 69 | <dt><span class="section"><a href="date_time/local_time.html#date_time.local_time.custom_time_zone">Custom Time Zone</a></span></dt> |
|---|
| 70 | <dt><span class="section"><a href="date_time/local_time.html#date_time.local_time.local_date_time">Local Date Time</a></span></dt> |
|---|
| 71 | <dt><span class="section"><a href="date_time/local_time.html#date_time.local_time.local_time_period">Local Time Period</a></span></dt> |
|---|
| 72 | </dl></dd> |
|---|
| 73 | <dt><span class="section"><a href="date_time/date_time_io.html">Date Time Input/Output</a></span></dt> |
|---|
| 74 | <dd><dl> |
|---|
| 75 | <dt><span class="section"><a href="date_time/date_time_io.html#date_time.format_flags">Format Flags</a></span></dt> |
|---|
| 76 | <dt><span class="section"><a href="date_time/date_time_io.html#date_time.date_facet">Date Facet</a></span></dt> |
|---|
| 77 | <dt><span class="section"><a href="date_time/date_time_io.html#date_time.date_input_facet">Date Input Facet</a></span></dt> |
|---|
| 78 | <dt><span class="section"><a href="date_time/date_time_io.html#date_time.time_facet">Time Facet</a></span></dt> |
|---|
| 79 | <dt><span class="section"><a href="date_time/date_time_io.html#date_time.time_input_facet">Time Input Facet</a></span></dt> |
|---|
| 80 | <dt><span class="section"><a href="date_time/date_time_io.html#date_time.io_objects">Date Time Formatter/Parser Objects</a></span></dt> |
|---|
| 81 | <dt><span class="section"><a href="date_time/date_time_io.html#date_time.io_tutorial">Date Time IO Tutorial</a></span></dt> |
|---|
| 82 | </dl></dd> |
|---|
| 83 | <dt><span class="section"><a href="date_time/serialization.html">Serialization</a></span></dt> |
|---|
| 84 | <dt><span class="section"><a href="date_time/details.html">Details</a></span></dt> |
|---|
| 85 | <dd><dl> |
|---|
| 86 | <dt><span class="section"><a href="date_time/details.html#date_time.calculations">Calculations</a></span></dt> |
|---|
| 87 | <dt><span class="section"><a href="date_time/details.html#date_time.design_goals">Design Goals</a></span></dt> |
|---|
| 88 | <dt><span class="section"><a href="date_time/details.html#date_time.tradeoffs">Tradeoffs: Stability, Predictability, and Approximations</a></span></dt> |
|---|
| 89 | <dt><span class="section"><a href="date_time/details.html#date_time.terminology">Terminology</a></span></dt> |
|---|
| 90 | <dt><span class="section"><a href="date_time/details.html#date_time.references">References</a></span></dt> |
|---|
| 91 | <dt><span class="section"><a href="date_time/details.html#date_time.buildinfo">Build-Compiler Information</a></span></dt> |
|---|
| 92 | <dt><span class="section"><a href="date_time/details.html#date_time.tests">Tests</a></span></dt> |
|---|
| 93 | <dt><span class="section"><a href="date_time/details.html#date_time.changes">Change History</a></span></dt> |
|---|
| 94 | <dt><span class="section"><a href="date_time/details.html#date_time.acknowledgements">Acknowledgements</a></span></dt> |
|---|
| 95 | </dl></dd> |
|---|
| 96 | <dt><span class="section"><a href="date_time/examples.html">Examples</a></span></dt> |
|---|
| 97 | <dd><dl> |
|---|
| 98 | <dt><span class="section"><a href="date_time/examples.html#date_time.examples.dates_as_strings">Dates as Strings</a></span></dt> |
|---|
| 99 | <dt><span class="section"><a href="date_time/examples.html#date_time.examples.days_alive">Days Alive</a></span></dt> |
|---|
| 100 | <dt><span class="section"><a href="date_time/examples.html#date_time.examples.days_between_new_year">Days Between New Years</a></span></dt> |
|---|
| 101 | <dt><span class="section"><a href="date_time/examples.html#date_time.examples.end_of_month_day">Last Day of the Months</a></span></dt> |
|---|
| 102 | <dt><span class="section"><a href="date_time/examples.html#date_time.examples.localization">Localization Demonstration</a></span></dt> |
|---|
| 103 | <dt><span class="section"><a href="date_time/examples.html#date_time.examples.date_period_calc">Date Period Calculations</a></span></dt> |
|---|
| 104 | <dt><span class="section"><a href="date_time/examples.html#date_time.examples.print_holidays">Print Holidays</a></span></dt> |
|---|
| 105 | <dt><span class="section"><a href="date_time/examples.html#date_time.examples.print_month">Print Month</a></span></dt> |
|---|
| 106 | <dt><span class="section"><a href="date_time/examples.html#date_time.examples.month_add">Month Adding</a></span></dt> |
|---|
| 107 | <dt><span class="section"><a href="date_time/examples.html#date_time.examples.time_math">Time Math</a></span></dt> |
|---|
| 108 | <dt><span class="section"><a href="date_time/examples.html#date_time.examples.print_hours">Print Hours</a></span></dt> |
|---|
| 109 | <dt><span class="section"><a href="date_time/examples.html#date_time.examples.local_utc_conversion">Local to UTC Conversion</a></span></dt> |
|---|
| 110 | <dt><span class="section"><a href="date_time/examples.html#date_time.examples.time_periods">Time Periods</a></span></dt> |
|---|
| 111 | <dt><span class="section"><a href="date_time/examples.html#date_time.examples.simple_time_zone">Simple Time Zones</a></span></dt> |
|---|
| 112 | <dt><span class="section"><a href="date_time/examples.html#date_time.examples.calc_rules">Daylight Savings Calc Rules</a></span></dt> |
|---|
| 113 | <dt><span class="section"><a href="date_time/examples.html#date_time.examples.flight">Flight Time Example</a></span></dt> |
|---|
| 114 | <dt><span class="section"><a href="date_time/examples.html#date_time.examples.seconds_since_epoch">Seconds Since Epoch</a></span></dt> |
|---|
| 115 | </dl></dd> |
|---|
| 116 | <dt><span class="section"><a href="date_time/doxy.html">Library Reference</a></span></dt> |
|---|
| 117 | <dd><dl> |
|---|
| 118 | <dt><span class="section"><a href="date_time/doxy.html#date_time_reference">Date Time Reference</a></span></dt> |
|---|
| 119 | <dt><span class="section"><a href="date_time/doxy.html#gregorian_reference">Gregorian Reference</a></span></dt> |
|---|
| 120 | <dt><span class="section"><a href="date_time/doxy.html#posix_time_reference">Posix Time Reference</a></span></dt> |
|---|
| 121 | <dt><span class="section"><a href="date_time/doxy.html#local_time_reference">Local Time Reference</a></span></dt> |
|---|
| 122 | </dl></dd> |
|---|
| 123 | </dl> |
|---|
| 124 | </div> |
|---|
| 125 | <h2> |
|---|
| 126 | <a name="id2579451"></a>Introduction</h2> |
|---|
| 127 | <p> |
|---|
| 128 | A set of date-time libraries based on generic programming concepts. |
|---|
| 129 | </p> |
|---|
| 130 | <p>This documentation is also available in PDF format. It can be found at: |
|---|
| 131 | </p> |
|---|
| 132 | <table class="simplelist" border="0" summary="Simple list"><tr><td><a href="http://www.crystalclearsoftware.com/libraries/date_time/date_time.pdf" target="_top">http://www.crystalclearsoftware.com/libraries/date_time/date_time.pdf</a></td></tr></table> |
|---|
| 133 | <p> |
|---|
| 134 | In addition, a full doxygen reference can be found at: |
|---|
| 135 | </p> |
|---|
| 136 | <table class="simplelist" border="0" summary="Simple list"><tr><td><a href="http://www.crystalclearsoftware.com/libraries/date_time/ref_guide/index.html" target="_top">http://www.crystalclearsoftware.com/libraries/date_time/ref_guide/index.html</a></td></tr></table> |
|---|
| 137 | <p> |
|---|
| 138 | The most current version of the documentation can be found at: |
|---|
| 139 | </p> |
|---|
| 140 | <table class="simplelist" border="0" summary="Simple list"><tr><td><a href="http://www.crystalclearsoftware.com/libraries/date_time/index.html" target="_top">http://www.crystalclearsoftware.com/libraries/date_time/index.html</a></td></tr></table> |
|---|
| 141 | <div class="section" lang="en"> |
|---|
| 142 | <div class="titlepage"><div><div><h3 class="title"> |
|---|
| 143 | <a name="date_time.conceptual"></a>Conceptual</h3></div></div></div> |
|---|
| 144 | <div class="toc"><dl> |
|---|
| 145 | <dt><span class="section"><a href="date_time.html#Motivation">Motivation</a></span></dt> |
|---|
| 146 | <dt><span class="section"><a href="date_time.html#date_time.domain_concepts">Domain Concepts</a></span></dt> |
|---|
| 147 | <dt><span class="section"><a href="date_time.html#date_time.design_concepts">Design Concepts</a></span></dt> |
|---|
| 148 | </dl></div> |
|---|
| 149 | <div class="section" lang="en"> |
|---|
| 150 | <div class="titlepage"><div><div><h4 class="title"> |
|---|
| 151 | <a name="Motivation"></a>Motivation</h4></div></div></div> |
|---|
| 152 | <p> |
|---|
| 153 | 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. |
|---|
| 154 | </p> |
|---|
| 155 | <p> |
|---|
| 156 | 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. |
|---|
| 157 | </p> |
|---|
| 158 | <p> |
|---|
| 159 | 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. |
|---|
| 160 | </p> |
|---|
| 161 | </div> |
|---|
| 162 | <div class="section" lang="en"> |
|---|
| 163 | <div class="titlepage"><div><div><h4 class="title"> |
|---|
| 164 | <a name="date_time.domain_concepts"></a>Domain Concepts</h4></div></div></div> |
|---|
| 165 | <p> |
|---|
| 166 | The date time domain is rich in terminology and problems. |
|---|
| 167 | The following is a brief introduction to the concepts you |
|---|
| 168 | will find reflected in the library. |
|---|
| 169 | </p> |
|---|
| 170 | <p> |
|---|
| 171 | The library supports 3 basic temporal types: |
|---|
| 172 | </p> |
|---|
| 173 | <div class="itemizedlist"><ul type="bullet"> |
|---|
| 174 | <li style="list-style-type: disc"> |
|---|
| 175 | <span class="strong"><strong>Time Point</strong></span> -- Specifier |
|---|
| 176 | for a location in the time continuum. |
|---|
| 177 | </li> |
|---|
| 178 | <li style="list-style-type: disc"> |
|---|
| 179 | <span class="strong"><strong>Time Duration</strong></span> -- A |
|---|
| 180 | length of time unattached to any point on the time continuum. |
|---|
| 181 | </li> |
|---|
| 182 | <li style="list-style-type: disc"> |
|---|
| 183 | <span class="strong"><strong>Time Interval</strong></span> -- A duration |
|---|
| 184 | of time attached to a specific point in the time continuum. |
|---|
| 185 | Also known as a time period. |
|---|
| 186 | </li> |
|---|
| 187 | </ul></div> |
|---|
| 188 | <p> |
|---|
| 189 | Each of these temporal types has a <span class="strong"><strong>Resolution</strong></span> which is defined by the smallest representable duration. A <span class="strong"><strong>Time system</strong></span> provides all these categories of temporal types as well as the rules for labeling and calculating with time points. <span class="strong"><strong>Calendar Systems</strong></span> are simply time systems with a maximum resolution of one day. The <span class="strong"><strong>Gregorian</strong></span> 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. <span class="strong"><strong>UTC (Coordinated Universal Time)</strong></span> 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 <span class="strong"><strong>local time</strong></span> 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 <span class="strong"><strong>daylight savings time (DST)</strong></span> adjustments to shift the daylight hours during the summer. |
|---|
| 190 | </p> |
|---|
| 191 | <p> |
|---|
| 192 | A <span class="strong"><strong>Clock Device</strong></span> 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. |
|---|
| 193 | </p> |
|---|
| 194 | <p> |
|---|
| 195 | 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 <a href="date_time/details.html#date_time.tradeoffs" title="Tradeoffs: Stability, Predictability, and Approximations">Stability, Predictability, and Approximations</a>. |
|---|
| 196 | </p> |
|---|
| 197 | <div class="itemizedlist"><ul type="bullet"> |
|---|
| 198 | <li style="list-style-type: disc"><a href="date_time/details.html#date_time.terminology" title="Terminology">Basic Terminology</a></li> |
|---|
| 199 | <li style="list-style-type: disc"><a href="date_time/details.html#date_time.calculations" title="Calculations">Calculations</a></li> |
|---|
| 200 | <li style="list-style-type: disc"><a href="date_time/details.html#date_time.tradeoffs" title="Tradeoffs: Stability, Predictability, and Approximations">Stability, Predictability, and Approximations</a></li> |
|---|
| 201 | <li style="list-style-type: disc"><a href="date_time/details.html#date_time.references" title="References">References</a></li> |
|---|
| 202 | </ul></div> |
|---|
| 203 | </div> |
|---|
| 204 | <div class="section" lang="en"> |
|---|
| 205 | <div class="titlepage"><div><div><h4 class="title"> |
|---|
| 206 | <a name="date_time.design_concepts"></a>Design Concepts</h4></div></div></div> |
|---|
| 207 | <p> |
|---|
| 208 | 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. |
|---|
| 209 | </p> |
|---|
| 210 | <p> |
|---|
| 211 | 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. |
|---|
| 212 | </p> |
|---|
| 213 | <p> |
|---|
| 214 | 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 <a href="date_time/details.html#date_time.design_goals" title="Design Goals">summarized here</a>. |
|---|
| 215 | </p> |
|---|
| 216 | </div> |
|---|
| 217 | </div> |
|---|
| 218 | </div> |
|---|
| 219 | <table width="100%"><tr> |
|---|
| 220 | <td align="left"><small><p>Last revised: June 12, 2005 at 20:53:10 GMT</p></small></td> |
|---|
| 221 | <td align="right"><small></small></td> |
|---|
| 222 | </tr></table> |
|---|
| 223 | <hr> |
|---|
| 224 | <div class="spirit-nav"> |
|---|
| 225 | <a accesskey="p" href="SignedInteger.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="libraries.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="date_time/examples/general_usage_examples.html"><img src="images/next.png" alt="Next"></a> |
|---|
| 226 | </div> |
|---|
| 227 | </body> |
|---|
| 228 | </html> |
|---|
