MRPT  2.0.4
datetime.h
Go to the documentation of this file.
1 /* +------------------------------------------------------------------------+
2  | Mobile Robot Programming Toolkit (MRPT) |
3  | https://www.mrpt.org/ |
4  | |
5  | Copyright (c) 2005-2020, Individual contributors, see AUTHORS file |
6  | See: https://www.mrpt.org/Authors - All rights reserved. |
7  | Released under BSD License. See: https://www.mrpt.org/License |
8  +------------------------------------------------------------------------+ */
9 #pragma once
10 
11 #include <mrpt/core/Clock.h>
12 #include <mrpt/core/exceptions.h>
13 #include <cstdint>
14 #include <iosfwd>
15 #include <string>
16 
17 namespace mrpt::system
18 {
19 /** @defgroup time_date Time and date functions.
20  * Header: `#include <mrpt/system/datetime.h>`.
21  * Library: \ref mrpt_system_grp
22  *
23  * Defines types and functions to handle cross-platform timestamps. The basic
24  * type is mrpt::system::TTimeStamp, representing a high-resolution (100ns)
25  * Clock::time_point, compatible with all C++11 std::chrono functions.
26  *
27  * There are also functions to convert forth and back to a `double`
28  * representation of timestamps: numbers just like UNIX epoch timestamps but
29  * with decimals for the fractionary part of seconds.
30  *
31  * \ingroup mrpt_system_grp
32  * @{ */
33 
34 /** A system independent time type, it holds the the number of 100-nanosecond
35  * intervals since January 1, 1601 (UTC) as a mrpt::Clock::time_point
36  * (uint64_t).
37  * \sa system::getCurrentTime, system::timeDifference, INVALID_TIMESTAMP,
38  * TTimeParts
39  */
41 
42 /** Represents an invalid timestamp, where applicable. */
43 #define INVALID_TIMESTAMP mrpt::Clock::time_point()
44 
45 /** The parts of a date/time (it's like the standard 'tm' but with fractions of
46  * seconds).
47  * \sa TTimeStamp, timestampToParts, buildTimestampFromParts
48  */
49 struct TTimeParts
50 {
51  uint16_t year{0}; /** The year */
52  uint8_t month{0}; /** Month (1-12) */
53  uint8_t day{0}; /** Day (1-31) */
54  uint8_t hour{0}; /** Hour (0-23) */
55  uint8_t minute{0}; /** Minute (0-59) */
56  double second{0}; /** Seconds (0.0000-59.9999) */
57  uint8_t day_of_week{0}; /** Day of week (1:Sunday, 7:Saturday) */
59 };
60 
61 /** Builds a timestamp from the parts (Parts are in UTC)
62  * \sa timestampToParts
63  */
65  const mrpt::system::TTimeParts& p);
66 
67 /** Builds a timestamp from the parts (Parts are in local time)
68  * \sa timestampToParts, buildTimestampFromParts
69  */
71  const mrpt::system::TTimeParts& p);
72 
73 /** Gets the individual parts of a date/time (days, hours, minutes, seconds) -
74  * UTC time or local time
75  * \sa buildTimestampFromParts
76  */
77 void timestampToParts(TTimeStamp t, TTimeParts& p, bool localTime = false);
78 
79 /** Returns the current (UTC) system time.
80  * \sa now
81  */
83 /** A shortcut for system::getCurrentTime
84  * \sa getCurrentTime
85  */
87 /** Transform from standard "time_t" (actually a double number, it can contain
88  * fractions of seconds) to TTimeStamp.
89  * \sa timestampTotime_t
90  */
92 {
93  return mrpt::Clock::fromDouble(t);
94 }
95 
96 /** Transform from standard "time_t" to TTimeStamp.
97  * \sa timestampTotime_t
98  */
100 
101 /** Transform from TTimeStamp to standard "time_t" (actually a double number, it
102  * can contain fractions of seconds).
103  * \sa time_tToTimestamp
104  */
105 inline double timestampTotime_t(const mrpt::system::TTimeStamp t) noexcept
106 {
107  return mrpt::Clock::toDouble(t);
108 }
109 
110 /** Transform from TTimeStamp to standard "time_t" (actually a double number, it
111  * can contain fractions of seconds).
112  * This function is just an (inline) alias of timestampTotime_t(), with a more
113  * significant name.
114  * \sa time_tToTimestamp
115  */
116 inline double timestampToDouble(const mrpt::system::TTimeStamp t) noexcept
117 {
118  return timestampTotime_t(t);
119 }
120 
121 /** Returns the time difference from t1 to t2 (positive if t2 is posterior to
122  * t1), in seconds */
123 inline double timeDifference(
124  const mrpt::system::TTimeStamp t_first,
125  const mrpt::system::TTimeStamp t_later)
126 {
127  MRPT_START
128  ASSERT_(t_later != INVALID_TIMESTAMP);
129  ASSERT_(t_first != INVALID_TIMESTAMP);
130  return 1e-6 * std::chrono::duration_cast<std::chrono::microseconds>(
131  t_later - t_first)
132  .count();
133  MRPT_END
134 }
135 
136 /** Returns the current time, as a `double` (fractional version of time_t)
137  * instead of a `TTimeStamp`.
138  * \sa now(), timestampTotime_t() */
139 inline double now_double()
140 {
142 }
143 
144 /** Shifts a timestamp the given amount of seconds (>0: forwards in time, <0:
145  * backwards) */
147  const mrpt::system::TTimeStamp tim, const double num_seconds)
148 {
149  return tim +
150  std::chrono::microseconds(static_cast<int64_t>(num_seconds * 1e6));
151 }
152 
153 /** Returns a formated string with the given time difference (passed as the
154  * number of seconds), as a string [H]H:MM:SS.MILLISECONDS
155  * \sa unitsFormat
156  */
157 std::string formatTimeInterval(const double timeSeconds);
158 
159 /** Convert a timestamp into this textual form (UTC time):
160  * YEAR/MONTH/DAY,HH:MM:SS.MMM
161  * \sa dateTimeLocalToString
162  */
163 std::string dateTimeToString(const mrpt::system::TTimeStamp t);
164 
165 /** Convert a timestamp into this textual form (in local time):
166  * YEAR/MONTH/DAY,HH:MM:SS.MMM
167  * \sa dateTimeToString
168  */
170 
171 /** Convert a timestamp into this textual form: YEAR/MONTH/DAY
172  */
173 std::string dateToString(const mrpt::system::TTimeStamp t);
174 
175 /** Returns the number of seconds ellapsed from midnight in the given timestamp
176  */
178 
179 /** Convert a timestamp into this textual form (UTC): HH:MM:SS.MMMMMM
180  */
181 std::string timeToString(const mrpt::system::TTimeStamp t);
182 
183 /** Convert a timestamp into this textual form (in local time): HH:MM:SS.MMMMMM
184  */
185 std::string timeLocalToString(
186  const mrpt::system::TTimeStamp t, unsigned int secondFractionDigits = 6);
187 
188 /** This function implements time interval formatting: Given a time in seconds,
189  * it will return a string describing the interval with the most appropriate
190  * unit.
191  * E.g.: 1.23 year, 3.50 days, 9.3 hours, 5.3 minutes, 3.34 sec, 178.1 ms, 87.1
192  * us.
193  * \sa unitsFormat
194  */
195 std::string intervalFormat(const double seconds);
196 
197 /** Textual representation of a TTimeStamp as the plain number in
198  * time_since_epoch().count() */
199 std::ostream& operator<<(std::ostream& o, const TTimeStamp& t);
200 
201 /** @} */
202 
203 } // namespace mrpt::system
static double toDouble(const time_point t) noexcept
Converts a timestamp to a UNIX time_t-like number, with fractional part.
Definition: Clock.cpp:106
void timestampToParts(TTimeStamp t, TTimeParts &p, bool localTime=false)
Gets the individual parts of a date/time (days, hours, minutes, seconds) - UTC time or local time...
Definition: datetime.cpp:50
std::ostream & operator<<(std::ostream &o, const TTimeStamp &t)
Textual representation of a TTimeStamp as the plain number in time_since_epoch().count() ...
Definition: datetime.cpp:303
#define MRPT_START
Definition: exceptions.h:241
static time_point fromDouble(const double t) noexcept
Create a timestamp from its double representation.
Definition: Clock.cpp:99
std::chrono::time_point< Clock > time_point
Definition: Clock.h:25
double timestampToDouble(const mrpt::system::TTimeStamp t) noexcept
Transform from TTimeStamp to standard "time_t" (actually a double number, it can contain fractions of...
Definition: datetime.h:116
mrpt::system::TTimeStamp getCurrentTime()
Returns the current (UTC) system time.
Definition: datetime.h:82
double now_double()
Returns the current time, as a double (fractional version of time_t) instead of a TTimeStamp...
Definition: datetime.h:139
mrpt::system::TTimeStamp buildTimestampFromParts(const mrpt::system::TTimeParts &p)
Builds a timestamp from the parts (Parts are in UTC)
Definition: datetime.cpp:74
uint8_t day_of_week
Seconds (0.0000-59.9999)
Definition: datetime.h:57
mrpt::system::TTimeStamp now()
A shortcut for system::getCurrentTime.
Definition: datetime.h:86
double extractDayTimeFromTimestamp(const mrpt::system::TTimeStamp t)
Returns the number of seconds ellapsed from midnight in the given timestamp.
Definition: datetime.cpp:197
std::string timeToString(const mrpt::system::TTimeStamp t)
Convert a timestamp into this textual form (UTC): HH:MM:SS.MMMMMM.
Definition: datetime.cpp:244
std::string formatTimeInterval(const double timeSeconds)
Returns a formated string with the given time difference (passed as the number of seconds)...
Definition: datetime.cpp:124
static time_point now() noexcept
Returns the current time using the currently selected Clock source.
Definition: Clock.cpp:94
#define ASSERT_(f)
Defines an assertion mechanism.
Definition: exceptions.h:120
mrpt::Clock::time_point TTimeStamp
A system independent time type, it holds the the number of 100-nanosecond intervals since January 1...
Definition: datetime.h:40
int daylight_saving
Day of week (1:Sunday, 7:Saturday)
Definition: datetime.h:58
std::string dateToString(const mrpt::system::TTimeStamp t)
Convert a timestamp into this textual form: YEAR/MONTH/DAY.
Definition: datetime.cpp:263
The parts of a date/time (it&#39;s like the standard &#39;tm&#39; but with fractions of seconds).
Definition: datetime.h:49
double timestampTotime_t(const mrpt::system::TTimeStamp t) noexcept
Transform from TTimeStamp to standard "time_t" (actually a double number, it can contain fractions of...
Definition: datetime.h:105
std::string intervalFormat(const double seconds)
This function implements time interval formatting: Given a time in seconds, it will return a string d...
Definition: datetime.cpp:283
uint8_t day
Month (1-12)
Definition: datetime.h:53
double second
Minute (0-59)
Definition: datetime.h:56
mrpt::system::TTimeStamp buildTimestampFromPartsLocalTime(const mrpt::system::TTimeParts &p)
Builds a timestamp from the parts (Parts are in local time)
Definition: datetime.cpp:99
uint8_t minute
Hour (0-23)
Definition: datetime.h:55
std::string dateTimeToString(const mrpt::system::TTimeStamp t)
Convert a timestamp into this textual form (UTC time): YEAR/MONTH/DAY,HH:MM:SS.MMM.
Definition: datetime.cpp:154
#define MRPT_END
Definition: exceptions.h:245
std::string timeLocalToString(const mrpt::system::TTimeStamp t, unsigned int secondFractionDigits=6)
Convert a timestamp into this textual form (in local time): HH:MM:SS.MMMMMM.
Definition: datetime.cpp:222
uint8_t month
The year.
Definition: datetime.h:52
mrpt::system::TTimeStamp timestampAdd(const mrpt::system::TTimeStamp tim, const double num_seconds)
Shifts a timestamp the given amount of seconds (>0: forwards in time, <0: backwards) ...
Definition: datetime.h:146
uint8_t hour
Day (1-31)
Definition: datetime.h:54
double timeDifference(const mrpt::system::TTimeStamp t_first, const mrpt::system::TTimeStamp t_later)
Returns the time difference from t1 to t2 (positive if t2 is posterior to t1), in seconds...
Definition: datetime.h:123
std::string dateTimeLocalToString(const mrpt::system::TTimeStamp t)
Convert a timestamp into this textual form (in local time): YEAR/MONTH/DAY,HH:MM:SS.MMM.
Definition: datetime.cpp:176
mrpt::system::TTimeStamp time_tToTimestamp(const double t)
Transform from standard "time_t" (actually a double number, it can contain fractions of seconds) to T...
Definition: datetime.h:91
#define INVALID_TIMESTAMP
Represents an invalid timestamp, where applicable.
Definition: datetime.h:43



Page generated by Doxygen 1.8.14 for MRPT 2.0.4 Git: 33de1d0ad Sat Jun 20 11:02:42 2020 +0200 at sáb jun 20 17:35:17 CEST 2020