1/* (c) Magnus Auvinen. See licence.txt in the root of the distribution for more information. */
2/* If you are missing that file, acquire a complete release at teeworlds.com. */
3
4#ifndef BASE_TIME_H
5#define BASE_TIME_H
6
7#include <chrono>
8#include <cstdint>
9#include <ctime>
10
11/**
12 * Time utilities.
13 *
14 * @defgroup Time Time
15 *
16 * @ref Timestamp
17 */
18
19/**
20 * Timestamp related functions.
21 *
22 * @defgroup Timestamp Timestamps
23 *
24 * @ref Time
25 */
26
27/**
28 * Clears the cached sample of the high resolution timer.
29 *
30 * @ingroup Time
31 *
32 * @see time_get
33 */
34void set_new_tick();
35
36/**
37 * Fetches a sample from a high resolution timer and converts it to nanoseconds.
38 *
39 * @ingroup Time
40 *
41 * @return Current value of the timer in nanoseconds.
42 */
43std::chrono::nanoseconds time_get_nanoseconds();
44
45/**
46 * Fetches a sample from a high resolution timer.
47 *
48 * @ingroup Time
49 *
50 * @return Current value of the timer.
51 *
52 * @remark To know how fast the timer is ticking, see @link time_freq @endlink.
53 *
54 * @see time_freq
55 */
56int64_t time_get_impl();
57
58/**
59 * Fetches a cached sample from a high resolution timer.
60 *
61 * @ingroup Time
62 *
63 * @return Current value of the timer.
64 *
65 * @remark To know how fast the timer is ticking, see @link time_freq @endlink.
66 * @remark The value is cached for each tick, see @link set_new_tick @endlink.
67 * Uses @link time_get_impl @endlink to fetch the uncached sample.
68 *
69 * @see time_freq time_get_impl
70 */
71int64_t time_get();
72
73/**
74 * @ingroup Time
75 *
76 * @return The frequency of the high resolution timer.
77 */
78int64_t time_freq();
79
80/**
81 * Retrieves the current time as a UNIX timestamp.
82 *
83 * @ingroup Timestamp
84 *
85 * @return The time as a UNIX timestamp.
86 */
87int64_t time_timestamp();
88
89/**
90 * Retrieves the hours since midnight (0..23).
91 *
92 * @ingroup Time
93 *
94 * @return The current hour of the day.
95 */
96int time_houroftheday();
97
98/**
99 * A season of the year or seasonal event.
100 *
101 * @ingroup Time
102 */
103enum class ETimeSeason
104{
105 SPRING,
106 SUMMER,
107 AUTUMN,
108 WINTER,
109 EASTER,
110 HALLOWEEN,
111 XMAS,
112 NEWYEAR,
113};
114
115/**
116 * Retrieves the current season or event of the year.
117 *
118 * @ingroup Time
119 *
120 * @return The current season or event, see `ETimeSeason`.
121 */
122ETimeSeason time_season();
123
124/**
125 * Copies a timestamp of the current time in the format `year-month-day_hour-minute-second` to the string.
126 *
127 * @ingroup Timestamp
128 *
129 * @param buffer Pointer to a buffer that shall receive the timestamp string.
130 * @param buffer_size Size of the buffer.
131 *
132 * @remark Guarantees that buffer string will contain null-termination.
133 */
134void str_timestamp(char *buffer, int buffer_size);
135
136/**
137 * Copies a timestamp of the current time in the given format to the string.
138 *
139 * @ingroup Timestamp
140 *
141 * @param buffer Pointer to a buffer that shall receive the timestamp string.
142 * @param buffer_size Size of the buffer.
143 * @param format Time formatting string. See https://cppreference.com/w/c/chrono/strftime.html for format description.
144 * See `TimestampFormat` for common formats.
145 *
146 * @remark Guarantees that buffer string will contain null-termination.
147 */
148[[gnu::format(strftime, 3, 0)]] void str_timestamp_format(char *buffer, int buffer_size, const char *format);
149
150/**
151 * Copies a timestamp of the given time in the given format to the string.
152 *
153 * @ingroup Timestamp
154 *
155 * @param time The time value to represent as a string.
156 * @param buffer Pointer to a buffer that shall receive the timestamp string.
157 * @param buffer_size Size of the buffer.
158 * @param format Time formatting string. See https://cppreference.com/w/c/chrono/strftime.html for format description.
159 * See `TimestampFormat` for common formats.
160 *
161 * @remark Guarantees that buffer string will contain null-termination.
162 */
163[[gnu::format(strftime, 4, 0)]] void str_timestamp_ex(time_t time, char *buffer, int buffer_size, const char *format);
164
165/**
166 * Parses a string into a timestamp following a specified format.
167 *
168 * @ingroup Timestamp
169 *
170 * @param string Pointer to the string to parse.
171 * @param format The time format to use. See `TimestampFormat` for common formats.
172 * @param timestamp Pointer to the timestamp result.
173 *
174 * @return `true` on success, `false` if the string could not be parsed with the specified format.
175 */
176[[gnu::format(strftime, 2, 0)]] bool timestamp_from_str(const char *string, const char *format, time_t *timestamp);
177
178/**
179 * Timestamp format strings for the `str_timestamp_format`, `str_timestamp_ex` and `timestamp_from_str` functions.
180 *
181 * @ingroup Timestamp
182 *
183 * @see str_timestamp_format
184 * @see str_timestamp_ex
185 * @see timestamp_from_str
186 */
187namespace TimestampFormat
188{
189 inline const char *const TIME = "%H:%M:%S";
190 inline const char *const SPACE = "%Y-%m-%d %H:%M:%S";
191 inline const char *const NOSPACE = "%Y-%m-%d_%H-%M-%S";
192}
193
194/**
195 * Time formats for the `str_time` and `str_time_float` functions.
196 *
197 * @ingroup Timestamp
198 *
199 * @see str_time
200 * @see str_time_float
201 */
202enum class ETimeFormat
203{
204 DAYS,
205 HOURS,
206 MINS,
207 HOURS_CENTISECS,
208 MINS_CENTISECS,
209 SECS_CENTISECS,
210};
211
212/**
213 * Formats a time string.
214 *
215 * @ingroup Timestamp
216 *
217 * @param centisecs Time in centiseconds.
218 * @param format Format of the time string, see `ETimeFormat`.
219 * @param buffer Pointer to a buffer that shall receive the timestamp string.
220 * @param buffer_size Size of the buffer.
221 *
222 * @return Number of bytes written.
223 */
224int str_time(int64_t centisecs, ETimeFormat format, char *buffer, int buffer_size);
225
226/**
227 * Formats a time string.
228 *
229 * @ingroup Timestamp
230 *
231 * @param secs Time in seconds.
232 * @param format Format of the time string, see `ETimeFormat`.
233 * @param buffer Pointer to a buffer that shall receive the timestamp string.
234 * @param buffer_size Size of the buffer.
235 *
236 * @remark The time is rounded to the nearest centisecond.
237 *
238 * @return Number of bytes written.
239 */
240int str_time_float(float secs, ETimeFormat format, char *buffer, int buffer_size);
241
242#endif
243