1 // Generated by gmmproc 2.64.2 -- DO NOT MODIFY!
2 #ifndef _GLIBMM_DATETIME_H
3 #define _GLIBMM_DATETIME_H
4
5
6 /* Copyright (C) 2011 The glibmm Development Team
7 *
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2.1 of the License, or (at your option) any later version.
12 *
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
20 */
21
22
23 #include <glibmmconfig.h>
24 #include <glibmm/refptr.h>
25 #include <glibmm/timezone.h>
26 #include <glibmm/ustring.h>
27 #include <glibmm/value.h>
28 #include <glib.h>
29
30 #ifndef DOXYGEN_SHOULD_SKIP_THIS
31 typedef struct _GDateTime GDateTime;
32 #endif
33
34 //TODO: When we can change API, make DateTime a _CLASS_BOXEDTYPE.
35
36 namespace Glib
37 {
38
39 struct TimeVal;
40
41 /** A value representing an interval of time, in microseconds. As GTimeSpan,
42 * its underlying type is gint64.
43 */
44 using TimeSpan = GTimeSpan;
45
46 /** DateTime - A structure representing Date and Time.
47 * DateTime is a structure that combines a Gregorian date and time into a
48 * single structure. It provides many conversion and methods to manipulate
49 * dates and times. Time precision is provided down to microseconds and the
50 * time can range (proleptically) from 0001-01-01 00:00:00 to 9999-12-31
51 * 23:59:59.999999. DateTime follows POSIX time in the sense that it is
52 * oblivious to leap seconds.
53 *
54 * DateTime is an immutable object; once it has been created it cannot be
55 * modified further. All modifiers will create a new DateTime. Nearly all such
56 * functions can fail due to the date or time going out of range, in which case
57 * <tt>0</tt> will be returned.
58 *
59 * Many parts of the API may produce non-obvious results. As an example, adding
60 * two months to January 31st will yield March 31st whereas adding one month
61 * and then one month again will yield either March 28th or March 29th. Also
62 * note that adding 24 hours is not always the same as adding one day (since
63 * days containing daylight savings time transitions are either 23 or 25 hours
64 * in length).
65 * @newin{2,30}
66 */
67 class GLIBMM_API DateTime
68 {
69 public:
70 #ifndef DOXYGEN_SHOULD_SKIP_THIS
71 using CppObjectType = DateTime;
72 using BaseObjectType = GDateTime;
73 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
74
75 /** Constructs an invalid object.
76 * E.g. for output arguments to methods. There is not much you can do with
77 * the object before it has been assigned a valid value.
78 */
79 DateTime();
80
81 // Use make_a_copy=true when getting it directly from a struct.
82 explicit DateTime(GDateTime* castitem, bool make_a_copy = false);
83
84 DateTime(const DateTime& src);
85 DateTime& operator=(const DateTime& src);
86
87 DateTime(DateTime&& other) noexcept;
88 DateTime& operator=(DateTime&& other) noexcept;
89
90 ~DateTime() noexcept;
91
92 void swap(DateTime& other) noexcept;
93
gobj()94 GDateTime* gobj() { return gobject_; }
gobj()95 const GDateTime* gobj() const { return gobject_; }
96
97 ///Provides access to the underlying C instance. The caller is responsible for freeing it. Use when directly setting fields in structs.
98 GDateTime* gobj_copy() const;
99
100 protected:
101 GDateTime* gobject_;
102
103 private:
104
105
106 public:
107
108 /** Creates a DateTime corresponding to this exact instant in the given
109 * time zone @a tz. The time is as accurate as the system allows, to a
110 * maximum accuracy of 1 microsecond.
111 *
112 * This function will always succeed unless the system clock is set to
113 * truly insane values (or unless GLib is still being used after the
114 * year 9999).
115 *
116 * You should release the return value by calling g_date_time_unref()
117 * when you are done with it.
118 *
119 * @newin{2,26}
120 *
121 * @param tz A TimeZone.
122 * @return A new DateTime, or <tt>nullptr</tt>.
123 */
124 static DateTime create_now(const TimeZone& tz);
125
126 /** Creates a DateTime corresponding to this exact instant in the local
127 * time zone.
128 *
129 * This is equivalent to calling g_date_time_new_now() with the time
130 * zone returned by g_time_zone_new_local().
131 *
132 * @newin{2,26}
133 *
134 * @return A new DateTime, or <tt>nullptr</tt>.
135 */
136 static DateTime create_now_local();
137
138 /** Creates a DateTime corresponding to this exact instant in UTC.
139 *
140 * This is equivalent to calling g_date_time_new_now() with the time
141 * zone returned by g_time_zone_new_utc().
142 *
143 * @newin{2,26}
144 *
145 * @return A new DateTime, or <tt>nullptr</tt>.
146 */
147 static DateTime create_now_utc();
148
149
150 /** Creates a DateTime corresponding to the given Unix time @a t in the
151 * local time zone.
152 *
153 * Unix time is the number of seconds that have elapsed since 1970-01-01
154 * 00:00:00 UTC, regardless of the local time offset.
155 *
156 * This call can fail (returning <tt>nullptr</tt>) if @a t represents a time outside
157 * of the supported range of DateTime.
158 *
159 * You should release the return value by calling g_date_time_unref()
160 * when you are done with it.
161 *
162 * @newin{2,26}
163 *
164 * @param t The Unix time.
165 * @return A new DateTime, or <tt>nullptr</tt>.
166 */
167 static DateTime create_now_local(gint64 t);
168
169 /** Creates a DateTime corresponding to the given Unix time @a t in UTC.
170 *
171 * Unix time is the number of seconds that have elapsed since 1970-01-01
172 * 00:00:00 UTC.
173 *
174 * This call can fail (returning <tt>nullptr</tt>) if @a t represents a time outside
175 * of the supported range of DateTime.
176 *
177 * You should release the return value by calling g_date_time_unref()
178 * when you are done with it.
179 *
180 * @newin{2,26}
181 *
182 * @param t The Unix time.
183 * @return A new DateTime, or <tt>nullptr</tt>.
184 */
185 static DateTime create_now_utc(gint64 t);
186
187
188 #ifndef GLIBMM_DISABLE_DEPRECATED
189
190 /** Creates a DateTime corresponding to the given TimeVal @a tv in the
191 * local time zone.
192 *
193 * The time contained in a TimeVal is always stored in the form of
194 * seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the
195 * local time offset.
196 *
197 * This call can fail (returning <tt>nullptr</tt>) if @a tv represents a time outside
198 * of the supported range of DateTime.
199 *
200 * You should release the return value by calling g_date_time_unref()
201 * when you are done with it.
202 *
203 * @newin{2,26}
204 * Deprecated: 2.62: TimeVal is not year-2038-safe. Use
205 * g_date_time_new_from_unix_local() instead.
206 *
207 * @deprecated Use create_now_local(gint64 t) instead.
208 *
209 * @param tv A TimeVal.
210 * @return A new DateTime, or <tt>nullptr</tt>.
211 */
212 static DateTime create_now_local(const TimeVal& tv);
213 #endif // GLIBMM_DISABLE_DEPRECATED
214
215
216 #ifndef GLIBMM_DISABLE_DEPRECATED
217
218 /** Creates a DateTime corresponding to the given TimeVal @a tv in UTC.
219 *
220 * The time contained in a TimeVal is always stored in the form of
221 * seconds elapsed since 1970-01-01 00:00:00 UTC.
222 *
223 * This call can fail (returning <tt>nullptr</tt>) if @a tv represents a time outside
224 * of the supported range of DateTime.
225 *
226 * You should release the return value by calling g_date_time_unref()
227 * when you are done with it.
228 *
229 * @newin{2,26}
230 * Deprecated: 2.62: TimeVal is not year-2038-safe. Use
231 * g_date_time_new_from_unix_utc() instead.
232 *
233 * @deprecated Use create_now_utc(gint64 t) instead.
234 *
235 * @param tv A TimeVal.
236 * @return A new DateTime, or <tt>nullptr</tt>.
237 */
238 static DateTime create_now_utc(const TimeVal& tv);
239 #endif // GLIBMM_DISABLE_DEPRECATED
240
241
242 /** Creates a DateTime corresponding to the given
243 * [ISO 8601 formatted string](https://en.wikipedia.org/wiki/ISO_8601)
244 * @a text. ISO 8601 strings of the form <date><sep><time><tz> are supported, with
245 * some extensions from [RFC 3339](https://tools.ietf.org/html/rfc3339) as
246 * mentioned below.
247 *
248 * Note that as DateTime "is oblivious to leap seconds", leap seconds information
249 * in an ISO-8601 string will be ignored, so a `23:59:60` time would be parsed as
250 * `23:59:59`.
251 *
252 * <sep> is the separator and can be either 'T', 't' or ' '. The latter two
253 * separators are an extension from
254 * [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6).
255 *
256 * <date> is in the form:
257 *
258 * - `YYYY-MM-DD` - Year/month/day, e.g. 2016-08-24.
259 * - `YYYYMMDD` - Same as above without dividers.
260 * - `YYYY-DDD` - Ordinal day where DDD is from 001 to 366, e.g. 2016-237.
261 * - `YYYYDDD` - Same as above without dividers.
262 * - `YYYY-Www-D` - Week day where ww is from 01 to 52 and D from 1-7,
263 * e.g. 2016-W34-3.
264 * - `YYYYWwwD` - Same as above without dividers.
265 *
266 * <time> is in the form:
267 *
268 * - `hh:mm:ss(.sss)` - Hours, minutes, seconds (subseconds), e.g. 22:10:42.123.
269 * - `hhmmss(.sss)` - Same as above without dividers.
270 *
271 * <tz> is an optional timezone suffix of the form:
272 *
273 * - `Z` - UTC.
274 * - `+hh:mm` or `-hh:mm` - Offset from UTC in hours and minutes, e.g. +12:00.
275 * - `+hh` or `-hh` - Offset from UTC in hours, e.g. +12.
276 *
277 * If the timezone is not provided in @a text it must be provided in @a default_tz
278 * (this field is otherwise ignored).
279 *
280 * This call can fail (returning <tt>nullptr</tt>) if @a text is not a valid ISO 8601
281 * formatted string.
282 *
283 * You should release the return value by calling g_date_time_unref()
284 * when you are done with it.
285 *
286 * @newin{2,62}
287 *
288 * @param text An ISO 8601 formatted time string.
289 * @param default_tz A TimeZone to use if the text doesn't contain a
290 * timezone, or <tt>nullptr</tt>.
291 * @return A new DateTime, or <tt>nullptr</tt>.
292 */
293 static DateTime create_from_iso8601(const Glib::ustring& text, const TimeZone& default_tz);
294
295 /// A create_from_iso8601() convenience overload.
296 static DateTime create_from_iso8601(const Glib::ustring& text);
297
298 /** Creates a new DateTime corresponding to the given date and time in
299 * the time zone @a tz.
300 *
301 * The @a year must be between 1 and 9999, @a month between 1 and 12 and @a day
302 * between 1 and 28, 29, 30 or 31 depending on the month and the year.
303 *
304 * @a hour must be between 0 and 23 and @a minute must be between 0 and 59.
305 *
306 * @a seconds must be at least 0.0 and must be strictly less than 60.0.
307 * It will be rounded down to the nearest microsecond.
308 *
309 * If the given time is not representable in the given time zone (for
310 * example, 02:30 on March 14th 2010 in Toronto, due to daylight savings
311 * time) then the time will be rounded up to the nearest existing time
312 * (in this case, 03:00). If this matters to you then you should verify
313 * the return value for containing the same as the numbers you gave.
314 *
315 * In the case that the given time is ambiguous in the given time zone
316 * (for example, 01:30 on November 7th 2010 in Toronto, due to daylight
317 * savings time) then the time falling within standard (ie:
318 * non-daylight) time is taken.
319 *
320 * It not considered a programmer error for the values to this function
321 * to be out of range, but in the case that they are, the function will
322 * return <tt>nullptr</tt>.
323 *
324 * You should release the return value by calling g_date_time_unref()
325 * when you are done with it.
326 *
327 * @newin{2,26}
328 *
329 * @param tz A TimeZone.
330 * @param year The year component of the date.
331 * @param month The month component of the date.
332 * @param day The day component of the date.
333 * @param hour The hour component of the date.
334 * @param minute The minute component of the date.
335 * @param seconds The number of seconds past the minute.
336 * @return A new DateTime, or <tt>nullptr</tt>.
337 */
338 static DateTime create(const TimeZone& tz, int year, int month, int day, int hour, int minute, double seconds);
339
340 /** Creates a new DateTime corresponding to the given date and time in
341 * the local time zone.
342 *
343 * This call is equivalent to calling g_date_time_new() with the time
344 * zone returned by g_time_zone_new_local().
345 *
346 * @newin{2,26}
347 *
348 * @param year The year component of the date.
349 * @param month The month component of the date.
350 * @param day The day component of the date.
351 * @param hour The hour component of the date.
352 * @param minute The minute component of the date.
353 * @param seconds The number of seconds past the minute.
354 * @return A DateTime, or <tt>nullptr</tt>.
355 */
356 static DateTime create_local(int year, int month, int day, int hour, int minute, double seconds);
357
358 /** Creates a new DateTime corresponding to the given date and time in
359 * UTC.
360 *
361 * This call is equivalent to calling g_date_time_new() with the time
362 * zone returned by g_time_zone_new_utc().
363 *
364 * @newin{2,26}
365 *
366 * @param year The year component of the date.
367 * @param month The month component of the date.
368 * @param day The day component of the date.
369 * @param hour The hour component of the date.
370 * @param minute The minute component of the date.
371 * @param seconds The number of seconds past the minute.
372 * @return A DateTime, or <tt>nullptr</tt>.
373 */
374 static DateTime create_utc(int year, int month, int day, int hour, int minute, double seconds);
375
376 /** Returns true if the %DateTime object is valid.
377 * This will return false, for instance, if the @a text in create_from_iso8601()
378 * is not a valid ISO 8601 formatted string.
379 *
380 * @newin{2,62}
381 */
382 explicit operator bool() const;
383
384
385 /** Creates a copy of @a datetime and adds the specified timespan to the copy.
386 *
387 * @newin{2,26}
388 *
389 * @param timespan A TimeSpan.
390 * @return The newly created DateTime which should be freed with
391 * g_date_time_unref().
392 */
393 DateTime add(TimeSpan timespan) const;
394
395 /** Creates a copy of @a datetime and adds the specified number of years to the
396 * copy. Add negative values to subtract years.
397 *
398 * As with g_date_time_add_months(), if the resulting date would be 29th
399 * February on a non-leap year, the day will be clamped to 28th February.
400 *
401 * @newin{2,26}
402 *
403 * @param years The number of years.
404 * @return The newly created DateTime which should be freed with
405 * g_date_time_unref().
406 */
407 DateTime add_years(int years) const;
408
409 /** Creates a copy of @a datetime and adds the specified number of months to the
410 * copy. Add negative values to subtract months.
411 *
412 * The day of the month of the resulting DateTime is clamped to the number
413 * of days in the updated calendar month. For example, if adding 1 month to
414 * 31st January 2018, the result would be 28th February 2018. In 2020 (a leap
415 * year), the result would be 29th February.
416 *
417 * @newin{2,26}
418 *
419 * @param months The number of months.
420 * @return The newly created DateTime which should be freed with
421 * g_date_time_unref().
422 */
423 DateTime add_months(int months) const;
424
425 /** Creates a copy of @a datetime and adds the specified number of weeks to the
426 * copy. Add negative values to subtract weeks.
427 *
428 * @newin{2,26}
429 *
430 * @param weeks The number of weeks.
431 * @return The newly created DateTime which should be freed with
432 * g_date_time_unref().
433 */
434 DateTime add_weeks(int weeks) const;
435
436 /** Creates a copy of @a datetime and adds the specified number of days to the
437 * copy. Add negative values to subtract days.
438 *
439 * @newin{2,26}
440 *
441 * @param days The number of days.
442 * @return The newly created DateTime which should be freed with
443 * g_date_time_unref().
444 */
445 DateTime add_days(int days) const;
446
447 /** Creates a copy of @a datetime and adds the specified number of hours.
448 * Add negative values to subtract hours.
449 *
450 * @newin{2,26}
451 *
452 * @param hours The number of hours to add.
453 * @return The newly created DateTime which should be freed with
454 * g_date_time_unref().
455 */
456 DateTime add_hours(int hours) const;
457
458 /** Creates a copy of @a datetime adding the specified number of minutes.
459 * Add negative values to subtract minutes.
460 *
461 * @newin{2,26}
462 *
463 * @param minutes The number of minutes to add.
464 * @return The newly created DateTime which should be freed with
465 * g_date_time_unref().
466 */
467 DateTime add_minutes(int minutes) const;
468
469 /** Creates a copy of @a datetime and adds the specified number of seconds.
470 * Add negative values to subtract seconds.
471 *
472 * @newin{2,26}
473 *
474 * @param seconds The number of seconds to add.
475 * @return The newly created DateTime which should be freed with
476 * g_date_time_unref().
477 */
478 DateTime add_seconds(double seconds) const;
479
480 /** Creates a new DateTime adding the specified values to the current date and
481 * time in @a datetime. Add negative values to subtract.
482 *
483 * @newin{2,26}
484 *
485 * @param years The number of years to add.
486 * @param months The number of months to add.
487 * @param days The number of days to add.
488 * @param hours The number of hours to add.
489 * @param minutes The number of minutes to add.
490 * @param seconds The number of seconds to add.
491 * @return The newly created DateTime that should be freed with
492 * g_date_time_unref().
493 */
494 DateTime add_full(int years, int months, int days, int hours, int minutes, double seconds) const;
495
496
497 /** Calculates the difference in time between @a *this and @a other. The
498 * TimeSpan that is returned is effectively @a *this - @a other.
499 *
500 * @newin{2,26}
501 *
502 * @param other The other DateTime.
503 * @return The difference between the two DateTime, as a time
504 * span expressed in microseconds.
505 */
506 TimeSpan difference(const DateTime& other) const;
507
508
509 /** A comparison function for DateTimes that is suitable
510 * as a CompareFunc.
511 *
512 * @newin{2,26}
513 *
514 * @param other The DateTime to compare with.
515 * @return -1, 0 or 1 if @a *this is less than, equal to or greater
516 * than @a other.
517 */
518 int compare(const DateTime& other) const;
519
520
521 /** Hashes @a datetime into a <tt>unsigned int</tt>, suitable for use within HashTable.
522 *
523 * @newin{2,26}
524 *
525 * @return A <tt>unsigned int</tt> containing the hash.
526 */
527 guint hash() const;
528
529
530 /** Checks to see if @a *this and @a other are equal.
531 *
532 * Equal here means that they represent the same moment after converting
533 * them to the same time zone.
534 *
535 * @newin{2,26}
536 *
537 * @param other The DateTime to compare with.
538 * @return <tt>true</tt> if @a *this and @a other are equal.
539 */
540 bool equal(const DateTime& other) const;
541
542
543 /** Retrieves the Gregorian day, month, and year of a given DateTime.
544 *
545 * @newin{2,26}
546 *
547 * @param year The return location for the gregorian year, or <tt>nullptr</tt>.
548 * @param month The return location for the month of the year, or <tt>nullptr</tt>.
549 * @param day The return location for the day of the month, or <tt>nullptr</tt>.
550 */
551 void get_ymd(int& year, int& month, int& day) const;
552
553 /** Retrieves the year represented by @a datetime in the Gregorian calendar.
554 *
555 * @newin{2,26}
556 *
557 * @return The year represented by @a datetime.
558 */
559 int get_year() const;
560
561 /** Retrieves the month of the year represented by @a datetime in the Gregorian
562 * calendar.
563 *
564 * @newin{2,26}
565 *
566 * @return The month represented by @a datetime.
567 */
568 int get_month() const;
569
570 /** Retrieves the day of the month represented by @a datetime in the gregorian
571 * calendar.
572 *
573 * @newin{2,26}
574 *
575 * @return The day of the month.
576 */
577 int get_day_of_month() const;
578
579 /** Returns the ISO 8601 week-numbering year in which the week containing
580 * @a datetime falls.
581 *
582 * This function, taken together with g_date_time_get_week_of_year() and
583 * g_date_time_get_day_of_week() can be used to determine the full ISO
584 * week date on which @a datetime falls.
585 *
586 * This is usually equal to the normal Gregorian year (as returned by
587 * g_date_time_get_year()), except as detailed below:
588 *
589 * For Thursday, the week-numbering year is always equal to the usual
590 * calendar year. For other days, the number is such that every day
591 * within a complete week (Monday to Sunday) is contained within the
592 * same week-numbering year.
593 *
594 * For Monday, Tuesday and Wednesday occurring near the end of the year,
595 * this may mean that the week-numbering year is one greater than the
596 * calendar year (so that these days have the same week-numbering year
597 * as the Thursday occurring early in the next year).
598 *
599 * For Friday, Saturday and Sunday occurring near the start of the year,
600 * this may mean that the week-numbering year is one less than the
601 * calendar year (so that these days have the same week-numbering year
602 * as the Thursday occurring late in the previous year).
603 *
604 * An equivalent description is that the week-numbering year is equal to
605 * the calendar year containing the majority of the days in the current
606 * week (Monday to Sunday).
607 *
608 * Note that January 1 0001 in the proleptic Gregorian calendar is a
609 * Monday, so this function never returns 0.
610 *
611 * @newin{2,26}
612 *
613 * @return The ISO 8601 week-numbering year for @a datetime.
614 */
615 int get_week_numbering_year() const;
616
617 /** Returns the ISO 8601 week number for the week containing @a datetime.
618 * The ISO 8601 week number is the same for every day of the week (from
619 * Moday through Sunday). That can produce some unusual results
620 * (described below).
621 *
622 * The first week of the year is week 1. This is the week that contains
623 * the first Thursday of the year. Equivalently, this is the first week
624 * that has more than 4 of its days falling within the calendar year.
625 *
626 * The value 0 is never returned by this function. Days contained
627 * within a year but occurring before the first ISO 8601 week of that
628 * year are considered as being contained in the last week of the
629 * previous year. Similarly, the final days of a calendar year may be
630 * considered as being part of the first ISO 8601 week of the next year
631 * if 4 or more days of that week are contained within the new year.
632 *
633 * @newin{2,26}
634 *
635 * @return The ISO 8601 week number for @a datetime.
636 */
637 int get_week_of_year() const;
638
639 /** Retrieves the ISO 8601 day of the week on which @a datetime falls (1 is
640 * Monday, 2 is Tuesday... 7 is Sunday).
641 *
642 * @newin{2,26}
643 *
644 * @return The day of the week.
645 */
646 int get_day_of_week() const;
647
648 /** Retrieves the day of the year represented by @a datetime in the Gregorian
649 * calendar.
650 *
651 * @newin{2,26}
652 *
653 * @return The day of the year.
654 */
655 int get_day_of_year() const;
656
657 /** Retrieves the hour of the day represented by @a datetime
658 *
659 * @newin{2,26}
660 *
661 * @return The hour of the day.
662 */
663 int get_hour() const;
664
665 /** Retrieves the minute of the hour represented by @a datetime
666 *
667 * @newin{2,26}
668 *
669 * @return The minute of the hour.
670 */
671 int get_minute() const;
672
673 /** Retrieves the second of the minute represented by @a datetime
674 *
675 * @newin{2,26}
676 *
677 * @return The second represented by @a datetime.
678 */
679 int get_second() const;
680
681 /** Retrieves the microsecond of the date represented by @a datetime
682 *
683 * @newin{2,26}
684 *
685 * @return The microsecond of the second.
686 */
687 int get_microsecond() const;
688
689 /** Retrieves the number of seconds since the start of the last minute,
690 * including the fractional part.
691 *
692 * @newin{2,26}
693 *
694 * @return The number of seconds.
695 */
696 double get_seconds() const;
697
698 /** Gives the Unix time corresponding to @a datetime, rounding down to the
699 * nearest second.
700 *
701 * Unix time is the number of seconds that have elapsed since 1970-01-01
702 * 00:00:00 UTC, regardless of the time zone associated with @a datetime.
703 *
704 * @newin{2,26}
705 *
706 * @return The Unix time corresponding to @a datetime.
707 */
708 gint64 to_unix() const;
709
710
711 #ifndef GLIBMM_DISABLE_DEPRECATED
712
713 /** Stores the instant in time that @a datetime represents into @a tv.
714 *
715 * The time contained in a TimeVal is always stored in the form of
716 * seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the time
717 * zone associated with @a datetime.
718 *
719 * On systems where 'long' is 32bit (ie: all 32bit systems and all
720 * Windows systems), a TimeVal is incapable of storing the entire
721 * range of values that DateTime is capable of expressing. On those
722 * systems, this function returns <tt>false</tt> to indicate that the time is
723 * out of range.
724 *
725 * On systems where 'long' is 64bit, this function never fails.
726 *
727 * @newin{2,26}
728 * Deprecated: 2.62: TimeVal is not year-2038-safe. Use
729 * g_date_time_to_unix() instead.
730 *
731 * @deprecated Use to_unix() instead.
732 *
733 * @param tv A TimeVal to modify.
734 * @return <tt>true</tt> if successful, else <tt>false</tt>.
735 */
736 bool to_timeval(TimeVal& tv) const;
737 #endif // GLIBMM_DISABLE_DEPRECATED
738
739
740 /** Determines the offset to UTC in effect at the time and in the time
741 * zone of @a datetime.
742 *
743 * The offset is the number of microseconds that you add to UTC time to
744 * arrive at local time for the time zone (ie: negative numbers for time
745 * zones west of GMT, positive numbers for east).
746 *
747 * If @a datetime represents UTC time, then the offset is always zero.
748 *
749 * @newin{2,26}
750 *
751 * @return The number of microseconds that should be added to UTC to
752 * get the local time.
753 */
754 TimeSpan get_utc_offset() const;
755
756
757 /** Get the time zone for this @a datetime.
758 *
759 * @newin{2,60}
760 *
761 * @return The time zone.
762 */
763 TimeZone get_timezone() const;
764
765 /** Determines the time zone abbreviation to be used at the time and in
766 * the time zone of @a datetime.
767 *
768 * For example, in Toronto this is currently "EST" during the winter
769 * months and "EDT" during the summer months when daylight savings
770 * time is in effect.
771 *
772 * @newin{2,26}
773 *
774 * @return The time zone abbreviation. The returned
775 * string is owned by the DateTime and it should not be
776 * modified or freed.
777 */
778 Glib::ustring get_timezone_abbreviation() const;
779
780 /** Determines if daylight savings time is in effect at the time and in
781 * the time zone of @a datetime.
782 *
783 * @newin{2,26}
784 *
785 * @return <tt>true</tt> if daylight savings time is in effect.
786 */
787 bool is_daylight_savings() const;
788
789 /** Create a new DateTime corresponding to the same instant in time as
790 * @a datetime, but in the time zone @a tz.
791 *
792 * This call can fail in the case that the time goes out of bounds. For
793 * example, converting 0001-01-01 00:00:00 UTC to a time zone west of
794 * Greenwich will fail (due to the year 0 being out of range).
795 *
796 * You should release the return value by calling g_date_time_unref()
797 * when you are done with it.
798 *
799 * @newin{2,26}
800 *
801 * @param tz The new TimeZone.
802 * @return A new DateTime, or <tt>nullptr</tt>.
803 */
804 DateTime to_timezone(const TimeZone& tz) const;
805
806 /** Creates a new DateTime corresponding to the same instant in time as
807 * @a datetime, but in the local time zone.
808 *
809 * This call is equivalent to calling g_date_time_to_timezone() with the
810 * time zone returned by g_time_zone_new_local().
811 *
812 * @newin{2,26}
813 *
814 * @return The newly created DateTime.
815 */
816 DateTime to_local() const;
817
818 /** Creates a new DateTime corresponding to the same instant in time as
819 * @a datetime, but in UTC.
820 *
821 * This call is equivalent to calling g_date_time_to_timezone() with the
822 * time zone returned by g_time_zone_new_utc().
823 *
824 * @newin{2,26}
825 *
826 * @return The newly created DateTime.
827 */
828 DateTime to_utc() const;
829
830 /** Creates a newly allocated string representing the requested @a format_str.
831 *
832 * The format strings understood by this function are a subset of the
833 * strftime() format language as specified by C99. The \\%D, \\%U and \\%W
834 * conversions are not supported, nor is the 'E' modifier. The GNU
835 * extensions \\%k, \\%l, \\%s and \\%P are supported, however, as are the
836 * '0', '_' and '-' modifiers.
837 *
838 * In contrast to strftime(), this function always produces a UTF-8
839 * string, regardless of the current locale. Note that the rendering of
840 * many formats is locale-dependent and may not match the strftime()
841 * output exactly.
842 *
843 * The following format specifiers are supported:
844 *
845 * - \\%a: the abbreviated weekday name according to the current locale
846 * - \\%A: the full weekday name according to the current locale
847 * - \\%b: the abbreviated month name according to the current locale
848 * - \\%B: the full month name according to the current locale
849 * - \\%c: the preferred date and time representation for the current locale
850 * - \\%C: the century number (year/100) as a 2-digit integer (00-99)
851 * - \\%d: the day of the month as a decimal number (range 01 to 31)
852 * - \\%e: the day of the month as a decimal number (range 1 to 31)
853 * - \\%F: equivalent to `%Y-%m-%d` (the ISO 8601 date format)
854 * - \\%g: the last two digits of the ISO 8601 week-based year as a
855 * decimal number (00-99). This works well with \\%V and \\%u.
856 * - \\%G: the ISO 8601 week-based year as a decimal number. This works
857 * well with \\%V and \\%u.
858 * - \\%h: equivalent to \\%b
859 * - \\%H: the hour as a decimal number using a 24-hour clock (range 00 to 23)
860 * - \\%I: the hour as a decimal number using a 12-hour clock (range 01 to 12)
861 * - \\%j: the day of the year as a decimal number (range 001 to 366)
862 * - \\%k: the hour (24-hour clock) as a decimal number (range 0 to 23);
863 * single digits are preceded by a blank
864 * - \\%l: the hour (12-hour clock) as a decimal number (range 1 to 12);
865 * single digits are preceded by a blank
866 * - \\%m: the month as a decimal number (range 01 to 12)
867 * - \\%M: the minute as a decimal number (range 00 to 59)
868 * - \\%p: either "AM" or "PM" according to the given time value, or the
869 * corresponding strings for the current locale. Noon is treated as
870 * "PM" and midnight as "AM".
871 * - \\%P: like \\%p but lowercase: "am" or "pm" or a corresponding string for
872 * the current locale
873 * - \\%r: the time in a.m. or p.m. notation
874 * - \\%R: the time in 24-hour notation (\\%H:\\%M)
875 * - \\%s: the number of seconds since the Epoch, that is, since 1970-01-01
876 * 00:00:00 UTC
877 * - \\%S: the second as a decimal number (range 00 to 60)
878 * - \\%t: a tab character
879 * - \\%T: the time in 24-hour notation with seconds (\\%H:\\%M:\\%S)
880 * - \\%u: the ISO 8601 standard day of the week as a decimal, range 1 to 7,
881 * Monday being 1. This works well with \\%G and \\%V.
882 * - \\%V: the ISO 8601 standard week number of the current year as a decimal
883 * number, range 01 to 53, where week 1 is the first week that has at
884 * least 4 days in the new year. See g_date_time_get_week_of_year().
885 * This works well with \\%G and \\%u.
886 * - \\%w: the day of the week as a decimal, range 0 to 6, Sunday being 0.
887 * This is not the ISO 8601 standard format -- use \\%u instead.
888 * - \\%x: the preferred date representation for the current locale without
889 * the time
890 * - \\%X: the preferred time representation for the current locale without
891 * the date
892 * - \\%y: the year as a decimal number without the century
893 * - \\%Y: the year as a decimal number including the century
894 * - \\%z: the time zone as an offset from UTC (+hhmm)
895 * - \\%:z: the time zone as an offset from UTC (+hh:mm).
896 * This is a gnulib strftime() extension. Since: 2.38
897 * - \\%::z: the time zone as an offset from UTC (+hh:mm:ss). This is a
898 * gnulib strftime() extension. Since: 2.38
899 * - \\%:::z: the time zone as an offset from UTC, with : to necessary
900 * precision (e.g., -04, +05:30). This is a gnulib strftime() extension. Since: 2.38
901 * - \\%Z: the time zone or name or abbreviation
902 * - \\%\\%: a literal \\% character
903 *
904 * Some conversion specifications can be modified by preceding the
905 * conversion specifier by one or more modifier characters. The
906 * following modifiers are supported for many of the numeric
907 * conversions:
908 *
909 * - O: Use alternative numeric symbols, if the current locale supports those.
910 * - _: Pad a numeric result with spaces. This overrides the default padding
911 * for the specifier.
912 * - -: Do not pad a numeric result. This overrides the default padding
913 * for the specifier.
914 * - 0: Pad a numeric result with zeros. This overrides the default padding
915 * for the specifier.
916 *
917 * Additionally, when O is used with B, b, or h, it produces the alternative
918 * form of a month name. The alternative form should be used when the month
919 * name is used without a day number (e.g., standalone). It is required in
920 * some languages (Baltic, Slavic, Greek, and more) due to their grammatical
921 * rules. For other languages there is no difference. \\%OB is a GNU and BSD
922 * strftime() extension expected to be added to the future POSIX specification,
923 * \\%Ob and \\%Oh are GNU strftime() extensions. @newin{2,56}
924 *
925 * @newin{2,26}
926 *
927 * @param format_str A valid UTF-8 string, containing the format for the
928 * DateTime.
929 * @return A newly allocated string formatted to the requested format
930 * or <tt>nullptr</tt> in the case that there was an error (such as a format specifier
931 * not being supported in the current locale).
932 */
933 Glib::ustring format(const Glib::ustring& format_str) const;
934
935 /** Format @a datetime in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601),
936 * including the date, time and time zone, and return that as a UTF-8 encoded
937 * string.
938 *
939 * @newin{2,62}
940 *
941 * @return A newly allocated string formatted in ISO 8601 format
942 * or <tt>nullptr</tt> in the case that there was an error.
943 */
944 Glib::ustring format_iso8601() const;
945
946
947 };
948
949 #ifndef DOXYGEN_SHOULD_SKIP_THIS
950 // This is needed so Glib::DateTime can be used with Glib::Value and _WRAP_PROPERTY.
951 template <>
952 class GLIBMM_API Value<Glib::DateTime> : public ValueBase_Boxed
953 {
954 public:
955 using CppType = Glib::DateTime;
956 using CType = GDateTime*;
957
958 static GType value_type();
959
960 void set(const CppType& data);
961 CppType get() const;
962 };
963 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
964
965 } // namespace Glib
966
967
968 namespace Glib
969 {
970
971 /** @relates Glib::DateTime
972 * @param lhs The left-hand side
973 * @param rhs The right-hand side
974 */
swap(DateTime & lhs,DateTime & rhs)975 inline void swap(DateTime& lhs, DateTime& rhs) noexcept
976 { lhs.swap(rhs); }
977
978 } // namespace Glib
979
980 namespace Glib
981 {
982
983 /** A Glib::wrap() method for this object.
984 *
985 * @param object The C instance.
986 * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
987 * @result A C++ instance that wraps this C instance.
988 *
989 * @relates Glib::DateTime
990 */
991 GLIBMM_API
992 Glib::DateTime wrap(GDateTime* object, bool take_copy = false);
993
994 } // namespace Glib
995
996
997 #endif /* _GLIBMM_DATETIME_H */
998
999