glib-2.0/glib/gdate.h

0001 /* GLIB - Library of useful routines for C programming
0002  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
0003  *
0004  * SPDX-License-Identifier: LGPL-2.1-or-later
0005  *
0006  * This library is free software; you can redistribute it and/or
0007  * modify it under the terms of the GNU Lesser General Public
0008  * License as published by the Free Software Foundation; either
0009  * version 2.1 of the License, or (at your option) any later version.
0010  *
0011  * This library is distributed in the hope that it will be useful,
0012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0014  * Lesser General Public License for more details.
0015  *
0016  * You should have received a copy of the GNU Lesser General Public
0017  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
0018  */
0019
0020 /*
0021  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
0022  * file for a list of people on the GLib Team.  See the ChangeLog
0023  * files for a list of changes.  These files are distributed with
0024  * GLib at ftp://ftp.gtk.org/pub/gtk/.
0025  */
0026
0027 #ifndef __G_DATE_H__
0028 #define __G_DATE_H__
0029
0030 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
0031 #error "Only <glib.h> can be included directly."
0032 #endif
0033
0034 #include <time.h>
0035
0036 #include <glib/gtypes.h>
0037 #include <glib/gquark.h>
0038
0039 G_BEGIN_DECLS
0040
0041 typedef gint32  GTime GLIB_DEPRECATED_TYPE_IN_2_62_FOR(GDateTime);
0042 typedef guint16 GDateYear;
0043 typedef guint8  GDateDay;   /* day of the month */
0044 typedef struct _GDate GDate;
0045
0046 /* enum used to specify order of appearance in parsed date strings */
0047 typedef enum
0048 {
0049   G_DATE_DAY   = 0,
0050   G_DATE_MONTH = 1,
0051   G_DATE_YEAR  = 2
0052 } GDateDMY;
0053
0054 /* actual week and month values */
0055 typedef enum
0056 {
0057   G_DATE_BAD_WEEKDAY  = 0,
0058   G_DATE_MONDAY       = 1,
0059   G_DATE_TUESDAY      = 2,
0060   G_DATE_WEDNESDAY    = 3,
0061   G_DATE_THURSDAY     = 4,
0062   G_DATE_FRIDAY       = 5,
0063   G_DATE_SATURDAY     = 6,
0064   G_DATE_SUNDAY       = 7
0065 } GDateWeekday;
0066 typedef enum
0067 {
0068   G_DATE_BAD_MONTH = 0,
0069   G_DATE_JANUARY   = 1,
0070   G_DATE_FEBRUARY  = 2,
0071   G_DATE_MARCH     = 3,
0072   G_DATE_APRIL     = 4,
0073   G_DATE_MAY       = 5,
0074   G_DATE_JUNE      = 6,
0075   G_DATE_JULY      = 7,
0076   G_DATE_AUGUST    = 8,
0077   G_DATE_SEPTEMBER = 9,
0078   G_DATE_OCTOBER   = 10,
0079   G_DATE_NOVEMBER  = 11,
0080   G_DATE_DECEMBER  = 12
0081 } GDateMonth;
0082
0083 #define G_DATE_BAD_JULIAN 0U
0084 #define G_DATE_BAD_DAY    0U
0085 #define G_DATE_BAD_YEAR   0U
0086
0087 /* Note: directly manipulating structs is generally a bad idea, but
0088  * in this case it's an *incredibly* bad idea, because all or part
0089  * of this struct can be invalid at any given time. Use the functions,
0090  * or you will get hosed, I promise.
0091  */
0092 struct _GDate
0093 {
0094   guint julian_days : 32; /* julian days representation - we use a
0095                            *  bitfield hoping that 64 bit platforms
0096                            *  will pack this whole struct in one big
0097                            *  int
0098                            */
0099
0100   guint julian : 1;    /* julian is valid */
0101   guint dmy    : 1;    /* dmy is valid */
0102
0103   /* DMY representation */
0104   guint day    : 6;
0105   guint month  : 4;
0106   guint year   : 16;
0107 };
0108
0109 /* g_date_new() returns an invalid date, you then have to _set() stuff
0110  * to get a usable object. You can also allocate a GDate statically,
0111  * then call g_date_clear() to initialize.
0112  */
0113 GLIB_AVAILABLE_IN_ALL
0114 GDate*       g_date_new                   (void);
0115 GLIB_AVAILABLE_IN_ALL
0116 GDate*       g_date_new_dmy               (GDateDay     day,
0117                                            GDateMonth   month,
0118                                            GDateYear    year);
0119 GLIB_AVAILABLE_IN_ALL
0120 GDate*       g_date_new_julian            (guint32      julian_day);
0121 GLIB_AVAILABLE_IN_ALL
0122 void         g_date_free                  (GDate       *date);
0123 GLIB_AVAILABLE_IN_2_56
0124 GDate*       g_date_copy                  (const GDate *date);
0125
0126 /* check g_date_valid() after doing an operation that might fail, like
0127  * _parse.  Almost all g_date operations are undefined on invalid
0128  * dates (the exceptions are the mutators, since you need those to
0129  * return to validity).
0130  */
0131 GLIB_AVAILABLE_IN_ALL
0132 gboolean     g_date_valid                 (const GDate *date);
0133 GLIB_AVAILABLE_IN_ALL
0134 gboolean     g_date_valid_day             (GDateDay     day) G_GNUC_CONST;
0135 GLIB_AVAILABLE_IN_ALL
0136 gboolean     g_date_valid_month           (GDateMonth month) G_GNUC_CONST;
0137 GLIB_AVAILABLE_IN_ALL
0138 gboolean     g_date_valid_year            (GDateYear  year) G_GNUC_CONST;
0139 GLIB_AVAILABLE_IN_ALL
0140 gboolean     g_date_valid_weekday         (GDateWeekday weekday) G_GNUC_CONST;
0141 GLIB_AVAILABLE_IN_ALL
0142 gboolean     g_date_valid_julian          (guint32 julian_date) G_GNUC_CONST;
0143 GLIB_AVAILABLE_IN_ALL
0144 gboolean     g_date_valid_dmy             (GDateDay     day,
0145                                            GDateMonth   month,
0146                                            GDateYear    year) G_GNUC_CONST;
0147
0148 GLIB_AVAILABLE_IN_ALL
0149 GDateWeekday g_date_get_weekday           (const GDate *date);
0150 GLIB_AVAILABLE_IN_ALL
0151 GDateMonth   g_date_get_month             (const GDate *date);
0152 GLIB_AVAILABLE_IN_ALL
0153 GDateYear    g_date_get_year              (const GDate *date);
0154 GLIB_AVAILABLE_IN_ALL
0155 GDateDay     g_date_get_day               (const GDate *date);
0156 GLIB_AVAILABLE_IN_ALL
0157 guint32      g_date_get_julian            (const GDate *date);
0158 GLIB_AVAILABLE_IN_ALL
0159 guint        g_date_get_day_of_year       (const GDate *date);
0160 /* First monday/sunday is the start of week 1; if we haven't reached
0161  * that day, return 0. These are not ISO weeks of the year; that
0162  * routine needs to be added.
0163  * these functions return the number of weeks, starting on the
0164  * corresponding day
0165  */
0166 GLIB_AVAILABLE_IN_ALL
0167 guint        g_date_get_monday_week_of_year (const GDate *date);
0168 GLIB_AVAILABLE_IN_ALL
0169 guint        g_date_get_sunday_week_of_year (const GDate *date);
0170 GLIB_AVAILABLE_IN_2_86
0171 guint        g_date_get_week_of_year        (const GDate  *date,
0172                                              GDateWeekday  first_day_of_week);
0173 GLIB_AVAILABLE_IN_ALL
0174 guint        g_date_get_iso8601_week_of_year (const GDate *date);
0175
0176 /* If you create a static date struct you need to clear it to get it
0177  * in a safe state before use. You can clear a whole array at
0178  * once with the ndates argument.
0179  */
0180 GLIB_AVAILABLE_IN_ALL
0181 void         g_date_clear                 (GDate       *date,
0182                                            guint        n_dates);
0183
0184 /* The parse routine is meant for dates typed in by a user, so it
0185  * permits many formats but tries to catch common typos. If your data
0186  * needs to be strictly validated, it is not an appropriate function.
0187  */
0188 GLIB_AVAILABLE_IN_ALL
0189 void         g_date_set_parse             (GDate       *date,
0190                                            const gchar *str);
0191 GLIB_AVAILABLE_IN_ALL
0192 void         g_date_set_time_t            (GDate       *date,
0193                        time_t       timet);
0194 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
0195 GLIB_DEPRECATED_IN_2_62_FOR(g_date_set_time_t)
0196 void         g_date_set_time_val          (GDate       *date,
0197                        GTimeVal    *timeval);
0198 GLIB_DEPRECATED_FOR(g_date_set_time_t)
0199 void         g_date_set_time              (GDate       *date,
0200                                            GTime        time_);
0201 G_GNUC_END_IGNORE_DEPRECATIONS
0202 GLIB_AVAILABLE_IN_ALL
0203 void         g_date_set_month             (GDate       *date,
0204                                            GDateMonth   month);
0205 GLIB_AVAILABLE_IN_ALL
0206 void         g_date_set_day               (GDate       *date,
0207                                            GDateDay     day);
0208 GLIB_AVAILABLE_IN_ALL
0209 void         g_date_set_year              (GDate       *date,
0210                                            GDateYear    year);
0211 GLIB_AVAILABLE_IN_ALL
0212 void         g_date_set_dmy               (GDate       *date,
0213                                            GDateDay     day,
0214                                            GDateMonth   month,
0215                                            GDateYear    y);
0216 GLIB_AVAILABLE_IN_ALL
0217 void         g_date_set_julian            (GDate       *date,
0218                                            guint32      julian_date);
0219 GLIB_AVAILABLE_IN_ALL
0220 gboolean     g_date_is_first_of_month     (const GDate *date);
0221 GLIB_AVAILABLE_IN_ALL
0222 gboolean     g_date_is_last_of_month      (const GDate *date);
0223
0224 /* To go forward by some number of weeks just go forward weeks*7 days */
0225 GLIB_AVAILABLE_IN_ALL
0226 void         g_date_add_days              (GDate       *date,
0227                                            guint        n_days);
0228 GLIB_AVAILABLE_IN_ALL
0229 void         g_date_subtract_days         (GDate       *date,
0230                                            guint        n_days);
0231
0232 /* If you add/sub months while day > 28, the day might change */
0233 GLIB_AVAILABLE_IN_ALL
0234 void         g_date_add_months            (GDate       *date,
0235                                            guint        n_months);
0236 GLIB_AVAILABLE_IN_ALL
0237 void         g_date_subtract_months       (GDate       *date,
0238                                            guint        n_months);
0239
0240 /* If it's feb 29, changing years can move you to the 28th */
0241 GLIB_AVAILABLE_IN_ALL
0242 void         g_date_add_years             (GDate       *date,
0243                                            guint        n_years);
0244 GLIB_AVAILABLE_IN_ALL
0245 void         g_date_subtract_years        (GDate       *date,
0246                                            guint        n_years);
0247 GLIB_AVAILABLE_IN_ALL
0248 gboolean     g_date_is_leap_year          (GDateYear    year) G_GNUC_CONST;
0249 GLIB_AVAILABLE_IN_ALL
0250 guint8       g_date_get_days_in_month     (GDateMonth   month,
0251                                            GDateYear    year) G_GNUC_CONST;
0252 GLIB_AVAILABLE_IN_ALL
0253 guint8       g_date_get_monday_weeks_in_year  (GDateYear    year) G_GNUC_CONST;
0254 GLIB_AVAILABLE_IN_ALL
0255 guint8       g_date_get_sunday_weeks_in_year  (GDateYear    year) G_GNUC_CONST;
0256 GLIB_AVAILABLE_IN_2_86
0257 guint8       g_date_get_weeks_in_year         (GDateYear    year,
0258                                                GDateWeekday first_day_of_week) G_GNUC_CONST;
0259
0260 /* Returns the number of days between the two dates.  If date2 comes
0261    before date1, a negative value is return. */
0262 GLIB_AVAILABLE_IN_ALL
0263 gint         g_date_days_between          (const GDate *date1,
0264                        const GDate *date2);
0265
0266 /* qsort-friendly (with a cast...) */
0267 GLIB_AVAILABLE_IN_ALL
0268 gint         g_date_compare               (const GDate *lhs,
0269                                            const GDate *rhs);
0270 GLIB_AVAILABLE_IN_ALL
0271 void         g_date_to_struct_tm          (const GDate *date,
0272                                            struct tm   *tm);
0273
0274 GLIB_AVAILABLE_IN_ALL
0275 void         g_date_clamp                 (GDate *date,
0276                        const GDate *min_date,
0277                        const GDate *max_date);
0278
0279 /* Swap date1 and date2's values if date1 > date2. */
0280 GLIB_AVAILABLE_IN_ALL
0281 void         g_date_order                 (GDate *date1, GDate *date2);
0282
0283 /* Just like strftime() except you can only use date-related formats.
0284  *   Using a time format is undefined.
0285  */
0286 GLIB_AVAILABLE_IN_ALL
0287 gsize        g_date_strftime              (gchar       *s,
0288                                            gsize        slen,
0289                                            const gchar *format,
0290                                            const GDate *date);
0291
0292 #define g_date_weekday          g_date_get_weekday GLIB_DEPRECATED_MACRO_IN_2_26_FOR(g_date_get_weekday)
0293 #define g_date_month            g_date_get_month GLIB_DEPRECATED_MACRO_IN_2_26_FOR(g_date_get_month)
0294 #define g_date_year             g_date_get_year GLIB_DEPRECATED_MACRO_IN_2_26_FOR(g_date_get_year)
0295 #define g_date_day          g_date_get_day GLIB_DEPRECATED_MACRO_IN_2_26_FOR(g_date_get_day)
0296 #define g_date_julian           g_date_get_julian GLIB_DEPRECATED_MACRO_IN_2_26_FOR(g_date_get_julian)
0297 #define g_date_day_of_year      g_date_get_day_of_year GLIB_DEPRECATED_MACRO_IN_2_26_FOR(g_date_get_day_of_year)
0298 #define g_date_monday_week_of_year  g_date_get_monday_week_of_year GLIB_DEPRECATED_MACRO_IN_2_26_FOR(g_date_get_monday_week_of_year)
0299 #define g_date_sunday_week_of_year  g_date_get_sunday_week_of_year GLIB_DEPRECATED_MACRO_IN_2_26_FOR(g_date_get_sunday_week_of_year)
0300 #define g_date_days_in_month        g_date_get_days_in_month GLIB_DEPRECATED_MACRO_IN_2_26_FOR(g_date_get_days_in_month)
0301 #define g_date_monday_weeks_in_year     g_date_get_monday_weeks_in_year GLIB_DEPRECATED_MACRO_IN_2_26_FOR(g_date_get_monday_weeks_in_year)
0302 #define g_date_sunday_weeks_in_year g_date_get_sunday_weeks_in_year GLIB_DEPRECATED_MACRO_IN_2_26_FOR(g_date_get_sunday_weeks_in_year)
0303
0304 G_END_DECLS
0305
0306 #endif /* __G_DATE_H__ */