date.sgml

This GLib version 2.16.1. GLib is the low-level core library that forms the basis for projects such

represents, taking the <link linkend="setlocale">current locale</link> 
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


<!-- ##### FUNCTION g_date_add_days ##### -->
<para>
Increments a date some number of days. To move forward by weeks, add
weeks*7 days. The date must be valid.
</para>

@date: a #GDate to increment
@n_days: number of days to move the date forward


<!-- ##### FUNCTION g_date_subtract_days ##### -->
<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.
</para>

@date: a #GDate to decrement
@n_days: number of days to move


<!-- ##### FUNCTION g_date_add_months ##### -->
<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.
</para>

@date: a #GDate to increment
@n_months: number of months to move forward


<!-- ##### FUNCTION g_date_subtract_months ##### -->
<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.
</para>

@date: a #GDate to decrement
@n_months: number of months to move


<!-- ##### FUNCTION g_date_add_years ##### -->
<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.
</para>

@date: a #GDate to increment
@n_years: number of years to move forward


<!-- ##### FUNCTION g_date_subtract_years ##### -->
<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.
</para>

@date: a #GDate to decrement
@n_years: number of years to move


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

@date1: the first date
@date2: the second date
@Returns: the number of days between @date1 and @date2


<!-- ##### FUNCTION g_date_compare ##### -->
<para>
qsort()-style comparsion function for dates. Both
dates must be valid.
</para>

@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


<!-- ##### FUNCTION g_date_clamp ##### -->
<para>
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.
Otherwise, @date is unchanged.
Either of @min_date and @max_date may be %NULL.  All non-%NULL dates
must be valid.
</para>

@date: a #GDate to clamp
@min_date: minimum accepted value for @date
@max_date: maximum accepted value for @date


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

@date1: the first date
@date2: the second date


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

@date: a #GDate to extract the day of the month from
@Returns: day of the month


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

@date: a #GDate to get the month from
@Returns: month of the year as a #GDateMonth


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

@date: a #GDate
@Returns: year in which the date falls


<!-- ##### FUNCTION g_date_get_julian ##### -->
<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.
</para>

@date: a #GDate to extract the Julian day from
@Returns: Julian day


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

@date: a #GDate.
@Returns: day of the week as a #GDateWeekday.


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

@date: a #GDate to extract day of year from
@Returns: day of the year


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

@month: month
@year: year
@Returns: number of days in @month during the @year


<!-- ##### FUNCTION g_date_is_first_of_month ##### -->
<para>
Returns %TRUE if the date is on the first of a month. The date must be valid.
</para>

@date: a #GDate to check
@Returns: %TRUE if the date is the first of the month


<!-- ##### FUNCTION g_date_is_last_of_month ##### -->
<para>
Returns %TRUE if the date is the last day of the month. The date must be valid.
</para>

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


<!-- ##### FUNCTION g_date_is_leap_year ##### -->
<para>
Returns %TRUE if the year is a leap year.<footnote><para>
For the purposes of this function, leap year is every year divisible by
4 unless that year is divisible by 100. If it is divisible by 100 it would 
be a leap year only if that year is also divisible by 400.</para></footnote>
</para>

@year: year to check
@Returns: %TRUE if the year is a leap year


<!-- ##### FUNCTION g_date_get_monday_week_of_year ##### -->
<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.
</para>

@date: a #GDate
@Returns: week of the year


<!-- ##### FUNCTION g_date_get_monday_weeks_in_year ##### -->
<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.)
</para>

@year: a year
@Returns: number of Mondays in the year


<!-- ##### FUNCTION g_date_get_sunday_week_of_year ##### -->
<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.
</para>

@date: a #GDate
@Returns: week number


<!-- ##### FUNCTION g_date_get_sunday_weeks_in_year ##### -->
<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.)
</para>

@year: year to count weeks in
@Returns: number of weeks


<!-- ##### FUNCTION g_date_get_iso8601_week_of_year ##### -->
<para>

</para>

@date: 
@Returns: 


<!-- ##### FUNCTION g_date_strftime ##### -->
<para>
Generates a printed representation of the date, in a 
<link linkend="setlocale">locale</link>-specific way. Works just like 
the platform's C library strftime() function, but only accepts date-related 
formats; time-related formats give undefined results. Date must be valid. 
Unlike strftime() (which uses the locale encoding), works on a UTF-8 format 
string and stores a UTF-8 result.
</para>

<para>
This function does not provide any conversion specifiers in addition
to those implemented by the platform's C library. For example, don't
expect that using g_date_strftime() would make the %F provided by the C99 
strftime() work on Windows where the C library only complies to C89.
</para>

@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


<!-- ##### FUNCTION g_date_to_struct_tm ##### -->
<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.
</para>

@date: a #GDate to set the <structname>struct tm</structname> from.
@tm: <structname>struct tm</structname> to fill.


<!-- ##### FUNCTION g_date_valid ##### -->
<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.
</para>

@date: a #GDate to check
@Returns: Whether the date is valid


<!-- ##### FUNCTION g_date_valid_day ##### -->
<para>
Returns %TRUE if the day of the month is valid (a day is valid if it's
between 1 and 31 inclusive).
</para>

@day: day to check
@Returns: %TRUE if the day is valid


<!-- ##### FUNCTION g_date_valid_month ##### -->
<para>
Returns %TRUE if the month value is valid. The 12 #GDateMonth
enumeration values are the only valid months.
</para>

@month: month
@Returns: %TRUE if the month is valid


<!-- ##### FUNCTION g_date_valid_year ##### -->
<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.
</para>

@year: year
@Returns: %TRUE if the year is valid


<!-- ##### FUNCTION g_date_valid_dmy ##### -->
<para>
Returns %TRUE if the day-month-year triplet forms a valid, existing day
in the range of days #GDate understands (Year 1 or later, no more than
a few thousand years in the future).
</para>

@day: day
@month: month
@year: year
@Returns: %TRUE if the date is a valid one


<!-- ##### FUNCTION g_date_valid_julian ##### -->
<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.
</para>

@julian_date: Julian day to check
@Returns: %TRUE if the Julian day is valid


<!-- ##### FUNCTION g_date_valid_weekday ##### -->
<para>
Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration
values are the only valid weekdays.
</para>

@weekday: weekday
@Returns: %TRUE if the weekday is valid