1//
2// Copyright (c) 2019-2024 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
3//
4// Distributed under the Boost Software License, Version 1.0. (See accompanying
5// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6//
7
8#ifndef BOOST_MYSQL_DATETIME_HPP
9#define BOOST_MYSQL_DATETIME_HPP
10
11#include <boost/mysql/days.hpp>
12
13#include <boost/mysql/detail/config.hpp>
14#include <boost/mysql/detail/datetime.hpp>
15
16#include <boost/assert.hpp>
17#include <boost/config.hpp>
18#include <boost/throw_exception.hpp>
19
20#include <chrono>
21#include <cstdint>
22#include <iosfwd>
23#include <ratio>
24#include <stdexcept>
25
26namespace boost {
27namespace mysql {
28
29/**
30 * \brief Type representing MySQL `DATETIME` and `TIMESTAMP` data types.
31 * \details Represents a broken datetime by its year, month, day, hour, minute, second and
32 * microsecond components. This type is close to the protocol and should not be used as a vocabulary
33 * type. Instead, cast it to a `std::chrono::time_point` by calling \ref as_time_point or \ref
34 * get_time_point.
35 * \n
36 * As opposed to `time_point`, this type allows representing invalid and zero datetimes.
37 */
38class datetime
39{
40public:
41 /**
42 * \brief A `std::chrono::time_point` that can represent any valid datetime.
43 * \details Represents microseconds since the UNIX epoch, with the same precision for all architectures.
44 */
45 using time_point = std::chrono::
46 time_point<std::chrono::system_clock, std::chrono::duration<std::int64_t, std::micro>>;
47
48 /**
49 * \brief Constructs a zero datetime.
50 * \details Results in a datetime with all of its components set to zero.
51 * \par Exception safety
52 * No-throw guarantee.
53 */
54 constexpr datetime() noexcept = default;
55
56 /**
57 * \brief Constructs a datetime from its individual components.
58 * \par Exception safety
59 * No-throw guarantee.
60 */
61 constexpr datetime(
62 std::uint16_t year,
63 std::uint8_t month,
64 std::uint8_t day,
65 std::uint8_t hour = 0,
66 std::uint8_t minute = 0,
67 std::uint8_t second = 0,
68 std::uint32_t microsecond = 0
69 ) noexcept
70 : year_(year),
71 month_(month),
72 day_(day),
73 hour_(hour),
74 minute_(minute),
75 second_(second),
76 microsecond_(microsecond)
77 {
78 }
79
80 /**
81 * \brief Constructs a datetime from a `time_point`.
82 * \par Exception safety
83 * Strong guarantee. Throws on invalid input.
84 * \throws std::out_of_range If the resulting `datetime` object would be
85 * out of the [\ref min_datetime, \ref max_datetime] range.
86 */
87 BOOST_CXX14_CONSTEXPR inline explicit datetime(time_point tp);
88
89 /**
90 * \brief Retrieves the year component.
91 * \par Exception safety
92 * No-throw guarantee.
93 */
94 constexpr std::uint16_t year() const noexcept { return year_; }
95
96 /**
97 * \brief Retrieves the month component.
98 * \par Exception safety
99 * No-throw guarantee.
100 */
101 constexpr std::uint8_t month() const noexcept { return month_; }
102
103 /**
104 * \brief Retrieves the day component.
105 * \par Exception safety
106 * No-throw guarantee.
107 */
108 constexpr std::uint8_t day() const noexcept { return day_; }
109
110 /**
111 * \brief Retrieves the hour component.
112 * \par Exception safety
113 * No-throw guarantee.
114 */
115 constexpr std::uint8_t hour() const noexcept { return hour_; }
116
117 /**
118 * \brief Retrieves the minute component.
119 * \par Exception safety
120 * No-throw guarantee.
121 */
122 constexpr std::uint8_t minute() const noexcept { return minute_; }
123
124 /**
125 * \brief Retrieves the second component.
126 * \par Exception safety
127 * No-throw guarantee.
128 */
129 constexpr std::uint8_t second() const noexcept { return second_; }
130
131 /**
132 * \brief Retrieves the microsecond component.
133 * \par Exception safety
134 * No-throw guarantee.
135 */
136 constexpr std::uint32_t microsecond() const noexcept { return microsecond_; }
137
138 /**
139 * \brief Returns `true` if `*this` represents a valid `time_point`.
140 * \details If any of the individual components is out of range, the datetime
141 * doesn't represent an actual `time_point` (e.g. `datetime(2020, 2, 30)`) or
142 * the datetime is not in the [\ref min_date, \ref max_date] validity range,
143 * returns `false`. Otherwise, returns `true`.
144 *
145 * \par Exception safety
146 * No-throw guarantee.
147 */
148 constexpr bool valid() const noexcept
149 {
150 return detail::is_valid(years: year_, month: month_, day: day_) && hour_ <= detail::max_hour &&
151 minute_ <= detail::max_min && second_ <= detail::max_sec && microsecond_ <= detail::max_micro;
152 }
153
154 /**
155 * \brief Converts `*this` into a `time_point` (unchecked access).
156 * \par Preconditions
157 * `this->valid() == true` (if violated, results in undefined behavior).
158 *
159 * \par Exception safety
160 * No-throw guarantee.
161 */
162 BOOST_CXX14_CONSTEXPR time_point get_time_point() const noexcept
163 {
164 BOOST_ASSERT(valid());
165 return unch_get_time_point();
166 }
167
168 /**
169 * \brief Converts `*this` into a `time_point` (checked access).
170 * \par Exception safety
171 * Strong guarantee.
172 * \throws std::invalid_argument If `!this->valid()`.
173 */
174 BOOST_CXX14_CONSTEXPR inline time_point as_time_point() const
175 {
176 if (!valid())
177 BOOST_THROW_EXCEPTION(std::invalid_argument("datetime::as_time_point: invalid datetime"));
178 return unch_get_time_point();
179 }
180
181 /**
182 * \brief Tests for equality.
183 * \details Two datetimes are considered equal if all of its individual components
184 * are equal. This function works for invalid datetimes, too.
185 *
186 * \par Exception safety
187 * No-throw guarantee.
188 */
189 constexpr bool operator==(const datetime& rhs) const noexcept
190 {
191 return year_ == rhs.year_ && month_ == rhs.month_ && day_ == rhs.day_ && hour_ == rhs.hour_ &&
192 minute_ == rhs.minute_ && second_ == rhs.second_ && microsecond_ == rhs.microsecond_;
193 }
194
195 /**
196 * \brief Tests for inequality.
197 * \par Exception safety
198 * No-throw guarantee.
199 */
200 constexpr bool operator!=(const datetime& rhs) const noexcept { return !(*this == rhs); }
201
202 /**
203 * \brief Returns the current system time as a datetime object.
204 * \par Exception safety
205 * Strong guarantee. Only throws if obtaining the current time throws.
206 */
207 static datetime now()
208 {
209 auto now = time_point::clock::now();
210 return datetime(std::chrono::time_point_cast<time_point::duration>(t: now));
211 }
212
213private:
214 std::uint16_t year_{};
215 std::uint8_t month_{};
216 std::uint8_t day_{};
217 std::uint8_t hour_{};
218 std::uint8_t minute_{};
219 std::uint8_t second_{};
220 std::uint32_t microsecond_{};
221
222 BOOST_CXX14_CONSTEXPR inline time_point unch_get_time_point() const noexcept
223 {
224 // Doing time of day independently to prevent overflow
225 days d(detail::ymd_to_days(years: year_, month: month_, day: day_));
226 auto time_of_day = std::chrono::hours(hour_) + std::chrono::minutes(minute_) +
227 std::chrono::seconds(second_) + std::chrono::microseconds(microsecond_);
228 return time_point(d) + time_of_day;
229 }
230};
231
232/**
233 * \relates datetime
234 * \brief Streams a datetime.
235 * \details This function works for invalid datetimes, too.
236 */
237BOOST_MYSQL_DECL
238std::ostream& operator<<(std::ostream& os, const datetime& v);
239
240/// The minimum allowed value for \ref datetime.
241constexpr datetime min_datetime(0u, 1u, 1u);
242
243/// The maximum allowed value for \ref datetime.
244constexpr datetime max_datetime(9999u, 12u, 31u, 23u, 59u, 59u, 999999u);
245
246} // namespace mysql
247} // namespace boost
248
249// Implementations
250BOOST_CXX14_CONSTEXPR boost::mysql::datetime::datetime(time_point tp)
251{
252 using std::chrono::duration_cast;
253 using std::chrono::hours;
254 using std::chrono::microseconds;
255 using std::chrono::minutes;
256 using std::chrono::seconds;
257
258 // Avoiding using -= for durations as it's not constexpr until C++17
259 auto input_dur = tp.time_since_epoch();
260 auto rem = input_dur % days(1);
261 auto num_days = duration_cast<days>(d: input_dur);
262 if (rem.count() < 0)
263 {
264 rem = rem + days(1);
265 num_days = num_days - days(1);
266 }
267 auto num_hours = duration_cast<hours>(d: rem);
268 rem = rem - num_hours;
269 auto num_minutes = duration_cast<minutes>(d: rem);
270 rem = rem - num_minutes;
271 auto num_seconds = duration_cast<seconds>(d: rem);
272 rem = rem - num_seconds;
273 auto num_microseconds = duration_cast<microseconds>(d: rem);
274
275 BOOST_ASSERT(num_hours.count() >= 0 && num_hours.count() <= detail::max_hour);
276 BOOST_ASSERT(num_minutes.count() >= 0 && num_minutes.count() <= detail::max_min);
277 BOOST_ASSERT(num_seconds.count() >= 0 && num_seconds.count() <= detail::max_sec);
278 BOOST_ASSERT(num_microseconds.count() >= 0 && num_microseconds.count() <= detail::max_micro);
279
280 bool ok = detail::days_to_ymd(num_days: num_days.count(), years&: year_, month&: month_, day&: day_);
281 if (!ok)
282 BOOST_THROW_EXCEPTION(std::out_of_range("datetime::datetime: time_point was out of range"));
283
284 microsecond_ = static_cast<std::uint32_t>(num_microseconds.count());
285 second_ = static_cast<std::uint8_t>(num_seconds.count());
286 minute_ = static_cast<std::uint8_t>(num_minutes.count());
287 hour_ = static_cast<std::uint8_t>(num_hours.count());
288}
289
290#ifdef BOOST_MYSQL_HEADER_ONLY
291#include <boost/mysql/impl/datetime.ipp>
292#endif
293
294#endif
295

source code of boost/libs/mysql/include/boost/mysql/datetime.hpp