Date
GDate is a struct for calendrical calculations.
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 method@GLib.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 day.
The GDate implementation has several nice features; it is only a 64-bit struct, so storing large numbers of dates is very efficient. It can keep both a Julian and day-month-year representation of the date, 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).
GDate is simple to use. First you need a "blank" date; you can get a dynamically allocated date from ctor@GLib.Date.new, or you can declare an automatic variable or array and initialize it by calling method@GLib.Date.clear. A cleared date is safe; it's safe to call method@GLib.Date.set_dmy and the other mutator functions to initialize the value of a cleared date. However, a cleared date is initially invalid, 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 method@GLib.Date.valid predicate. method@GLib.Date.valid is also used to check for errors with method@GLib.Date.set_parse and other functions that can fail. Dates can be invalidated by calling method@GLib.Date.clear again.
It is very important to use the API to access the GDate struct. Often only the day-month-year or only the Julian representation is valid. Sometimes neither is valid. Use the API.
GLib also features GDateTime which represents a precise time.
Skipped during bindings generation
parameter
timet: time_tparameter
tm: Unsupported pointer to primitive type
Constructors
Functions
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.
Initializes one or more #GDate structs to a safe 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().
Computes the number of days between two dates. If @date2 is prior to @date1, the returned value is negative. Both dates must be valid.
Returns the day of the year, where Jan 1 is the first day of the year. The date must be valid.
Returns the week of the year, where weeks are interpreted according to ISO 8601.
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.
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.
Returns the week of the year during which this date falls, if weeks are understood to begin on Sunday. The date must be valid. Can return 0 if the day is before the first Sunday of the year.
Returns the day of the week for a #GDate. The date must be valid.
Returns true if the date is on the first of a month. The date must be valid.
Returns true if the date is the last day of the month. The date must be valid.
Parses a user-inputted string @str, and try to figure out what date it represents, taking the setlocale 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.
Sets the value of a date from a #GTimeVal value. Note that the
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.
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.
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.