source: appstream-generator/build/girepo/glib/Date.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

File size: 19.5 KB
Line 
1/*
2 * Licensed under the GNU Lesser General Public License Version 3
3 *
4 * This library is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as published by
6 * the Free Software Foundation, either version 3 of the license, or
7 * (at your option) any later version.
8 *
9 * This software is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 * GNU Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public License
15 * along with this library.  If not, see <http://www.gnu.org/licenses/>.
16 */
17
18// generated automatically - do not change
19
20
21module glib.Date;
22
23private import gi.glib;
24public  import gi.glibtypes;
25private import glib.ConstructionException;
26private import glib.Str;
27private import glib.TimeVal;
28
29
30/**
31 * Represents a day between January 1, Year 1 and a few thousand years in
32 * the future. None of its members should be accessed directly.
33 *
34 * If the #GDate-struct is obtained from g_date_new(), it will be safe
35 * to mutate but invalid and thus not safe for calendrical computations.
36 *
37 * If it's declared on the stack, it will contain garbage so must be
38 * initialized with g_date_clear(). g_date_clear() makes the date invalid
39 * but sane. An invalid date doesn't represent a day, it's "empty." A date
40 * becomes valid after you set it to a Julian day or you set a day, month,
41 * and year.
42 */
43public class Date
44{
45        /** the main Gtk struct */
46        protected GDate* gDate;
47        protected bool ownedRef;
48
49        /** Get the main Gtk struct */
50        public GDate* getDateStruct()
51        {
52                return gDate;
53        }
54
55        /** the main Gtk struct as a void* */
56        protected void* getStruct()
57        {
58                return cast(void*)gDate;
59        }
60
61        /**
62         * Sets our main struct and passes it to the parent class.
63         */
64        public this (GDate* gDate, bool ownedRef = false)
65        {
66                this.gDate = gDate;
67                this.ownedRef = ownedRef;
68        }
69
70
71        /**
72         * Allocates a #GDate and initializes
73         * it to a sane state. The new date will
74         * be cleared (as if you'd called g_date_clear()) but invalid (it won't
75         * represent an existing day). Free the return value with g_date_free().
76         *
77         * Returns: a newly-allocated #GDate
78         *
79         * Throws: ConstructionException GTK+ fails to create the object.
80         */
81        public this()
82        {
83                auto p = g_date_new();
84               
85                if(p is null)
86                {
87                        throw new ConstructionException("null returned by new");
88                }
89               
90                this(cast(GDate*) p);
91        }
92
93        /**
94         * Like g_date_new(), but also sets the value of the date. Assuming the
95         * day-month-year triplet you pass in represents an existing day, the
96         * returned date will be valid.
97         *
98         * Params:
99         *     day = day of the month
100         *     month = month of the year
101         *     year = year
102         *
103         * Returns: a newly-allocated #GDate initialized with @day, @month, and @year
104         *
105         * Throws: ConstructionException GTK+ fails to create the object.
106         */
107        public this(GDateDay day, GDateMonth month, GDateYear year)
108        {
109                auto p = g_date_new_dmy(day, month, year);
110               
111                if(p is null)
112                {
113                        throw new ConstructionException("null returned by new_dmy");
114                }
115               
116                this(cast(GDate*) p);
117        }
118
119        /**
120         * Like g_date_new(), but also sets the value of the date. Assuming the
121         * Julian day number you pass in is valid (greater than 0, less than an
122         * unreasonably large number), the returned date will be valid.
123         *
124         * Params:
125         *     julianDay = days since January 1, Year 1
126         *
127         * Returns: a newly-allocated #GDate initialized with @julian_day
128         *
129         * Throws: ConstructionException GTK+ fails to create the object.
130         */
131        public this(uint julianDay)
132        {
133                auto p = g_date_new_julian(julianDay);
134               
135                if(p is null)
136                {
137                        throw new ConstructionException("null returned by new_julian");
138                }
139               
140                this(cast(GDate*) p);
141        }
142
143        /**
144         * Increments a date some number of days.
145         * To move forward by weeks, add weeks*7 days.
146         * The date must be valid.
147         *
148         * Params:
149         *     nDays = number of days to move the date forward
150         */
151        public void addDays(uint nDays)
152        {
153                g_date_add_days(gDate, nDays);
154        }
155
156        /**
157         * Increments a date by some number of months.
158         * If the day of the month is greater than 28,
159         * this routine may change the day of the month
160         * (because the destination month may not have
161         * the current day in it). The date must be valid.
162         *
163         * Params:
164         *     nMonths = number of months to move forward
165         */
166        public void addMonths(uint nMonths)
167        {
168                g_date_add_months(gDate, nMonths);
169        }
170
171        /**
172         * Increments a date by some number of years.
173         * If the date is February 29, and the destination
174         * year is not a leap year, the date will be changed
175         * to February 28. The date must be valid.
176         *
177         * Params:
178         *     nYears = number of years to move forward
179         */
180        public void addYears(uint nYears)
181        {
182                g_date_add_years(gDate, nYears);
183        }
184
185        /**
186         * If @date is prior to @min_date, sets @date equal to @min_date.
187         * If @date falls after @max_date, sets @date equal to @max_date.
188         * Otherwise, @date is unchanged.
189         * Either of @min_date and @max_date may be %NULL.
190         * All non-%NULL dates must be valid.
191         *
192         * Params:
193         *     minDate = minimum accepted value for @date
194         *     maxDate = maximum accepted value for @date
195         */
196        public void clamp(Date minDate, Date maxDate)
197        {
198                g_date_clamp(gDate, (minDate is null) ? null : minDate.getDateStruct(), (maxDate is null) ? null : maxDate.getDateStruct());
199        }
200
201        /**
202         * Initializes one or more #GDate structs to a sane but invalid
203         * state. The cleared dates will not represent an existing date, but will
204         * not contain garbage. Useful to init a date declared on the stack.
205         * Validity can be tested with g_date_valid().
206         *
207         * Params:
208         *     nDates = number of dates to clear
209         */
210        public void clear(uint nDates)
211        {
212                g_date_clear(gDate, nDates);
213        }
214
215        /**
216         * qsort()-style comparison function for dates.
217         * Both dates must be valid.
218         *
219         * Params:
220         *     rhs = second date to compare
221         *
222         * Returns: 0 for equal, less than zero if @lhs is less than @rhs,
223         *     greater than zero if @lhs is greater than @rhs
224         */
225        public int compare(Date rhs)
226        {
227                return g_date_compare(gDate, (rhs is null) ? null : rhs.getDateStruct());
228        }
229
230        /**
231         * Computes the number of days between two dates.
232         * If @date2 is prior to @date1, the returned value is negative.
233         * Both dates must be valid.
234         *
235         * Params:
236         *     date2 = the second date
237         *
238         * Returns: the number of days between @date1 and @date2
239         */
240        public int daysBetween(Date date2)
241        {
242                return g_date_days_between(gDate, (date2 is null) ? null : date2.getDateStruct());
243        }
244
245        /**
246         * Frees a #GDate returned from g_date_new().
247         */
248        public void free()
249        {
250                g_date_free(gDate);
251        }
252
253        /**
254         * Returns the day of the month. The date must be valid.
255         *
256         * Returns: day of the month
257         */
258        public GDateDay getDay()
259        {
260                return g_date_get_day(gDate);
261        }
262
263        /**
264         * Returns the day of the year, where Jan 1 is the first day of the
265         * year. The date must be valid.
266         *
267         * Returns: day of the year
268         */
269        public uint getDayOfYear()
270        {
271                return g_date_get_day_of_year(gDate);
272        }
273
274        /**
275         * Returns the week of the year, where weeks are interpreted according
276         * to ISO 8601.
277         *
278         * Returns: ISO 8601 week number of the year.
279         *
280         * Since: 2.6
281         */
282        public uint getIso8601WeekOfYear()
283        {
284                return g_date_get_iso8601_week_of_year(gDate);
285        }
286
287        /**
288         * Returns the Julian day or "serial number" of the #GDate. The
289         * Julian day is simply the number of days since January 1, Year 1; i.e.,
290         * January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2,
291         * etc. The date must be valid.
292         *
293         * Returns: Julian day
294         */
295        public uint getJulian()
296        {
297                return g_date_get_julian(gDate);
298        }
299
300        /**
301         * Returns the week of the year, where weeks are understood to start on
302         * Monday. If the date is before the first Monday of the year, return 0.
303         * The date must be valid.
304         *
305         * Returns: week of the year
306         */
307        public uint getMondayWeekOfYear()
308        {
309                return g_date_get_monday_week_of_year(gDate);
310        }
311
312        /**
313         * Returns the month of the year. The date must be valid.
314         *
315         * Returns: month of the year as a #GDateMonth
316         */
317        public GDateMonth getMonth()
318        {
319                return g_date_get_month(gDate);
320        }
321
322        /**
323         * Returns the week of the year during which this date falls, if
324         * weeks are understood to being on Sunday. The date must be valid.
325         * Can return 0 if the day is before the first Sunday of the year.
326         *
327         * Returns: week number
328         */
329        public uint getSundayWeekOfYear()
330        {
331                return g_date_get_sunday_week_of_year(gDate);
332        }
333
334        /**
335         * Returns the day of the week for a #GDate. The date must be valid.
336         *
337         * Returns: day of the week as a #GDateWeekday.
338         */
339        public GDateWeekday getWeekday()
340        {
341                return g_date_get_weekday(gDate);
342        }
343
344        /**
345         * Returns the year of a #GDate. The date must be valid.
346         *
347         * Returns: year in which the date falls
348         */
349        public GDateYear getYear()
350        {
351                return g_date_get_year(gDate);
352        }
353
354        /**
355         * Returns %TRUE if the date is on the first of a month.
356         * The date must be valid.
357         *
358         * Returns: %TRUE if the date is the first of the month
359         */
360        public bool isFirstOfMonth()
361        {
362                return g_date_is_first_of_month(gDate) != 0;
363        }
364
365        /**
366         * Returns %TRUE if the date is the last day of the month.
367         * The date must be valid.
368         *
369         * Returns: %TRUE if the date is the last day of the month
370         */
371        public bool isLastOfMonth()
372        {
373                return g_date_is_last_of_month(gDate) != 0;
374        }
375
376        /**
377         * Checks if @date1 is less than or equal to @date2,
378         * and swap the values if this is not the case.
379         *
380         * Params:
381         *     date2 = the second date
382         */
383        public void order(Date date2)
384        {
385                g_date_order(gDate, (date2 is null) ? null : date2.getDateStruct());
386        }
387
388        /**
389         * Sets the day of the month for a #GDate. If the resulting
390         * day-month-year triplet is invalid, the date will be invalid.
391         *
392         * Params:
393         *     day = day to set
394         */
395        public void setDay(GDateDay day)
396        {
397                g_date_set_day(gDate, day);
398        }
399
400        /**
401         * Sets the value of a #GDate from a day, month, and year.
402         * The day-month-year triplet must be valid; if you aren't
403         * sure it is, call g_date_valid_dmy() to check before you
404         * set it.
405         *
406         * Params:
407         *     day = day
408         *     month = month
409         *     y = year
410         */
411        public void setDmy(GDateDay day, GDateMonth month, GDateYear y)
412        {
413                g_date_set_dmy(gDate, day, month, y);
414        }
415
416        /**
417         * Sets the value of a #GDate from a Julian day number.
418         *
419         * Params:
420         *     julianDate = Julian day number (days since January 1, Year 1)
421         */
422        public void setJulian(uint julianDate)
423        {
424                g_date_set_julian(gDate, julianDate);
425        }
426
427        /**
428         * Sets the month of the year for a #GDate.  If the resulting
429         * day-month-year triplet is invalid, the date will be invalid.
430         *
431         * Params:
432         *     month = month to set
433         */
434        public void setMonth(GDateMonth month)
435        {
436                g_date_set_month(gDate, month);
437        }
438
439        /**
440         * Parses a user-inputted string @str, and try to figure out what date it
441         * represents, taking the [current locale][setlocale] into account. If the
442         * string is successfully parsed, the date will be valid after the call.
443         * Otherwise, it will be invalid. You should check using g_date_valid()
444         * to see whether the parsing succeeded.
445         *
446         * This function is not appropriate for file formats and the like; it
447         * isn't very precise, and its exact behavior varies with the locale.
448         * It's intended to be a heuristic routine that guesses what the user
449         * means by a given string (and it does work pretty well in that
450         * capacity).
451         *
452         * Params:
453         *     str = string to parse
454         */
455        public void setParse(string str)
456        {
457                g_date_set_parse(gDate, Str.toStringz(str));
458        }
459
460        /**
461         * Sets the value of a date from a #GTime value.
462         * The time to date conversion is done using the user's current timezone.
463         *
464         * Deprecated: Use g_date_set_time_t() instead.
465         *
466         * Params:
467         *     time = #GTime value to set.
468         */
469        public void setTime(GTime time)
470        {
471                g_date_set_time(gDate, time);
472        }
473
474        /**
475         * Sets the value of a date to the date corresponding to a time
476         * specified as a time_t. The time to date conversion is done using
477         * the user's current timezone.
478         *
479         * To set the value of a date to the current day, you could write:
480         * |[<!-- language="C" -->
481         * g_date_set_time_t (date, time (NULL));
482         * ]|
483         *
484         * Params:
485         *     timet = time_t value to set
486         *
487         * Since: 2.10
488         */
489        public void setTimeT(uint timet)
490        {
491                g_date_set_time_t(gDate, timet);
492        }
493
494        /**
495         * Sets the value of a date from a #GTimeVal value.  Note that the
496         * @tv_usec member is ignored, because #GDate can't make use of the
497         * additional precision.
498         *
499         * The time to date conversion is done using the user's current timezone.
500         *
501         * Params:
502         *     timeval = #GTimeVal value to set
503         *
504         * Since: 2.10
505         */
506        public void setTimeVal(TimeVal timeval)
507        {
508                g_date_set_time_val(gDate, (timeval is null) ? null : timeval.getTimeValStruct());
509        }
510
511        /**
512         * Sets the year for a #GDate. If the resulting day-month-year
513         * triplet is invalid, the date will be invalid.
514         *
515         * Params:
516         *     year = year to set
517         */
518        public void setYear(GDateYear year)
519        {
520                g_date_set_year(gDate, year);
521        }
522
523        /**
524         * Moves a date some number of days into the past.
525         * To move by weeks, just move by weeks*7 days.
526         * The date must be valid.
527         *
528         * Params:
529         *     nDays = number of days to move
530         */
531        public void subtractDays(uint nDays)
532        {
533                g_date_subtract_days(gDate, nDays);
534        }
535
536        /**
537         * Moves a date some number of months into the past.
538         * If the current day of the month doesn't exist in
539         * the destination month, the day of the month
540         * may change. The date must be valid.
541         *
542         * Params:
543         *     nMonths = number of months to move
544         */
545        public void subtractMonths(uint nMonths)
546        {
547                g_date_subtract_months(gDate, nMonths);
548        }
549
550        /**
551         * Moves a date some number of years into the past.
552         * If the current day doesn't exist in the destination
553         * year (i.e. it's February 29 and you move to a non-leap-year)
554         * then the day is changed to February 29. The date
555         * must be valid.
556         *
557         * Params:
558         *     nYears = number of years to move
559         */
560        public void subtractYears(uint nYears)
561        {
562                g_date_subtract_years(gDate, nYears);
563        }
564
565        /**
566         * Fills in the date-related bits of a struct tm using the @date value.
567         * Initializes the non-date parts with something sane but meaningless.
568         *
569         * Params:
570         *     tm = struct tm to fill
571         */
572        public void toStructTm(void* tm)
573        {
574                g_date_to_struct_tm(gDate, tm);
575        }
576
577        /**
578         * Returns %TRUE if the #GDate represents an existing day. The date must not
579         * contain garbage; it should have been initialized with g_date_clear()
580         * if it wasn't allocated by one of the g_date_new() variants.
581         *
582         * Returns: Whether the date is valid
583         */
584        public bool valid()
585        {
586                return g_date_valid(gDate) != 0;
587        }
588
589        /**
590         * Returns the number of days in a month, taking leap
591         * years into account.
592         *
593         * Params:
594         *     month = month
595         *     year = year
596         *
597         * Returns: number of days in @month during the @year
598         */
599        public static ubyte getDaysInMonth(GDateMonth month, GDateYear year)
600        {
601                return g_date_get_days_in_month(month, year);
602        }
603
604        /**
605         * Returns the number of weeks in the year, where weeks
606         * are taken to start on Monday. Will be 52 or 53. The
607         * date must be valid. (Years always have 52 7-day periods,
608         * plus 1 or 2 extra days depending on whether it's a leap
609         * year. This function is basically telling you how many
610         * Mondays are in the year, i.e. there are 53 Mondays if
611         * one of the extra days happens to be a Monday.)
612         *
613         * Params:
614         *     year = a year
615         *
616         * Returns: number of Mondays in the year
617         */
618        public static ubyte getMondayWeeksInYear(GDateYear year)
619        {
620                return g_date_get_monday_weeks_in_year(year);
621        }
622
623        /**
624         * Returns the number of weeks in the year, where weeks
625         * are taken to start on Sunday. Will be 52 or 53. The
626         * date must be valid. (Years always have 52 7-day periods,
627         * plus 1 or 2 extra days depending on whether it's a leap
628         * year. This function is basically telling you how many
629         * Sundays are in the year, i.e. there are 53 Sundays if
630         * one of the extra days happens to be a Sunday.)
631         *
632         * Params:
633         *     year = year to count weeks in
634         *
635         * Returns: the number of weeks in @year
636         */
637        public static ubyte getSundayWeeksInYear(GDateYear year)
638        {
639                return g_date_get_sunday_weeks_in_year(year);
640        }
641
642        /**
643         * Returns %TRUE if the year is a leap year.
644         *
645         * For the purposes of this function, leap year is every year
646         * divisible by 4 unless that year is divisible by 100. If it
647         * is divisible by 100 it would be a leap year only if that year
648         * is also divisible by 400.
649         *
650         * Params:
651         *     year = year to check
652         *
653         * Returns: %TRUE if the year is a leap year
654         */
655        public static bool isLeapYear(GDateYear year)
656        {
657                return g_date_is_leap_year(year) != 0;
658        }
659
660        /**
661         * Generates a printed representation of the date, in a
662         * [locale][setlocale]-specific way.
663         * Works just like the platform's C library strftime() function,
664         * but only accepts date-related formats; time-related formats
665         * give undefined results. Date must be valid. Unlike strftime()
666         * (which uses the locale encoding), works on a UTF-8 format
667         * string and stores a UTF-8 result.
668         *
669         * This function does not provide any conversion specifiers in
670         * addition to those implemented by the platform's C library.
671         * For example, don't expect that using g_date_strftime() would
672         * make the \%F provided by the C99 strftime() work on Windows
673         * where the C library only complies to C89.
674         *
675         * Params:
676         *     s = destination buffer
677         *     slen = buffer size
678         *     format = format string
679         *     date = valid #GDate
680         *
681         * Returns: number of characters written to the buffer, or 0 the buffer was too small
682         */
683        public static size_t strftime(string s, size_t slen, string format, Date date)
684        {
685                return g_date_strftime(Str.toStringz(s), slen, Str.toStringz(format), (date is null) ? null : date.getDateStruct());
686        }
687
688        /**
689         * Returns %TRUE if the day of the month is valid (a day is valid if it's
690         * between 1 and 31 inclusive).
691         *
692         * Params:
693         *     day = day to check
694         *
695         * Returns: %TRUE if the day is valid
696         */
697        public static bool validDay(GDateDay day)
698        {
699                return g_date_valid_day(day) != 0;
700        }
701
702        /**
703         * Returns %TRUE if the day-month-year triplet forms a valid, existing day
704         * in the range of days #GDate understands (Year 1 or later, no more than
705         * a few thousand years in the future).
706         *
707         * Params:
708         *     day = day
709         *     month = month
710         *     year = year
711         *
712         * Returns: %TRUE if the date is a valid one
713         */
714        public static bool validDmy(GDateDay day, GDateMonth month, GDateYear year)
715        {
716                return g_date_valid_dmy(day, month, year) != 0;
717        }
718
719        /**
720         * Returns %TRUE if the Julian day is valid. Anything greater than zero
721         * is basically a valid Julian, though there is a 32-bit limit.
722         *
723         * Params:
724         *     julianDate = Julian day to check
725         *
726         * Returns: %TRUE if the Julian day is valid
727         */
728        public static bool validJulian(uint julianDate)
729        {
730                return g_date_valid_julian(julianDate) != 0;
731        }
732
733        /**
734         * Returns %TRUE if the month value is valid. The 12 #GDateMonth
735         * enumeration values are the only valid months.
736         *
737         * Params:
738         *     month = month
739         *
740         * Returns: %TRUE if the month is valid
741         */
742        public static bool validMonth(GDateMonth month)
743        {
744                return g_date_valid_month(month) != 0;
745        }
746
747        /**
748         * Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration
749         * values are the only valid weekdays.
750         *
751         * Params:
752         *     weekday = weekday
753         *
754         * Returns: %TRUE if the weekday is valid
755         */
756        public static bool validWeekday(GDateWeekday weekday)
757        {
758                return g_date_valid_weekday(weekday) != 0;
759        }
760
761        /**
762         * Returns %TRUE if the year is valid. Any year greater than 0 is valid,
763         * though there is a 16-bit limit to what #GDate will understand.
764         *
765         * Params:
766         *     year = year
767         *
768         * Returns: %TRUE if the year is valid
769         */
770        public static bool validYear(GDateYear year)
771        {
772                return g_date_valid_year(year) != 0;
773        }
774}
Note: See TracBrowser for help on using the repository browser.