Update Gargoyle interpreters to r548
[projects/chimara/chimara.git] / libchimara / datetime.c
1 #include <glib.h>
2 #include "glk.h"
3
4 /**
5  * glk_current_time:
6  * @time: pointer to a #glktimeval_t structure.
7  *
8  * The current Unix time is stored in the structure @time. (The argument may not
9  * be %NULL.) This is the number of seconds since the beginning of 1970 (UTC).
10  *
11  * The first two values in the structure should be considered a single
12  * <emphasis>signed</emphasis> 64-bit number. This allows the #glktimeval_t to
13  * store a reasonable range of values in the future and past. The @high_sec
14  * value will remain zero until sometime in 2106. If your computer is running in
15  * 1969, perhaps due to an unexpected solar flare, then @high_sec will be
16  * negative.
17  * 
18  * The third value in the structure represents a fraction of a second, in
19  * microseconds (from 0 to 999999). The resolution of the glk_current_time()
20  * call is platform-dependent; the @microsec value may not be updated
21  * continuously.
22  */
23 void 
24 glk_current_time(glktimeval_t *time)
25 {
26         g_return_if_fail(time != NULL);
27 }
28
29 /**
30  * glk_current_simple_time:
31  * @factor: Factor by which to divide the time value.
32  *
33  * If dealing with 64-bit values is awkward, you can also get the current time
34  * as a lower-resolution 32-bit value. This is simply the Unix time divided by
35  * the @factor argument (which must not be zero). For example, if factor is 60,
36  * the result will be the number of minutes since 1970 (rounded towards negative
37  * infinity). If factor is 1, you will get the Unix time directly, but the value
38  * will be truncated starting some time in 2038.
39  *
40  * Returns: Unix time divided by @factor, truncated to 32 bits.
41  */
42 glsi32
43 glk_current_simple_time(glui32 factor)
44 {
45         g_return_val_if_fail(factor != 0, -1);
46         
47         return -1;
48 }
49
50 /**
51  * glk_time_to_date_utc:
52  * @time: A #glktimeval_t structure as returned by glk_current_time().
53  * @date: An empty #glkdate_t structure to fill in.
54  *
55  * Convert the given timestamp (as returned by glk_current_time()) to a
56  * broken-out structure. This function returns a date and time in universal time
57  * (GMT).
58  *
59  * <note><para>
60  *   The seconds value may be 60 because of a leap second.
61  * </para></note>
62  */
63 void
64 glk_time_to_date_utc(glktimeval_t *time, glkdate_t *date)
65 {
66         g_return_if_fail(time != NULL);
67         g_return_if_fail(date != NULL);
68 }
69
70 /**
71  * glk_time_to_date_local:
72  * @time: A #glktimeval_t structure as returned by glk_current_time().
73  * @date: An empty #glkdate_t structure to fill in.
74  *
75  * Does the same thing as glk_time_to_date_utc(), but this function returns
76  * local time.
77  */
78 void
79 glk_time_to_date_local(glktimeval_t *time, glkdate_t *date)
80 {
81         g_return_if_fail(time != NULL);
82         g_return_if_fail(date != NULL);
83 }
84
85 /**
86  * glk_simple_time_to_date_utc:
87  * @time: Timestamp as returned by glk_current_simple_time().
88  * @factor: Factor by which to multiply @time in order to get seconds.
89  * @date: An empty #glkdate_t structure to fill in.
90  *
91  * Convert the given timestamp (as returned by glk_current_simple_time()) to a
92  * broken-out structure in universal time. The @time argument is multiplied by
93  * @factor to produce a Unix timestamp.
94  *
95  * Since the resolution of glk_simple_time_to_date_utc() and
96  * glk_simple_time_to_date_local() is no better than seconds, they will return
97  * zero for the microseconds value. 
98  */ 
99 void
100 glk_simple_time_to_date_utc(glsi32 time, glui32 factor, glkdate_t *date)
101 {
102         g_return_if_fail(factor != 0);
103         g_return_if_fail(date != NULL);
104 }
105
106 /**
107  * glk_simple_time_to_date_local:
108  * @time: Timestamp as returned by glk_current_simple_time().
109  * @factor: Factor by which to multiply @time in order to get seconds.
110  * @date: An empty #glkdate_t structure to fill in.
111  *
112  * Does the same thing as glk_simple_time_to_date_utc(), but fills in the @date
113  * structure in local time.
114  */
115 void
116 glk_simple_time_to_date_local(glsi32 time, glui32 factor, glkdate_t *date)
117 {
118         g_return_if_fail(factor != 0);
119         g_return_if_fail(date != NULL);
120 }
121
122 /**
123  * glk_date_to_time_utc:
124  * @date: A date in the form of a #glkdate_t structure.
125  * @time: An empty #glktimeval_t structure to fill in.
126  *
127  * Convert the broken-out structure (interpreted as universal time) to a
128  * timestamp. The weekday value in @date is ignored. The other values need not
129  * be in their normal ranges; they will be normalized.
130  *
131  * If the time cannot be represented by the platform's time library, this may
132  * return -1 for the seconds value. (I.e., the @high_sec and @low_sec fields
133  * both $FFFFFFFF. The microseconds field is undefined in this case.)
134  */
135 void
136 glk_date_to_time_utc(glkdate_t *date, glktimeval_t *time)
137 {
138         g_return_if_fail(date != NULL);
139         g_return_if_fail(time != NULL);
140 }
141
142 /**
143  * glk_date_to_time_local:
144  * @date: A date in the form of a #glkdate_t structure.
145  * @time: An empty #glktimeval_t structure to fill in.
146  *
147  * Does the same thing as glk_date_to_time_utc(), but interprets the broken-out
148  * structure as local time.
149  *
150  * The glk_date_to_time_local() function may not be smart about Daylight Saving
151  * Time conversions.
152  * <note><para>
153  *   If implemented with the mktime() libc function, it should use the negative
154  *   @tm_isdst flag to <quote>attempt to divine whether summer time is in
155  *   effect</quote>.
156  * </para></note>
157  */
158 void
159 glk_date_to_time_local(glkdate_t *date, glktimeval_t *time)
160 {
161         g_return_if_fail(date != NULL);
162         g_return_if_fail(time != NULL);
163 }
164
165 /**
166  * glk_date_to_simple_time_utc:
167  * @date: A date in the form of a #glkdate_t structure.
168  * @factor: Factor by which to divide the time value.
169  *
170  * Convert the broken-out structure (interpreted as universal time) to a
171  * timestamp divided by @factor. The weekday value in @date is ignored. The
172  * other values need not be in their normal ranges; they will be normalized.
173  *
174  * If the time cannot be represented by the platform's time library, this may
175  * return -1.
176  *
177  * Returns: a timestamp divided by @factor, and truncated to 32 bits, or -1 on
178  * error.
179  */
180 glsi32
181 glk_date_to_simple_time_utc(glkdate_t *date, glui32 factor)
182 {
183         g_return_val_if_fail(date != NULL, -1);
184         g_return_val_if_fail(factor != 0, -1);
185         
186         return -1;
187 }
188
189 /**
190  * glk_date_to_simple_time_local:
191  * @date: A date in the form of a #glkdate_t structure.
192  * @factor: Factor by which to divide the time value.
193  *
194  * Does the same thing as glk_date_to_simple_time_utc(), but interprets the
195  * broken-out structure as local time.
196  *
197  * Returns: a timestamp divided by @factor, and truncated to 32 bits, or -1 on
198  * error.
199  */
200 glsi32
201 glk_date_to_simple_time_local(glkdate_t *date, glui32 factor)
202 {
203         g_return_val_if_fail(date != NULL, -1);
204         g_return_val_if_fail(factor != 0, -1);
205         
206         return -1;
207 }