Date

Object Hierarchy:

Description:

[ CCode ( type_id = "G_TYPE_DATE" ) ]
public struct 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 Date the fixed day is January 1, 1 AD. ("Julian" dates in the Date 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.

Namespace: GLib

Package: glib-2.0

Content:

Static methods:

public static uchar get_days_in_month (DateMonth month, DateYear year)
Returns the number of days in a month, taking leap years into account.
public static bool valid_day (DateDay day)
Returns true if the day of the month is valid (a day is valid if it's between 1 and 31 inclusive).
public static bool valid_dmy (DateDay day, DateMonth month, DateYear year)
Returns true if the day-month-year triplet forms a valid, existing day in the range of days Date understands (Year 1 or later, no more than a few thousand years in the future).
public static bool valid_julian (uint julian_date)
Returns true if the Julian day is valid.
public static bool valid_weekday (DateWeekday weekday)
Returns true if the weekday is valid.

Methods:

public void add_days (uint n_days)
Increments a date some number of days.
public void add_months (uint n_months)
Increments a date by some number of months.
public void add_years (uint n_years)
Increments a date by some number of years.
public void clamp (Date min_date, Date max_date)
If this is prior to min_date, sets this equal to min_date.
public void clear (uint n_dates = 1)
Initializes one or more Date structs to a safe but invalid state.
public int compare (Date rhs)
qsort-style comparison function for dates.
public Date? copy ()
Copies a GDate to a newly-allocated GDate.
public int days_between (Date date2)
Computes the number of days between two dates.
public DateDay get_day ()
Returns the day of the month.
public uint get_day_of_year ()
Returns the day of the year, where Jan 1 is the first day of the year.
public uint get_iso8601_week_of_year ()
Returns the week of the year, where weeks are interpreted according to ISO 8601.
public uint get_julian ()
Returns the Julian day or "serial number" of the Date .
public uint get_monday_week_of_year ()
Returns the week of the year, where weeks are understood to start on Monday.
public DateMonth get_month ()
Returns the month of the year.
public uint get_sunday_week_of_year ()
Returns the week of the year during which this date falls, if weeks are understood to begin on Sunday.
public DateWeekday get_weekday ()
Returns the day of the week for a Date.
public DateYear get_year ()
Returns the year of a Date.
public bool is_first_of_month ()
Returns true if the date is on the first of a month.
public bool is_last_of_month ()
Returns true if the date is the last day of the month.
public void order (Date date2)
Checks if this is less than or equal to date2, and swap the values if this is not the case.
public void set_day (DateDay day)
Sets the day of the month for a Date.
public void set_dmy (DateDay day, int month, DateYear y)
Sets the value of a Date from a day, month, and year.
public void set_julian (uint julian_day)
Sets the value of a Date from a Julian day number.
public void set_month (DateMonth month)
Sets the month of the year for a Date.
public void set_parse (string str)
Parses a user-inputted string str, and try to figure out what date it represents, taking the current locale into account.
public void set_time_t (time_t timet)
Sets the value of a date to the date corresponding to a time specified as a time_t.
public void set_time_val (TimeVal timeval)
Sets the value of a date from a TimeVal value.
public void set_year (DateYear year)
Sets the year for a Date.
public size_t strftime (char[] s, string format)
Generates a printed representation of the date, in a locale-specific way.
public void subtract_days (uint n_days)
Moves a date some number of days into the past.
public void subtract_months (uint n_months)
Moves a date some number of months into the past.
public void subtract_years (uint n_years)
Moves a date some number of years into the past.
public void to_time (out Time tm)
Fills in the date-related bits of a struct tm using the this value.
public bool valid ()
Returns true if the Date represents an existing day.