glib/gdate.h

   1 /* GLIB - Library of useful routines for C programming
   2  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2.1 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 /*
  19  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
  20  * file for a list of people on the GLib Team.  See the ChangeLog
  21  * files for a list of changes.  These files are distributed with
  22  * GLib at ftp://ftp.gtk.org/pub/gtk/.
  23  */
  24
  25 #ifndef __G_DATE_H__
  26 #define __G_DATE_H__
  27
  28 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
  29 #error "Only <glib.h> can be included directly."
  30 #endif
  31
  32 #include <time.h>
  33
  34 #include <glib/gtypes.h>
  35 #include <glib/gquark.h>
  36
  37 G_BEGIN_DECLS
  38
  39 /* GDate
  40  *
  41  * Date calculations (not time for now, to be resolved). These are a
  42  * mutant combination of Steffen Beyer's DateCalc routines
  43  * (http://www.perl.com/CPAN/authors/id/STBEY/) and Jon Trowbridge's
  44  * date routines (written for in-house software).  Written by Havoc
  45  * Pennington <hp@pobox.com>
  46  */
  47
  48 typedef gint32  GTime;
  49 typedef guint16 GDateYear;
  50 typedef guint8  GDateDay;   /* day of the month */
  51 typedef struct _GDate GDate;
  52
  53 /* enum used to specify order of appearance in parsed date strings */
  54 typedef enum
  55 {
  56   G_DATE_DAY   = 0,
  57   G_DATE_MONTH = 1,
  58   G_DATE_YEAR  = 2
  59 } GDateDMY;
  60
  61 /* actual week and month values */
  62 typedef enum
  63 {
  64   G_DATE_BAD_WEEKDAY  = 0,
  65   G_DATE_MONDAY       = 1,
  66   G_DATE_TUESDAY      = 2,
  67   G_DATE_WEDNESDAY    = 3,
  68   G_DATE_THURSDAY     = 4,
  69   G_DATE_FRIDAY       = 5,
  70   G_DATE_SATURDAY     = 6,
  71   G_DATE_SUNDAY       = 7
  72 } GDateWeekday;
  73 typedef enum
  74 {
  75   G_DATE_BAD_MONTH = 0,
  76   G_DATE_JANUARY   = 1,
  77   G_DATE_FEBRUARY  = 2,
  78   G_DATE_MARCH     = 3,
  79   G_DATE_APRIL     = 4,
  80   G_DATE_MAY       = 5,
  81   G_DATE_JUNE      = 6,
  82   G_DATE_JULY      = 7,
  83   G_DATE_AUGUST    = 8,
  84   G_DATE_SEPTEMBER = 9,
  85   G_DATE_OCTOBER   = 10,
  86   G_DATE_NOVEMBER  = 11,
  87   G_DATE_DECEMBER  = 12
  88 } GDateMonth;
  89
  90 #define G_DATE_BAD_JULIAN 0U
  91 #define G_DATE_BAD_DAY    0U
  92 #define G_DATE_BAD_YEAR   0U
  93
  94 /* Note: directly manipulating structs is generally a bad idea, but
  95  * in this case it's an *incredibly* bad idea, because all or part
  96  * of this struct can be invalid at any given time. Use the functions,
  97  * or you will get hosed, I promise.
  98  */
  99 struct _GDate
 100 {
 101   guint julian_days : 32; /* julian days representation - we use a
 102                            *  bitfield hoping that 64 bit platforms
 103                            *  will pack this whole struct in one big
 104                            *  int
 105                            */
 106
 107   guint julian : 1;    /* julian is valid */
 108   guint dmy    : 1;    /* dmy is valid */
 109
 110   /* DMY representation */
 111   guint day    : 6;
 112   guint month  : 4;
 113   guint year   : 16;
 114 };
 115
 116 /* g_date_new() returns an invalid date, you then have to _set() stuff
 117  * to get a usable object. You can also allocate a GDate statically,
 118  * then call g_date_clear() to initialize.
 119  */
 120 GLIB_AVAILABLE_IN_ALL
 121 GDate*       g_date_new                   (void);
 122 GLIB_AVAILABLE_IN_ALL
 123 GDate*       g_date_new_dmy               (GDateDay     day,
 124                                            GDateMonth   month,
 125                                            GDateYear    year);
 126 GLIB_AVAILABLE_IN_ALL
 127 GDate*       g_date_new_julian            (guint32      julian_day);
 128 GLIB_AVAILABLE_IN_ALL
 129 void         g_date_free                  (GDate       *date);
 130 GLIB_AVAILABLE_IN_2_56
 131 GDate*       g_date_copy                  (const GDate *date);
 132
 133 /* check g_date_valid() after doing an operation that might fail, like
 134  * _parse.  Almost all g_date operations are undefined on invalid
 135  * dates (the exceptions are the mutators, since you need those to
 136  * return to validity).
 137  */
 138 GLIB_AVAILABLE_IN_ALL
 139 gboolean     g_date_valid                 (const GDate *date);
 140 GLIB_AVAILABLE_IN_ALL
 141 gboolean     g_date_valid_day             (GDateDay     day) G_GNUC_CONST;
 142 GLIB_AVAILABLE_IN_ALL
 143 gboolean     g_date_valid_month           (GDateMonth month) G_GNUC_CONST;
 144 GLIB_AVAILABLE_IN_ALL
 145 gboolean     g_date_valid_year            (GDateYear  year) G_GNUC_CONST;
 146 GLIB_AVAILABLE_IN_ALL
 147 gboolean     g_date_valid_weekday         (GDateWeekday weekday) G_GNUC_CONST;
 148 GLIB_AVAILABLE_IN_ALL
 149 gboolean     g_date_valid_julian          (guint32 julian_date) G_GNUC_CONST;
 150 GLIB_AVAILABLE_IN_ALL
 151 gboolean     g_date_valid_dmy             (GDateDay     day,
 152                                            GDateMonth   month,
 153                                            GDateYear    year) G_GNUC_CONST;
 154
 155 GLIB_AVAILABLE_IN_ALL
 156 GDateWeekday g_date_get_weekday           (const GDate *date);
 157 GLIB_AVAILABLE_IN_ALL
 158 GDateMonth   g_date_get_month             (const GDate *date);
 159 GLIB_AVAILABLE_IN_ALL
 160 GDateYear    g_date_get_year              (const GDate *date);
 161 GLIB_AVAILABLE_IN_ALL
 162 GDateDay     g_date_get_day               (const GDate *date);
 163 GLIB_AVAILABLE_IN_ALL
 164 guint32      g_date_get_julian            (const GDate *date);
 165 GLIB_AVAILABLE_IN_ALL
 166 guint        g_date_get_day_of_year       (const GDate *date);
 167 /* First monday/sunday is the start of week 1; if we haven't reached
 168  * that day, return 0. These are not ISO weeks of the year; that
 169  * routine needs to be added.
 170  * these functions return the number of weeks, starting on the
 171  * corrsponding day
 172  */
 173 GLIB_AVAILABLE_IN_ALL
 174 guint        g_date_get_monday_week_of_year (const GDate *date);
 175 GLIB_AVAILABLE_IN_ALL
 176 guint        g_date_get_sunday_week_of_year (const GDate *date);
 177 GLIB_AVAILABLE_IN_ALL
 178 guint        g_date_get_iso8601_week_of_year (const GDate *date);
 179
 180 /* If you create a static date struct you need to clear it to get it
 181  * in a sane state before use. You can clear a whole array at
 182  * once with the ndates argument.
 183  */
 184 GLIB_AVAILABLE_IN_ALL
 185 void         g_date_clear                 (GDate       *date,
 186                                            guint        n_dates);
 187
 188 /* The parse routine is meant for dates typed in by a user, so it
 189  * permits many formats but tries to catch common typos. If your data
 190  * needs to be strictly validated, it is not an appropriate function.
 191  */
 192 GLIB_AVAILABLE_IN_ALL
 193 void         g_date_set_parse             (GDate       *date,
 194                                            const gchar *str);
 195 GLIB_AVAILABLE_IN_ALL
 196 void         g_date_set_time_t            (GDate       *date,
 197                                            time_t       timet);
 198 GLIB_AVAILABLE_IN_ALL
 199 void         g_date_set_time_val          (GDate       *date,
 200                                            GTimeVal    *timeval);
 201 #ifndef G_DISABLE_DEPRECATED
 202 GLIB_DEPRECATED_FOR(g_date_set_time_t)
 203 void         g_date_set_time              (GDate       *date,
 204                                            GTime        time_);
 205 #endif
 206 GLIB_AVAILABLE_IN_ALL
 207 void         g_date_set_month             (GDate       *date,
 208                                            GDateMonth   month);
 209 GLIB_AVAILABLE_IN_ALL
 210 void         g_date_set_day               (GDate       *date,
 211                                            GDateDay     day);
 212 GLIB_AVAILABLE_IN_ALL
 213 void         g_date_set_year              (GDate       *date,
 214                                            GDateYear    year);
 215 GLIB_AVAILABLE_IN_ALL
 216 void         g_date_set_dmy               (GDate       *date,
 217                                            GDateDay     day,
 218                                            GDateMonth   month,
 219                                            GDateYear    y);
 220 GLIB_AVAILABLE_IN_ALL
 221 void         g_date_set_julian            (GDate       *date,
 222                                            guint32      julian_date);
 223 GLIB_AVAILABLE_IN_ALL
 224 gboolean     g_date_is_first_of_month     (const GDate *date);
 225 GLIB_AVAILABLE_IN_ALL
 226 gboolean     g_date_is_last_of_month      (const GDate *date);
 227
 228 /* To go forward by some number of weeks just go forward weeks*7 days */
 229 GLIB_AVAILABLE_IN_ALL
 230 void         g_date_add_days              (GDate       *date,
 231                                            guint        n_days);
 232 GLIB_AVAILABLE_IN_ALL
 233 void         g_date_subtract_days         (GDate       *date,
 234                                            guint        n_days);
 235
 236 /* If you add/sub months while day > 28, the day might change */
 237 GLIB_AVAILABLE_IN_ALL
 238 void         g_date_add_months            (GDate       *date,
 239                                            guint        n_months);
 240 GLIB_AVAILABLE_IN_ALL
 241 void         g_date_subtract_months       (GDate       *date,
 242                                            guint        n_months);
 243
 244 /* If it's feb 29, changing years can move you to the 28th */
 245 GLIB_AVAILABLE_IN_ALL
 246 void         g_date_add_years             (GDate       *date,
 247                                            guint        n_years);
 248 GLIB_AVAILABLE_IN_ALL
 249 void         g_date_subtract_years        (GDate       *date,
 250                                            guint        n_years);
 251 GLIB_AVAILABLE_IN_ALL
 252 gboolean     g_date_is_leap_year          (GDateYear    year) G_GNUC_CONST;
 253 GLIB_AVAILABLE_IN_ALL
 254 guint8       g_date_get_days_in_month     (GDateMonth   month,
 255                                            GDateYear    year) G_GNUC_CONST;
 256 GLIB_AVAILABLE_IN_ALL
 257 guint8       g_date_get_monday_weeks_in_year  (GDateYear    year) G_GNUC_CONST;
 258 GLIB_AVAILABLE_IN_ALL
 259 guint8       g_date_get_sunday_weeks_in_year  (GDateYear    year) G_GNUC_CONST;
 260
 261 /* Returns the number of days between the two dates.  If date2 comes
 262    before date1, a negative value is return. */
 263 GLIB_AVAILABLE_IN_ALL
 264 gint         g_date_days_between          (const GDate *date1,
 265                                            const GDate *date2);
 266
 267 /* qsort-friendly (with a cast...) */
 268 GLIB_AVAILABLE_IN_ALL
 269 gint         g_date_compare               (const GDate *lhs,
 270                                            const GDate *rhs);
 271 GLIB_AVAILABLE_IN_ALL
 272 void         g_date_to_struct_tm          (const GDate *date,
 273                                            struct tm   *tm);
 274
 275 GLIB_AVAILABLE_IN_ALL
 276 void         g_date_clamp                 (GDate *date,
 277                                            const GDate *min_date,
 278                                            const GDate *max_date);
 279
 280 /* Swap date1 and date2's values if date1 > date2. */
 281 GLIB_AVAILABLE_IN_ALL
 282 void         g_date_order                 (GDate *date1, GDate *date2);
 283
 284 /* Just like strftime() except you can only use date-related formats.
 285  *   Using a time format is undefined.
 286  */
 287 GLIB_AVAILABLE_IN_ALL
 288 gsize        g_date_strftime              (gchar       *s,
 289                                            gsize        slen,
 290                                            const gchar *format,
 291                                            const GDate *date);
 292
 293 #ifndef G_DISABLE_DEPRECATED
 294
 295 #define g_date_weekday                  g_date_get_weekday
 296 #define g_date_month                    g_date_get_month
 297 #define g_date_year                     g_date_get_year
 298 #define g_date_day                      g_date_get_day
 299 #define g_date_julian                   g_date_get_julian
 300 #define g_date_day_of_year              g_date_get_day_of_year
 301 #define g_date_monday_week_of_year      g_date_get_monday_week_of_year
 302 #define g_date_sunday_week_of_year      g_date_get_sunday_week_of_year
 303 #define g_date_days_in_month            g_date_get_days_in_month
 304 #define g_date_monday_weeks_in_year     g_date_get_monday_weeks_in_year
 305 #define g_date_sunday_weeks_in_year     g_date_get_sunday_weeks_in_year
 306
 307 #endif /* G_DISABLE_DEPRECATED */
 308
 309 G_END_DECLS
 310
 311 #endif /* __G_DATE_H__ */