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.DateTime;
26 
27 private import glib.ConstructionException;
28 private import glib.Str;
29 private import glib.TimeVal;
30 private import glib.TimeZone;
31 private import glib.c.functions;
32 public  import glib.c.types;
33 public  import gtkc.glibtypes;
34 private import gtkd.Loader;
35 
36 
37 /**
38  * `GDateTime` is an opaque structure whose members
39  * cannot be accessed directly.
40  *
41  * Since: 2.26
42  */
43 public class DateTime
44 {
45 	/** the main Gtk struct */
46 	protected GDateTime* gDateTime;
47 	protected bool ownedRef;
48 
49 	/** Get the main Gtk struct */
50 	public GDateTime* getDateTimeStruct(bool transferOwnership = false)
51 	{
52 		if (transferOwnership)
53 			ownedRef = false;
54 		return gDateTime;
55 	}
56 
57 	/** the main Gtk struct as a void* */
58 	protected void* getStruct()
59 	{
60 		return cast(void*)gDateTime;
61 	}
62 
63 	/**
64 	 * Sets our main struct and passes it to the parent class.
65 	 */
66 	public this (GDateTime* gDateTime, bool ownedRef = false)
67 	{
68 		this.gDateTime = gDateTime;
69 		this.ownedRef = ownedRef;
70 	}
71 
72 	~this ()
73 	{
74 		if ( Linker.isLoaded(LIBRARY_GLIB) && ownedRef )
75 			g_date_time_unref(gDateTime);
76 	}
77 
78 	/**
79 	 * Creates a DateTime corresponding to the given Unix time t
80 	 * Unix time is the number of seconds that have elapsed since 1970-01-01
81 	 * 00:00:00 UTC, regardless of the local time offset.
82 	 *
83 	 * This call can fail (ConstructionException) if t represents a time outside
84 	 * of the supported range of GDateTime.
85 	 * You should release the return value by calling unref()
86 	 * when you are done with it
87 	 *
88 	 * Params:
89 	 *     t   = the Unix time
90 	 *     utc = If true use utc else use the local timezone.
91 	 *
92 	 * Throws: ConstructionException GTK+ fails to create the object.
93 	 *
94 	 * Since: 2.26
95 	 */
96 	public this (long t, bool utc = true)
97 	{
98 		GDateTime* p;
99 
100 		if ( utc )
101 		{
102 			p = g_date_time_new_from_unix_utc(t);
103 		}
104 		else
105 		{
106 			p = g_date_time_new_from_unix_local(t);
107 		}
108 
109 		if(p is null)
110 		{
111 			throw new ConstructionException("null returned by g_date_time_new_from_unix_local(t)");
112 		}
113 		this(cast(GDateTime*) p);
114 	}
115 
116 	/**
117 	 * Creates a DateTime corresponding to the given TimeVal tv.
118 	 * The time contained in a TimeVal is always stored in the form of
119 	 * seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the
120 	 * local time offset.
121 	 *
122 	 * This call can fail (ConstructionException) if tv represents a time outside
123 	 * of the supported range of DateTime.
124 	 * You should release the return value by calling unref()
125 	 * when you are done with it.
126 	 *
127 	 * Params:
128 	 *     tv  = a GTimeVal
129 	 *     utc = If true use utc else use the local timezone.
130 	 *
131 	 * Throws: ConstructionException GTK+ fails to create the object.
132 	 *
133 	 * Since: 2.26
134 	 */
135 	public this (ref GTimeVal tv, bool utc = true)
136 	{
137 		GDateTime* p;
138 
139 		if ( utc )
140 		{
141 			p = g_date_time_new_from_timeval_utc(&tv);
142 		}
143 		else
144 		{
145 			p = g_date_time_new_from_timeval_local(&tv);
146 		}
147 
148 		if(p is null)
149 		{
150 			throw new ConstructionException("null returned by g_date_time_new_from_timeval_local((tv is null) ? null : tv.getTimeValStruct())");
151 		}
152 		this(cast(GDateTime*) p);
153 	}
154 
155 	/** */
156 	override bool opEquals(Object rhs)
157 	{
158 		DateTime date = cast(DateTime)rhs;
159 
160 		if ( date is null )
161 			return false;
162 
163 		return equal(this, date) != 0;
164 	}
165 
166 	/** */
167 	override int opCmp(Object rhs)
168 	{
169 		DateTime date = cast(DateTime)rhs;
170 
171 		if ( date is null )
172 			return int.min;
173 
174 		return compare(this, date);
175 	}
176 
177 	/** */
178 	override nothrow @trusted hash_t toHash()
179 	{
180 		return hash();
181 	}
182 
183 	/**
184 	 * Hashes datetime into a guint, suitable for use within GHashTable.
185 	 * Since 2.26
186 	 * Params:
187 	 * datetime = a GDateTime
188 	 * Returns: a guint containing the hash
189 	 */
190 	public nothrow @trusted uint hash()
191 	{
192 		try
193 		{
194 			return g_date_time_hash(gDateTime);
195 		}
196 		catch(Exception e)
197 		{
198 			return 0;
199 		}
200 	}
201 
202 	/**
203 	 */
204 
205 	/**
206 	 * Creates a new #GDateTime corresponding to the given date and time in
207 	 * the time zone @tz.
208 	 *
209 	 * The @year must be between 1 and 9999, @month between 1 and 12 and @day
210 	 * between 1 and 28, 29, 30 or 31 depending on the month and the year.
211 	 *
212 	 * @hour must be between 0 and 23 and @minute must be between 0 and 59.
213 	 *
214 	 * @seconds must be at least 0.0 and must be strictly less than 60.0.
215 	 * It will be rounded down to the nearest microsecond.
216 	 *
217 	 * If the given time is not representable in the given time zone (for
218 	 * example, 02:30 on March 14th 2010 in Toronto, due to daylight savings
219 	 * time) then the time will be rounded up to the nearest existing time
220 	 * (in this case, 03:00).  If this matters to you then you should verify
221 	 * the return value for containing the same as the numbers you gave.
222 	 *
223 	 * In the case that the given time is ambiguous in the given time zone
224 	 * (for example, 01:30 on November 7th 2010 in Toronto, due to daylight
225 	 * savings time) then the time falling within standard (ie:
226 	 * non-daylight) time is taken.
227 	 *
228 	 * It not considered a programmer error for the values to this function
229 	 * to be out of range, but in the case that they are, the function will
230 	 * return %NULL.
231 	 *
232 	 * You should release the return value by calling g_date_time_unref()
233 	 * when you are done with it.
234 	 *
235 	 * Params:
236 	 *     tz = a #GTimeZone
237 	 *     year = the year component of the date
238 	 *     month = the month component of the date
239 	 *     day = the day component of the date
240 	 *     hour = the hour component of the date
241 	 *     minute = the minute component of the date
242 	 *     seconds = the number of seconds past the minute
243 	 *
244 	 * Returns: a new #GDateTime, or %NULL
245 	 *
246 	 * Since: 2.26
247 	 *
248 	 * Throws: ConstructionException GTK+ fails to create the object.
249 	 */
250 	public this(TimeZone tz, int year, int month, int day, int hour, int minute, double seconds)
251 	{
252 		auto p = g_date_time_new((tz is null) ? null : tz.getTimeZoneStruct(), year, month, day, hour, minute, seconds);
253 
254 		if(p is null)
255 		{
256 			throw new ConstructionException("null returned by new");
257 		}
258 
259 		this(cast(GDateTime*) p);
260 	}
261 
262 	/**
263 	 * Creates a #GDateTime corresponding to the given
264 	 * [ISO 8601 formatted string](https://en.wikipedia.org/wiki/ISO_8601)
265 	 * @text. ISO 8601 strings of the form <date><sep><time><tz> are supported.
266 	 *
267 	 * <sep> is the separator and can be either 'T', 't' or ' '.
268 	 *
269 	 * <date> is in the form:
270 	 *
271 	 * - `YYYY-MM-DD` - Year/month/day, e.g. 2016-08-24.
272 	 * - `YYYYMMDD` - Same as above without dividers.
273 	 * - `YYYY-DDD` - Ordinal day where DDD is from 001 to 366, e.g. 2016-237.
274 	 * - `YYYYDDD` - Same as above without dividers.
275 	 * - `YYYY-Www-D` - Week day where ww is from 01 to 52 and D from 1-7,
276 	 * e.g. 2016-W34-3.
277 	 * - `YYYYWwwD` - Same as above without dividers.
278 	 *
279 	 * <time> is in the form:
280 	 *
281 	 * - `hh:mm:ss(.sss)` - Hours, minutes, seconds (subseconds), e.g. 22:10:42.123.
282 	 * - `hhmmss(.sss)` - Same as above without dividers.
283 	 *
284 	 * <tz> is an optional timezone suffix of the form:
285 	 *
286 	 * - `Z` - UTC.
287 	 * - `+hh:mm` or `-hh:mm` - Offset from UTC in hours and minutes, e.g. +12:00.
288 	 * - `+hh` or `-hh` - Offset from UTC in hours, e.g. +12.
289 	 *
290 	 * If the timezone is not provided in @text it must be provided in @default_tz
291 	 * (this field is otherwise ignored).
292 	 *
293 	 * This call can fail (returning %NULL) if @text is not a valid ISO 8601
294 	 * formatted string.
295 	 *
296 	 * You should release the return value by calling g_date_time_unref()
297 	 * when you are done with it.
298 	 *
299 	 * Params:
300 	 *     text = an ISO 8601 formatted time string.
301 	 *     defaultTz = a #GTimeZone to use if the text doesn't contain a
302 	 *         timezone, or %NULL.
303 	 *
304 	 * Returns: a new #GDateTime, or %NULL
305 	 *
306 	 * Since: 2.56
307 	 *
308 	 * Throws: ConstructionException GTK+ fails to create the object.
309 	 */
310 	public this(string text, TimeZone defaultTz)
311 	{
312 		auto p = g_date_time_new_from_iso8601(Str.toStringz(text), (defaultTz is null) ? null : defaultTz.getTimeZoneStruct());
313 
314 		if(p is null)
315 		{
316 			throw new ConstructionException("null returned by new_from_iso8601");
317 		}
318 
319 		this(cast(GDateTime*) p);
320 	}
321 
322 	/**
323 	 * Creates a #GDateTime corresponding to this exact instant in the given
324 	 * time zone @tz.  The time is as accurate as the system allows, to a
325 	 * maximum accuracy of 1 microsecond.
326 	 *
327 	 * This function will always succeed unless the system clock is set to
328 	 * truly insane values (or unless GLib is still being used after the
329 	 * year 9999).
330 	 *
331 	 * You should release the return value by calling g_date_time_unref()
332 	 * when you are done with it.
333 	 *
334 	 * Params:
335 	 *     tz = a #GTimeZone
336 	 *
337 	 * Returns: a new #GDateTime, or %NULL
338 	 *
339 	 * Since: 2.26
340 	 *
341 	 * Throws: ConstructionException GTK+ fails to create the object.
342 	 */
343 	public this(TimeZone tz)
344 	{
345 		auto p = g_date_time_new_now((tz is null) ? null : tz.getTimeZoneStruct());
346 
347 		if(p is null)
348 		{
349 			throw new ConstructionException("null returned by new_now");
350 		}
351 
352 		this(cast(GDateTime*) p);
353 	}
354 
355 	/**
356 	 * Creates a copy of @datetime and adds the specified timespan to the copy.
357 	 *
358 	 * Params:
359 	 *     timespan = a #GTimeSpan
360 	 *
361 	 * Returns: the newly created #GDateTime which should be freed with
362 	 *     g_date_time_unref().
363 	 *
364 	 * Since: 2.26
365 	 */
366 	public DateTime add(GTimeSpan timespan)
367 	{
368 		auto p = g_date_time_add(gDateTime, timespan);
369 
370 		if(p is null)
371 		{
372 			return null;
373 		}
374 
375 		return new DateTime(cast(GDateTime*) p, true);
376 	}
377 
378 	/**
379 	 * Creates a copy of @datetime and adds the specified number of days to the
380 	 * copy. Add negative values to subtract days.
381 	 *
382 	 * Params:
383 	 *     days = the number of days
384 	 *
385 	 * Returns: the newly created #GDateTime which should be freed with
386 	 *     g_date_time_unref().
387 	 *
388 	 * Since: 2.26
389 	 */
390 	public DateTime addDays(int days)
391 	{
392 		auto p = g_date_time_add_days(gDateTime, days);
393 
394 		if(p is null)
395 		{
396 			return null;
397 		}
398 
399 		return new DateTime(cast(GDateTime*) p, true);
400 	}
401 
402 	/**
403 	 * Creates a new #GDateTime adding the specified values to the current date and
404 	 * time in @datetime. Add negative values to subtract.
405 	 *
406 	 * Params:
407 	 *     years = the number of years to add
408 	 *     months = the number of months to add
409 	 *     days = the number of days to add
410 	 *     hours = the number of hours to add
411 	 *     minutes = the number of minutes to add
412 	 *     seconds = the number of seconds to add
413 	 *
414 	 * Returns: the newly created #GDateTime that should be freed with
415 	 *     g_date_time_unref().
416 	 *
417 	 * Since: 2.26
418 	 */
419 	public DateTime addFull(int years, int months, int days, int hours, int minutes, double seconds)
420 	{
421 		auto p = g_date_time_add_full(gDateTime, years, months, days, hours, minutes, seconds);
422 
423 		if(p is null)
424 		{
425 			return null;
426 		}
427 
428 		return new DateTime(cast(GDateTime*) p, true);
429 	}
430 
431 	/**
432 	 * Creates a copy of @datetime and adds the specified number of hours.
433 	 * Add negative values to subtract hours.
434 	 *
435 	 * Params:
436 	 *     hours = the number of hours to add
437 	 *
438 	 * Returns: the newly created #GDateTime which should be freed with
439 	 *     g_date_time_unref().
440 	 *
441 	 * Since: 2.26
442 	 */
443 	public DateTime addHours(int hours)
444 	{
445 		auto p = g_date_time_add_hours(gDateTime, hours);
446 
447 		if(p is null)
448 		{
449 			return null;
450 		}
451 
452 		return new DateTime(cast(GDateTime*) p, true);
453 	}
454 
455 	/**
456 	 * Creates a copy of @datetime adding the specified number of minutes.
457 	 * Add negative values to subtract minutes.
458 	 *
459 	 * Params:
460 	 *     minutes = the number of minutes to add
461 	 *
462 	 * Returns: the newly created #GDateTime which should be freed with
463 	 *     g_date_time_unref().
464 	 *
465 	 * Since: 2.26
466 	 */
467 	public DateTime addMinutes(int minutes)
468 	{
469 		auto p = g_date_time_add_minutes(gDateTime, minutes);
470 
471 		if(p is null)
472 		{
473 			return null;
474 		}
475 
476 		return new DateTime(cast(GDateTime*) p, true);
477 	}
478 
479 	/**
480 	 * Creates a copy of @datetime and adds the specified number of months to the
481 	 * copy. Add negative values to subtract months.
482 	 *
483 	 * The day of the month of the resulting #GDateTime is clamped to the number
484 	 * of days in the updated calendar month. For example, if adding 1 month to
485 	 * 31st January 2018, the result would be 28th February 2018. In 2020 (a leap
486 	 * year), the result would be 29th February.
487 	 *
488 	 * Params:
489 	 *     months = the number of months
490 	 *
491 	 * Returns: the newly created #GDateTime which should be freed with
492 	 *     g_date_time_unref().
493 	 *
494 	 * Since: 2.26
495 	 */
496 	public DateTime addMonths(int months)
497 	{
498 		auto p = g_date_time_add_months(gDateTime, months);
499 
500 		if(p is null)
501 		{
502 			return null;
503 		}
504 
505 		return new DateTime(cast(GDateTime*) p, true);
506 	}
507 
508 	/**
509 	 * Creates a copy of @datetime and adds the specified number of seconds.
510 	 * Add negative values to subtract seconds.
511 	 *
512 	 * Params:
513 	 *     seconds = the number of seconds to add
514 	 *
515 	 * Returns: the newly created #GDateTime which should be freed with
516 	 *     g_date_time_unref().
517 	 *
518 	 * Since: 2.26
519 	 */
520 	public DateTime addSeconds(double seconds)
521 	{
522 		auto p = g_date_time_add_seconds(gDateTime, seconds);
523 
524 		if(p is null)
525 		{
526 			return null;
527 		}
528 
529 		return new DateTime(cast(GDateTime*) p, true);
530 	}
531 
532 	/**
533 	 * Creates a copy of @datetime and adds the specified number of weeks to the
534 	 * copy. Add negative values to subtract weeks.
535 	 *
536 	 * Params:
537 	 *     weeks = the number of weeks
538 	 *
539 	 * Returns: the newly created #GDateTime which should be freed with
540 	 *     g_date_time_unref().
541 	 *
542 	 * Since: 2.26
543 	 */
544 	public DateTime addWeeks(int weeks)
545 	{
546 		auto p = g_date_time_add_weeks(gDateTime, weeks);
547 
548 		if(p is null)
549 		{
550 			return null;
551 		}
552 
553 		return new DateTime(cast(GDateTime*) p, true);
554 	}
555 
556 	/**
557 	 * Creates a copy of @datetime and adds the specified number of years to the
558 	 * copy. Add negative values to subtract years.
559 	 *
560 	 * As with g_date_time_add_months(), if the resulting date would be 29th
561 	 * February on a non-leap year, the day will be clamped to 28th February.
562 	 *
563 	 * Params:
564 	 *     years = the number of years
565 	 *
566 	 * Returns: the newly created #GDateTime which should be freed with
567 	 *     g_date_time_unref().
568 	 *
569 	 * Since: 2.26
570 	 */
571 	public DateTime addYears(int years)
572 	{
573 		auto p = g_date_time_add_years(gDateTime, years);
574 
575 		if(p is null)
576 		{
577 			return null;
578 		}
579 
580 		return new DateTime(cast(GDateTime*) p, true);
581 	}
582 
583 	/**
584 	 * Calculates the difference in time between @end and @begin.  The
585 	 * #GTimeSpan that is returned is effectively @end - @begin (ie:
586 	 * positive if the first parameter is larger).
587 	 *
588 	 * Params:
589 	 *     begin = a #GDateTime
590 	 *
591 	 * Returns: the difference between the two #GDateTime, as a time
592 	 *     span expressed in microseconds.
593 	 *
594 	 * Since: 2.26
595 	 */
596 	public GTimeSpan difference(DateTime begin)
597 	{
598 		return g_date_time_difference(gDateTime, (begin is null) ? null : begin.getDateTimeStruct());
599 	}
600 
601 	/**
602 	 * Creates a newly allocated string representing the requested @format.
603 	 *
604 	 * The format strings understood by this function are a subset of the
605 	 * strftime() format language as specified by C99.  The \%D, \%U and \%W
606 	 * conversions are not supported, nor is the 'E' modifier.  The GNU
607 	 * extensions \%k, \%l, \%s and \%P are supported, however, as are the
608 	 * '0', '_' and '-' modifiers.
609 	 *
610 	 * In contrast to strftime(), this function always produces a UTF-8
611 	 * string, regardless of the current locale.  Note that the rendering of
612 	 * many formats is locale-dependent and may not match the strftime()
613 	 * output exactly.
614 	 *
615 	 * The following format specifiers are supported:
616 	 *
617 	 * - \%a: the abbreviated weekday name according to the current locale
618 	 * - \%A: the full weekday name according to the current locale
619 	 * - \%b: the abbreviated month name according to the current locale
620 	 * - \%B: the full month name according to the current locale
621 	 * - \%c: the preferred date and time representation for the current locale
622 	 * - \%C: the century number (year/100) as a 2-digit integer (00-99)
623 	 * - \%d: the day of the month as a decimal number (range 01 to 31)
624 	 * - \%e: the day of the month as a decimal number (range  1 to 31)
625 	 * - \%F: equivalent to `%Y-%m-%d` (the ISO 8601 date format)
626 	 * - \%g: the last two digits of the ISO 8601 week-based year as a
627 	 * decimal number (00-99). This works well with \%V and \%u.
628 	 * - \%G: the ISO 8601 week-based year as a decimal number. This works
629 	 * well with \%V and \%u.
630 	 * - \%h: equivalent to \%b
631 	 * - \%H: the hour as a decimal number using a 24-hour clock (range 00 to 23)
632 	 * - \%I: the hour as a decimal number using a 12-hour clock (range 01 to 12)
633 	 * - \%j: the day of the year as a decimal number (range 001 to 366)
634 	 * - \%k: the hour (24-hour clock) as a decimal number (range 0 to 23);
635 	 * single digits are preceded by a blank
636 	 * - \%l: the hour (12-hour clock) as a decimal number (range 1 to 12);
637 	 * single digits are preceded by a blank
638 	 * - \%m: the month as a decimal number (range 01 to 12)
639 	 * - \%M: the minute as a decimal number (range 00 to 59)
640 	 * - \%p: either "AM" or "PM" according to the given time value, or the
641 	 * corresponding  strings for the current locale.  Noon is treated as
642 	 * "PM" and midnight as "AM".
643 	 * - \%P: like \%p but lowercase: "am" or "pm" or a corresponding string for
644 	 * the current locale
645 	 * - \%r: the time in a.m. or p.m. notation
646 	 * - \%R: the time in 24-hour notation (\%H:\%M)
647 	 * - \%s: the number of seconds since the Epoch, that is, since 1970-01-01
648 	 * 00:00:00 UTC
649 	 * - \%S: the second as a decimal number (range 00 to 60)
650 	 * - \%t: a tab character
651 	 * - \%T: the time in 24-hour notation with seconds (\%H:\%M:\%S)
652 	 * - \%u: the ISO 8601 standard day of the week as a decimal, range 1 to 7,
653 	 * Monday being 1. This works well with \%G and \%V.
654 	 * - \%V: the ISO 8601 standard week number of the current year as a decimal
655 	 * number, range 01 to 53, where week 1 is the first week that has at
656 	 * least 4 days in the new year. See g_date_time_get_week_of_year().
657 	 * This works well with \%G and \%u.
658 	 * - \%w: the day of the week as a decimal, range 0 to 6, Sunday being 0.
659 	 * This is not the ISO 8601 standard format -- use \%u instead.
660 	 * - \%x: the preferred date representation for the current locale without
661 	 * the time
662 	 * - \%X: the preferred time representation for the current locale without
663 	 * the date
664 	 * - \%y: the year as a decimal number without the century
665 	 * - \%Y: the year as a decimal number including the century
666 	 * - \%z: the time zone as an offset from UTC (+hhmm)
667 	 * - \%:z: the time zone as an offset from UTC (+hh:mm).
668 	 * This is a gnulib strftime() extension. Since: 2.38
669 	 * - \%::z: the time zone as an offset from UTC (+hh:mm:ss). This is a
670 	 * gnulib strftime() extension. Since: 2.38
671 	 * - \%:::z: the time zone as an offset from UTC, with : to necessary
672 	 * precision (e.g., -04, +05:30). This is a gnulib strftime() extension. Since: 2.38
673 	 * - \%Z: the time zone or name or abbreviation
674 	 * - \%\%: a literal \% character
675 	 *
676 	 * Some conversion specifications can be modified by preceding the
677 	 * conversion specifier by one or more modifier characters. The
678 	 * following modifiers are supported for many of the numeric
679 	 * conversions:
680 	 *
681 	 * - O: Use alternative numeric symbols, if the current locale supports those.
682 	 * - _: Pad a numeric result with spaces. This overrides the default padding
683 	 * for the specifier.
684 	 * - -: Do not pad a numeric result. This overrides the default padding
685 	 * for the specifier.
686 	 * - 0: Pad a numeric result with zeros. This overrides the default padding
687 	 * for the specifier.
688 	 *
689 	 * Additionally, when O is used with B, b, or h, it produces the alternative
690 	 * form of a month name. The alternative form should be used when the month
691 	 * name is used without a day number (e.g., standalone). It is required in
692 	 * some languages (Baltic, Slavic, Greek, and more) due to their grammatical
693 	 * rules. For other languages there is no difference. \%OB is a GNU and BSD
694 	 * strftime() extension expected to be added to the future POSIX specification,
695 	 * \%Ob and \%Oh are GNU strftime() extensions. Since: 2.56
696 	 *
697 	 * Params:
698 	 *     format = a valid UTF-8 string, containing the format for the
699 	 *         #GDateTime
700 	 *
701 	 * Returns: a newly allocated string formatted to the requested format
702 	 *     or %NULL in the case that there was an error (such as a format specifier
703 	 *     not being supported in the current locale). The string
704 	 *     should be freed with g_free().
705 	 *
706 	 * Since: 2.26
707 	 */
708 	public string format(string format)
709 	{
710 		auto retStr = g_date_time_format(gDateTime, Str.toStringz(format));
711 
712 		scope(exit) Str.freeString(retStr);
713 		return Str.toString(retStr);
714 	}
715 
716 	/**
717 	 * Retrieves the day of the month represented by @datetime in the gregorian
718 	 * calendar.
719 	 *
720 	 * Returns: the day of the month
721 	 *
722 	 * Since: 2.26
723 	 */
724 	public int getDayOfMonth()
725 	{
726 		return g_date_time_get_day_of_month(gDateTime);
727 	}
728 
729 	/**
730 	 * Retrieves the ISO 8601 day of the week on which @datetime falls (1 is
731 	 * Monday, 2 is Tuesday... 7 is Sunday).
732 	 *
733 	 * Returns: the day of the week
734 	 *
735 	 * Since: 2.26
736 	 */
737 	public int getDayOfWeek()
738 	{
739 		return g_date_time_get_day_of_week(gDateTime);
740 	}
741 
742 	/**
743 	 * Retrieves the day of the year represented by @datetime in the Gregorian
744 	 * calendar.
745 	 *
746 	 * Returns: the day of the year
747 	 *
748 	 * Since: 2.26
749 	 */
750 	public int getDayOfYear()
751 	{
752 		return g_date_time_get_day_of_year(gDateTime);
753 	}
754 
755 	/**
756 	 * Retrieves the hour of the day represented by @datetime
757 	 *
758 	 * Returns: the hour of the day
759 	 *
760 	 * Since: 2.26
761 	 */
762 	public int getHour()
763 	{
764 		return g_date_time_get_hour(gDateTime);
765 	}
766 
767 	/**
768 	 * Retrieves the microsecond of the date represented by @datetime
769 	 *
770 	 * Returns: the microsecond of the second
771 	 *
772 	 * Since: 2.26
773 	 */
774 	public int getMicrosecond()
775 	{
776 		return g_date_time_get_microsecond(gDateTime);
777 	}
778 
779 	/**
780 	 * Retrieves the minute of the hour represented by @datetime
781 	 *
782 	 * Returns: the minute of the hour
783 	 *
784 	 * Since: 2.26
785 	 */
786 	public int getMinute()
787 	{
788 		return g_date_time_get_minute(gDateTime);
789 	}
790 
791 	/**
792 	 * Retrieves the month of the year represented by @datetime in the Gregorian
793 	 * calendar.
794 	 *
795 	 * Returns: the month represented by @datetime
796 	 *
797 	 * Since: 2.26
798 	 */
799 	public int getMonth()
800 	{
801 		return g_date_time_get_month(gDateTime);
802 	}
803 
804 	/**
805 	 * Retrieves the second of the minute represented by @datetime
806 	 *
807 	 * Returns: the second represented by @datetime
808 	 *
809 	 * Since: 2.26
810 	 */
811 	public int getSecond()
812 	{
813 		return g_date_time_get_second(gDateTime);
814 	}
815 
816 	/**
817 	 * Retrieves the number of seconds since the start of the last minute,
818 	 * including the fractional part.
819 	 *
820 	 * Returns: the number of seconds
821 	 *
822 	 * Since: 2.26
823 	 */
824 	public double getSeconds()
825 	{
826 		return g_date_time_get_seconds(gDateTime);
827 	}
828 
829 	/**
830 	 * Determines the time zone abbreviation to be used at the time and in
831 	 * the time zone of @datetime.
832 	 *
833 	 * For example, in Toronto this is currently "EST" during the winter
834 	 * months and "EDT" during the summer months when daylight savings
835 	 * time is in effect.
836 	 *
837 	 * Returns: the time zone abbreviation. The returned
838 	 *     string is owned by the #GDateTime and it should not be
839 	 *     modified or freed
840 	 *
841 	 * Since: 2.26
842 	 */
843 	public string getTimezoneAbbreviation()
844 	{
845 		return Str.toString(g_date_time_get_timezone_abbreviation(gDateTime));
846 	}
847 
848 	/**
849 	 * Determines the offset to UTC in effect at the time and in the time
850 	 * zone of @datetime.
851 	 *
852 	 * The offset is the number of microseconds that you add to UTC time to
853 	 * arrive at local time for the time zone (ie: negative numbers for time
854 	 * zones west of GMT, positive numbers for east).
855 	 *
856 	 * If @datetime represents UTC time, then the offset is always zero.
857 	 *
858 	 * Returns: the number of microseconds that should be added to UTC to
859 	 *     get the local time
860 	 *
861 	 * Since: 2.26
862 	 */
863 	public GTimeSpan getUtcOffset()
864 	{
865 		return g_date_time_get_utc_offset(gDateTime);
866 	}
867 
868 	/**
869 	 * Returns the ISO 8601 week-numbering year in which the week containing
870 	 * @datetime falls.
871 	 *
872 	 * This function, taken together with g_date_time_get_week_of_year() and
873 	 * g_date_time_get_day_of_week() can be used to determine the full ISO
874 	 * week date on which @datetime falls.
875 	 *
876 	 * This is usually equal to the normal Gregorian year (as returned by
877 	 * g_date_time_get_year()), except as detailed below:
878 	 *
879 	 * For Thursday, the week-numbering year is always equal to the usual
880 	 * calendar year.  For other days, the number is such that every day
881 	 * within a complete week (Monday to Sunday) is contained within the
882 	 * same week-numbering year.
883 	 *
884 	 * For Monday, Tuesday and Wednesday occurring near the end of the year,
885 	 * this may mean that the week-numbering year is one greater than the
886 	 * calendar year (so that these days have the same week-numbering year
887 	 * as the Thursday occurring early in the next year).
888 	 *
889 	 * For Friday, Saturday and Sunday occurring near the start of the year,
890 	 * this may mean that the week-numbering year is one less than the
891 	 * calendar year (so that these days have the same week-numbering year
892 	 * as the Thursday occurring late in the previous year).
893 	 *
894 	 * An equivalent description is that the week-numbering year is equal to
895 	 * the calendar year containing the majority of the days in the current
896 	 * week (Monday to Sunday).
897 	 *
898 	 * Note that January 1 0001 in the proleptic Gregorian calendar is a
899 	 * Monday, so this function never returns 0.
900 	 *
901 	 * Returns: the ISO 8601 week-numbering year for @datetime
902 	 *
903 	 * Since: 2.26
904 	 */
905 	public int getWeekNumberingYear()
906 	{
907 		return g_date_time_get_week_numbering_year(gDateTime);
908 	}
909 
910 	/**
911 	 * Returns the ISO 8601 week number for the week containing @datetime.
912 	 * The ISO 8601 week number is the same for every day of the week (from
913 	 * Moday through Sunday).  That can produce some unusual results
914 	 * (described below).
915 	 *
916 	 * The first week of the year is week 1.  This is the week that contains
917 	 * the first Thursday of the year.  Equivalently, this is the first week
918 	 * that has more than 4 of its days falling within the calendar year.
919 	 *
920 	 * The value 0 is never returned by this function.  Days contained
921 	 * within a year but occurring before the first ISO 8601 week of that
922 	 * year are considered as being contained in the last week of the
923 	 * previous year.  Similarly, the final days of a calendar year may be
924 	 * considered as being part of the first ISO 8601 week of the next year
925 	 * if 4 or more days of that week are contained within the new year.
926 	 *
927 	 * Returns: the ISO 8601 week number for @datetime.
928 	 *
929 	 * Since: 2.26
930 	 */
931 	public int getWeekOfYear()
932 	{
933 		return g_date_time_get_week_of_year(gDateTime);
934 	}
935 
936 	/**
937 	 * Retrieves the year represented by @datetime in the Gregorian calendar.
938 	 *
939 	 * Returns: the year represented by @datetime
940 	 *
941 	 * Since: 2.26
942 	 */
943 	public int getYear()
944 	{
945 		return g_date_time_get_year(gDateTime);
946 	}
947 
948 	/**
949 	 * Retrieves the Gregorian day, month, and year of a given #GDateTime.
950 	 *
951 	 * Params:
952 	 *     year = the return location for the gregorian year, or %NULL.
953 	 *     month = the return location for the month of the year, or %NULL.
954 	 *     day = the return location for the day of the month, or %NULL.
955 	 *
956 	 * Since: 2.26
957 	 */
958 	public void getYmd(out int year, out int month, out int day)
959 	{
960 		g_date_time_get_ymd(gDateTime, &year, &month, &day);
961 	}
962 
963 	/**
964 	 * Determines if daylight savings time is in effect at the time and in
965 	 * the time zone of @datetime.
966 	 *
967 	 * Returns: %TRUE if daylight savings time is in effect
968 	 *
969 	 * Since: 2.26
970 	 */
971 	public bool isDaylightSavings()
972 	{
973 		return g_date_time_is_daylight_savings(gDateTime) != 0;
974 	}
975 
976 	/**
977 	 * Atomically increments the reference count of @datetime by one.
978 	 *
979 	 * Returns: the #GDateTime with the reference count increased
980 	 *
981 	 * Since: 2.26
982 	 */
983 	public DateTime doref()
984 	{
985 		auto p = g_date_time_ref(gDateTime);
986 
987 		if(p is null)
988 		{
989 			return null;
990 		}
991 
992 		return new DateTime(cast(GDateTime*) p, true);
993 	}
994 
995 	/**
996 	 * Creates a new #GDateTime corresponding to the same instant in time as
997 	 * @datetime, but in the local time zone.
998 	 *
999 	 * This call is equivalent to calling g_date_time_to_timezone() with the
1000 	 * time zone returned by g_time_zone_new_local().
1001 	 *
1002 	 * Returns: the newly created #GDateTime
1003 	 *
1004 	 * Since: 2.26
1005 	 */
1006 	public DateTime toLocal()
1007 	{
1008 		auto p = g_date_time_to_local(gDateTime);
1009 
1010 		if(p is null)
1011 		{
1012 			return null;
1013 		}
1014 
1015 		return new DateTime(cast(GDateTime*) p, true);
1016 	}
1017 
1018 	/**
1019 	 * Stores the instant in time that @datetime represents into @tv.
1020 	 *
1021 	 * The time contained in a #GTimeVal is always stored in the form of
1022 	 * seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the time
1023 	 * zone associated with @datetime.
1024 	 *
1025 	 * On systems where 'long' is 32bit (ie: all 32bit systems and all
1026 	 * Windows systems), a #GTimeVal is incapable of storing the entire
1027 	 * range of values that #GDateTime is capable of expressing.  On those
1028 	 * systems, this function returns %FALSE to indicate that the time is
1029 	 * out of range.
1030 	 *
1031 	 * On systems where 'long' is 64bit, this function never fails.
1032 	 *
1033 	 * Params:
1034 	 *     tv = a #GTimeVal to modify
1035 	 *
1036 	 * Returns: %TRUE if successful, else %FALSE
1037 	 *
1038 	 * Since: 2.26
1039 	 */
1040 	public bool toTimeval(TimeVal tv)
1041 	{
1042 		return g_date_time_to_timeval(gDateTime, (tv is null) ? null : tv.getTimeValStruct()) != 0;
1043 	}
1044 
1045 	/**
1046 	 * Create a new #GDateTime corresponding to the same instant in time as
1047 	 * @datetime, but in the time zone @tz.
1048 	 *
1049 	 * This call can fail in the case that the time goes out of bounds.  For
1050 	 * example, converting 0001-01-01 00:00:00 UTC to a time zone west of
1051 	 * Greenwich will fail (due to the year 0 being out of range).
1052 	 *
1053 	 * You should release the return value by calling g_date_time_unref()
1054 	 * when you are done with it.
1055 	 *
1056 	 * Params:
1057 	 *     tz = the new #GTimeZone
1058 	 *
1059 	 * Returns: a new #GDateTime, or %NULL
1060 	 *
1061 	 * Since: 2.26
1062 	 */
1063 	public DateTime toTimezone(TimeZone tz)
1064 	{
1065 		auto p = g_date_time_to_timezone(gDateTime, (tz is null) ? null : tz.getTimeZoneStruct());
1066 
1067 		if(p is null)
1068 		{
1069 			return null;
1070 		}
1071 
1072 		return new DateTime(cast(GDateTime*) p, true);
1073 	}
1074 
1075 	/**
1076 	 * Gives the Unix time corresponding to @datetime, rounding down to the
1077 	 * nearest second.
1078 	 *
1079 	 * Unix time is the number of seconds that have elapsed since 1970-01-01
1080 	 * 00:00:00 UTC, regardless of the time zone associated with @datetime.
1081 	 *
1082 	 * Returns: the Unix time corresponding to @datetime
1083 	 *
1084 	 * Since: 2.26
1085 	 */
1086 	public long toUnix()
1087 	{
1088 		return g_date_time_to_unix(gDateTime);
1089 	}
1090 
1091 	/**
1092 	 * Creates a new #GDateTime corresponding to the same instant in time as
1093 	 * @datetime, but in UTC.
1094 	 *
1095 	 * This call is equivalent to calling g_date_time_to_timezone() with the
1096 	 * time zone returned by g_time_zone_new_utc().
1097 	 *
1098 	 * Returns: the newly created #GDateTime
1099 	 *
1100 	 * Since: 2.26
1101 	 */
1102 	public DateTime toUtc()
1103 	{
1104 		auto p = g_date_time_to_utc(gDateTime);
1105 
1106 		if(p is null)
1107 		{
1108 			return null;
1109 		}
1110 
1111 		return new DateTime(cast(GDateTime*) p, true);
1112 	}
1113 
1114 	/**
1115 	 * Atomically decrements the reference count of @datetime by one.
1116 	 *
1117 	 * When the reference count reaches zero, the resources allocated by
1118 	 * @datetime are freed
1119 	 *
1120 	 * Since: 2.26
1121 	 */
1122 	public void unref()
1123 	{
1124 		g_date_time_unref(gDateTime);
1125 	}
1126 
1127 	/**
1128 	 * A comparison function for #GDateTimes that is suitable
1129 	 * as a #GCompareFunc. Both #GDateTimes must be non-%NULL.
1130 	 *
1131 	 * Params:
1132 	 *     dt1 = first #GDateTime to compare
1133 	 *     dt2 = second #GDateTime to compare
1134 	 *
1135 	 * Returns: -1, 0 or 1 if @dt1 is less than, equal to or greater
1136 	 *     than @dt2.
1137 	 *
1138 	 * Since: 2.26
1139 	 */
1140 	public static int compare(DateTime dt1, DateTime dt2)
1141 	{
1142 		return g_date_time_compare((dt1 is null) ? null : dt1.getDateTimeStruct(), (dt2 is null) ? null : dt2.getDateTimeStruct());
1143 	}
1144 
1145 	/**
1146 	 * Checks to see if @dt1 and @dt2 are equal.
1147 	 *
1148 	 * Equal here means that they represent the same moment after converting
1149 	 * them to the same time zone.
1150 	 *
1151 	 * Params:
1152 	 *     dt1 = a #GDateTime
1153 	 *     dt2 = a #GDateTime
1154 	 *
1155 	 * Returns: %TRUE if @dt1 and @dt2 are equal
1156 	 *
1157 	 * Since: 2.26
1158 	 */
1159 	public static bool equal(DateTime dt1, DateTime dt2)
1160 	{
1161 		return g_date_time_equal((dt1 is null) ? null : dt1.getDateTimeStruct(), (dt2 is null) ? null : dt2.getDateTimeStruct()) != 0;
1162 	}
1163 }