1 // Generated by gmmproc 2.64.2 -- DO NOT MODIFY! 2 #ifndef _GLIBMM_DATE_H 3 #define _GLIBMM_DATE_H 4 5 6 /* Copyright (C) 2002 The gtkmm Development Team 7 * 8 * This library is free software; you can redistribute it and/or 9 * modify it under the terms of the GNU Lesser General Public 10 * License as published by the Free Software Foundation; either 11 * version 2.1 of the License, or (at your option) any later version. 12 * 13 * This library is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * Lesser General Public License for more details. 17 * 18 * You should have received a copy of the GNU Lesser General Public 19 * License along with this library. If not, see <http://www.gnu.org/licenses/>. 20 */ 21 22 23 #include <glibmmconfig.h> 24 #include <glibmm/ustring.h> 25 #include <glib.h> 26 #include <ctime> 27 28 #ifndef DOXYGEN_SHOULD_SKIP_THIS 29 extern "C" { struct tm; } 30 #endif 31 32 namespace Glib 33 { 34 35 /** Julian calendar date. 36 */ 37 class GLIBMM_API Date 38 { 39 public: 40 using Day = guint8 ; 41 using Year = guint16; 42 43 /** @addtogroup glibmmEnums glibmm Enums and Flags */ 44 45 /** 46 * @var Month BAD_MONTH 47 * Invalid value. 48 * 49 * @var Month JANUARY 50 * January. 51 * 52 * @var Month FEBRUARY 53 * February. 54 * 55 * @var Month MARCH 56 * March. 57 * 58 * @var Month APRIL 59 * April. 60 * 61 * @var Month MAY 62 * May. 63 * 64 * @var Month JUNE 65 * June. 66 * 67 * @var Month JULY 68 * July. 69 * 70 * @var Month AUGUST 71 * August. 72 * 73 * @var Month SEPTEMBER 74 * September. 75 * 76 * @var Month OCTOBER 77 * October. 78 * 79 * @var Month NOVEMBER 80 * November. 81 * 82 * @var Month DECEMBER 83 * December. 84 * 85 * @enum Month 86 * 87 * Enumeration representing a month; values are DATE_JANUARY, 88 * DATE_FEBRUARY, etc. DATE_BAD_MONTH is the invalid value. 89 * 90 * @ingroup glibmmEnums 91 */ 92 enum Month 93 { 94 BAD_MONTH, 95 JANUARY, 96 FEBRUARY, 97 MARCH, 98 APRIL, 99 MAY, 100 JUNE, 101 JULY, 102 AUGUST, 103 SEPTEMBER, 104 OCTOBER, 105 NOVEMBER, 106 DECEMBER 107 }; 108 109 110 /** 111 * @var Weekday BAD_WEEKDAY 112 * Invalid value. 113 * 114 * @var Weekday MONDAY 115 * Monday. 116 * 117 * @var Weekday TUESDAY 118 * Tuesday. 119 * 120 * @var Weekday WEDNESDAY 121 * Wednesday. 122 * 123 * @var Weekday THURSDAY 124 * Thursday. 125 * 126 * @var Weekday FRIDAY 127 * Friday. 128 * 129 * @var Weekday SATURDAY 130 * Saturday. 131 * 132 * @var Weekday SUNDAY 133 * Sunday. 134 * 135 * @enum Weekday 136 * 137 * Enumeration representing a day of the week; DATE_MONDAY, 138 * DATE_TUESDAY, etc. DATE_BAD_WEEKDAY is an invalid weekday. 139 * 140 * @ingroup glibmmEnums 141 */ 142 enum Weekday 143 { 144 BAD_WEEKDAY, 145 MONDAY, 146 TUESDAY, 147 WEDNESDAY, 148 THURSDAY, 149 FRIDAY, 150 SATURDAY, 151 SUNDAY 152 }; 153 154 155 /** 156 * @var DMY DAY 157 * A day. 158 * 159 * @var DMY MONTH 160 * A month. 161 * 162 * @var DMY YEAR 163 * A year. 164 * 165 * @enum DMY 166 * 167 * This enumeration isn't used in the API, but may be useful if you need 168 * to mark a number as a day, month, or year. 169 * 170 * @ingroup glibmmEnums 171 */ 172 enum DMY 173 { 174 DAY, 175 MONTH, 176 YEAR 177 }; 178 179 180 static const Day BAD_DAY = 0; 181 static const Year BAD_YEAR = 0; 182 static const guint32 BAD_JULIAN = 0; 183 184 /** Construct an undefined date. 185 */ 186 Date(); 187 188 /** Construct a date with the given day, month and year. 189 * @param day The day. 190 * @param month The month. 191 * @param year The year. 192 */ 193 Date(Day day, Month month, Year year); 194 195 /** Construct a date from a julian day. 196 * @param julian_day The julian day (guint32). 197 */ 198 explicit Date(guint32 julian_day); 199 200 /** Construct a Glib::Date by copying the contents of a GDate. 201 * @param castitem The GDate. 202 * 203 * @newin{2,18} 204 */ 205 explicit Date(const GDate& castitem); 206 207 /** Construct a Glib::Date from another. 208 * @param other the other Glib::Date. 209 * 210 * @newin{2,18} 211 */ 212 Date(const Date& other); 213 214 /** Assign another date to this one. For example: 215 * @code 216 * ... 217 * Glib::Date my_date; 218 * my_date = other_date; 219 * @endcode 220 * 221 * @param other The other Glib::Date. 222 * 223 * @newin{2,18} 224 */ 225 Date& operator=(const Date& other); 226 227 /// Provides access to the underlying C instance. gobj()228 GDate* gobj() { return &gobject_; } 229 230 /// Provides access to the underlying C instance. gobj()231 const GDate* gobj() const { return &gobject_; } 232 233 private: 234 GDate gobject_; 235 236 public: 237 /** Clear the date. The cleared dates will not represent an existing date, 238 * but will not contain garbage. 239 */ 240 void clear(); 241 242 /** Parses a user-inputted string str, and try to figure out what date it represents, taking the current locale into account. If the string is successfully parsed, the date will be valid after the call. Otherwise, it will be invalid. 243 * This function is not appropriate for file formats and the like; it isn't very precise, and its exact behavior varies with the locale. It's intended to be a heuristic routine that guesses what the user means by a given string (and it does work pretty well in that capacity). 244 * @param str String to parse. 245 */ 246 void set_parse (const Glib::ustring& str); 247 248 #ifndef GLIBMM_DISABLE_DEPRECATED 249 250 G_GNUC_BEGIN_IGNORE_DEPRECATIONS 251 //Avoid a build problem in the case that std::time_t is equivalent to gint32 (GTime is also gint32) 252 //That would make the set_time() method overload impossible. 253 #ifdef GLIBMM_HAVE_C_STD_TIME_T_IS_NOT_INT32 254 /** Sets the value of a date from a GTime value. 255 * 256 * @param time GTime value to set. 257 * 258 * @deprecated Please use set_time(std::time_t) instead. 259 */ 260 void set_time(GTime time); 261 #endif //GLIBMM_HAVE_C_STD_TIME_T_IS_NOT_INT32 262 G_GNUC_END_IGNORE_DEPRECATIONS 263 #endif // GLIBMM_DISABLE_DEPRECATED 264 265 266 /** Sets the value of a date from a <type>std::time_t</type> value. 267 * 268 * @param timet std::time_t value to set 269 * 270 * @see set_time_current() 271 * 272 * Since: 2.10 273 */ 274 void set_time(std::time_t timet); 275 276 #ifndef GLIBMM_DISABLE_DEPRECATED 277 278 G_GNUC_BEGIN_IGNORE_DEPRECATIONS 279 /** Sets the value of a date from a GTimeVal value. Note that the 280 * tv_usec member is ignored, because Glib::Date can't make use of the 281 * additional precision. 282 * 283 * @deprecated Use set_time(std::time_t timet) instead. 284 * 285 * @param timeval GTimeVal value to set 286 * 287 * Since: 2.10 288 */ 289 void set_time(const GTimeVal& timeval); 290 G_GNUC_END_IGNORE_DEPRECATIONS 291 #endif // GLIBMM_DISABLE_DEPRECATED 292 293 294 /** Set this Glib::Date to the current time. 295 */ 296 void set_time_current(); 297 298 /** Sets the month of the year. If the resulting day-month-year triplet is invalid, the date will be invalid. 299 * @param month Month to set. 300 */ 301 void set_month(Month month); 302 303 /** Sets the day of the month. If the resulting day-month-year triplet is invalid, the date will be invalid. 304 * @param day Day to set. 305 */ 306 void set_day(Day day); 307 308 /** Sets the year. If the resulting day-month-year triplet is invalid, the date will be invalid. 309 * @param year Year to set. 310 */ 311 void set_year(Year year); 312 313 /** Sets the value of a day, month, and year.. If the resulting day-month-year triplet is invalid, the date will be invalid. 314 * @param day Day to set. 315 * @param month Month to set. 316 * @param year Year to set. 317 */ 318 void set_dmy(Day day, Month month, Year year); 319 320 /** Sets the value of a GDate from a Julian day number. 321 * @param julian_day Julian day to set. 322 */ 323 void set_julian(guint32 julian_day); 324 325 /** Add a number of days to a Date. 326 * This method returns a reference to the object itself, so you can write code such as: 327 * @code 328 * somedate.add_days(2).add_months(3).add_years(17); 329 * @endcode 330 * 331 * @param n_days Days to add. 332 * @return Resulting Date 333 */ 334 Date& add_days(int n_days); 335 336 /** Subtract n_days to a Date. 337 * This method returns a reference to the object itself, so you can write code such as: 338 * @code 339 * somedate.subtract_days(2).subtract_months(3).subtract_years(17); 340 * @endcode 341 * 342 * @param n_days Days to subtract. 343 * @return Resulting Date 344 */ 345 Date& subtract_days(int n_days); 346 347 /** Add n_months to a Date. 348 * This method returns a reference to the object itself, so you can write code such as: 349 * @code 350 * somedate.add_years(2).add_months(3).add_days(17); 351 * @endcode 352 * 353 * @param n_months Months to add. 354 * @return Resulting Date 355 */ 356 Date& add_months(int n_months); 357 358 /** Subtract n_months to a Date. 359 * This method returns a reference to the object itself, so you can write code such as: 360 * @code 361 * somedate.subtract_years(2).subtract_months(3).subtract_days(17); 362 * @endcode 363 * 364 * @param n_months Months to subtract. 365 * @return Resulting Date 366 */ 367 Date& subtract_months(int n_months); 368 369 /** Add n_days to a Date. 370 * This method returns a reference to the object itself, so you can write code such as: 371 * @code 372 * somedate.add_years(2).add_months(3).add_days(17); 373 * @endcode 374 * 375 * @param n_years Years to add. 376 * @return Resulting Date 377 */ 378 Date& add_years(int n_years); 379 380 /** Subtract n_years to a Date. 381 * This method returns a reference to the object itself, so you can write code such as: 382 * @code 383 * somedate.subtract_years(2).subtract_months(3).subtract_days(17); 384 * @endcode 385 * 386 * @param n_years Years to subtract. 387 * @return Resulting Date 388 */ 389 Date& subtract_years(int n_years); 390 391 /** Calculate days between two dates. 392 * @param rhs Date. 393 * @return Numbers of days. 394 */ 395 int days_between(const Date& rhs) const; 396 397 /** Compare two dates. 398 * @param rhs Date to compare. 399 * @return Result of comparition. 400 */ 401 int compare(const Date& rhs) const; 402 403 /** If date is prior to min_date, sets date equal to min_date. 404 * If date falls after max_date, sets date equal to max_date. All dates must be valid. 405 * See also clamp_min() and clamp_max(). 406 * This method returns a reference to the object itself. 407 * @param min_date Date minimum value. 408 * @param max_date Date maximum value. 409 * @return Date in interval. 410 */ 411 Date& clamp(const Date& min_date, const Date& max_date); 412 413 /** If date is prior to min_date, sets date equal to min_date. 414 * See also clamp(), and clamp_max(). 415 * This method returns a reference to the object itself. 416 * @param min_date Date minimum value. 417 * @return Date in interval. 418 */ 419 Date& clamp_min(const Date& min_date); 420 421 /** If date falls after max_date, sets date equal to max_date. 422 * See also clamp(), and clamp_min(). 423 * This method returns a reference to the object itself. 424 * @param max_date Date maximum value. 425 * @return Date in interval. 426 */ 427 Date& clamp_max(const Date& max_date); 428 429 /** Checks if date is less than or equal to other date, and swap the values if this is not the case. 430 * @param other Date ro compare. 431 * @return Date. 432 */ 433 void order(Date& other); 434 435 /** Returns the day of the week for a Date. The date must be valid. 436 * @return Day of the week as a Date::Weekday. 437 */ 438 Weekday get_weekday() const; 439 440 /** Returns the month of the year. The date must be valid. 441 * @return Month of the year as a Date::Month. 442 */ 443 Month get_month() const; 444 445 /** Returns the year of a Date. The date must be valid. 446 * @return Year in which the date falls. 447 */ 448 Year get_year() const; 449 450 /** Returns the day of the month. The date must be valid. 451 * @return Day of the month.. 452 */ 453 Day get_day() const; 454 455 /** Returns the Julian day or "serial number" of the Date. 456 * The Julian day is simply the number of days since January 1, Year 1; 457 * i.e., January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2, etc. 458 * The date must be valid. 459 * @return Julian day. 460 */ 461 guint32 get_julian() const; 462 463 /** Returns the day of the year, where Jan 1 is the first day of the year. 464 * The date must be valid. 465 * @return Julian day. 466 */ 467 unsigned int get_day_of_year() const; 468 469 /** Returns the week of the year, where weeks are understood to start on Monday. 470 * If the date is before the first Monday of the year, return 0. 471 * The date must be valid. 472 * @return Week of the year. 473 */ 474 unsigned int get_monday_week_of_year() const; 475 476 /** Returns the week of the year during which this date falls, if weeks are understood to being on Sunday. 477 * Can return 0 if the day is before the first Sunday of the year. 478 * The date must be valid. 479 * @return Week of the year. 480 */ 481 unsigned int get_sunday_week_of_year() const; 482 483 /** Returns the week of the year, where weeks are interpreted according to ISO 8601. 484 * The date must be valid. 485 * @return ISO 8601 week number of the year. 486 * 487 * @newin{2,22} 488 */ 489 unsigned int get_iso8601_week_of_year() const; 490 491 /** Returns true if the date is on the first of a month. 492 * The date must be valid. 493 * @return true if the date is the first of the month. 494 */ 495 bool is_first_of_month() const; 496 497 /** Returns true if the date is the last day of the month. 498 * The date must be valid. 499 * @return true if the date is the last day of the month. 500 */ 501 bool is_last_of_month() const; 502 503 /** Returns the number of days in a month, taking leap years into account. 504 * @param month Month. 505 * @param year Year. 506 * @return Number of days in month during the year. 507 */ 508 static guint8 get_days_in_month(Month month, Year year); 509 510 /** Returns the number of weeks in the year, where weeks are taken to start on Monday. Will be 52 or 53. 511 * (Years always have 52 7-day periods, plus 1 or 2 extra days depending on whether it's a leap year. This function is basically telling you how many Mondays are in the year, i.e. there are 53 Mondays if one of the extra days happens to be a Monday.) 512 * @param year Year to count weeks in. 513 * @return Number of weeks. 514 */ 515 static guint8 get_monday_weeks_in_year(Year year); 516 517 /** Returns the number of weeks in the year, where weeks are taken to start on Sunday. Will be 52 or 53. 518 * (Years always have 52 7-day periods, plus 1 or 2 extra days depending on whether it's a leap year. This function is basically telling you how many Sundays are in the year, i.e. there are 53 Sundays if one of the extra days happens to be a Sunday.) 519 * @param year Year to count weeks in. 520 * @return Number of weeks. 521 */ 522 static guint8 get_sunday_weeks_in_year(Year year); 523 524 /** Returns true if the year is a leap year. 525 * @param year Year to check. 526 * @return true if the year is a leap year. 527 */ 528 static bool is_leap_year(Year year); 529 530 /** Convert date to string. 531 * @param format A format string as used by @c strftime(), in UTF-8 532 * encoding. Only date formats are allowed, the result of time formats 533 * is undefined. 534 * @return The formatted date string. 535 * @throw Glib::ConvertError 536 */ 537 Glib::ustring format_string(const Glib::ustring& format) const; 538 539 /** Fills in the date-related bits of a struct tm using the date value. Initializes the non-date parts with something sane but meaningless. 540 * @param dest Struct tm to fill. 541 */ 542 void to_struct_tm(struct tm& dest) const; 543 544 /** Returns true if the Date represents an existing day. 545 * @return true if the date is valid. 546 */ 547 bool valid() const; 548 549 /** Returns true if the day of the month is valid (a day is valid if it's between 1 and 31 inclusive). 550 * @param day Day to check. 551 * @return true if the day is valid. 552 */ 553 static bool valid_day(Day day); 554 555 /** Returns true if the month value is valid. The 12 Date::Month enumeration values are the only valid months. 556 * @param month Month to check. 557 * @return true if the month is valid. 558 */ 559 static bool valid_month(Month month); 560 561 562 /** Returns true if the year is valid. 563 * Any year greater than 0 is valid, though there is a 16-bit limit to what Date will understand. 564 * @param year Year to check. 565 * @return true if the year is valid. 566 */ 567 static bool valid_year(Year year); 568 569 /** Returns true if the weekday is valid. 570 * The 7 Date::Weekday enumeration values are the only valid. 571 * @param weekday Weekday to check. 572 * @return true if the weekday is valid. 573 */ 574 static bool valid_weekday(Weekday weekday); 575 576 /** Returns true if the Julian day is valid. 577 * Anything greater than zero is basically a valid Julian, though there is a 32-bit limit. 578 * @param julian_day Julian day to check. 579 * @return true if the Julian day is valid. 580 */ 581 static bool valid_julian(guint32 julian_day); 582 583 584 /** Returns true if the day-month-year triplet forms a valid, existing day in the range of days Date understands (Year 1 or later, no more than a few thousand years in the future). 585 * @param day Day to check. 586 * @param month Month to check. 587 * @param year Year to check. 588 * @return true if the date is a valid one. 589 */ 590 static bool valid_dmy(Day day, Month month, Year year); 591 }; 592 593 594 /** @relates Glib::Date */ 595 inline bool operator==(const Date& lhs, const Date& rhs) 596 { return (lhs.compare(rhs) == 0); } 597 598 /** @relates Glib::Date */ 599 inline bool operator!=(const Date& lhs, const Date& rhs) 600 { return (lhs.compare(rhs) != 0); } 601 602 /** @relates Glib::Date */ 603 inline bool operator<(const Date& lhs, const Date& rhs) 604 { return (lhs.compare(rhs) < 0); } 605 606 /** @relates Glib::Date */ 607 inline bool operator>(const Date& lhs, const Date& rhs) 608 { return (lhs.compare(rhs) > 0); } 609 610 /** @relates Glib::Date */ 611 inline bool operator<=(const Date& lhs, const Date& rhs) 612 { return (lhs.compare(rhs) <= 0); } 613 614 /** @relates Glib::Date */ 615 inline bool operator>=(const Date& lhs, const Date& rhs) 616 { return (lhs.compare(rhs) >= 0); } 617 618 } // namespace Glib 619 620 621 #endif /* _GLIBMM_DATE_H */ 622 623