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