]>
Commit | Line | Data |
---|---|---|
1 | // © 2016 and later: Unicode, Inc. and others. | |
2 | // License & terms of use: http://www.unicode.org/copyright.html | |
3 | /* | |
4 | ******************************************************************************* | |
5 | * | |
6 | * Copyright (C) 2007-2015, International Business Machines | |
7 | * Corporation and others. All Rights Reserved. | |
8 | * | |
9 | ******************************************************************************* | |
10 | * file name: udatpg.h | |
11 | * encoding: UTF-8 | |
12 | * tab size: 8 (not used) | |
13 | * indentation:4 | |
14 | * | |
15 | * created on: 2007jul30 | |
16 | * created by: Markus W. Scherer | |
17 | */ | |
18 | ||
19 | #ifndef __UDATPG_H__ | |
20 | #define __UDATPG_H__ | |
21 | ||
22 | #include "unicode/utypes.h" | |
23 | #include "unicode/uenum.h" | |
24 | #include "unicode/localpointer.h" | |
25 | ||
26 | /** | |
27 | * \file | |
28 | * \brief C API: Wrapper for icu::DateTimePatternGenerator (unicode/dtptngen.h). | |
29 | * | |
30 | * UDateTimePatternGenerator provides flexible generation of date format patterns, | |
31 | * like "yy-MM-dd". The user can build up the generator by adding successive | |
32 | * patterns. Once that is done, a query can be made using a "skeleton", which is | |
33 | * a pattern which just includes the desired fields and lengths. The generator | |
34 | * will return the "best fit" pattern corresponding to that skeleton. | |
35 | * <p>The main method people will use is udatpg_getBestPattern, since normally | |
36 | * UDateTimePatternGenerator is pre-built with data from a particular locale. | |
37 | * However, generators can be built directly from other data as well. | |
38 | * <p><i>Issue: may be useful to also have a function that returns the list of | |
39 | * fields in a pattern, in order, since we have that internally. | |
40 | * That would be useful for getting the UI order of field elements.</i> | |
41 | */ | |
42 | ||
43 | /** | |
44 | * Opaque type for a date/time pattern generator object. | |
45 | * @stable ICU 3.8 | |
46 | */ | |
47 | typedef void *UDateTimePatternGenerator; | |
48 | ||
49 | /** | |
50 | * Field number constants for udatpg_getAppendItemFormats() and similar functions. | |
51 | * These constants are separate from UDateFormatField despite semantic overlap | |
52 | * because some fields are merged for the date/time pattern generator. | |
53 | * @stable ICU 3.8 | |
54 | */ | |
55 | typedef enum UDateTimePatternField { | |
56 | /** @stable ICU 3.8 */ | |
57 | UDATPG_ERA_FIELD, | |
58 | /** @stable ICU 3.8 */ | |
59 | UDATPG_YEAR_FIELD, | |
60 | /** @stable ICU 3.8 */ | |
61 | UDATPG_QUARTER_FIELD, | |
62 | /** @stable ICU 3.8 */ | |
63 | UDATPG_MONTH_FIELD, | |
64 | /** @stable ICU 3.8 */ | |
65 | UDATPG_WEEK_OF_YEAR_FIELD, | |
66 | /** @stable ICU 3.8 */ | |
67 | UDATPG_WEEK_OF_MONTH_FIELD, | |
68 | /** @stable ICU 3.8 */ | |
69 | UDATPG_WEEKDAY_FIELD, | |
70 | /** @stable ICU 3.8 */ | |
71 | UDATPG_DAY_OF_YEAR_FIELD, | |
72 | /** @stable ICU 3.8 */ | |
73 | UDATPG_DAY_OF_WEEK_IN_MONTH_FIELD, | |
74 | /** @stable ICU 3.8 */ | |
75 | UDATPG_DAY_FIELD, | |
76 | /** @stable ICU 3.8 */ | |
77 | UDATPG_DAYPERIOD_FIELD, | |
78 | /** @stable ICU 3.8 */ | |
79 | UDATPG_HOUR_FIELD, | |
80 | /** @stable ICU 3.8 */ | |
81 | UDATPG_MINUTE_FIELD, | |
82 | /** @stable ICU 3.8 */ | |
83 | UDATPG_SECOND_FIELD, | |
84 | /** @stable ICU 3.8 */ | |
85 | UDATPG_FRACTIONAL_SECOND_FIELD, | |
86 | /** @stable ICU 3.8 */ | |
87 | UDATPG_ZONE_FIELD, | |
88 | ||
89 | /* Do not conditionalize the following with #ifndef U_HIDE_DEPRECATED_API, | |
90 | * it is needed for layout of DateTimePatternGenerator object. */ | |
91 | /** | |
92 | * One more than the highest normal UDateTimePatternField value. | |
93 | * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. | |
94 | */ | |
95 | UDATPG_FIELD_COUNT | |
96 | } UDateTimePatternField; | |
97 | ||
98 | /** | |
99 | * Field display name width constants for udatpg_getFieldDisplayName(). | |
100 | * @stable ICU 61 | |
101 | */ | |
102 | typedef enum UDateTimePGDisplayWidth { | |
103 | /** @stable ICU 61 */ | |
104 | UDATPG_WIDE, | |
105 | /** @stable ICU 61 */ | |
106 | UDATPG_ABBREVIATED, | |
107 | /** @stable ICU 61 */ | |
108 | UDATPG_NARROW | |
109 | } UDateTimePGDisplayWidth; | |
110 | ||
111 | /** | |
112 | * Masks to control forcing the length of specified fields in the returned | |
113 | * pattern to match those in the skeleton (when this would not happen | |
114 | * otherwise). These may be combined to force the length of multiple fields. | |
115 | * Used with udatpg_getBestPatternWithOptions, udatpg_replaceFieldTypesWithOptions. | |
116 | * @stable ICU 4.4 | |
117 | */ | |
118 | typedef enum UDateTimePatternMatchOptions { | |
119 | /** @stable ICU 4.4 */ | |
120 | UDATPG_MATCH_NO_OPTIONS = 0, | |
121 | /** @stable ICU 4.4 */ | |
122 | UDATPG_MATCH_HOUR_FIELD_LENGTH = 1 << UDATPG_HOUR_FIELD, | |
123 | #ifndef U_HIDE_INTERNAL_API | |
124 | /** @internal ICU 4.4 */ | |
125 | UDATPG_MATCH_MINUTE_FIELD_LENGTH = 1 << UDATPG_MINUTE_FIELD, | |
126 | /** @internal ICU 4.4 */ | |
127 | UDATPG_MATCH_SECOND_FIELD_LENGTH = 1 << UDATPG_SECOND_FIELD, | |
128 | #endif /* U_HIDE_INTERNAL_API */ | |
129 | /** @stable ICU 4.4 */ | |
130 | UDATPG_MATCH_ALL_FIELDS_LENGTH = (1 << UDATPG_FIELD_COUNT) - 1, | |
131 | /** @internal, Apple-specific for now */ | |
132 | UADATPG_FORCE_12_HOUR_CYCLE = 1 << 29, | |
133 | /** @internal, Apple-specific for now */ | |
134 | UADATPG_FORCE_24_HOUR_CYCLE = 1 << 30, | |
135 | /** @internal, Apple-specific for now */ | |
136 | UADATPG_FORCE_HOUR_CYCLE_MASK = 3 << 29, | |
137 | } UDateTimePatternMatchOptions; | |
138 | ||
139 | /** | |
140 | * Status return values from udatpg_addPattern(). | |
141 | * @stable ICU 3.8 | |
142 | */ | |
143 | typedef enum UDateTimePatternConflict { | |
144 | /** @stable ICU 3.8 */ | |
145 | UDATPG_NO_CONFLICT, | |
146 | /** @stable ICU 3.8 */ | |
147 | UDATPG_BASE_CONFLICT, | |
148 | /** @stable ICU 3.8 */ | |
149 | UDATPG_CONFLICT, | |
150 | #ifndef U_HIDE_DEPRECATED_API | |
151 | /** | |
152 | * One more than the highest normal UDateTimePatternConflict value. | |
153 | * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. | |
154 | */ | |
155 | UDATPG_CONFLICT_COUNT | |
156 | #endif // U_HIDE_DEPRECATED_API | |
157 | } UDateTimePatternConflict; | |
158 | ||
159 | /** | |
160 | * Open a generator according to a given locale. | |
161 | * @param locale | |
162 | * @param pErrorCode a pointer to the UErrorCode which must not indicate a | |
163 | * failure before the function call. | |
164 | * @return a pointer to UDateTimePatternGenerator. | |
165 | * @stable ICU 3.8 | |
166 | */ | |
167 | U_STABLE UDateTimePatternGenerator * U_EXPORT2 | |
168 | udatpg_open(const char *locale, UErrorCode *pErrorCode); | |
169 | ||
170 | /** | |
171 | * Open an empty generator, to be constructed with udatpg_addPattern(...) etc. | |
172 | * @param pErrorCode a pointer to the UErrorCode which must not indicate a | |
173 | * failure before the function call. | |
174 | * @return a pointer to UDateTimePatternGenerator. | |
175 | * @stable ICU 3.8 | |
176 | */ | |
177 | U_STABLE UDateTimePatternGenerator * U_EXPORT2 | |
178 | udatpg_openEmpty(UErrorCode *pErrorCode); | |
179 | ||
180 | /** | |
181 | * Close a generator. | |
182 | * @param dtpg a pointer to UDateTimePatternGenerator. | |
183 | * @stable ICU 3.8 | |
184 | */ | |
185 | U_STABLE void U_EXPORT2 | |
186 | udatpg_close(UDateTimePatternGenerator *dtpg); | |
187 | ||
188 | #if U_SHOW_CPLUSPLUS_API | |
189 | ||
190 | U_NAMESPACE_BEGIN | |
191 | ||
192 | /** | |
193 | * \class LocalUDateTimePatternGeneratorPointer | |
194 | * "Smart pointer" class, closes a UDateTimePatternGenerator via udatpg_close(). | |
195 | * For most methods see the LocalPointerBase base class. | |
196 | * | |
197 | * @see LocalPointerBase | |
198 | * @see LocalPointer | |
199 | * @stable ICU 4.4 | |
200 | */ | |
201 | U_DEFINE_LOCAL_OPEN_POINTER(LocalUDateTimePatternGeneratorPointer, UDateTimePatternGenerator, udatpg_close); | |
202 | ||
203 | U_NAMESPACE_END | |
204 | ||
205 | #endif // U_SHOW_CPLUSPLUS_API | |
206 | ||
207 | /** | |
208 | * Create a copy pf a generator. | |
209 | * @param dtpg a pointer to UDateTimePatternGenerator to be copied. | |
210 | * @param pErrorCode a pointer to the UErrorCode which must not indicate a | |
211 | * failure before the function call. | |
212 | * @return a pointer to a new UDateTimePatternGenerator. | |
213 | * @stable ICU 3.8 | |
214 | */ | |
215 | U_STABLE UDateTimePatternGenerator * U_EXPORT2 | |
216 | udatpg_clone(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode); | |
217 | ||
218 | /** | |
219 | * Get the best pattern matching the input skeleton. It is guaranteed to | |
220 | * have all of the fields in the skeleton. | |
221 | * | |
222 | * Note that this function uses a non-const UDateTimePatternGenerator: | |
223 | * It uses a stateful pattern parser which is set up for each generator object, | |
224 | * rather than creating one for each function call. | |
225 | * Consecutive calls to this function do not affect each other, | |
226 | * but this function cannot be used concurrently on a single generator object. | |
227 | * | |
228 | * @param dtpg a pointer to UDateTimePatternGenerator. | |
229 | * @param skeleton | |
230 | * The skeleton is a pattern containing only the variable fields. | |
231 | * For example, "MMMdd" and "mmhh" are skeletons. | |
232 | * @param length the length of skeleton | |
233 | * @param bestPattern | |
234 | * The best pattern found from the given skeleton. | |
235 | * @param capacity the capacity of bestPattern. | |
236 | * @param pErrorCode a pointer to the UErrorCode which must not indicate a | |
237 | * failure before the function call. | |
238 | * @return the length of bestPattern. | |
239 | * @stable ICU 3.8 | |
240 | */ | |
241 | U_STABLE int32_t U_EXPORT2 | |
242 | udatpg_getBestPattern(UDateTimePatternGenerator *dtpg, | |
243 | const UChar *skeleton, int32_t length, | |
244 | UChar *bestPattern, int32_t capacity, | |
245 | UErrorCode *pErrorCode); | |
246 | ||
247 | /** | |
248 | * Get the best pattern matching the input skeleton. It is guaranteed to | |
249 | * have all of the fields in the skeleton. | |
250 | * | |
251 | * Note that this function uses a non-const UDateTimePatternGenerator: | |
252 | * It uses a stateful pattern parser which is set up for each generator object, | |
253 | * rather than creating one for each function call. | |
254 | * Consecutive calls to this function do not affect each other, | |
255 | * but this function cannot be used concurrently on a single generator object. | |
256 | * | |
257 | * @param dtpg a pointer to UDateTimePatternGenerator. | |
258 | * @param skeleton | |
259 | * The skeleton is a pattern containing only the variable fields. | |
260 | * For example, "MMMdd" and "mmhh" are skeletons. | |
261 | * @param length the length of skeleton | |
262 | * @param options | |
263 | * Options for forcing the length of specified fields in the | |
264 | * returned pattern to match those in the skeleton (when this | |
265 | * would not happen otherwise). For default behavior, use | |
266 | * UDATPG_MATCH_NO_OPTIONS. | |
267 | * @param bestPattern | |
268 | * The best pattern found from the given skeleton. | |
269 | * @param capacity | |
270 | * the capacity of bestPattern. | |
271 | * @param pErrorCode | |
272 | * a pointer to the UErrorCode which must not indicate a | |
273 | * failure before the function call. | |
274 | * @return the length of bestPattern. | |
275 | * @stable ICU 4.4 | |
276 | */ | |
277 | U_STABLE int32_t U_EXPORT2 | |
278 | udatpg_getBestPatternWithOptions(UDateTimePatternGenerator *dtpg, | |
279 | const UChar *skeleton, int32_t length, | |
280 | UDateTimePatternMatchOptions options, | |
281 | UChar *bestPattern, int32_t capacity, | |
282 | UErrorCode *pErrorCode); | |
283 | ||
284 | /** | |
285 | * Get a unique skeleton from a given pattern. For example, | |
286 | * both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd". | |
287 | * | |
288 | * Note that this function uses a non-const UDateTimePatternGenerator: | |
289 | * It uses a stateful pattern parser which is set up for each generator object, | |
290 | * rather than creating one for each function call. | |
291 | * Consecutive calls to this function do not affect each other, | |
292 | * but this function cannot be used concurrently on a single generator object. | |
293 | * | |
294 | * @param unusedDtpg a pointer to UDateTimePatternGenerator. | |
295 | * This parameter is no longer used. Callers may pass NULL. | |
296 | * @param pattern input pattern, such as "dd/MMM". | |
297 | * @param length the length of pattern. | |
298 | * @param skeleton such as "MMMdd" | |
299 | * @param capacity the capacity of skeleton. | |
300 | * @param pErrorCode a pointer to the UErrorCode which must not indicate a | |
301 | * failure before the function call. | |
302 | * @return the length of skeleton. | |
303 | * @stable ICU 3.8 | |
304 | */ | |
305 | U_STABLE int32_t U_EXPORT2 | |
306 | udatpg_getSkeleton(UDateTimePatternGenerator *unusedDtpg, | |
307 | const UChar *pattern, int32_t length, | |
308 | UChar *skeleton, int32_t capacity, | |
309 | UErrorCode *pErrorCode); | |
310 | ||
311 | /** | |
312 | * Get a unique base skeleton from a given pattern. This is the same | |
313 | * as the skeleton, except that differences in length are minimized so | |
314 | * as to only preserve the difference between string and numeric form. So | |
315 | * for example, both "MMM-dd" and "d/MMM" produce the skeleton "MMMd" | |
316 | * (notice the single d). | |
317 | * | |
318 | * Note that this function uses a non-const UDateTimePatternGenerator: | |
319 | * It uses a stateful pattern parser which is set up for each generator object, | |
320 | * rather than creating one for each function call. | |
321 | * Consecutive calls to this function do not affect each other, | |
322 | * but this function cannot be used concurrently on a single generator object. | |
323 | * | |
324 | * @param unusedDtpg a pointer to UDateTimePatternGenerator. | |
325 | * This parameter is no longer used. Callers may pass NULL. | |
326 | * @param pattern input pattern, such as "dd/MMM". | |
327 | * @param length the length of pattern. | |
328 | * @param baseSkeleton such as "Md" | |
329 | * @param capacity the capacity of base skeleton. | |
330 | * @param pErrorCode a pointer to the UErrorCode which must not indicate a | |
331 | * failure before the function call. | |
332 | * @return the length of baseSkeleton. | |
333 | * @stable ICU 3.8 | |
334 | */ | |
335 | U_STABLE int32_t U_EXPORT2 | |
336 | udatpg_getBaseSkeleton(UDateTimePatternGenerator *unusedDtpg, | |
337 | const UChar *pattern, int32_t length, | |
338 | UChar *baseSkeleton, int32_t capacity, | |
339 | UErrorCode *pErrorCode); | |
340 | ||
341 | /** | |
342 | * Adds a pattern to the generator. If the pattern has the same skeleton as | |
343 | * an existing pattern, and the override parameter is set, then the previous | |
344 | * value is overriden. Otherwise, the previous value is retained. In either | |
345 | * case, the conflicting status is set and previous vale is stored in | |
346 | * conflicting pattern. | |
347 | * <p> | |
348 | * Note that single-field patterns (like "MMM") are automatically added, and | |
349 | * don't need to be added explicitly! | |
350 | * | |
351 | * @param dtpg a pointer to UDateTimePatternGenerator. | |
352 | * @param pattern input pattern, such as "dd/MMM" | |
353 | * @param patternLength the length of pattern. | |
354 | * @param override When existing values are to be overridden use true, | |
355 | * otherwise use false. | |
356 | * @param conflictingPattern Previous pattern with the same skeleton. | |
357 | * @param capacity the capacity of conflictingPattern. | |
358 | * @param pLength a pointer to the length of conflictingPattern. | |
359 | * @param pErrorCode a pointer to the UErrorCode which must not indicate a | |
360 | * failure before the function call. | |
361 | * @return conflicting status. The value could be UDATPG_NO_CONFLICT, | |
362 | * UDATPG_BASE_CONFLICT or UDATPG_CONFLICT. | |
363 | * @stable ICU 3.8 | |
364 | */ | |
365 | U_STABLE UDateTimePatternConflict U_EXPORT2 | |
366 | udatpg_addPattern(UDateTimePatternGenerator *dtpg, | |
367 | const UChar *pattern, int32_t patternLength, | |
368 | UBool override, | |
369 | UChar *conflictingPattern, int32_t capacity, int32_t *pLength, | |
370 | UErrorCode *pErrorCode); | |
371 | ||
372 | /** | |
373 | * An AppendItem format is a pattern used to append a field if there is no | |
374 | * good match. For example, suppose that the input skeleton is "GyyyyMMMd", | |
375 | * and there is no matching pattern internally, but there is a pattern | |
376 | * matching "yyyyMMMd", say "d-MM-yyyy". Then that pattern is used, plus the | |
377 | * G. The way these two are conjoined is by using the AppendItemFormat for G | |
378 | * (era). So if that value is, say "{0}, {1}" then the final resulting | |
379 | * pattern is "d-MM-yyyy, G". | |
380 | * <p> | |
381 | * There are actually three available variables: {0} is the pattern so far, | |
382 | * {1} is the element we are adding, and {2} is the name of the element. | |
383 | * <p> | |
384 | * This reflects the way that the CLDR data is organized. | |
385 | * | |
386 | * @param dtpg a pointer to UDateTimePatternGenerator. | |
387 | * @param field UDateTimePatternField, such as UDATPG_ERA_FIELD | |
388 | * @param value pattern, such as "{0}, {1}" | |
389 | * @param length the length of value. | |
390 | * @stable ICU 3.8 | |
391 | */ | |
392 | U_STABLE void U_EXPORT2 | |
393 | udatpg_setAppendItemFormat(UDateTimePatternGenerator *dtpg, | |
394 | UDateTimePatternField field, | |
395 | const UChar *value, int32_t length); | |
396 | ||
397 | /** | |
398 | * Getter corresponding to setAppendItemFormat. Values below 0 or at or | |
399 | * above UDATPG_FIELD_COUNT are illegal arguments. | |
400 | * | |
401 | * @param dtpg A pointer to UDateTimePatternGenerator. | |
402 | * @param field UDateTimePatternField, such as UDATPG_ERA_FIELD | |
403 | * @param pLength A pointer that will receive the length of appendItemFormat. | |
404 | * @return appendItemFormat for field. | |
405 | * @stable ICU 3.8 | |
406 | */ | |
407 | U_STABLE const UChar * U_EXPORT2 | |
408 | udatpg_getAppendItemFormat(const UDateTimePatternGenerator *dtpg, | |
409 | UDateTimePatternField field, | |
410 | int32_t *pLength); | |
411 | ||
412 | /** | |
413 | * Set the name of field, eg "era" in English for ERA. These are only | |
414 | * used if the corresponding AppendItemFormat is used, and if it contains a | |
415 | * {2} variable. | |
416 | * <p> | |
417 | * This reflects the way that the CLDR data is organized. | |
418 | * | |
419 | * @param dtpg a pointer to UDateTimePatternGenerator. | |
420 | * @param field UDateTimePatternField | |
421 | * @param value name for the field. | |
422 | * @param length the length of value. | |
423 | * @stable ICU 3.8 | |
424 | */ | |
425 | U_STABLE void U_EXPORT2 | |
426 | udatpg_setAppendItemName(UDateTimePatternGenerator *dtpg, | |
427 | UDateTimePatternField field, | |
428 | const UChar *value, int32_t length); | |
429 | ||
430 | /** | |
431 | * Getter corresponding to setAppendItemNames. Values below 0 or at or above | |
432 | * UDATPG_FIELD_COUNT are illegal arguments. Note: The more general function | |
433 | * for getting date/time field display names is udatpg_getFieldDisplayName. | |
434 | * | |
435 | * @param dtpg a pointer to UDateTimePatternGenerator. | |
436 | * @param field UDateTimePatternField, such as UDATPG_ERA_FIELD | |
437 | * @param pLength A pointer that will receive the length of the name for field. | |
438 | * @return name for field | |
439 | * @see udatpg_getFieldDisplayName | |
440 | * @stable ICU 3.8 | |
441 | */ | |
442 | U_STABLE const UChar * U_EXPORT2 | |
443 | udatpg_getAppendItemName(const UDateTimePatternGenerator *dtpg, | |
444 | UDateTimePatternField field, | |
445 | int32_t *pLength); | |
446 | ||
447 | /** | |
448 | * The general interface to get a display name for a particular date/time field, | |
449 | * in one of several possible display widths. | |
450 | * | |
451 | * @param dtpg | |
452 | * A pointer to the UDateTimePatternGenerator object with the localized | |
453 | * display names. | |
454 | * @param field | |
455 | * The desired UDateTimePatternField, such as UDATPG_ERA_FIELD. | |
456 | * @param width | |
457 | * The desired UDateTimePGDisplayWidth, such as UDATPG_ABBREVIATED. | |
458 | * @param fieldName | |
459 | * A pointer to a buffer to receive the NULL-terminated display name. If the name | |
460 | * fits into fieldName but cannot be NULL-terminated (length == capacity) then | |
461 | * the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the name doesn't | |
462 | * fit into fieldName then the error code is set to U_BUFFER_OVERFLOW_ERROR. | |
463 | * @param capacity | |
464 | * The size of fieldName (in UChars). | |
465 | * @param pErrorCode | |
466 | * A pointer to a UErrorCode to receive any errors | |
467 | * @return | |
468 | * The full length of the name; if greater than capacity, fieldName contains a | |
469 | * truncated result. | |
470 | * @stable ICU 61 | |
471 | */ | |
472 | U_STABLE int32_t U_EXPORT2 | |
473 | udatpg_getFieldDisplayName(const UDateTimePatternGenerator *dtpg, | |
474 | UDateTimePatternField field, | |
475 | UDateTimePGDisplayWidth width, | |
476 | UChar *fieldName, int32_t capacity, | |
477 | UErrorCode *pErrorCode); | |
478 | ||
479 | /** | |
480 | * The DateTimeFormat is a message format pattern used to compose date and | |
481 | * time patterns. The default pattern in the root locale is "{1} {0}", where | |
482 | * {1} will be replaced by the date pattern and {0} will be replaced by the | |
483 | * time pattern; however, other locales may specify patterns such as | |
484 | * "{1}, {0}" or "{1} 'at' {0}", etc. | |
485 | * <p> | |
486 | * This is used when the input skeleton contains both date and time fields, | |
487 | * but there is not a close match among the added patterns. For example, | |
488 | * suppose that this object was created by adding "dd-MMM" and "hh:mm", and | |
489 | * its DateTimeFormat is the default "{1} {0}". Then if the input skeleton | |
490 | * is "MMMdhmm", there is not an exact match, so the input skeleton is | |
491 | * broken up into two components "MMMd" and "hmm". There are close matches | |
492 | * for those two skeletons, so the result is put together with this pattern, | |
493 | * resulting in "d-MMM h:mm". | |
494 | * | |
495 | * @param dtpg a pointer to UDateTimePatternGenerator. | |
496 | * @param dtFormat | |
497 | * message format pattern, here {1} will be replaced by the date | |
498 | * pattern and {0} will be replaced by the time pattern. | |
499 | * @param length the length of dtFormat. | |
500 | * @stable ICU 3.8 | |
501 | */ | |
502 | U_STABLE void U_EXPORT2 | |
503 | udatpg_setDateTimeFormat(const UDateTimePatternGenerator *dtpg, | |
504 | const UChar *dtFormat, int32_t length); | |
505 | ||
506 | /** | |
507 | * Getter corresponding to setDateTimeFormat. | |
508 | * @param dtpg a pointer to UDateTimePatternGenerator. | |
509 | * @param pLength A pointer that will receive the length of the format | |
510 | * @return dateTimeFormat. | |
511 | * @stable ICU 3.8 | |
512 | */ | |
513 | U_STABLE const UChar * U_EXPORT2 | |
514 | udatpg_getDateTimeFormat(const UDateTimePatternGenerator *dtpg, | |
515 | int32_t *pLength); | |
516 | ||
517 | /** | |
518 | * The decimal value is used in formatting fractions of seconds. If the | |
519 | * skeleton contains fractional seconds, then this is used with the | |
520 | * fractional seconds. For example, suppose that the input pattern is | |
521 | * "hhmmssSSSS", and the best matching pattern internally is "H:mm:ss", and | |
522 | * the decimal string is ",". Then the resulting pattern is modified to be | |
523 | * "H:mm:ss,SSSS" | |
524 | * | |
525 | * @param dtpg a pointer to UDateTimePatternGenerator. | |
526 | * @param decimal | |
527 | * @param length the length of decimal. | |
528 | * @stable ICU 3.8 | |
529 | */ | |
530 | U_STABLE void U_EXPORT2 | |
531 | udatpg_setDecimal(UDateTimePatternGenerator *dtpg, | |
532 | const UChar *decimal, int32_t length); | |
533 | ||
534 | /** | |
535 | * Getter corresponding to setDecimal. | |
536 | * | |
537 | * @param dtpg a pointer to UDateTimePatternGenerator. | |
538 | * @param pLength A pointer that will receive the length of the decimal string. | |
539 | * @return corresponding to the decimal point. | |
540 | * @stable ICU 3.8 | |
541 | */ | |
542 | U_STABLE const UChar * U_EXPORT2 | |
543 | udatpg_getDecimal(const UDateTimePatternGenerator *dtpg, | |
544 | int32_t *pLength); | |
545 | ||
546 | /** | |
547 | * Adjusts the field types (width and subtype) of a pattern to match what is | |
548 | * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a | |
549 | * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be | |
550 | * "dd-MMMM hh:mm". This is used internally to get the best match for the | |
551 | * input skeleton, but can also be used externally. | |
552 | * | |
553 | * Note that this function uses a non-const UDateTimePatternGenerator: | |
554 | * It uses a stateful pattern parser which is set up for each generator object, | |
555 | * rather than creating one for each function call. | |
556 | * Consecutive calls to this function do not affect each other, | |
557 | * but this function cannot be used concurrently on a single generator object. | |
558 | * | |
559 | * @param dtpg a pointer to UDateTimePatternGenerator. | |
560 | * @param pattern Input pattern | |
561 | * @param patternLength the length of input pattern. | |
562 | * @param skeleton | |
563 | * @param skeletonLength the length of input skeleton. | |
564 | * @param dest pattern adjusted to match the skeleton fields widths and subtypes. | |
565 | * @param destCapacity the capacity of dest. | |
566 | * @param pErrorCode a pointer to the UErrorCode which must not indicate a | |
567 | * failure before the function call. | |
568 | * @return the length of dest. | |
569 | * @stable ICU 3.8 | |
570 | */ | |
571 | U_STABLE int32_t U_EXPORT2 | |
572 | udatpg_replaceFieldTypes(UDateTimePatternGenerator *dtpg, | |
573 | const UChar *pattern, int32_t patternLength, | |
574 | const UChar *skeleton, int32_t skeletonLength, | |
575 | UChar *dest, int32_t destCapacity, | |
576 | UErrorCode *pErrorCode); | |
577 | ||
578 | /** | |
579 | * Adjusts the field types (width and subtype) of a pattern to match what is | |
580 | * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a | |
581 | * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be | |
582 | * "dd-MMMM hh:mm". This is used internally to get the best match for the | |
583 | * input skeleton, but can also be used externally. | |
584 | * | |
585 | * Note that this function uses a non-const UDateTimePatternGenerator: | |
586 | * It uses a stateful pattern parser which is set up for each generator object, | |
587 | * rather than creating one for each function call. | |
588 | * Consecutive calls to this function do not affect each other, | |
589 | * but this function cannot be used concurrently on a single generator object. | |
590 | * | |
591 | * @param dtpg a pointer to UDateTimePatternGenerator. | |
592 | * @param pattern Input pattern | |
593 | * @param patternLength the length of input pattern. | |
594 | * @param skeleton | |
595 | * @param skeletonLength the length of input skeleton. | |
596 | * @param options | |
597 | * Options controlling whether the length of specified fields in the | |
598 | * pattern are adjusted to match those in the skeleton (when this | |
599 | * would not happen otherwise). For default behavior, use | |
600 | * UDATPG_MATCH_NO_OPTIONS. | |
601 | * @param dest pattern adjusted to match the skeleton fields widths and subtypes. | |
602 | * @param destCapacity the capacity of dest. | |
603 | * @param pErrorCode a pointer to the UErrorCode which must not indicate a | |
604 | * failure before the function call. | |
605 | * @return the length of dest. | |
606 | * @stable ICU 4.4 | |
607 | */ | |
608 | U_STABLE int32_t U_EXPORT2 | |
609 | udatpg_replaceFieldTypesWithOptions(UDateTimePatternGenerator *dtpg, | |
610 | const UChar *pattern, int32_t patternLength, | |
611 | const UChar *skeleton, int32_t skeletonLength, | |
612 | UDateTimePatternMatchOptions options, | |
613 | UChar *dest, int32_t destCapacity, | |
614 | UErrorCode *pErrorCode); | |
615 | ||
616 | /** | |
617 | * Return a UEnumeration list of all the skeletons in canonical form. | |
618 | * Call udatpg_getPatternForSkeleton() to get the corresponding pattern. | |
619 | * | |
620 | * @param dtpg a pointer to UDateTimePatternGenerator. | |
621 | * @param pErrorCode a pointer to the UErrorCode which must not indicate a | |
622 | * failure before the function call | |
623 | * @return a UEnumeration list of all the skeletons | |
624 | * The caller must close the object. | |
625 | * @stable ICU 3.8 | |
626 | */ | |
627 | U_STABLE UEnumeration * U_EXPORT2 | |
628 | udatpg_openSkeletons(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode); | |
629 | ||
630 | /** | |
631 | * Return a UEnumeration list of all the base skeletons in canonical form. | |
632 | * | |
633 | * @param dtpg a pointer to UDateTimePatternGenerator. | |
634 | * @param pErrorCode a pointer to the UErrorCode which must not indicate a | |
635 | * failure before the function call. | |
636 | * @return a UEnumeration list of all the base skeletons | |
637 | * The caller must close the object. | |
638 | * @stable ICU 3.8 | |
639 | */ | |
640 | U_STABLE UEnumeration * U_EXPORT2 | |
641 | udatpg_openBaseSkeletons(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode); | |
642 | ||
643 | /** | |
644 | * Get the pattern corresponding to a given skeleton. | |
645 | * | |
646 | * @param dtpg a pointer to UDateTimePatternGenerator. | |
647 | * @param skeleton | |
648 | * @param skeletonLength pointer to the length of skeleton. | |
649 | * @param pLength pointer to the length of return pattern. | |
650 | * @return pattern corresponding to a given skeleton. | |
651 | * @stable ICU 3.8 | |
652 | */ | |
653 | U_STABLE const UChar * U_EXPORT2 | |
654 | udatpg_getPatternForSkeleton(const UDateTimePatternGenerator *dtpg, | |
655 | const UChar *skeleton, int32_t skeletonLength, | |
656 | int32_t *pLength); | |
657 | ||
658 | /** | |
659 | * Remap a pattern per the options (Apple-specific for now). | |
660 | * Currently this will only remap the time to force an alternate time | |
661 | * cycle (12-hour instead of 24-hour or vice versa), handling updating | |
662 | * the pattern characters, insertion/removal of AM/PM marker, etc. in | |
663 | * a locale-appropriate way. It calls udatpg_getBestPatternWithOptions | |
664 | * as part of updating the time format. | |
665 | * | |
666 | * @param dtpg a pointer to UDateTimePatternGenerator. | |
667 | * @param pattern | |
668 | * The pattern to remap. | |
669 | * @param patternLength | |
670 | * The length of the pattern (may be -1 to indicate that it | |
671 | * is zero-terminated). | |
672 | * @param options | |
673 | * Options for forcing the hour cycle and for forcing the | |
674 | * length of specified fields in the | |
675 | * returned pattern to match those in the skeleton (when this | |
676 | * would not happen otherwise). For default behavior, use | |
677 | * UDATPG_MATCH_NO_OPTIONS. | |
678 | * @param newPattern | |
679 | * The remapped pattern. | |
680 | * @param newPatternCapacity | |
681 | * The capacity of newPattern. | |
682 | * @param pErrorCode | |
683 | * A pointer to the UErrorCode. If at entry it indicates a | |
684 | * failure, the call will return immediately. | |
685 | * @return | |
686 | * The length of newPattern. If this is greater than | |
687 | * newPatternCapacity an error will be set and the contents of | |
688 | * newPattern are undefined. | |
689 | * @internal | |
690 | */ | |
691 | U_INTERNAL int32_t U_EXPORT2 | |
692 | uadatpg_remapPatternWithOptions(UDateTimePatternGenerator *dtpg, | |
693 | const UChar *pattern, int32_t patternLength, | |
694 | UDateTimePatternMatchOptions options, | |
695 | UChar *newPattern, int32_t newPatternCapacity, | |
696 | UErrorCode *pErrorCode); | |
697 | ||
698 | #endif |