+// © 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
/*
*******************************************************************************
*
-* Copyright (C) 2007-2011, 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
*
/**
* \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
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
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;
/**
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;
/**
U_NAMESPACE_END
-#endif
+#endif // U_SHOW_CPLUSPLUS_API
/**
* Create a copy pf a generator.
* 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"
* @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);
* 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"
* @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);
/**
* 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
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.
* <p>
* 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,
*
* @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
*/
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
projects / apple / icu.git / blobdiff