glib/auto/date_time.rs
1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{ffi, translate::*, BoolError, TimeSpan, TimeZone};
6
7crate::wrapper! {
8 /// `GDateTime` is a structure that combines a Gregorian date and time
9 /// into a single structure.
10 ///
11 /// `GDateTime` provides many conversion and methods to manipulate dates and times.
12 /// Time precision is provided down to microseconds and the time can range
13 /// (proleptically) from 0001-01-01 00:00:00 to 9999-12-31 23:59:59.999999.
14 /// `GDateTime` follows POSIX time in the sense that it is oblivious to leap
15 /// seconds.
16 ///
17 /// `GDateTime` is an immutable object; once it has been created it cannot
18 /// be modified further. All modifiers will create a new `GDateTime`.
19 /// Nearly all such functions can fail due to the date or time going out
20 /// of range, in which case [`None`] will be returned.
21 ///
22 /// `GDateTime` is reference counted: the reference count is increased by calling
23 /// `GLib::DateTime::ref()` and decreased by calling `GLib::DateTime::unref()`.
24 /// When the reference count drops to 0, the resources allocated by the `GDateTime`
25 /// structure are released.
26 ///
27 /// Many parts of the API may produce non-obvious results. As an
28 /// example, adding two months to January 31st will yield March 31st
29 /// whereas adding one month and then one month again will yield either
30 /// March 28th or March 29th. Also note that adding 24 hours is not
31 /// always the same as adding one day (since days containing daylight
32 /// savings time transitions are either 23 or 25 hours in length).
33 // rustdoc-stripper-ignore-next-stop
34 /// `GDateTime` is a structure that combines a Gregorian date and time
35 /// into a single structure.
36 ///
37 /// `GDateTime` provides many conversion and methods to manipulate dates and times.
38 /// Time precision is provided down to microseconds and the time can range
39 /// (proleptically) from 0001-01-01 00:00:00 to 9999-12-31 23:59:59.999999.
40 /// `GDateTime` follows POSIX time in the sense that it is oblivious to leap
41 /// seconds.
42 ///
43 /// `GDateTime` is an immutable object; once it has been created it cannot
44 /// be modified further. All modifiers will create a new `GDateTime`.
45 /// Nearly all such functions can fail due to the date or time going out
46 /// of range, in which case [`None`] will be returned.
47 ///
48 /// `GDateTime` is reference counted: the reference count is increased by calling
49 /// `GLib::DateTime::ref()` and decreased by calling `GLib::DateTime::unref()`.
50 /// When the reference count drops to 0, the resources allocated by the `GDateTime`
51 /// structure are released.
52 ///
53 /// Many parts of the API may produce non-obvious results. As an
54 /// example, adding two months to January 31st will yield March 31st
55 /// whereas adding one month and then one month again will yield either
56 /// March 28th or March 29th. Also note that adding 24 hours is not
57 /// always the same as adding one day (since days containing daylight
58 /// savings time transitions are either 23 or 25 hours in length).
59 #[derive(Debug)]
60 pub struct DateTime(Shared<ffi::GDateTime>);
61
62 match fn {
63 ref => |ptr| ffi::g_date_time_ref(ptr),
64 unref => |ptr| ffi::g_date_time_unref(ptr),
65 type_ => || ffi::g_date_time_get_type(),
66 }
67}
68
69impl DateTime {
70 /// Creates a new #GDateTime corresponding to the given date and time in
71 /// the time zone @tz.
72 ///
73 /// The @year must be between 1 and 9999, @month between 1 and 12 and @day
74 /// between 1 and 28, 29, 30 or 31 depending on the month and the year.
75 ///
76 /// @hour must be between 0 and 23 and @minute must be between 0 and 59.
77 ///
78 /// @seconds must be at least 0.0 and must be strictly less than 60.0.
79 /// It will be rounded down to the nearest microsecond.
80 ///
81 /// If the given time is not representable in the given time zone (for
82 /// example, 02:30 on March 14th 2010 in Toronto, due to daylight savings
83 /// time) then the time will be rounded up to the nearest existing time
84 /// (in this case, 03:00). If this matters to you then you should verify
85 /// the return value for containing the same as the numbers you gave.
86 ///
87 /// In the case that the given time is ambiguous in the given time zone
88 /// (for example, 01:30 on November 7th 2010 in Toronto, due to daylight
89 /// savings time) then the time falling within standard (ie:
90 /// non-daylight) time is taken.
91 ///
92 /// It not considered a programmer error for the values to this function
93 /// to be out of range, but in the case that they are, the function will
94 /// return [`None`].
95 ///
96 /// You should release the return value by calling g_date_time_unref()
97 /// when you are done with it.
98 /// ## `tz`
99 /// a #GTimeZone
100 /// ## `year`
101 /// the year component of the date
102 /// ## `month`
103 /// the month component of the date
104 /// ## `day`
105 /// the day component of the date
106 /// ## `hour`
107 /// the hour component of the date
108 /// ## `minute`
109 /// the minute component of the date
110 /// ## `seconds`
111 /// the number of seconds past the minute
112 ///
113 /// # Returns
114 ///
115 /// a new #GDateTime, or [`None`]
116 // rustdoc-stripper-ignore-next-stop
117 /// Creates a new #GDateTime corresponding to the given date and time in
118 /// the time zone @tz.
119 ///
120 /// The @year must be between 1 and 9999, @month between 1 and 12 and @day
121 /// between 1 and 28, 29, 30 or 31 depending on the month and the year.
122 ///
123 /// @hour must be between 0 and 23 and @minute must be between 0 and 59.
124 ///
125 /// @seconds must be at least 0.0 and must be strictly less than 60.0.
126 /// It will be rounded down to the nearest microsecond.
127 ///
128 /// If the given time is not representable in the given time zone (for
129 /// example, 02:30 on March 14th 2010 in Toronto, due to daylight savings
130 /// time) then the time will be rounded up to the nearest existing time
131 /// (in this case, 03:00). If this matters to you then you should verify
132 /// the return value for containing the same as the numbers you gave.
133 ///
134 /// In the case that the given time is ambiguous in the given time zone
135 /// (for example, 01:30 on November 7th 2010 in Toronto, due to daylight
136 /// savings time) then the time falling within standard (ie:
137 /// non-daylight) time is taken.
138 ///
139 /// It not considered a programmer error for the values to this function
140 /// to be out of range, but in the case that they are, the function will
141 /// return [`None`].
142 ///
143 /// You should release the return value by calling g_date_time_unref()
144 /// when you are done with it.
145 /// ## `tz`
146 /// a #GTimeZone
147 /// ## `year`
148 /// the year component of the date
149 /// ## `month`
150 /// the month component of the date
151 /// ## `day`
152 /// the day component of the date
153 /// ## `hour`
154 /// the hour component of the date
155 /// ## `minute`
156 /// the minute component of the date
157 /// ## `seconds`
158 /// the number of seconds past the minute
159 ///
160 /// # Returns
161 ///
162 /// a new #GDateTime, or [`None`]
163 #[doc(alias = "g_date_time_new")]
164 pub fn new(
165 tz: &TimeZone,
166 year: i32,
167 month: i32,
168 day: i32,
169 hour: i32,
170 minute: i32,
171 seconds: f64,
172 ) -> Result<DateTime, BoolError> {
173 unsafe {
174 Option::<_>::from_glib_full(ffi::g_date_time_new(
175 tz.to_glib_none().0,
176 year,
177 month,
178 day,
179 hour,
180 minute,
181 seconds,
182 ))
183 .ok_or_else(|| crate::bool_error!("Invalid date"))
184 }
185 }
186
187 /// Creates a #GDateTime corresponding to the given
188 /// [ISO 8601 formatted string](https://en.wikipedia.org/wiki/ISO_8601)
189 /// @text. ISO 8601 strings of the form `<date><sep><time><tz>` are supported, with
190 /// some extensions from [RFC 3339](https://tools.ietf.org/html/rfc3339) as
191 /// mentioned below.
192 ///
193 /// Note that as #GDateTime "is oblivious to leap seconds", leap seconds information
194 /// in an ISO-8601 string will be ignored, so a `23:59:60` time would be parsed as
195 /// `23:59:59`.
196 ///
197 /// `<sep>` is the separator and can be either 'T', 't' or ' '. The latter two
198 /// separators are an extension from
199 /// [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6).
200 ///
201 /// `<date>` is in the form:
202 ///
203 /// - `YYYY-MM-DD` - Year/month/day, e.g. 2016-08-24.
204 /// - `YYYYMMDD` - Same as above without dividers.
205 /// - `YYYY-DDD` - Ordinal day where DDD is from 001 to 366, e.g. 2016-237.
206 /// - `YYYYDDD` - Same as above without dividers.
207 /// - `YYYY-Www-D` - Week day where ww is from 01 to 52 and D from 1-7,
208 /// e.g. 2016-W34-3.
209 /// - `YYYYWwwD` - Same as above without dividers.
210 ///
211 /// `<time>` is in the form:
212 ///
213 /// - `hh:mm:ss(.sss)` - Hours, minutes, seconds (subseconds), e.g. 22:10:42.123.
214 /// - `hhmmss(.sss)` - Same as above without dividers.
215 ///
216 /// `<tz>` is an optional timezone suffix of the form:
217 ///
218 /// - `Z` - UTC.
219 /// - `+hh:mm` or `-hh:mm` - Offset from UTC in hours and minutes, e.g. +12:00.
220 /// - `+hh` or `-hh` - Offset from UTC in hours, e.g. +12.
221 ///
222 /// If the timezone is not provided in @text it must be provided in @default_tz
223 /// (this field is otherwise ignored).
224 ///
225 /// This call can fail (returning [`None`]) if @text is not a valid ISO 8601
226 /// formatted string.
227 ///
228 /// You should release the return value by calling g_date_time_unref()
229 /// when you are done with it.
230 /// ## `text`
231 /// an ISO 8601 formatted time string.
232 /// ## `default_tz`
233 /// a #GTimeZone to use if the text doesn't contain a
234 /// timezone, or [`None`].
235 ///
236 /// # Returns
237 ///
238 /// a new #GDateTime, or [`None`]
239 // rustdoc-stripper-ignore-next-stop
240 /// Creates a #GDateTime corresponding to the given
241 /// [ISO 8601 formatted string](https://en.wikipedia.org/wiki/ISO_8601)
242 /// @text. ISO 8601 strings of the form `<date><sep><time><tz>` are supported, with
243 /// some extensions from [RFC 3339](https://tools.ietf.org/html/rfc3339) as
244 /// mentioned below.
245 ///
246 /// Note that as #GDateTime "is oblivious to leap seconds", leap seconds information
247 /// in an ISO-8601 string will be ignored, so a `23:59:60` time would be parsed as
248 /// `23:59:59`.
249 ///
250 /// `<sep>` is the separator and can be either 'T', 't' or ' '. The latter two
251 /// separators are an extension from
252 /// [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6).
253 ///
254 /// `<date>` is in the form:
255 ///
256 /// - `YYYY-MM-DD` - Year/month/day, e.g. 2016-08-24.
257 /// - `YYYYMMDD` - Same as above without dividers.
258 /// - `YYYY-DDD` - Ordinal day where DDD is from 001 to 366, e.g. 2016-237.
259 /// - `YYYYDDD` - Same as above without dividers.
260 /// - `YYYY-Www-D` - Week day where ww is from 01 to 52 and D from 1-7,
261 /// e.g. 2016-W34-3.
262 /// - `YYYYWwwD` - Same as above without dividers.
263 ///
264 /// `<time>` is in the form:
265 ///
266 /// - `hh:mm:ss(.sss)` - Hours, minutes, seconds (subseconds), e.g. 22:10:42.123.
267 /// - `hhmmss(.sss)` - Same as above without dividers.
268 ///
269 /// `<tz>` is an optional timezone suffix of the form:
270 ///
271 /// - `Z` - UTC.
272 /// - `+hh:mm` or `-hh:mm` - Offset from UTC in hours and minutes, e.g. +12:00.
273 /// - `+hh` or `-hh` - Offset from UTC in hours, e.g. +12.
274 ///
275 /// If the timezone is not provided in @text it must be provided in @default_tz
276 /// (this field is otherwise ignored).
277 ///
278 /// This call can fail (returning [`None`]) if @text is not a valid ISO 8601
279 /// formatted string.
280 ///
281 /// You should release the return value by calling g_date_time_unref()
282 /// when you are done with it.
283 /// ## `text`
284 /// an ISO 8601 formatted time string.
285 /// ## `default_tz`
286 /// a #GTimeZone to use if the text doesn't contain a
287 /// timezone, or [`None`].
288 ///
289 /// # Returns
290 ///
291 /// a new #GDateTime, or [`None`]
292 #[doc(alias = "g_date_time_new_from_iso8601")]
293 #[doc(alias = "new_from_iso8601")]
294 pub fn from_iso8601(text: &str, default_tz: Option<&TimeZone>) -> Result<DateTime, BoolError> {
295 unsafe {
296 Option::<_>::from_glib_full(ffi::g_date_time_new_from_iso8601(
297 text.to_glib_none().0,
298 default_tz.to_glib_none().0,
299 ))
300 .ok_or_else(|| crate::bool_error!("Invalid date"))
301 }
302 }
303
304 //#[cfg_attr(feature = "v2_62", deprecated = "Since 2.62")]
305 //#[allow(deprecated)]
306 //#[doc(alias = "g_date_time_new_from_timeval_local")]
307 //#[doc(alias = "new_from_timeval_local")]
308 //pub fn from_timeval_local(tv: /*Ignored*/&TimeVal) -> Result<DateTime, BoolError> {
309 // unsafe { TODO: call ffi:g_date_time_new_from_timeval_local() }
310 //}
311
312 //#[cfg_attr(feature = "v2_62", deprecated = "Since 2.62")]
313 //#[allow(deprecated)]
314 //#[doc(alias = "g_date_time_new_from_timeval_utc")]
315 //#[doc(alias = "new_from_timeval_utc")]
316 //pub fn from_timeval_utc(tv: /*Ignored*/&TimeVal) -> Result<DateTime, BoolError> {
317 // unsafe { TODO: call ffi:g_date_time_new_from_timeval_utc() }
318 //}
319
320 /// Creates a #GDateTime corresponding to the given Unix time @t in the
321 /// local time zone.
322 ///
323 /// Unix time is the number of seconds that have elapsed since 1970-01-01
324 /// 00:00:00 UTC, regardless of the local time offset.
325 ///
326 /// This call can fail (returning [`None`]) if @t represents a time outside
327 /// of the supported range of #GDateTime.
328 ///
329 /// You should release the return value by calling g_date_time_unref()
330 /// when you are done with it.
331 /// ## `t`
332 /// the Unix time
333 ///
334 /// # Returns
335 ///
336 /// a new #GDateTime, or [`None`]
337 // rustdoc-stripper-ignore-next-stop
338 /// Creates a #GDateTime corresponding to the given Unix time @t in the
339 /// local time zone.
340 ///
341 /// Unix time is the number of seconds that have elapsed since 1970-01-01
342 /// 00:00:00 UTC, regardless of the local time offset.
343 ///
344 /// This call can fail (returning [`None`]) if @t represents a time outside
345 /// of the supported range of #GDateTime.
346 ///
347 /// You should release the return value by calling g_date_time_unref()
348 /// when you are done with it.
349 /// ## `t`
350 /// the Unix time
351 ///
352 /// # Returns
353 ///
354 /// a new #GDateTime, or [`None`]
355 #[doc(alias = "g_date_time_new_from_unix_local")]
356 #[doc(alias = "new_from_unix_local")]
357 pub fn from_unix_local(t: i64) -> Result<DateTime, BoolError> {
358 unsafe {
359 Option::<_>::from_glib_full(ffi::g_date_time_new_from_unix_local(t))
360 .ok_or_else(|| crate::bool_error!("Invalid date"))
361 }
362 }
363
364 /// Creates a [`DateTime`][crate::DateTime] corresponding to the given Unix time @t in the
365 /// local time zone.
366 ///
367 /// Unix time is the number of microseconds that have elapsed since 1970-01-01
368 /// 00:00:00 UTC, regardless of the local time offset.
369 ///
370 /// This call can fail (returning `NULL`) if @t represents a time outside
371 /// of the supported range of #GDateTime.
372 ///
373 /// You should release the return value by calling `GLib::DateTime::unref()`
374 /// when you are done with it.
375 /// ## `usecs`
376 /// the Unix time in microseconds
377 ///
378 /// # Returns
379 ///
380 /// a new [`DateTime`][crate::DateTime], or `NULL`
381 // rustdoc-stripper-ignore-next-stop
382 /// Creates a [`DateTime`][crate::DateTime] corresponding to the given Unix time @t in the
383 /// local time zone.
384 ///
385 /// Unix time is the number of microseconds that have elapsed since 1970-01-01
386 /// 00:00:00 UTC, regardless of the local time offset.
387 ///
388 /// This call can fail (returning `NULL`) if @t represents a time outside
389 /// of the supported range of #GDateTime.
390 ///
391 /// You should release the return value by calling `GLib::DateTime::unref()`
392 /// when you are done with it.
393 /// ## `usecs`
394 /// the Unix time in microseconds
395 ///
396 /// # Returns
397 ///
398 /// a new [`DateTime`][crate::DateTime], or `NULL`
399 #[cfg(feature = "v2_80")]
400 #[cfg_attr(docsrs, doc(cfg(feature = "v2_80")))]
401 #[doc(alias = "g_date_time_new_from_unix_local_usec")]
402 #[doc(alias = "new_from_unix_local_usec")]
403 pub fn from_unix_local_usec(usecs: i64) -> Result<DateTime, BoolError> {
404 unsafe {
405 Option::<_>::from_glib_full(ffi::g_date_time_new_from_unix_local_usec(usecs))
406 .ok_or_else(|| crate::bool_error!("Invalid date"))
407 }
408 }
409
410 /// Creates a #GDateTime corresponding to the given Unix time @t in UTC.
411 ///
412 /// Unix time is the number of seconds that have elapsed since 1970-01-01
413 /// 00:00:00 UTC.
414 ///
415 /// This call can fail (returning [`None`]) if @t represents a time outside
416 /// of the supported range of #GDateTime.
417 ///
418 /// You should release the return value by calling g_date_time_unref()
419 /// when you are done with it.
420 /// ## `t`
421 /// the Unix time
422 ///
423 /// # Returns
424 ///
425 /// a new #GDateTime, or [`None`]
426 // rustdoc-stripper-ignore-next-stop
427 /// Creates a #GDateTime corresponding to the given Unix time @t in UTC.
428 ///
429 /// Unix time is the number of seconds that have elapsed since 1970-01-01
430 /// 00:00:00 UTC.
431 ///
432 /// This call can fail (returning [`None`]) if @t represents a time outside
433 /// of the supported range of #GDateTime.
434 ///
435 /// You should release the return value by calling g_date_time_unref()
436 /// when you are done with it.
437 /// ## `t`
438 /// the Unix time
439 ///
440 /// # Returns
441 ///
442 /// a new #GDateTime, or [`None`]
443 #[doc(alias = "g_date_time_new_from_unix_utc")]
444 #[doc(alias = "new_from_unix_utc")]
445 pub fn from_unix_utc(t: i64) -> Result<DateTime, BoolError> {
446 unsafe {
447 Option::<_>::from_glib_full(ffi::g_date_time_new_from_unix_utc(t))
448 .ok_or_else(|| crate::bool_error!("Invalid date"))
449 }
450 }
451
452 /// Creates a [`DateTime`][crate::DateTime] corresponding to the given Unix time @t in UTC.
453 ///
454 /// Unix time is the number of microseconds that have elapsed since 1970-01-01
455 /// 00:00:00 UTC.
456 ///
457 /// This call can fail (returning `NULL`) if @t represents a time outside
458 /// of the supported range of #GDateTime.
459 ///
460 /// You should release the return value by calling `GLib::DateTime::unref()`
461 /// when you are done with it.
462 /// ## `usecs`
463 /// the Unix time in microseconds
464 ///
465 /// # Returns
466 ///
467 /// a new [`DateTime`][crate::DateTime], or `NULL`
468 // rustdoc-stripper-ignore-next-stop
469 /// Creates a [`DateTime`][crate::DateTime] corresponding to the given Unix time @t in UTC.
470 ///
471 /// Unix time is the number of microseconds that have elapsed since 1970-01-01
472 /// 00:00:00 UTC.
473 ///
474 /// This call can fail (returning `NULL`) if @t represents a time outside
475 /// of the supported range of #GDateTime.
476 ///
477 /// You should release the return value by calling `GLib::DateTime::unref()`
478 /// when you are done with it.
479 /// ## `usecs`
480 /// the Unix time in microseconds
481 ///
482 /// # Returns
483 ///
484 /// a new [`DateTime`][crate::DateTime], or `NULL`
485 #[cfg(feature = "v2_80")]
486 #[cfg_attr(docsrs, doc(cfg(feature = "v2_80")))]
487 #[doc(alias = "g_date_time_new_from_unix_utc_usec")]
488 #[doc(alias = "new_from_unix_utc_usec")]
489 pub fn from_unix_utc_usec(usecs: i64) -> Result<DateTime, BoolError> {
490 unsafe {
491 Option::<_>::from_glib_full(ffi::g_date_time_new_from_unix_utc_usec(usecs))
492 .ok_or_else(|| crate::bool_error!("Invalid date"))
493 }
494 }
495
496 /// Creates a new #GDateTime corresponding to the given date and time in
497 /// the local time zone.
498 ///
499 /// This call is equivalent to calling g_date_time_new() with the time
500 /// zone returned by g_time_zone_new_local().
501 /// ## `year`
502 /// the year component of the date
503 /// ## `month`
504 /// the month component of the date
505 /// ## `day`
506 /// the day component of the date
507 /// ## `hour`
508 /// the hour component of the date
509 /// ## `minute`
510 /// the minute component of the date
511 /// ## `seconds`
512 /// the number of seconds past the minute
513 ///
514 /// # Returns
515 ///
516 /// a #GDateTime, or [`None`]
517 // rustdoc-stripper-ignore-next-stop
518 /// Creates a new #GDateTime corresponding to the given date and time in
519 /// the local time zone.
520 ///
521 /// This call is equivalent to calling g_date_time_new() with the time
522 /// zone returned by g_time_zone_new_local().
523 /// ## `year`
524 /// the year component of the date
525 /// ## `month`
526 /// the month component of the date
527 /// ## `day`
528 /// the day component of the date
529 /// ## `hour`
530 /// the hour component of the date
531 /// ## `minute`
532 /// the minute component of the date
533 /// ## `seconds`
534 /// the number of seconds past the minute
535 ///
536 /// # Returns
537 ///
538 /// a #GDateTime, or [`None`]
539 #[doc(alias = "g_date_time_new_local")]
540 #[doc(alias = "new_local")]
541 pub fn from_local(
542 year: i32,
543 month: i32,
544 day: i32,
545 hour: i32,
546 minute: i32,
547 seconds: f64,
548 ) -> Result<DateTime, BoolError> {
549 unsafe {
550 Option::<_>::from_glib_full(ffi::g_date_time_new_local(
551 year, month, day, hour, minute, seconds,
552 ))
553 .ok_or_else(|| crate::bool_error!("Invalid date"))
554 }
555 }
556
557 /// Creates a #GDateTime corresponding to this exact instant in the given
558 /// time zone @tz. The time is as accurate as the system allows, to a
559 /// maximum accuracy of 1 microsecond.
560 ///
561 /// This function will always succeed unless GLib is still being used after the
562 /// year 9999.
563 ///
564 /// You should release the return value by calling g_date_time_unref()
565 /// when you are done with it.
566 /// ## `tz`
567 /// a #GTimeZone
568 ///
569 /// # Returns
570 ///
571 /// a new #GDateTime, or [`None`]
572 // rustdoc-stripper-ignore-next-stop
573 /// Creates a #GDateTime corresponding to this exact instant in the given
574 /// time zone @tz. The time is as accurate as the system allows, to a
575 /// maximum accuracy of 1 microsecond.
576 ///
577 /// This function will always succeed unless GLib is still being used after the
578 /// year 9999.
579 ///
580 /// You should release the return value by calling g_date_time_unref()
581 /// when you are done with it.
582 /// ## `tz`
583 /// a #GTimeZone
584 ///
585 /// # Returns
586 ///
587 /// a new #GDateTime, or [`None`]
588 #[doc(alias = "g_date_time_new_now")]
589 #[doc(alias = "new_now")]
590 pub fn now(tz: &TimeZone) -> Result<DateTime, BoolError> {
591 unsafe {
592 Option::<_>::from_glib_full(ffi::g_date_time_new_now(tz.to_glib_none().0))
593 .ok_or_else(|| crate::bool_error!("Invalid date"))
594 }
595 }
596
597 /// Creates a #GDateTime corresponding to this exact instant in the local
598 /// time zone.
599 ///
600 /// This is equivalent to calling g_date_time_new_now() with the time
601 /// zone returned by g_time_zone_new_local().
602 ///
603 /// # Returns
604 ///
605 /// a new #GDateTime, or [`None`]
606 // rustdoc-stripper-ignore-next-stop
607 /// Creates a #GDateTime corresponding to this exact instant in the local
608 /// time zone.
609 ///
610 /// This is equivalent to calling g_date_time_new_now() with the time
611 /// zone returned by g_time_zone_new_local().
612 ///
613 /// # Returns
614 ///
615 /// a new #GDateTime, or [`None`]
616 #[doc(alias = "g_date_time_new_now_local")]
617 #[doc(alias = "new_now_local")]
618 pub fn now_local() -> Result<DateTime, BoolError> {
619 unsafe {
620 Option::<_>::from_glib_full(ffi::g_date_time_new_now_local())
621 .ok_or_else(|| crate::bool_error!("Invalid date"))
622 }
623 }
624
625 /// Creates a #GDateTime corresponding to this exact instant in UTC.
626 ///
627 /// This is equivalent to calling g_date_time_new_now() with the time
628 /// zone returned by g_time_zone_new_utc().
629 ///
630 /// # Returns
631 ///
632 /// a new #GDateTime, or [`None`]
633 // rustdoc-stripper-ignore-next-stop
634 /// Creates a #GDateTime corresponding to this exact instant in UTC.
635 ///
636 /// This is equivalent to calling g_date_time_new_now() with the time
637 /// zone returned by g_time_zone_new_utc().
638 ///
639 /// # Returns
640 ///
641 /// a new #GDateTime, or [`None`]
642 #[doc(alias = "g_date_time_new_now_utc")]
643 #[doc(alias = "new_now_utc")]
644 pub fn now_utc() -> Result<DateTime, BoolError> {
645 unsafe {
646 Option::<_>::from_glib_full(ffi::g_date_time_new_now_utc())
647 .ok_or_else(|| crate::bool_error!("Invalid date"))
648 }
649 }
650
651 /// Creates a new #GDateTime corresponding to the given date and time in
652 /// UTC.
653 ///
654 /// This call is equivalent to calling g_date_time_new() with the time
655 /// zone returned by g_time_zone_new_utc().
656 /// ## `year`
657 /// the year component of the date
658 /// ## `month`
659 /// the month component of the date
660 /// ## `day`
661 /// the day component of the date
662 /// ## `hour`
663 /// the hour component of the date
664 /// ## `minute`
665 /// the minute component of the date
666 /// ## `seconds`
667 /// the number of seconds past the minute
668 ///
669 /// # Returns
670 ///
671 /// a #GDateTime, or [`None`]
672 // rustdoc-stripper-ignore-next-stop
673 /// Creates a new #GDateTime corresponding to the given date and time in
674 /// UTC.
675 ///
676 /// This call is equivalent to calling g_date_time_new() with the time
677 /// zone returned by g_time_zone_new_utc().
678 /// ## `year`
679 /// the year component of the date
680 /// ## `month`
681 /// the month component of the date
682 /// ## `day`
683 /// the day component of the date
684 /// ## `hour`
685 /// the hour component of the date
686 /// ## `minute`
687 /// the minute component of the date
688 /// ## `seconds`
689 /// the number of seconds past the minute
690 ///
691 /// # Returns
692 ///
693 /// a #GDateTime, or [`None`]
694 #[doc(alias = "g_date_time_new_utc")]
695 #[doc(alias = "new_utc")]
696 pub fn from_utc(
697 year: i32,
698 month: i32,
699 day: i32,
700 hour: i32,
701 minute: i32,
702 seconds: f64,
703 ) -> Result<DateTime, BoolError> {
704 unsafe {
705 Option::<_>::from_glib_full(ffi::g_date_time_new_utc(
706 year, month, day, hour, minute, seconds,
707 ))
708 .ok_or_else(|| crate::bool_error!("Invalid date"))
709 }
710 }
711
712 /// Creates a copy of @self and adds the specified timespan to the copy.
713 /// ## `timespan`
714 /// a #GTimeSpan
715 ///
716 /// # Returns
717 ///
718 /// the newly created #GDateTime which
719 /// should be freed with g_date_time_unref(), or [`None`]
720 // rustdoc-stripper-ignore-next-stop
721 /// Creates a copy of @self and adds the specified timespan to the copy.
722 /// ## `timespan`
723 /// a #GTimeSpan
724 ///
725 /// # Returns
726 ///
727 /// the newly created #GDateTime which
728 /// should be freed with g_date_time_unref(), or [`None`]
729 #[doc(alias = "g_date_time_add")]
730 pub fn add(&self, timespan: TimeSpan) -> Result<DateTime, BoolError> {
731 unsafe {
732 Option::<_>::from_glib_full(ffi::g_date_time_add(
733 self.to_glib_none().0,
734 timespan.into_glib(),
735 ))
736 .ok_or_else(|| crate::bool_error!("Invalid date"))
737 }
738 }
739
740 /// Creates a copy of @self and adds the specified number of days to the
741 /// copy. Add negative values to subtract days.
742 /// ## `days`
743 /// the number of days
744 ///
745 /// # Returns
746 ///
747 /// the newly created #GDateTime which
748 /// should be freed with g_date_time_unref(), or [`None`]
749 // rustdoc-stripper-ignore-next-stop
750 /// Creates a copy of @self and adds the specified number of days to the
751 /// copy. Add negative values to subtract days.
752 /// ## `days`
753 /// the number of days
754 ///
755 /// # Returns
756 ///
757 /// the newly created #GDateTime which
758 /// should be freed with g_date_time_unref(), or [`None`]
759 #[doc(alias = "g_date_time_add_days")]
760 pub fn add_days(&self, days: i32) -> Result<DateTime, BoolError> {
761 unsafe {
762 Option::<_>::from_glib_full(ffi::g_date_time_add_days(self.to_glib_none().0, days))
763 .ok_or_else(|| crate::bool_error!("Invalid date"))
764 }
765 }
766
767 /// Creates a new #GDateTime adding the specified values to the current date and
768 /// time in @self. Add negative values to subtract.
769 /// ## `years`
770 /// the number of years to add
771 /// ## `months`
772 /// the number of months to add
773 /// ## `days`
774 /// the number of days to add
775 /// ## `hours`
776 /// the number of hours to add
777 /// ## `minutes`
778 /// the number of minutes to add
779 /// ## `seconds`
780 /// the number of seconds to add
781 ///
782 /// # Returns
783 ///
784 /// the newly created #GDateTime which
785 /// should be freed with g_date_time_unref(), or [`None`]
786 // rustdoc-stripper-ignore-next-stop
787 /// Creates a new #GDateTime adding the specified values to the current date and
788 /// time in @self. Add negative values to subtract.
789 /// ## `years`
790 /// the number of years to add
791 /// ## `months`
792 /// the number of months to add
793 /// ## `days`
794 /// the number of days to add
795 /// ## `hours`
796 /// the number of hours to add
797 /// ## `minutes`
798 /// the number of minutes to add
799 /// ## `seconds`
800 /// the number of seconds to add
801 ///
802 /// # Returns
803 ///
804 /// the newly created #GDateTime which
805 /// should be freed with g_date_time_unref(), or [`None`]
806 #[doc(alias = "g_date_time_add_full")]
807 pub fn add_full(
808 &self,
809 years: i32,
810 months: i32,
811 days: i32,
812 hours: i32,
813 minutes: i32,
814 seconds: f64,
815 ) -> Result<DateTime, BoolError> {
816 unsafe {
817 Option::<_>::from_glib_full(ffi::g_date_time_add_full(
818 self.to_glib_none().0,
819 years,
820 months,
821 days,
822 hours,
823 minutes,
824 seconds,
825 ))
826 .ok_or_else(|| crate::bool_error!("Invalid date"))
827 }
828 }
829
830 /// Creates a copy of @self and adds the specified number of hours.
831 /// Add negative values to subtract hours.
832 /// ## `hours`
833 /// the number of hours to add
834 ///
835 /// # Returns
836 ///
837 /// the newly created #GDateTime which
838 /// should be freed with g_date_time_unref(), or [`None`]
839 // rustdoc-stripper-ignore-next-stop
840 /// Creates a copy of @self and adds the specified number of hours.
841 /// Add negative values to subtract hours.
842 /// ## `hours`
843 /// the number of hours to add
844 ///
845 /// # Returns
846 ///
847 /// the newly created #GDateTime which
848 /// should be freed with g_date_time_unref(), or [`None`]
849 #[doc(alias = "g_date_time_add_hours")]
850 pub fn add_hours(&self, hours: i32) -> Result<DateTime, BoolError> {
851 unsafe {
852 Option::<_>::from_glib_full(ffi::g_date_time_add_hours(self.to_glib_none().0, hours))
853 .ok_or_else(|| crate::bool_error!("Invalid date"))
854 }
855 }
856
857 /// Creates a copy of @self adding the specified number of minutes.
858 /// Add negative values to subtract minutes.
859 /// ## `minutes`
860 /// the number of minutes to add
861 ///
862 /// # Returns
863 ///
864 /// the newly created #GDateTime which
865 /// should be freed with g_date_time_unref(), or [`None`]
866 // rustdoc-stripper-ignore-next-stop
867 /// Creates a copy of @self adding the specified number of minutes.
868 /// Add negative values to subtract minutes.
869 /// ## `minutes`
870 /// the number of minutes to add
871 ///
872 /// # Returns
873 ///
874 /// the newly created #GDateTime which
875 /// should be freed with g_date_time_unref(), or [`None`]
876 #[doc(alias = "g_date_time_add_minutes")]
877 pub fn add_minutes(&self, minutes: i32) -> Result<DateTime, BoolError> {
878 unsafe {
879 Option::<_>::from_glib_full(ffi::g_date_time_add_minutes(
880 self.to_glib_none().0,
881 minutes,
882 ))
883 .ok_or_else(|| crate::bool_error!("Invalid date"))
884 }
885 }
886
887 /// Creates a copy of @self and adds the specified number of months to the
888 /// copy. Add negative values to subtract months.
889 ///
890 /// The day of the month of the resulting #GDateTime is clamped to the number
891 /// of days in the updated calendar month. For example, if adding 1 month to
892 /// 31st January 2018, the result would be 28th February 2018. In 2020 (a leap
893 /// year), the result would be 29th February.
894 /// ## `months`
895 /// the number of months
896 ///
897 /// # Returns
898 ///
899 /// the newly created #GDateTime which
900 /// should be freed with g_date_time_unref(), or [`None`]
901 // rustdoc-stripper-ignore-next-stop
902 /// Creates a copy of @self and adds the specified number of months to the
903 /// copy. Add negative values to subtract months.
904 ///
905 /// The day of the month of the resulting #GDateTime is clamped to the number
906 /// of days in the updated calendar month. For example, if adding 1 month to
907 /// 31st January 2018, the result would be 28th February 2018. In 2020 (a leap
908 /// year), the result would be 29th February.
909 /// ## `months`
910 /// the number of months
911 ///
912 /// # Returns
913 ///
914 /// the newly created #GDateTime which
915 /// should be freed with g_date_time_unref(), or [`None`]
916 #[doc(alias = "g_date_time_add_months")]
917 pub fn add_months(&self, months: i32) -> Result<DateTime, BoolError> {
918 unsafe {
919 Option::<_>::from_glib_full(ffi::g_date_time_add_months(self.to_glib_none().0, months))
920 .ok_or_else(|| crate::bool_error!("Invalid date"))
921 }
922 }
923
924 /// Creates a copy of @self and adds the specified number of seconds.
925 /// Add negative values to subtract seconds.
926 /// ## `seconds`
927 /// the number of seconds to add
928 ///
929 /// # Returns
930 ///
931 /// the newly created #GDateTime which
932 /// should be freed with g_date_time_unref(), or [`None`]
933 // rustdoc-stripper-ignore-next-stop
934 /// Creates a copy of @self and adds the specified number of seconds.
935 /// Add negative values to subtract seconds.
936 /// ## `seconds`
937 /// the number of seconds to add
938 ///
939 /// # Returns
940 ///
941 /// the newly created #GDateTime which
942 /// should be freed with g_date_time_unref(), or [`None`]
943 #[doc(alias = "g_date_time_add_seconds")]
944 pub fn add_seconds(&self, seconds: f64) -> Result<DateTime, BoolError> {
945 unsafe {
946 Option::<_>::from_glib_full(ffi::g_date_time_add_seconds(
947 self.to_glib_none().0,
948 seconds,
949 ))
950 .ok_or_else(|| crate::bool_error!("Invalid date"))
951 }
952 }
953
954 /// Creates a copy of @self and adds the specified number of weeks to the
955 /// copy. Add negative values to subtract weeks.
956 /// ## `weeks`
957 /// the number of weeks
958 ///
959 /// # Returns
960 ///
961 /// the newly created #GDateTime which
962 /// should be freed with g_date_time_unref(), or [`None`]
963 // rustdoc-stripper-ignore-next-stop
964 /// Creates a copy of @self and adds the specified number of weeks to the
965 /// copy. Add negative values to subtract weeks.
966 /// ## `weeks`
967 /// the number of weeks
968 ///
969 /// # Returns
970 ///
971 /// the newly created #GDateTime which
972 /// should be freed with g_date_time_unref(), or [`None`]
973 #[doc(alias = "g_date_time_add_weeks")]
974 pub fn add_weeks(&self, weeks: i32) -> Result<DateTime, BoolError> {
975 unsafe {
976 Option::<_>::from_glib_full(ffi::g_date_time_add_weeks(self.to_glib_none().0, weeks))
977 .ok_or_else(|| crate::bool_error!("Invalid date"))
978 }
979 }
980
981 /// Creates a copy of @self and adds the specified number of years to the
982 /// copy. Add negative values to subtract years.
983 ///
984 /// As with g_date_time_add_months(), if the resulting date would be 29th
985 /// February on a non-leap year, the day will be clamped to 28th February.
986 /// ## `years`
987 /// the number of years
988 ///
989 /// # Returns
990 ///
991 /// the newly created #GDateTime which
992 /// should be freed with g_date_time_unref(), or [`None`]
993 // rustdoc-stripper-ignore-next-stop
994 /// Creates a copy of @self and adds the specified number of years to the
995 /// copy. Add negative values to subtract years.
996 ///
997 /// As with g_date_time_add_months(), if the resulting date would be 29th
998 /// February on a non-leap year, the day will be clamped to 28th February.
999 /// ## `years`
1000 /// the number of years
1001 ///
1002 /// # Returns
1003 ///
1004 /// the newly created #GDateTime which
1005 /// should be freed with g_date_time_unref(), or [`None`]
1006 #[doc(alias = "g_date_time_add_years")]
1007 pub fn add_years(&self, years: i32) -> Result<DateTime, BoolError> {
1008 unsafe {
1009 Option::<_>::from_glib_full(ffi::g_date_time_add_years(self.to_glib_none().0, years))
1010 .ok_or_else(|| crate::bool_error!("Invalid date"))
1011 }
1012 }
1013
1014 #[doc(alias = "g_date_time_compare")]
1015 fn compare(&self, dt2: &DateTime) -> i32 {
1016 unsafe {
1017 ffi::g_date_time_compare(
1018 ToGlibPtr::<*mut ffi::GDateTime>::to_glib_none(self).0 as ffi::gconstpointer,
1019 ToGlibPtr::<*mut ffi::GDateTime>::to_glib_none(dt2).0 as ffi::gconstpointer,
1020 )
1021 }
1022 }
1023
1024 /// Calculates the difference in time between @self and @begin. The
1025 /// #GTimeSpan that is returned is effectively @self - @begin (ie:
1026 /// positive if the first parameter is larger).
1027 /// ## `begin`
1028 /// a #GDateTime
1029 ///
1030 /// # Returns
1031 ///
1032 /// the difference between the two #GDateTime, as a time
1033 /// span expressed in microseconds.
1034 // rustdoc-stripper-ignore-next-stop
1035 /// Calculates the difference in time between @self and @begin. The
1036 /// #GTimeSpan that is returned is effectively @self - @begin (ie:
1037 /// positive if the first parameter is larger).
1038 /// ## `begin`
1039 /// a #GDateTime
1040 ///
1041 /// # Returns
1042 ///
1043 /// the difference between the two #GDateTime, as a time
1044 /// span expressed in microseconds.
1045 #[doc(alias = "g_date_time_difference")]
1046 pub fn difference(&self, begin: &DateTime) -> TimeSpan {
1047 unsafe {
1048 from_glib(ffi::g_date_time_difference(
1049 self.to_glib_none().0,
1050 begin.to_glib_none().0,
1051 ))
1052 }
1053 }
1054
1055 #[doc(alias = "g_date_time_equal")]
1056 fn equal(&self, dt2: &DateTime) -> bool {
1057 unsafe {
1058 from_glib(ffi::g_date_time_equal(
1059 ToGlibPtr::<*mut ffi::GDateTime>::to_glib_none(self).0 as ffi::gconstpointer,
1060 ToGlibPtr::<*mut ffi::GDateTime>::to_glib_none(dt2).0 as ffi::gconstpointer,
1061 ))
1062 }
1063 }
1064
1065 /// Creates a newly allocated string representing the requested @format.
1066 ///
1067 /// The format strings understood by this function are a subset of the
1068 /// `strftime()` format language as specified by C99. The ``D``, ``U`` and ``W``
1069 /// conversions are not supported, nor is the `E` modifier. The GNU
1070 /// extensions ``k``, ``l``, ``s`` and ``P`` are supported, however, as are the
1071 /// `0`, `_` and `-` modifiers. The Python extension ``f`` is also supported.
1072 ///
1073 /// In contrast to `strftime()`, this function always produces a UTF-8
1074 /// string, regardless of the current locale. Note that the rendering of
1075 /// many formats is locale-dependent and may not match the `strftime()`
1076 /// output exactly.
1077 ///
1078 /// The following format specifiers are supported:
1079 ///
1080 /// - ``a``: the abbreviated weekday name according to the current locale
1081 /// - ``A``: the full weekday name according to the current locale
1082 /// - ``b``: the abbreviated month name according to the current locale
1083 /// - ``B``: the full month name according to the current locale
1084 /// - ``c``: the preferred date and time representation for the current locale
1085 /// - ``C``: the century number (year/100) as a 2-digit integer (00-99)
1086 /// - ``d``: the day of the month as a decimal number (range 01 to 31)
1087 /// - ``e``: the day of the month as a decimal number (range 1 to 31);
1088 /// single digits are preceded by a figure space (U+2007)
1089 /// - ``F``: equivalent to ``Y`-`m`-`d`` (the ISO 8601 date format)
1090 /// - ``g``: the last two digits of the ISO 8601 week-based year as a
1091 /// decimal number (00-99). This works well with ``V`` and ``u``.
1092 /// - ``G``: the ISO 8601 week-based year as a decimal number. This works
1093 /// well with ``V`` and ``u``.
1094 /// - ``h``: equivalent to ``b``
1095 /// - ``H``: the hour as a decimal number using a 24-hour clock (range 00 to 23)
1096 /// - ``I``: the hour as a decimal number using a 12-hour clock (range 01 to 12)
1097 /// - ``j``: the day of the year as a decimal number (range 001 to 366)
1098 /// - ``k``: the hour (24-hour clock) as a decimal number (range 0 to 23);
1099 /// single digits are preceded by a figure space (U+2007)
1100 /// - ``l``: the hour (12-hour clock) as a decimal number (range 1 to 12);
1101 /// single digits are preceded by a figure space (U+2007)
1102 /// - ``m``: the month as a decimal number (range 01 to 12)
1103 /// - ``M``: the minute as a decimal number (range 00 to 59)
1104 /// - ``f``: the microsecond as a decimal number (range 000000 to 999999)
1105 /// - ``p``: either ‘AM’ or ‘PM’ according to the given time value, or the
1106 /// corresponding strings for the current locale. Noon is treated as
1107 /// ‘PM’ and midnight as ‘AM’. Use of this format specifier is discouraged, as
1108 /// many locales have no concept of AM/PM formatting. Use ``c`` or ``X`` instead.
1109 /// - ``P``: like ``p`` but lowercase: ‘am’ or ‘pm’ or a corresponding string for
1110 /// the current locale. Use of this format specifier is discouraged, as
1111 /// many locales have no concept of AM/PM formatting. Use ``c`` or ``X`` instead.
1112 /// - ``r``: the time in a.m. or p.m. notation. Use of this format specifier is
1113 /// discouraged, as many locales have no concept of AM/PM formatting. Use ``c``
1114 /// or ``X`` instead.
1115 /// - ``R``: the time in 24-hour notation (``H`:`M``)
1116 /// - ``s``: the number of seconds since the Epoch, that is, since 1970-01-01
1117 /// 00:00:00 UTC
1118 /// - ``S``: the second as a decimal number (range 00 to 60)
1119 /// - ``t``: a tab character
1120 /// - ``T``: the time in 24-hour notation with seconds (``H`:`M`:`S``)
1121 /// - ``u``: the ISO 8601 standard day of the week as a decimal, range 1 to 7,
1122 /// Monday being 1. This works well with ``G`` and ``V``.
1123 /// - ``V``: the ISO 8601 standard week number of the current year as a decimal
1124 /// number, range 01 to 53, where week 1 is the first week that has at
1125 /// least 4 days in the new year. See g_date_time_get_week_of_year().
1126 /// This works well with ``G`` and ``u``.
1127 /// - ``w``: the day of the week as a decimal, range 0 to 6, Sunday being 0.
1128 /// This is not the ISO 8601 standard format — use ``u`` instead.
1129 /// - ``x``: the preferred date representation for the current locale without
1130 /// the time
1131 /// - ``X``: the preferred time representation for the current locale without
1132 /// the date
1133 /// - ``y``: the year as a decimal number without the century
1134 /// - ``Y``: the year as a decimal number including the century
1135 /// - ``z``: the time zone as an offset from UTC (`+hhmm`)
1136 /// - `%:z`: the time zone as an offset from UTC (`+hh:mm`).
1137 /// This is a gnulib `strftime()` extension. Since: 2.38
1138 /// - `%::z`: the time zone as an offset from UTC (`+hh:mm:ss`). This is a
1139 /// gnulib `strftime()` extension. Since: 2.38
1140 /// - `%:::z`: the time zone as an offset from UTC, with `:` to necessary
1141 /// precision (e.g., `-04`, `+05:30`). This is a gnulib `strftime()` extension. Since: 2.38
1142 /// - ``Z``: the time zone or name or abbreviation
1143 /// - `%%`: a literal `%` character
1144 ///
1145 /// Some conversion specifications can be modified by preceding the
1146 /// conversion specifier by one or more modifier characters.
1147 ///
1148 /// The following modifiers are supported for many of the numeric
1149 /// conversions:
1150 ///
1151 /// - `O`: Use alternative numeric symbols, if the current locale supports those.
1152 /// - `_`: Pad a numeric result with spaces. This overrides the default padding
1153 /// for the specifier.
1154 /// - `-`: Do not pad a numeric result. This overrides the default padding
1155 /// for the specifier.
1156 /// - `0`: Pad a numeric result with zeros. This overrides the default padding
1157 /// for the specifier.
1158 ///
1159 /// The following modifiers are supported for many of the alphabetic conversions:
1160 ///
1161 /// - `^`: Use upper case if possible. This is a gnulib `strftime()` extension.
1162 /// Since: 2.80
1163 /// - `#`: Use opposite case if possible. This is a gnulib `strftime()`
1164 /// extension. Since: 2.80
1165 ///
1166 /// Additionally, when `O` is used with `B`, `b`, or `h`, it produces the alternative
1167 /// form of a month name. The alternative form should be used when the month
1168 /// name is used without a day number (e.g., standalone). It is required in
1169 /// some languages (Baltic, Slavic, Greek, and more) due to their grammatical
1170 /// rules. For other languages there is no difference. ``OB`` is a GNU and BSD
1171 /// `strftime()` extension expected to be added to the future POSIX specification,
1172 /// ``Ob`` and ``Oh`` are GNU `strftime()` extensions. Since: 2.56
1173 ///
1174 /// Since GLib 2.80, when `E` is used with ``c``, ``C``, ``x``, ``X``, ``y`` or ``Y``,
1175 /// the date is formatted using an alternate era representation specific to the
1176 /// locale. This is typically used for the Thai solar calendar or Japanese era
1177 /// names, for example.
1178 ///
1179 /// - ``Ec``: the preferred date and time representation for the current locale,
1180 /// using the alternate era representation
1181 /// - ``EC``: the name of the era
1182 /// - ``Ex``: the preferred date representation for the current locale without
1183 /// the time, using the alternate era representation
1184 /// - ``EX``: the preferred time representation for the current locale without
1185 /// the date, using the alternate era representation
1186 /// - ``Ey``: the year since the beginning of the era denoted by the ``EC``
1187 /// specifier
1188 /// - ``EY``: the full alternative year representation
1189 /// ## `format`
1190 /// a valid UTF-8 string, containing the format for the
1191 /// #GDateTime
1192 ///
1193 /// # Returns
1194 ///
1195 /// a newly allocated string formatted to
1196 /// the requested format or [`None`] in the case that there was an error (such
1197 /// as a format specifier not being supported in the current locale). The
1198 /// string should be freed with g_free().
1199 // rustdoc-stripper-ignore-next-stop
1200 /// Creates a newly allocated string representing the requested @format.
1201 ///
1202 /// The format strings understood by this function are a subset of the
1203 /// `strftime()` format language as specified by C99. The ``D``, ``U`` and ``W``
1204 /// conversions are not supported, nor is the `E` modifier. The GNU
1205 /// extensions ``k``, ``l``, ``s`` and ``P`` are supported, however, as are the
1206 /// `0`, `_` and `-` modifiers. The Python extension ``f`` is also supported.
1207 ///
1208 /// In contrast to `strftime()`, this function always produces a UTF-8
1209 /// string, regardless of the current locale. Note that the rendering of
1210 /// many formats is locale-dependent and may not match the `strftime()`
1211 /// output exactly.
1212 ///
1213 /// The following format specifiers are supported:
1214 ///
1215 /// - ``a``: the abbreviated weekday name according to the current locale
1216 /// - ``A``: the full weekday name according to the current locale
1217 /// - ``b``: the abbreviated month name according to the current locale
1218 /// - ``B``: the full month name according to the current locale
1219 /// - ``c``: the preferred date and time representation for the current locale
1220 /// - ``C``: the century number (year/100) as a 2-digit integer (00-99)
1221 /// - ``d``: the day of the month as a decimal number (range 01 to 31)
1222 /// - ``e``: the day of the month as a decimal number (range 1 to 31);
1223 /// single digits are preceded by a figure space (U+2007)
1224 /// - ``F``: equivalent to ``Y`-`m`-`d`` (the ISO 8601 date format)
1225 /// - ``g``: the last two digits of the ISO 8601 week-based year as a
1226 /// decimal number (00-99). This works well with ``V`` and ``u``.
1227 /// - ``G``: the ISO 8601 week-based year as a decimal number. This works
1228 /// well with ``V`` and ``u``.
1229 /// - ``h``: equivalent to ``b``
1230 /// - ``H``: the hour as a decimal number using a 24-hour clock (range 00 to 23)
1231 /// - ``I``: the hour as a decimal number using a 12-hour clock (range 01 to 12)
1232 /// - ``j``: the day of the year as a decimal number (range 001 to 366)
1233 /// - ``k``: the hour (24-hour clock) as a decimal number (range 0 to 23);
1234 /// single digits are preceded by a figure space (U+2007)
1235 /// - ``l``: the hour (12-hour clock) as a decimal number (range 1 to 12);
1236 /// single digits are preceded by a figure space (U+2007)
1237 /// - ``m``: the month as a decimal number (range 01 to 12)
1238 /// - ``M``: the minute as a decimal number (range 00 to 59)
1239 /// - ``f``: the microsecond as a decimal number (range 000000 to 999999)
1240 /// - ``p``: either ‘AM’ or ‘PM’ according to the given time value, or the
1241 /// corresponding strings for the current locale. Noon is treated as
1242 /// ‘PM’ and midnight as ‘AM’. Use of this format specifier is discouraged, as
1243 /// many locales have no concept of AM/PM formatting. Use ``c`` or ``X`` instead.
1244 /// - ``P``: like ``p`` but lowercase: ‘am’ or ‘pm’ or a corresponding string for
1245 /// the current locale. Use of this format specifier is discouraged, as
1246 /// many locales have no concept of AM/PM formatting. Use ``c`` or ``X`` instead.
1247 /// - ``r``: the time in a.m. or p.m. notation. Use of this format specifier is
1248 /// discouraged, as many locales have no concept of AM/PM formatting. Use ``c``
1249 /// or ``X`` instead.
1250 /// - ``R``: the time in 24-hour notation (``H`:`M``)
1251 /// - ``s``: the number of seconds since the Epoch, that is, since 1970-01-01
1252 /// 00:00:00 UTC
1253 /// - ``S``: the second as a decimal number (range 00 to 60)
1254 /// - ``t``: a tab character
1255 /// - ``T``: the time in 24-hour notation with seconds (``H`:`M`:`S``)
1256 /// - ``u``: the ISO 8601 standard day of the week as a decimal, range 1 to 7,
1257 /// Monday being 1. This works well with ``G`` and ``V``.
1258 /// - ``V``: the ISO 8601 standard week number of the current year as a decimal
1259 /// number, range 01 to 53, where week 1 is the first week that has at
1260 /// least 4 days in the new year. See g_date_time_get_week_of_year().
1261 /// This works well with ``G`` and ``u``.
1262 /// - ``w``: the day of the week as a decimal, range 0 to 6, Sunday being 0.
1263 /// This is not the ISO 8601 standard format — use ``u`` instead.
1264 /// - ``x``: the preferred date representation for the current locale without
1265 /// the time
1266 /// - ``X``: the preferred time representation for the current locale without
1267 /// the date
1268 /// - ``y``: the year as a decimal number without the century
1269 /// - ``Y``: the year as a decimal number including the century
1270 /// - ``z``: the time zone as an offset from UTC (`+hhmm`)
1271 /// - `%:z`: the time zone as an offset from UTC (`+hh:mm`).
1272 /// This is a gnulib `strftime()` extension. Since: 2.38
1273 /// - `%::z`: the time zone as an offset from UTC (`+hh:mm:ss`). This is a
1274 /// gnulib `strftime()` extension. Since: 2.38
1275 /// - `%:::z`: the time zone as an offset from UTC, with `:` to necessary
1276 /// precision (e.g., `-04`, `+05:30`). This is a gnulib `strftime()` extension. Since: 2.38
1277 /// - ``Z``: the time zone or name or abbreviation
1278 /// - `%%`: a literal `%` character
1279 ///
1280 /// Some conversion specifications can be modified by preceding the
1281 /// conversion specifier by one or more modifier characters.
1282 ///
1283 /// The following modifiers are supported for many of the numeric
1284 /// conversions:
1285 ///
1286 /// - `O`: Use alternative numeric symbols, if the current locale supports those.
1287 /// - `_`: Pad a numeric result with spaces. This overrides the default padding
1288 /// for the specifier.
1289 /// - `-`: Do not pad a numeric result. This overrides the default padding
1290 /// for the specifier.
1291 /// - `0`: Pad a numeric result with zeros. This overrides the default padding
1292 /// for the specifier.
1293 ///
1294 /// The following modifiers are supported for many of the alphabetic conversions:
1295 ///
1296 /// - `^`: Use upper case if possible. This is a gnulib `strftime()` extension.
1297 /// Since: 2.80
1298 /// - `#`: Use opposite case if possible. This is a gnulib `strftime()`
1299 /// extension. Since: 2.80
1300 ///
1301 /// Additionally, when `O` is used with `B`, `b`, or `h`, it produces the alternative
1302 /// form of a month name. The alternative form should be used when the month
1303 /// name is used without a day number (e.g., standalone). It is required in
1304 /// some languages (Baltic, Slavic, Greek, and more) due to their grammatical
1305 /// rules. For other languages there is no difference. ``OB`` is a GNU and BSD
1306 /// `strftime()` extension expected to be added to the future POSIX specification,
1307 /// ``Ob`` and ``Oh`` are GNU `strftime()` extensions. Since: 2.56
1308 ///
1309 /// Since GLib 2.80, when `E` is used with ``c``, ``C``, ``x``, ``X``, ``y`` or ``Y``,
1310 /// the date is formatted using an alternate era representation specific to the
1311 /// locale. This is typically used for the Thai solar calendar or Japanese era
1312 /// names, for example.
1313 ///
1314 /// - ``Ec``: the preferred date and time representation for the current locale,
1315 /// using the alternate era representation
1316 /// - ``EC``: the name of the era
1317 /// - ``Ex``: the preferred date representation for the current locale without
1318 /// the time, using the alternate era representation
1319 /// - ``EX``: the preferred time representation for the current locale without
1320 /// the date, using the alternate era representation
1321 /// - ``Ey``: the year since the beginning of the era denoted by the ``EC``
1322 /// specifier
1323 /// - ``EY``: the full alternative year representation
1324 /// ## `format`
1325 /// a valid UTF-8 string, containing the format for the
1326 /// #GDateTime
1327 ///
1328 /// # Returns
1329 ///
1330 /// a newly allocated string formatted to
1331 /// the requested format or [`None`] in the case that there was an error (such
1332 /// as a format specifier not being supported in the current locale). The
1333 /// string should be freed with g_free().
1334 #[doc(alias = "g_date_time_format")]
1335 pub fn format(&self, format: &str) -> Result<crate::GString, BoolError> {
1336 unsafe {
1337 Option::<_>::from_glib_full(ffi::g_date_time_format(
1338 self.to_glib_none().0,
1339 format.to_glib_none().0,
1340 ))
1341 .ok_or_else(|| crate::bool_error!("Invalid date"))
1342 }
1343 }
1344
1345 /// Format @self in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601),
1346 /// including the date, time and time zone, and return that as a UTF-8 encoded
1347 /// string.
1348 ///
1349 /// Since GLib 2.66, this will output to sub-second precision if needed.
1350 ///
1351 /// # Returns
1352 ///
1353 /// a newly allocated string formatted in
1354 /// ISO 8601 format or [`None`] in the case that there was an error. The string
1355 /// should be freed with g_free().
1356 // rustdoc-stripper-ignore-next-stop
1357 /// Format @self in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601),
1358 /// including the date, time and time zone, and return that as a UTF-8 encoded
1359 /// string.
1360 ///
1361 /// Since GLib 2.66, this will output to sub-second precision if needed.
1362 ///
1363 /// # Returns
1364 ///
1365 /// a newly allocated string formatted in
1366 /// ISO 8601 format or [`None`] in the case that there was an error. The string
1367 /// should be freed with g_free().
1368 #[cfg(feature = "v2_62")]
1369 #[cfg_attr(docsrs, doc(cfg(feature = "v2_62")))]
1370 #[doc(alias = "g_date_time_format_iso8601")]
1371 pub fn format_iso8601(&self) -> Result<crate::GString, BoolError> {
1372 unsafe {
1373 Option::<_>::from_glib_full(ffi::g_date_time_format_iso8601(self.to_glib_none().0))
1374 .ok_or_else(|| crate::bool_error!("Invalid date"))
1375 }
1376 }
1377
1378 /// Retrieves the day of the month represented by @self in the gregorian
1379 /// calendar.
1380 ///
1381 /// # Returns
1382 ///
1383 /// the day of the month
1384 // rustdoc-stripper-ignore-next-stop
1385 /// Retrieves the day of the month represented by @self in the gregorian
1386 /// calendar.
1387 ///
1388 /// # Returns
1389 ///
1390 /// the day of the month
1391 #[doc(alias = "g_date_time_get_day_of_month")]
1392 #[doc(alias = "get_day_of_month")]
1393 pub fn day_of_month(&self) -> i32 {
1394 unsafe { ffi::g_date_time_get_day_of_month(self.to_glib_none().0) }
1395 }
1396
1397 /// Retrieves the ISO 8601 day of the week on which @self falls (1 is
1398 /// Monday, 2 is Tuesday... 7 is Sunday).
1399 ///
1400 /// # Returns
1401 ///
1402 /// the day of the week
1403 // rustdoc-stripper-ignore-next-stop
1404 /// Retrieves the ISO 8601 day of the week on which @self falls (1 is
1405 /// Monday, 2 is Tuesday... 7 is Sunday).
1406 ///
1407 /// # Returns
1408 ///
1409 /// the day of the week
1410 #[doc(alias = "g_date_time_get_day_of_week")]
1411 #[doc(alias = "get_day_of_week")]
1412 pub fn day_of_week(&self) -> i32 {
1413 unsafe { ffi::g_date_time_get_day_of_week(self.to_glib_none().0) }
1414 }
1415
1416 /// Retrieves the day of the year represented by @self in the Gregorian
1417 /// calendar.
1418 ///
1419 /// # Returns
1420 ///
1421 /// the day of the year
1422 // rustdoc-stripper-ignore-next-stop
1423 /// Retrieves the day of the year represented by @self in the Gregorian
1424 /// calendar.
1425 ///
1426 /// # Returns
1427 ///
1428 /// the day of the year
1429 #[doc(alias = "g_date_time_get_day_of_year")]
1430 #[doc(alias = "get_day_of_year")]
1431 pub fn day_of_year(&self) -> i32 {
1432 unsafe { ffi::g_date_time_get_day_of_year(self.to_glib_none().0) }
1433 }
1434
1435 /// Retrieves the hour of the day represented by @self
1436 ///
1437 /// # Returns
1438 ///
1439 /// the hour of the day
1440 // rustdoc-stripper-ignore-next-stop
1441 /// Retrieves the hour of the day represented by @self
1442 ///
1443 /// # Returns
1444 ///
1445 /// the hour of the day
1446 #[doc(alias = "g_date_time_get_hour")]
1447 #[doc(alias = "get_hour")]
1448 pub fn hour(&self) -> i32 {
1449 unsafe { ffi::g_date_time_get_hour(self.to_glib_none().0) }
1450 }
1451
1452 /// Retrieves the microsecond of the date represented by @self
1453 ///
1454 /// # Returns
1455 ///
1456 /// the microsecond of the second
1457 // rustdoc-stripper-ignore-next-stop
1458 /// Retrieves the microsecond of the date represented by @self
1459 ///
1460 /// # Returns
1461 ///
1462 /// the microsecond of the second
1463 #[doc(alias = "g_date_time_get_microsecond")]
1464 #[doc(alias = "get_microsecond")]
1465 pub fn microsecond(&self) -> i32 {
1466 unsafe { ffi::g_date_time_get_microsecond(self.to_glib_none().0) }
1467 }
1468
1469 /// Retrieves the minute of the hour represented by @self
1470 ///
1471 /// # Returns
1472 ///
1473 /// the minute of the hour
1474 // rustdoc-stripper-ignore-next-stop
1475 /// Retrieves the minute of the hour represented by @self
1476 ///
1477 /// # Returns
1478 ///
1479 /// the minute of the hour
1480 #[doc(alias = "g_date_time_get_minute")]
1481 #[doc(alias = "get_minute")]
1482 pub fn minute(&self) -> i32 {
1483 unsafe { ffi::g_date_time_get_minute(self.to_glib_none().0) }
1484 }
1485
1486 /// Retrieves the month of the year represented by @self in the Gregorian
1487 /// calendar.
1488 ///
1489 /// # Returns
1490 ///
1491 /// the month represented by @self
1492 // rustdoc-stripper-ignore-next-stop
1493 /// Retrieves the month of the year represented by @self in the Gregorian
1494 /// calendar.
1495 ///
1496 /// # Returns
1497 ///
1498 /// the month represented by @self
1499 #[doc(alias = "g_date_time_get_month")]
1500 #[doc(alias = "get_month")]
1501 pub fn month(&self) -> i32 {
1502 unsafe { ffi::g_date_time_get_month(self.to_glib_none().0) }
1503 }
1504
1505 /// Retrieves the second of the minute represented by @self
1506 ///
1507 /// # Returns
1508 ///
1509 /// the second represented by @self
1510 // rustdoc-stripper-ignore-next-stop
1511 /// Retrieves the second of the minute represented by @self
1512 ///
1513 /// # Returns
1514 ///
1515 /// the second represented by @self
1516 #[doc(alias = "g_date_time_get_second")]
1517 #[doc(alias = "get_second")]
1518 pub fn second(&self) -> i32 {
1519 unsafe { ffi::g_date_time_get_second(self.to_glib_none().0) }
1520 }
1521
1522 /// Retrieves the number of seconds since the start of the last minute,
1523 /// including the fractional part.
1524 ///
1525 /// # Returns
1526 ///
1527 /// the number of seconds
1528 // rustdoc-stripper-ignore-next-stop
1529 /// Retrieves the number of seconds since the start of the last minute,
1530 /// including the fractional part.
1531 ///
1532 /// # Returns
1533 ///
1534 /// the number of seconds
1535 #[doc(alias = "g_date_time_get_seconds")]
1536 #[doc(alias = "get_seconds")]
1537 pub fn seconds(&self) -> f64 {
1538 unsafe { ffi::g_date_time_get_seconds(self.to_glib_none().0) }
1539 }
1540
1541 /// Get the time zone for this @self.
1542 ///
1543 /// # Returns
1544 ///
1545 /// the time zone
1546 // rustdoc-stripper-ignore-next-stop
1547 /// Get the time zone for this @self.
1548 ///
1549 /// # Returns
1550 ///
1551 /// the time zone
1552 #[cfg(feature = "v2_58")]
1553 #[cfg_attr(docsrs, doc(cfg(feature = "v2_58")))]
1554 #[doc(alias = "g_date_time_get_timezone")]
1555 #[doc(alias = "get_timezone")]
1556 pub fn timezone(&self) -> TimeZone {
1557 unsafe { from_glib_none(ffi::g_date_time_get_timezone(self.to_glib_none().0)) }
1558 }
1559
1560 /// Determines the time zone abbreviation to be used at the time and in
1561 /// the time zone of @self.
1562 ///
1563 /// For example, in Toronto this is currently "EST" during the winter
1564 /// months and "EDT" during the summer months when daylight savings
1565 /// time is in effect.
1566 ///
1567 /// # Returns
1568 ///
1569 /// the time zone abbreviation. The returned
1570 /// string is owned by the #GDateTime and it should not be
1571 /// modified or freed
1572 // rustdoc-stripper-ignore-next-stop
1573 /// Determines the time zone abbreviation to be used at the time and in
1574 /// the time zone of @self.
1575 ///
1576 /// For example, in Toronto this is currently "EST" during the winter
1577 /// months and "EDT" during the summer months when daylight savings
1578 /// time is in effect.
1579 ///
1580 /// # Returns
1581 ///
1582 /// the time zone abbreviation. The returned
1583 /// string is owned by the #GDateTime and it should not be
1584 /// modified or freed
1585 #[doc(alias = "g_date_time_get_timezone_abbreviation")]
1586 #[doc(alias = "get_timezone_abbreviation")]
1587 pub fn timezone_abbreviation(&self) -> crate::GString {
1588 unsafe {
1589 from_glib_none(ffi::g_date_time_get_timezone_abbreviation(
1590 self.to_glib_none().0,
1591 ))
1592 }
1593 }
1594
1595 /// Determines the offset to UTC in effect at the time and in the time
1596 /// zone of @self.
1597 ///
1598 /// The offset is the number of microseconds that you add to UTC time to
1599 /// arrive at local time for the time zone (ie: negative numbers for time
1600 /// zones west of GMT, positive numbers for east).
1601 ///
1602 /// If @self represents UTC time, then the offset is always zero.
1603 ///
1604 /// # Returns
1605 ///
1606 /// the number of microseconds that should be added to UTC to
1607 /// get the local time
1608 // rustdoc-stripper-ignore-next-stop
1609 /// Determines the offset to UTC in effect at the time and in the time
1610 /// zone of @self.
1611 ///
1612 /// The offset is the number of microseconds that you add to UTC time to
1613 /// arrive at local time for the time zone (ie: negative numbers for time
1614 /// zones west of GMT, positive numbers for east).
1615 ///
1616 /// If @self represents UTC time, then the offset is always zero.
1617 ///
1618 /// # Returns
1619 ///
1620 /// the number of microseconds that should be added to UTC to
1621 /// get the local time
1622 #[doc(alias = "g_date_time_get_utc_offset")]
1623 #[doc(alias = "get_utc_offset")]
1624 pub fn utc_offset(&self) -> TimeSpan {
1625 unsafe { from_glib(ffi::g_date_time_get_utc_offset(self.to_glib_none().0)) }
1626 }
1627
1628 /// Returns the ISO 8601 week-numbering year in which the week containing
1629 /// @self falls.
1630 ///
1631 /// This function, taken together with g_date_time_get_week_of_year() and
1632 /// g_date_time_get_day_of_week() can be used to determine the full ISO
1633 /// week date on which @self falls.
1634 ///
1635 /// This is usually equal to the normal Gregorian year (as returned by
1636 /// g_date_time_get_year()), except as detailed below:
1637 ///
1638 /// For Thursday, the week-numbering year is always equal to the usual
1639 /// calendar year. For other days, the number is such that every day
1640 /// within a complete week (Monday to Sunday) is contained within the
1641 /// same week-numbering year.
1642 ///
1643 /// For Monday, Tuesday and Wednesday occurring near the end of the year,
1644 /// this may mean that the week-numbering year is one greater than the
1645 /// calendar year (so that these days have the same week-numbering year
1646 /// as the Thursday occurring early in the next year).
1647 ///
1648 /// For Friday, Saturday and Sunday occurring near the start of the year,
1649 /// this may mean that the week-numbering year is one less than the
1650 /// calendar year (so that these days have the same week-numbering year
1651 /// as the Thursday occurring late in the previous year).
1652 ///
1653 /// An equivalent description is that the week-numbering year is equal to
1654 /// the calendar year containing the majority of the days in the current
1655 /// week (Monday to Sunday).
1656 ///
1657 /// Note that January 1 0001 in the proleptic Gregorian calendar is a
1658 /// Monday, so this function never returns 0.
1659 ///
1660 /// # Returns
1661 ///
1662 /// the ISO 8601 week-numbering year for @self
1663 // rustdoc-stripper-ignore-next-stop
1664 /// Returns the ISO 8601 week-numbering year in which the week containing
1665 /// @self falls.
1666 ///
1667 /// This function, taken together with g_date_time_get_week_of_year() and
1668 /// g_date_time_get_day_of_week() can be used to determine the full ISO
1669 /// week date on which @self falls.
1670 ///
1671 /// This is usually equal to the normal Gregorian year (as returned by
1672 /// g_date_time_get_year()), except as detailed below:
1673 ///
1674 /// For Thursday, the week-numbering year is always equal to the usual
1675 /// calendar year. For other days, the number is such that every day
1676 /// within a complete week (Monday to Sunday) is contained within the
1677 /// same week-numbering year.
1678 ///
1679 /// For Monday, Tuesday and Wednesday occurring near the end of the year,
1680 /// this may mean that the week-numbering year is one greater than the
1681 /// calendar year (so that these days have the same week-numbering year
1682 /// as the Thursday occurring early in the next year).
1683 ///
1684 /// For Friday, Saturday and Sunday occurring near the start of the year,
1685 /// this may mean that the week-numbering year is one less than the
1686 /// calendar year (so that these days have the same week-numbering year
1687 /// as the Thursday occurring late in the previous year).
1688 ///
1689 /// An equivalent description is that the week-numbering year is equal to
1690 /// the calendar year containing the majority of the days in the current
1691 /// week (Monday to Sunday).
1692 ///
1693 /// Note that January 1 0001 in the proleptic Gregorian calendar is a
1694 /// Monday, so this function never returns 0.
1695 ///
1696 /// # Returns
1697 ///
1698 /// the ISO 8601 week-numbering year for @self
1699 #[doc(alias = "g_date_time_get_week_numbering_year")]
1700 #[doc(alias = "get_week_numbering_year")]
1701 pub fn week_numbering_year(&self) -> i32 {
1702 unsafe { ffi::g_date_time_get_week_numbering_year(self.to_glib_none().0) }
1703 }
1704
1705 /// Returns the ISO 8601 week number for the week containing @self.
1706 /// The ISO 8601 week number is the same for every day of the week (from
1707 /// Moday through Sunday). That can produce some unusual results
1708 /// (described below).
1709 ///
1710 /// The first week of the year is week 1. This is the week that contains
1711 /// the first Thursday of the year. Equivalently, this is the first week
1712 /// that has more than 4 of its days falling within the calendar year.
1713 ///
1714 /// The value 0 is never returned by this function. Days contained
1715 /// within a year but occurring before the first ISO 8601 week of that
1716 /// year are considered as being contained in the last week of the
1717 /// previous year. Similarly, the final days of a calendar year may be
1718 /// considered as being part of the first ISO 8601 week of the next year
1719 /// if 4 or more days of that week are contained within the new year.
1720 ///
1721 /// # Returns
1722 ///
1723 /// the ISO 8601 week number for @self.
1724 // rustdoc-stripper-ignore-next-stop
1725 /// Returns the ISO 8601 week number for the week containing @self.
1726 /// The ISO 8601 week number is the same for every day of the week (from
1727 /// Moday through Sunday). That can produce some unusual results
1728 /// (described below).
1729 ///
1730 /// The first week of the year is week 1. This is the week that contains
1731 /// the first Thursday of the year. Equivalently, this is the first week
1732 /// that has more than 4 of its days falling within the calendar year.
1733 ///
1734 /// The value 0 is never returned by this function. Days contained
1735 /// within a year but occurring before the first ISO 8601 week of that
1736 /// year are considered as being contained in the last week of the
1737 /// previous year. Similarly, the final days of a calendar year may be
1738 /// considered as being part of the first ISO 8601 week of the next year
1739 /// if 4 or more days of that week are contained within the new year.
1740 ///
1741 /// # Returns
1742 ///
1743 /// the ISO 8601 week number for @self.
1744 #[doc(alias = "g_date_time_get_week_of_year")]
1745 #[doc(alias = "get_week_of_year")]
1746 pub fn week_of_year(&self) -> i32 {
1747 unsafe { ffi::g_date_time_get_week_of_year(self.to_glib_none().0) }
1748 }
1749
1750 /// Retrieves the year represented by @self in the Gregorian calendar.
1751 ///
1752 /// # Returns
1753 ///
1754 /// the year represented by @self
1755 // rustdoc-stripper-ignore-next-stop
1756 /// Retrieves the year represented by @self in the Gregorian calendar.
1757 ///
1758 /// # Returns
1759 ///
1760 /// the year represented by @self
1761 #[doc(alias = "g_date_time_get_year")]
1762 #[doc(alias = "get_year")]
1763 pub fn year(&self) -> i32 {
1764 unsafe { ffi::g_date_time_get_year(self.to_glib_none().0) }
1765 }
1766
1767 /// Retrieves the Gregorian day, month, and year of a given #GDateTime.
1768 ///
1769 /// # Returns
1770 ///
1771 ///
1772 /// ## `year`
1773 /// the return location for the gregorian year, or [`None`].
1774 ///
1775 /// ## `month`
1776 /// the return location for the month of the year, or [`None`].
1777 ///
1778 /// ## `day`
1779 /// the return location for the day of the month, or [`None`].
1780 // rustdoc-stripper-ignore-next-stop
1781 /// Retrieves the Gregorian day, month, and year of a given #GDateTime.
1782 ///
1783 /// # Returns
1784 ///
1785 ///
1786 /// ## `year`
1787 /// the return location for the gregorian year, or [`None`].
1788 ///
1789 /// ## `month`
1790 /// the return location for the month of the year, or [`None`].
1791 ///
1792 /// ## `day`
1793 /// the return location for the day of the month, or [`None`].
1794 #[doc(alias = "g_date_time_get_ymd")]
1795 #[doc(alias = "get_ymd")]
1796 pub fn ymd(&self) -> (i32, i32, i32) {
1797 unsafe {
1798 let mut year = std::mem::MaybeUninit::uninit();
1799 let mut month = std::mem::MaybeUninit::uninit();
1800 let mut day = std::mem::MaybeUninit::uninit();
1801 ffi::g_date_time_get_ymd(
1802 self.to_glib_none().0,
1803 year.as_mut_ptr(),
1804 month.as_mut_ptr(),
1805 day.as_mut_ptr(),
1806 );
1807 (year.assume_init(), month.assume_init(), day.assume_init())
1808 }
1809 }
1810
1811 #[doc(alias = "g_date_time_hash")]
1812 fn hash(&self) -> u32 {
1813 unsafe {
1814 ffi::g_date_time_hash(
1815 ToGlibPtr::<*mut ffi::GDateTime>::to_glib_none(self).0 as ffi::gconstpointer,
1816 )
1817 }
1818 }
1819
1820 /// Determines if daylight savings time is in effect at the time and in
1821 /// the time zone of @self.
1822 ///
1823 /// # Returns
1824 ///
1825 /// [`true`] if daylight savings time is in effect
1826 // rustdoc-stripper-ignore-next-stop
1827 /// Determines if daylight savings time is in effect at the time and in
1828 /// the time zone of @self.
1829 ///
1830 /// # Returns
1831 ///
1832 /// [`true`] if daylight savings time is in effect
1833 #[doc(alias = "g_date_time_is_daylight_savings")]
1834 pub fn is_daylight_savings(&self) -> bool {
1835 unsafe { from_glib(ffi::g_date_time_is_daylight_savings(self.to_glib_none().0)) }
1836 }
1837
1838 /// Creates a new #GDateTime corresponding to the same instant in time as
1839 /// @self, but in the local time zone.
1840 ///
1841 /// This call is equivalent to calling g_date_time_to_timezone() with the
1842 /// time zone returned by g_time_zone_new_local().
1843 ///
1844 /// # Returns
1845 ///
1846 /// the newly created #GDateTime which
1847 /// should be freed with g_date_time_unref(), or [`None`]
1848 // rustdoc-stripper-ignore-next-stop
1849 /// Creates a new #GDateTime corresponding to the same instant in time as
1850 /// @self, but in the local time zone.
1851 ///
1852 /// This call is equivalent to calling g_date_time_to_timezone() with the
1853 /// time zone returned by g_time_zone_new_local().
1854 ///
1855 /// # Returns
1856 ///
1857 /// the newly created #GDateTime which
1858 /// should be freed with g_date_time_unref(), or [`None`]
1859 #[doc(alias = "g_date_time_to_local")]
1860 pub fn to_local(&self) -> Result<DateTime, BoolError> {
1861 unsafe {
1862 Option::<_>::from_glib_full(ffi::g_date_time_to_local(self.to_glib_none().0))
1863 .ok_or_else(|| crate::bool_error!("Invalid date"))
1864 }
1865 }
1866
1867 //#[cfg_attr(feature = "v2_62", deprecated = "Since 2.62")]
1868 //#[allow(deprecated)]
1869 //#[doc(alias = "g_date_time_to_timeval")]
1870 //pub fn to_timeval(&self, tv: /*Ignored*/&mut TimeVal) -> bool {
1871 // unsafe { TODO: call ffi:g_date_time_to_timeval() }
1872 //}
1873
1874 /// Create a new #GDateTime corresponding to the same instant in time as
1875 /// @self, but in the time zone @tz.
1876 ///
1877 /// This call can fail in the case that the time goes out of bounds. For
1878 /// example, converting 0001-01-01 00:00:00 UTC to a time zone west of
1879 /// Greenwich will fail (due to the year 0 being out of range).
1880 /// ## `tz`
1881 /// the new #GTimeZone
1882 ///
1883 /// # Returns
1884 ///
1885 /// the newly created #GDateTime which
1886 /// should be freed with g_date_time_unref(), or [`None`]
1887 // rustdoc-stripper-ignore-next-stop
1888 /// Create a new #GDateTime corresponding to the same instant in time as
1889 /// @self, but in the time zone @tz.
1890 ///
1891 /// This call can fail in the case that the time goes out of bounds. For
1892 /// example, converting 0001-01-01 00:00:00 UTC to a time zone west of
1893 /// Greenwich will fail (due to the year 0 being out of range).
1894 /// ## `tz`
1895 /// the new #GTimeZone
1896 ///
1897 /// # Returns
1898 ///
1899 /// the newly created #GDateTime which
1900 /// should be freed with g_date_time_unref(), or [`None`]
1901 #[doc(alias = "g_date_time_to_timezone")]
1902 pub fn to_timezone(&self, tz: &TimeZone) -> Result<DateTime, BoolError> {
1903 unsafe {
1904 Option::<_>::from_glib_full(ffi::g_date_time_to_timezone(
1905 self.to_glib_none().0,
1906 tz.to_glib_none().0,
1907 ))
1908 .ok_or_else(|| crate::bool_error!("Invalid date"))
1909 }
1910 }
1911
1912 /// Gives the Unix time corresponding to @self, rounding down to the
1913 /// nearest second.
1914 ///
1915 /// Unix time is the number of seconds that have elapsed since 1970-01-01
1916 /// 00:00:00 UTC, regardless of the time zone associated with @self.
1917 ///
1918 /// # Returns
1919 ///
1920 /// the Unix time corresponding to @self
1921 // rustdoc-stripper-ignore-next-stop
1922 /// Gives the Unix time corresponding to @self, rounding down to the
1923 /// nearest second.
1924 ///
1925 /// Unix time is the number of seconds that have elapsed since 1970-01-01
1926 /// 00:00:00 UTC, regardless of the time zone associated with @self.
1927 ///
1928 /// # Returns
1929 ///
1930 /// the Unix time corresponding to @self
1931 #[doc(alias = "g_date_time_to_unix")]
1932 pub fn to_unix(&self) -> i64 {
1933 unsafe { ffi::g_date_time_to_unix(self.to_glib_none().0) }
1934 }
1935
1936 /// Gives the Unix time corresponding to @self, in microseconds.
1937 ///
1938 /// Unix time is the number of microseconds that have elapsed since 1970-01-01
1939 /// 00:00:00 UTC, regardless of the time zone associated with @self.
1940 ///
1941 /// # Returns
1942 ///
1943 /// the Unix time corresponding to @self
1944 // rustdoc-stripper-ignore-next-stop
1945 /// Gives the Unix time corresponding to @self, in microseconds.
1946 ///
1947 /// Unix time is the number of microseconds that have elapsed since 1970-01-01
1948 /// 00:00:00 UTC, regardless of the time zone associated with @self.
1949 ///
1950 /// # Returns
1951 ///
1952 /// the Unix time corresponding to @self
1953 #[cfg(feature = "v2_80")]
1954 #[cfg_attr(docsrs, doc(cfg(feature = "v2_80")))]
1955 #[doc(alias = "g_date_time_to_unix_usec")]
1956 pub fn to_unix_usec(&self) -> i64 {
1957 unsafe { ffi::g_date_time_to_unix_usec(self.to_glib_none().0) }
1958 }
1959
1960 /// Creates a new #GDateTime corresponding to the same instant in time as
1961 /// @self, but in UTC.
1962 ///
1963 /// This call is equivalent to calling g_date_time_to_timezone() with the
1964 /// time zone returned by g_time_zone_new_utc().
1965 ///
1966 /// # Returns
1967 ///
1968 /// the newly created #GDateTime which
1969 /// should be freed with g_date_time_unref(), or [`None`]
1970 // rustdoc-stripper-ignore-next-stop
1971 /// Creates a new #GDateTime corresponding to the same instant in time as
1972 /// @self, but in UTC.
1973 ///
1974 /// This call is equivalent to calling g_date_time_to_timezone() with the
1975 /// time zone returned by g_time_zone_new_utc().
1976 ///
1977 /// # Returns
1978 ///
1979 /// the newly created #GDateTime which
1980 /// should be freed with g_date_time_unref(), or [`None`]
1981 #[doc(alias = "g_date_time_to_utc")]
1982 pub fn to_utc(&self) -> Result<DateTime, BoolError> {
1983 unsafe {
1984 Option::<_>::from_glib_full(ffi::g_date_time_to_utc(self.to_glib_none().0))
1985 .ok_or_else(|| crate::bool_error!("Invalid date"))
1986 }
1987 }
1988}
1989
1990impl PartialOrd for DateTime {
1991 #[inline]
1992 fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
1993 Some(self.cmp(other))
1994 }
1995}
1996
1997impl Ord for DateTime {
1998 #[inline]
1999 fn cmp(&self, other: &Self) -> std::cmp::Ordering {
2000 self.compare(other).cmp(&0)
2001 }
2002}
2003
2004impl PartialEq for DateTime {
2005 #[inline]
2006 fn eq(&self, other: &Self) -> bool {
2007 self.equal(other)
2008 }
2009}
2010
2011impl Eq for DateTime {}
2012
2013impl std::hash::Hash for DateTime {
2014 #[inline]
2015 fn hash<H>(&self, state: &mut H)
2016 where
2017 H: std::hash::Hasher,
2018 {
2019 std::hash::Hash::hash(&self.hash(), state)
2020 }
2021}
2022
2023unsafe impl Send for DateTime {}
2024unsafe impl Sync for DateTime {}