/src/wrappers/glib/library/utilities/glib_date_and_time_functions.e
Specman e | 1101 lines | 2 code | 361 blank | 738 comment | 0 complexity | 594646f10ed99ae698a3b53d546da5f9 MD5 | raw file
1deferred class GLIB_DATE_AND_TIME_FUNCTIONS 2 3-- Top | Description 4 5-- Date and Time Functions 6 7-- Date and Time Functions -- calendrical calculations and miscellaneous time 8-- stuff. 9 10-- Synopsis 11 12 13-- #include <glib.h> 14 15 16-- #define G_USEC_PER_SEC 17-- GTimeVal; 18-- void g_get_current_time (GTimeVal *result); 19-- void g_usleep (gulong microseconds); 20-- void g_time_val_add (GTimeVal *time_, 21-- glong microseconds); 22-- gboolean g_time_val_from_iso8601 (const gchar *iso_date, 23-- GTimeVal *time_); 24-- gchar* g_time_val_to_iso8601 (GTimeVal *time_); 25 26-- GDate; 27-- typedef GTime; 28-- enum GDateDMY; 29-- typedef GDateDay; 30-- enum GDateMonth; 31-- typedef GDateYear; 32-- enum GDateWeekday; 33 34-- #define G_DATE_BAD_DAY 35-- #define G_DATE_BAD_JULIAN 36-- #define G_DATE_BAD_YEAR 37 38-- GDate* g_date_new (void); 39-- GDate* g_date_new_dmy (GDateDay day, 40-- GDateMonth month, 41-- GDateYear year); 42-- GDate* g_date_new_julian (guint32 julian_day); 43-- void g_date_clear (GDate *date, 44-- guint n_dates); 45-- void g_date_free (GDate *date); 46 47-- void g_date_set_day (GDate *date, 48-- GDateDay day); 49-- void g_date_set_month (GDate *date, 50-- GDateMonth month); 51-- void g_date_set_year (GDate *date, 52-- GDateYear year); 53-- void g_date_set_dmy (GDate *date, 54-- GDateDay day, 55-- GDateMonth month, 56-- GDateYear y); 57-- void g_date_set_julian (GDate *date, 58-- guint32 julian_date); 59-- void g_date_set_time (GDate *date, 60-- GTime time_); 61-- void g_date_set_time_t (GDate *date, 62-- time_t timet); 63-- void g_date_set_time_val (GDate *date, 64-- GTimeVal *timeval); 65-- void g_date_set_parse (GDate *date, 66-- const gchar *str); 67 68-- void g_date_add_days (GDate *date, 69-- guint n_days); 70-- void g_date_subtract_days (GDate *date, 71-- guint n_days); 72-- void g_date_add_months (GDate *date, 73-- guint n_months); 74-- void g_date_subtract_months (GDate *date, 75-- guint n_months); 76-- void g_date_add_years (GDate *date, 77-- guint n_years); 78-- void g_date_subtract_years (GDate *date, 79-- guint n_years); 80-- gint g_date_days_between (const GDate *date1, 81-- const GDate *date2); 82-- gint g_date_compare (const GDate *lhs, 83-- const GDate *rhs); 84-- void g_date_clamp (GDate *date, 85-- const GDate *min_date, 86-- const GDate *max_date); 87-- void g_date_order (GDate *date1, 88-- GDate *date2); 89 90-- GDateDay g_date_get_day (const GDate *date); 91-- GDateMonth g_date_get_month (const GDate *date); 92-- GDateYear g_date_get_year (const GDate *date); 93-- guint32 g_date_get_julian (const GDate *date); 94-- GDateWeekday g_date_get_weekday (const GDate *date); 95-- guint g_date_get_day_of_year (const GDate *date); 96 97-- guint8 g_date_get_days_in_month (GDateMonth month, 98-- GDateYear year); 99-- gboolean g_date_is_first_of_month (const GDate *date); 100-- gboolean g_date_is_last_of_month (const GDate *date); 101-- gboolean g_date_is_leap_year (GDateYear year); 102-- guint g_date_get_monday_week_of_year (const GDate *date); 103-- guint8 g_date_get_monday_weeks_in_year (GDateYear year); 104-- guint g_date_get_sunday_week_of_year (const GDate *date); 105-- guint8 g_date_get_sunday_weeks_in_year (GDateYear year); 106-- guint g_date_get_iso8601_week_of_year (const GDate *date); 107 108-- gsize g_date_strftime (gchar *s, 109-- gsize slen, 110-- const gchar *format, 111-- const GDate *date); 112-- void g_date_to_struct_tm (const GDate *date, 113-- struct tm *tm); 114 115-- gboolean g_date_valid (const GDate *date); 116-- gboolean g_date_valid_day (GDateDay day); 117-- gboolean g_date_valid_month (GDateMonth month); 118-- gboolean g_date_valid_year (GDateYear year); 119-- gboolean g_date_valid_dmy (GDateDay day, 120-- GDateMonth month, 121-- GDateYear year); 122-- gboolean g_date_valid_julian (guint32 julian_date); 123-- gboolean g_date_valid_weekday (GDateWeekday weekday); 124 125 126-- Description 127 128-- The GDate data structure represents a day between January 1, Year 1, and sometime 129-- a few thousand years in the future (right now it will go to the year 65535 or so, 130-- but g_date_set_parse() only parses up to the year 8000 or so - just count on "a 131-- few thousand"). GDate is meant to represent everyday dates, not astronomical 132-- dates or historical dates or ISO timestamps or the like. It extrapolates the 133-- current Gregorian calendar forward and backward in time; there is no attempt to 134-- change the calendar to match time periods or locations. GDate does not store time 135-- information; it represents a day. 136 137-- The GDate implementation has several nice features; it is only a 64-bit struct, 138-- so storing large numbers of dates is very efficient. It can keep both a Julian 139-- and day-month-year representation of the date, since some calculations are much 140-- easier with one representation or the other. A Julian representation is simply a 141-- count of days since some fixed day in the past; for GDate the fixed day is 142-- January 1, 1 AD. ("Julian" dates in the GDate API aren't really Julian dates in 143-- the technical sense; technically, Julian dates count from the start of the Julian 144-- period, Jan 1, 4713 BC). 145 146-- GDate is simple to use. First you need a "blank" date; you can get a dynamically 147-- allocated date from g_date_new(), or you can declare an automatic variable or 148-- array and initialize it to a sane state by calling g_date_clear(). A cleared date 149-- is sane; it's safe to call g_date_set_dmy() and the other mutator functions to 150-- initialize the value of a cleared date. However, a cleared date is initially 151-- invalid, meaning that it doesn't represent a day that exists. It is undefined to 152-- call any of the date calculation routines on an invalid date. If you obtain a 153-- date from a user or other unpredictable source, you should check its validity 154-- with the g_date_valid() predicate. g_date_valid() is also used to check for 155-- errors with g_date_set_parse() and other functions that can fail. Dates can be 156-- invalidated by calling g_date_clear() again. 157 158-- It is very important to use the API to access the GDate struct. Often only the 159-- day-month-year or only the Julian representation is valid. Sometimes neither is 160-- valid. Use the API. 161 162-- GLib doesn't contain any time-manipulation functions; however, there is a GTime 163-- typedef and a GTimeVal struct which represents a more precise time (with 164-- microseconds). You can request the current time as a GTimeVal with 165-- g_get_current_time(). 166 167-- Details 168 169-- G_USEC_PER_SEC 170 171-- #define G_USEC_PER_SEC 1000000 172 173-- Number of microseconds in one second (1 million). This macro is provided for code 174-- readability. 175 176-- --------------------------------------------------------------------------------- 177 178-- GTimeVal 179 180-- typedef struct { 181-- glong tv_sec; 182-- glong tv_usec; 183-- } GTimeVal; 184 185-- Represents a precise time, with seconds and microseconds. Similar to the struct 186-- timeval returned by the gettimeofday() UNIX call. 187 188-- glong tv_sec; seconds. 189-- glong tv_usec; microseconds. 190 191-- --------------------------------------------------------------------------------- 192 193-- g_get_current_time () 194 195-- void g_get_current_time (GTimeVal *result); 196 197-- Equivalent to the UNIX gettimeofday() function, but portable. 198 199-- result : GTimeVal structure in which to store current time. 200 201-- --------------------------------------------------------------------------------- 202 203-- g_usleep () 204 205-- void g_usleep (gulong microseconds); 206 207-- Pauses the current thread for the given number of microseconds. There are 1 208-- million microseconds per second (represented by the G_USEC_PER_SEC macro). 209-- g_usleep() may have limited precision, depending on hardware and operating 210-- system; don't rely on the exact length of the sleep. 211 212-- microseconds : number of microseconds to pause. 213 214-- --------------------------------------------------------------------------------- 215 216-- g_time_val_add () 217 218-- void g_time_val_add (GTimeVal *time_, 219-- glong microseconds); 220 221-- Adds the given number of microseconds to time_. microseconds can also be negative 222-- to decrease the value of time_. 223 224-- time_ : a GTimeVal 225-- microseconds : number of microseconds to add to time 226 227-- --------------------------------------------------------------------------------- 228 229-- g_time_val_from_iso8601 () 230 231-- gboolean g_time_val_from_iso8601 (const gchar *iso_date, 232-- GTimeVal *time_); 233 234-- Converts a string containing an ISO 8601 encoded date and time to a GTimeVal and 235-- puts it into time_. 236 237-- iso_date : a ISO 8601 encoded date string 238-- time_ : a GTimeVal 239-- Returns : TRUE if the conversion was successful. 240 241-- Since 2.12 242 243-- --------------------------------------------------------------------------------- 244 245-- g_time_val_to_iso8601 () 246 247-- gchar* g_time_val_to_iso8601 (GTimeVal *time_); 248 249-- Converts time_ into a ISO 8601 encoded string, relative to the Coordinated 250-- Universal Time (UTC). 251 252-- time_ : a GTimeVal 253-- Returns : a newly allocated string containing a ISO 8601 date 254 255-- Since 2.12 256 257-- --------------------------------------------------------------------------------- 258 259-- GDate 260 261-- typedef struct { 262-- guint julian_days : 32; /* julian days representation - we use a 263-- * bitfield hoping that 64 bit platforms 264-- * will pack this whole struct in one big 265-- * int 266-- */ 267 268-- guint julian : 1; /* julian is valid */ 269-- guint dmy : 1; /* dmy is valid */ 270 271-- /* DMY representation */ 272-- guint day : 6; 273-- guint month : 4; 274-- guint year : 16; 275-- } GDate; 276 277-- Represents a day between January 1, Year 1 and a few thousand years in the 278-- future. None of its members should be accessed directly. If the GDate is obtained 279-- from g_date_new(), it will be safe to mutate but invalid and thus not safe for 280-- calendrical computations. If it's declared on the stack, it will contain garbage 281-- so must be initialized with g_date_clear(). g_date_clear() makes the date invalid 282-- but sane. An invalid date doesn't represent a day, it's "empty." A date becomes 283-- valid after you set it to a Julian day or you set a day, month, and year. 284 285-- guint julian_days : 32; the Julian representation of the date 286-- guint julian : 1; this bit is set if julian_days is valid 287-- guint dmy : 1; this is set if day, month and year are valid 288-- guint day : 6; the day of the day-month-year representation of the date, 289-- as a number between 1 and 31 290-- guint month : 4; the day of the day-month-year representation of the date, 291-- as a number between 1 and 12 292-- guint year : 16; the day of the day-month-year representation of the date 293 294-- --------------------------------------------------------------------------------- 295 296-- GTime 297 298-- typedef gint32 GTime; 299 300-- Simply a replacement for time_t. It has been deprected since it is not equivalent 301-- to time_t on 64-bit platforms with a 64-bit time_t. Unrelated to GTimer. 302 303-- Note that GTime is defined to always be a 32bit integer, unlike time_t which may 304-- be 64bit on some systems. Therefore, GTime will overflow in the year 2038, and 305-- you cannot use the address of a GTime variable as argument to the UNIX time() 306-- function. Instead, do the following: 307 308-- time_t ttime; 309-- GTime gtime; 310 311-- time (&ttime); 312-- gtime = (GTime)ttime; 313 314-- --------------------------------------------------------------------------------- 315 316-- enum GDateDMY 317 318-- typedef enum 319-- { 320-- G_DATE_DAY = 0, 321-- G_DATE_MONTH = 1, 322-- G_DATE_YEAR = 2 323-- } GDateDMY; 324 325-- This enumeration isn't used in the API, but may be useful if you need to mark a 326-- number as a day, month, or year. 327 328-- G_DATE_DAY a day 329-- G_DATE_MONTH a month 330-- G_DATE_YEAR a year 331 332-- --------------------------------------------------------------------------------- 333 334-- GDateDay 335 336-- typedef guint8 GDateDay; /* day of the month */ 337 338-- Integer representing a day of the month; between 1 and 31. G_DATE_BAD_DAY 339-- represents an invalid day of the month. 340 341-- --------------------------------------------------------------------------------- 342 343-- enum GDateMonth 344 345-- typedef enum 346-- { 347-- G_DATE_BAD_MONTH = 0, 348-- G_DATE_JANUARY = 1, 349-- G_DATE_FEBRUARY = 2, 350-- G_DATE_MARCH = 3, 351-- G_DATE_APRIL = 4, 352-- G_DATE_MAY = 5, 353-- G_DATE_JUNE = 6, 354-- G_DATE_JULY = 7, 355-- G_DATE_AUGUST = 8, 356-- G_DATE_SEPTEMBER = 9, 357-- G_DATE_OCTOBER = 10, 358-- G_DATE_NOVEMBER = 11, 359-- G_DATE_DECEMBER = 12 360-- } GDateMonth; 361 362-- Enumeration representing a month; values are G_DATE_JANUARY, G_DATE_FEBRUARY, 363-- etc. G_DATE_BAD_MONTH is the invalid value. 364 365-- G_DATE_BAD_MONTH invalid value. 366-- G_DATE_JANUARY January. 367-- G_DATE_FEBRUARY February. 368-- G_DATE_MARCH March. 369-- G_DATE_APRIL April. 370-- G_DATE_MAY May. 371-- G_DATE_JUNE June. 372-- G_DATE_JULY July. 373-- G_DATE_AUGUST August. 374-- G_DATE_SEPTEMBER September. 375-- G_DATE_OCTOBER October. 376-- G_DATE_NOVEMBER November. 377-- G_DATE_DECEMBER December. 378 379-- --------------------------------------------------------------------------------- 380 381-- GDateYear 382 383-- typedef guint16 GDateYear; 384 385-- Integer representing a year; G_DATE_BAD_YEAR is the invalid value. The year must 386-- be 1 or higher; negative (BC) years are not allowed. The year is represented with 387-- four digits. 388 389-- --------------------------------------------------------------------------------- 390 391-- enum GDateWeekday 392 393-- typedef enum 394-- { 395-- G_DATE_BAD_WEEKDAY = 0, 396-- G_DATE_MONDAY = 1, 397-- G_DATE_TUESDAY = 2, 398-- G_DATE_WEDNESDAY = 3, 399-- G_DATE_THURSDAY = 4, 400-- G_DATE_FRIDAY = 5, 401-- G_DATE_SATURDAY = 6, 402-- G_DATE_SUNDAY = 7 403-- } GDateWeekday; 404 405-- Enumeration representing a day of the week; G_DATE_MONDAY, G_DATE_TUESDAY, etc. 406-- G_DATE_BAD_WEEKDAY is an invalid weekday. 407 408-- G_DATE_BAD_WEEKDAY invalid value. 409-- G_DATE_MONDAY Monday. 410-- G_DATE_TUESDAY Tuesday. 411-- G_DATE_WEDNESDAY Wednesday. 412-- G_DATE_THURSDAY Thursday. 413-- G_DATE_FRIDAY Friday. 414-- G_DATE_SATURDAY Saturday. 415-- G_DATE_SUNDAY Sunday. 416 417-- --------------------------------------------------------------------------------- 418 419-- G_DATE_BAD_DAY 420 421-- #define G_DATE_BAD_DAY 0U 422 423-- Represents an invalid GDateDay. 424 425-- --------------------------------------------------------------------------------- 426 427-- G_DATE_BAD_JULIAN 428 429-- #define G_DATE_BAD_JULIAN 0U 430 431-- Represents an invalid Julian day number. 432 433-- --------------------------------------------------------------------------------- 434 435-- G_DATE_BAD_YEAR 436 437-- #define G_DATE_BAD_YEAR 0U 438 439-- Represents an invalid year. 440 441-- --------------------------------------------------------------------------------- 442 443-- g_date_new () 444 445-- GDate* g_date_new (void); 446 447-- Allocates a GDate and initializes it to a sane state. The new date will be 448-- cleared (as if you'd called g_date_clear()) but invalid (it won't represent an 449-- existing day). Free the return value with g_date_free(). 450 451-- Returns : a newly-allocated GDate. 452 453-- --------------------------------------------------------------------------------- 454 455-- g_date_new_dmy () 456 457-- GDate* g_date_new_dmy (GDateDay day, 458-- GDateMonth month, 459-- GDateYear year); 460 461-- Like g_date_new(), but also sets the value of the date. Assuming the 462-- day-month-year triplet you pass in represents an existing day, the returned date 463-- will be valid. 464 465-- day : day of the month. 466-- month : month of the year. 467-- year : year 468-- Returns : a newly-allocated GDate initialized with day, month, and year. 469 470-- --------------------------------------------------------------------------------- 471 472-- g_date_new_julian () 473 474-- GDate* g_date_new_julian (guint32 julian_day); 475 476-- Like g_date_new(), but also sets the value of the date. Assuming the Julian day 477-- number you pass in is valid (greater than 0, less than an unreasonably large 478-- number), the returned date will be valid. 479 480-- julian_day : days since January 1, Year 1. 481-- Returns : a newly-allocated GDate initialized with julian_day. 482 483-- --------------------------------------------------------------------------------- 484 485-- g_date_clear () 486 487-- void g_date_clear (GDate *date, 488-- guint n_dates); 489 490-- Initializes one or more GDate structs to a sane but invalid state. The cleared 491-- dates will not represent an existing date, but will not contain garbage. Useful 492-- to init a date declared on the stack. Validity can be tested with g_date_valid(). 493 494-- date : pointer to one or more dates to clear. 495-- n_dates : number of dates to clear. 496 497-- --------------------------------------------------------------------------------- 498 499-- g_date_free () 500 501-- void g_date_free (GDate *date); 502 503-- Frees a GDate returned from g_date_new(). 504 505-- date : a GDate. 506 507-- --------------------------------------------------------------------------------- 508 509-- g_date_set_day () 510 511-- void g_date_set_day (GDate *date, 512-- GDateDay day); 513 514-- Sets the day of the month for a GDate. If the resulting day-month-year triplet is 515-- invalid, the date will be invalid. 516 517-- date : a GDate. 518-- day : day to set. 519 520-- --------------------------------------------------------------------------------- 521 522-- g_date_set_month () 523 524-- void g_date_set_month (GDate *date, 525-- GDateMonth month); 526 527-- Sets the month of the year for a GDate. If the resulting day-month-year triplet 528-- is invalid, the date will be invalid. 529 530-- date : a GDate. 531-- month : month to set. 532 533-- --------------------------------------------------------------------------------- 534 535-- g_date_set_year () 536 537-- void g_date_set_year (GDate *date, 538-- GDateYear year); 539 540-- Sets the year for a GDate. If the resulting day-month-year triplet is invalid, 541-- the date will be invalid. 542 543-- date : a GDate. 544-- year : year to set. 545 546-- --------------------------------------------------------------------------------- 547 548-- g_date_set_dmy () 549 550-- void g_date_set_dmy (GDate *date, 551-- GDateDay day, 552-- GDateMonth month, 553-- GDateYear y); 554 555-- Sets the value of a GDate from a day, month, and year. The day-month-year triplet 556-- must be valid; if you aren't sure it is, call g_date_valid_dmy() to check before 557-- you set it. 558 559-- date : a GDate. 560-- day : day. 561-- month : month. 562-- y : year. 563 564-- --------------------------------------------------------------------------------- 565 566-- g_date_set_julian () 567 568-- void g_date_set_julian (GDate *date, 569-- guint32 julian_date); 570 571-- Sets the value of a GDate from a Julian day number. 572 573-- date : a GDate. 574-- julian_date : Julian day number (days since January 1, Year 1). 575 576-- --------------------------------------------------------------------------------- 577 578-- g_date_set_time () 579 580-- void g_date_set_time (GDate *date, 581-- GTime time_); 582 583-- Warning 584 585-- g_date_set_time is deprecated and should not be used in newly-written code. 586 587-- Sets the value of a date from a GTime value. 588 589-- Deprecated:2.10: Use g_date_set_time_t() instead. 590 591-- date : a GDate. 592-- time_ : GTime value to set. 593 594-- --------------------------------------------------------------------------------- 595 596-- g_date_set_time_t () 597 598-- void g_date_set_time_t (GDate *date, 599-- time_t timet); 600 601-- Sets the value of a date from a time_t value. 602 603-- To set the value of a date to the current day, you could write: 604 605 606-- g_date_set_time_t (date, time (NULL)); 607 608-- date : a GDate 609-- timet : time_t value to set 610 611-- Since 2.10 612 613-- --------------------------------------------------------------------------------- 614 615-- g_date_set_time_val () 616 617-- void g_date_set_time_val (GDate *date, 618-- GTimeVal *timeval); 619 620-- Sets the value of a date from a GTimeVal value. Note that the tv_usec member is 621-- ignored, because GDate can't make use of the additional precision. 622 623-- date : a GDate 624-- timeval : GTimeVal value to set 625 626-- Since 2.10 627 628-- --------------------------------------------------------------------------------- 629 630-- g_date_set_parse () 631 632-- void g_date_set_parse (GDate *date, 633-- const gchar *str); 634 635-- Parses a user-inputted string str, and try to figure out what date it represents, 636-- taking the current locale into account. If the string is successfully parsed, the 637-- date will be valid after the call. Otherwise, it will be invalid. You should 638-- check using g_date_valid() to see whether the parsing succeeded. 639 640-- This function is not appropriate for file formats and the like; it isn't very 641-- precise, and its exact behavior varies with the locale. It's intended to be a 642-- heuristic routine that guesses what the user means by a given string (and it does 643-- work pretty well in that capacity). 644 645-- date : a GDate to fill in. 646-- str : string to parse. 647 648-- --------------------------------------------------------------------------------- 649 650-- g_date_add_days () 651 652-- void g_date_add_days (GDate *date, 653-- guint n_days); 654 655-- Increments a date some number of days. To move forward by weeks, add weeks*7 656-- days. The date must be valid. 657 658-- date : a GDate to increment. 659-- n_days : number of days to move the date forward. 660 661-- --------------------------------------------------------------------------------- 662 663-- g_date_subtract_days () 664 665-- void g_date_subtract_days (GDate *date, 666-- guint n_days); 667 668-- Moves a date some number of days into the past. To move by weeks, just move by 669-- weeks*7 days. The date must be valid. 670 671-- date : a GDate to decrement. 672-- n_days : number of days to move. 673 674-- --------------------------------------------------------------------------------- 675 676-- g_date_add_months () 677 678-- void g_date_add_months (GDate *date, 679-- guint n_months); 680 681-- Increments a date by some number of months. If the day of the month is greater 682-- than 28, this routine may change the day of the month (because the destination 683-- month may not have the current day in it). The date must be valid. 684 685-- date : a GDate to increment. 686-- n_months : number of months to move forward. 687 688-- --------------------------------------------------------------------------------- 689 690-- g_date_subtract_months () 691 692-- void g_date_subtract_months (GDate *date, 693-- guint n_months); 694 695-- Moves a date some number of months into the past. If the current day of the month 696-- doesn't exist in the destination month, the day of the month may change. The date 697-- must be valid. 698 699-- date : a GDate to decrement. 700-- n_months : number of months to move. 701 702-- --------------------------------------------------------------------------------- 703 704-- g_date_add_years () 705 706-- void g_date_add_years (GDate *date, 707-- guint n_years); 708 709-- Increments a date by some number of years. If the date is February 29, and the 710-- destination year is not a leap year, the date will be changed to February 28. The 711-- date must be valid. 712 713-- date : a GDate to increment. 714-- n_years : number of years to move forward. 715 716-- --------------------------------------------------------------------------------- 717 718-- g_date_subtract_years () 719 720-- void g_date_subtract_years (GDate *date, 721-- guint n_years); 722 723-- Moves a date some number of years into the past. If the current day doesn't exist 724-- in the destination year (i.e. it's February 29 and you move to a non-leap-year) 725-- then the day is changed to February 29. The date must be valid. 726 727-- date : a GDate to decrement. 728-- n_years : number of years to move. 729 730-- --------------------------------------------------------------------------------- 731 732-- g_date_days_between () 733 734-- gint g_date_days_between (const GDate *date1, 735-- const GDate *date2); 736 737-- Computes the number of days between two dates. If date2 is prior to date1, the 738-- returned value is negative. Both dates must be valid. 739 740-- date1 : the first date. 741-- date2 : the second date. 742-- Returns : the number of days between date1 and date2. 743 744-- --------------------------------------------------------------------------------- 745 746-- g_date_compare () 747 748-- gint g_date_compare (const GDate *lhs, 749-- const GDate *rhs); 750 751-- qsort()-style comparsion function for dates. Both dates must be valid. 752 753-- lhs : first date to compare. 754-- rhs : second date to compare. 755-- Returns : 0 for equal, less than zero if lhs is less than rhs, greater than zero 756-- if lhs is greater than rhs. 757 758-- --------------------------------------------------------------------------------- 759 760-- g_date_clamp () 761 762-- void g_date_clamp (GDate *date, 763-- const GDate *min_date, 764-- const GDate *max_date); 765 766-- If date is prior to min_date, sets date equal to min_date. If date falls after 767-- max_date, sets date equal to max_date. Either min_date and max_date may be NULL. 768-- All non-NULL dates must be valid. 769 770-- date : a GDate to clamp. 771-- min_date : minimum accepted value for date. 772-- max_date : maximum accepted value for date. 773 774-- --------------------------------------------------------------------------------- 775 776-- g_date_order () 777 778-- void g_date_order (GDate *date1, 779-- GDate *date2); 780 781-- Checks if date1 is less than or equal to date2, and swap the values if this is 782-- not the case. 783 784-- date1 : the first date. 785-- date2 : the second date. 786 787-- --------------------------------------------------------------------------------- 788 789-- g_date_get_day () 790 791-- GDateDay g_date_get_day (const GDate *date); 792 793-- Returns the day of the month. The date must be valid. 794 795-- date : a GDate to extract the day of the month from. 796-- Returns : day of the month. 797 798-- --------------------------------------------------------------------------------- 799 800-- g_date_get_month () 801 802-- GDateMonth g_date_get_month (const GDate *date); 803 804-- Returns the month of the year. The date must be valid. 805 806-- date : a GDate to get the month from. 807-- Returns : month of the year as a GDateMonth. 808 809-- --------------------------------------------------------------------------------- 810 811-- g_date_get_year () 812 813-- GDateYear g_date_get_year (const GDate *date); 814 815-- Returns the year of a GDate. The date must be valid. 816 817-- date : a GDate. 818-- Returns : year in which the date falls. 819 820-- --------------------------------------------------------------------------------- 821 822-- g_date_get_julian () 823 824-- guint32 g_date_get_julian (const GDate *date); 825 826-- Returns the Julian day or "serial number" of the GDate. The Julian day is simply 827-- the number of days since January 1, Year 1; i.e., January 1, Year 1 is Julian day 828-- 1; January 2, Year 1 is Julian day 2, etc. The date must be valid. 829 830-- date : a GDate to extract the Julian day from. 831-- Returns : Julian day. 832 833-- --------------------------------------------------------------------------------- 834 835-- g_date_get_weekday () 836 837-- GDateWeekday g_date_get_weekday (const GDate *date); 838 839-- Returns the day of the week for a GDate. The date must be valid. 840 841-- date : a GDate. 842-- Returns : day of the week as a GDateWeekday. 843 844-- --------------------------------------------------------------------------------- 845 846-- g_date_get_day_of_year () 847 848-- guint g_date_get_day_of_year (const GDate *date); 849 850-- Returns the day of the year, where Jan 1 is the first day of the year. The date 851-- must be valid. 852 853-- date : a GDate to extract day of year from. 854-- Returns : day of the year. 855 856-- --------------------------------------------------------------------------------- 857 858-- g_date_get_days_in_month () 859 860-- guint8 g_date_get_days_in_month (GDateMonth month, 861-- GDateYear year); 862 863-- Returns the number of days in a month, taking leap years into account. 864 865-- month : month. 866-- year : year. 867-- Returns : number of days in month during the year. 868 869-- --------------------------------------------------------------------------------- 870 871-- g_date_is_first_of_month () 872 873-- gboolean g_date_is_first_of_month (const GDate *date); 874 875-- Returns TRUE if the date is on the first of a month. The date must be valid. 876 877-- date : a GDate to check. 878-- Returns : TRUE if the date is the first of the month. 879 880-- --------------------------------------------------------------------------------- 881 882-- g_date_is_last_of_month () 883 884-- gboolean g_date_is_last_of_month (const GDate *date); 885 886-- Returns TRUE if the date is the last day of the month. The date must be valid. 887 888-- date : a GDate to check. 889-- Returns : TRUE if the date is the last day of the month. 890 891-- --------------------------------------------------------------------------------- 892 893-- g_date_is_leap_year () 894 895-- gboolean g_date_is_leap_year (GDateYear year); 896 897-- Returns TRUE if the year is a leap year. 898 899-- year : year to check. 900-- Returns : TRUE if the year is a leap year. 901 902-- --------------------------------------------------------------------------------- 903 904-- g_date_get_monday_week_of_year () 905 906-- guint g_date_get_monday_week_of_year (const GDate *date); 907 908-- Returns the week of the year, where weeks are understood to start on Monday. If 909-- the date is before the first Monday of the year, return 0. The date must be 910-- valid. 911 912-- date : a GDate. 913-- Returns : week of the year. 914 915-- --------------------------------------------------------------------------------- 916 917-- g_date_get_monday_weeks_in_year () 918 919-- guint8 g_date_get_monday_weeks_in_year (GDateYear year); 920 921-- Returns the number of weeks in the year, where weeks are taken to start on 922-- Monday. Will be 52 or 53. The date must be valid. (Years always have 52 7-day 923-- periods, plus 1 or 2 extra days depending on whether it's a leap year. This 924-- function is basically telling you how many Mondays are in the year, i.e. there 925-- are 53 Mondays if one of the extra days happens to be a Monday.) 926 927-- year : a year. 928-- Returns : number of Mondays in the year. 929 930-- --------------------------------------------------------------------------------- 931 932-- g_date_get_sunday_week_of_year () 933 934-- guint g_date_get_sunday_week_of_year (const GDate *date); 935 936-- Returns the week of the year during which this date falls, if weeks are 937-- understood to being on Sunday. The date must be valid. Can return 0 if the day is 938-- before the first Sunday of the year. 939 940-- date : a GDate. 941-- Returns : week number. 942 943-- --------------------------------------------------------------------------------- 944 945-- g_date_get_sunday_weeks_in_year () 946 947-- guint8 g_date_get_sunday_weeks_in_year (GDateYear year); 948 949-- Returns the number of weeks in the year, where weeks are taken to start on 950-- Sunday. Will be 52 or 53. The date must be valid. (Years always have 52 7-day 951-- periods, plus 1 or 2 extra days depending on whether it's a leap year. This 952-- function is basically telling you how many Sundays are in the year, i.e. there 953-- are 53 Sundays if one of the extra days happens to be a Sunday.) 954 955-- year : year to count weeks in. 956-- Returns : number of weeks. 957 958-- --------------------------------------------------------------------------------- 959 960-- g_date_get_iso8601_week_of_year () 961 962-- guint g_date_get_iso8601_week_of_year (const GDate *date); 963 964-- Returns the week of the year, where weeks are interpreted according to ISO 8601. 965 966-- date : a valid GDate 967-- Returns : ISO 8601 week number of the year. 968 969-- Since 2.6 970 971-- --------------------------------------------------------------------------------- 972 973-- g_date_strftime () 974 975-- gsize g_date_strftime (gchar *s, 976-- gsize slen, 977-- const gchar *format, 978-- const GDate *date); 979 980-- Generates a printed representation of the date, in a locale-specific way. Works 981-- just like the platform's C library strftime() function, but only accepts 982-- date-related formats; time-related formats give undefined results. Date must be 983-- valid. Unlike strftime() (which uses the locale encoding), works on a UTF-8 984-- format string and stores a UTF-8 result. 985 986-- This function does not provide any conversion specifiers in addition to those 987-- implemented by the platform's C library. For example, don't expect that using 988-- g_date_strftime() would make the F provided by the C99 strftime() work on Windows 989-- where the C library only complies to C89. 990 991-- s : destination buffer. 992-- slen : buffer size. 993-- format : format string. 994-- date : valid GDate. 995-- Returns : number of characters written to the buffer, or 0 the buffer was too 996-- small. 997 998-- --------------------------------------------------------------------------------- 999 1000-- g_date_to_struct_tm () 1001 1002-- void g_date_to_struct_tm (const GDate *date, 1003-- struct tm *tm); 1004 1005-- Fills in the date-related bits of a struct tm using the date value. Initializes 1006-- the non-date parts with something sane but meaningless. 1007 1008-- date : a GDate to set the struct tm from. 1009-- tm : struct tm to fill. 1010 1011-- --------------------------------------------------------------------------------- 1012 1013-- g_date_valid () 1014 1015-- gboolean g_date_valid (const GDate *date); 1016 1017-- Returns TRUE if the GDate represents an existing day. The date must not contain 1018-- garbage; it should have been initialized with g_date_clear() if it wasn't 1019-- allocated by one of the g_date_new() variants. 1020 1021-- date : a GDate to check. 1022-- Returns : Whether the date is valid. 1023 1024-- --------------------------------------------------------------------------------- 1025 1026-- g_date_valid_day () 1027 1028-- gboolean g_date_valid_day (GDateDay day); 1029 1030-- Returns TRUE if the day of the month is valid (a day is valid if it's between 1 1031-- and 31 inclusive). 1032 1033-- day : day to check. 1034-- Returns : TRUE if the day is valid. 1035 1036-- --------------------------------------------------------------------------------- 1037 1038-- g_date_valid_month () 1039 1040-- gboolean g_date_valid_month (GDateMonth month); 1041 1042-- Returns TRUE if the month value is valid. The 12 GDateMonth enumeration values 1043-- are the only valid months. 1044 1045-- month : month. 1046-- Returns : TRUE if the month is valid. 1047 1048-- --------------------------------------------------------------------------------- 1049 1050-- g_date_valid_year () 1051 1052-- gboolean g_date_valid_year (GDateYear year); 1053 1054-- Returns TRUE if the year is valid. Any year greater than 0 is valid, though there 1055-- is a 16-bit limit to what GDate will understand. 1056 1057-- year : year. 1058-- Returns : TRUE if the year is valid. 1059 1060-- --------------------------------------------------------------------------------- 1061 1062-- g_date_valid_dmy () 1063 1064-- gboolean g_date_valid_dmy (GDateDay day, 1065-- GDateMonth month, 1066-- GDateYear year); 1067 1068-- Returns TRUE if the day-month-year triplet forms a valid, existing day in the 1069-- range of days GDate understands (Year 1 or later, no more than a few thousand 1070-- years in the future). 1071 1072-- day : day. 1073-- month : month. 1074-- year : year. 1075-- Returns : TRUE if the date is a valid one. 1076 1077-- --------------------------------------------------------------------------------- 1078 1079-- g_date_valid_julian () 1080 1081-- gboolean g_date_valid_julian (guint32 julian_date); 1082 1083-- Returns TRUE if the Julian day is valid. Anything greater than zero is basically 1084-- a valid Julian, though there is a 32-bit limit. 1085 1086-- julian_date : Julian day to check. 1087-- Returns : TRUE if the Julian day is valid. 1088 1089-- --------------------------------------------------------------------------------- 1090 1091-- g_date_valid_weekday () 1092 1093-- gboolean g_date_valid_weekday (GDateWeekday weekday); 1094 1095-- Returns TRUE if the weekday is valid. The 7 GDateWeekday enumeration values are 1096-- the only valid weekdays. 1097 1098-- weekday : weekday. 1099-- Returns : TRUE if the weekday is valid. 1100 1101end -- class GLIB_DATE_AND_TIME_FUNCTIONS