![]() |
![]() |
![]() |
GLib Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <glib.h> #define G_TIME_SPAN_DAY #define G_TIME_SPAN_HOUR #define G_TIME_SPAN_MINUTE #define G_TIME_SPAN_SECOND typedef GTimeSpan; GDateTime; GDateTime * g_date_time_new_full (gint year
,gint month
,gint day
,gint hour
,gint minute
,gint second
,const gchar *timezone
); GDateTime * g_date_time_new_from_date (gint year
,gint month
,gint day
); GDateTime * g_date_time_new_from_epoch (gint64 secs
); GDateTime * g_date_time_new_from_timeval (GTimeVal *tv
); GDateTime * g_date_time_new_now (void
); GDateTime * g_date_time_new_utc_now (void
); GDateTime * g_date_time_new_today (void
); GDateTime * g_date_time_copy (const GDateTime *datetime
); GDateTime * g_date_time_ref (GDateTime *datetime
); void g_date_time_unref (GDateTime *datetime
); GDateTime * g_date_time_add (const GDateTime *datetime
,GTimeSpan timespan
); GDateTime * g_date_time_add_days (const GDateTime *datetime
,gint days
); GDateTime * g_date_time_add_full (const GDateTime *datetime
,gint years
,gint months
,gint days
,gint hours
,gint minutes
,gint seconds
); GDateTime * g_date_time_add_hours (const GDateTime *datetime
,gint hours
); GDateTime * g_date_time_add_milliseconds (const GDateTime *datetime
,gint milliseconds
); GDateTime * g_date_time_add_minutes (const GDateTime *datetime
,gint minutes
); GDateTime * g_date_time_add_months (const GDateTime *datetime
,gint months
); GDateTime * g_date_time_add_seconds (const GDateTime *datetime
,gint seconds
); GDateTime * g_date_time_add_weeks (const GDateTime *datetime
,gint weeks
); GDateTime * g_date_time_add_years (const GDateTime *datetime
,gint years
); GTimeSpan g_date_time_difference (const GDateTime *begin
,const GDateTime *end
); gint g_date_time_compare (gconstpointer dt1
,gconstpointer dt2
); gboolean g_date_time_equal (gconstpointer dt1
,gconstpointer dt2
); guint g_date_time_hash (gconstpointer datetime
); gint g_date_time_get_day_of_month (const GDateTime *datetime
); gint g_date_time_get_day_of_week (const GDateTime *datetime
); gint g_date_time_get_day_of_year (const GDateTime *datetime
); void g_date_time_get_dmy (const GDateTime *datetime
,gint *day
,gint *month
,gint *year
); gint g_date_time_get_hour (const GDateTime *datetime
); void g_date_time_get_julian (const GDateTime *datetime
,gint *period
,gint *julian
,gint *hour
,gint *minute
,gint *second
); gint g_date_time_get_microsecond (const GDateTime *datetime
); gint g_date_time_get_millisecond (const GDateTime *datetime
); gint g_date_time_get_minute (const GDateTime *datetime
); gint g_date_time_get_month (const GDateTime *datetime
); gint g_date_time_get_second (const GDateTime *datetime
); GTimeSpan g_date_time_get_utc_offset (const GDateTime *datetime
); const gchar * g_date_time_get_timezone_name (const GDateTime *datetime
); gint g_date_time_get_year (const GDateTime *datetime
); gboolean g_date_time_is_daylight_savings (const GDateTime *datetime
); gboolean g_date_time_is_leap_year (const GDateTime *datetime
); GDateTime * g_date_time_day (const GDateTime *datetime
); GDateTime * g_date_time_to_local (const GDateTime *datetime
); gint64 g_date_time_to_epoch (const GDateTime *datetime
); void g_date_time_to_timeval (const GDateTime *datetime
,GTimeVal *tv
); GDateTime * g_date_time_to_utc (const GDateTime *datetime
); gchar * g_date_time_printf (const GDateTime *datetime
,const gchar *format
);
GDateTime is a structure that combines a date and time into a single structure. It provides many conversion and methods to manipulate dates and times. Time precision is provided down to microseconds.
GDateTime is an immutable object: once it has been created it cannot be modified further. All modifiers will create a new GDateTime.
GDateTime is reference counted: the reference count is increased by calling
g_date_time_ref()
and decreased by calling g_date_time_unref()
. When the
reference count drops to 0, the resources allocated by the GDateTime
structure are released.
Internally, GDateTime uses the Julian Day Number since the initial Julian Period (-4712 BC). However, the public API uses the internationally accepted Gregorian Calendar.
GDateTime is available since GLib 2.26.
#define G_TIME_SPAN_DAY (G_GINT64_CONSTANT (86400000000))
Evaluates to a time span of one day.
Since 2.26
#define G_TIME_SPAN_HOUR (G_GINT64_CONSTANT (3600000000))
Evaluates to a time span of one hour.
Since 2.26
#define G_TIME_SPAN_MINUTE (G_GINT64_CONSTANT (60000000))
Evaluates to a time span of one minute.
Since 2.26
#define G_TIME_SPAN_SECOND (G_GINT64_CONSTANT (1000000))
Evaluates to a time span of one second.
Since 2.26
typedef gint64 GTimeSpan;
A value representing an interval of time, in microseconds.
Since 2.26
typedef struct _GDateTime GDateTime;
GDateTime is an opaque structure whose members cannot be accessed directly.
Since 2.26
GDateTime * g_date_time_new_full (gint year
,gint month
,gint day
,gint hour
,gint minute
,gint second
,const gchar *timezone
);
Creates a new GDateTime using the date and times in the Gregorian calendar.
|
the Gregorian year |
|
the Gregorian month |
|
the day of the Gregorian month |
|
the hour of the day |
|
the minute of the hour |
|
the second of the minute |
|
the Olson's database timezone name, or NULL
for local (e.g. America/New_York). [allow-none]
|
Returns : |
the newly created GDateTime |
Since 2.26
GDateTime * g_date_time_new_from_date (gint year
,gint month
,gint day
);
Creates a new GDateTime using the specified date within the Gregorian calendar.
|
the Gregorian year |
|
the Gregorian month |
|
the day in the Gregorian month |
Returns : |
the newly created GDateTime or NULL if it is outside of
the representable range.
|
Since 2.26
GDateTime * g_date_time_new_from_epoch (gint64 secs
);
Creates a new GDateTime using the time since Jan 1, 1970 specified by t
.
|
|
Returns : |
the newly created GDateTime |
Since 2.26
GDateTime * g_date_time_new_from_timeval (GTimeVal *tv
);
Creates a new GDateTime using the date and time specified by GTimeVal.
Since 2.26
GDateTime * g_date_time_new_now (void
);
Creates a new GDateTime representing the current date and time.
Returns : |
the newly created GDateTime which should be freed with
g_date_time_unref() .
|
Since 2.26
GDateTime * g_date_time_new_utc_now (void
);
Creates a new GDateTime that represents the current instant in Universal Coordinated Time (UTC).
Returns : |
the newly created GDateTime which should be freed with
g_date_time_unref() .
|
Since 2.26
GDateTime * g_date_time_new_today (void
);
Createsa new GDateTime that represents Midnight on the current day.
Returns : |
the newly created GDateTime which should be freed with
g_date_time_unref() .
|
Since 2.26
GDateTime * g_date_time_copy (const GDateTime *datetime
);
Creates a copy of datetime
.
|
a GDateTime |
Returns : |
the newly created GDateTime which should be freed with
g_date_time_unref() .
|
Since 2.26
GDateTime * g_date_time_ref (GDateTime *datetime
);
Atomically increments the reference count of datetime
by one.
Since 2.26
void g_date_time_unref (GDateTime *datetime
);
Atomically decrements the reference count of datetime
by one.
When the reference count reaches zero, the resources allocated by
datetime
are freed
|
a GDateTime |
Since 2.26
GDateTime * g_date_time_add (const GDateTime *datetime
,GTimeSpan timespan
);
Creates a copy of datetime
and adds the specified timespan to the copy.
|
a GDateTime |
|
a GTimeSpan |
Returns : |
the newly created GDateTime which should be freed with
g_date_time_unref() .
|
Since 2.26
GDateTime * g_date_time_add_days (const GDateTime *datetime
,gint days
);
Creates a copy of datetime
and adds the specified number of days to the
copy.
|
a GDateTime |
|
the number of days |
Returns : |
the newly created GDateTime which should be freed with
g_date_time_unref() .
|
Since 2.26
GDateTime * g_date_time_add_full (const GDateTime *datetime
,gint years
,gint months
,gint days
,gint hours
,gint minutes
,gint seconds
);
Creates a new GDateTime adding the specified values to the current date and
time in datetime
.
|
a GDateTime |
|
the number of years to add |
|
the number of months to add |
|
the number of days to add |
|
the number of hours to add |
|
the number of minutes to add |
|
the number of seconds to add |
Returns : |
the newly created GDateTime that should be freed with
g_date_time_unref() .
|
Since 2.26
GDateTime * g_date_time_add_hours (const GDateTime *datetime
,gint hours
);
Creates a copy of datetime
and adds the specified number of hours
|
a GDateTime |
|
the number of hours to add |
Returns : |
the newly created GDateTime which should be freed with
g_date_time_unref() .
|
Since 2.26
GDateTime * g_date_time_add_milliseconds (const GDateTime *datetime
,gint milliseconds
);
Creates a copy of datetime
adding the specified number of milliseconds.
|
a GDateTime |
|
the number of milliseconds to add |
Returns : |
the newly created GDateTime which should be freed with
g_date_time_unref() .
|
Since 2.26
GDateTime * g_date_time_add_minutes (const GDateTime *datetime
,gint minutes
);
Creates a copy of datetime
adding the specified number of minutes.
|
a GDateTime |
|
the number of minutes to add |
Returns : |
the newly created GDateTime which should be freed with
g_date_time_unref() .
|
Since 2.26
GDateTime * g_date_time_add_months (const GDateTime *datetime
,gint months
);
Creates a copy of datetime
and adds the specified number of months to the
copy.
|
a GDateTime |
|
the number of months |
Returns : |
the newly created GDateTime which should be freed with
g_date_time_unref() .
|
Since 2.26
GDateTime * g_date_time_add_seconds (const GDateTime *datetime
,gint seconds
);
Creates a copy of datetime
and adds the specified number of seconds.
|
a GDateTime |
|
the number of seconds to add |
Returns : |
the newly created GDateTime which should be freed with
g_date_time_unref() .
|
Since 2.26
GDateTime * g_date_time_add_weeks (const GDateTime *datetime
,gint weeks
);
Creates a copy of datetime
and adds the specified number of weeks to the
copy.
|
a GDateTime |
|
the number of weeks |
Returns : |
the newly created GDateTime which should be freed with
g_date_time_unref() .
|
Since 2.26
GDateTime * g_date_time_add_years (const GDateTime *datetime
,gint years
);
Creates a copy of datetime
and adds the specified number of years to the
copy.
|
a GDateTime |
|
the number of years |
Returns : |
the newly created GDateTime which should be freed with
g_date_time_unref() .
|
Since 2.26
GTimeSpan g_date_time_difference (const GDateTime *begin
,const GDateTime *end
);
Calculates the known difference in time between begin
and end
.
Since the exact precision cannot always be known due to incomplete historic information, an attempt is made to calculate the difference.
|
a GDateTime |
|
a GDateTime |
Returns : |
the difference between the two GDateTime, as a time span expressed in microseconds. |
Since 2.26
gint g_date_time_compare (gconstpointer dt1
,gconstpointer dt2
);
qsort()
-style comparison for GDateTime's. Both GDateTime<-- -->'s
must be non-NULL
.
|
first GDateTime to compare |
|
second GDateTime to compare |
Returns : |
0 for equal, less than zero if dt1 is less than dt2, greater than zero if dt2 is greator than dt1. |
Since 2.26
gboolean g_date_time_equal (gconstpointer dt1
,gconstpointer dt2
);
Checks to see if dt1
and dt2
are equal.
Equal here means that they represent the same moment after converting them to the same timezone.
Since 2.26
guint g_date_time_hash (gconstpointer datetime
);
Hashes datetime
into a guint, suitable for use within GHashTable.
Since 2.26
gint g_date_time_get_day_of_month (const GDateTime *datetime
);
Retrieves the day of the month represented by datetime
in the gregorian
calendar.
|
a GDateTime |
Returns : |
the day of the month |
Since 2.26
gint g_date_time_get_day_of_week (const GDateTime *datetime
);
Retrieves the day of the week represented by datetime
within the gregorian
calendar. 1 is Sunday, 2 is Monday, etc.
|
a GDateTime |
Returns : |
the day of the week |
Since 2.26
gint g_date_time_get_day_of_year (const GDateTime *datetime
);
Retrieves the day of the year represented by datetime
in the Gregorian
calendar.
|
a GDateTime |
Returns : |
the day of the year |
Since 2.26
void g_date_time_get_dmy (const GDateTime *datetime
,gint *day
,gint *month
,gint *year
);
Retrieves the Gregorian day, month, and year of a given GDateTime.
|
a GDateTime. |
|
the return location for the day of the month, or NULL . [out]
|
|
the return location for the monty of the year, or NULL . [out]
|
|
the return location for the gregorian year, or NULL . [out]
|
Since 2.26
gint g_date_time_get_hour (const GDateTime *datetime
);
Retrieves the hour of the day represented by datetime
|
a GDateTime |
Returns : |
the hour of the day |
Since 2.26
void g_date_time_get_julian (const GDateTime *datetime
,gint *period
,gint *julian
,gint *hour
,gint *minute
,gint *second
);
Retrieves the Julian period, day, hour, minute, and second which datetime
represents in the Julian calendar.
|
a GDateTime |
|
a location for the Julian period. [out] |
|
a location for the day in the Julian period. [out] |
|
a location for the hour of the day. [out] |
|
a location for the minute of the hour. [out] |
|
a location for hte second of the minute. [out] |
Since 2.26
gint g_date_time_get_microsecond (const GDateTime *datetime
);
Retrieves the microsecond of the date represented by datetime
|
a GDateTime |
Returns : |
the microsecond of the second |
Since 2.26
gint g_date_time_get_millisecond (const GDateTime *datetime
);
Retrieves the millisecond of the date represented by datetime
|
a GDateTime |
Returns : |
the millisecond of the second |
Since 2.26
gint g_date_time_get_minute (const GDateTime *datetime
);
Retrieves the minute of the hour represented by datetime
|
a GDateTime |
Returns : |
the minute of the hour |
Since 2.26
gint g_date_time_get_month (const GDateTime *datetime
);
Retrieves the month of the year represented by datetime
in the Gregorian
calendar.
|
a GDateTime |
Returns : |
the month represented by datetime
|
Since 2.26
gint g_date_time_get_second (const GDateTime *datetime
);
Retrieves the second of the minute represented by datetime
|
a GDateTime |
Returns : |
the second represented by datetime
|
Since 2.26
GTimeSpan g_date_time_get_utc_offset (const GDateTime *datetime
);
Retrieves the offset from UTC that the local timezone specified by
datetime
represents.
If datetime
represents UTC time, then the offset is zero.
|
a GDateTime |
Returns : |
the offset, expressed as a time span expressed in microseconds. |
Since 2.26
const gchar * g_date_time_get_timezone_name (const GDateTime *datetime
);
Retrieves the Olson's database timezone name of the timezone specified
by datetime
.
|
a GDateTime |
Returns : |
the name of the timezone. The returned string is owned by the GDateTime and it should not be modified or freed. [transfer none] |
Since 2.26
gint g_date_time_get_year (const GDateTime *datetime
);
Retrieves the year represented by datetime
in the Gregorian calendar.
|
A GDateTime |
Returns : |
the year represented by datetime
|
Since 2.26
gboolean g_date_time_is_daylight_savings (const GDateTime *datetime
);
Determines if datetime
represents a date known to fall within daylight
savings time in the gregorian calendar.
Since 2.26
gboolean g_date_time_is_leap_year (const GDateTime *datetime
);
Determines if datetime
represents a date known to fall within
a leap year in the Gregorian calendar.
Since 2.26
GDateTime * g_date_time_day (const GDateTime *datetime
);
Creates a new GDateTime at Midnight on the date represented by datetime
.
|
a GDateTime |
Returns : |
the newly created GDateTime which should be freed with
g_date_time_unref() .
|
Since 2.26
GDateTime * g_date_time_to_local (const GDateTime *datetime
);
Creates a new GDateTime with datetime
converted to local time.
Since 2.26
gint64 g_date_time_to_epoch (const GDateTime *datetime
);
Converts datetime
into an integer representing seconds since the
Unix epoch
|
a GDateTime |
Returns : |
datetime as seconds since the Unix epoch
|
Since 2.26
void g_date_time_to_timeval (const GDateTime *datetime
,GTimeVal *tv
);
Converts datetime
into a GTimeVal and stores the result into timeval
.
Since 2.26
GDateTime * g_date_time_to_utc (const GDateTime *datetime
);
Creates a new GDateTime that reprents datetime
in Universal coordinated
time.
|
a GDateTime |
Returns : |
the newly created GDateTime which should be freed with
g_date_time_unref() .
|
Since 2.26
gchar * g_date_time_printf (const GDateTime *datetime
,const gchar *format
);
Creates a newly allocated string representing the requested format
.
The following format specifiers are supported:
%a
The abbreviated weekday name according to the current locale.
%A
The full weekday name according to the current locale.
%b
The abbreviated month name according to the current locale.
%B
The full month name according to the current locale.
%d
The day of the month as a decimal number (range 01 to 31).
%e
The day of the month as a decimal number (range 1 to 31).
%F
Equivalent to Y
-m
-d
(the ISO 8601 date format).
%h
Equivalent to b
.
%H
The hour as a decimal number using a 24-hour clock (range 00 to 23).
%I
The hour as a decimal number using a 12-hour clock (range 01 to 12).
%j
The day of the year as a decimal number (range 001 to 366).
%k
The hour (24-hour clock) as a decimal number (range 0 to 23);
single digits are preceded by a blank.
%l
The hour (12-hour clock) as a decimal number (range 1 to 12);
single digits are preceded by a blank.
%m
The month as a decimal number (range 01 to 12).
%M
The minute as a decimal number (range 00 to 59).
%N
The micro-seconds as a decimal number.
%p
Either "AM" or "PM" according to the given time value, or the
corresponding strings for the current locale. Noon is treated
as "PM" and midnight as "AM".
%P
Like %p
but lowercase: "am" or "pm" or a corresponding string for
the current locale.
%r
The time in a.m. or p.m. notation.
%R
The time in 24-hour notation (H
:M
).
%s
The number of seconds since the Epoch, that is, since 1970-01-01
00:00:00 UTC.
%S
The second as a decimal number (range 00 to 60).
%t
A tab character.
%u
The day of the week as a decimal, range 1 to 7, Monday being 1.
%W
The week number of the current year as a decimal number.
%x
The preferred date representation for the current locale without
the time.
%X
The preferred date representation for the current locale without
the date.
%y
The year as a decimal number without the century.
%Y
The year as a decimal number including the century.
%Z
Alphabetic time zone abbreviation (e.g. EDT).
%%% A literal %% character.
|
A GDateTime |
|
a valid UTF-8 string, containing the format for the GDateTime |
Returns : |
a newly allocated string formatted to the requested format or
NULL in the case that there was an error. The string should be freed
with g_free() .
|
Since 2.26