OLD | NEW |
| (Empty) |
1 /* | |
2 ******************************************************************************* | |
3 * Copyright (C) 2004 - 2008, International Business Machines Corporation and | |
4 * others. All Rights Reserved. | |
5 ******************************************************************************* | |
6 */ | |
7 | |
8 #ifndef UTMSCALE_H | |
9 #define UTMSCALE_H | |
10 | |
11 #include "unicode/utypes.h" | |
12 | |
13 #if !UCONFIG_NO_FORMATTING | |
14 | |
15 /** | |
16 * \file | |
17 * \brief C API: Universal Time Scale | |
18 * | |
19 * There are quite a few different conventions for binary datetime, depending on
different | |
20 * platforms and protocols. Some of these have severe drawbacks. For example, pe
ople using | |
21 * Unix time (seconds since Jan 1, 1970) think that they are safe until near the
year 2038. | |
22 * But cases can and do arise where arithmetic manipulations causes serious prob
lems. Consider | |
23 * the computation of the average of two datetimes, for example: if one calculat
es them with | |
24 * <code>averageTime = (time1 + time2)/2</code>, there will be overflow even wit
h dates | |
25 * around the present. Moreover, even if these problems don't occur, there is th
e issue of | |
26 * conversion back and forth between different systems. | |
27 * | |
28 * <p> | |
29 * Binary datetimes differ in a number of ways: the datatype, the unit, | |
30 * and the epoch (origin). We'll refer to these as time scales. For example: | |
31 * | |
32 * <table border="1" cellspacing="0" cellpadding="4"> | |
33 * <caption>Table 1: Binary Time Scales</caption> | |
34 * <tr> | |
35 * <th align="left">Source</th> | |
36 * <th align="left">Datatype</th> | |
37 * <th align="left">Unit</th> | |
38 * <th align="left">Epoch</th> | |
39 * </tr> | |
40 * | |
41 * <tr> | |
42 * <td>UDTS_JAVA_TIME</td> | |
43 * <td>int64_t</td> | |
44 * <td>milliseconds</td> | |
45 * <td>Jan 1, 1970</td> | |
46 * </tr> | |
47 * <tr> | |
48 * | |
49 * <td>UDTS_UNIX_TIME</td> | |
50 * <td>int32_t or int64_t</td> | |
51 * <td>seconds</td> | |
52 * <td>Jan 1, 1970</td> | |
53 * </tr> | |
54 * <tr> | |
55 * <td>UDTS_ICU4C_TIME</td> | |
56 * | |
57 * <td>double</td> | |
58 * <td>milliseconds</td> | |
59 * <td>Jan 1, 1970</td> | |
60 * </tr> | |
61 * <tr> | |
62 * <td>UDTS_WINDOWS_FILE_TIME</td> | |
63 * <td>int64_t</td> | |
64 * | |
65 * <td>ticks (100 nanoseconds)</td> | |
66 * <td>Jan 1, 1601</td> | |
67 * </tr> | |
68 * <tr> | |
69 * <td>UDTS_DOTNET_DATE_TIME</td> | |
70 * <td>int64_t</td> | |
71 * <td>ticks (100 nanoseconds)</td> | |
72 * | |
73 * <td>Jan 1, 0001</td> | |
74 * </tr> | |
75 * <tr> | |
76 * <td>UDTS_MAC_OLD_TIME</td> | |
77 * <td>int32_t or int64_t</td> | |
78 * <td>seconds</td> | |
79 * <td>Jan 1, 1904</td> | |
80 * | |
81 * </tr> | |
82 * <tr> | |
83 * <td>UDTS_MAC_TIME</td> | |
84 * <td>double</td> | |
85 * <td>seconds</td> | |
86 * <td>Jan 1, 2001</td> | |
87 * </tr> | |
88 * | |
89 * <tr> | |
90 * <td>UDTS_EXCEL_TIME</td> | |
91 * <td>?</td> | |
92 * <td>days</td> | |
93 * <td>Dec 31, 1899</td> | |
94 * </tr> | |
95 * <tr> | |
96 * | |
97 * <td>UDTS_DB2_TIME</td> | |
98 * <td>?</td> | |
99 * <td>days</td> | |
100 * <td>Dec 31, 1899</td> | |
101 * </tr> | |
102 * | |
103 * <tr> | |
104 * <td>UDTS_UNIX_MICROSECONDS_TIME</td> | |
105 * <td>int64_t</td> | |
106 * <td>microseconds</td> | |
107 * <td>Jan 1, 1970</td> | |
108 * </tr> | |
109 * </table> | |
110 * | |
111 * <p> | |
112 * All of the epochs start at 00:00 am (the earliest possible time on the day in
question), | |
113 * and are assumed to be UTC. | |
114 * | |
115 * <p> | |
116 * The ranges for different datatypes are given in the following table (all valu
es in years). | |
117 * The range of years includes the entire range expressible with positive and ne
gative | |
118 * values of the datatype. The range of years for double is the range that would
be allowed | |
119 * without losing precision to the corresponding unit. | |
120 * | |
121 * <table border="1" cellspacing="0" cellpadding="4"> | |
122 * <tr> | |
123 * <th align="left">Units</th> | |
124 * <th align="left">int64_t</th> | |
125 * <th align="left">double</th> | |
126 * <th align="left">int32_t</th> | |
127 * </tr> | |
128 * | |
129 * <tr> | |
130 * <td>1 sec</td> | |
131 * <td align="right">5.84542x10<sup>11</sup></td> | |
132 * <td align="right">285,420,920.94</td> | |
133 * <td align="right">136.10</td> | |
134 * </tr> | |
135 * <tr> | |
136 * | |
137 * <td>1 millisecond</td> | |
138 * <td align="right">584,542,046.09</td> | |
139 * <td align="right">285,420.92</td> | |
140 * <td align="right">0.14</td> | |
141 * </tr> | |
142 * <tr> | |
143 * <td>1 microsecond</td> | |
144 * | |
145 * <td align="right">584,542.05</td> | |
146 * <td align="right">285.42</td> | |
147 * <td align="right">0.00</td> | |
148 * </tr> | |
149 * <tr> | |
150 * <td>100 nanoseconds (tick)</td> | |
151 * <td align="right">58,454.20</td> | |
152 * <td align="right">28.54</td> | |
153 * <td align="right">0.00</td> | |
154 * </tr> | |
155 * <tr> | |
156 * <td>1 nanosecond</td> | |
157 * <td align="right">584.5420461</td> | |
158 * <td align="right">0.2854</td> | |
159 * <td align="right">0.00</td> | |
160 * </tr> | |
161 * </table> | |
162 * | |
163 * <p> | |
164 * These functions implement a universal time scale which can be used as a 'pivo
t', | |
165 * and provide conversion functions to and from all other major time scales. | |
166 * This datetimes to be converted to the pivot time, safely manipulated, | |
167 * and converted back to any other datetime time scale. | |
168 * | |
169 *<p> | |
170 * So what to use for this pivot? Java time has plenty of range, but cannot repr
esent | |
171 * .NET <code>System.DateTime</code> values without severe loss of precision. IC
U4C time addresses this by using a | |
172 * <code>double</code> that is otherwise equivalent to the Java time. However, t
here are disadvantages | |
173 * with <code>doubles</code>. They provide for much more graceful degradation in
arithmetic operations. | |
174 * But they only have 53 bits of accuracy, which means that they will lose preci
sion when | |
175 * converting back and forth to ticks. What would really be nice would be a | |
176 * <code>long double</code> (80 bits -- 64 bit mantissa), but that is not suppor
ted on most systems. | |
177 * | |
178 *<p> | |
179 * The Unix extended time uses a structure with two components: time in seconds
and a | |
180 * fractional field (microseconds). However, this is clumsy, slow, and | |
181 * prone to error (you always have to keep track of overflow and underflow in th
e | |
182 * fractional field). <code>BigDecimal</code> would allow for arbitrary precisio
n and arbitrary range, | |
183 * but we do not want to use this as the normal type, because it is slow and doe
s not | |
184 * have a fixed size. | |
185 * | |
186 *<p> | |
187 * Because of these issues, we ended up concluding that the .NET framework's | |
188 * <code>System.DateTime</code> would be the best pivot. However, we use the ful
l range | |
189 * allowed by the datatype, allowing for datetimes back to 29,000 BC and up to 2
9,000 AD. | |
190 * This time scale is very fine grained, does not lose precision, and covers a r
ange that | |
191 * will meet almost all requirements. It will not handle the range that Java tim
es do, | |
192 * but frankly, being able to handle dates before 29,000 BC or after 29,000 AD i
s of very limited interest. | |
193 * | |
194 */ | |
195 | |
196 /** | |
197 * <code>UDateTimeScale</code> values are used to specify the time scale used fo
r | |
198 * conversion into or out if the universal time scale. | |
199 * | |
200 * @stable ICU 3.2 | |
201 */ | |
202 typedef enum UDateTimeScale { | |
203 /** | |
204 * Used in the JDK. Data is a Java <code>long</code> (<code>int64_t</code>).
Value | |
205 * is milliseconds since January 1, 1970. | |
206 * | |
207 * @stable ICU 3.2 | |
208 */ | |
209 UDTS_JAVA_TIME = 0, | |
210 | |
211 /** | |
212 * Used on Unix systems. Data is <code>int32_t</code> or <code>int64_t</code
>. Value | |
213 * is seconds since January 1, 1970. | |
214 * | |
215 * @stable ICU 3.2 | |
216 */ | |
217 UDTS_UNIX_TIME, | |
218 | |
219 /** | |
220 * Used in IUC4C. Data is a <code>double</code>. Value | |
221 * is milliseconds since January 1, 1970. | |
222 * | |
223 * @stable ICU 3.2 | |
224 */ | |
225 UDTS_ICU4C_TIME, | |
226 | |
227 /** | |
228 * Used in Windows for file times. Data is an <code>int64_t</code>. Value | |
229 * is ticks (1 tick == 100 nanoseconds) since January 1, 1601. | |
230 * | |
231 * @stable ICU 3.2 | |
232 */ | |
233 UDTS_WINDOWS_FILE_TIME, | |
234 | |
235 /** | |
236 * Used in the .NET framework's <code>System.DateTime</code> structure. Data
is an <code>int64_t</code>. Value | |
237 * is ticks (1 tick == 100 nanoseconds) since January 1, 0001. | |
238 * | |
239 * @stable ICU 3.2 | |
240 */ | |
241 UDTS_DOTNET_DATE_TIME, | |
242 | |
243 /** | |
244 * Used in older Macintosh systems. Data is <code>int32_t</code> or <code>in
t64_t</code>. Value | |
245 * is seconds since January 1, 1904. | |
246 * | |
247 * @stable ICU 3.2 | |
248 */ | |
249 UDTS_MAC_OLD_TIME, | |
250 | |
251 /** | |
252 * Used in newer Macintosh systems. Data is a <code>double</code>. Value | |
253 * is seconds since January 1, 2001. | |
254 * | |
255 * @stable ICU 3.2 | |
256 */ | |
257 UDTS_MAC_TIME, | |
258 | |
259 /** | |
260 * Used in Excel. Data is an <code>?unknown?</code>. Value | |
261 * is days since December 31, 1899. | |
262 * | |
263 * @stable ICU 3.2 | |
264 */ | |
265 UDTS_EXCEL_TIME, | |
266 | |
267 /** | |
268 * Used in DB2. Data is an <code>?unknown?</code>. Value | |
269 * is days since December 31, 1899. | |
270 * | |
271 * @stable ICU 3.2 | |
272 */ | |
273 UDTS_DB2_TIME, | |
274 | |
275 /** | |
276 * Data is a <code>long</code>. Value is microseconds since January 1, 1970. | |
277 * Similar to Unix time (linear value from 1970) and struct timeval | |
278 * (microseconds resolution). | |
279 * | |
280 * @stable ICU 3.8 | |
281 */ | |
282 UDTS_UNIX_MICROSECONDS_TIME, | |
283 | |
284 /** | |
285 * The first unused time scale value. The limit of this enum | |
286 */ | |
287 UDTS_MAX_SCALE | |
288 } UDateTimeScale; | |
289 | |
290 /** | |
291 * <code>UTimeScaleValue</code> values are used to specify the time scale values | |
292 * to <code>utmscale_getTimeScaleValue</code>. | |
293 * | |
294 * @see utmscale_getTimeScaleValue | |
295 * | |
296 * @stable ICU 3.2 | |
297 */ | |
298 typedef enum UTimeScaleValue { | |
299 /** | |
300 * The constant used to select the units vale | |
301 * for a time scale. | |
302 * | |
303 * @see utmscale_getTimeScaleValue | |
304 * | |
305 * @stable ICU 3.2 | |
306 */ | |
307 UTSV_UNITS_VALUE = 0, | |
308 | |
309 /** | |
310 * The constant used to select the epoch offset value | |
311 * for a time scale. | |
312 * | |
313 * @see utmscale_getTimeScaleValue | |
314 * | |
315 * @stable ICU 3.2 | |
316 */ | |
317 UTSV_EPOCH_OFFSET_VALUE=1, | |
318 | |
319 /** | |
320 * The constant used to select the minimum from value | |
321 * for a time scale. | |
322 * | |
323 * @see utmscale_getTimeScaleValue | |
324 * | |
325 * @stable ICU 3.2 | |
326 */ | |
327 UTSV_FROM_MIN_VALUE=2, | |
328 | |
329 /** | |
330 * The constant used to select the maximum from value | |
331 * for a time scale. | |
332 * | |
333 * @see utmscale_getTimeScaleValue | |
334 * | |
335 * @stable ICU 3.2 | |
336 */ | |
337 UTSV_FROM_MAX_VALUE=3, | |
338 | |
339 /** | |
340 * The constant used to select the minimum to value | |
341 * for a time scale. | |
342 * | |
343 * @see utmscale_getTimeScaleValue | |
344 * | |
345 * @stable ICU 3.2 | |
346 */ | |
347 UTSV_TO_MIN_VALUE=4, | |
348 | |
349 /** | |
350 * The constant used to select the maximum to value | |
351 * for a time scale. | |
352 * | |
353 * @see utmscale_getTimeScaleValue | |
354 * | |
355 * @stable ICU 3.2 | |
356 */ | |
357 UTSV_TO_MAX_VALUE=5, | |
358 | |
359 #ifndef U_HIDE_INTERNAL_API | |
360 /** | |
361 * The constant used to select the epoch plus one value | |
362 * for a time scale. | |
363 * | |
364 * NOTE: This is an internal value. DO NOT USE IT. May not | |
365 * actually be equal to the epoch offset value plus one. | |
366 * | |
367 * @see utmscale_getTimeScaleValue | |
368 * | |
369 * @internal ICU 3.2 | |
370 */ | |
371 UTSV_EPOCH_OFFSET_PLUS_1_VALUE=6, | |
372 | |
373 /** | |
374 * The constant used to select the epoch plus one value | |
375 * for a time scale. | |
376 * | |
377 * NOTE: This is an internal value. DO NOT USE IT. May not | |
378 * actually be equal to the epoch offset value plus one. | |
379 * | |
380 * @see utmscale_getTimeScaleValue | |
381 * | |
382 * @internal ICU 3.2 | |
383 */ | |
384 UTSV_EPOCH_OFFSET_MINUS_1_VALUE=7, | |
385 | |
386 /** | |
387 * The constant used to select the units round value | |
388 * for a time scale. | |
389 * | |
390 * NOTE: This is an internal value. DO NOT USE IT. | |
391 * | |
392 * @see utmscale_getTimeScaleValue | |
393 * | |
394 * @internal ICU 3.2 | |
395 */ | |
396 UTSV_UNITS_ROUND_VALUE=8, | |
397 | |
398 /** | |
399 * The constant used to select the minimum safe rounding value | |
400 * for a time scale. | |
401 * | |
402 * NOTE: This is an internal value. DO NOT USE IT. | |
403 * | |
404 * @see utmscale_getTimeScaleValue | |
405 * | |
406 * @internal ICU 3.2 | |
407 */ | |
408 UTSV_MIN_ROUND_VALUE=9, | |
409 | |
410 /** | |
411 * The constant used to select the maximum safe rounding value | |
412 * for a time scale. | |
413 * | |
414 * NOTE: This is an internal value. DO NOT USE IT. | |
415 * | |
416 * @see utmscale_getTimeScaleValue | |
417 * | |
418 * @internal ICU 3.2 | |
419 */ | |
420 UTSV_MAX_ROUND_VALUE=10, | |
421 | |
422 #endif /* U_HIDE_INTERNAL_API */ | |
423 | |
424 /** | |
425 * The number of time scale values, in other words limit of this enum. | |
426 * | |
427 * @see utmscale_getTimeScaleValue | |
428 */ | |
429 UTSV_MAX_SCALE_VALUE=11 | |
430 | |
431 } UTimeScaleValue; | |
432 | |
433 /** | |
434 * Get a value associated with a particular time scale. | |
435 * | |
436 * @param timeScale The time scale | |
437 * @param value A constant representing the value to get | |
438 * @param status The status code. Set to <code>U_ILLEGAL_ARGUMENT_ERROR</code> i
f arguments are invalid. | |
439 * @return - the value. | |
440 * | |
441 * @stable ICU 3.2 | |
442 */ | |
443 U_STABLE int64_t U_EXPORT2 | |
444 utmscale_getTimeScaleValue(UDateTimeScale timeScale, UTimeScaleValue value,
UErrorCode *status); | |
445 | |
446 /* Conversion to 'universal time scale' */ | |
447 | |
448 /** | |
449 * Convert a <code>int64_t</code> datetime from the given time scale to the univ
ersal time scale. | |
450 * | |
451 * @param otherTime The <code>int64_t</code> datetime | |
452 * @param timeScale The time scale to convert from | |
453 * @param status The status code. Set to <code>U_ILLEGAL_ARGUMENT_ERROR</code> i
f the conversion is out of range. | |
454 * | |
455 * @return The datetime converted to the universal time scale | |
456 * | |
457 * @stable ICU 3.2 | |
458 */ | |
459 U_STABLE int64_t U_EXPORT2 | |
460 utmscale_fromInt64(int64_t otherTime, UDateTimeScale timeScale, UErrorCode *
status); | |
461 | |
462 /* Conversion from 'universal time scale' */ | |
463 | |
464 /** | |
465 * Convert a datetime from the universal time scale to a <code>int64_t</code> in
the given time scale. | |
466 * | |
467 * @param universalTime The datetime in the universal time scale | |
468 * @param timeScale The time scale to convert to | |
469 * @param status The status code. Set to <code>U_ILLEGAL_ARGUMENT_ERROR</code> i
f the conversion is out of range. | |
470 * | |
471 * @return The datetime converted to the given time scale | |
472 * | |
473 * @stable ICU 3.2 | |
474 */ | |
475 U_STABLE int64_t U_EXPORT2 | |
476 utmscale_toInt64(int64_t universalTime, UDateTimeScale timeScale, UErrorCode
*status); | |
477 | |
478 #endif /* #if !UCONFIG_NO_FORMATTING */ | |
479 | |
480 #endif | |
481 | |
OLD | NEW |