X-Git-Url: https://git.saurik.com/apple/icu.git/blobdiff_plain/46f4442e9a5a4f3b98b7c1083586332f6a8a99a4..2ca993e82fb37b597a3c73ecd1586a139a6579c5:/icuSources/i18n/unicode/udatpg.h diff --git a/icuSources/i18n/unicode/udatpg.h b/icuSources/i18n/unicode/udatpg.h index 206637fc..7c58665a 100644 --- a/icuSources/i18n/unicode/udatpg.h +++ b/icuSources/i18n/unicode/udatpg.h @@ -1,7 +1,7 @@ /* ******************************************************************************* * -* Copyright (C) 2007-2008, International Business Machines +* Copyright (C) 2007-2015, International Business Machines * Corporation and others. All Rights Reserved. * ******************************************************************************* @@ -19,10 +19,11 @@ #include "unicode/utypes.h" #include "unicode/uenum.h" +#include "unicode/localpointer.h" /** * \file - * \brief C API: Wrapper for DateTimePatternGenerator (unicode/dtptngen.h). + * \brief C API: Wrapper for icu::DateTimePatternGenerator (unicode/dtptngen.h). * * UDateTimePatternGenerator provides flexible generation of date format patterns, * like "yy-MM-dd". The user can build up the generator by adding successive @@ -39,7 +40,7 @@ /** * Opaque type for a date/time pattern generator object. - * @stable ICU 4.0 + * @stable ICU 3.8 */ typedef void *UDateTimePatternGenerator; @@ -47,57 +48,85 @@ typedef void *UDateTimePatternGenerator; * Field number constants for udatpg_getAppendItemFormats() and similar functions. * These constants are separate from UDateFormatField despite semantic overlap * because some fields are merged for the date/time pattern generator. - * @stable ICU 4.0 + * @stable ICU 3.8 */ typedef enum UDateTimePatternField { - /** @stable ICU 4.0 */ + /** @stable ICU 3.8 */ UDATPG_ERA_FIELD, - /** @stable ICU 4.0 */ + /** @stable ICU 3.8 */ UDATPG_YEAR_FIELD, - /** @stable ICU 4.0 */ + /** @stable ICU 3.8 */ UDATPG_QUARTER_FIELD, - /** @stable ICU 4.0 */ + /** @stable ICU 3.8 */ UDATPG_MONTH_FIELD, - /** @stable ICU 4.0 */ + /** @stable ICU 3.8 */ UDATPG_WEEK_OF_YEAR_FIELD, - /** @stable ICU 4.0 */ + /** @stable ICU 3.8 */ UDATPG_WEEK_OF_MONTH_FIELD, - /** @stable ICU 4.0 */ + /** @stable ICU 3.8 */ UDATPG_WEEKDAY_FIELD, - /** @stable ICU 4.0 */ + /** @stable ICU 3.8 */ UDATPG_DAY_OF_YEAR_FIELD, - /** @stable ICU 4.0 */ + /** @stable ICU 3.8 */ UDATPG_DAY_OF_WEEK_IN_MONTH_FIELD, - /** @stable ICU 4.0 */ + /** @stable ICU 3.8 */ UDATPG_DAY_FIELD, - /** @stable ICU 4.0 */ + /** @stable ICU 3.8 */ UDATPG_DAYPERIOD_FIELD, - /** @stable ICU 4.0 */ + /** @stable ICU 3.8 */ UDATPG_HOUR_FIELD, - /** @stable ICU 4.0 */ + /** @stable ICU 3.8 */ UDATPG_MINUTE_FIELD, - /** @stable ICU 4.0 */ + /** @stable ICU 3.8 */ UDATPG_SECOND_FIELD, - /** @stable ICU 4.0 */ + /** @stable ICU 3.8 */ UDATPG_FRACTIONAL_SECOND_FIELD, - /** @stable ICU 4.0 */ + /** @stable ICU 3.8 */ UDATPG_ZONE_FIELD, - /** @stable ICU 4.0 */ + /** @stable ICU 3.8 */ UDATPG_FIELD_COUNT } UDateTimePatternField; +/** + * Masks to control forcing the length of specified fields in the returned + * pattern to match those in the skeleton (when this would not happen + * otherwise). These may be combined to force the length of multiple fields. + * Used with udatpg_getBestPatternWithOptions, udatpg_replaceFieldTypesWithOptions. + * @stable ICU 4.4 + */ +typedef enum UDateTimePatternMatchOptions { + /** @stable ICU 4.4 */ + UDATPG_MATCH_NO_OPTIONS = 0, + /** @stable ICU 4.4 */ + UDATPG_MATCH_HOUR_FIELD_LENGTH = 1 << UDATPG_HOUR_FIELD, +#ifndef U_HIDE_INTERNAL_API + /** @internal ICU 4.4 */ + UDATPG_MATCH_MINUTE_FIELD_LENGTH = 1 << UDATPG_MINUTE_FIELD, + /** @internal ICU 4.4 */ + UDATPG_MATCH_SECOND_FIELD_LENGTH = 1 << UDATPG_SECOND_FIELD, +#endif /* U_HIDE_INTERNAL_API */ + /** @stable ICU 4.4 */ + UDATPG_MATCH_ALL_FIELDS_LENGTH = (1 << UDATPG_FIELD_COUNT) - 1, + /** @internal, Apple-specific for now */ + UADATPG_FORCE_12_HOUR_CYCLE = 1 << 29, + /** @internal, Apple-specific for now */ + UADATPG_FORCE_24_HOUR_CYCLE = 1 << 30, + /** @internal, Apple-specific for now */ + UADATPG_FORCE_HOUR_CYCLE_MASK = 3 << 29, +} UDateTimePatternMatchOptions; + /** * Status return values from udatpg_addPattern(). - * @stable ICU 4.0 + * @stable ICU 3.8 */ typedef enum UDateTimePatternConflict { - /** @stable ICU 4.0 */ + /** @stable ICU 3.8 */ UDATPG_NO_CONFLICT, - /** @stable ICU 4.0 */ + /** @stable ICU 3.8 */ UDATPG_BASE_CONFLICT, - /** @stable ICU 4.0 */ + /** @stable ICU 3.8 */ UDATPG_CONFLICT, - /** @stable ICU 4.0 */ + /** @stable ICU 3.8 */ UDATPG_CONFLICT_COUNT } UDateTimePatternConflict; @@ -107,9 +136,9 @@ typedef enum UDateTimePatternConflict { * @param pErrorCode a pointer to the UErrorCode which must not indicate a * failure before the function call. * @return a pointer to UDateTimePatternGenerator. - * @stable ICU 4.0 + * @stable ICU 3.8 */ -U_DRAFT UDateTimePatternGenerator * U_EXPORT2 +U_STABLE UDateTimePatternGenerator * U_EXPORT2 udatpg_open(const char *locale, UErrorCode *pErrorCode); /** @@ -117,28 +146,47 @@ udatpg_open(const char *locale, UErrorCode *pErrorCode); * @param pErrorCode a pointer to the UErrorCode which must not indicate a * failure before the function call. * @return a pointer to UDateTimePatternGenerator. - * @stable ICU 4.0 + * @stable ICU 3.8 */ -U_DRAFT UDateTimePatternGenerator * U_EXPORT2 +U_STABLE UDateTimePatternGenerator * U_EXPORT2 udatpg_openEmpty(UErrorCode *pErrorCode); /** * Close a generator. * @param dtpg a pointer to UDateTimePatternGenerator. - * @stable ICU 4.0 + * @stable ICU 3.8 */ -U_DRAFT void U_EXPORT2 +U_STABLE void U_EXPORT2 udatpg_close(UDateTimePatternGenerator *dtpg); +#if U_SHOW_CPLUSPLUS_API + +U_NAMESPACE_BEGIN + +/** + * \class LocalUDateTimePatternGeneratorPointer + * "Smart pointer" class, closes a UDateTimePatternGenerator via udatpg_close(). + * For most methods see the LocalPointerBase base class. + * + * @see LocalPointerBase + * @see LocalPointer + * @stable ICU 4.4 + */ +U_DEFINE_LOCAL_OPEN_POINTER(LocalUDateTimePatternGeneratorPointer, UDateTimePatternGenerator, udatpg_close); + +U_NAMESPACE_END + +#endif + /** * Create a copy pf a generator. * @param dtpg a pointer to UDateTimePatternGenerator to be copied. * @param pErrorCode a pointer to the UErrorCode which must not indicate a * failure before the function call. * @return a pointer to a new UDateTimePatternGenerator. - * @stable ICU 4.0 + * @stable ICU 3.8 */ -U_DRAFT UDateTimePatternGenerator * U_EXPORT2 +U_STABLE UDateTimePatternGenerator * U_EXPORT2 udatpg_clone(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode); /** @@ -162,14 +210,51 @@ udatpg_clone(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode); * @param pErrorCode a pointer to the UErrorCode which must not indicate a * failure before the function call. * @return the length of bestPattern. - * @stable ICU 4.0 + * @stable ICU 3.8 */ -U_DRAFT int32_t U_EXPORT2 +U_STABLE int32_t U_EXPORT2 udatpg_getBestPattern(UDateTimePatternGenerator *dtpg, const UChar *skeleton, int32_t length, UChar *bestPattern, int32_t capacity, UErrorCode *pErrorCode); +/** + * Get the best pattern matching the input skeleton. It is guaranteed to + * have all of the fields in the skeleton. + * + * Note that this function uses a non-const UDateTimePatternGenerator: + * It uses a stateful pattern parser which is set up for each generator object, + * rather than creating one for each function call. + * Consecutive calls to this function do not affect each other, + * but this function cannot be used concurrently on a single generator object. + * + * @param dtpg a pointer to UDateTimePatternGenerator. + * @param skeleton + * The skeleton is a pattern containing only the variable fields. + * For example, "MMMdd" and "mmhh" are skeletons. + * @param length the length of skeleton + * @param options + * Options for forcing the length of specified fields in the + * returned pattern to match those in the skeleton (when this + * would not happen otherwise). For default behavior, use + * UDATPG_MATCH_NO_OPTIONS. + * @param bestPattern + * The best pattern found from the given skeleton. + * @param capacity + * the capacity of bestPattern. + * @param pErrorCode + * a pointer to the UErrorCode which must not indicate a + * failure before the function call. + * @return the length of bestPattern. + * @stable ICU 4.4 + */ +U_STABLE int32_t U_EXPORT2 +udatpg_getBestPatternWithOptions(UDateTimePatternGenerator *dtpg, + const UChar *skeleton, int32_t length, + UDateTimePatternMatchOptions options, + UChar *bestPattern, int32_t capacity, + UErrorCode *pErrorCode); + /** * Get a unique skeleton from a given pattern. For example, * both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd". @@ -180,7 +265,8 @@ udatpg_getBestPattern(UDateTimePatternGenerator *dtpg, * Consecutive calls to this function do not affect each other, * but this function cannot be used concurrently on a single generator object. * - * @param dtpg a pointer to UDateTimePatternGenerator. + * @param unusedDtpg a pointer to UDateTimePatternGenerator. + * This parameter is no longer used. Callers may pass NULL. * @param pattern input pattern, such as "dd/MMM". * @param length the length of pattern. * @param skeleton such as "MMMdd" @@ -188,10 +274,10 @@ udatpg_getBestPattern(UDateTimePatternGenerator *dtpg, * @param pErrorCode a pointer to the UErrorCode which must not indicate a * failure before the function call. * @return the length of skeleton. - * @stable ICU 4.0 + * @stable ICU 3.8 */ -U_DRAFT int32_t U_EXPORT2 -udatpg_getSkeleton(UDateTimePatternGenerator *dtpg, +U_STABLE int32_t U_EXPORT2 +udatpg_getSkeleton(UDateTimePatternGenerator *unusedDtpg, const UChar *pattern, int32_t length, UChar *skeleton, int32_t capacity, UErrorCode *pErrorCode); @@ -209,7 +295,8 @@ udatpg_getSkeleton(UDateTimePatternGenerator *dtpg, * Consecutive calls to this function do not affect each other, * but this function cannot be used concurrently on a single generator object. * - * @param dtpg a pointer to UDateTimePatternGenerator. + * @param unusedDtpg a pointer to UDateTimePatternGenerator. + * This parameter is no longer used. Callers may pass NULL. * @param pattern input pattern, such as "dd/MMM". * @param length the length of pattern. * @param baseSkeleton such as "Md" @@ -217,10 +304,10 @@ udatpg_getSkeleton(UDateTimePatternGenerator *dtpg, * @param pErrorCode a pointer to the UErrorCode which must not indicate a * failure before the function call. * @return the length of baseSkeleton. - * @stable ICU 4.0 + * @stable ICU 3.8 */ -U_DRAFT int32_t U_EXPORT2 -udatpg_getBaseSkeleton(UDateTimePatternGenerator *dtpg, +U_STABLE int32_t U_EXPORT2 +udatpg_getBaseSkeleton(UDateTimePatternGenerator *unusedDtpg, const UChar *pattern, int32_t length, UChar *baseSkeleton, int32_t capacity, UErrorCode *pErrorCode); @@ -247,9 +334,9 @@ udatpg_getBaseSkeleton(UDateTimePatternGenerator *dtpg, * failure before the function call. * @return conflicting status. The value could be UDATPG_NO_CONFLICT, * UDATPG_BASE_CONFLICT or UDATPG_CONFLICT. - * @stable ICU 4.0 + * @stable ICU 3.8 */ -U_DRAFT UDateTimePatternConflict U_EXPORT2 +U_STABLE UDateTimePatternConflict U_EXPORT2 udatpg_addPattern(UDateTimePatternGenerator *dtpg, const UChar *pattern, int32_t patternLength, UBool override, @@ -274,9 +361,9 @@ udatpg_addPattern(UDateTimePatternGenerator *dtpg, * @param field UDateTimePatternField, such as UDATPG_ERA_FIELD * @param value pattern, such as "{0}, {1}" * @param length the length of value. - * @stable ICU 4.0 + * @stable ICU 3.8 */ -U_DRAFT void U_EXPORT2 +U_STABLE void U_EXPORT2 udatpg_setAppendItemFormat(UDateTimePatternGenerator *dtpg, UDateTimePatternField field, const UChar *value, int32_t length); @@ -289,9 +376,9 @@ udatpg_setAppendItemFormat(UDateTimePatternGenerator *dtpg, * @param field UDateTimePatternField, such as UDATPG_ERA_FIELD * @param pLength A pointer that will receive the length of appendItemFormat. * @return appendItemFormat for field. - * @stable ICU 4.0 + * @stable ICU 3.8 */ -U_DRAFT const UChar * U_EXPORT2 +U_STABLE const UChar * U_EXPORT2 udatpg_getAppendItemFormat(const UDateTimePatternGenerator *dtpg, UDateTimePatternField field, int32_t *pLength); @@ -307,9 +394,9 @@ udatpg_getAppendItemFormat(const UDateTimePatternGenerator *dtpg, * @param field UDateTimePatternField * @param value name for the field. * @param length the length of value. - * @stable ICU 4.0 + * @stable ICU 3.8 */ -U_DRAFT void U_EXPORT2 +U_STABLE void U_EXPORT2 udatpg_setAppendItemName(UDateTimePatternGenerator *dtpg, UDateTimePatternField field, const UChar *value, int32_t length); @@ -322,22 +409,24 @@ udatpg_setAppendItemName(UDateTimePatternGenerator *dtpg, * @param field UDateTimePatternField, such as UDATPG_ERA_FIELD * @param pLength A pointer that will receive the length of the name for field. * @return name for field - * @stable ICU 4.0 + * @stable ICU 3.8 */ -U_DRAFT const UChar * U_EXPORT2 +U_STABLE const UChar * U_EXPORT2 udatpg_getAppendItemName(const UDateTimePatternGenerator *dtpg, UDateTimePatternField field, int32_t *pLength); /** - * The date time format is a message format pattern used to compose date and - * time patterns. The default value is "{0} {1}", where {0} will be replaced - * by the date pattern and {1} will be replaced by the time pattern. + * The DateTimeFormat is a message format pattern used to compose date and + * time patterns. The default pattern in the root locale is "{1} {0}", where + * {1} will be replaced by the date pattern and {0} will be replaced by the + * time pattern; however, other locales may specify patterns such as + * "{1}, {0}" or "{1} 'at' {0}", etc. *

* This is used when the input skeleton contains both date and time fields, * but there is not a close match among the added patterns. For example, * suppose that this object was created by adding "dd-MMM" and "hh:mm", and - * its datetimeFormat is the default "{0} {1}". Then if the input skeleton + * its DateTimeFormat is the default "{1} {0}". Then if the input skeleton * is "MMMdhmm", there is not an exact match, so the input skeleton is * broken up into two components "MMMd" and "hmm". There are close matches * for those two skeletons, so the result is put together with this pattern, @@ -345,12 +434,12 @@ udatpg_getAppendItemName(const UDateTimePatternGenerator *dtpg, * * @param dtpg a pointer to UDateTimePatternGenerator. * @param dtFormat - * message format pattern, here {0} will be replaced by the date - * pattern and {1} will be replaced by the time pattern. + * message format pattern, here {1} will be replaced by the date + * pattern and {0} will be replaced by the time pattern. * @param length the length of dtFormat. - * @stable ICU 4.0 + * @stable ICU 3.8 */ -U_DRAFT void U_EXPORT2 +U_STABLE void U_EXPORT2 udatpg_setDateTimeFormat(const UDateTimePatternGenerator *dtpg, const UChar *dtFormat, int32_t length); @@ -359,9 +448,9 @@ udatpg_setDateTimeFormat(const UDateTimePatternGenerator *dtpg, * @param dtpg a pointer to UDateTimePatternGenerator. * @param pLength A pointer that will receive the length of the format * @return dateTimeFormat. - * @stable ICU 4.0 + * @stable ICU 3.8 */ -U_DRAFT const UChar * U_EXPORT2 +U_STABLE const UChar * U_EXPORT2 udatpg_getDateTimeFormat(const UDateTimePatternGenerator *dtpg, int32_t *pLength); @@ -376,9 +465,9 @@ udatpg_getDateTimeFormat(const UDateTimePatternGenerator *dtpg, * @param dtpg a pointer to UDateTimePatternGenerator. * @param decimal * @param length the length of decimal. - * @stable ICU 4.0 + * @stable ICU 3.8 */ -U_DRAFT void U_EXPORT2 +U_STABLE void U_EXPORT2 udatpg_setDecimal(UDateTimePatternGenerator *dtpg, const UChar *decimal, int32_t length); @@ -388,9 +477,9 @@ udatpg_setDecimal(UDateTimePatternGenerator *dtpg, * @param dtpg a pointer to UDateTimePatternGenerator. * @param pLength A pointer that will receive the length of the decimal string. * @return corresponding to the decimal point. - * @stable ICU 4.0 + * @stable ICU 3.8 */ -U_DRAFT const UChar * U_EXPORT2 +U_STABLE const UChar * U_EXPORT2 udatpg_getDecimal(const UDateTimePatternGenerator *dtpg, int32_t *pLength); @@ -417,15 +506,53 @@ udatpg_getDecimal(const UDateTimePatternGenerator *dtpg, * @param pErrorCode a pointer to the UErrorCode which must not indicate a * failure before the function call. * @return the length of dest. - * @stable ICU 4.0 + * @stable ICU 3.8 */ -U_DRAFT int32_t U_EXPORT2 +U_STABLE int32_t U_EXPORT2 udatpg_replaceFieldTypes(UDateTimePatternGenerator *dtpg, const UChar *pattern, int32_t patternLength, const UChar *skeleton, int32_t skeletonLength, UChar *dest, int32_t destCapacity, UErrorCode *pErrorCode); +/** + * Adjusts the field types (width and subtype) of a pattern to match what is + * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a + * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be + * "dd-MMMM hh:mm". This is used internally to get the best match for the + * input skeleton, but can also be used externally. + * + * Note that this function uses a non-const UDateTimePatternGenerator: + * It uses a stateful pattern parser which is set up for each generator object, + * rather than creating one for each function call. + * Consecutive calls to this function do not affect each other, + * but this function cannot be used concurrently on a single generator object. + * + * @param dtpg a pointer to UDateTimePatternGenerator. + * @param pattern Input pattern + * @param patternLength the length of input pattern. + * @param skeleton + * @param skeletonLength the length of input skeleton. + * @param options + * Options controlling whether the length of specified fields in the + * pattern are adjusted to match those in the skeleton (when this + * would not happen otherwise). For default behavior, use + * UDATPG_MATCH_NO_OPTIONS. + * @param dest pattern adjusted to match the skeleton fields widths and subtypes. + * @param destCapacity the capacity of dest. + * @param pErrorCode a pointer to the UErrorCode which must not indicate a + * failure before the function call. + * @return the length of dest. + * @stable ICU 4.4 + */ +U_STABLE int32_t U_EXPORT2 +udatpg_replaceFieldTypesWithOptions(UDateTimePatternGenerator *dtpg, + const UChar *pattern, int32_t patternLength, + const UChar *skeleton, int32_t skeletonLength, + UDateTimePatternMatchOptions options, + UChar *dest, int32_t destCapacity, + UErrorCode *pErrorCode); + /** * Return a UEnumeration list of all the skeletons in canonical form. * Call udatpg_getPatternForSkeleton() to get the corresponding pattern. @@ -435,9 +562,9 @@ udatpg_replaceFieldTypes(UDateTimePatternGenerator *dtpg, * failure before the function call * @return a UEnumeration list of all the skeletons * The caller must close the object. - * @stable ICU 4.0 + * @stable ICU 3.8 */ -U_DRAFT UEnumeration * U_EXPORT2 +U_STABLE UEnumeration * U_EXPORT2 udatpg_openSkeletons(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode); /** @@ -448,9 +575,9 @@ udatpg_openSkeletons(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCo * failure before the function call. * @return a UEnumeration list of all the base skeletons * The caller must close the object. - * @stable ICU 4.0 + * @stable ICU 3.8 */ -U_DRAFT UEnumeration * U_EXPORT2 +U_STABLE UEnumeration * U_EXPORT2 udatpg_openBaseSkeletons(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode); /** @@ -461,11 +588,51 @@ udatpg_openBaseSkeletons(const UDateTimePatternGenerator *dtpg, UErrorCode *pErr * @param skeletonLength pointer to the length of skeleton. * @param pLength pointer to the length of return pattern. * @return pattern corresponding to a given skeleton. - * @stable ICU 4.0 + * @stable ICU 3.8 */ -U_DRAFT const UChar * U_EXPORT2 +U_STABLE const UChar * U_EXPORT2 udatpg_getPatternForSkeleton(const UDateTimePatternGenerator *dtpg, const UChar *skeleton, int32_t skeletonLength, int32_t *pLength); +/** + * Remap a pattern per the options (Apple-specific for now). + * Currently this will only remap the time to force an alternate time + * cycle (12-hour instead of 24-hour or vice versa), handling updating + * the pattern characters, insertion/removal of AM/PM marker, etc. in + * a locale-appropriate way. It calls udatpg_getBestPatternWithOptions + * as part of updating the time format. + * + * @param dtpg a pointer to UDateTimePatternGenerator. + * @param pattern + * The pattern to remap. + * @param patternLength + * The length of the pattern (may be -1 to indicate that it + * is zero-terminated). + * @param options + * Options for forcing the hour cycle and for forcing the + * length of specified fields in the + * returned pattern to match those in the skeleton (when this + * would not happen otherwise). For default behavior, use + * UDATPG_MATCH_NO_OPTIONS. + * @param newPattern + * The remapped pattern. + * @param newPatternCapacity + * The capacity of newPattern. + * @param pErrorCode + * A pointer to the UErrorCode. If at entry it indicates a + * failure, the call will return immediately. + * @return + * The length of newPattern. If this is greater than + * newPatternCapacity an error will be set and the contents of + * newPattern are undefined. + * @internal + */ +U_INTERNAL int32_t U_EXPORT2 +uadatpg_remapPatternWithOptions(UDateTimePatternGenerator *dtpg, + const UChar *pattern, int32_t patternLength, + UDateTimePatternMatchOptions options, + UChar *newPattern, int32_t newPatternCapacity, + UErrorCode *pErrorCode); + #endif