QuantLib: a free/open-source library for quantitative finance
fully annotated source code - version 1.34
Loading...
Searching...
No Matches
date.hpp
Go to the documentation of this file.
1/* -*- mode: c++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2
3/*
4 Copyright (C) 2000, 2001, 2002, 2003 RiskMap srl
5 Copyright (C) 2003, 2004, 2005, 2006 StatPro Italia srl
6 Copyright (C) 2004, 2005, 2006 Ferdinando Ametrano
7 Copyright (C) 2006 Katiuscia Manzoni
8 Copyright (C) 2006 Toyin Akin
9 Copyright (C) 2015 Klaus Spanderen
10 Copyright (C) 2020 Leonardo Arcari
11 Copyright (C) 2020 Kline s.r.l.
12
13 This file is part of QuantLib, a free-software/open-source library
14 for financial quantitative analysts and developers - http://quantlib.org/
15
16 QuantLib is free software: you can redistribute it and/or modify it
17 under the terms of the QuantLib license. You should have received a
18 copy of the license along with this program; if not, please email
19 <quantlib-dev@lists.sf.net>. The license is also available online at
20 <http://quantlib.org/license.shtml>.
21
22 This program is distributed in the hope that it will be useful, but WITHOUT
23 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
24 FOR A PARTICULAR PURPOSE. See the license for more details.
25*/
26
27/*! \file date.hpp
28 \brief date- and time-related classes, typedefs and enumerations
29*/
30
31#ifndef quantlib_date_hpp
32#define quantlib_date_hpp
33
34#include <ql/time/period.hpp>
35#include <ql/time/weekday.hpp>
36#include <ql/utilities/null.hpp>
37
38#ifdef QL_HIGH_RESOLUTION_DATE
39#include <boost/date_time/posix_time/ptime.hpp>
40#include <boost/date_time/posix_time/posix_time_duration.hpp>
41#endif
42
43#include <cstdint>
44#include <utility>
45#include <functional>
46#include <string>
47
48
49namespace QuantLib {
50
51 //! Day number
52 /*! \ingroup datetime */
53 typedef Integer Day;
54
55 //! Month names
56 /*! \ingroup datetime */
57 enum Month { January = 1,
59 March = 3,
60 April = 4,
61 May = 5,
62 June = 6,
63 July = 7,
64 August = 8,
66 October = 10,
69 Jan = 1,
70 Feb = 2,
71 Mar = 3,
72 Apr = 4,
73 Jun = 6,
74 Jul = 7,
75 Aug = 8,
76 Sep = 9,
77 Oct = 10,
78 Nov = 11,
79 Dec = 12
80 };
81
82 /*! \relates Month */
83 std::ostream& operator<<(std::ostream&, Month);
84
85 //! Year number
86 /*! \ingroup datetime */
87 typedef Integer Year;
88
89#ifdef QL_HIGH_RESOLUTION_DATE
90 //! Hour number
91 /*! \ingroup datetime */
92 typedef boost::posix_time::hours::hour_type Hour;
93
94 //! Minute number
95 /*! \ingroup datetime */
96 typedef boost::posix_time::minutes::min_type Minute;
97
98 //! Second number
99 /*! \ingroup datetime */
100 typedef boost::posix_time::minutes::sec_type Second;
101
102 //! Millisecond number
103 /*! \ingroup datetime */
104 typedef boost::posix_time::time_duration::fractional_seconds_type
105 Millisecond;
106
107 //! Microsecond number
108 /*! \ingroup datetime */
109 typedef boost::posix_time::time_duration::fractional_seconds_type
110 Microsecond;
111#endif
112
113 //! Concrete date class
114 /*! This class provides methods to inspect dates as well as methods and
115 operators which implement a limited date algebra (increasing and
116 decreasing dates, and calculating their difference).
117
118 \ingroup datetime
119
120 \test self-consistency of dates, serial numbers, days of
121 month, months, and weekdays is checked over the whole
122 date range.
123 */
124
125 class Date {
126 public:
127 //! serial number type
128 typedef std::int_fast32_t serial_type;
129 //! \name constructors
130 //@{
131 //! Default constructor returning a null date.
132 Date();
133 //! Constructor taking a serial number as given by Applix or Excel.
135 //! More traditional constructor.
136 Date(Day d, Month m, Year y);
137
138#ifdef QL_HIGH_RESOLUTION_DATE
139 //! Constructor taking boost posix date time object
140 explicit Date(const boost::posix_time::ptime& localTime);
141 //! More traditional constructor.
142 Date(Day d, Month m, Year y,
143 Hour hours, Minute minutes, Second seconds,
144 Millisecond millisec = 0, Microsecond microsec = 0);
145#endif
146 //@}
147
148 //! \name inspectors
149 //@{
150 Weekday weekday() const;
151 Day dayOfMonth() const;
152 //! One-based (Jan 1st = 1)
153 Day dayOfYear() const;
154 Month month() const;
155 Year year() const;
157
158#ifdef QL_HIGH_RESOLUTION_DATE
159 Hour hours() const;
160 Minute minutes() const;
161 Second seconds() const;
162 Millisecond milliseconds() const;
163 Microsecond microseconds() const;
164
165 Time fractionOfDay() const;
166 Time fractionOfSecond() const;
167
168 const boost::posix_time::ptime& dateTime() const;
169#endif
170 //@}
171
172 //! \name date algebra
173 //@{
174 //! increments date by the given number of days
176 //! increments date by the given period
177 Date& operator+=(const Period&);
178 //! decrement date by the given number of days
180 //! decrements date by the given period
181 Date& operator-=(const Period&);
182 //! 1-day pre-increment
183 Date& operator++();
184 //! 1-day post-increment
185 Date operator++(int );
186 //! 1-day pre-decrement
187 Date& operator--();
188 //! 1-day post-decrement
189 Date operator--(int );
190 //! returns a new date incremented by the given number of days
192 //! returns a new date incremented by the given period
193 Date operator+(const Period&) const;
194 //! returns a new date decremented by the given number of days
196 //! returns a new date decremented by the given period
197 Date operator-(const Period&) const;
198 //@}
199
200 //! \name static methods
201 //@{
202 //! today's date.
203 static Date todaysDate();
204 //! earliest allowed date
205 static Date minDate();
206 //! latest allowed date
207 static Date maxDate();
208 //! whether the given year is a leap one
209 static bool isLeap(Year y);
210 //! last day of the month to which the given date belongs
211 static Date endOfMonth(const Date& d);
212 //! whether a date is the last day of its month
213 static bool isEndOfMonth(const Date& d);
214 //! next given weekday following or equal to the given date
215 /*! E.g., the Friday following Tuesday, January 15th, 2002
216 was January 18th, 2002.
217
218 see http://www.cpearson.com/excel/DateTimeWS.htm
219 */
220 static Date nextWeekday(const Date& d,
221 Weekday w);
222 //! n-th given weekday in the given month and year
223 /*! E.g., the 4th Thursday of March, 1998 was March 26th,
224 1998.
225
226 see http://www.cpearson.com/excel/DateTimeWS.htm
227 */
228 static Date nthWeekday(Size n,
229 Weekday w,
230 Month m,
231 Year y);
232
233#ifdef QL_HIGH_RESOLUTION_DATE
234 //! local date time, based on the time zone settings of the computer
235 static Date localDateTime();
236 //! UTC date time
237 static Date universalDateTime();
238
239 //! underlying resolution of the posix date time object
240 static boost::posix_time::time_duration::tick_type ticksPerSecond();
241#endif
242
243 //@}
244
245 private:
249
250#ifdef QL_HIGH_RESOLUTION_DATE
251 boost::posix_time::ptime dateTime_;
252#else
254 static Date advance(const Date& d, Integer units, TimeUnit);
255 static Integer monthLength(Month m, bool leapYear);
256 static Integer monthOffset(Month m, bool leapYear);
258#endif
259 };
260
261 /*! \relates Date
262 \brief Difference in days between dates
263 */
264 Date::serial_type operator-(const Date&, const Date&);
265 /*! \relates Date
266 \brief Difference in days (including fraction of days) between dates
267 */
268 Time daysBetween(const Date&, const Date&);
269
270 /*! \relates Date */
271 bool operator==(const Date&, const Date&);
272 /*! \relates Date */
273 bool operator!=(const Date&, const Date&);
274 /*! \relates Date */
275 bool operator<(const Date&, const Date&);
276 /*! \relates Date */
277 bool operator<=(const Date&, const Date&);
278 /*! \relates Date */
279 bool operator>(const Date&, const Date&);
280 /*! \relates Date */
281 bool operator>=(const Date&, const Date&);
282
283 /*!
284 Compute a hash value of @p d.
285
286 This method makes Date hashable via <tt>boost::hash</tt>.
287
288 Example:
289
290 \code{.cpp}
291 #include <unordered_set>
292
293 std::unordered_set<Date> set;
294 Date d = Date(1, Jan, 2020);
295
296 set.insert(d);
297 assert(set.count(d)); // 'd' was added to 'set'
298 \endcode
299
300 \param [in] d Date to hash
301 \return A hash value of @p d
302 \relates Date
303 */
304 std::size_t hash_value(const Date& d);
305
306 /*! \relates Date */
307 std::ostream& operator<<(std::ostream&, const Date&);
308
309 namespace detail {
310
312 explicit short_date_holder(const Date d) : d(d) {}
314 };
315 std::ostream& operator<<(std::ostream&, const short_date_holder&);
316
318 explicit long_date_holder(const Date& d) : d(d) {}
320 };
321 std::ostream& operator<<(std::ostream&, const long_date_holder&);
322
324 explicit iso_date_holder(const Date& d) : d(d) {}
326 };
327 std::ostream& operator<<(std::ostream&, const iso_date_holder&);
328
330 formatted_date_holder(const Date& d, std::string f) : d(d), f(std::move(f)) {}
332 std::string f;
333 };
334 std::ostream& operator<<(std::ostream&,
335 const formatted_date_holder&);
336
337#ifdef QL_HIGH_RESOLUTION_DATE
338 struct iso_datetime_holder {
339 explicit iso_datetime_holder(const Date& d) : d(d) {}
340 Date d;
341 };
342 std::ostream& operator<<(std::ostream&, const iso_datetime_holder&);
343#endif
344 }
345
346 namespace io {
347
348 //! output dates in short format (mm/dd/yyyy)
349 /*! \ingroup manips */
350 detail::short_date_holder short_date(const Date&);
351
352 //! output dates in long format (Month ddth, yyyy)
353 /*! \ingroup manips */
354 detail::long_date_holder long_date(const Date&);
355
356 //! output dates in ISO format (yyyy-mm-dd)
357 /*! \ingroup manips */
358 detail::iso_date_holder iso_date(const Date&);
359
360 //! output dates in user defined format using boost date functionality
361 /*! \ingroup manips */
362 detail::formatted_date_holder formatted_date(const Date&,
363 const std::string& fmt);
364
365#ifdef QL_HIGH_RESOLUTION_DATE
366 //! output datetimes in ISO format (YYYY-MM-DDThh:mm:ss,SSSSSS)
367 /*! \ingroup manips */
368 detail::iso_datetime_holder iso_datetime(const Date&);
369#endif
370
371 }
372
373 #ifdef QL_NULL_AS_FUNCTIONS
374
375 //! specialization of Null template for the Date class
376 template <>
377 inline Date Null<Date>() {
378 return {};
379 }
380
381 #else
382
383 template <>
384 class Null<Date> {
385 public:
386 Null() = default;
387 operator Date() const { return {}; }
388 };
389
390 #endif
391
392#ifndef QL_HIGH_RESOLUTION_DATE
393 // inline definitions
394
395 inline Weekday Date::weekday() const {
396 Integer w = serialNumber_ % 7;
397 return Weekday(w == 0 ? 7 : w);
398 }
399
400 inline Day Date::dayOfMonth() const {
401 return dayOfYear() - monthOffset(month(),isLeap(year()));
402 }
403
404 inline Day Date::dayOfYear() const {
405 return serialNumber_ - yearOffset(year());
406 }
407
409 return serialNumber_;
410 }
411
413 return Date(serialNumber_+days);
414 }
415
417 return Date(serialNumber_-days);
418 }
419
420 inline Date Date::operator+(const Period& p) const {
421 return advance(*this,p.length(),p.units());
422 }
423
424 inline Date Date::operator-(const Period& p) const {
425 return advance(*this,-p.length(),p.units());
426 }
427
428 inline Date Date::endOfMonth(const Date& d) {
429 Month m = d.month();
430 Year y = d.year();
431 return {monthLength(m, isLeap(y)), m, y};
432 }
433
434 inline bool Date::isEndOfMonth(const Date& d) {
435 return (d.dayOfMonth() == monthLength(d.month(), isLeap(d.year())));
436 }
437
438 inline Date::serial_type operator-(const Date& d1, const Date& d2) {
439 return d1.serialNumber()-d2.serialNumber();
440 }
441
442 inline Time daysBetween(const Date& d1, const Date& d2) {
443 return Time(d2-d1);
444 }
445
446 inline bool operator==(const Date& d1, const Date& d2) {
447 return (d1.serialNumber() == d2.serialNumber());
448 }
449
450 inline bool operator!=(const Date& d1, const Date& d2) {
451 return (d1.serialNumber() != d2.serialNumber());
452 }
453
454 inline bool operator<(const Date& d1, const Date& d2) {
455 return (d1.serialNumber() < d2.serialNumber());
456 }
457
458 inline bool operator<=(const Date& d1, const Date& d2) {
459 return (d1.serialNumber() <= d2.serialNumber());
460 }
461
462 inline bool operator>(const Date& d1, const Date& d2) {
463 return (d1.serialNumber() > d2.serialNumber());
464 }
465
466 inline bool operator>=(const Date& d1, const Date& d2) {
467 return (d1.serialNumber() >= d2.serialNumber());
468 }
469#endif
470}
471
472namespace std {
473 template<>
474 struct hash<QuantLib::Date> {
475 std::size_t operator()(const QuantLib::Date& d) const {
476 return QuantLib::hash_value(d);
477 }
478 };
479}
480
481#endif
Concrete date class.
Definition: date.hpp:125
Date & operator-=(Date::serial_type days)
decrement date by the given number of days
Definition: date.cpp:113
static Date::serial_type yearOffset(Year y)
Definition: date.cpp:283
static Date minDate()
earliest allowed date
Definition: date.cpp:766
Month month() const
Definition: date.cpp:82
Year year() const
Definition: date.cpp:93
Day dayOfMonth() const
Definition: date.hpp:400
static Date todaysDate()
today's date.
Definition: date.cpp:788
static Date::serial_type maximumSerialNumber()
Definition: date.cpp:753
Date operator-(Date::serial_type days) const
returns a new date decremented by the given number of days
Definition: date.hpp:416
Date::serial_type serialNumber_
Definition: date.hpp:253
Date operator+(Date::serial_type days) const
returns a new date incremented by the given number of days
Definition: date.hpp:412
Date & operator+=(Date::serial_type days)
increments date by the given number of days
Definition: date.cpp:101
Date & operator--()
1-day pre-decrement
Definition: date.cpp:132
static Date endOfMonth(const Date &d)
last day of the month to which the given date belongs
Definition: date.hpp:428
static Integer monthOffset(Month m, bool leapYear)
Definition: date.cpp:269
Weekday weekday() const
Definition: date.hpp:395
Date & operator++()
1-day pre-increment
Definition: date.cpp:125
static Integer monthLength(Month m, bool leapYear)
Definition: date.cpp:259
Day dayOfYear() const
One-based (Jan 1st = 1)
Definition: date.hpp:404
static bool isEndOfMonth(const Date &d)
whether a date is the last day of its month
Definition: date.hpp:434
std::int_fast32_t serial_type
serial number type
Definition: date.hpp:128
Date::serial_type serialNumber() const
Definition: date.hpp:408
static Date advance(const Date &d, Integer units, TimeUnit)
Definition: date.cpp:139
static Date::serial_type minimumSerialNumber()
Definition: date.cpp:749
static void checkSerialNumber(Date::serial_type serialNumber)
Definition: date.cpp:757
static Date nthWeekday(Size n, Weekday w, Month m, Year y)
n-th given weekday in the given month and year
Definition: date.cpp:802
static bool isLeap(Year y)
whether the given year is a leap one
Definition: date.cpp:187
static Date nextWeekday(const Date &d, Weekday w)
next given weekday following or equal to the given date
Definition: date.cpp:797
static Date maxDate()
latest allowed date
Definition: date.cpp:771
Date()
Default constructor returning a null date.
Definition: date.cpp:58
template class providing a null value for a given type.
Definition: null.hpp:76
TimeUnit units() const
Definition: period.hpp:51
Integer length() const
Definition: period.hpp:50
Date d
Integer Year
Year number.
Definition: date.hpp:87
Integer Day
Day number.
Definition: date.hpp:53
TimeUnit
Units used to describe time periods.
Definition: timeunit.hpp:37
Month
Month names.
Definition: date.hpp:57
@ Jul
Definition: date.hpp:74
@ December
Definition: date.hpp:68
@ August
Definition: date.hpp:64
@ Jan
Definition: date.hpp:69
@ January
Definition: date.hpp:57
@ Mar
Definition: date.hpp:71
@ Nov
Definition: date.hpp:78
@ Aug
Definition: date.hpp:75
@ Oct
Definition: date.hpp:77
@ Feb
Definition: date.hpp:70
@ Jun
Definition: date.hpp:73
@ July
Definition: date.hpp:63
@ Dec
Definition: date.hpp:79
@ May
Definition: date.hpp:61
@ March
Definition: date.hpp:59
@ February
Definition: date.hpp:58
@ April
Definition: date.hpp:60
@ November
Definition: date.hpp:67
@ October
Definition: date.hpp:66
@ Apr
Definition: date.hpp:72
@ June
Definition: date.hpp:62
@ Sep
Definition: date.hpp:76
@ September
Definition: date.hpp:65
detail::short_date_holder short_date(const Date &d)
output dates in short format (mm/dd/yyyy)
Definition: date.cpp:983
detail::long_date_holder long_date(const Date &d)
output dates in long format (Month ddth, yyyy)
Definition: date.cpp:987
detail::formatted_date_holder formatted_date(const Date &d, const std::string &f)
output dates in user defined format using boost date functionality
Definition: date.cpp:995
detail::iso_date_holder iso_date(const Date &d)
output dates in ISO format (yyyy-mm-dd)
Definition: date.cpp:991
Real Time
continuous quantity with 1-year units
Definition: types.hpp:62
QL_INTEGER Integer
integer number
Definition: types.hpp:35
std::size_t Size
size of a container
Definition: types.hpp:58
std::ostream & operator<<(std::ostream &out, const short_date_holder &holder)
Definition: date.cpp:894
Definition: any.hpp:35
Quantity operator-(const Quantity &m1, const Quantity &m2)
Definition: quantity.hpp:171
bool operator==(const Currency &c1, const Currency &c2)
Definition: currency.hpp:231
bool operator<(const Quantity &m1, const Quantity &m2)
Definition: quantity.cpp:125
bool operator>=(const Quantity &m1, const Quantity &m2)
Definition: quantity.hpp:201
std::ostream & operator<<(std::ostream &out, GFunctionFactory::YieldCurveModel type)
bool operator!=(const Currency &c1, const Currency &c2)
Definition: currency.hpp:236
bool operator>(const Quantity &m1, const Quantity &m2)
Definition: quantity.hpp:197
Real days(const Period &p)
Definition: period.cpp:330
std::size_t hash_value(const Date &d)
Definition: date.cpp:846
bool operator<=(const Quantity &m1, const Quantity &m2)
Definition: quantity.cpp:144
Time daysBetween(const Date &d1, const Date &d2)
Definition: date.hpp:442
STL namespace.
null values
period- and frequency-related classes and enumerations
formatted_date_holder(const Date &d, std::string f)
Definition: date.hpp:330
iso_date_holder(const Date &d)
Definition: date.hpp:324
long_date_holder(const Date &d)
Definition: date.hpp:318
std::size_t operator()(const QuantLib::Date &d) const
Definition: date.hpp:475
Weekday enumeration.