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 ETimeSeason
104{
105 SEASON_SPRING = 0,
106 SEASON_SUMMER,
107 SEASON_AUTUMN,
108 SEASON_WINTER,
109 SEASON_EASTER,
110 SEASON_HALLOWEEN,
111 SEASON_XMAS,
112 SEASON_NEWYEAR
113};
114
115/**
116 * Retrieves the current season of the year.
117 *
118 * @ingroup Time
119 *
120 * @return One of the SEASON_* enum literals.
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 *
145 * @remark Guarantees that buffer string will contain null-termination.
146 */
147[[gnu::format(strftime, 3, 0)]] void str_timestamp_format(char *buffer, int buffer_size, const char *format);
148
149/**
150 * Copies a timestamp of the given time in the given format to the string.
151 *
152 * @ingroup Timestamp
153 *
154 * @param time The time value to represent as a string.
155 * @param buffer Pointer to a buffer that shall receive the timestamp string.
156 * @param buffer_size Size of the buffer.
157 * @param format Time formatting string. See https://cppreference.com/w/c/chrono/strftime.html for format description.
158 *
159 * @remark Guarantees that buffer string will contain null-termination.
160 */
161[[gnu::format(strftime, 4, 0)]] void str_timestamp_ex(time_t time, char *buffer, int buffer_size, const char *format);
162
163/**
164 * Parses a string into a timestamp following a specified format.
165 *
166 * @ingroup Timestamp
167 *
168 * @param string Pointer to the string to parse.
169 * @param format The time format to use (for example `FORMAT_NOSPACE` below).
170 * @param timestamp Pointer to the timestamp result.
171 *
172 * @return `true` on success, `false` if the string could not be parsed with the specified format.
173 */
174[[gnu::format(strftime, 2, 0)]] bool timestamp_from_str(const char *string, const char *format, time_t *timestamp);
175
176#define FORMAT_TIME "%H:%M:%S"
177#define FORMAT_SPACE "%Y-%m-%d %H:%M:%S"
178#define FORMAT_NOSPACE "%Y-%m-%d_%H-%M-%S"
179
180enum
181{
182 TIME_DAYS,
183 TIME_HOURS,
184 TIME_MINS,
185 TIME_HOURS_CENTISECS,
186 TIME_MINS_CENTISECS,
187 TIME_SECS_CENTISECS,
188};
189
190/**
191 * Formats a time string.
192 *
193 * @ingroup Timestamp
194 *
195 * @param centisecs Time in centiseconds.
196 * @param format Format of the time string, see enum above, for example `TIME_DAYS`.
197 * @param buffer Pointer to a buffer that shall receive the timestamp string.
198 * @param buffer_size Size of the buffer.
199 *
200 * @return Number of bytes written, `-1` on invalid format or `buffer_size <= 0`.
201 */
202int str_time(int64_t centisecs, int format, char *buffer, int buffer_size);
203
204/**
205 * Formats a time string.
206 *
207 * @ingroup Timestamp
208 *
209 * @param secs Time in seconds.
210 * @param format Format of the time string, see enum above, for example `TIME_DAYS`.
211 * @param buffer Pointer to a buffer that shall receive the timestamp string.
212 * @param buffer_size Size of the buffer.
213 *
214 * @remark The time is rounded to the nearest centisecond.
215 *
216 * @return Number of bytes written, `-1` on invalid format or `buffer_size <= 0`.
217 */
218int str_time_float(float secs, int format, char *buffer, int buffer_size);
219
220#endif
221