Date
- class Date(**kwargs)
- Constructors:
Date()
new() -> GLib.Date
new_dmy(day:int, month:GLib.DateMonth, year:int) -> GLib.Date
new_julian(julian_day:int) -> GLib.Date
Constructors
- class Date
- classmethod new() Date
Allocates a
Date
and initializes it to a safe state. The new date will be cleared (as if you’d calledclear()
) but invalid (it won’t represent an existing day). Free the return value withfree()
.
- classmethod new_dmy(day: int, month: DateMonth, year: int) Date
Create a new
Date
representing the given day-month-year triplet.The triplet you pass in must represent a valid date. Use
valid_dmy()
if needed to validate it. The returnedDate
is guaranteed to be non-None
and valid.- Parameters:
day – day of the month
month – month of the year
year – year
Methods
- class Date
- add_days(n_days: int) None
Increments a date some number of days. To move forward by weeks, add weeks*7 days. The date must be valid.
- Parameters:
n_days – number of days to move the date forward
- add_months(n_months: int) None
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.
- Parameters:
n_months – number of months to move forward
- add_years(n_years: int) None
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.
- Parameters:
n_years – number of years to move forward
- clamp(min_date: Date, max_date: Date) None
If
date
is prior tomin_date
, setsdate
equal tomin_date
. Ifdate
falls aftermax_date
, setsdate
equal tomax_date
. Otherwise,date
is unchanged. Either ofmin_date
andmax_date
may beNone
. All non-None
dates must be valid.- Parameters:
min_date – minimum accepted value for
date
max_date – maximum accepted value for
date
- clear(n_dates: int) None
Initializes one or more
Date
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 withvalid()
.- Parameters:
n_dates – number of dates to clear
- compare(rhs: Date) int
qsort()-style comparison function for dates. Both dates must be valid.
- Parameters:
rhs – second date to compare
- days_between(date2: Date) int
Computes the number of days between two dates. If
date2
is prior todate1
, the returned value is negative. Both dates must be valid.- Parameters:
date2 – the second date
- get_day_of_year() int
Returns the day of the year, where Jan 1 is the first day of the year. The date must be valid.
- get_days_in_month(month: DateMonth, year: int) int
Returns the number of days in a month, taking leap years into account.
- Parameters:
month – month
year – year
- get_iso8601_week_of_year() int
Returns the week of the year, where weeks are interpreted according to ISO 8601.
Added in version 2.6.
- get_julian() int
Returns the Julian day or “serial number” of the
Date
. 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.
- get_monday_week_of_year() int
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.
- get_monday_weeks_in_year(year: int) int
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.)
- Parameters:
year – a year
- get_sunday_week_of_year() int
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.
- get_sunday_weeks_in_year(year: int) int
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.)
- Parameters:
year – year to count weeks in
- get_weekday() DateWeekday
Returns the day of the week for a
Date
. The date must be valid.
- is_first_of_month() bool
Returns
True
if the date is on the first of a month. The date must be valid.
- is_last_of_month() bool
Returns
True
if the date is the last day of the month. The date must be valid.
- is_leap_year(year: int) bool
Returns
True
if the year is a leap year.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.
- Parameters:
year – year to check
- order(date2: Date) None
Checks if
date1
is less than or equal todate2
, and swap the values if this is not the case.- Parameters:
date2 – the second date
- set_day(day: int) None
Sets the day of the month for a
Date
. If the resulting day-month-year triplet is invalid, the date will be invalid.- Parameters:
day – day to set
- set_dmy(day: int, month: DateMonth, y: int) None
Sets the value of a
Date
from a day, month, and year. The day-month-year triplet must be valid; if you aren’t sure it is, callvalid_dmy()
to check before you set it.- Parameters:
day – day
month – month
y – year
- set_julian(julian_date: int) None
Sets the value of a
Date
from a Julian day number.- Parameters:
julian_date – Julian day number (days since January 1, Year 1)
- set_month(month: DateMonth) None
Sets the month of the year for a
Date
. If the resulting day-month-year triplet is invalid, the date will be invalid.- Parameters:
month – month to set
- set_parse(str: str) None
Parses a user-inputted string
str
, and try to figure out what date it represents, taking the [current locale][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 usingvalid()
to see whether the parsing succeeded.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).
- Parameters:
str – string to parse
- set_time(time_: int) None
Sets the value of a date from a
Time
value. The time to date conversion is done using the user’s current timezone.Deprecated since version 2.10: Use
set_time_t()
instead.- Parameters:
time –
Time
value to set.
- set_time_t(timet: int) None
Sets the value of a date to the date corresponding to a time specified as a time_t. The time to date conversion is done using the user’s current timezone.
To set the value of a date to the current day, you could write:
time_t now = time (NULL); if (now == (time_t) -1) // handle the error g_date_set_time_t (date, now);
Added in version 2.10.
- Parameters:
timet – time_t value to set
- set_time_val(timeval: TimeVal) None
Sets the value of a date from a
TimeVal
value. Note that thetv_usec
member is ignored, becauseDate
can’t make use of the additional precision.The time to date conversion is done using the user’s current timezone.
Added in version 2.10.
Deprecated since version 2.62:
TimeVal
is not year-2038-safe. Useset_time_t()
instead.- Parameters:
timeval –
TimeVal
value to set
- set_year(year: int) None
Sets the year for a
Date
. If the resulting day-month-year triplet is invalid, the date will be invalid.- Parameters:
year – year to set
- strftime(s: str, slen: int, format: str, date: Date) int
Generates a printed representation of the date, in a [locale][setlocale]-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.
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
strftime()
would make the ``%F`` provided by the C99 strftime() work on Windows where the C library only complies to C89.- Parameters:
s – destination buffer
slen – buffer size
format – format string
date – valid
Date
- subtract_days(n_days: int) None
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.
- Parameters:
n_days – number of days to move
- subtract_months(n_months: int) None
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.
- Parameters:
n_months – number of months to move
- subtract_years(n_years: int) None
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.
- Parameters:
n_years – number of years to move
- to_struct_tm(tm: None) None
Fills in the date-related bits of a struct tm using the
date
value. Initializes the non-date parts with something safe but meaningless.- Parameters:
tm – struct tm to fill
- valid() bool
Returns
True
if theDate
represents an existing day. The date must not contain garbage; it should have been initialized withclear()
if it wasn’t allocated by one of thenew()
variants.
- valid_day(day: int) bool
Returns
True
if the day of the month is valid (a day is valid if it’s between 1 and 31 inclusive).- Parameters:
day – day to check
- valid_dmy(day: int, month: DateMonth, year: int) bool
Returns
True
if the day-month-year triplet forms a valid, existing day in the range of daysDate
understands (Year 1 or later, no more than a few thousand years in the future).- Parameters:
day – day
month – month
year – year
- valid_julian(julian_date: int) bool
Returns
True
if the Julian day is valid. Anything greater than zero is basically a valid Julian, though there is a 32-bit limit.- Parameters:
julian_date – Julian day to check
- valid_month(month: DateMonth) bool
Returns
True
if the month value is valid. The 12DateMonth
enumeration values are the only valid months.- Parameters:
month – month
- valid_weekday(weekday: DateWeekday) bool
Returns
True
if the weekday is valid. The sevenDateWeekday
enumeration values are the only valid weekdays.- Parameters:
weekday – weekday
Fields
- class Date
- day
The day of the day-month-year representation of the date, as a number between 1 and 31
- dmy
This is set if
day
,month
andyear
are valid
- julian
This bit is set if
julian_days
is valid
- julian_days
The Julian representation of the date
- month
The month of the day-month-year representation of the date, as a number between 1 and 12
- year
The year of the day-month-year representation of the date