Date and Time Functions

Date and Time Functions

Synopsis


#include <glib.h>

#define             G_USEC_PER_SEC
                    GTimeVal;
void                g_get_current_time                  (GTimeVal *result);
void                g_usleep                            (gulong microseconds);
void                g_time_val_add                      (GTimeVal *time_,
                                                         glong microseconds);
gboolean            g_time_val_from_iso8601             (const gchar *iso_date,
                                                         GTimeVal *time_);
gchar*              g_time_val_to_iso8601               (GTimeVal *time_);

gint64              g_get_monotonic_time                (void);
gint64              g_get_real_time                     (void);

                    GDate;
typedef             GTime;
enum                GDateDMY;
typedef             GDateDay;
enum                GDateMonth;
typedef             GDateYear;
enum                GDateWeekday;

#define             G_DATE_BAD_DAY
#define             G_DATE_BAD_JULIAN
#define             G_DATE_BAD_YEAR

GDate*              g_date_new                          (void);
GDate*              g_date_new_dmy                      (GDateDay day,
                                                         GDateMonth month,
                                                         GDateYear year);
GDate*              g_date_new_julian                   (guint32 julian_day);
void                g_date_clear                        (GDate *date,
                                                         guint n_dates);
void                g_date_free                         (GDate *date);

void                g_date_set_day                      (GDate *date,
                                                         GDateDay day);
void                g_date_set_month                    (GDate *date,
                                                         GDateMonth month);
void                g_date_set_year                     (GDate *date,
                                                         GDateYear year);
void                g_date_set_dmy                      (GDate *date,
                                                         GDateDay day,
                                                         GDateMonth month,
                                                         GDateYear y);
void                g_date_set_julian                   (GDate *date,
                                                         guint32 julian_date);
void                g_date_set_time                     (GDate *date,
                                                         GTime time_);
void                g_date_set_time_t                   (GDate *date,
                                                         time_t timet);
void                g_date_set_time_val                 (GDate *date,
                                                         GTimeVal *timeval);
void                g_date_set_parse                    (GDate *date,
                                                         const gchar *str);

void                g_date_add_days                     (GDate *date,
                                                         guint n_days);
void                g_date_subtract_days                (GDate *date,
                                                         guint n_days);
void                g_date_add_months                   (GDate *date,
                                                         guint n_months);
void                g_date_subtract_months              (GDate *date,
                                                         guint n_months);
void                g_date_add_years                    (GDate *date,
                                                         guint n_years);
void                g_date_subtract_years               (GDate *date,
                                                         guint n_years);
gint                g_date_days_between                 (const GDate *date1,
                                                         const GDate *date2);
gint                g_date_compare                      (const GDate *lhs,
                                                         const GDate *rhs);
void                g_date_clamp                        (GDate *date,
                                                         const GDate *min_date,
                                                         const GDate *max_date);
void                g_date_order                        (GDate *date1,
                                                         GDate *date2);

GDateDay            g_date_get_day                      (const GDate *date);
GDateMonth          g_date_get_month                    (const GDate *date);
GDateYear           g_date_get_year                     (const GDate *date);
guint32             g_date_get_julian                   (const GDate *date);
GDateWeekday        g_date_get_weekday                  (const GDate *date);
guint               g_date_get_day_of_year              (const GDate *date);

guint8              g_date_get_days_in_month            (GDateMonth month,
                                                         GDateYear year);
gboolean            g_date_is_first_of_month            (const GDate *date);
gboolean            g_date_is_last_of_month             (const GDate *date);
gboolean            g_date_is_leap_year                 (GDateYear year);
guint               g_date_get_monday_week_of_year      (const GDate *date);
guint8              g_date_get_monday_weeks_in_year     (GDateYear year);
guint               g_date_get_sunday_week_of_year      (const GDate *date);
guint8              g_date_get_sunday_weeks_in_year     (GDateYear year);
guint               g_date_get_iso8601_week_of_year     (const GDate *date);

gsize               g_date_strftime                     (gchar *s,
                                                         gsize slen,
                                                         const gchar *format,
                                                         const GDate *date);
void                g_date_to_struct_tm                 (const GDate *date,
                                                         struct tm *tm);

gboolean            g_date_valid                        (const GDate *date);
gboolean            g_date_valid_day                    (GDateDay day);
gboolean            g_date_valid_month                  (GDateMonth month);
gboolean            g_date_valid_year                   (GDateYear year);
gboolean            g_date_valid_dmy                    (GDateDay day,
                                                         GDateMonth month,
                                                         GDateYear year);
gboolean            g_date_valid_julian                 (guint32 julian_date);
gboolean            g_date_valid_weekday                (GDateWeekday weekday);

Description

Details

G_USEC_PER_SEC

#define G_USEC_PER_SEC 1000000


GTimeVal

typedef struct {
  glong tv_sec;
  glong tv_usec;
} GTimeVal;


g_get_current_time ()

void                g_get_current_time                  (GTimeVal *result);

Equivalent to the UNIX gettimeofday() function, but portable.

You may find g_get_real_time() to be more convenient.

result :

GTimeVal structure in which to store current time.

g_usleep ()

void                g_usleep                            (gulong microseconds);

microseconds :


g_time_val_add ()

void                g_time_val_add                      (GTimeVal *time_,
                                                         glong microseconds);

Adds the given number of microseconds to time_. microseconds can also be negative to decrease the value of time_.

time_ :

a GTimeVal

microseconds :

number of microseconds to add to time

g_time_val_from_iso8601 ()

gboolean            g_time_val_from_iso8601             (const gchar *iso_date,
                                                         GTimeVal *time_);

Converts a string containing an ISO 8601 encoded date and time to a GTimeVal and puts it into time_.

iso_date :

an ISO 8601 encoded date string

time_ :

a GTimeVal

Returns :

TRUE if the conversion was successful.

Since 2.12


g_time_val_to_iso8601 ()

gchar*              g_time_val_to_iso8601               (GTimeVal *time_);

Converts time_ into an ISO 8601 encoded string, relative to the Coordinated Universal Time (UTC).

time_ :

a GTimeVal

Returns :

a newly allocated string containing an ISO 8601 date

Since 2.12


g_get_monotonic_time ()

gint64              g_get_monotonic_time                (void);

Queries the system monotonic time, if available.

On POSIX systems with clock_gettime() and CLOCK_MONOTONIC this call is a very shallow wrapper for that. Otherwise, we make a best effort that probably involves returning the wall clock time (with at least microsecond accuracy, subject to the limitations of the OS kernel).

Note that, on Windows, "limitations of the OS kernel" is a rather substantial statement. Depending on the configuration of the system, the wall clock time is updated as infrequently as 64 times a second (which is approximately every 16ms).

Returns :

the monotonic time, in microseconds

Since 2.28


g_get_real_time ()

gint64              g_get_real_time                     (void);

Queries the system wall-clock time.

This call is functionally equivalent to g_get_current_time() except that the return value is often more convenient than dealing with a GTimeVal.

You should only use this call if you are actually interested in the real wall-clock time. g_get_monotonic_time() is probably more useful for measuring intervals.

Returns :

the number of microseconds since January 1, 1970 UTC.

Since 2.28


GDate

typedef struct {
  guint julian_days : 32; /* julian days representation - we use a
                           *  bitfield hoping that 64 bit platforms
                           *  will pack this whole struct in one big
                           *  int
                           */

  guint julian : 1;    /* julian is valid */
  guint dmy    : 1;    /* dmy is valid */

  /* DMY representation */
  guint day    : 6;
  guint month  : 4;
  guint year   : 16;
} GDate;


GTime

typedef gint32  GTime;


enum GDateDMY

typedef enum
{
  G_DATE_DAY   = 0,
  G_DATE_MONTH = 1,
  G_DATE_YEAR  = 2
} GDateDMY;


GDateDay

typedef guint8  GDateDay;   /* day of the month */


enum GDateMonth

typedef enum
{
  G_DATE_BAD_MONTH = 0,
  G_DATE_JANUARY   = 1,
  G_DATE_FEBRUARY  = 2,
  G_DATE_MARCH     = 3,
  G_DATE_APRIL     = 4,
  G_DATE_MAY       = 5,
  G_DATE_JUNE      = 6,
  G_DATE_JULY      = 7,
  G_DATE_AUGUST    = 8,
  G_DATE_SEPTEMBER = 9,
  G_DATE_OCTOBER   = 10,
  G_DATE_NOVEMBER  = 11,
  G_DATE_DECEMBER  = 12
} GDateMonth;


GDateYear

typedef guint16 GDateYear;


enum GDateWeekday

typedef enum
{
  G_DATE_BAD_WEEKDAY  = 0,
  G_DATE_MONDAY       = 1,
  G_DATE_TUESDAY      = 2,
  G_DATE_WEDNESDAY    = 3,
  G_DATE_THURSDAY     = 4,
  G_DATE_FRIDAY       = 5,
  G_DATE_SATURDAY     = 6,
  G_DATE_SUNDAY       = 7
} GDateWeekday;


G_DATE_BAD_DAY

#define G_DATE_BAD_DAY    0U


G_DATE_BAD_JULIAN

#define G_DATE_BAD_JULIAN 0U


G_DATE_BAD_YEAR

#define G_DATE_BAD_YEAR   0U


g_date_new ()

GDate*              g_date_new                          (void);

Returns :


g_date_new_dmy ()

GDate*              g_date_new_dmy                      (GDateDay day,
                                                         GDateMonth month,
                                                         GDateYear year);

day :

month :

year :

Returns :


g_date_new_julian ()

GDate*              g_date_new_julian                   (guint32 julian_day);

julian_day :

Returns :


g_date_clear ()

void                g_date_clear                        (GDate *date,
                                                         guint n_dates);

date :

n_dates :


g_date_free ()

void                g_date_free                         (GDate *date);

date :


g_date_set_day ()

void                g_date_set_day                      (GDate *date,
                                                         GDateDay day);

date :

day :


g_date_set_month ()

void                g_date_set_month                    (GDate *date,
                                                         GDateMonth month);

date :

month :


g_date_set_year ()

void                g_date_set_year                     (GDate *date,
                                                         GDateYear year);

date :

year :


g_date_set_dmy ()

void                g_date_set_dmy                      (GDate *date,
                                                         GDateDay day,
                                                         GDateMonth month,
                                                         GDateYear y);

date :

day :

month :

y :


g_date_set_julian ()

void                g_date_set_julian                   (GDate *date,
                                                         guint32 julian_date);

date :

julian_date :


g_date_set_time ()

void                g_date_set_time                     (GDate *date,
                                                         GTime time_);

Warning

g_date_set_time has been deprecated since version 2.10 and should not be used in newly-written code. Use g_date_set_time_t() instead.

Sets the value of a date from a GTime value. The time to date conversion is done using the user's current timezone.

date :

a GDate.

time_ :

GTime value to set.

g_date_set_time_t ()

void                g_date_set_time_t                   (GDate *date,
                                                         time_t 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:

 g_date_set_time_t (date, time (NULL)); 

date :

a GDate

timet :

time_t value to set

Since 2.10


g_date_set_time_val ()

void                g_date_set_time_val                 (GDate *date,
                                                         GTimeVal *timeval);

Sets the value of a date from a GTimeVal value. Note that the tv_usec member is ignored, because GDate can't make use of the additional precision.

The time to date conversion is done using the user's current timezone.

date :

a GDate

timeval :

GTimeVal value to set

Since 2.10


g_date_set_parse ()

void                g_date_set_parse                    (GDate *date,
                                                         const gchar *str);

date :

str :


g_date_add_days ()

void                g_date_add_days                     (GDate *date,
                                                         guint n_days);

date :

n_days :


g_date_subtract_days ()

void                g_date_subtract_days                (GDate *date,
                                                         guint n_days);

date :

n_days :


g_date_add_months ()

void                g_date_add_months                   (GDate *date,
                                                         guint n_months);

date :

n_months :


g_date_subtract_months ()

void                g_date_subtract_months              (GDate *date,
                                                         guint n_months);

date :

n_months :


g_date_add_years ()

void                g_date_add_years                    (GDate *date,
                                                         guint n_years);

date :

n_years :


g_date_subtract_years ()

void                g_date_subtract_years               (GDate *date,
                                                         guint n_years);

date :

n_years :


g_date_days_between ()

gint                g_date_days_between                 (const GDate *date1,
                                                         const GDate *date2);

date1 :

date2 :

Returns :


g_date_compare ()

gint                g_date_compare                      (const GDate *lhs,
                                                         const GDate *rhs);

lhs :

rhs :

Returns :


g_date_clamp ()

void                g_date_clamp                        (GDate *date,
                                                         const GDate *min_date,
                                                         const GDate *max_date);

date :

min_date :

max_date :


g_date_order ()

void                g_date_order                        (GDate *date1,
                                                         GDate *date2);

date1 :

date2 :


g_date_get_day ()

GDateDay            g_date_get_day                      (const GDate *date);

date :

Returns :


g_date_get_month ()

GDateMonth          g_date_get_month                    (const GDate *date);

date :

Returns :


g_date_get_year ()

GDateYear           g_date_get_year                     (const GDate *date);

date :

Returns :


g_date_get_julian ()

guint32             g_date_get_julian                   (const GDate *date);

date :

Returns :


g_date_get_weekday ()

GDateWeekday        g_date_get_weekday                  (const GDate *date);

date :

Returns :


g_date_get_day_of_year ()

guint               g_date_get_day_of_year              (const GDate *date);

date :

Returns :


g_date_get_days_in_month ()

guint8              g_date_get_days_in_month            (GDateMonth month,
                                                         GDateYear year);

month :

year :

Returns :


g_date_is_first_of_month ()

gboolean            g_date_is_first_of_month            (const GDate *date);

date :

Returns :


g_date_is_last_of_month ()

gboolean            g_date_is_last_of_month             (const GDate *date);

date :

Returns :


g_date_is_leap_year ()

gboolean            g_date_is_leap_year                 (GDateYear year);

year :

Returns :


g_date_get_monday_week_of_year ()

guint               g_date_get_monday_week_of_year      (const GDate *date);

date :

Returns :


g_date_get_monday_weeks_in_year ()

guint8              g_date_get_monday_weeks_in_year     (GDateYear year);

year :

Returns :


g_date_get_sunday_week_of_year ()

guint               g_date_get_sunday_week_of_year      (const GDate *date);

date :

Returns :


g_date_get_sunday_weeks_in_year ()

guint8              g_date_get_sunday_weeks_in_year     (GDateYear year);

year :

Returns :


g_date_get_iso8601_week_of_year ()

guint               g_date_get_iso8601_week_of_year     (const GDate *date);

Returns the week of the year, where weeks are interpreted according to ISO 8601.

date :

a valid GDate

Returns :

ISO 8601 week number of the year.

Since 2.6


g_date_strftime ()

gsize               g_date_strftime                     (gchar *s,
                                                         gsize slen,
                                                         const gchar *format,
                                                         const GDate *date);

s :

slen :

format :

date :

Returns :


g_date_to_struct_tm ()

void                g_date_to_struct_tm                 (const GDate *date,
                                                         struct tm *tm);

date :

tm :


g_date_valid ()

gboolean            g_date_valid                        (const GDate *date);

date :

Returns :


g_date_valid_day ()

gboolean            g_date_valid_day                    (GDateDay day);

day :

Returns :


g_date_valid_month ()

gboolean            g_date_valid_month                  (GDateMonth month);

month :

Returns :


g_date_valid_year ()

gboolean            g_date_valid_year                   (GDateYear year);

year :

Returns :


g_date_valid_dmy ()

gboolean            g_date_valid_dmy                    (GDateDay day,
                                                         GDateMonth month,
                                                         GDateYear year);

day :

month :

year :

Returns :


g_date_valid_julian ()

gboolean            g_date_valid_julian                 (guint32 julian_date);

julian_date :

Returns :


g_date_valid_weekday ()

gboolean            g_date_valid_weekday                (GDateWeekday weekday);

weekday :

Returns :