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