Main MRPT website > C++ reference
MRPT logo
datetime.h
Go to the documentation of this file.
1 /* +---------------------------------------------------------------------------+
2  | The Mobile Robot Programming Toolkit (MRPT) C++ library |
3  | |
4  | http://www.mrpt.org/ |
5  | |
6  | Copyright (C) 2005-2012 University of Malaga |
7  | |
8  | This software was written by the Machine Perception and Intelligent |
9  | Robotics Lab, University of Malaga (Spain). |
10  | Contact: Jose-Luis Blanco <jlblanco@ctima.uma.es> |
11  | |
12  | This file is part of the MRPT project. |
13  | |
14  | MRPT is free software: you can redistribute it and/or modify |
15  | it under the terms of the GNU General Public License as published by |
16  | the Free Software Foundation, either version 3 of the License, or |
17  | (at your option) any later version. |
18  | |
19  | MRPT is distributed in the hope that it will be useful, |
20  | but WITHOUT ANY WARRANTY; without even the implied warranty of |
21  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
22  | GNU General Public License for more details. |
23  | |
24  | You should have received a copy of the GNU General Public License |
25  | along with MRPT. If not, see <http://www.gnu.org/licenses/>. |
26  | |
27  +---------------------------------------------------------------------------+ */
28 #ifndef MRPT_SYSTEM_DATETIME_H
29 #define MRPT_SYSTEM_DATETIME_H
30 
31 #include <mrpt/utils/utils_defs.h>
32 
33 /** Represents an invalid timestamp, where applicable. */
34 #define INVALID_TIMESTAMP (0)
35 
36 namespace mrpt
37 {
38  namespace system
39  {
40  /** @defgroup time_date Time and date functions (in #include <mrpt/system/datetime.h>)
41  * \ingroup mrpt_base_grp
42  * @{ */
43 
44  /** A system independent time type, it holds the the number of 100-nanosecond intervals since January 1, 1601 (UTC).
45  * \sa system::getCurrentTime, system::timeDifference, INVALID_TIMESTAMP, TTimeParts
46  */
47  typedef uint64_t TTimeStamp;
48 
49  /** The parts of a date/time (it's like the standard 'tm' but with fractions of seconds).
50  * \sa TTimeStamp, timestampToParts, buildTimestampFromParts
51  */
52  struct TTimeParts
53  {
54  uint16_t year; /** The year */
55  uint8_t month; /** Month (1-12) */
56  uint8_t day; /** Day (1-31) */
57  uint8_t hour; /** Hour (0-23) */
58  uint8_t minute; /** Minute (0-59) */
59  double second; /** Seconds (0.0000-59.9999) */
60  uint8_t day_of_week; /** Day of week (1:Sunday, 7:Saturday) */
61  int daylight_saving;
62  };
63 
64  /** Builds a timestamp from the parts (Parts are in UTC)
65  * \sa timestampToParts
66  */
67  mrpt::system::TTimeStamp BASE_IMPEXP buildTimestampFromParts( const mrpt::system::TTimeParts &p );
68 
69  /** Builds a timestamp from the parts (Parts are in local time)
70  * \sa timestampToParts, buildTimestampFromParts
71  */
72  mrpt::system::TTimeStamp BASE_IMPEXP buildTimestampFromPartsLocalTime( const mrpt::system::TTimeParts &p );
73 
74  /** Gets the individual parts of a date/time (days, hours, minutes, seconds) - UTC time or local time
75  * \sa buildTimestampFromParts
76  */
77  void BASE_IMPEXP timestampToParts( TTimeStamp t, TTimeParts &p, bool localTime = false );
78 
79  /** Returns the current (UTC) system time.
80  * \sa now,getCurrentLocalTime
81  */
82  mrpt::system::TTimeStamp BASE_IMPEXP getCurrentTime( );
83 
84  /** A shortcut for system::getCurrentTime
85  * \sa getCurrentTime, getCurrentLocalTime
86  */
87  inline mrpt::system::TTimeStamp now() {
88  return getCurrentTime();
89  }
90 
91  /** Returns the current (local) time.
92  * \sa now,getCurrentTime
93  */
94  mrpt::system::TTimeStamp BASE_IMPEXP getCurrentLocalTime( );
95 
96  /** Transform from standard "time_t" (actually a double number, it can contain fractions of seconds) to TTimeStamp.
97  * \sa timestampTotime_t
98  */
99  mrpt::system::TTimeStamp BASE_IMPEXP time_tToTimestamp( const double &t );
100 
101  /** Transform from standard "time_t" to TTimeStamp.
102  * \sa timestampTotime_t
103  */
104  mrpt::system::TTimeStamp BASE_IMPEXP time_tToTimestamp( const time_t &t );
105 
106  /** Transform from TTimeStamp to standard "time_t" (actually a double number, it can contain fractions of seconds).
107  * \sa time_tToTimestamp, secondsToTimestamp
108  */
109  double BASE_IMPEXP timestampTotime_t( const mrpt::system::TTimeStamp &t );
110 
111  /** Transform from TTimeStamp to standard "time_t" (actually a double number, it can contain fractions of seconds).
112  * This function is just an (inline) alias of timestampTotime_t(), with a more significant name.
113  * \sa time_tToTimestamp, secondsToTimestamp
114  */
115  inline double timestampToDouble( const mrpt::system::TTimeStamp &t ) { return timestampTotime_t(t); }
116 
117  /** Retuns the time difference from t1 to t2 (positive if t2 is posterior to t1), in seconds.
118  * \sa secondsToTimestamp
119  */
120  double BASE_IMPEXP timeDifference( const mrpt::system::TTimeStamp &t_first, const mrpt::system::TTimeStamp &t_later );
121 
122  /** Transform a time interval (in seconds) into TTimeStamp (e.g. which can be added to an existing valid timestamp)
123  * \sa timeDifference
124  */
125  mrpt::system::TTimeStamp BASE_IMPEXP secondsToTimestamp( const double &nSeconds );
126 
127  /** Returns a formated string with the given time difference (passed as the number of seconds), as a string [H]H:MM:SS.MILISECS
128  * \sa unitsFormat
129  */
130  std::string BASE_IMPEXP formatTimeInterval( const double &timeSeconds );
131 
132  /** Convert a timestamp into this textual form (UTC time): YEAR/MONTH/DAY,HH:MM:SS.MMM
133  * \sa dateTimeLocalToString
134  */
135  std::string BASE_IMPEXP dateTimeToString(const mrpt::system::TTimeStamp &t);
136 
137  /** Convert a timestamp into this textual form (in local time): YEAR/MONTH/DAY,HH:MM:SS.MMM
138  * \sa dateTimeToString
139  */
140  std::string BASE_IMPEXP dateTimeLocalToString(const mrpt::system::TTimeStamp &t);
141 
142  /** Convert a timestamp into this textual form: YEAR/MONTH/DAY
143  */
144  std::string BASE_IMPEXP dateToString(const mrpt::system::TTimeStamp &t);
145 
146  /** Returns the number of seconds ellapsed from midnight in the given timestamp
147  */
148  double BASE_IMPEXP extractDayTimeFromTimestamp(const mrpt::system::TTimeStamp &t);
149 
150  /** Convert a timestamp into this textual form (UTC): HH:MM:SS.MMMMMM
151  */
152  std::string BASE_IMPEXP timeToString(const mrpt::system::TTimeStamp &t);
153 
154  /** Convert a timestamp into this textual form (in local time): HH:MM:SS.MMMMMM
155  */
156  std::string BASE_IMPEXP timeLocalToString(const mrpt::system::TTimeStamp &t, unsigned int secondFractionDigits=6);
157 
158  /** This function implements time interval formatting: Given a time in seconds, it will return a string describing the interval with the most appropriate unit.
159  * E.g.: 1.23 year, 3.50 days, 9.3 hours, 5.3 minutes, 3.34 sec, 178.1 ms, 87.1 us.
160  * \sa unitsFormat
161  */
162  std::string BASE_IMPEXP intervalFormat(const double seconds);
163 
164  /** @} */
165 
166  } // End of namespace
167 
168 } // End of namespace
169 
170 #endif


Page generated by Doxygen 1.8.3 for MRPT 0.9.6 SVN: at Fri Feb 15 22:05:02 EST 2013