date.sgml 20.6 KB
Newer Older
Owen Taylor's avatar
Owen Taylor committed
1 2 3 4
<!-- ##### SECTION Title ##### -->
Date and Time Functions

<!-- ##### SECTION Short_Description ##### -->
5
calendrical calculations and miscellaneous time stuff.
Owen Taylor's avatar
Owen Taylor committed
6 7

<!-- ##### SECTION Long_Description ##### -->
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
<para>
The #GDate data structure represents a day between January 1, Year 1,
and sometime a few thousand years in the future (right now it will go
to the year 65535 or so, but g_date_set_parse() only parses up to the
year 8000 or so - just count on "a few thousand"). #GDate is meant to
represent everyday dates, not astronomical dates or historical dates
or ISO timestamps or the like. It extrapolates the current Gregorian
calendar forward and backward in time; there is no attempt to change
the calendar to match time periods or locations. #GDate does not store
time information; it represents a <emphasis>day</emphasis>.
</para>

<para>
The #GDate implementation has several nice features; it is only a
64-bit struct, so storing large numbers of dates is very efficient. It
Matthias Clasen's avatar
Matthias Clasen committed
23
can keep both a Julian and day-month-year representation of the date,
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49
since some calculations are much easier with one representation or the
other. A Julian representation is simply a count of days since some
fixed day in the past; for #GDate the fixed day is January 1, 1 AD.
("Julian" dates in the #GDate API aren't really Julian dates in the
technical sense; technically, Julian dates count from the start of the
Julian period, Jan 1, 4713 BC).
</para>

<para>
#GDate is simple to use. First you need a "blank" date; you can get a
dynamically allocated date from g_date_new(), or you can declare an
automatic variable or array and initialize it to a sane state by
calling g_date_clear(). A cleared date is sane; it's safe to call
g_date_set_dmy() and the other mutator functions to initialize the
value of a cleared date. However, a cleared date is initially
<emphasis>invalid</emphasis>, meaning that it doesn't represent a day
that exists. It is undefined to call any of the date calculation
routines on an invalid date. If you obtain a date from a user or other
unpredictable source, you should check its validity with the
g_date_valid() predicate. g_date_valid() is also used to check for
errors with g_date_set_parse() and other functions that can
fail. Dates can be invalidated by calling g_date_clear() again.
</para>

<para>
<emphasis>It is very important to use the API to access the #GDate
Matthias Clasen's avatar
Matthias Clasen committed
50
struct.</emphasis> Often only the day-month-year or only the Julian
51 52 53 54 55
representation is valid. Sometimes neither is valid. Use the API.
</para>

<para>
GLib doesn't contain any time-manipulation functions; however, there
56 57 58
is a #GTime typedef and a #GTimeVal struct which represents a more 
precise time (with microseconds). You can request the current time as 
a #GTimeVal with g_get_current_time().
Owen Taylor's avatar
Owen Taylor committed
59 60 61
</para>

<!-- ##### SECTION See_Also ##### -->
62 63
<para>

Owen Taylor's avatar
Owen Taylor committed
64 65
</para>

66 67 68
<!-- ##### SECTION Stability_Level ##### -->


69
<!-- ##### MACRO G_USEC_PER_SEC ##### -->
Owen Taylor's avatar
Owen Taylor committed
70
<para>
Havoc Pennington's avatar
Havoc Pennington committed
71 72
Number of microseconds in one second (1 million). This macro is provided for
code readability.
Owen Taylor's avatar
Owen Taylor committed
73 74 75 76 77
</para>



<!-- ##### STRUCT GTimeVal ##### -->
78
<para>
79 80 81
Represents a precise time, with seconds and microseconds. 
Similar to the <structname>struct timeval</structname> returned by 
the <function>gettimeofday()</function> UNIX call.
Owen Taylor's avatar
Owen Taylor committed
82 83
</para>

84 85
@tv_sec: seconds.
@tv_usec: microseconds.
Owen Taylor's avatar
Owen Taylor committed
86 87

<!-- ##### FUNCTION g_get_current_time ##### -->
88
<para>
Owen Taylor's avatar
Owen Taylor committed
89 90
</para>

Tim Janik's avatar
Tim Janik committed
91
@result: 
Owen Taylor's avatar
Owen Taylor committed
92 93 94 95


<!-- ##### FUNCTION g_usleep ##### -->
<para>
Sebastian Wilhelmi's avatar
Sebastian Wilhelmi committed
96 97 98 99 100
Pauses the current thread for the given number of microseconds. There
are 1 million microseconds per second (represented by the
#G_USEC_PER_SEC macro). g_usleep() may have limited precision,
depending on hardware and operating system; don't rely on the exact
length of the sleep.
Owen Taylor's avatar
Owen Taylor committed
101 102
</para>

103
@microseconds: number of microseconds to pause.
Owen Taylor's avatar
Owen Taylor committed
104 105


106 107 108 109 110
<!-- ##### FUNCTION g_time_val_add ##### -->
<para>

</para>

111
@time_: 
112 113 114
@microseconds: 


Matthias Clasen's avatar
Matthias Clasen committed
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133
<!-- ##### FUNCTION g_time_val_from_iso8601 ##### -->
<para>

</para>

@iso_date: 
@time_: 
@Returns: 


<!-- ##### FUNCTION g_time_val_to_iso8601 ##### -->
<para>

</para>

@time_: 
@Returns: 


Owen Taylor's avatar
Owen Taylor committed
134
<!-- ##### STRUCT GDate ##### -->
135 136 137 138 139 140 141 142 143 144
<para>
Represents a day between January 1, Year 1 and a few thousand years in
the future. None of its members should be accessed directly. If the
<structname>GDate</structname> is obtained from g_date_new(), it will
be safe to mutate but invalid and thus not safe for calendrical computations.
If it's declared on the stack, it will contain garbage so must be
initialized with g_date_clear(). g_date_clear() makes the date invalid
but sane. An invalid date doesn't represent a day, it's "empty." A
date becomes valid after you set it to a Julian day or you set a day,
month, and year.
Owen Taylor's avatar
Owen Taylor committed
145 146
</para>

Matthias Clasen's avatar
Matthias Clasen committed
147
@julian_days: the Julian representation of the date
Matthias Clasen's avatar
Matthias Clasen committed
148
@julian: this bit is set if @julian_days is valid
Matthias Clasen's avatar
Matthias Clasen committed
149 150 151 152 153 154
@dmy: this is set if @day, @month and @year are valid
@day: the day of the day-month-year representation of the date, as 
  a number between 1 and 31
@month: the day of the day-month-year representation of the date, as 
  a number between 1 and 12
@year: the day of the day-month-year representation of the date
Owen Taylor's avatar
Owen Taylor committed
155 156

<!-- ##### TYPEDEF GTime ##### -->
157
<para>
158 159 160 161
Simply a replacement for <type>time_t</type>. It has been deprected
since it is <emphasis>not</emphasis> equivalent to <type>time_t</type> 
on 64-bit platforms with a 64-bit <type>time_t</type>. 
Unrelated to #GTimer.
Owen Taylor's avatar
Owen Taylor committed
162 163
</para>

164

165 166 167
<para>
Note that <type>GTime</type> is defined to always be a 32bit integer,
unlike <type>time_t</type> which may be 64bit on some systems. 
Matthias Clasen's avatar
Matthias Clasen committed
168
Therefore, <type>GTime</type> will overflow in the year 2038, and
169 170 171 172 173 174 175 176 177 178 179 180 181 182
you cannot use the address of a <type>GTime</type> variable as argument 
to the UNIX time() function. Instead, do the following:
<informalexample>
<programlisting>
time_t ttime;
GTime gtime;

time (&amp;ttime);
gtime = (GTime)ttime;
</programlisting>
</informalexample>
</para>


Owen Taylor's avatar
Owen Taylor committed
183
<!-- ##### ENUM GDateDMY ##### -->
184 185 186
<para>
This enumeration isn't used in the API, but may be useful if you need
to mark a number as a day, month, or year.
Owen Taylor's avatar
Owen Taylor committed
187 188
</para>

Matthias Clasen's avatar
Matthias Clasen committed
189 190 191
@G_DATE_DAY: a day
@G_DATE_MONTH: a month
@G_DATE_YEAR: a year
Owen Taylor's avatar
Owen Taylor committed
192 193

<!-- ##### TYPEDEF GDateDay ##### -->
194 195 196
<para>
Integer representing a day of the month; between 1 and
31. #G_DATE_BAD_DAY represents an invalid day of the month.
Owen Taylor's avatar
Owen Taylor committed
197 198 199 200
</para>


<!-- ##### ENUM GDateMonth ##### -->
201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218
<para>
Enumeration representing a month; values are #G_DATE_JANUARY,
#G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the invalid value.
</para>

@G_DATE_BAD_MONTH: invalid value.
@G_DATE_JANUARY: January.
@G_DATE_FEBRUARY: February.
@G_DATE_MARCH: March.
@G_DATE_APRIL: April.
@G_DATE_MAY: May.
@G_DATE_JUNE: June.
@G_DATE_JULY: July.
@G_DATE_AUGUST: August.
@G_DATE_SEPTEMBER: September.
@G_DATE_OCTOBER: October.
@G_DATE_NOVEMBER: November.
@G_DATE_DECEMBER: December.
Owen Taylor's avatar
Owen Taylor committed
219 220

<!-- ##### TYPEDEF GDateYear ##### -->
221 222 223 224
<para>
Integer representing a year; #G_DATE_BAD_YEAR is the invalid
value. The year must be 1 or higher; negative (BC) years are not
allowed. The year is represented with four digits.
Owen Taylor's avatar
Owen Taylor committed
225 226 227 228
</para>


<!-- ##### ENUM GDateWeekday ##### -->
229 230 231
<para>
Enumeration representing a day of the week; #G_DATE_MONDAY,
#G_DATE_TUESDAY, etc. #G_DATE_BAD_WEEKDAY is an invalid weekday.
Owen Taylor's avatar
Owen Taylor committed
232 233
</para>

234 235 236 237 238 239 240 241
@G_DATE_BAD_WEEKDAY: invalid value.
@G_DATE_MONDAY: Monday.
@G_DATE_TUESDAY: Tuesday.
@G_DATE_WEDNESDAY: Wednesday.
@G_DATE_THURSDAY: Thursday.
@G_DATE_FRIDAY: Friday.
@G_DATE_SATURDAY: Saturday.
@G_DATE_SUNDAY: Sunday.
Owen Taylor's avatar
Owen Taylor committed
242 243

<!-- ##### MACRO G_DATE_BAD_DAY ##### -->
244 245
<para>
Represents an invalid #GDateDay.
Owen Taylor's avatar
Owen Taylor committed
246 247 248 249 250
</para>



<!-- ##### MACRO G_DATE_BAD_JULIAN ##### -->
251 252
<para>
Represents an invalid Julian day number.
Owen Taylor's avatar
Owen Taylor committed
253 254 255 256 257
</para>



<!-- ##### MACRO G_DATE_BAD_YEAR ##### -->
258 259
<para>
Represents an invalid year.
Owen Taylor's avatar
Owen Taylor committed
260 261 262 263 264
</para>



<!-- ##### FUNCTION g_date_new ##### -->
265 266 267 268
<para>
Allocates a #GDate and initializes it to a sane state. The new date will
be cleared (as if you'd called g_date_clear()) but invalid (it won't
represent an existing day). Free the return value with g_date_free().
Owen Taylor's avatar
Owen Taylor committed
269 270
</para>

271
@Returns: a newly-allocated #GDate.
Owen Taylor's avatar
Owen Taylor committed
272 273 274


<!-- ##### FUNCTION g_date_new_dmy ##### -->
275 276
<para>
Like g_date_new(), but also sets the value of the date. Assuming the
Matthias Clasen's avatar
Matthias Clasen committed
277
day-month-year triplet you pass in represents an existing day, the
278
returned date will be valid.
Owen Taylor's avatar
Owen Taylor committed
279 280
</para>

281 282 283 284
@day: day of the month.
@month: month of the year.
@year: year
@Returns: a newly-allocated #GDate initialized with @day, @month, and @year.
Owen Taylor's avatar
Owen Taylor committed
285 286 287


<!-- ##### FUNCTION g_date_new_julian ##### -->
288 289 290 291
<para>
Like g_date_new(), but also sets the value of the date. Assuming the
Julian day number you pass in is valid (greater than 0, less than an
unreasonably large number), the returned date will be valid.
Owen Taylor's avatar
Owen Taylor committed
292 293
</para>

294 295
@julian_day: days since January 1, Year 1.
@Returns: a newly-allocated #GDate initialized with @julian_day.
Owen Taylor's avatar
Owen Taylor committed
296 297 298


<!-- ##### FUNCTION g_date_clear ##### -->
299 300 301 302 303
<para>
Initializes one or more #GDate structs to a sane but invalid
state. The cleared dates will not represent an existing date, but will
not contain garbage. Useful to init a date declared on the stack.
Validity can be tested with g_date_valid().
Owen Taylor's avatar
Owen Taylor committed
304 305
</para>

306 307
@date: pointer to one or more dates to clear.
@n_dates: number of dates to clear.
Owen Taylor's avatar
Owen Taylor committed
308 309 310


<!-- ##### FUNCTION g_date_free ##### -->
311 312
<para>
Frees a #GDate returned from g_date_new().
Owen Taylor's avatar
Owen Taylor committed
313 314
</para>

315
@date: a #GDate.
Owen Taylor's avatar
Owen Taylor committed
316 317 318


<!-- ##### FUNCTION g_date_set_day ##### -->
319 320 321
<para>
Sets the day of the month for a #GDate. If the resulting day-month-year
triplet is invalid, the date will be invalid.
Owen Taylor's avatar
Owen Taylor committed
322 323
</para>

324 325
@date: a #GDate.
@day: day to set.
Owen Taylor's avatar
Owen Taylor committed
326 327 328


<!-- ##### FUNCTION g_date_set_month ##### -->
329 330 331
<para>
Sets the month of the year for a #GDate.  If the resulting
day-month-year triplet is invalid, the date will be invalid.
Owen Taylor's avatar
Owen Taylor committed
332 333
</para>

334 335
@date: a #GDate.
@month: month to set.
Owen Taylor's avatar
Owen Taylor committed
336 337 338


<!-- ##### FUNCTION g_date_set_year ##### -->
339 340 341
<para>
Sets the year for a #GDate. If the resulting day-month-year triplet is
invalid, the date will be invalid.
Owen Taylor's avatar
Owen Taylor committed
342 343
</para>

344 345
@date: a #GDate.
@year: year to set.
Owen Taylor's avatar
Owen Taylor committed
346 347 348


<!-- ##### FUNCTION g_date_set_dmy ##### -->
349 350 351 352
<para>
Sets the value of a #GDate from a day, month, and year. The day-month-year 
triplet must be valid; if you aren't sure it is, call g_date_valid_dmy() to
check before you set it.
Owen Taylor's avatar
Owen Taylor committed
353 354
</para>

355 356 357 358
@date: a #GDate.
@day: day.
@month: month.
@y: year.
Owen Taylor's avatar
Owen Taylor committed
359 360 361


<!-- ##### FUNCTION g_date_set_julian ##### -->
362 363
<para>
Sets the value of a #GDate from a Julian day number.
Owen Taylor's avatar
Owen Taylor committed
364 365
</para>

366 367
@date: a #GDate.
@julian_date: Julian day number (days since January 1, Year 1).
Owen Taylor's avatar
Owen Taylor committed
368 369 370


<!-- ##### FUNCTION g_date_set_time ##### -->
371
<para>
372

Owen Taylor's avatar
Owen Taylor committed
373 374
</para>

Matthias Clasen's avatar
Matthias Clasen committed
375
@date: 
376
@time_: 
Owen Taylor's avatar
Owen Taylor committed
377 378


Matthias Clasen's avatar
Matthias Clasen committed
379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396
<!-- ##### FUNCTION g_date_set_time_t ##### -->
<para>

</para>

@date: 
@timet: 


<!-- ##### FUNCTION g_date_set_time_val ##### -->
<para>

</para>

@date: 
@timeval: 


Owen Taylor's avatar
Owen Taylor committed
397
<!-- ##### FUNCTION g_date_set_parse ##### -->
398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415
<para>
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. You should check using g_date_valid() to see
whether the parsing succeeded.
</para>

<para>
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).
</para>

@date: a #GDate to fill in.
@str: string to parse.
Owen Taylor's avatar
Owen Taylor committed
416 417 418


<!-- ##### FUNCTION g_date_add_days ##### -->
419 420 421
<para>
Increments a date some number of days. To move forward by weeks, add
weeks*7 days. The date must be valid.
Owen Taylor's avatar
Owen Taylor committed
422 423
</para>

424 425
@date: a #GDate to increment.
@n_days: number of days to move the date forward.
Owen Taylor's avatar
Owen Taylor committed
426 427 428


<!-- ##### FUNCTION g_date_subtract_days ##### -->
429 430 431
<para>
Moves a date some number of days into the past. To move by weeks, just
move by weeks*7 days. The date must be valid.
Owen Taylor's avatar
Owen Taylor committed
432 433
</para>

434 435
@date: a #GDate to decrement.
@n_days: number of days to move.
Owen Taylor's avatar
Owen Taylor committed
436 437 438


<!-- ##### FUNCTION g_date_add_months ##### -->
439 440 441 442 443
<para>
Increments a date by some number of months. If the day of the month is
greater than 28, this routine may change the day of the month (because
the destination month may not have the current day in it). The date
must be valid.
Owen Taylor's avatar
Owen Taylor committed
444 445
</para>

446 447
@date: a #GDate to increment.
@n_months: number of months to move forward.
Owen Taylor's avatar
Owen Taylor committed
448 449 450


<!-- ##### FUNCTION g_date_subtract_months ##### -->
451 452 453 454
<para>
Moves a date some number of months into the past. If the current day of
the month doesn't exist in the destination month, the day of the month
may change. The date must be valid.
Owen Taylor's avatar
Owen Taylor committed
455 456
</para>

457 458
@date: a #GDate to decrement.
@n_months: number of months to move.
Owen Taylor's avatar
Owen Taylor committed
459 460 461


<!-- ##### FUNCTION g_date_add_years ##### -->
462 463 464 465
<para>
Increments a date by some number of years. If the date is February 29,
and the destination year is not a leap year, the date will be changed
to February 28. The date must be valid.
Owen Taylor's avatar
Owen Taylor committed
466 467
</para>

468 469
@date: a #GDate to increment.
@n_years: number of years to move forward.
Owen Taylor's avatar
Owen Taylor committed
470 471 472


<!-- ##### FUNCTION g_date_subtract_years ##### -->
473 474 475 476 477
<para>
Moves a date some number of years into the past. If the current day
doesn't exist in the destination year (i.e. it's February 29 and you
move to a non-leap-year) then the day is changed to February 29. The date
must be valid.
Owen Taylor's avatar
Owen Taylor committed
478 479
</para>

480 481
@date: a #GDate to decrement.
@n_years: number of years to move.
Owen Taylor's avatar
Owen Taylor committed
482 483


484 485
<!-- ##### FUNCTION g_date_days_between ##### -->
<para>
486
Computes the number of days between two dates.
487 488 489 490
If @date2 is prior to @date1, the returned value is negative.
Both dates must be valid.
</para>

491 492 493
@date1: the first date.
@date2: the second date.
@Returns: the number of days between @date1 and @date2.
494 495


Owen Taylor's avatar
Owen Taylor committed
496
<!-- ##### FUNCTION g_date_compare ##### -->
497 498 499
<para>
<function>qsort()</function>-style comparsion function for dates. Both
dates must be valid.
Owen Taylor's avatar
Owen Taylor committed
500 501
</para>

502 503 504 505
@lhs: first date to compare.
@rhs: second date to compare.
@Returns: 0 for equal, less than zero if @lhs is less than @rhs,
greater than zero if @lhs is greater than @rhs.
Owen Taylor's avatar
Owen Taylor committed
506 507


508 509
<!-- ##### FUNCTION g_date_clamp ##### -->
<para>
510 511
If @date is prior to @min_date, sets @date equal to @min_date.
If @date falls after @max_date, sets @date equal to @max_date.
512 513 514 515
Either @min_date and @max_date may be %NULL.  All non-%NULL dates
must be valid.
</para>

516 517 518
@date: a #GDate to clamp.
@min_date: minimum accepted value for @date.
@max_date: maximum accepted value for @date.
519 520 521 522


<!-- ##### FUNCTION g_date_order ##### -->
<para>
523
Checks if @date1 is less than or equal to @date2,
524 525 526
and swap the values if this is not the case.
</para>

527 528
@date1: the first date.
@date2: the second date.
529 530


531
<!-- ##### FUNCTION g_date_get_day ##### -->
532 533
<para>
Returns the day of the month. The date must be valid.
534 535
</para>

536 537
@date: a #GDate to extract the day of the month from.
@Returns: day of the month.
538 539 540


<!-- ##### FUNCTION g_date_get_month ##### -->
541 542
<para>
Returns the month of the year. The date must be valid.
543 544
</para>

545 546
@date: a #GDate to get the month from.
@Returns: month of the year as a #GDateMonth.
547 548 549


<!-- ##### FUNCTION g_date_get_year ##### -->
550 551
<para>
Returns the year of a #GDate. The date must be valid.
552 553
</para>

554 555
@date: a #GDate.
@Returns: year in which the date falls.
556 557 558


<!-- ##### FUNCTION g_date_get_julian ##### -->
559 560 561 562 563
<para>
Returns the Julian day or "serial number" of the #GDate. The
Julian day is simply the number of days since January 1, Year 1; i.e.,
January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2,
etc. The date must be valid.
564 565
</para>

566 567
@date: a #GDate to extract the Julian day from.
@Returns: Julian day.
568 569 570


<!-- ##### FUNCTION g_date_get_weekday ##### -->
571 572
<para>
Returns the day of the week for a #GDate. The date must be valid.
573 574
</para>

575 576
@date: a #GDate.
@Returns: day of the week as a #GDateWeekday.
577 578 579


<!-- ##### FUNCTION g_date_get_day_of_year ##### -->
580 581 582
<para>
Returns the day of the year, where Jan 1 is the first day of the
year. The date must be valid.
583 584
</para>

585 586
@date: a #GDate to extract day of year from.
@Returns: day of the year.
587 588 589


<!-- ##### FUNCTION g_date_get_days_in_month ##### -->
590 591
<para>
Returns the number of days in a month, taking leap years into account.
592 593
</para>

594 595 596
@month: month.
@year: year.
@Returns: number of days in @month during the @year.
597 598


Owen Taylor's avatar
Owen Taylor committed
599
<!-- ##### FUNCTION g_date_is_first_of_month ##### -->
600 601
<para>
Returns %TRUE if the date is on the first of a month. The date must be valid.
Owen Taylor's avatar
Owen Taylor committed
602 603
</para>

604 605
@date: a #GDate to check.
@Returns: %TRUE if the date is the first of the month.
Owen Taylor's avatar
Owen Taylor committed
606 607 608


<!-- ##### FUNCTION g_date_is_last_of_month ##### -->
609 610
<para>
Returns %TRUE if the date is the last day of the month. The date must be valid.
Owen Taylor's avatar
Owen Taylor committed
611 612
</para>

613 614 615
@date: a #GDate to check.
@Returns: %TRUE if the date is the last day of the month.

Owen Taylor's avatar
Owen Taylor committed
616 617

<!-- ##### FUNCTION g_date_is_leap_year ##### -->
618 619
<para>
Returns %TRUE if the year is a leap year.
Owen Taylor's avatar
Owen Taylor committed
620 621
</para>

622 623
@year: year to check.
@Returns: %TRUE if the year is a leap year.
Owen Taylor's avatar
Owen Taylor committed
624 625


626
<!-- ##### FUNCTION g_date_get_monday_week_of_year ##### -->
627 628 629 630
<para>
Returns the week of the year, where weeks are understood to start on
Monday. If the date is before the first Monday of the year, return
0. The date must be valid.
631 632
</para>

633 634
@date: a #GDate.
@Returns: week of the year.
635 636 637


<!-- ##### FUNCTION g_date_get_monday_weeks_in_year ##### -->
638 639 640 641 642 643 644
<para>
Returns the number of weeks in the year, where weeks are taken to start
on Monday. Will be 52 or 53. The date must be valid. (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.)
645 646
</para>

647 648
@year: a year.
@Returns: number of Mondays in the year.
649 650 651


<!-- ##### FUNCTION g_date_get_sunday_week_of_year ##### -->
652 653 654 655
<para>
Returns the week of the year during which this date falls, if weeks 
are understood to being on Sunday. The date must be valid. Can return 0 if 
the day is before the first Sunday of the year.
656 657
</para>

658 659
@date: a #GDate.
@Returns: week number.
660 661 662


<!-- ##### FUNCTION g_date_get_sunday_weeks_in_year ##### -->
663 664 665 666 667 668 669
<para>
Returns the number of weeks in the year, where weeks are taken to start
on Sunday. Will be 52 or 53. The date must be valid. (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.)
670 671
</para>

672 673
@year: year to count weeks in.
@Returns: number of weeks.
674 675


676 677 678 679 680 681 682 683 684
<!-- ##### FUNCTION g_date_get_iso8601_week_of_year ##### -->
<para>

</para>

@date: 
@Returns: 


Owen Taylor's avatar
Owen Taylor committed
685
<!-- ##### FUNCTION g_date_strftime ##### -->
686 687 688 689 690
<para>
Generates a printed representation of the date, in a locale-specific
way. Works just like the standard C <function>strftime()</function>
function, but only accepts date-related formats; time-related formats
give undefined results. Date must be valid.
Owen Taylor's avatar
Owen Taylor committed
691 692
</para>

693 694 695 696 697
@s: destination buffer.
@slen: buffer size.
@format: format string.
@date: valid #GDate.
@Returns: number of characters written to the buffer, or 0 the buffer was too small.
Owen Taylor's avatar
Owen Taylor committed
698 699 700


<!-- ##### FUNCTION g_date_to_struct_tm ##### -->
701 702 703 704
<para>
Fills in the date-related bits of a <structname>struct tm</structname>
using the @date value. Initializes the non-date parts with something
sane but meaningless.
Owen Taylor's avatar
Owen Taylor committed
705 706
</para>

707 708
@date: a #GDate to set the <structname>struct tm</structname> from.
@tm: <structname>struct tm</structname> to fill.
Owen Taylor's avatar
Owen Taylor committed
709 710 711


<!-- ##### FUNCTION g_date_valid ##### -->
712 713 714 715
<para>
Returns %TRUE if the #GDate represents an existing day. The date must not
contain garbage; it should have been initialized with g_date_clear()
if it wasn't allocated by one of the g_date_new() variants.
Owen Taylor's avatar
Owen Taylor committed
716 717
</para>

718
@date: a #GDate to check.
719
@Returns: Whether the date is valid.
Owen Taylor's avatar
Owen Taylor committed
720 721 722


<!-- ##### FUNCTION g_date_valid_day ##### -->
723 724 725
<para>
Returns %TRUE if the day of the month is valid (a day is valid if it's
between 1 and 31 inclusive).
Owen Taylor's avatar
Owen Taylor committed
726 727
</para>

728 729
@day: day to check.
@Returns: %TRUE if the day is valid.
Owen Taylor's avatar
Owen Taylor committed
730 731 732


<!-- ##### FUNCTION g_date_valid_month ##### -->
733 734 735
<para>
Returns %TRUE if the month value is valid. The 12 #GDateMonth
enumeration values are the only valid months.
Owen Taylor's avatar
Owen Taylor committed
736 737
</para>

738 739
@month: month.
@Returns: %TRUE if the month is valid.
Owen Taylor's avatar
Owen Taylor committed
740 741 742


<!-- ##### FUNCTION g_date_valid_year ##### -->
743 744 745
<para>
Returns %TRUE if the year is valid. Any year greater than 0 is valid,
though there is a 16-bit limit to what #GDate will understand.
Owen Taylor's avatar
Owen Taylor committed
746 747
</para>

748 749
@year: year.
@Returns: %TRUE if the year is valid.
Owen Taylor's avatar
Owen Taylor committed
750 751 752


<!-- ##### FUNCTION g_date_valid_dmy ##### -->
753
<para>
Matthias Clasen's avatar
Matthias Clasen committed
754
Returns %TRUE if the day-month-year triplet forms a valid, existing day
755 756
in the range of days #GDate understands (Year 1 or later, no more than
a few thousand years in the future).
Owen Taylor's avatar
Owen Taylor committed
757 758
</para>

759 760 761 762
@day: day.
@month: month.
@year: year.
@Returns: %TRUE if the date is a valid one.
Owen Taylor's avatar
Owen Taylor committed
763 764 765


<!-- ##### FUNCTION g_date_valid_julian ##### -->
766 767 768
<para>
Returns %TRUE if the Julian day is valid. Anything greater than zero is basically a
valid Julian, though there is a 32-bit limit.
Owen Taylor's avatar
Owen Taylor committed
769 770
</para>

771 772
@julian_date: Julian day to check.
@Returns: %TRUE if the Julian day is valid.
Owen Taylor's avatar
Owen Taylor committed
773 774 775


<!-- ##### FUNCTION g_date_valid_weekday ##### -->
776 777 778
<para>
Returns %TRUE if the weekday is valid. The 7 #GDateWeekday enumeration
values are the only valid weekdays.
Owen Taylor's avatar
Owen Taylor committed
779 780
</para>

781 782
@weekday: weekday.
@Returns: %TRUE if the weekday is valid.
Owen Taylor's avatar
Owen Taylor committed
783 784