glib/auto/time_zone.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::*, TimeType};
6
7crate::wrapper! {
8 /// A `GTimeZone` represents a time zone, at no particular point in time.
9 ///
10 /// The `GTimeZone` struct is refcounted and immutable.
11 ///
12 /// Each time zone has an identifier (for example, ‘Europe/London’) which is
13 /// platform dependent. See `GLib::TimeZone::new()` for information on the
14 /// identifier formats. The identifier of a time zone can be retrieved using
15 /// [`identifier()`][Self::identifier()].
16 ///
17 /// A time zone contains a number of intervals. Each interval has an abbreviation
18 /// to describe it (for example, ‘PDT’), an offset to UTC and a flag indicating
19 /// if the daylight savings time is in effect during that interval. A time zone
20 /// always has at least one interval — interval 0. Note that interval abbreviations
21 /// are not the same as time zone identifiers (apart from ‘UTC’), and cannot be
22 /// passed to `GLib::TimeZone::new()`.
23 ///
24 /// Every UTC time is contained within exactly one interval, but a given
25 /// local time may be contained within zero, one or two intervals (due to
26 /// incontinuities associated with daylight savings time).
27 ///
28 /// An interval may refer to a specific period of time (eg: the duration
29 /// of daylight savings time during 2010) or it may refer to many periods
30 /// of time that share the same properties (eg: all periods of daylight
31 /// savings time). It is also possible (usually for political reasons)
32 /// that some properties (like the abbreviation) change between intervals
33 /// without other properties changing.
34 // rustdoc-stripper-ignore-next-stop
35 /// A `GTimeZone` represents a time zone, at no particular point in time.
36 ///
37 /// The `GTimeZone` struct is refcounted and immutable.
38 ///
39 /// Each time zone has an identifier (for example, ‘Europe/London’) which is
40 /// platform dependent. See `GLib::TimeZone::new()` for information on the
41 /// identifier formats. The identifier of a time zone can be retrieved using
42 /// [`identifier()`][Self::identifier()].
43 ///
44 /// A time zone contains a number of intervals. Each interval has an abbreviation
45 /// to describe it (for example, ‘PDT’), an offset to UTC and a flag indicating
46 /// if the daylight savings time is in effect during that interval. A time zone
47 /// always has at least one interval — interval 0. Note that interval abbreviations
48 /// are not the same as time zone identifiers (apart from ‘UTC’), and cannot be
49 /// passed to `GLib::TimeZone::new()`.
50 ///
51 /// Every UTC time is contained within exactly one interval, but a given
52 /// local time may be contained within zero, one or two intervals (due to
53 /// incontinuities associated with daylight savings time).
54 ///
55 /// An interval may refer to a specific period of time (eg: the duration
56 /// of daylight savings time during 2010) or it may refer to many periods
57 /// of time that share the same properties (eg: all periods of daylight
58 /// savings time). It is also possible (usually for political reasons)
59 /// that some properties (like the abbreviation) change between intervals
60 /// without other properties changing.
61 #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
62 pub struct TimeZone(Shared<ffi::GTimeZone>);
63
64 match fn {
65 ref => |ptr| ffi::g_time_zone_ref(ptr),
66 unref => |ptr| ffi::g_time_zone_unref(ptr),
67 type_ => || ffi::g_time_zone_get_type(),
68 }
69}
70
71impl TimeZone {
72 /// A version of g_time_zone_new_identifier() which returns the UTC time zone
73 /// if @identifier could not be parsed or loaded.
74 ///
75 /// If you need to check whether @identifier was loaded successfully, use
76 /// g_time_zone_new_identifier().
77 ///
78 /// # Deprecated since 2.68
79 ///
80 /// Use g_time_zone_new_identifier() instead, as it provides
81 /// error reporting. Change your code to handle a potentially [`None`] return
82 /// value.
83 /// ## `identifier`
84 /// a timezone identifier
85 ///
86 /// # Returns
87 ///
88 /// the requested timezone
89 // rustdoc-stripper-ignore-next-stop
90 /// A version of g_time_zone_new_identifier() which returns the UTC time zone
91 /// if @identifier could not be parsed or loaded.
92 ///
93 /// If you need to check whether @identifier was loaded successfully, use
94 /// g_time_zone_new_identifier().
95 ///
96 /// # Deprecated since 2.68
97 ///
98 /// Use g_time_zone_new_identifier() instead, as it provides
99 /// error reporting. Change your code to handle a potentially [`None`] return
100 /// value.
101 /// ## `identifier`
102 /// a timezone identifier
103 ///
104 /// # Returns
105 ///
106 /// the requested timezone
107 #[cfg_attr(feature = "v2_68", deprecated = "Since 2.68")]
108 #[allow(deprecated)]
109 #[doc(alias = "g_time_zone_new")]
110 pub fn new(identifier: Option<&str>) -> TimeZone {
111 unsafe { from_glib_full(ffi::g_time_zone_new(identifier.to_glib_none().0)) }
112 }
113
114 /// Creates a #GTimeZone corresponding to @identifier. If @identifier cannot be
115 /// parsed or loaded, [`None`] is returned.
116 ///
117 /// @identifier can either be an RFC3339/ISO 8601 time offset or
118 /// something that would pass as a valid value for the `TZ` environment
119 /// variable (including [`None`]).
120 ///
121 /// In Windows, @identifier can also be the unlocalized name of a time
122 /// zone for standard time, for example "Pacific Standard Time".
123 ///
124 /// Valid RFC3339 time offsets are `"Z"` (for UTC) or
125 /// `"±hh:mm"`. ISO 8601 additionally specifies
126 /// `"±hhmm"` and `"±hh"`. Offsets are
127 /// time values to be added to Coordinated Universal Time (UTC) to get
128 /// the local time.
129 ///
130 /// In UNIX, the `TZ` environment variable typically corresponds
131 /// to the name of a file in the zoneinfo database, an absolute path to a file
132 /// somewhere else, or a string in
133 /// "std offset [dst [offset],start[/time],end[/time]]" (POSIX) format.
134 /// There are no spaces in the specification. The name of standard
135 /// and daylight savings time zone must be three or more alphabetic
136 /// characters. Offsets are time values to be added to local time to
137 /// get Coordinated Universal Time (UTC) and should be
138 /// `"[±]hh[[:]mm[:ss]]"`. Dates are either
139 /// `"Jn"` (Julian day with n between 1 and 365, leap
140 /// years not counted), `"n"` (zero-based Julian day
141 /// with n between 0 and 365) or `"Mm.w.d"` (day d
142 /// (0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day
143 /// 0 is a Sunday). Times are in local wall clock time, the default is
144 /// 02:00:00.
145 ///
146 /// In Windows, the "tzn[+|–]hh[:mm[:ss]][dzn]" format is used, but also
147 /// accepts POSIX format. The Windows format uses US rules for all time
148 /// zones; daylight savings time is 60 minutes behind the standard time
149 /// with date and time of change taken from Pacific Standard Time.
150 /// Offsets are time values to be added to the local time to get
151 /// Coordinated Universal Time (UTC).
152 ///
153 /// g_time_zone_new_local() calls this function with the value of the
154 /// `TZ` environment variable. This function itself is independent of
155 /// the value of `TZ`, but if @identifier is [`None`] then `/etc/localtime`
156 /// will be consulted to discover the correct time zone on UNIX and the
157 /// registry will be consulted or GetTimeZoneInformation() will be used
158 /// to get the local time zone on Windows.
159 ///
160 /// If intervals are not available, only time zone rules from `TZ`
161 /// environment variable or other means, then they will be computed
162 /// from year 1900 to 2037. If the maximum year for the rules is
163 /// available and it is greater than 2037, then it will followed
164 /// instead.
165 ///
166 /// See
167 /// [RFC3339 §5.6](http://tools.ietf.org/html/rfc3339#section-5.6)
168 /// for a precise definition of valid RFC3339 time offsets
169 /// (the `time-offset` expansion) and ISO 8601 for the
170 /// full list of valid time offsets. See
171 /// [The GNU C Library manual](http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html)
172 /// for an explanation of the possible
173 /// values of the `TZ` environment variable. See
174 /// [Microsoft Time Zone Index Values](http://msdn.microsoft.com/en-us/library/ms912391`28v`=winembedded.11`29`)
175 /// for the list of time zones on Windows.
176 ///
177 /// You should release the return value by calling g_time_zone_unref()
178 /// when you are done with it.
179 /// ## `identifier`
180 /// a timezone identifier
181 ///
182 /// # Returns
183 ///
184 /// the requested timezone, or [`None`] on
185 /// failure
186 // rustdoc-stripper-ignore-next-stop
187 /// Creates a #GTimeZone corresponding to @identifier. If @identifier cannot be
188 /// parsed or loaded, [`None`] is returned.
189 ///
190 /// @identifier can either be an RFC3339/ISO 8601 time offset or
191 /// something that would pass as a valid value for the `TZ` environment
192 /// variable (including [`None`]).
193 ///
194 /// In Windows, @identifier can also be the unlocalized name of a time
195 /// zone for standard time, for example "Pacific Standard Time".
196 ///
197 /// Valid RFC3339 time offsets are `"Z"` (for UTC) or
198 /// `"±hh:mm"`. ISO 8601 additionally specifies
199 /// `"±hhmm"` and `"±hh"`. Offsets are
200 /// time values to be added to Coordinated Universal Time (UTC) to get
201 /// the local time.
202 ///
203 /// In UNIX, the `TZ` environment variable typically corresponds
204 /// to the name of a file in the zoneinfo database, an absolute path to a file
205 /// somewhere else, or a string in
206 /// "std offset [dst [offset],start[/time],end[/time]]" (POSIX) format.
207 /// There are no spaces in the specification. The name of standard
208 /// and daylight savings time zone must be three or more alphabetic
209 /// characters. Offsets are time values to be added to local time to
210 /// get Coordinated Universal Time (UTC) and should be
211 /// `"[±]hh[[:]mm[:ss]]"`. Dates are either
212 /// `"Jn"` (Julian day with n between 1 and 365, leap
213 /// years not counted), `"n"` (zero-based Julian day
214 /// with n between 0 and 365) or `"Mm.w.d"` (day d
215 /// (0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day
216 /// 0 is a Sunday). Times are in local wall clock time, the default is
217 /// 02:00:00.
218 ///
219 /// In Windows, the "tzn[+|–]hh[:mm[:ss]][dzn]" format is used, but also
220 /// accepts POSIX format. The Windows format uses US rules for all time
221 /// zones; daylight savings time is 60 minutes behind the standard time
222 /// with date and time of change taken from Pacific Standard Time.
223 /// Offsets are time values to be added to the local time to get
224 /// Coordinated Universal Time (UTC).
225 ///
226 /// g_time_zone_new_local() calls this function with the value of the
227 /// `TZ` environment variable. This function itself is independent of
228 /// the value of `TZ`, but if @identifier is [`None`] then `/etc/localtime`
229 /// will be consulted to discover the correct time zone on UNIX and the
230 /// registry will be consulted or GetTimeZoneInformation() will be used
231 /// to get the local time zone on Windows.
232 ///
233 /// If intervals are not available, only time zone rules from `TZ`
234 /// environment variable or other means, then they will be computed
235 /// from year 1900 to 2037. If the maximum year for the rules is
236 /// available and it is greater than 2037, then it will followed
237 /// instead.
238 ///
239 /// See
240 /// [RFC3339 §5.6](http://tools.ietf.org/html/rfc3339#section-5.6)
241 /// for a precise definition of valid RFC3339 time offsets
242 /// (the `time-offset` expansion) and ISO 8601 for the
243 /// full list of valid time offsets. See
244 /// [The GNU C Library manual](http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html)
245 /// for an explanation of the possible
246 /// values of the `TZ` environment variable. See
247 /// [Microsoft Time Zone Index Values](http://msdn.microsoft.com/en-us/library/ms912391`28v`=winembedded.11`29`)
248 /// for the list of time zones on Windows.
249 ///
250 /// You should release the return value by calling g_time_zone_unref()
251 /// when you are done with it.
252 /// ## `identifier`
253 /// a timezone identifier
254 ///
255 /// # Returns
256 ///
257 /// the requested timezone, or [`None`] on
258 /// failure
259 #[cfg(feature = "v2_68")]
260 #[cfg_attr(docsrs, doc(cfg(feature = "v2_68")))]
261 #[doc(alias = "g_time_zone_new_identifier")]
262 #[doc(alias = "new_identifier")]
263 pub fn from_identifier(identifier: Option<&str>) -> Option<TimeZone> {
264 unsafe { from_glib_full(ffi::g_time_zone_new_identifier(identifier.to_glib_none().0)) }
265 }
266
267 /// Creates a #GTimeZone corresponding to local time. The local time
268 /// zone may change between invocations to this function; for example,
269 /// if the system administrator changes it.
270 ///
271 /// This is equivalent to calling g_time_zone_new() with the value of
272 /// the `TZ` environment variable (including the possibility of [`None`]).
273 ///
274 /// You should release the return value by calling g_time_zone_unref()
275 /// when you are done with it.
276 ///
277 /// # Returns
278 ///
279 /// the local timezone
280 // rustdoc-stripper-ignore-next-stop
281 /// Creates a #GTimeZone corresponding to local time. The local time
282 /// zone may change between invocations to this function; for example,
283 /// if the system administrator changes it.
284 ///
285 /// This is equivalent to calling g_time_zone_new() with the value of
286 /// the `TZ` environment variable (including the possibility of [`None`]).
287 ///
288 /// You should release the return value by calling g_time_zone_unref()
289 /// when you are done with it.
290 ///
291 /// # Returns
292 ///
293 /// the local timezone
294 #[doc(alias = "g_time_zone_new_local")]
295 #[doc(alias = "new_local")]
296 pub fn local() -> TimeZone {
297 unsafe { from_glib_full(ffi::g_time_zone_new_local()) }
298 }
299
300 /// Creates a #GTimeZone corresponding to the given constant offset from UTC,
301 /// in seconds.
302 ///
303 /// This is equivalent to calling g_time_zone_new() with a string in the form
304 /// `[+|-]hh[:mm[:ss]]`.
305 ///
306 /// It is possible for this function to fail if @seconds is too big (greater than
307 /// 24 hours), in which case this function will return the UTC timezone for
308 /// backwards compatibility. To detect failures like this, use
309 /// g_time_zone_new_identifier() directly.
310 /// ## `seconds`
311 /// offset to UTC, in seconds
312 ///
313 /// # Returns
314 ///
315 /// a timezone at the given offset from UTC, or UTC on
316 /// failure
317 // rustdoc-stripper-ignore-next-stop
318 /// Creates a #GTimeZone corresponding to the given constant offset from UTC,
319 /// in seconds.
320 ///
321 /// This is equivalent to calling g_time_zone_new() with a string in the form
322 /// `[+|-]hh[:mm[:ss]]`.
323 ///
324 /// It is possible for this function to fail if @seconds is too big (greater than
325 /// 24 hours), in which case this function will return the UTC timezone for
326 /// backwards compatibility. To detect failures like this, use
327 /// g_time_zone_new_identifier() directly.
328 /// ## `seconds`
329 /// offset to UTC, in seconds
330 ///
331 /// # Returns
332 ///
333 /// a timezone at the given offset from UTC, or UTC on
334 /// failure
335 #[cfg(feature = "v2_58")]
336 #[cfg_attr(docsrs, doc(cfg(feature = "v2_58")))]
337 #[doc(alias = "g_time_zone_new_offset")]
338 #[doc(alias = "new_offset")]
339 pub fn from_offset(seconds: i32) -> TimeZone {
340 unsafe { from_glib_full(ffi::g_time_zone_new_offset(seconds)) }
341 }
342
343 /// Creates a #GTimeZone corresponding to UTC.
344 ///
345 /// This is equivalent to calling g_time_zone_new() with a value like
346 /// "Z", "UTC", "+00", etc.
347 ///
348 /// You should release the return value by calling g_time_zone_unref()
349 /// when you are done with it.
350 ///
351 /// # Returns
352 ///
353 /// the universal timezone
354 // rustdoc-stripper-ignore-next-stop
355 /// Creates a #GTimeZone corresponding to UTC.
356 ///
357 /// This is equivalent to calling g_time_zone_new() with a value like
358 /// "Z", "UTC", "+00", etc.
359 ///
360 /// You should release the return value by calling g_time_zone_unref()
361 /// when you are done with it.
362 ///
363 /// # Returns
364 ///
365 /// the universal timezone
366 #[doc(alias = "g_time_zone_new_utc")]
367 #[doc(alias = "new_utc")]
368 pub fn utc() -> TimeZone {
369 unsafe { from_glib_full(ffi::g_time_zone_new_utc()) }
370 }
371
372 /// Finds an interval within @self that corresponds to the given @time_.
373 /// The meaning of @time_ depends on @type_.
374 ///
375 /// If @type_ is [`TimeType::Universal`][crate::TimeType::Universal] then this function will always
376 /// succeed (since universal time is monotonic and continuous).
377 ///
378 /// Otherwise @time_ is treated as local time. The distinction between
379 /// [`TimeType::Standard`][crate::TimeType::Standard] and [`TimeType::Daylight`][crate::TimeType::Daylight] is ignored except in
380 /// the case that the given @time_ is ambiguous. In Toronto, for example,
381 /// 01:30 on November 7th 2010 occurred twice (once inside of daylight
382 /// savings time and the next, an hour later, outside of daylight savings
383 /// time). In this case, the different value of @type_ would result in a
384 /// different interval being returned.
385 ///
386 /// It is still possible for this function to fail. In Toronto, for
387 /// example, 02:00 on March 14th 2010 does not exist (due to the leap
388 /// forward to begin daylight savings time). -1 is returned in that
389 /// case.
390 /// ## `type_`
391 /// the #GTimeType of @time_
392 /// ## `time_`
393 /// a number of seconds since January 1, 1970
394 ///
395 /// # Returns
396 ///
397 /// the interval containing @time_, or -1 in case of failure
398 // rustdoc-stripper-ignore-next-stop
399 /// Finds an interval within @self that corresponds to the given @time_.
400 /// The meaning of @time_ depends on @type_.
401 ///
402 /// If @type_ is [`TimeType::Universal`][crate::TimeType::Universal] then this function will always
403 /// succeed (since universal time is monotonic and continuous).
404 ///
405 /// Otherwise @time_ is treated as local time. The distinction between
406 /// [`TimeType::Standard`][crate::TimeType::Standard] and [`TimeType::Daylight`][crate::TimeType::Daylight] is ignored except in
407 /// the case that the given @time_ is ambiguous. In Toronto, for example,
408 /// 01:30 on November 7th 2010 occurred twice (once inside of daylight
409 /// savings time and the next, an hour later, outside of daylight savings
410 /// time). In this case, the different value of @type_ would result in a
411 /// different interval being returned.
412 ///
413 /// It is still possible for this function to fail. In Toronto, for
414 /// example, 02:00 on March 14th 2010 does not exist (due to the leap
415 /// forward to begin daylight savings time). -1 is returned in that
416 /// case.
417 /// ## `type_`
418 /// the #GTimeType of @time_
419 /// ## `time_`
420 /// a number of seconds since January 1, 1970
421 ///
422 /// # Returns
423 ///
424 /// the interval containing @time_, or -1 in case of failure
425 #[doc(alias = "g_time_zone_find_interval")]
426 pub fn find_interval(&self, type_: TimeType, time_: i64) -> i32 {
427 unsafe { ffi::g_time_zone_find_interval(self.to_glib_none().0, type_.into_glib(), time_) }
428 }
429
430 /// Determines the time zone abbreviation to be used during a particular
431 /// @interval of time in the time zone @self.
432 ///
433 /// For example, in Toronto this is currently "EST" during the winter
434 /// months and "EDT" during the summer months when daylight savings time
435 /// is in effect.
436 /// ## `interval`
437 /// an interval within the timezone
438 ///
439 /// # Returns
440 ///
441 /// the time zone abbreviation, which belongs to @self
442 // rustdoc-stripper-ignore-next-stop
443 /// Determines the time zone abbreviation to be used during a particular
444 /// @interval of time in the time zone @self.
445 ///
446 /// For example, in Toronto this is currently "EST" during the winter
447 /// months and "EDT" during the summer months when daylight savings time
448 /// is in effect.
449 /// ## `interval`
450 /// an interval within the timezone
451 ///
452 /// # Returns
453 ///
454 /// the time zone abbreviation, which belongs to @self
455 #[doc(alias = "g_time_zone_get_abbreviation")]
456 #[doc(alias = "get_abbreviation")]
457 pub fn abbreviation(&self, interval: i32) -> crate::GString {
458 unsafe {
459 from_glib_none(ffi::g_time_zone_get_abbreviation(
460 self.to_glib_none().0,
461 interval,
462 ))
463 }
464 }
465
466 /// Get the identifier of this #GTimeZone, as passed to g_time_zone_new().
467 /// If the identifier passed at construction time was not recognised, `UTC` will
468 /// be returned. If it was [`None`], the identifier of the local timezone at
469 /// construction time will be returned.
470 ///
471 /// The identifier will be returned in the same format as provided at
472 /// construction time: if provided as a time offset, that will be returned by
473 /// this function.
474 ///
475 /// # Returns
476 ///
477 /// identifier for this timezone
478 // rustdoc-stripper-ignore-next-stop
479 /// Get the identifier of this #GTimeZone, as passed to g_time_zone_new().
480 /// If the identifier passed at construction time was not recognised, `UTC` will
481 /// be returned. If it was [`None`], the identifier of the local timezone at
482 /// construction time will be returned.
483 ///
484 /// The identifier will be returned in the same format as provided at
485 /// construction time: if provided as a time offset, that will be returned by
486 /// this function.
487 ///
488 /// # Returns
489 ///
490 /// identifier for this timezone
491 #[cfg(feature = "v2_58")]
492 #[cfg_attr(docsrs, doc(cfg(feature = "v2_58")))]
493 #[doc(alias = "g_time_zone_get_identifier")]
494 #[doc(alias = "get_identifier")]
495 pub fn identifier(&self) -> crate::GString {
496 unsafe { from_glib_none(ffi::g_time_zone_get_identifier(self.to_glib_none().0)) }
497 }
498
499 /// Determines the offset to UTC in effect during a particular @interval
500 /// of time in the time zone @self.
501 ///
502 /// The offset is the number of seconds that you add to UTC time to
503 /// arrive at local time for @self (ie: negative numbers for time zones
504 /// west of GMT, positive numbers for east).
505 /// ## `interval`
506 /// an interval within the timezone
507 ///
508 /// # Returns
509 ///
510 /// the number of seconds that should be added to UTC to get the
511 /// local time in @self
512 // rustdoc-stripper-ignore-next-stop
513 /// Determines the offset to UTC in effect during a particular @interval
514 /// of time in the time zone @self.
515 ///
516 /// The offset is the number of seconds that you add to UTC time to
517 /// arrive at local time for @self (ie: negative numbers for time zones
518 /// west of GMT, positive numbers for east).
519 /// ## `interval`
520 /// an interval within the timezone
521 ///
522 /// # Returns
523 ///
524 /// the number of seconds that should be added to UTC to get the
525 /// local time in @self
526 #[doc(alias = "g_time_zone_get_offset")]
527 #[doc(alias = "get_offset")]
528 pub fn offset(&self, interval: i32) -> i32 {
529 unsafe { ffi::g_time_zone_get_offset(self.to_glib_none().0, interval) }
530 }
531
532 /// Determines if daylight savings time is in effect during a particular
533 /// @interval of time in the time zone @self.
534 /// ## `interval`
535 /// an interval within the timezone
536 ///
537 /// # Returns
538 ///
539 /// [`true`] if daylight savings time is in effect
540 // rustdoc-stripper-ignore-next-stop
541 /// Determines if daylight savings time is in effect during a particular
542 /// @interval of time in the time zone @self.
543 /// ## `interval`
544 /// an interval within the timezone
545 ///
546 /// # Returns
547 ///
548 /// [`true`] if daylight savings time is in effect
549 #[doc(alias = "g_time_zone_is_dst")]
550 pub fn is_dst(&self, interval: i32) -> bool {
551 unsafe { from_glib(ffi::g_time_zone_is_dst(self.to_glib_none().0, interval)) }
552 }
553}
554
555unsafe impl Send for TimeZone {}
556unsafe impl Sync for TimeZone {}