Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. — Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.

Boost Date-Time Library Documentation

Version 1.02

Overview

Introduction -- Motivation -- Usage Examples -- Domain Concepts -- Design and Extensions -- Acknowledgements -- More Info

Build-Compiler Information -- Change History -- Tests -- License -- Basic Terminology Reference -- References

Date Programming

Gregorian Date System

Time Programming

Posix Time System

Introduction

A set of date-time libraries based on generic programming concepts.

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.

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.

Usage Examples

The following shows examples of the sorts of code that can be written using the gregorian date system. See Date Programming for more details.

     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 >= 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 <= weekend; ++itr) {
       std::cout << to_iso_extended_string(*itr) << std::endl;
     }

And some time examples using the posix_time system. See Time Programming for more details.

     using 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
     //Get the date part out of the time
     date today = now.date();
     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 < tommorrow_start; ++titr) {
       std::cout << to_simple_string(*titr) << std::endl;
     }

Domain Concepts

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.

The library supports 3 basic temporal types:

Time Point -- Specifier for a location in the time continuum.
Time Duration -- A length of time unattached to any point on the time continuum.
Time Interval -- A duration of time attached to a specific point in the time continuum. Also known as a time period.

Each of these temporal types has a Resolution which is defined by the smallest representable duration. A Time system provides all these categories of temporal types as well as the rules for labeling and calculating with time points. Calendar Systems are simply time systems with a maximum resolution of one day. The Gregorian 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. UTC (Coordinated Universal Time) 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 local time 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 daylight savings time (DST) adjustments to shift the daylight hours during the summer.

A Clock Device 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.

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 Stability, Predictability, and Approximations.

Additional reference materials can be found in the following:

Tests

The library provides a large number of tests in the

   libs/date_time/test 
   libs/date_time/test/gregorian
   libs/date_time/test/posix_time

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.

Design and Extensions

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.

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.

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 summarized here.

Acknowledgements

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. For boost release 1.31 Bart Garst has done most of the actual programming work -- this is a large number of bug fixes and extensions!

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.

More Info

The design of the library is currently being evolved using Wiki and email discussions. You can find more information at:

License

In short, open for any use without warranty. For details see the Boost software license at LICENSE_1_0.txt