Class Date
- All Implemented Interfaces:
Proxy
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 setParse(java.lang.String)
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 Date()
, or you can declare an
automatic variable or array and initialize it by calling clear(int)
.
A cleared date is safe; it's safe to call setDmy(org.gnome.glib.DateDay, org.gnome.glib.DateMonth, org.gnome.glib.DateYear)
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 valid()
predicate. valid()
is also used to check for errors with setParse(java.lang.String)
and other functions
that can fail. Dates can be invalidated by calling clear(int)
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.
-
Constructor Summary
ConstructorDescriptionDate()
Allocates aGDate
and initializes it to a safe state.Date
(MemorySegment address) Create a Date proxy instance for the provided memory address. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addDays
(int nDays) Increments a date some number of days.void
addMonths
(int nMonths) Increments a date by some number of months.void
addYears
(int nYears) Increments a date by some number of years.void
If this Date is prior tominDate
, sets this Date equal tominDate
.void
clear
(int nDates) Initializes one or moreGDate
structs to a safe but invalid state.int
qsort()-style comparison function for dates.copy()
Copies a GDate to a newly-allocated GDate.int
daysBetween
(Date date2) Computes the number of days between two dates.static Date
Create a newGDate
representing the given day-month-year triplet.void
free()
Frees aGDate
returned from g_date_new().getDay()
Returns the day of the month.int
Returns the day of the year, where Jan 1 is the first day of the year.static byte
getDaysInMonth
(DateMonth month, DateYear year) Returns the number of days in a month, taking leap years into account.int
Returns the week of the year, where weeks are interpreted according to ISO 8601.int
Returns the Julian day or "serial number" of theGDate
.static MemoryLayout
The memory layout of the native struct.int
Returns the week of the year, where weeks are understood to start on Monday.static byte
getMondayWeeksInYear
(DateYear year) Returns the number of weeks in the year, where weeks are taken to start on Monday.getMonth()
Returns the month of the year.int
Returns the week of the year during which this date falls, if weeks are understood to begin on Sunday.static byte
getSundayWeeksInYear
(DateYear year) Returns the number of weeks in the year, where weeks are taken to start on Sunday.static Type
getType()
Get the GType of the Date classReturns the day of the week for aGDate
.getYear()
Returns the year of aGDate
.boolean
Returnstrue
if the date is on the first of a month.boolean
Returnstrue
if the date is the last day of the month.static boolean
isLeapYear
(DateYear year) Returnstrue
if the year is a leap year.static Date
julian
(int julianDay) Create a newGDate
representing the given Julian date.void
Checks if this Date is less than or equal todate2
, and swap the values if this is not the case.void
Sets the day of the month for aGDate
.void
Sets the value of aGDate
from a day, month, and year.void
setJulian
(int julianDate) Sets the value of aGDate
from a Julian day number.void
Sets the month of the year for aGDate
.void
Parses a user-inputted stringstr
, and try to figure out what date it represents, taking the [current locale][setlocale] into account.void
Deprecated.Use g_date_set_time_t() instead.void
setTimeT
(long timet) Sets the value of a date to the date corresponding to a time specified as a time_t.void
setTimeVal
(TimeVal timeval) Deprecated.GTimeVal
is not year-2038-safe.void
Sets the year for aGDate
.static long
Generates a printed representation of the date, in a [locale][setlocale]-specific way.void
subtractDays
(int nDays) Moves a date some number of days into the past.void
subtractMonths
(int nMonths) Moves a date some number of months into the past.void
subtractYears
(int nYears) Moves a date some number of years into the past.void
Fills in the date-related bits of a struct tm using the this Date value.boolean
valid()
Returnstrue
if theGDate
represents an existing day.static boolean
Returnstrue
if the day of the month is valid (a day is valid if it's between 1 and 31 inclusive).static boolean
Returnstrue
if the day-month-year triplet forms a valid, existing day in the range of daysGDate
understands (Year 1 or later, no more than a few thousand years in the future).static boolean
validJulian
(int julianDate) Returnstrue
if the Julian day is valid.static boolean
validMonth
(DateMonth month) Returnstrue
if the month value is valid.static boolean
validWeekday
(DateWeekday weekday) Returnstrue
if the weekday is valid.static boolean
Returnstrue
if the year is valid.Methods inherited from class io.github.jwharm.javagi.base.ProxyInstance
equals, handle, hashCode
-
Constructor Details
-
Date
Create a Date proxy instance for the provided memory address.- Parameters:
address
- the memory address of the native object
-
Date
public Date()Allocates aGDate
and initializes it to a safe state. The new date will be cleared (as if you'd called g_date_clear()) but invalid (it won't represent an existing day). Free the return value with g_date_free().
-
-
Method Details
-
getType
-
getMemoryLayout
The memory layout of the native struct.- Returns:
- the memory layout
-
dmy
Create a newGDate
representing the given day-month-year triplet.The triplet you pass in must represent a valid date. Use g_date_valid_dmy() if needed to validate it. The returned
GDate
is guaranteed to be non-null
and valid.- Parameters:
day
- day of the monthmonth
- month of the yearyear
- year- Returns:
- a newly-allocated
GDate
initialized withday
,month
, andyear
-
julian
Create a newGDate
representing the given Julian date.The
julianDay
you pass in must be valid. Use g_date_valid_julian() if needed to validate it. The returnedGDate
is guaranteed to be non-null
and valid.- Parameters:
julianDay
- days since January 1, Year 1- Returns:
- a newly-allocated
GDate
initialized withjulianDay
-
getDaysInMonth
-
getMondayWeeksInYear
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- Returns:
- number of Mondays in the year
-
getSundayWeeksInYear
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- Returns:
- the number of weeks in
year
-
isLeapYear
Returnstrue
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- Returns:
true
if the year is a leap year
-
strftime
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.- Parameters:
s
- destination bufferslen
- buffer sizeformat
- format stringdate
- validGDate
- Returns:
- number of characters written to the buffer, or 0 the buffer was too small
-
validDay
Returnstrue
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- Returns:
true
if the day is valid
-
validDmy
Returnstrue
if the day-month-year triplet forms a valid, existing day in the range of daysGDate
understands (Year 1 or later, no more than a few thousand years in the future).- Parameters:
day
- daymonth
- monthyear
- year- Returns:
true
if the date is a valid one
-
validJulian
public static boolean validJulian(int julianDate) Returnstrue
if the Julian day is valid. Anything greater than zero is basically a valid Julian, though there is a 32-bit limit.- Parameters:
julianDate
- Julian day to check- Returns:
true
if the Julian day is valid
-
validMonth
Returnstrue
if the month value is valid. The 12GDateMonth
enumeration values are the only valid months.- Parameters:
month
- month- Returns:
true
if the month is valid
-
validWeekday
Returnstrue
if the weekday is valid. The sevenGDateWeekday
enumeration values are the only valid weekdays.- Parameters:
weekday
- weekday- Returns:
true
if the weekday is valid
-
validYear
Returnstrue
if the year is valid. Any year greater than 0 is valid, though there is a 16-bit limit to whatGDate
will understand.- Parameters:
year
- year- Returns:
true
if the year is valid
-
addDays
public void addDays(int nDays) Increments a date some number of days. To move forward by weeks, add weeks*7 days. The date must be valid.- Parameters:
nDays
- number of days to move the date forward
-
addMonths
public void addMonths(int nMonths) 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:
nMonths
- number of months to move forward
-
addYears
public void addYears(int nYears) 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:
nYears
- number of years to move forward
-
clamp
If this Date is prior tominDate
, sets this Date equal tominDate
. If this Date falls aftermaxDate
, sets this Date equal tomaxDate
. Otherwise, this Date is unchanged. Either ofminDate
andmaxDate
may benull
. All non-null
dates must be valid.- Parameters:
minDate
- minimum accepted value for this DatemaxDate
- maximum accepted value for this Date
-
clear
public void clear(int nDates) Initializes one or moreGDate
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().- Parameters:
nDates
- number of dates to clear
-
compare
qsort()-style comparison function for dates. Both dates must be valid.- Parameters:
rhs
- second date to compare- Returns:
- 0 for equal, less than zero if this Date is less than
rhs
, greater than zero if this Date is greater thanrhs
-
copy
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.- Returns:
- a newly-allocated
GDate
initialized from this Date
-
daysBetween
Computes the number of days between two dates. Ifdate2
is prior to this Date, the returned value is negative. Both dates must be valid.- Parameters:
date2
- the second date- Returns:
- the number of days between this Date and
date2
-
free
public void free()Frees aGDate
returned from g_date_new(). -
getDay
Returns the day of the month. The date must be valid.- Returns:
- day of the month
-
getDayOfYear
public int getDayOfYear()Returns the day of the year, where Jan 1 is the first day of the year. The date must be valid.- Returns:
- day of the year
-
getIso8601WeekOfYear
public int getIso8601WeekOfYear()Returns the week of the year, where weeks are interpreted according to ISO 8601.- Returns:
- ISO 8601 week number of the year.
-
getJulian
public int getJulian()Returns the Julian day or "serial number" of theGDate
. 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:
- Julian day
-
getMondayWeekOfYear
public int getMondayWeekOfYear()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:
- week of the year
-
getMonth
Returns the month of the year. The date must be valid.- Returns:
- month of the year as a
GDateMonth
-
getSundayWeekOfYear
public int getSundayWeekOfYear()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:
- week number
-
getWeekday
Returns the day of the week for aGDate
. The date must be valid.- Returns:
- day of the week as a
GDateWeekday
.
-
getYear
Returns the year of aGDate
. The date must be valid.- Returns:
- year in which the date falls
-
isFirstOfMonth
public boolean isFirstOfMonth()Returnstrue
if the date is on the first of a month. The date must be valid.- Returns:
true
if the date is the first of the month
-
isLastOfMonth
public boolean isLastOfMonth()Returnstrue
if the date is the last day of the month. The date must be valid.- Returns:
true
if the date is the last day of the month
-
order
Checks if this Date is less than or equal todate2
, and swap the values if this is not the case.- Parameters:
date2
- the second date
-
setDay
Sets the day of the month for aGDate
. If the resulting day-month-year triplet is invalid, the date will be invalid.- Parameters:
day
- day to set
-
setDmy
-
setJulian
public void setJulian(int julianDate) Sets the value of aGDate
from a Julian day number.- Parameters:
julianDate
- Julian day number (days since January 1, Year 1)
-
setMonth
Sets the month of the year for aGDate
. If the resulting day-month-year triplet is invalid, the date will be invalid.- Parameters:
month
- month to set
-
setParse
Parses a user-inputted stringstr
, 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).
- Parameters:
str
- string to parse
-
setTime
Deprecated.Use g_date_set_time_t() instead.Sets the value of a date from aGTime
value. The time to date conversion is done using the user's current timezone.- Parameters:
time
-GTime
value to set.
-
setTimeT
public void setTimeT(long 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);
- Parameters:
timet
- time_t value to set
-
setTimeVal
Deprecated.GTimeVal
is not year-2038-safe. Use g_date_set_time_t() instead.Sets the value of a date from aGTimeVal
value. Note that thetvUsec
member is ignored, becauseGDate
can't make use of the additional precision.The time to date conversion is done using the user's current timezone.
- Parameters:
timeval
-GTimeVal
value to set
-
setYear
Sets the year for aGDate
. If the resulting day-month-year triplet is invalid, the date will be invalid.- Parameters:
year
- year to set
-
subtractDays
public void subtractDays(int nDays) 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:
nDays
- number of days to move
-
subtractMonths
public void subtractMonths(int nMonths) 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:
nMonths
- number of months to move
-
subtractYears
public void subtractYears(int nYears) 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:
nYears
- number of years to move
-
toStructTm
Fills in the date-related bits of a struct tm using the this Date value. Initializes the non-date parts with something safe but meaningless.- Parameters:
tm
- struct tm to fill
-
valid
public boolean valid()Returnstrue
if theGDate
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.- Returns:
- Whether the date is valid
-