1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module glib.TimeZone;
26 
27 private import glib.ConstructionException;
28 private import glib.Str;
29 private import glib.c.functions;
30 public  import glib.c.types;
31 public  import gtkc.glibtypes;
32 private import gtkd.Loader;
33 
34 
35 /**
36  * #GTimeZone is an opaque structure whose members cannot be accessed
37  * directly.
38  *
39  * Since: 2.26
40  */
41 public class TimeZone
42 {
43 	/** the main Gtk struct */
44 	protected GTimeZone* gTimeZone;
45 	protected bool ownedRef;
46 
47 	/** Get the main Gtk struct */
48 	public GTimeZone* getTimeZoneStruct(bool transferOwnership = false)
49 	{
50 		if (transferOwnership)
51 			ownedRef = false;
52 		return gTimeZone;
53 	}
54 
55 	/** the main Gtk struct as a void* */
56 	protected void* getStruct()
57 	{
58 		return cast(void*)gTimeZone;
59 	}
60 
61 	/**
62 	 * Sets our main struct and passes it to the parent class.
63 	 */
64 	public this (GTimeZone* gTimeZone, bool ownedRef = false)
65 	{
66 		this.gTimeZone = gTimeZone;
67 		this.ownedRef = ownedRef;
68 	}
69 
70 	~this ()
71 	{
72 		if ( Linker.isLoaded(LIBRARY_GLIB) && ownedRef )
73 			g_time_zone_unref(gTimeZone);
74 	}
75 
76 
77 	/**
78 	 * Creates a #GTimeZone corresponding to @identifier.
79 	 *
80 	 * @identifier can either be an RFC3339/ISO 8601 time offset or
81 	 * something that would pass as a valid value for the `TZ` environment
82 	 * variable (including %NULL).
83 	 *
84 	 * In Windows, @identifier can also be the unlocalized name of a time
85 	 * zone for standard time, for example "Pacific Standard Time".
86 	 *
87 	 * Valid RFC3339 time offsets are `"Z"` (for UTC) or
88 	 * `"±hh:mm"`.  ISO 8601 additionally specifies
89 	 * `"±hhmm"` and `"±hh"`.  Offsets are
90 	 * time values to be added to Coordinated Universal Time (UTC) to get
91 	 * the local time.
92 	 *
93 	 * In UNIX, the `TZ` environment variable typically corresponds
94 	 * to the name of a file in the zoneinfo database, or string in
95 	 * "std offset [dst [offset],start[/time],end[/time]]" (POSIX) format.
96 	 * There  are  no spaces in the specification. The name of standard
97 	 * and daylight savings time zone must be three or more alphabetic
98 	 * characters. Offsets are time values to be added to local time to
99 	 * get Coordinated Universal Time (UTC) and should be
100 	 * `"[±]hh[[:]mm[:ss]]"`.  Dates are either
101 	 * `"Jn"` (Julian day with n between 1 and 365, leap
102 	 * years not counted), `"n"` (zero-based Julian day
103 	 * with n between 0 and 365) or `"Mm.w.d"` (day d
104 	 * (0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day
105 	 * 0 is a Sunday).  Times are in local wall clock time, the default is
106 	 * 02:00:00.
107 	 *
108 	 * In Windows, the "tzn[+|–]hh[:mm[:ss]][dzn]" format is used, but also
109 	 * accepts POSIX format.  The Windows format uses US rules for all time
110 	 * zones; daylight savings time is 60 minutes behind the standard time
111 	 * with date and time of change taken from Pacific Standard Time.
112 	 * Offsets are time values to be added to the local time to get
113 	 * Coordinated Universal Time (UTC).
114 	 *
115 	 * g_time_zone_new_local() calls this function with the value of the
116 	 * `TZ` environment variable. This function itself is independent of
117 	 * the value of `TZ`, but if @identifier is %NULL then `/etc/localtime`
118 	 * will be consulted to discover the correct time zone on UNIX and the
119 	 * registry will be consulted or GetTimeZoneInformation() will be used
120 	 * to get the local time zone on Windows.
121 	 *
122 	 * If intervals are not available, only time zone rules from `TZ`
123 	 * environment variable or other means, then they will be computed
124 	 * from year 1900 to 2037.  If the maximum year for the rules is
125 	 * available and it is greater than 2037, then it will followed
126 	 * instead.
127 	 *
128 	 * See
129 	 * [RFC3339 §5.6](http://tools.ietf.org/html/rfc3339#section-5.6)
130 	 * for a precise definition of valid RFC3339 time offsets
131 	 * (the `time-offset` expansion) and ISO 8601 for the
132 	 * full list of valid time offsets.  See
133 	 * [The GNU C Library manual](http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html)
134 	 * for an explanation of the possible
135 	 * values of the `TZ` environment variable. See
136 	 * [Microsoft Time Zone Index Values](http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx)
137 	 * for the list of time zones on Windows.
138 	 *
139 	 * You should release the return value by calling g_time_zone_unref()
140 	 * when you are done with it.
141 	 *
142 	 * Params:
143 	 *     identifier = a timezone identifier
144 	 *
145 	 * Returns: the requested timezone
146 	 *
147 	 * Since: 2.26
148 	 *
149 	 * Throws: ConstructionException GTK+ fails to create the object.
150 	 */
151 	public this(string identifier)
152 	{
153 		auto p = g_time_zone_new(Str.toStringz(identifier));
154 
155 		if(p is null)
156 		{
157 			throw new ConstructionException("null returned by new");
158 		}
159 
160 		this(cast(GTimeZone*) p);
161 	}
162 
163 	/**
164 	 * Finds an interval within @tz that corresponds to the given @time_,
165 	 * possibly adjusting @time_ if required to fit into an interval.
166 	 * The meaning of @time_ depends on @type.
167 	 *
168 	 * This function is similar to g_time_zone_find_interval(), with the
169 	 * difference that it always succeeds (by making the adjustments
170 	 * described below).
171 	 *
172 	 * In any of the cases where g_time_zone_find_interval() succeeds then
173 	 * this function returns the same value, without modifying @time_.
174 	 *
175 	 * This function may, however, modify @time_ in order to deal with
176 	 * non-existent times.  If the non-existent local @time_ of 02:30 were
177 	 * requested on March 14th 2010 in Toronto then this function would
178 	 * adjust @time_ to be 03:00 and return the interval containing the
179 	 * adjusted time.
180 	 *
181 	 * Params:
182 	 *     type = the #GTimeType of @time_
183 	 *     time = a pointer to a number of seconds since January 1, 1970
184 	 *
185 	 * Returns: the interval containing @time_, never -1
186 	 *
187 	 * Since: 2.26
188 	 */
189 	public int adjustTime(GTimeType type, long* time)
190 	{
191 		return g_time_zone_adjust_time(gTimeZone, type, time);
192 	}
193 
194 	/**
195 	 * Finds an the interval within @tz that corresponds to the given @time_.
196 	 * The meaning of @time_ depends on @type.
197 	 *
198 	 * If @type is %G_TIME_TYPE_UNIVERSAL then this function will always
199 	 * succeed (since universal time is monotonic and continuous).
200 	 *
201 	 * Otherwise @time_ is treated as local time.  The distinction between
202 	 * %G_TIME_TYPE_STANDARD and %G_TIME_TYPE_DAYLIGHT is ignored except in
203 	 * the case that the given @time_ is ambiguous.  In Toronto, for example,
204 	 * 01:30 on November 7th 2010 occurred twice (once inside of daylight
205 	 * savings time and the next, an hour later, outside of daylight savings
206 	 * time).  In this case, the different value of @type would result in a
207 	 * different interval being returned.
208 	 *
209 	 * It is still possible for this function to fail.  In Toronto, for
210 	 * example, 02:00 on March 14th 2010 does not exist (due to the leap
211 	 * forward to begin daylight savings time).  -1 is returned in that
212 	 * case.
213 	 *
214 	 * Params:
215 	 *     type = the #GTimeType of @time_
216 	 *     time = a number of seconds since January 1, 1970
217 	 *
218 	 * Returns: the interval containing @time_, or -1 in case of failure
219 	 *
220 	 * Since: 2.26
221 	 */
222 	public int findInterval(GTimeType type, long time)
223 	{
224 		return g_time_zone_find_interval(gTimeZone, type, time);
225 	}
226 
227 	/**
228 	 * Determines the time zone abbreviation to be used during a particular
229 	 * @interval of time in the time zone @tz.
230 	 *
231 	 * For example, in Toronto this is currently "EST" during the winter
232 	 * months and "EDT" during the summer months when daylight savings time
233 	 * is in effect.
234 	 *
235 	 * Params:
236 	 *     interval = an interval within the timezone
237 	 *
238 	 * Returns: the time zone abbreviation, which belongs to @tz
239 	 *
240 	 * Since: 2.26
241 	 */
242 	public string getAbbreviation(int interval)
243 	{
244 		return Str.toString(g_time_zone_get_abbreviation(gTimeZone, interval));
245 	}
246 
247 	/**
248 	 * Determines the offset to UTC in effect during a particular @interval
249 	 * of time in the time zone @tz.
250 	 *
251 	 * The offset is the number of seconds that you add to UTC time to
252 	 * arrive at local time for @tz (ie: negative numbers for time zones
253 	 * west of GMT, positive numbers for east).
254 	 *
255 	 * Params:
256 	 *     interval = an interval within the timezone
257 	 *
258 	 * Returns: the number of seconds that should be added to UTC to get the
259 	 *     local time in @tz
260 	 *
261 	 * Since: 2.26
262 	 */
263 	public int getOffset(int interval)
264 	{
265 		return g_time_zone_get_offset(gTimeZone, interval);
266 	}
267 
268 	/**
269 	 * Determines if daylight savings time is in effect during a particular
270 	 * @interval of time in the time zone @tz.
271 	 *
272 	 * Params:
273 	 *     interval = an interval within the timezone
274 	 *
275 	 * Returns: %TRUE if daylight savings time is in effect
276 	 *
277 	 * Since: 2.26
278 	 */
279 	public bool isDst(int interval)
280 	{
281 		return g_time_zone_is_dst(gTimeZone, interval) != 0;
282 	}
283 
284 	/**
285 	 * Increases the reference count on @tz.
286 	 *
287 	 * Returns: a new reference to @tz.
288 	 *
289 	 * Since: 2.26
290 	 */
291 	public TimeZone doref()
292 	{
293 		auto p = g_time_zone_ref(gTimeZone);
294 
295 		if(p is null)
296 		{
297 			return null;
298 		}
299 
300 		return new TimeZone(cast(GTimeZone*) p, true);
301 	}
302 
303 	/**
304 	 * Decreases the reference count on @tz.
305 	 *
306 	 * Since: 2.26
307 	 */
308 	public void unref()
309 	{
310 		g_time_zone_unref(gTimeZone);
311 	}
312 }