X-Git-Url: https://git.saurik.com/apple/icu.git/blobdiff_plain/729e4ab9bc6618bc3d8a898e575df7f4019e29ca..4f1e1a09ce4daed860e35d359ce2fceccb0764e8:/icuSources/i18n/unicode/udatpg.h diff --git a/icuSources/i18n/unicode/udatpg.h b/icuSources/i18n/unicode/udatpg.h index 3dc7e89f..a5e2220d 100644 --- a/icuSources/i18n/unicode/udatpg.h +++ b/icuSources/i18n/unicode/udatpg.h @@ -1,12 +1,14 @@ +// © 2016 and later: Unicode, Inc. and others. +// License & terms of use: http://www.unicode.org/copyright.html /* ******************************************************************************* * -* Copyright (C) 2007-2010, International Business Machines +* Copyright (C) 2007-2015, International Business Machines * Corporation and others. All Rights Reserved. * ******************************************************************************* * file name: udatpg.h -* encoding: US-ASCII +* encoding: UTF-8 * tab size: 8 (not used) * indentation:4 * @@ -23,7 +25,7 @@ /** * \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 @@ -83,10 +85,31 @@ typedef enum UDateTimePatternField { UDATPG_FRACTIONAL_SECOND_FIELD, /** @stable ICU 3.8 */ UDATPG_ZONE_FIELD, - /** @stable ICU 3.8 */ + + /* Do not conditionalize the following with #ifndef U_HIDE_DEPRECATED_API, + * it is needed for layout of DateTimePatternGenerator object. */ + /** + * One more than the highest normal UDateTimePatternField value. + * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. + */ UDATPG_FIELD_COUNT } UDateTimePatternField; +#ifndef U_HIDE_DRAFT_API +/** + * Field display name width constants for udatpg_getFieldDisplayName(). + * @draft ICU 61 + */ +typedef enum UDateTimePGDisplayWidth { + /** @draft ICU 61 */ + UDATPG_WIDE, + /** @draft ICU 61 */ + UDATPG_ABBREVIATED, + /** @draft ICU 61 */ + UDATPG_NARROW +} UDateTimePGDisplayWidth; +#endif // U_HIDE_DRAFT_API + /** * Masks to control forcing the length of specified fields in the returned * pattern to match those in the skeleton (when this would not happen @@ -99,12 +122,20 @@ typedef enum UDateTimePatternMatchOptions { 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 + 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; /** @@ -118,8 +149,13 @@ typedef enum UDateTimePatternConflict { UDATPG_BASE_CONFLICT, /** @stable ICU 3.8 */ UDATPG_CONFLICT, - /** @stable ICU 3.8 */ +#ifndef U_HIDE_DEPRECATED_API + /** + * One more than the highest normal UDateTimePatternConflict value. + * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. + */ UDATPG_CONFLICT_COUNT +#endif // U_HIDE_DEPRECATED_API } UDateTimePatternConflict; /** @@ -168,7 +204,7 @@ U_DEFINE_LOCAL_OPEN_POINTER(LocalUDateTimePatternGeneratorPointer, UDateTimePatt U_NAMESPACE_END -#endif +#endif // U_SHOW_CPLUSPLUS_API /** * Create a copy pf a generator. @@ -257,7 +293,8 @@ udatpg_getBestPatternWithOptions(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" @@ -268,7 +305,7 @@ udatpg_getBestPatternWithOptions(UDateTimePatternGenerator *dtpg, * @stable ICU 3.8 */ U_STABLE int32_t U_EXPORT2 -udatpg_getSkeleton(UDateTimePatternGenerator *dtpg, +udatpg_getSkeleton(UDateTimePatternGenerator *unusedDtpg, const UChar *pattern, int32_t length, UChar *skeleton, int32_t capacity, UErrorCode *pErrorCode); @@ -286,7 +323,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" @@ -297,7 +335,7 @@ udatpg_getSkeleton(UDateTimePatternGenerator *dtpg, * @stable ICU 3.8 */ U_STABLE int32_t U_EXPORT2 -udatpg_getBaseSkeleton(UDateTimePatternGenerator *dtpg, +udatpg_getBaseSkeleton(UDateTimePatternGenerator *unusedDtpg, const UChar *pattern, int32_t length, UChar *baseSkeleton, int32_t capacity, UErrorCode *pErrorCode); @@ -393,12 +431,14 @@ udatpg_setAppendItemName(UDateTimePatternGenerator *dtpg, /** * Getter corresponding to setAppendItemNames. Values below 0 or at or above - * UDATPG_FIELD_COUNT are illegal arguments. + * UDATPG_FIELD_COUNT are illegal arguments. Note: The more general function + * for getting date/time field display names is udatpg_getFieldDisplayName. * * @param dtpg a pointer to UDateTimePatternGenerator. * @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 + * @see udatpg_getFieldDisplayName * @stable ICU 3.8 */ U_STABLE const UChar * U_EXPORT2 @@ -406,15 +446,51 @@ udatpg_getAppendItemName(const UDateTimePatternGenerator *dtpg, UDateTimePatternField field, int32_t *pLength); +#ifndef U_HIDE_DRAFT_API /** - * 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 general interface to get a display name for a particular date/time field, + * in one of several possible display widths. + * + * @param dtpg + * A pointer to the UDateTimePatternGenerator object with the localized + * display names. + * @param field + * The desired UDateTimePatternField, such as UDATPG_ERA_FIELD. + * @param width + * The desired UDateTimePGDisplayWidth, such as UDATPG_ABBREVIATED. + * @param fieldName + * A pointer to a buffer to receive the NULL-terminated display name. If the name + * fits into fieldName but cannot be NULL-terminated (length == capacity) then + * the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the name doesn't + * fit into fieldName then the error code is set to U_BUFFER_OVERFLOW_ERROR. + * @param capacity + * The size of fieldName (in UChars). + * @param pErrorCode + * A pointer to a UErrorCode to receive any errors + * @return + * The full length of the name; if greater than capacity, fieldName contains a + * truncated result. + * @draft ICU 61 + */ +U_DRAFT int32_t U_EXPORT2 +udatpg_getFieldDisplayName(const UDateTimePatternGenerator *dtpg, + UDateTimePatternField field, + UDateTimePGDisplayWidth width, + UChar *fieldName, int32_t capacity, + UErrorCode *pErrorCode); +#endif // U_HIDE_DRAFT_API + +/** + * 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, @@ -422,8 +498,8 @@ 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 3.8 */ @@ -583,4 +659,44 @@ 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