![]() |
![]() |
![]() |
![]() |
<GDate>
Represents a day between January 1, Year 1 and a few thousand years in the future. None of its members should be accessed directly.
If the GDate-struct is obtained from g_date_new()
, it will be safe
to mutate but invalid and thus not safe for calendrical computations.
If it's declared on the stack, it will contain garbage so must be
initialized with g_date_clear()
. g_date_clear()
makes the date invalid
but safe. An invalid date doesn't represent a day, it's "empty." A date
becomes valid after you set it to a Julian day or you set a day, month,
and year.
(define-values () (date:add-days self n-days))
Increments a date some number of days. To move forward by weeks, add weeks*7 days. The date must be valid.
(define-values () (date:add-months self n-months))
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.
(define-values () (date:add-years self n-years))
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.
(define-values () (date:clamp self min-date max-date))
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.
(define-values () (date:clear self n-dates))
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()
.
(define-values (%return) (date:compare self rhs))
qsort()
-style comparison function for dates.
Both dates must be valid.
(define-values (%return) (date:copy self))
Copies a GDate to a newly-allocated GDate. If the input was invalid
(as determined by g_date_valid()
), the invalid state will be copied
as is into the new object.
(define-values (%return) (date:days-between self date2))
Computes the number of days between two dates.
If date2
is prior to date1
, the returned value is negative.
Both dates must be valid.
(define-values (%return) (date:get-day self))
Returns the day of the month. The date must be valid.
(define-values (%return) (date:get-day-of-year self))
Returns the day of the year, where Jan 1 is the first day of the year. The date must be valid.
(define-values (%return) (date:get-iso8601-week-of-year self))
Returns the week of the year, where weeks are interpreted according to ISO 8601.
(define-values (%return) (date:get-julian self))
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.
(define-values (%return) (date:get-monday-week-of-year self))
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.
(define-values (%return) (date:get-month self))
Returns the month of the year. The date must be valid.
(define-values (%return) (date:get-sunday-week-of-year self))
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.
(define-values (%return) (date:get-weekday self))
Returns the day of the week for a GDate. The date must be valid.
(define-values (%return) (date:get-year self))
Returns the year of a GDate. The date must be valid.
(define-values (%return) (date:is-first-of-month? self))
Returns TRUE
if the date is on the first of a month.
The date must be valid.
(define-values (%return) (date:is-last-of-month? self))
Returns TRUE
if the date is the last day of the month.
The date must be valid.
(define-values () (date:order self date2))
Checks if date1
is less than or equal to date2
,
and swap the values if this is not the case.
(define-values () (date:set-day self day))
Sets the day of the month for a GDate. If the resulting day-month-year triplet is invalid, the date will be invalid.
(define-values () (date:set-dmy self day month y))
Sets the value of a GDate from a day, month, and year.
The day-month-year triplet must be valid; if you aren't
sure it is, call g_date_valid_dmy()
to check before you
set it.
(define-values () (date:set-julian self julian-date))
Sets the value of a GDate from a Julian day number.
(define-values () (date:set-month self month))
Sets the month of the year for a GDate. If the resulting day-month-year triplet is invalid, the date will be invalid.
(define-values () (date:set-parse self str))
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 using g_date_valid()
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).
(define-values () (date:set-time self time-))
Sets the value of a date from a GTime value. The time to date conversion is done using the user's current timezone.
(define-values () (date:set-time-t self timet))
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);
(define-values () (date:set-year self year))
Sets the year for a GDate. If the resulting day-month-year triplet is invalid, the date will be invalid.
(define-values () (date:subtract-days self n-days))
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.
(define-values () (date:subtract-months self n-months))
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.
(define-values () (date:subtract-years self n-years))
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.
(define-values () (date:to-struct-tm self tm))
Fills in the date-related bits of a struct tm using the date
value.
Initializes the non-date parts with something safe but meaningless.
(define-values (%return) (date:valid? self))
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.
(define-values (%return) (date:get-days-in-month month year))
Returns the number of days in a month, taking leap years into account.
(define-values (%return) (date:get-monday-weeks-in-year year))
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.)
(define-values (%return) (date:get-sunday-weeks-in-year year))
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.)
(define-values (%return) (date:is-leap-year? year))
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.
(define-values (%return) (date:strftime s slen format date))
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 g_date_strftime()
would
make the \%F provided by the C99 strftime()
work on Windows
where the C library only complies to C89.
(define-values (%return) (date:valid-day? day))
Returns TRUE
if the day of the month is valid (a day is valid if it's
between 1 and 31 inclusive).
(define-values (%return) (date:valid-dmy? day month year))
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).
(define-values (%return) (date:valid-julian? julian-date))
Returns TRUE
if the Julian day is valid. Anything greater than zero
is basically a valid Julian, though there is a 32-bit limit.
(define-values (%return) (date:valid-month? month))
Returns TRUE
if the month value is valid. The 12 GDateMonth
enumeration values are the only valid months.