+
+
+
+
+
+
+The following are a number of terms relevant to the date-time domain. +
+
A taxonomy of temporal types: +
And some other terms: +
Some standard date-time terminology: +
Some more experimental ones: +
These are design sorts of terms: +
+
++
+Overview -- +Compilation Options -- +Compiler/Portability Notes -- +Directory Structure -- +Required Boost Libraries +
+
+The library has several functions that require the creation of a library file. +The Jamfile in the build directory will produce a library +(libboost_date_time) that contains these functions. + +
+
+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. +
+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. + +
+
+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: +
+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/stadard libraries with this limitation include: +
+
+
+The date_time directory structure has been changed for boost submission. +
+The directory tree has the following structure: +
+ /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/examples/gregorian -- nifty example programs + /libs/date_time/src/gregorian -- cpp files for libboost_date_time + /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/src/posix_time -- empty (one file, but no source code...) ++
+ +
+The library depends on +
+
+
+
+
+Timepoints -- +Durations -- +Interval -- +Special Cases +
+ +
+This section describes some of basic arithmetic rules that can be performed with GDTL timepoints. + +
+ Timepoint + Duration --> Timepoint + Timepoint - Duration --> Timepoint + + Duration + Timepoint --> Undefined + Duration - Timepoint --> Undefined + + Timepoint + Timepoint --> Undefined + Timepoint - Timepoint --> Duration ++
+
+This section describes standard operations for a time duration. +
+ Duration + Duration --> Duration + Duration - Duration --> Duration + + Duration * Integer --> Duration + Integer * Duration --> Duration + + Duration(∞) * Integer --> Duration(∞) + Duration(∞)/Integer --> Duration(∞) ++
+ + +
+
+Here are the "operations" supported by intervals. They are based on half-open +range. + +
+ //These can be defined by either of 2 Timepoints or a Timepoint and Duration + Timeinterval intersects Timeinterval --> bool + Timeinterval intersection Timeinterval --> Timeperiod //results undefined if no intersection + Timeinterval contains Timepoint --> bool + Timeinterval contains Timeinterval --> bool + Timeinterval shift Duration --> shift start and end by duration amount + ++ +
+
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. +
+ Timepoint(NADT) + Duration --> Timepoint(NADT) + Timepoint(∞) + Duration --> Timepoint(∞) + Timepoint + Duration(∞) --> Timepoint(∞) + Timepoint - Duration(∞) --> Timepoint(-∞) ++ +
+
+
+
+
+ +
+
| Category | Description | Functions |
| Interfaces | +Provide concrete classes for manipulation of dates and times | +
+
|
+
| Calculation | +Provide a basis for performing efficient time calculations | +
+
|
| Representation Flexibility | +Provide the maximum possible reusability and flexibility | +
+
|
| Date Calculations | +Provide tools for date calculations | +
+
|
+
| Time Calculations | +Provide concrete classes for manipulation of time | +
+
|
+
| Clock Interfaces | +Provide classes for retrieving time current time | +
+
|
+
| I/O Interfaces | +Provide input and output for time including | +
+
|
+
+
+
+
+
+
+The following are a number of references and sources of information about the +date-time domain. +
+
+
+
+
+
+
+
+
++
+ +
+The library does its best to provide everything a user could want, but there are certain inherent constraints that limit what any temporal library can do. Specifically, a user much choose which two of the following three capabilities are desired in any particular application: +
+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. +
+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. +
+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. +
+
+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. +
+
+The representation of a type is stable 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. +
+An operation on a type is stable if the result of applying the operation to a particular operand(s) does not change over time. +
+
+ +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 +is_member( x ) +which determines whether a value x is a member of type T. +This predicate must return true, false, or dont_know. +
+If for all x, is_member( x ) returns either true or false, we +say the set T is well-defined. +
+If for any x, is_member( x ) returns dont_know, we say the +set T is ill-defined. +
+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: +
+For any temporal type T, there must be a predicate is_member( x, t ) +which determines whether a value x is a member of T. +The parameter t represents the time when the predicate is evaluated. +For each xi, there must be a time ti and a value v +such that: +
+If for all xi, ti = negative infinity, +we say the type T is predictable. +
+If for some xi, ti = positive infinity, +we say the type T is ill-formed. +
+Otherwise we say the type T is unpredictable (this +implies that for some xi, ti is finite). +
+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. + +
+
+Predictable types have a couple of important properties: +
+Unpredictable types have exactly the opposite properties: +
+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. +
+
+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. +
+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 +analagous to the user of integers, where results are expected +to be exact. +
+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. +
+ +
+
+
+
+
+Overall Index -- +Gregorian Index -- +Posix Time Index +
+Date Documentation +
+Header -- +Construction -- +Construct from String -- + Construct from Clock -- +Accessors -- +Conversion To String -- +Operators +
+
+The class boost::gregorian::date is the primary interface for library users. In general, the date class is immutable once constructed although it does allow assignment. + +
+Other techniques for creating dates include date iterators and date algorithms or generators. + +
+ +
+
+#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 ++
+
| Syntax | Description | Example |
| date(greg_year year, greg_month month, greg_day day) | +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. + | +date d(2002,Jan,10) |
| date(date d) | +Copy constructor | +date d1(d) |
| date(special_values sv) | +Constructor for infinitites, not-a-date-time, max_date, and min_date | +date d1(neg_infin); date d2(pos_infin); date d3(not_a_date_time); date d4(max_date); date d5(min_date); |
+
+
| Syntax | Description | Example |
| date from_string(const std::string&) | +From delimited date string where with order year-month-day eg: 2002-1-25 | +std::string ds("2002/1/25"); + date d(from_string(ds)) |
| date from_undelimited_string(const std::string&) | +From iso type date string where with order year-month-day eg: 20020125 | +std::string ds("20020125"); + date d(from_string(ds)) |
+ +
+
| Syntax | Description | Example |
| day_clock::local_day() | +Get the local day based on the time zone settings of the computer. | +date d(day_clock::local_day()) |
| day_clock::universal_day() | +Get the UTC day. | +date d(day_clock::universal_day()) |
+ +
+
| Syntax | Description | Example |
| greg_year year() const | +Get the year part of the date. | +date d(2002,Jan,10); d.year() --> 2002; |
| greg_month month() const | +Get the month part of the date. | +date d(2002,Jan,10); d.month() --> 1; |
| greg_day day() const | +Get the day part of the date. | +date d(2002,Jan,10); d.day() --> 10; |
| greg_ymd year_month_day() const | +Return a year_month_day struct. More efficient when all 3 parts of the date are needed. | +date d(2002,Jan,10);
+ date::ymd_type ymd = d.year_month_day(); + ymd.year --> 2002, ymd.month --> 1, ymd.day --> 10 |
| greg_day_of_week day_of_week() const | +Get the day of the week (eg: Sunday, Monday, etc. | +date d(2002,Jan,10); d.day() --> Thursday; |
| bool is_infinity() const | +Returns true if date is either possitive or negative infinity | +date d(pos_infin); d.is_infinity() --> true; |
| bool is_neg_infinity() const | +Returns true if date is negative infinity | +date d(neg_infin); d.is_neg_infinity() --> true; |
| bool is_pos_infinity() const | +Returns true if date is positive infinity | +date d(neg_infin); d.is_pos_infinity() --> true; |
| bool is_not_a_date() const | +Returns true if value is not a date | +date d(not_a_date_time); d.is_not_a_date() --> true; |
+
+
| Syntax | Description | Example |
| std::string to_simple_string(date d) | +To YYYY-mmm-DD string where mmm 3 char month name. | +2002-Jan-01 |
| std::string to_iso_string(date d) | +To YYYYMMDD where all components are integers. | +20020131 |
| std::string to_iso_extended_string(date d) | +To YYYY-MM-DD where all components are integers. | +2002-01-31 |
+ + +
+
| Syntax | Description | Example |
| operator==, operator!=, operator>, operator< + operator>=, operator<= |
+ A full complement of comparison operators | +d1 == d2, etc |
| date operator+(date_duration) const | +Return a date adding a day offset | +date d(2002,Jan,1);
+ date_duration dd(1); + date d2 = d + dd; |
| date operator-(date_duration) const | +Return a date by adding a day offset | +date d(2002,Jan,1);
+ date_duration dd(1); + date d2 = d - dd; |
| date_duration operator-(date) const | +Return a date duration by subtracting two dates | +date d1(2002,Jan,1);
+ date d2(2002,Jan,2); + date_duration dd = d2-d1; |
+
+
++
+Overall Index -- +Gregorian Index -- +Posix Time Index +
+Date Documentation +
+Header -- +Construction -- +Accessors -- +Operators +
+
+The class boost::gregorian::date_duration is a simple day count used for arithmetic with gregorian::date. A duration can be either positive or negative. +
+ +
+
+#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 ++
+ +
+
| Syntax | Description | Example |
| date_duration(long) | +Create a duration count. | +date_duration dd(3); //3 days |
+ +
+
| Syntax | Description | Example |
| long days() const | +Get the day count. | +date_duration dd(3); dd.days() --> 3 |
| bool is_negative() const | +True if number of days is less than zero.. | +date_duration dd(-1); dd.is_negative() --> true |
| static date_duration unit() | +Return smallest possible unit of duration type. | +date_duration::unit() --> date_duration(1) |
+ +
+
| Syntax | Description | Example |
| operator==, operator!=, + operator>, operator< + operator>=, operator<= |
+ A full complement of comparison operators | +dd1 == dd2, etc |
| date_duration operator+(date_duration) const | +Add date durations. | +date_duration dd1(3);
+ date_duration dd2(5); + date_duration dd3 = dd1 + dd2; |
| date_duration operator-(date_duration) const | +Subtract durations. | +date_duration dd1(3);
+ date_duration dd2(5); + date_duration dd3 = dd1 - dd2; |
+ + +
+
++
+
+Overall Index -- +Gregorian Index -- +Posix Time Index +
+Date Period Documentation +
+Header -- +Construction -- +Accessors -- +Conversion To String -- +Operators -- +
+
+The class boost::gregorian::date_period provides direct representation +for ranges between two dates. Periods provide the ability to simplify +some types of caculations by simplifing 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 period calculation +example provides an example of this. + + +
+Date periods used in combination with infinity values have the abilty +to represent complex concepts such as 'until further notice'. + +
+
+
+
+
+#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 ++ +
+
+
| Syntax | Description | Example |
| date_period(date begin, date last) | ++ Create a period as [begin, last). If last is <= begin then + the period will be defined as null. + | +date_period dp(date(2002,Jan,10), date_duration(2)); |
| date_period(date start, date end) | ++ Create a period as [begin, begin+len). If len is <= zero then + the period will be defined as null. + | +date_period dp(date(2002,Jan,10), date_duration(2)); |
| date_period(date_period rhs) | +Copy constructor | +date_period dp1(dp) |
+ +
+ +
+
| Syntax | Description | Example |
| date begin() const | +Return first day of period. | +date_period dp(date(2002,Jan,1), date(2002,Jan,10)); + dp.begin() --> 2002-Jan-01 |
| date last() const | +Return last date in the period | +date_period dp(date(2002,Jan,1), date(2002,Jan,10)); + dp.last() --> 2002-Jan-09 |
| date end() const | +Return one past the last in period | +date_period dp(date(2002,Jan,1), date(2002,Jan,10)); + dp.end() --> 2002-Jan-10 |
| bool is_null() const | +True if period is not well formed. eg: start less than end | +date_period dp(date(2002,Jan,10), date(2002,Jan,1)); + dp.begin() --> true |
| bool contains(date) const | +True if date is within the period | +date_period dp(date(2002,Jan,1), date(2002,Jan,10)); + dp.contains(date(2002,Jan,2)) --> true |
| bool contains(date_period) const | +True if date period is within the period | +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 |
| bool intersects(date_period) const | +True if periods overlap | +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 |
| date_period intersection(date_period) const | +Calculate the intersection of 2 periods. Null if no intersection. | +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) --> dp2 |
| date_period merge(date_period) const | +Returns union of two periods. Null if no intersection. | +date_period dp1(date(2002,Jan,1), date(2002,Jan,10)); + date_period dp2(date(2002,Jan,9), date(2002,Jan,31)); + dp2.intersects(dp1) --> 2002-Jan-01/2002-Jan-31 |
| date_period shift(date_duration) | +Add duration to both start and end. | +date_period dp1(date(2002,Jan,1), date(2002,Jan,10)); + dp1.shift(date_duration(1)); --> 2002-Jan-02/2002-Jan-11 |
+
+
| Syntax | Description | Example |
| std::string to_simple_string(date_period dp) | +To [YYYY-mmm-DD/YYYY-mmm-DD] string where mmm is 3 char month name. | +[2002-Jan-01/2002-Jan-31] |
+ + +
+
| Syntax | Description | Example |
| operator==, operator!=, operator>, operator< + | A full complement of comparison operators | +dp1 == dp2, etc |
| operator< | +True if dp1.end() less than dp2.begin() | +dp1 < dp2, etc |
| operator> | +True if dp1.begin() greater than dp2.end() | +dp1 > dp2, etc |
+ + +
+
++
+Introduction -- +Class Overview +
+
+The library provides for localized stream-based I/O of dates and times. +Note that this support is not supported for all compilers. See the +build information page for details. +
+ +
+
| Class | +Construction Parameters | +Description |
| date_iterator | ++ | Common base class for all day level iterators. |
| day_iterator | +date start_date, int day_count=1 | +Iterate day_count days at a time. |
| week_iterator | +date start_date, int week_offset=1 | +Iterate week_offset weeks at a time. |
| month_iterator | +date start_date, int month_offset=1 | +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. + |
| year_iterator | +date start_date, int year_offset=1 | +Iterate year_offset years |
+
+
+
+
+
+Overall Index -- +Gregorian Index -- +Posix Time Index +
+Date Documentation +
+
+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. + +
+For most purposes this class is simply accessed by +gregorian::date 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. +
+The print month example demonstrates this. +
+
+#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 ++
+ + +
+
| Syntax | Description | Example |
| static short day_of_week(ymd_type) | +Return the day of the week (0==Sunday, 1==Monday, etc) | +See also gregorian::date day_of_week |
| static date_int_type day_number(ymd_type) | +Convert a ymd_type into a day number. The day number is an absolute number of days since the epoch start. | +|
| static short end_of_month_day(year_type, month_type) | +Given a year and month determine the last day of the month. | +|
| static ymd_type from_day_number(date_int_type) | +Convert a day number to a ymd struct. | +|
| static bool is_leap_year(year_type) | +Returns true if specified year is a leap year. | +gregorian_calendar::is_leap_year(2000) --> true |
+ +
+
+
+
+
+ptime Documentation +
+Header -- +Construction -- +Construct from String -- +Construct from Clock -- +Accessors -- +Conversion To String -- +Operators +
+
+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. + +
+Class ptime is dependent on gregorian::date +for the interface to the date portion of a time point. +
+Other techniques for creating times include time iterators. + + +
+ + +
+
+#include "boost/date_time/posix_time/posix_time.hpp" //include all types plus i/o +or +#include "boost/date_time/posix_time/posix_time_types.hpp" //no i/o just types ++
+
+
| Syntax | Description | Example |
| ptime(date,time_duration) | +Construct from a date and offset + | +ptime t1(date(2002,Jan,10), time_duration(1,2,3)); + ptime t2(date(2002,Jan,10), hours(1)+nanosec(5)); |
| ptime(ptime) | +Copy constructor | +ptime t3(t1) |
+
+
| Syntax | Description | Example |
| ptime time_from_string(const std::string&) | +From delimited string. | +std::string ts("2002-01-20 23:59:59.000");
+ + date d(time_from_string(ts)) |
+ +
+
| Syntax | Description | Example |
| static ptime second_clock::local_time(); | +Get the local time, second level resolution, based on the time zone settings of the computer. | +ptime t(second_clock::local_time()) |
| static ptime second_clock::universal_time() | +Get the UTC time. | +ptime t(second_clock::universal_day()) |
+ +
+
| Syntax | Description | Example |
| date date() const | +Get the date part of a time. | +date d(2002,Jan,10); + ptime t(d, hour(1)); + t.date() --> 2002-Jan-10; |
| time_duration time_of_day() const | +Get the time offset in the day. | +date d(2002,Jan,10); + ptime t(d, hour(1)); + t.time_of_day() --> 01:00:00; |
+
+
| Syntax | Description | Example |
| std::string to_simple_string(ptime) | +To YYYY-mmm-DD HH:MM:SS.fffffffff string where mmm 3 char month name. Fractional seconds only included if non-zero. | +2002-Jan-01 10:00:01.123456789 |
| std::string to_iso_string(ptime) | +Convert to form YYYYMMDDTHHMMSS,fffffffff where T is the date-time separator | +20020131T100001,123456789 |
| std::string to_iso_extended_string(ptime) | +Convert to form YYYY-MM-DDTHH:MM:SS,fffffffff where T is the date-time separator | +2002-01-31T10:00:01,123456789 |
+ + +
+
| Syntax | Description | Example |
| operator==, operator!=, operator>, operator< + operator>=, operator<= |
+ A full complement of comparison operators | +t1 == t2, etc |
| ptime operator+(date_duration) const | +Return a ptime adding a day offset | +date d(2002,Jan,1); + ptime t(d,minutes(5)); + date_duration dd(1); + ptime t2 = t + dd; |
| ptime operator-(date_duration) const | +Return a ptime subtracting a day offset | +date d(2002,Jan,1); + ptime t(d,minutes(5)); + date_duration dd(1); + ptime t2 = t - dd; |
| ptime operator+(time_duration) const | +Return a ptime adding a time duration | +date d(2002,Jan,1); + ptime t(d,minutes(5)); + ptime t2 = t + hours(1) + minutes(2); |
| ptime operator-(time_duration) const | +Return a ptime subtracting a time duration | +date d(2002,Jan,1); + ptime t(d,minutes(5)); + ptime t2 = t - minutes(2); |
| time_duration operator-(ptime) const | +Take the difference between two times. | +date d(2002,Jan,1); + ptime t1(d,minutes(5)); + ptime t2(d,seconds(5)); + time_duration t3 = t2 - t1;//negative result |
+ + +
+
+
+
+
+
+Overall Index -- +Gregorian Index -- +Posix Time Index +
+Time Duration Documentation +
+Header -- +Construction -- +Count Based Construction -- +Construct from String -- +Accessors -- +Conversion To String -- +Operators +
+
+The class boost::posix_time::time_duration the base type reponsible for representing a length of time. A duration can be either positive or negative. +
+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. + +
+
+
+As an example: +
+ + using namespace boost::gregorian; + using namespace boost::posix_time; + + time_duration td = hours(1) + seconds(10); //01:00:01 + td = hours(1) + nanosec(5); //01:00:00.000000005 +
+
+#include "boost/date_time/posix_time/posix_time.hpp" //include all types plus i/o +or +#include "boost/date_time/posix_time/posix_time/posix_time_types.hpp" //no i/o just types ++
+ +
+
| Syntax | Description | Example |
| time_duration(hours,minutes,seconds,fractional_seconds) | +Construct ad duration from the counts | +time_duration td(1,2,3,9); //1 hr 2 min 3 sec 9 nanoseconds |
+
| Syntax | Description | Example |
| hours(long) | +Number of hours | +time_duration td = hours(3); |
| minutes(long) | +Number of minutes | +time_duration td = minutes(3); |
| seconds(long) | +Number of seconds | +time_duration td = seconds(3); |
| millisec(long) | +Number of millisec | +time_duration td = millisec(3); |
| nanosec(long) | +Number of nanosec | +time_duration td = nanosec(3); |
+ +
+
| Syntax | Description | Example |
| time_duration duration_from_string(const std::string&) | +From delimited string. | +std::string ts("23:59:59.000");
+ + time_duraton td(duration_from_string(ts)) |
+ +
+
| Syntax | Description | Example |
| long hours() const | +Get the number of hours. | +time_duration td(1,2,3); td.hours() --> 1 |
| long minutes() const | +Get the number of minutes normalized. | +time_duration td(1,2,3); td.minutes() --> 2 |
| long seconds() const | +Get the number of seconds. | +time_duration td(1,2,3); td.hours() --> 3 |
| long fractional_seconds() const | +Get the number of fractional seconds. | +time_duration td(1,2,3, 1000); td.fractional_seconds() --> 1000 |
| bool is_negative() const | +True if duration is negative. | +time_duration td(-1,0,0); td.is_negative() --> true |
| time_duration invert_sign() const | +Generate a new duration with the sign inverted/ | +time_duration td(-1,0,0); td.invert_sign() --> 01:00:00 |
| static gdtl::time_resolutions resolution() | +Describes the resolution capability of the time_duration class. | +time_duration::resolution() --> nano |
| boost::int64_t ticks() | +Return the raw count of the duration type. | +time_duration td(0,0,0, 1000); td.ticks() --> 1000 |
| static time_duration unit() | +Return smallest possible unit of duration type (1 nanosecond). | +time_duration::unit() --> time_duration(0,0,0,1) |
+ +
+
+
| Syntax | Description | Example |
| std::string to_simple_string(time_duration) | +To HH:MM:SS.fffffffff were fff is fractional seconds that are only included if non-zero. | +10:00:01.123456789 |
| std::string to_iso_string(time_duration) | +Convert to form HHMMSS,fffffffff. | +100001,123456789 |
+ +
+
| Syntax | Description | Example |
| operator==, operator!=, + operator>, operator< + operator>=, operator<= |
+ A full complement of comparison operators | +dd1 == dd2, etc |
| time_duration operator+(time_duration) const | +Add durations. | +time_duration td1(hours(1)+minutes(2));
+ time_duration td2(seconds(10)); + time_duration td3 = td1 + td2; |
| time_duration operator-(time_duration) const | +Subtract durations. | +time_duration td1(hours(1)+nanosec(2)); + time_duration td2 = td1 - minutes(1); |
+ + +
+
+
+
+
+Overall Index -- +Gregorian Index -- +Posix Time Index +
+Time Period Documentation +
+Header -- +Construction -- +Accessors -- +Conversion To String -- +Operators -- +More Info +
+
+The class boost::posix_time::time_period provides direct representation for ranges between two times. Periods provide the ability to simplify some types of caculations by simplifing the conditional logic of the program. + +
+The time periods example provides an example of using time periods. +
+
+
+
+#include "boost/date_time/posix_time/posix_time.hpp" //include all types plus i/o +or +#include "boost/date_time/posix_time/posix_time_types.hpp" //no i/o just types ++ +
+
+
| Syntax | Description | Example |
| time_period(ptime begin, ptime last) | ++ Create a period as [begin, last). If last is <= begin then + the period will be defined as null. + | +date d(2002,Jan,01); + ptime t(d, seconds(10)); //10 sec after midnight + time_period tp(t, hours(3)); |
| time_period(ptime start, ptime end) | ++ Create a period as [begin, begin+len). If len is <= zero then + the period will be defined as null. + | +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); |
| time_period(time_period rhs) | +Copy constructor | +time_period tp1(tp) |
+ +
+ +
+
| Syntax | Description | Example |
| ptime begin() const | +Return first time of period. | +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 |
| ptime last() const | +Return last time in the period | +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 |
| ptime end() const | +Return one past the last in period | +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 |
| bool is_null() const | +True if period is not well formed. eg: start less than end | +|
| bool contains(ptime) const | +True if ptime is within the period | +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 |
| bool contains(time_period) const | +True if period is within the period | +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 |
| bool intersects(time_period) const | +True if periods overlap | +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 |
| time_period intersection(time_period) const | +Calculate the intersection of 2 periods. Null if no intersection. | +|
| time_period merge(time_period) const | +Returns union of two periods. Null if no intersection. | +|
| time_period shift(date_duration) | +Add duration to both start and end. | +
+
+
| Syntax | Description | Example |
| std::string to_simple_string(time_period dp) | +To [YYYY-mmm-DD hh:mm:ss.fffffffff/YYYY-mmm-DD hh:mm:ss.fffffffff] string where mmm is 3 char month name. | +[2002-Jan-01 01:25:10.000000001/2002-Jan-31 01:25:10.123456789] |
+ + +
+
| Syntax | Description | Example |
| operator==, operator!=, operator>, operator< + | A full complement of comparison operators | +tp1 == tp2, etc |
| operator< | +True if tp1.end() less than tp2.begin() | +tp1 < tp2, etc |
| operator> | +True if tp1.begin() greater than tp2.end() | +tp1 > tp2, etc |
+ + +
+
+
++
+
+Overall Index -- +Gregorian Index -- +Posix Time Index +
+Date Generators / Algorithms +
+Header -- +Class Overview +
+
+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. +
+
using namespace boost::gregorian; + typedef boost::date_time::nth_kday_of_month<date> nkday; + nkday ldgen(nkday::first, Monday, Sep)); //US labor day + date labor_day = ldgen.get_date(2002); //Calculate labor day for 2002 +
+ The print holidays example shows a detailed usage example. +
+
+#include "boost/date_time/date_generators.hpp" ++ + +
+
+
| Class | +Construction Parameters | +get_date Parameter | +Description | +Example |
| first_kday_after | +greg_day_of_week day_of_week | +date start_day | +Calculate something like First Sunday after Jan 1,2002 | +first_kday_after fkaf(Monday); date d = fkaf.get_date(date(2002,Jan,1));//2002-Jan-07 |
| first_kday_before | +greg_day_of_week day_of_week | +date start_day | +Calculate something like First Monday before Feb 1,2002 | +first_kday_before fkbf(Monday); date d = fkbf.get_date(date(2002,Feb,1));//2002-Jan-28 |
| last_kday_of_month | +greg_day_of_week day_of_week greg_month month |
+ greg_year year | +Calculate something like last Monday of January | +last_kday_of_month lkm(Monday,Jan); date d = lkm.get_date(2002);//2002-Jan-28 |
| first_kday_of_month | +greg_day_of_week day_of_week greg_month month |
+ greg_year year | +Calculate something like first Monday of January | +first_kday_of_month fkm(Monday,Jan); date d = fkm.get_date(2002);//2002-Jan-07 |
| partial_date | +greg_month month greg_day day_of_month |
+ greg_year year | +Generates a date by applying the year to the given month and day. | +partial_date pd(Jan,1); date d = pd.get_date(2002);//2002-Jan-01 |
+ +
+
++
+Date Generators / Algorithms +
+Introduction -- +Header -- +Class Overview +
+
+
+
+Date iterators provide a standard mechanism for iteration through dates. +Date iterators are a model of +Input Iterator +and can be used to populate collections with dates and other date generation +tasks. For example, the print month example iterates through all the days in a month and prints them. +
+All of the iterators here derive from boost::gregorian::date_iterator. + +
+
+#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 ++
+
+
| Class | +Construction Parameters | +Description |
| date_iterator | ++ | Common base class for all day level iterators. |
| day_iterator | +date start_date, int day_count=1 | +Iterate day_count days at a time. |
| week_iterator | +date start_date, int week_offset=1 | +Iterate week_offset weeks at a time. |
| month_iterator | +date start_date, int month_offset=1 | +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. + |
| year_iterator | +date start_date, int year_offset=1 | +Iterate year_offset years |
+
/*
+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/gdtl/gregorian/gregorian.hpp"
+#include "boost/gdtl/date_parsing.hpp"
+#include <iostream>
+#include <string>
+
+
+
+int
+main()
+{
+
+ using namespace gregorian;
+
+ try {
+ // The following date is in ISO 8601 extended format (CCYY-MM-DD)
+ std::string s("2001-10-9"); //2001-October-05
+ date d(gdtl::parse_date<date>(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(gdtl::parse_undelimited_date<date>(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(gdtl::parse_undelimited_date<date>(bad_date));
+ //use wont_construct so compiler doesn't complain, but you wont get here!
+ std::cout << "oh oh, you should reach this line: "
+ << to_iso_string(wont_construct) << std::endl;
+ }
+ catch(std::exception& e) {
+ std::cout << " Exception: " << e.what() << std::endl;
+ }
+
+
+ return 0;
+}
++
+#include "boost/gdtl/gregorian/gregorian.hpp"
+#include "boost/gdtl/date_parsing.hpp"
+#include <iostream>
+
+int
+main()
+{
+
+ using namespace gregorian;
+ std::string s;
+ std::cout << "Enter birth day YYYY-MM-DD (eg: 2002-02-01): ";
+ std::cin >> s;
+ try {
+ date birthday(gdtl::parse_date<date>(s));
+ //date birthday(2002,Jan,1);
+ date today = day_clock::local_day();
+ date_duration days_alive = today - birthday;
+ date_duration one_day(1);
+ if (days_alive == one_day) {
+ std::cout << "Born yesterday, very funny" << std::endl;
+ }
+ else if (days_alive < date_duration(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;
+};
++
// This example displays the amount of time until new year's in days
+
+#include "boost/gdtl/gregorian/gregorian.hpp"
+#include <iostream>
+
+int
+main()
+{
+
+ using namespace gregorian;
+
+ date::ymd_type today = day_clock::local_day_ymd();
+ date new_years_day(today.year + 1,1,1);
+ date_duration dd = new_years_day - date(today);
+
+ std::cout << "Days till new year: " << dd.days() << std::endl;
+ return 0;
+};
+
+
++
+
+
+Introduction -- +Usage Examples
+Temporal Types +
+Class date -- +Class date_duration -- +Class date_period +
+Other Topics +
+Date Iterators -- +Date Generators / Algorithms -- +Class gregorian_calendar -- +Class day_clock +
+
+The gregorian date system provides a date programming system based on the Gregorian Calendar. The current implementation supports dates in the range 1400-Jan-01 to 10000-Jan-01. The implemented calendar is a "propleptic Gregorian calendar" thus extending dates back prior to it's first adoption in in 1582. + +
+Caution is required when handling historic dates as there are many adjustments required to account for the local adoption of various calendar systems. +See Calendrical Calculations by Reingold & Dershowitz for more details. The current historical range of the calendar is not limited by algorithm, but rather time to write and perform tests to ensure correctness. It is expected that the range of this calendar system will continue to increase in the future. +
+Date information from Calendrical Calculations has been used to cross-test the correctness of the Gregorian calendar implementation. +
+All types for the gregorian system are found in namespace boost::gregorian. The library supports a convience header boost/date_time/gregorian/gregorian_types.hpp that will include all the classes of the library with no input/output depedency. +Another header boost/date_time/gregorian/gregorian.hpp will include the types and the input/output code. +
+The class boost::gregorian::date 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 generators and algorithms page. + + +
+
+
| Example | Description |
| Days Alive Days Till New Year | Simple date arithmetic. Retrieve current day from clock. |
| Dates as strings | Simple parsing and formmatting of dates from/to strings |
| Date Period Calculations | See if a date is in a set of date periods (eg: is it a holiday/weekend) |
| Print a month | 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. |
| Print Holidays | Uses date generators to convert abstract specification into concrete set of dates. |
+ +
+
+
++
+Overview
+
+
+Introduction -- +Motivation -- +Usage Examples -- +Domain Concepts -- +Tests -- +Design and Extensions -- +Acknowledgements -- +More Info +
+Build-Compiler Information + +
+Date Programming
+Gregorian Date System
+
+Time Programming
+Posix Time System
+
+
+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. +
+
+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;
+ } 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;
+ }+ +
+
+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: +
+A Clock Device is software component (tied to some hardware) that provides the current date or time with respect to a time system. + +
+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: + +
+ ++ +
+
+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. +
+ +
+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. +
+ +
+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. + +
+
+The design of the library is currently being evolved using Wiki and email discussions. You can find more information at: +
+
+ ++
//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/gdtl/posix_time/posix_time.hpp"
+#include "boost/gdtl/local_time_adjustor.hpp"
+#include "boost/gdtl/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 gdtl::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 gdtl::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 gdtl::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;
+}
+
+
+
+
+
+
+Overall Index -- +Gregorian Index -- +Posix Time Index +
+Local Time Adjustment +
+Header -- +Class Overview -- +More Info +
+
+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. +
+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. +
+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 local utc conversion example demonstrates both of these techniques. + +
+
+#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 ++
+ +
+
| Class | +Description | +Example |
| date_time::c_local_adjustor<ptime>::utc_to_local(ptime) | +Calculate local machine time from a UTC time based on time zone settings and the C API. | +
+ 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); + |
| date_time::local_adjustor<ptime, utc_offset, dst_rules>::utc_to_local(ptime) | +Calculate local machine time from a UTC time based daylight savings rules and utc offset | +example + |
| date_time::local_adjustor<ptime, utc_offset, dst_rules>::local_to_utc(ptime) | +Calculate UTC time based on daylight savings rules and utc offset. | +example + |
+ + +
+
/*
+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/gdtl/gregorian/gregorian.hpp"
+#include <set>
+#include <algorithm>
+#include <iostream>
+
+typedef std::set<gregorian::date_period> date_period_set;
+
+//Simple population of the exclusion set
+date_period_set
+generateExclusion()
+{
+ using namespace 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 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;
+
+}
+
+
+
+
+
+
+
+
+Overall Index -- +Gregorian Index +
+Temporal Types +
+Class ptime -- +Class time_duration -- +Class time_period +
+Other Topics +
+Time Iterators -- +UTC / Local Time Adjustments + + +
+
+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. + +
+
| Example | Description |
| Time Math | A few simple calculations using ptime and time_durations. |
| Print Hours | Retrieve time from clock, use a time_iterator. |
| Local to UTC Conversion | Demonstrates a couple different ways to convert a local to UTC time including daylight savings rules. |
| Time periods | Some simple examples of intersection and display of time periods. |
+
/*generate a set of dates using a collections 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/gdtl/gregorian/gregorian.hpp"
+#include <algorithm>
+#include <functional>
+#include <vector>
+#include <iostream>
+#include <set>
+
+namespace std {
+ //define an operator << for date so transform can call
+ std::ostream&
+ operator<<(std::ostream& os, const gregorian::date& d)
+ {
+ os << gregorian::to_simple_string(d);
+ return os;
+ }
+
+}
+
+void
+print_date(gregorian::date d)
+{
+ std::cout << d << " [" << d.day_of_week().as_short_string() << "]\n";
+}
+
+
+int
+main() {
+
+ std::cout << "Enter Year: ";
+ int year;
+ std::cin >> year;
+
+
+ using namespace gregorian;
+
+ //define a collection of holidays fixed by month and day
+ std::vector<partial_date> holidays;
+ holidays.push_back(partial_date(Jan,1)); //Western New Year
+ holidays.push_back(partial_date(Jul,4)); //US Independence Day
+ holidays.push_back(partial_date(Dec,25));//Christmas day
+
+
+ //define a shorthand for the nkday function object
+ typedef gdtl::nth_kday_of_month<date> nkday;
+ //define a collection of nth kday holidays
+ std::vector<nkday> more_holidays;
+ more_holidays.push_back(nkday(nkday::first, Monday, Sep)); //US labor day
+ more_holidays.push_back(nkday(nkday::third, Monday, Jan)); //MLK Day
+ more_holidays.push_back(nkday(nkday::second, Tuesday, Feb)); //Pres day
+ more_holidays.push_back(nkday(nkday::fourth, Thursday, Nov)); //Thanksgiving
+
+ 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(&nkday::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;
+
+}
++
//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/gdtl/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 + date_duration(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;
+}
++
/*
+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/gdtl/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 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(gregorian::date(year,month,1));
+ //loop thru the days and print each one
+ for (; ditr <= endOfMonth; ++ditr) {
+ std::cout << gregorian::to_simple_string(*ditr) << " ["
+ << ditr->day_of_week().as_short_string() << "]"
+ << std::endl;
+ }
+ }
+ catch(std::exception& e) {
+
+ std::cout << "Error bad date, check your entry: \n"
+ << " Details: " << e.what() << std::endl;
+ }
+ return 0;
+}
++
//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/gdtl/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;
+}
+
++
//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/gdtl/posix_time/posix_time.hpp"
+#include <iostream>
+
+using namespace posix_time;
+using namespace 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;
+}
+
+
+
+
+
+
+Time Iterators +
+Introduction -- +Header -- +Class Overview + +
+
+Time iterators provide a standard mechanism for iteration through times. Time iterators are a model of +Input Iterator and can be used to populate collections with times. The following example +iterates using a 15 minute interation interval. +
+
+
+ using namespace boost::gregorian;
+ using namespace boost::posix_time;
+ date d(2000,Jan,20);
+ ptime start(d);//2000-Jan-20 00:00:00
+ time_iterator titr(start,minutes(15)); //iterate on 15 minute intervals
+ //produces 00:00:00, 00:15:00, 00:30:00, 00:45:00
+ for (; titr < ptime(d,hour(1)); ++titr) {
+ std::cout << to_simple_string(*titr) << std::endl;
+ }
++The print hours +example iterates through the remainder of the day incrementing by an hour. + +
+
+#include "boost/date_time/posix_time/posix_time.hpp" //include all types plus i/o +or +#include "boost/date_time/posix_time/posix_time_types.hpp" //no i/o just types ++
+
+
| Class | +Construction Parameters | +Description |
| time_iterator | +ptime start_time, time_duration increment | +Iterate incrementing by the specified duration. |