PageRenderTime 54ms CodeModel.GetById 15ms app.highlight 18ms RepoModel.GetById 2ms app.codeStats 1ms

/src/wrappers/glib/library/utilities/glib_date_and_time_functions.e

http://github.com/tybor/Liberty
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