gdate.h 12.1 KB
Newer Older
1
2
3
4
5
6
/* GLIB - Library of useful routines for C programming
 * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
swilmet's avatar
swilmet committed
7
 * version 2.1 of the License, or (at your option) any later version.
8
9
10
11
12
13
14
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU
 * Lesser General Public License for more details.
 *
 * 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
20
21
 */

/*
 * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
 * file for a list of people on the GLib Team.  See the ChangeLog
 * files for a list of changes.  These files are distributed with
22
 * GLib at ftp://ftp.gtk.org/pub/gtk/.
23
24
 */

25
26
27
#ifndef __G_DATE_H__
#define __G_DATE_H__

28
#if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
29
30
31
#error "Only <glib.h> can be included directly."
#endif

32
33
34
#include <time.h>

#include <glib/gtypes.h>
35
#include <glib/gquark.h>
36
37
38
39
40
41
42
43
44
45
46
47

G_BEGIN_DECLS

/* GDate
 *
 * Date calculations (not time for now, to be resolved). These are a
 * mutant combination of Steffen Beyer's DateCalc routines
 * (http://www.perl.com/CPAN/authors/id/STBEY/) and Jon Trowbridge's
 * date routines (written for in-house software).  Written by Havoc
 * Pennington <hp@pobox.com>
 */

Philip Withnall's avatar
Philip Withnall committed
48
typedef gint32  GTime GLIB_DEPRECATED_TYPE_IN_2_62_FOR(GDateTime);
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
typedef guint16 GDateYear;
typedef guint8  GDateDay;   /* day of the month */
typedef struct _GDate GDate;

/* enum used to specify order of appearance in parsed date strings */
typedef enum
{
  G_DATE_DAY   = 0,
  G_DATE_MONTH = 1,
  G_DATE_YEAR  = 2
} GDateDMY;

/* actual week and month values */
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;
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;

#define G_DATE_BAD_JULIAN 0U
#define G_DATE_BAD_DAY    0U
#define G_DATE_BAD_YEAR   0U

/* Note: directly manipulating structs is generally a bad idea, but
 * in this case it's an *incredibly* bad idea, because all or part
 * of this struct can be invalid at any given time. Use the functions,
 * or you will get hosed, I promise.
 */
struct _GDate
{
  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;
};

/* g_date_new() returns an invalid date, you then have to _set() stuff
 * to get a usable object. You can also allocate a GDate statically,
 * then call g_date_clear() to initialize.
 */
120
GLIB_AVAILABLE_IN_ALL
121
GDate*       g_date_new                   (void);
122
GLIB_AVAILABLE_IN_ALL
123
124
125
GDate*       g_date_new_dmy               (GDateDay     day,
                                           GDateMonth   month,
                                           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);
Andrew Potter's avatar
Andrew Potter committed
130
131
GLIB_AVAILABLE_IN_2_56
GDate*       g_date_copy                  (const GDate *date);
132
133
134
135
136
137

/* check g_date_valid() after doing an operation that might fail, like
 * _parse.  Almost all g_date operations are undefined on invalid
 * dates (the exceptions are the mutators, since you need those to
 * return to validity).
 */
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
152
153
154
gboolean     g_date_valid_dmy             (GDateDay     day,
                                           GDateMonth   month,
                                           GDateYear    year) G_GNUC_CONST;

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
168
169
170
171
172
/* First monday/sunday is the start of week 1; if we haven't reached
 * that day, return 0. These are not ISO weeks of the year; that
 * routine needs to be added.
 * these functions return the number of weeks, starting on the
 * corrsponding day
 */
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
181
182
183

/* If you create a static date struct you need to clear it to get it
 * in a sane state before use. You can clear a whole array at
 * once with the ndates argument.
 */
184
GLIB_AVAILABLE_IN_ALL
185
186
187
188
189
190
191
void         g_date_clear                 (GDate       *date,
                                           guint        n_dates);

/* The parse routine is meant for dates typed in by a user, so it
 * permits many formats but tries to catch common typos. If your data
 * needs to be strictly validated, it is not an appropriate function.
 */
192
GLIB_AVAILABLE_IN_ALL
193
194
void         g_date_set_parse             (GDate       *date,
                                           const gchar *str);
195
GLIB_AVAILABLE_IN_ALL
196
197
void         g_date_set_time_t            (GDate       *date,
					   time_t       timet);
198
199
G_GNUC_BEGIN_IGNORE_DEPRECATIONS
GLIB_DEPRECATED_IN_2_62_FOR(g_date_set_time_t)
200
201
void         g_date_set_time_val          (GDate       *date,
					   GTimeVal    *timeval);
202
GLIB_DEPRECATED_FOR(g_date_set_time_t)
203
void         g_date_set_time              (GDate       *date,
204
                                           GTime        time_);
Philip Withnall's avatar
Philip Withnall committed
205
G_GNUC_END_IGNORE_DEPRECATIONS
206
GLIB_AVAILABLE_IN_ALL
207
208
void         g_date_set_month             (GDate       *date,
                                           GDateMonth   month);
209
GLIB_AVAILABLE_IN_ALL
210
211
void         g_date_set_day               (GDate       *date,
                                           GDateDay     day);
212
GLIB_AVAILABLE_IN_ALL
213
214
void         g_date_set_year              (GDate       *date,
                                           GDateYear    year);
215
GLIB_AVAILABLE_IN_ALL
216
217
218
219
void         g_date_set_dmy               (GDate       *date,
                                           GDateDay     day,
                                           GDateMonth   month,
                                           GDateYear    y);
220
GLIB_AVAILABLE_IN_ALL
221
222
void         g_date_set_julian            (GDate       *date,
                                           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
231
void         g_date_add_days              (GDate       *date,
                                           guint        n_days);
232
GLIB_AVAILABLE_IN_ALL
233
234
235
236
void         g_date_subtract_days         (GDate       *date,
                                           guint        n_days);

/* If you add/sub months while day > 28, the day might change */
237
GLIB_AVAILABLE_IN_ALL
238
239
void         g_date_add_months            (GDate       *date,
                                           guint        n_months);
240
GLIB_AVAILABLE_IN_ALL
241
242
243
244
void         g_date_subtract_months       (GDate       *date,
                                           guint        n_months);

/* If it's feb 29, changing years can move you to the 28th */
245
GLIB_AVAILABLE_IN_ALL
246
247
void         g_date_add_years             (GDate       *date,
                                           guint        n_years);
248
GLIB_AVAILABLE_IN_ALL
249
250
void         g_date_subtract_years        (GDate       *date,
                                           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
262
/* Returns the number of days between the two dates.  If date2 comes
   before date1, a negative value is return. */
263
GLIB_AVAILABLE_IN_ALL
264
265
266
gint         g_date_days_between          (const GDate *date1,
					   const GDate *date2);

267
/* qsort-friendly (with a cast...) */
268
GLIB_AVAILABLE_IN_ALL
269
270
gint         g_date_compare               (const GDate *lhs,
                                           const GDate *rhs);
271
GLIB_AVAILABLE_IN_ALL
272
void         g_date_to_struct_tm          (const GDate *date,
273
274
                                           struct tm   *tm);

275
GLIB_AVAILABLE_IN_ALL
276
277
278
279
280
void         g_date_clamp                 (GDate *date,
					   const GDate *min_date,
					   const GDate *max_date);

/* Swap date1 and date2's values if date1 > date2. */
281
GLIB_AVAILABLE_IN_ALL
282
283
void         g_date_order                 (GDate *date1, GDate *date2);

284
285
286
/* Just like strftime() except you can only use date-related formats.
 *   Using a time format is undefined.
 */
287
GLIB_AVAILABLE_IN_ALL
288
289
290
gsize        g_date_strftime              (gchar       *s,
                                           gsize        slen,
                                           const gchar *format,
291
                                           const GDate *date);
292

293
294
295
296
297
298
299
300
301
302
303
#define g_date_weekday 			g_date_get_weekday GLIB_DEPRECATED_MACRO_IN_2_26_FOR(g_date_get_weekday)
#define g_date_month 			g_date_get_month GLIB_DEPRECATED_MACRO_IN_2_26_FOR(g_date_get_month)
#define g_date_year 			g_date_get_year GLIB_DEPRECATED_MACRO_IN_2_26_FOR(g_date_get_year)
#define g_date_day 			g_date_get_day GLIB_DEPRECATED_MACRO_IN_2_26_FOR(g_date_get_day)
#define g_date_julian 			g_date_get_julian GLIB_DEPRECATED_MACRO_IN_2_26_FOR(g_date_get_julian)
#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)
#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)
#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)
#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)
#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)
#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)
Owen Taylor's avatar
Owen Taylor committed
304

305
306
307
G_END_DECLS

#endif /* __G_DATE_H__ */