Branch data Line data Source code
1 : : /*
2 : : * Copyright (C) 2009-2010 Christian Hergert <chris@dronelabs.com>
3 : : * Copyright © 2010 Codethink Limited
4 : : *
5 : : * SPDX-License-Identifier: LGPL-2.1-or-later
6 : : *
7 : : * This library is free software; you can redistribute it and/or modify
8 : : * it under the terms of the GNU Lesser General Public License as
9 : : * published by the Free Software Foundation; either version 2.1 of the
10 : : * licence, or (at your option) any later version.
11 : : *
12 : : * This is distributed in the hope that it will be useful, but WITHOUT
13 : : * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14 : : * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
15 : : * License for more details.
16 : : *
17 : : * You should have received a copy of the GNU Lesser General Public License
18 : : * along with this library; if not, see <http://www.gnu.org/licenses/>.
19 : : *
20 : : * Authors: Christian Hergert <chris@dronelabs.com>
21 : : * Thiago Santos <thiago.sousa.santos@collabora.co.uk>
22 : : * Emmanuele Bassi <ebassi@linux.intel.com>
23 : : * Ryan Lortie <desrt@desrt.ca>
24 : : */
25 : :
26 : : #ifndef __G_DATE_TIME_H__
27 : : #define __G_DATE_TIME_H__
28 : :
29 : : #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
30 : : #error "Only <glib.h> can be included directly."
31 : : #endif
32 : :
33 : : #include <glib/gtimezone.h>
34 : :
35 : : G_BEGIN_DECLS
36 : :
37 : : /**
38 : : * G_TIME_SPAN_DAY:
39 : : *
40 : : * Evaluates to a time span of one day.
41 : : *
42 : : * Since: 2.26
43 : : */
44 : : #define G_TIME_SPAN_DAY (G_GINT64_CONSTANT (86400000000))
45 : :
46 : : /**
47 : : * G_TIME_SPAN_HOUR:
48 : : *
49 : : * Evaluates to a time span of one hour.
50 : : *
51 : : * Since: 2.26
52 : : */
53 : : #define G_TIME_SPAN_HOUR (G_GINT64_CONSTANT (3600000000))
54 : :
55 : : /**
56 : : * G_TIME_SPAN_MINUTE:
57 : : *
58 : : * Evaluates to a time span of one minute.
59 : : *
60 : : * Since: 2.26
61 : : */
62 : : #define G_TIME_SPAN_MINUTE (G_GINT64_CONSTANT (60000000))
63 : :
64 : : /**
65 : : * G_TIME_SPAN_SECOND:
66 : : *
67 : : * Evaluates to a time span of one second.
68 : : *
69 : : * Since: 2.26
70 : : */
71 : : #define G_TIME_SPAN_SECOND (G_GINT64_CONSTANT (1000000))
72 : :
73 : : /**
74 : : * G_TIME_SPAN_MILLISECOND:
75 : : *
76 : : * Evaluates to a time span of one millisecond.
77 : : *
78 : : * Since: 2.26
79 : : */
80 : : #define G_TIME_SPAN_MILLISECOND (G_GINT64_CONSTANT (1000))
81 : :
82 : : /**
83 : : * GTimeSpan:
84 : : *
85 : : * A value representing an interval of time, in microseconds.
86 : : *
87 : : * Since: 2.26
88 : : */
89 : : typedef gint64 GTimeSpan;
90 : :
91 : : /**
92 : : * GDateTime:
93 : : *
94 : : * `GDateTime` is a structure that combines a Gregorian date and time
95 : : * into a single structure.
96 : : *
97 : : * `GDateTime` provides many conversion and methods to manipulate dates and times.
98 : : * Time precision is provided down to microseconds and the time can range
99 : : * (proleptically) from 0001-01-01 00:00:00 to 9999-12-31 23:59:59.999999.
100 : : * `GDateTime` follows POSIX time in the sense that it is oblivious to leap
101 : : * seconds.
102 : : *
103 : : * `GDateTime` is an immutable object; once it has been created it cannot
104 : : * be modified further. All modifiers will create a new `GDateTime`.
105 : : * Nearly all such functions can fail due to the date or time going out
106 : : * of range, in which case %NULL will be returned.
107 : : *
108 : : * `GDateTime` is reference counted: the reference count is increased by calling
109 : : * [method@GLib.DateTime.ref] and decreased by calling [method@GLib.DateTime.unref].
110 : : * When the reference count drops to 0, the resources allocated by the `GDateTime`
111 : : * structure are released.
112 : : *
113 : : * Many parts of the API may produce non-obvious results. As an
114 : : * example, adding two months to January 31st will yield March 31st
115 : : * whereas adding one month and then one month again will yield either
116 : : * March 28th or March 29th. Also note that adding 24 hours is not
117 : : * always the same as adding one day (since days containing daylight
118 : : * savings time transitions are either 23 or 25 hours in length).
119 : : *
120 : : * Since: 2.26
121 : : */
122 : : typedef struct _GDateTime GDateTime;
123 : :
124 : : GLIB_AVAILABLE_IN_ALL
125 : : void g_date_time_unref (GDateTime *datetime);
126 : : GLIB_AVAILABLE_IN_ALL
127 : : GDateTime * g_date_time_ref (GDateTime *datetime);
128 : :
129 : : GLIB_AVAILABLE_IN_ALL
130 : : GDateTime * g_date_time_new_now (GTimeZone *tz);
131 : : GLIB_AVAILABLE_IN_ALL
132 : : GDateTime * g_date_time_new_now_local (void);
133 : : GLIB_AVAILABLE_IN_ALL
134 : : GDateTime * g_date_time_new_now_utc (void);
135 : :
136 : : GLIB_AVAILABLE_IN_ALL
137 : : GDateTime * g_date_time_new_from_unix_local (gint64 t);
138 : : GLIB_AVAILABLE_IN_ALL
139 : : GDateTime * g_date_time_new_from_unix_utc (gint64 t);
140 : :
141 : : GLIB_AVAILABLE_IN_2_80
142 : : GDateTime * g_date_time_new_from_unix_local_usec (gint64 usecs);
143 : : GLIB_AVAILABLE_IN_2_80
144 : : GDateTime * g_date_time_new_from_unix_utc_usec (gint64 usecs);
145 : :
146 : : G_GNUC_BEGIN_IGNORE_DEPRECATIONS
147 : : GLIB_DEPRECATED_IN_2_62_FOR(g_date_time_new_from_unix_local)
148 : : GDateTime * g_date_time_new_from_timeval_local (const GTimeVal *tv);
149 : : GLIB_DEPRECATED_IN_2_62_FOR(g_date_time_new_from_unix_utc)
150 : : GDateTime * g_date_time_new_from_timeval_utc (const GTimeVal *tv);
151 : : G_GNUC_END_IGNORE_DEPRECATIONS
152 : :
153 : : GLIB_AVAILABLE_IN_2_56
154 : : GDateTime * g_date_time_new_from_iso8601 (const gchar *text,
155 : : GTimeZone *default_tz);
156 : :
157 : : GLIB_AVAILABLE_IN_ALL
158 : : GDateTime * g_date_time_new (GTimeZone *tz,
159 : : gint year,
160 : : gint month,
161 : : gint day,
162 : : gint hour,
163 : : gint minute,
164 : : gdouble seconds);
165 : : GLIB_AVAILABLE_IN_ALL
166 : : GDateTime * g_date_time_new_local (gint year,
167 : : gint month,
168 : : gint day,
169 : : gint hour,
170 : : gint minute,
171 : : gdouble seconds);
172 : : GLIB_AVAILABLE_IN_ALL
173 : : GDateTime * g_date_time_new_utc (gint year,
174 : : gint month,
175 : : gint day,
176 : : gint hour,
177 : : gint minute,
178 : : gdouble seconds);
179 : :
180 : : GLIB_AVAILABLE_IN_ALL
181 : : G_GNUC_WARN_UNUSED_RESULT
182 : : GDateTime * g_date_time_add (GDateTime *datetime,
183 : : GTimeSpan timespan);
184 : :
185 : : GLIB_AVAILABLE_IN_ALL
186 : : G_GNUC_WARN_UNUSED_RESULT
187 : : GDateTime * g_date_time_add_years (GDateTime *datetime,
188 : : gint years);
189 : : GLIB_AVAILABLE_IN_ALL
190 : : G_GNUC_WARN_UNUSED_RESULT
191 : : GDateTime * g_date_time_add_months (GDateTime *datetime,
192 : : gint months);
193 : : GLIB_AVAILABLE_IN_ALL
194 : : G_GNUC_WARN_UNUSED_RESULT
195 : : GDateTime * g_date_time_add_weeks (GDateTime *datetime,
196 : : gint weeks);
197 : : GLIB_AVAILABLE_IN_ALL
198 : : G_GNUC_WARN_UNUSED_RESULT
199 : : GDateTime * g_date_time_add_days (GDateTime *datetime,
200 : : gint days);
201 : :
202 : : GLIB_AVAILABLE_IN_ALL
203 : : G_GNUC_WARN_UNUSED_RESULT
204 : : GDateTime * g_date_time_add_hours (GDateTime *datetime,
205 : : gint hours);
206 : : GLIB_AVAILABLE_IN_ALL
207 : : G_GNUC_WARN_UNUSED_RESULT
208 : : GDateTime * g_date_time_add_minutes (GDateTime *datetime,
209 : : gint minutes);
210 : : GLIB_AVAILABLE_IN_ALL
211 : : G_GNUC_WARN_UNUSED_RESULT
212 : : GDateTime * g_date_time_add_seconds (GDateTime *datetime,
213 : : gdouble seconds);
214 : :
215 : : GLIB_AVAILABLE_IN_ALL
216 : : G_GNUC_WARN_UNUSED_RESULT
217 : : GDateTime * g_date_time_add_full (GDateTime *datetime,
218 : : gint years,
219 : : gint months,
220 : : gint days,
221 : : gint hours,
222 : : gint minutes,
223 : : gdouble seconds);
224 : :
225 : : GLIB_AVAILABLE_IN_ALL
226 : : gint g_date_time_compare (gconstpointer dt1,
227 : : gconstpointer dt2);
228 : : GLIB_AVAILABLE_IN_ALL
229 : : GTimeSpan g_date_time_difference (GDateTime *end,
230 : : GDateTime *begin);
231 : : GLIB_AVAILABLE_IN_ALL
232 : : guint g_date_time_hash (gconstpointer datetime);
233 : : GLIB_AVAILABLE_IN_ALL
234 : : gboolean g_date_time_equal (gconstpointer dt1,
235 : : gconstpointer dt2);
236 : :
237 : : GLIB_AVAILABLE_IN_ALL
238 : : void g_date_time_get_ymd (GDateTime *datetime,
239 : : gint *year,
240 : : gint *month,
241 : : gint *day);
242 : :
243 : : GLIB_AVAILABLE_IN_ALL
244 : : gint g_date_time_get_year (GDateTime *datetime);
245 : : GLIB_AVAILABLE_IN_ALL
246 : : gint g_date_time_get_month (GDateTime *datetime);
247 : : GLIB_AVAILABLE_IN_ALL
248 : : gint g_date_time_get_day_of_month (GDateTime *datetime);
249 : :
250 : : GLIB_AVAILABLE_IN_ALL
251 : : gint g_date_time_get_week_numbering_year (GDateTime *datetime);
252 : : GLIB_AVAILABLE_IN_ALL
253 : : gint g_date_time_get_week_of_year (GDateTime *datetime);
254 : : GLIB_AVAILABLE_IN_ALL
255 : : gint g_date_time_get_day_of_week (GDateTime *datetime);
256 : :
257 : : GLIB_AVAILABLE_IN_ALL
258 : : gint g_date_time_get_day_of_year (GDateTime *datetime);
259 : :
260 : : GLIB_AVAILABLE_IN_ALL
261 : : gint g_date_time_get_hour (GDateTime *datetime);
262 : : GLIB_AVAILABLE_IN_ALL
263 : : gint g_date_time_get_minute (GDateTime *datetime);
264 : : GLIB_AVAILABLE_IN_ALL
265 : : gint g_date_time_get_second (GDateTime *datetime);
266 : : GLIB_AVAILABLE_IN_ALL
267 : : gint g_date_time_get_microsecond (GDateTime *datetime);
268 : : GLIB_AVAILABLE_IN_ALL
269 : : gdouble g_date_time_get_seconds (GDateTime *datetime);
270 : :
271 : : GLIB_AVAILABLE_IN_ALL
272 : : gint64 g_date_time_to_unix (GDateTime *datetime);
273 : : GLIB_AVAILABLE_IN_2_80
274 : : gint64 g_date_time_to_unix_usec (GDateTime *datetime);
275 : :
276 : : G_GNUC_BEGIN_IGNORE_DEPRECATIONS
277 : : GLIB_DEPRECATED_IN_2_62_FOR(g_date_time_to_unix)
278 : : gboolean g_date_time_to_timeval (GDateTime *datetime,
279 : : GTimeVal *tv);
280 : : G_GNUC_END_IGNORE_DEPRECATIONS
281 : :
282 : : GLIB_AVAILABLE_IN_ALL
283 : : GTimeSpan g_date_time_get_utc_offset (GDateTime *datetime);
284 : : GLIB_AVAILABLE_IN_2_58
285 : : GTimeZone * g_date_time_get_timezone (GDateTime *datetime);
286 : : GLIB_AVAILABLE_IN_ALL
287 : : const gchar * g_date_time_get_timezone_abbreviation (GDateTime *datetime);
288 : : GLIB_AVAILABLE_IN_ALL
289 : : gboolean g_date_time_is_daylight_savings (GDateTime *datetime);
290 : :
291 : : GLIB_AVAILABLE_IN_ALL
292 : : GDateTime * g_date_time_to_timezone (GDateTime *datetime,
293 : : GTimeZone *tz);
294 : : GLIB_AVAILABLE_IN_ALL
295 : : GDateTime * g_date_time_to_local (GDateTime *datetime);
296 : : GLIB_AVAILABLE_IN_ALL
297 : : GDateTime * g_date_time_to_utc (GDateTime *datetime);
298 : :
299 : : GLIB_AVAILABLE_IN_ALL
300 : : gchar * g_date_time_format (GDateTime *datetime,
301 : : const gchar *format) G_GNUC_MALLOC;
302 : : GLIB_AVAILABLE_IN_2_62
303 : : gchar * g_date_time_format_iso8601 (GDateTime *datetime) G_GNUC_MALLOC;
304 : :
305 : : /**
306 : : * g_set_date_time: (skip)
307 : : * @date_time_pointer: (inout) (not optional) (nullable): a pointer to either
308 : : * a date-time or `NULL`
309 : : * @new_date_time: (nullable): a date-time to assign to @date_time_pointer
310 : : *
311 : : * Updates a pointer to a date-time to @new_date_time and returns whether
312 : : * @date_time_pointer was changed.
313 : : *
314 : : * If @new_date_time matches the previous date time, this function is a no-op.
315 : : * If @new_date_time is different, its ref-count will be increased and it will
316 : : * be assigned to @date_time_pointer.
317 : : * The previous date time pointed to by @date_time_pointer will have its
318 : : * ref-count decreased.
319 : : *
320 : : * Note two date-time objects that represent the same instant in different
321 : : * timezones are not considered equal.
322 : : *
323 : : * @date_time_pointer must not be `NULL`, but can point to a `NULL` value.
324 : : *
325 : : * Returns: true if the value of @date_time_pointer changed, false otherwise
326 : : *
327 : : * Since: 2.90
328 : : */
329 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_90
330 : : static inline gboolean g_set_date_time (GDateTime **date_time_pointer,
331 : : GDateTime *new_date_time);
332 : :
333 : : GLIB_AVAILABLE_STATIC_INLINE_IN_2_90
334 : : static inline gboolean
335 : 6 : g_set_date_time (GDateTime **date_time_pointer,
336 : : GDateTime *new_date_time)
337 : : {
338 : : GDateTime *old_date_time;
339 : :
340 : 6 : if (*date_time_pointer == new_date_time ||
341 : 5 : (*date_time_pointer != NULL &&
342 : 3 : new_date_time != NULL &&
343 : 4 : g_date_time_compare (*date_time_pointer, new_date_time) == 0 &&
344 : 1 : (g_date_time_get_timezone_abbreviation (*date_time_pointer) ==
345 : 1 : g_date_time_get_timezone_abbreviation (new_date_time))))
346 : : {
347 : 1 : return FALSE;
348 : : }
349 : :
350 : 5 : if (new_date_time != NULL)
351 : : {
352 : 4 : g_date_time_ref (new_date_time);
353 : 0 : }
354 : :
355 : 5 : old_date_time = *date_time_pointer;
356 : 5 : *date_time_pointer = new_date_time;
357 : :
358 : 5 : if (old_date_time != NULL)
359 : : {
360 : 4 : g_date_time_unref (old_date_time);
361 : 0 : }
362 : :
363 : 5 : return TRUE;
364 : 0 : }
365 : :
366 : : G_END_DECLS
367 : :
368 : : #endif /* __G_DATE_TIME_H__ */
|
