2
*******************************************************************************
3
* Copyright (C) 1996-2001, International Business Machines Corporation and others. All Rights Reserved.
4
*******************************************************************************
10
#include "unicode/utypes.h"
11
#include "unicode/ucal.h"
12
#include "unicode/unum.h"
15
* \brief C API: DateFormat
17
* <h2> Date Format C API</h2>
19
* Date Format C API consists of functions that convert dates and
20
* times from their internal representations to textual form and back again in a
21
* language-independent manner. Converting from the internal representation (milliseconds
22
* since midnight, January 1, 1970) to text is known as "formatting," and converting
23
* from text to millis is known as "parsing." We currently define only one concrete
24
* structure UDateFormat, which can handle pretty much all normal
25
* date formatting and parsing actions.
27
* Date Format helps you to format and parse dates for any locale. Your code can
28
* be completely independent of the locale conventions for months, days of the
29
* week, or even the calendar format: lunar vs. solar.
31
* To format a date for the current Locale with default time and date style,
32
* use one of the static factory methods:
35
* UErrorCode status = U_ZERO_ERROR;
37
* int32_t myStrlen = 0;
38
* UDateFormat* dfmt = udat_open(UCAL_DEFAULT, UCAL_DEFAULT, NULL, "PST", &status);
39
* myStrlen = udat_format(dfmt, myDate, NULL, myStrlen, NULL, &status);
40
* if (status==U_BUFFER_OVERFLOW_ERROR){
41
* status=U_ZERO_ERROR;
42
* myString=(UChar*)malloc(sizeof(UChar) * (myStrlen+1) );
43
* udat_format(dfmt, myDate, myString, myStrlen+1, NULL, &status);
47
* If you are formatting multiple numbers, it is more efficient to get the
48
* format and use it multiple times so that the system doesn't have to fetch the
49
* information about the local language and country conventions multiple times.
52
* UErrorCode status = U_ZERO_ERROR;
53
* int32_t i, myStrlen = 0;
56
* UDate myDateArr[] = { 0.0, 100000000.0, 2000000000.0 }; // test values
57
* UDateFormat* df = udat_open(UCAL_DEFAULT, UCAL_DEFAULT, NULL, "GMT", &status);
58
* for (i = 0; i < 3; i++) {
59
* myStrlen = udat_format(df, myDateArr[i], NULL, myStrlen, NULL, &status);
60
* if(status == U_BUFFER_OVERFLOW_ERROR){
61
* status = U_ZERO_ERROR;
62
* myString = (UChar*)malloc(sizeof(UChar) * (myStrlen+1) );
63
* udat_format(df, myDateArr[i], myString, myStrlen+1, NULL, &status);
64
* printf("%s\n", u_austrcpy(buffer, myString) );
70
* To get specific fields of a date, you can use UFieldPosition to
71
* get specific fields.
74
* UErrorCode status = U_ZERO_ERROR;
77
* int32_t myStrlen = 0;
80
* pos.field = 1; // Same as the DateFormat::EField enum
81
* UDateFormat* dfmt = udat_open(UCAL_DEFAULT, UCAL_DEFAULT, NULL, "PST", &status);
82
* myStrlen = udat_format(dfmt, myDate, NULL, myStrlen, &pos, &status);
83
* if (status==U_BUFFER_OVERFLOW_ERROR){
84
* status=U_ZERO_ERROR;
85
* myString=(UChar*)malloc(sizeof(UChar) * (myStrlen+1) );
86
* udat_format(dfmt, myDate, myString, myStrlen+1, &pos, &status);
88
* printf("date format: %s\n", u_austrcpy(buffer, myString));
89
* buffer[pos.endIndex] = 0; // NULL terminate the string.
90
* printf("UFieldPosition position equals %s\n", &buffer[pos.beginIndex]);
93
* To format a date for a different Locale, specify it in the call to
97
* UDateFormat* df = udat_open(UDAT_SHORT, UDAT_SHORT, "fr_FR", "GMT", &status);
100
* You can use a DateFormat API udat_parse() to parse.
103
* UErrorCode status = U_ZERO_ERROR;
104
* int32_t parsepos=0;
105
* UDate myDate = udat_parse(df, myString, u_strlen(myString), &parsepos, &status);
108
* You can pass in different options for the arguments for date and time style
109
* to control the length of the result; from SHORT to MEDIUM to LONG to FULL.
110
* The exact result depends on the locale, but generally:
111
* see UDateFormatStyle for more details
113
* <li> UDAT_SHORT is completely numeric, such as 12/13/52 or 3:30pm
114
* <li> UDAT_MEDIUM is longer, such as Jan 12, 1952
115
* <li> UDAT_LONG is longer, such as January 12, 1952 or 3:30:32pm
116
* <li> UDAT_FULL is pretty completely specified, such as
117
* Tuesday, April 12, 1952 AD or 3:30:42pm PST.
119
* You can also set the time zone on the format if you wish.
121
* You can also use forms of the parse and format methods with Parse Position and
122
* UFieldPosition to allow you to
124
* <li> Progressively parse through pieces of a string.
125
* <li> Align any particular field, or find out where it is for selection
130
/** A date formatter.
131
* For usage in C programs.
133
typedef void* UDateFormat;
135
/** The possible date/time format styles */
136
enum UDateFormatStyle {
146
UDAT_DEFAULT = UDAT_MEDIUM,
149
/** for internal API use only */
153
typedef enum UDateFormatStyle UDateFormatStyle;
156
* Open a new UDateFormat for formatting and parsing dates and times.
157
* A UDateFormat may be used to format dates in calls to \Ref{udat_format},
158
* and to parse dates in calls to \Ref{udat_parse}.
159
* @param timeStyle The style used to format times; one of UDAT_FULL_STYLE, UDAT_LONG_STYLE,
160
* UDAT_MEDIUM_STYLE, UDAT_SHORT_STYLE, or UDAT_DEFAULT_STYLE
161
* @param dateStyle The style used to format dates; one of UDAT_FULL_STYLE, UDAT_LONG_STYLE,
162
* UDAT_MEDIUM_STYLE, UDAT_SHORT_STYLE, or UDAT_DEFAULT_STYLE
163
* @param locale The locale specifying the formatting conventions
164
* @param tzID A timezone ID specifying the timezone to use. If 0, use
165
* the default timezone.
166
* @param tzIDLength The length of tzID, or -1 if null-terminated.
167
* @param status A pointer to an UErrorCode to receive any errors
168
* @param pattern A pattern specifying the format to use.
169
* @param patternLength The number of characters in the pattern, or -1 if null-terminated.
170
* @param locale The locale specifying the formatting conventions
171
* @param status A pointer to an UErrorCode to receive any errors
172
* @return A pointer to a UDateFormat to use for formatting dates and times, or 0 if
176
U_CAPI UDateFormat* U_EXPORT2
177
udat_open(UDateFormatStyle timeStyle,
178
UDateFormatStyle dateStyle,
182
const UChar *pattern,
183
int32_t patternLength,
188
* Close a UDateFormat.
189
* Once closed, a UDateFormat may no longer be used.
190
* @param fmt The formatter to close.
193
U_CAPI void U_EXPORT2
194
udat_close(UDateFormat* format);
197
* Open a copy of a UDateFormat.
198
* This function performs a deep copy.
199
* @param fmt The format to copy
200
* @param status A pointer to an UErrorCode to receive any errors.
201
* @return A pointer to a UDateFormat identical to fmt.
204
U_CAPI UDateFormat* U_EXPORT2
205
udat_clone(const UDateFormat *fmt,
209
* Format a date using an UDateFormat.
210
* The date will be formatted using the conventions specified in \Ref{udat_open}
211
* or \Ref{udat_openPattern}
212
* @param format The formatter to use
213
* @param dateToFormat The date to format
214
* @param result A pointer to a buffer to receive the formatted number.
215
* @param resultLength The maximum size of result.
216
* @param position A pointer to a UFieldPosition. On input, position->field
217
* is read. On output, position->beginIndex and position->endIndex indicate
218
* the beginning and ending indices of field number position->field, if such
219
* a field exists. This parameter may be NULL, in which case no field
220
* position data is returned.
221
* @param status A pointer to an UErrorCode to receive any errors
222
* @return The total buffer size needed; if greater than resultLength, the output was truncated.
224
* @see UFieldPosition
227
U_CAPI int32_t U_EXPORT2
228
udat_format( const UDateFormat* format,
231
int32_t resultLength,
232
UFieldPosition* position,
236
* Parse a string into an date/time using a UDateFormat.
237
* The date will be parsed using the conventions specified in \Ref{udat_open}
238
* or \Ref{udat_openPattern}
239
* @param fmt The formatter to use.
240
* @param text The text to parse.
241
* @param textLength The length of text, or -1 if null-terminated.
242
* @param parsePos If not 0, on input a pointer to an integer specifying the offset at which
243
* to begin parsing. If not 0, on output the offset at which parsing ended.
244
* @param status A pointer to an UErrorCode to receive any errors
245
* @return The value of the parsed date/time
249
U_CAPI UDate U_EXPORT2
250
udat_parse( const UDateFormat* format,
257
* Parse a string into an date/time using a UDateFormat.
258
* The date will be parsed using the conventions specified in \Ref{udat_open}
259
* or \Ref{udat_openPattern}
260
* @param fmt The formatter to use.
261
* @param calendar The calendar in which to store the parsed data.
262
* @param text The text to parse.
263
* @param textLength The length of text, or -1 if null-terminated.
264
* @param parsePos If not 0, on input a pointer to an integer specifying the offset at which
265
* to begin parsing. If not 0, on output the offset at which parsing ended.
266
* @param status A pointer to an UErrorCode to receive any errors
270
U_CAPI void U_EXPORT2
271
udat_parseCalendar(const UDateFormat* format,
279
* Determine if an UDateFormat will perform lenient parsing.
280
* With lenient parsing, the parser may use heuristics to interpret inputs that do not
281
* precisely match the pattern. With strict parsing, inputs must match the pattern.
282
* @param fmt The formatter to query
283
* @return TRUE if fmt is set to perform lenient parsing, FALSE otherwise.
284
* @see udat_setLenient
287
U_CAPI UBool U_EXPORT2
288
udat_isLenient(const UDateFormat* fmt);
291
* Specify whether an UDateFormat will perform lenient parsing.
292
* With lenient parsing, the parser may use heuristics to interpret inputs that do not
293
* precisely match the pattern. With strict parsing, inputs must match the pattern.
294
* @param fmt The formatter to set
295
* @param isLenient TRUE if fmt should perform lenient parsing, FALSE otherwise.
299
U_CAPI void U_EXPORT2
300
udat_setLenient( UDateFormat* fmt,
304
* Get the UCalendar associated with an UDateFormat.
305
* A UDateFormat uses a UCalendar to convert a raw value to, for example,
306
* the day of the week.
307
* @param fmt The formatter to query.
308
* @return A pointer to the UCalendar used by fmt.
309
* @see udat_setCalendar
312
U_CAPI const UCalendar* U_EXPORT2
313
udat_getCalendar(const UDateFormat* fmt);
316
* Set the UCalendar associated with an UDateFormat.
317
* A UDateFormat uses a UCalendar to convert a raw value to, for example,
318
* the day of the week.
319
* @param fmt The formatter to set.
320
* @param calendarToSet A pointer to an UCalendar to be used by fmt.
321
* @see udat_setCalendar
324
U_CAPI void U_EXPORT2
325
udat_setCalendar( UDateFormat* fmt,
326
const UCalendar* calendarToSet);
329
* Get the UNumberFormat associated with an UDateFormat.
330
* A UDateFormat uses a UNumberFormat to format numbers within a date,
331
* for example the day number.
332
* @param fmt The formatter to query.
333
* @return A pointer to the UNumberFormat used by fmt to format numbers.
334
* @see udat_setNumberFormat
337
U_CAPI const UNumberFormat* U_EXPORT2
338
udat_getNumberFormat(const UDateFormat* fmt);
341
* Set the UNumberFormat associated with an UDateFormat.
342
* A UDateFormat uses a UNumberFormat to format numbers within a date,
343
* for example the day number.
344
* @param fmt The formatter to set.
345
* @param numberFormatToSet A pointer to the UNumberFormat to be used by fmt to format numbers.
346
* @see udat_getNumberFormat
349
U_CAPI void U_EXPORT2
350
udat_setNumberFormat( UDateFormat* fmt,
351
const UNumberFormat* numberFormatToSet);
354
* Get a locale for which date/time formatting patterns are available.
355
* A UDateFormat in a locale returned by this function will perform the correct
356
* formatting and parsing for the locale.
357
* @param index The index of the desired locale.
358
* @return A locale for which date/time formatting patterns are available, or 0 if none.
359
* @see udat_countAvailable
362
U_CAPI const char* U_EXPORT2
363
udat_getAvailable(int32_t index);
366
* Determine how many locales have date/time formatting patterns available.
367
* This function is most useful as determining the loop ending condition for
368
* calls to \Ref{udat_getAvailable}.
369
* @return The number of locales for which date/time formatting patterns are available.
370
* @see udat_getAvailable
373
U_CAPI int32_t U_EXPORT2
374
udat_countAvailable(void);
377
* Get the year relative to which all 2-digit years are interpreted.
378
* For example, if the 2-digit start year is 2100, the year 99 will be
379
* interpreted as 2199.
380
* @param fmt The formatter to query.
381
* @param status A pointer to an UErrorCode to receive any errors
382
* @return The year relative to which all 2-digit years are interpreted.
383
* @see udat_Set2DigitYearStart
386
U_CAPI UDate U_EXPORT2
387
udat_get2DigitYearStart( const UDateFormat *fmt,
391
* Set the year relative to which all 2-digit years will be interpreted.
392
* For example, if the 2-digit start year is 2100, the year 99 will be
393
* interpreted as 2199.
394
* @param fmt The formatter to set.
395
* @param d The year relative to which all 2-digit years will be interpreted.
396
* @param status A pointer to an UErrorCode to receive any errors
397
* @see udat_Set2DigitYearStart
400
U_CAPI void U_EXPORT2
401
udat_set2DigitYearStart( UDateFormat *fmt,
406
* Extract the pattern from a UDateFormat.
407
* The pattern will follow the pattern syntax rules.
408
* @param fmt The formatter to query.
409
* @param localized TRUE if the pattern should be localized, FALSE otherwise.
410
* @param result A pointer to a buffer to receive the pattern.
411
* @param resultLength The maximum size of result.
412
* @param status A pointer to an UErrorCode to receive any errors
413
* @return The total buffer size needed; if greater than resultLength, the output was truncated.
414
* @see udat_applyPattern
417
U_CAPI int32_t U_EXPORT2
418
udat_toPattern( const UDateFormat *fmt,
421
int32_t resultLength,
425
* Set the pattern used by an UDateFormat.
426
* The pattern should follow the pattern syntax rules.
427
* @param fmt The formatter to set.
428
* @param localized TRUE if the pattern is localized, FALSE otherwise.
429
* @param pattern The new pattern
430
* @param patternLength The length of pattern, or -1 if null-terminated.
431
* @see udat_toPattern
434
U_CAPI void U_EXPORT2
435
udat_applyPattern( UDateFormat *format,
437
const UChar *pattern,
438
int32_t patternLength);
440
/** The possible types of date format symbols */
441
enum UDateFormatSymbolType {
442
/** The era names, for example AD */
444
/** The month names, for example February */
446
/** The short month names, for example Feb. */
448
/** The weekday names, for example Monday */
450
/** The short weekday names, for example Mon. */
452
/** The AM/PM names, for example AM */
454
/** The localized characters */
457
typedef enum UDateFormatSymbolType UDateFormatSymbolType;
459
/** Date format symbols.
460
* For usage in C programs.
462
struct UDateFormatSymbols;
463
typedef struct UDateFormatSymbols UDateFormatSymbols;
466
* Get the symbols associated with an UDateFormat.
467
* The symbols are what a UDateFormat uses to represent locale-specific data,
468
* for example month or day names.
469
* @param fmt The formatter to query.
470
* @param type The type of symbols to get. One of UDAT_ERAS, UDAT_MONTHS, UDAT_SHORT_MONTHS,
471
* UDAT_WEEKDAYS, UDAT_SHORT_WEEKDAYS, UDAT_AM_PMS, or UDAT_LOCALIZED_CHARS
472
* @param index The desired symbol of type type.
473
* @param result A pointer to a buffer to receive the pattern.
474
* @param resultLength The maximum size of result.
475
* @param status A pointer to an UErrorCode to receive any errors
476
* @return The total buffer size needed; if greater than resultLength, the output was truncated.
477
* @see udat_countSymbols
478
* @see udat_setSymbols
481
U_CAPI int32_t U_EXPORT2
482
udat_getSymbols(const UDateFormat *fmt,
483
UDateFormatSymbolType type,
486
int32_t resultLength,
490
* Count the number of particular symbols for an UDateFormat.
491
* This function is most useful as for detemining the loop termination condition
492
* for calls to \Ref{udat_getSymbols}.
493
* @param fmt The formatter to query.
494
* @param type The type of symbols to count. One of UDAT_ERAS, UDAT_MONTHS, UDAT_SHORT_MONTHS,
495
* UDAT_WEEKDAYS, UDAT_SHORT_WEEKDAYS, UDAT_AM_PMS, or UDAT_LOCALIZED_CHARS
496
* @return The number of symbols of type type.
497
* @see udat_getSymbols
498
* @see udat_setSymbols
501
U_CAPI int32_t U_EXPORT2
502
udat_countSymbols( const UDateFormat *fmt,
503
UDateFormatSymbolType type);
506
* Set the symbols associated with an UDateFormat.
507
* The symbols are what a UDateFormat uses to represent locale-specific data,
508
* for example month or day names.
509
* @param fmt The formatter to set
510
* @param type The type of symbols to set. One of UDAT_ERAS, UDAT_MONTHS, UDAT_SHORT_MONTHS,
511
* UDAT_WEEKDAYS, UDAT_SHORT_WEEKDAYS, UDAT_AM_PMS, or UDAT_LOCALIZED_CHARS
512
* @param index The index of the symbol to set of type type.
513
* @param value The new value
514
* @param valueLength The length of value, or -1 if null-terminated
515
* @param status A pointer to an UErrorCode to receive any errors
516
* @see udat_getSymbols
517
* @see udat_countSymbols
520
U_CAPI void U_EXPORT2
521
udat_setSymbols( UDateFormat *format,
522
UDateFormatSymbolType type,
528
/********************* Deprecated API ************************************/
530
*@deprecated Remove after Aug 2002
532
#ifdef U_USE_DEPRECATED_FORMAT_API
533
#if ((U_ICU_VERSION_MAJOR_NUM != 2) || (U_ICU_VERSION_MINOR_NUM !=1))
534
# error "ICU version has changed. Please redefine the macros under U_USE_DEPRECATED_FORMAT_API pre-processor definition"
537
udat_openPattern(const UChar* pattern,int32_t patternLength,const char* locale,UErrorCode *status)
539
return udat_open(UDAT_IGNORE,UDAT_IGNORE,locale,NULL,0,pattern,patternLength,status);
542
# define udat_open_2_1(timeStyle,dateStyle,locale,tzId,tzIdLength,status) udat_open(timeStyle,dateStyle,locale,tzId,tzIdLength,NULL,0,status)
545
/********************* End **********************************************/
added
removed
source/i18n/unicode/udat.h
