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.
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](running.
- 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](running.
- 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.