1 // Generated by gmmproc 2.64.2 -- DO NOT MODIFY!
2 #ifndef _GLIBMM_TIMEZONE_H
3 #define _GLIBMM_TIMEZONE_H
4
5
6 /* Copyright (C) 2011 The glibmm Development Team
7 *
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2.1 of the License, or (at your option) any later version.
12 *
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
20 */
21
22
23 #include <glibmmconfig.h>
24 #include <glibmm/refptr.h>
25 #include <glibmm/ustring.h>
26 #include <glibmm/value.h>
27 #include <glib.h>
28
29 #ifndef DOXYGEN_SHOULD_SKIP_THIS
30 typedef struct _GTimeZone GTimeZone;
31 #endif
32
33 //TODO: When we can change API, make TimeZone a _CLASS_BOXEDTYPE.
34
35 namespace Glib
36 {
37
38 /** @addtogroup glibmmEnums glibmm Enums and Flags */
39
40 /**
41 * @var TimeType TIME_TYPE_STANDARD
42 * The time is in local standard time.
43 *
44 * @var TimeType TIME_TYPE_DAYLIGHT
45 * The time is in local daylight time.
46 *
47 * @var TimeType TIME_TYPE_UNIVERSAL
48 * The time is in UTC.
49 *
50 * @enum TimeType
51 *
52 * Disambiguates a given time in two ways.
53 *
54 * First, specifies if the given time is in universal or local time.
55 *
56 * Second, if the time is in local time, specifies if it is local
57 * standard time or local daylight time. This is important for the case
58 * where the same local time occurs twice (during daylight savings time
59 * transitions, for example).
60 *
61 * @ingroup glibmmEnums
62 */
63 enum TimeType
64 {
65 TIME_TYPE_STANDARD,
66 TIME_TYPE_DAYLIGHT,
67 TIME_TYPE_UNIVERSAL
68 };
69
70
71 /** TimeZone - A structure representing a time zone.
72 * TimeZone is a structure that represents a time zone, at no particular point
73 * in time. It is immutable.
74 *
75 * A time zone contains a number of intervals. Each interval has an
76 * abbreviation to describe it, an offet to UTC and a flag indicating if the
77 * daylight savings time is in effect during that interval. A time zone always
78 * has at least one interval -- interval 0.
79 *
80 * Every UTC time is contained within exactly one interval, but a given local
81 * time may be contained within zero, one or two intervals (due to
82 * incontinuities associated with daylight savings time).
83 *
84 * An interval may refer to a specific period of time (eg: the duration of
85 * daylight savings time during 2010) or it may refer to many periods of time
86 * that share the same properties (eg: all periods of daylight savings time).
87 * It is also possible (usually for political reasons) that some properties
88 * (like the abbreviation) change between intervals without other properties
89 * changing.
90 * @newin{2,30}
91 */
92 class GLIBMM_API TimeZone
93 {
94 public:
95 #ifndef DOXYGEN_SHOULD_SKIP_THIS
96 using CppObjectType = TimeZone;
97 using BaseObjectType = GTimeZone;
98 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
99
100 /** Constructs an invalid object.
101 * E.g. for output arguments to methods. There is not much you can do with
102 * the object before it has been assigned a valid value.
103 */
104 TimeZone();
105
106 // Use make_a_copy=true when getting it directly from a struct.
107 explicit TimeZone(GTimeZone* castitem, bool make_a_copy = false);
108
109 TimeZone(const TimeZone& src);
110 TimeZone& operator=(const TimeZone& src);
111
112 TimeZone(TimeZone&& other) noexcept;
113 TimeZone& operator=(TimeZone&& other) noexcept;
114
115 ~TimeZone() noexcept;
116
117 void swap(TimeZone& other) noexcept;
118
gobj()119 GTimeZone* gobj() { return gobject_; }
gobj()120 const GTimeZone* gobj() const { return gobject_; }
121
122 ///Provides access to the underlying C instance. The caller is responsible for freeing it. Use when directly setting fields in structs.
123 GTimeZone* gobj_copy() const;
124
125 protected:
126 GTimeZone* gobject_;
127
128 private:
129
130
131 public:
132
133 /** Creates a TimeZone corresponding to @a identifier.
134 *
135 * @a identifier can either be an RFC3339/ISO 8601 time offset or
136 * something that would pass as a valid value for the `TZ` environment
137 * variable (including <tt>nullptr</tt>).
138 *
139 * In Windows, @a identifier can also be the unlocalized name of a time
140 * zone for standard time, for example "Pacific Standard Time".
141 *
142 * Valid RFC3339 time offsets are `"Z"` (for UTC) or
143 * `"±hh:mm"`. ISO 8601 additionally specifies
144 * `"±hhmm"` and `"±hh"`. Offsets are
145 * time values to be added to Coordinated Universal Time (UTC) to get
146 * the local time.
147 *
148 * In UNIX, the `TZ` environment variable typically corresponds
149 * to the name of a file in the zoneinfo database, an absolute path to a file
150 * somewhere else, or a string in
151 * "std offset [dst [offset],start[/time],end[/time]]" (POSIX) format.
152 * There are no spaces in the specification. The name of standard
153 * and daylight savings time zone must be three or more alphabetic
154 * characters. Offsets are time values to be added to local time to
155 * get Coordinated Universal Time (UTC) and should be
156 * `"[±]hh[[:]mm[:ss]]"`. Dates are either
157 * `"Jn"` (Julian day with n between 1 and 365, leap
158 * years not counted), `"n"` (zero-based Julian day
159 * with n between 0 and 365) or `"Mm.w.d"` (day d
160 * (0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day
161 * 0 is a Sunday). Times are in local wall clock time, the default is
162 * 02:00:00.
163 *
164 * In Windows, the "tzn[+|–]hh[:mm[:ss]][dzn]" format is used, but also
165 * accepts POSIX format. The Windows format uses US rules for all time
166 * zones; daylight savings time is 60 minutes behind the standard time
167 * with date and time of change taken from Pacific Standard Time.
168 * Offsets are time values to be added to the local time to get
169 * Coordinated Universal Time (UTC).
170 *
171 * g_time_zone_new_local() calls this function with the value of the
172 * `TZ` environment variable. This function itself is independent of
173 * the value of `TZ`, but if @a identifier is <tt>nullptr</tt> then `/etc/localtime`
174 * will be consulted to discover the correct time zone on UNIX and the
175 * registry will be consulted or GetTimeZoneInformation() will be used
176 * to get the local time zone on Windows.
177 *
178 * If intervals are not available, only time zone rules from `TZ`
179 * environment variable or other means, then they will be computed
180 * from year 1900 to 2037. If the maximum year for the rules is
181 * available and it is greater than 2037, then it will followed
182 * instead.
183 *
184 * See
185 * [RFC3339 §5.6](http://tools.ietf.org/html/rfc3339#section-5.6)
186 * for a precise definition of valid RFC3339 time offsets
187 * (the `time-offset` expansion) and ISO 8601 for the
188 * full list of valid time offsets. See
189 * [The GNU C Library manual](http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html)
190 * for an explanation of the possible
191 * values of the `TZ` environment variable. See
192 * [Microsoft Time Zone Index Values](http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx)
193 * for the list of time zones on Windows.
194 *
195 * You should release the return value by calling g_time_zone_unref()
196 * when you are done with it.
197 *
198 * @newin{2,26}
199 *
200 * @param identifier A timezone identifier.
201 * @return The requested timezone.
202 */
203 static TimeZone create(const Glib::ustring& identifier);
204
205 /** Creates a TimeZone corresponding to local time. The local time
206 * zone may change between invocations to this function; for example,
207 * if the system administrator changes it.
208 *
209 * This is equivalent to calling g_time_zone_new() with the value of
210 * the `TZ` environment variable (including the possibility of <tt>nullptr</tt>).
211 *
212 * You should release the return value by calling g_time_zone_unref()
213 * when you are done with it.
214 *
215 * @newin{2,26}
216 *
217 * @return The local timezone.
218 */
219 static TimeZone create_local();
220
221 /** Creates a TimeZone corresponding to UTC.
222 *
223 * This is equivalent to calling g_time_zone_new() with a value like
224 * "Z", "UTC", "+00", etc.
225 *
226 * You should release the return value by calling g_time_zone_unref()
227 * when you are done with it.
228 *
229 * @newin{2,26}
230 *
231 * @return The universal timezone.
232 */
233 static TimeZone create_utc();
234
235
236 /** Finds an interval within @a tz that corresponds to the given @a time.
237 * The meaning of @a time depends on @a type.
238 *
239 * If @a type is TIME_TYPE_UNIVERSAL then this function will always
240 * succeed (since universal time is monotonic and continuous).
241 *
242 * Otherwise @a time is treated as local time. The distinction between
243 * TIME_TYPE_STANDARD and TIME_TYPE_DAYLIGHT is ignored except in
244 * the case that the given @a time is ambiguous. In Toronto, for example,
245 * 01:30 on November 7th 2010 occurred twice (once inside of daylight
246 * savings time and the next, an hour later, outside of daylight savings
247 * time). In this case, the different value of @a type would result in a
248 * different interval being returned.
249 *
250 * It is still possible for this function to fail. In Toronto, for
251 * example, 02:00 on March 14th 2010 does not exist (due to the leap
252 * forward to begin daylight savings time). -1 is returned in that
253 * case.
254 *
255 * @newin{2,26}
256 *
257 * @param type The TimeType of @a time.
258 * @param time A number of seconds since January 1, 1970.
259 * @return The interval containing @a time, or -1 in case of failure.
260 */
261 int find_interval(TimeType type, gint64 time) const;
262
263 /** Finds an interval within @a tz that corresponds to the given @a time,
264 * possibly adjusting @a time if required to fit into an interval.
265 * The meaning of @a time depends on @a type.
266 *
267 * This function is similar to g_time_zone_find_interval(), with the
268 * difference that it always succeeds (by making the adjustments
269 * described below).
270 *
271 * In any of the cases where g_time_zone_find_interval() succeeds then
272 * this function returns the same value, without modifying @a time.
273 *
274 * This function may, however, modify @a time in order to deal with
275 * non-existent times. If the non-existent local @a time of 02:30 were
276 * requested on March 14th 2010 in Toronto then this function would
277 * adjust @a time to be 03:00 and return the interval containing the
278 * adjusted time.
279 *
280 * @newin{2,26}
281 *
282 * @param type The TimeType of @a time.
283 * @param time A pointer to a number of seconds since January 1, 1970.
284 * @return The interval containing @a time, never -1.
285 */
286 int adjust_time(TimeType type, gint64& time) const;
287
288 /** Determines the time zone abbreviation to be used during a particular
289 * @a interval of time in the time zone @a tz.
290 *
291 * For example, in Toronto this is currently "EST" during the winter
292 * months and "EDT" during the summer months when daylight savings time
293 * is in effect.
294 *
295 * @newin{2,26}
296 *
297 * @param interval An interval within the timezone.
298 * @return The time zone abbreviation, which belongs to @a tz.
299 */
300 Glib::ustring get_abbreviation(int interval) const;
301
302 /** Determines the offset to UTC in effect during a particular @a interval
303 * of time in the time zone @a tz.
304 *
305 * The offset is the number of seconds that you add to UTC time to
306 * arrive at local time for @a tz (ie: negative numbers for time zones
307 * west of GMT, positive numbers for east).
308 *
309 * @newin{2,26}
310 *
311 * @param interval An interval within the timezone.
312 * @return The number of seconds that should be added to UTC to get the
313 * local time in @a tz.
314 */
315 gint32 get_offset(int interval) const;
316
317 /** Determines if daylight savings time is in effect during a particular
318 * @a interval of time in the time zone @a tz.
319 *
320 * @newin{2,26}
321 *
322 * @param interval An interval within the timezone.
323 * @return <tt>true</tt> if daylight savings time is in effect.
324 */
325 bool is_dst(int interval) const;
326
327 /** Get the identifier of this TimeZone, as passed to g_time_zone_new().
328 * If the identifier passed at construction time was not recognised, `UTC` will
329 * be returned. If it was <tt>nullptr</tt>, the identifier of the local timezone at
330 * construction time will be returned.
331 *
332 * The identifier will be returned in the same format as provided at
333 * construction time: if provided as a time offset, that will be returned by
334 * this function.
335 *
336 * @newin{2,60}
337 *
338 * @return Identifier for this timezone.
339 */
340 Glib::ustring get_identifier() const;
341
342
343 };
344
345 #ifndef DOXYGEN_SHOULD_SKIP_THIS
346 // This is needed so Glib::TimeZone can be used with Glib::Value and _WRAP_PROPERTY.
347 template <>
348 class Value<Glib::TimeZone> : public ValueBase_Boxed
349 {
350 public:
351 using CppType = Glib::TimeZone;
352 using CType = GTimeZone*;
353
354 static GType value_type();
355
356 void set(const CppType& data);
357 CppType get() const;
358 };
359 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
360
361 } // namespace Glib
362
363
364 namespace Glib
365 {
366
367 /** @relates Glib::TimeZone
368 * @param lhs The left-hand side
369 * @param rhs The right-hand side
370 */
swap(TimeZone & lhs,TimeZone & rhs)371 inline void swap(TimeZone& lhs, TimeZone& rhs) noexcept
372 { lhs.swap(rhs); }
373
374 } // namespace Glib
375
376 namespace Glib
377 {
378
379 /** A Glib::wrap() method for this object.
380 *
381 * @param object The C instance.
382 * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
383 * @result A C++ instance that wraps this C instance.
384 *
385 * @relates Glib::TimeZone
386 */
387 GLIBMM_API
388 Glib::TimeZone wrap(GTimeZone* object, bool take_copy = false);
389
390 } // namespace Glib
391
392
393 #endif /* _GLIBMM_TIMEZONE_H */
394
395