gdate.h

00001 /* GLIB - Library of useful routines for C programming
00002  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
00003  * Portions copyright (c) 2006 Nokia Corporation.  All rights reserved.
00004  *
00005  * This library is free software; you can redistribute it and/or
00006  * modify it under the terms of the GNU Lesser General Public
00007  * License as published by the Free Software Foundation; either
00008  * version 2 of the License, or (at your option) any later version.
00009  *
00010  * This library is distributed in the hope that it will be useful,
00011  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00012  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00013  * Lesser General Public License for more details.
00014  *
00015  * You should have received a copy of the GNU Lesser General Public
00016  * License along with this library; if not, write to the
00017  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
00018  * Boston, MA 02111-1307, USA.
00019  */
00020 
00021 /*
00022  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
00023  * file for a list of people on the GLib Team.  See the ChangeLog
00024  * files for a list of changes.  These files are distributed with
00025  * GLib at ftp://ftp.gtk.org/pub/gtk/. 
00026  */
00027 
00028 #ifndef __G_DATE_H__
00029 #define __G_DATE_H__
00030 
00031 #include <_ansi.h>
00032 #include <time.h>
00033 
00034 #include <glib/gtypes.h>
00035 #include <glib/gquark.h>
00036 
00037 G_BEGIN_DECLS
00038 
00039 /* GDate
00040  *
00041  * Date calculations (not time for now, to be resolved). These are a
00042  * mutant combination of Steffen Beyer's DateCalc routines
00043  * (http://www.perl.com/CPAN/authors/id/STBEY/) and Jon Trowbridge's
00044  * date routines (written for in-house software).  Written by Havoc
00045  * Pennington <[email protected]>
00046  */
00047 
00048 typedef gint32  GTime;
00049 typedef guint16 GDateYear;
00050 typedef guint8  GDateDay;   /* day of the month */
00051 typedef struct _GDate GDate;
00052 /* make struct tm known without having to include time.h */
00053 struct tm;
00054 
00055 /* enum used to specify order of appearance in parsed date strings */
00056 typedef enum
00057 {
00058   G_DATE_DAY   = 0,
00059   G_DATE_MONTH = 1,
00060   G_DATE_YEAR  = 2
00061 } GDateDMY;
00062 
00063 /* actual week and month values */
00064 typedef enum
00065 {
00066   G_DATE_BAD_WEEKDAY  = 0,
00067   G_DATE_MONDAY       = 1,
00068   G_DATE_TUESDAY      = 2,
00069   G_DATE_WEDNESDAY    = 3,
00070   G_DATE_THURSDAY     = 4,
00071   G_DATE_FRIDAY       = 5,
00072   G_DATE_SATURDAY     = 6,
00073   G_DATE_SUNDAY       = 7
00074 } GDateWeekday;
00075 typedef enum
00076 {
00077   G_DATE_BAD_MONTH = 0,
00078   G_DATE_JANUARY   = 1,
00079   G_DATE_FEBRUARY  = 2,
00080   G_DATE_MARCH     = 3,
00081   G_DATE_APRIL     = 4,
00082   G_DATE_MAY       = 5,
00083   G_DATE_JUNE      = 6,
00084   G_DATE_JULY      = 7,
00085   G_DATE_AUGUST    = 8,
00086   G_DATE_SEPTEMBER = 9,
00087   G_DATE_OCTOBER   = 10,
00088   G_DATE_NOVEMBER  = 11,
00089   G_DATE_DECEMBER  = 12
00090 } GDateMonth;
00091 
00092 #define G_DATE_BAD_JULIAN 0U
00093 #define G_DATE_BAD_DAY    0U
00094 #define G_DATE_BAD_YEAR   0U
00095 
00096 /* Note: directly manipulating structs is generally a bad idea, but
00097  * in this case it's an *incredibly* bad idea, because all or part
00098  * of this struct can be invalid at any given time. Use the functions,
00099  * or you will get hosed, I promise.
00100  */
00101 struct _GDate
00102 {
00103   guint julian_days : 32; /* julian days representation - we use a
00104                            *  bitfield hoping that 64 bit platforms
00105                            *  will pack this whole struct in one big
00106                            *  int
00107                            */
00108 
00109   guint julian : 1;    /* julian is valid */
00110   guint dmy    : 1;    /* dmy is valid */
00111 
00112   /* DMY representation */
00113   guint day    : 6;
00114   guint month  : 4;
00115   guint year   : 16;
00116 };
00117 
00118 /* g_date_new() returns an invalid date, you then have to _set() stuff
00119  * to get a usable object. You can also allocate a GDate statically,
00120  * then call g_date_clear() to initialize.
00121  */
00122 IMPORT_C GDate*       g_date_new                   (void);
00123 IMPORT_C GDate*       g_date_new_dmy               (GDateDay     day,
00124                                            GDateMonth   month,
00125                                            GDateYear    year);
00126 IMPORT_C GDate*       g_date_new_julian            (guint32      julian_day);
00127 IMPORT_C void         g_date_free                  (GDate       *date);
00128 
00129 /* check g_date_valid() after doing an operation that might fail, like
00130  * _parse.  Almost all g_date operations are undefined on invalid
00131  * dates (the exceptions are the mutators, since you need those to
00132  * return to validity).
00133  */
00134 IMPORT_C gboolean     g_date_valid                 (const GDate *date);
00135 IMPORT_C gboolean     g_date_valid_day             (GDateDay     day) G_GNUC_CONST;
00136 IMPORT_C gboolean     g_date_valid_month           (GDateMonth month) G_GNUC_CONST;
00137 IMPORT_C gboolean     g_date_valid_year            (GDateYear  year) G_GNUC_CONST;
00138 IMPORT_C gboolean     g_date_valid_weekday         (GDateWeekday weekday) G_GNUC_CONST;
00139 IMPORT_C gboolean     g_date_valid_julian          (guint32 julian_date) G_GNUC_CONST;
00140 IMPORT_C gboolean     g_date_valid_dmy             (GDateDay     day,
00141                                            GDateMonth   month,
00142                                            GDateYear    year) G_GNUC_CONST;
00143 
00144 IMPORT_C GDateWeekday g_date_get_weekday           (const GDate *date);
00145 IMPORT_C GDateMonth   g_date_get_month             (const GDate *date);
00146 IMPORT_C GDateYear    g_date_get_year              (const GDate *date);
00147 IMPORT_C GDateDay     g_date_get_day               (const GDate *date);
00148 IMPORT_C guint32      g_date_get_julian            (const GDate *date);
00149 IMPORT_C guint        g_date_get_day_of_year       (const GDate *date);
00150 /* First monday/sunday is the start of week 1; if we haven't reached
00151  * that day, return 0. These are not ISO weeks of the year; that
00152  * routine needs to be added.
00153  * these functions return the number of weeks, starting on the
00154  * corrsponding day
00155  */
00156 IMPORT_C guint        g_date_get_monday_week_of_year (const GDate *date);
00157 IMPORT_C guint        g_date_get_sunday_week_of_year (const GDate *date);
00158 IMPORT_C guint        g_date_get_iso8601_week_of_year (const GDate *date);
00159 
00160 /* If you create a static date struct you need to clear it to get it
00161  * in a sane state before use. You can clear a whole array at
00162  * once with the ndates argument.
00163  */
00164 IMPORT_C void         g_date_clear                 (GDate       *date,
00165                                            guint        n_dates);
00166 
00167 /* The parse routine is meant for dates typed in by a user, so it
00168  * permits many formats but tries to catch common typos. If your data
00169  * needs to be strictly validated, it is not an appropriate function.
00170  */
00171 IMPORT_C void         g_date_set_parse             (GDate       *date,
00172                                            const gchar *str);
00173 IMPORT_C void         g_date_set_time              (GDate       *date,
00174                                            time_t       timet);
00175 IMPORT_C void         g_date_set_time_val          (GDate       *date,
00176                                            GTimeVal    *timeval);
00177 #ifndef G_DISABLE_DEPRECATED
00178 IMPORT_C void         g_date_set_time              (GDate       *date,
00179                                            GTime        time_);
00180 #endif
00181 IMPORT_C void         g_date_set_month             (GDate       *date,
00182                                            GDateMonth   month);
00183 IMPORT_C void         g_date_set_day               (GDate       *date,
00184                                            GDateDay     day);
00185 IMPORT_C void         g_date_set_year              (GDate       *date,
00186                                            GDateYear    year);
00187 IMPORT_C void         g_date_set_dmy               (GDate       *date,
00188                                            GDateDay     day,
00189                                            GDateMonth   month,
00190                                            GDateYear    y);
00191 IMPORT_C void         g_date_set_julian            (GDate       *date,
00192                                            guint32      julian_date);
00193 IMPORT_C gboolean     g_date_is_first_of_month     (const GDate *date);
00194 IMPORT_C gboolean     g_date_is_last_of_month      (const GDate *date);
00195 
00196 /* To go forward by some number of weeks just go forward weeks*7 days */
00197 IMPORT_C void         g_date_add_days              (GDate       *date,
00198                                            guint        n_days);
00199 IMPORT_C void         g_date_subtract_days         (GDate       *date,
00200                                            guint        n_days);
00201 
00202 /* If you add/sub months while day > 28, the day might change */
00203 IMPORT_C void         g_date_add_months            (GDate       *date,
00204                                            guint        n_months);
00205 IMPORT_C void         g_date_subtract_months       (GDate       *date,
00206                                            guint        n_months);
00207 
00208 /* If it's feb 29, changing years can move you to the 28th */
00209 IMPORT_C void         g_date_add_years             (GDate       *date,
00210                                            guint        n_years);
00211 IMPORT_C void         g_date_subtract_years        (GDate       *date,
00212                                            guint        n_years);
00213 IMPORT_C gboolean     g_date_is_leap_year          (GDateYear    year) G_GNUC_CONST;
00214 IMPORT_C guint8       g_date_get_days_in_month     (GDateMonth   month,
00215                                            GDateYear    year) G_GNUC_CONST;
00216 IMPORT_C guint8       g_date_get_monday_weeks_in_year  (GDateYear    year) G_GNUC_CONST;
00217 IMPORT_C guint8       g_date_get_sunday_weeks_in_year  (GDateYear    year) G_GNUC_CONST;
00218 
00219 /* Returns the number of days between the two dates.  If date2 comes
00220    before date1, a negative value is return. */
00221 IMPORT_C gint         g_date_days_between          (const GDate *date1,
00222                                            const GDate *date2);
00223 
00224 /* qsort-friendly (with a cast...) */
00225 IMPORT_C gint         g_date_compare               (const GDate *lhs,
00226                                            const GDate *rhs);
00227 IMPORT_C void         g_date_to_struct_tm          (const GDate *date,
00228                                            struct tm   *tm);
00229 
00230 IMPORT_C void         g_date_clamp                 (GDate *date,
00231                                            const GDate *min_date,
00232                                            const GDate *max_date);
00233 
00234 /* Swap date1 and date2's values if date1 > date2. */
00235 IMPORT_C void         g_date_order                 (GDate *date1, GDate *date2);
00236 
00237 /* Just like strftime() except you can only use date-related formats.
00238  *   Using a time format is undefined.
00239  */
00240 IMPORT_C gsize        g_date_strftime              (gchar       *s,
00241                                            gsize        slen,
00242                                            const gchar *format,
00243                                            const GDate *date);
00244 
00245 #ifndef G_DISABLE_DEPRECATED
00246 
00247 #define g_date_weekday                  g_date_get_weekday
00248 #define g_date_month                    g_date_get_month
00249 #define g_date_year                     g_date_get_year
00250 #define g_date_day                      g_date_get_day
00251 #define g_date_julian                   g_date_get_julian
00252 #define g_date_day_of_year              g_date_get_day_of_year
00253 #define g_date_monday_week_of_year      g_date_get_monday_week_of_year
00254 #define g_date_sunday_week_of_year      g_date_get_sunday_week_of_year
00255 #define g_date_days_in_month            g_date_get_days_in_month
00256 #define g_date_monday_weeks_in_year     g_date_get_monday_weeks_in_year
00257 #define g_date_sunday_weeks_in_year     g_date_get_sunday_weeks_in_year
00258 
00259 #endif /* G_DISABLE_DEPRECATED */
00260 
00261 G_END_DECLS
00262 
00263 #endif /* __G_DATE_H__ */
00264