ICU 56 update step 1

source/i18n/unicode/udat.h

Index: source/i18n/unicode/udat.h
diff --git a/source/i18n/unicode/udat.h b/source/i18n/unicode/udat.h
index 5bbe5aa0736c81bc52beb436c5b0c9f48586c5f6..bb673ca2d9052a2cd3ef5292a8fc86e91ddc008b 100644
--- a/source/i18n/unicode/udat.h
+++ b/source/i18n/unicode/udat.h
@@ -1,6 +1,6 @@
 /*
  *******************************************************************************
- * Copyright (C) 1996-2014, International Business Machines
+ * Copyright (C) 1996-2015, International Business Machines
  * Corporation and others. All Rights Reserved.
  *******************************************************************************
 */
@@ -16,6 +16,7 @@
 #include "unicode/ucal.h"
 #include "unicode/unum.h"
 #include "unicode/udisplaycontext.h"
+#include "unicode/ufieldpositer.h"
 /**
  * \file
  * \brief C API: DateFormat
@@ -760,6 +761,16 @@ typedef enum UDateFormatField {
     UDAT_RELATED_YEAR_FIELD = 34,
 #endif /* U_HIDE_INTERNAL_API */
 
+#ifndef U_HIDE_DRAFT_API
+    /**
+     * FieldPosition and UFieldPosition selector for time separator,
+     * no corresponding UCAL_ field. No pattern character is currently
+     * defined for this.
+     * @draft ICU 55
+     */
+    UDAT_TIME_SEPARATOR_FIELD = 35,
+#endif  /* U_HIDE_DRAFT_API */
+
    /**
      * Number of FieldPosition and UFieldPosition selectors for
      * DateFormat and UDateFormat.
@@ -768,11 +779,21 @@ typedef enum UDateFormatField {
      * in the future.
      * @stable ICU 3.0
      */
-    UDAT_FIELD_COUNT = 35
+    UDAT_FIELD_COUNT = 36
 
 } UDateFormatField;
 
 
+#ifndef U_HIDE_INTERNAL_API
+/**
+ * Is a pattern character defined for UDAT_TIME_SEPARATOR_FIELD?
+ * In ICU 55 it was COLON, but that was withdrawn in ICU 56.
+ * @internal ICU 56
+ */
+#define UDAT_HAS_PATTERN_CHAR_FOR_TIME_SEPARATOR 0
+#endif /* U_HIDE_INTERNAL_API */
+
+
 /**
  * Maps from a UDateFormatField to the corresponding UCalendarDateFields.
  * Note: since the mapping is many-to-one, there is no inverse mapping.
@@ -834,46 +855,44 @@ U_STABLE void U_EXPORT2
 udat_close(UDateFormat* format);
 
 
-/* Dont hide UDateFormatBooleanAttribute type with #ifndef U_HIDE_DRAFT_API, needed by virtual methods */
-/* Also don't hide UDAT_BOOLEAN_ATTRIBUTE_COUNT, needed by template class EnumSet<UDateFormatBooleanAttribute,...> */
 /**
  * DateFormat boolean attributes
  * 
- * @draft ICU 53
+ * @stable ICU 53
  */
 typedef enum UDateFormatBooleanAttribute {
-#ifndef U_HIDE_DRAFT_API
    /**
      * indicates whether whitespace is allowed. Includes trailing dot tolerance.
-     * @draft ICU 53
+     * @stable ICU 53
      */
     UDAT_PARSE_ALLOW_WHITESPACE = 0,
     /**
      * indicates tolerance of numeric data when String data may be assumed. eg: UDAT_YEAR_NAME_FIELD,
      * UDAT_STANDALONE_MONTH_FIELD, UDAT_DAY_OF_WEEK_FIELD
-     * @draft ICU 53
+     * @stable ICU 53
      */
     UDAT_PARSE_ALLOW_NUMERIC = 1,
+#ifndef U_HIDE_DRAFT_API
     /**
      * indicates tolerance of a partial literal match
-     * @draft ICU 53
+     * e.g. accepting "--mon-02-march-2011" for a pattern of "'--: 'EEE-WW-MMMM-yyyy"
+     * @draft ICU 56
      */
-    UDAT_PARSE_PARTIAL_MATCH = 2,
+    UDAT_PARSE_PARTIAL_LITERAL_MATCH = 2,
     /**  
      * indicates tolerance of pattern mismatch between input data and specified format pattern. 
      * e.g. accepting "September" for a month pattern of MMM ("Sep")   
-     * @draft ICU 53
+     * @draft ICU 56
      */ 
     UDAT_PARSE_MULTIPLE_PATTERNS_FOR_MATCH = 3,
 #endif /* U_HIDE_DRAFT_API */
     /**
      * count boolean date format constants
-     * @draft ICU 53
+     * @stable ICU 53
      */
     UDAT_BOOLEAN_ATTRIBUTE_COUNT = 4
 } UDateFormatBooleanAttribute;
 
-#ifndef U_HIDE_DRAFT_API
 /**
  * Get a boolean attribute associated with a UDateFormat.
  * An example would be a true value for a key of UDAT_PARSE_ALLOW_WHITESPACE indicating allowing whitespace leniency.
@@ -882,9 +901,9 @@ typedef enum UDateFormatBooleanAttribute {
  * @param attr The attribute to query; e.g. UDAT_PARSE_ALLOW_WHITESPACE.
  * @param status A pointer to an UErrorCode to receive any errors
  * @return The value of attr.
- * @draft ICU 53
+ * @stable ICU 53
  */
-U_DRAFT UBool U_EXPORT2
+U_STABLE UBool U_EXPORT2
 udat_getBooleanAttribute(const UDateFormat* fmt, UDateFormatBooleanAttribute attr, UErrorCode* status);
 
 /**
@@ -895,13 +914,11 @@ udat_getBooleanAttribute(const UDateFormat* fmt, UDateFormatBooleanAttribute att
  * @param attr The attribute to set; one of UDAT_PARSE_ALLOW_WHITESPACE or UDAT_PARSE_ALLOW_NUMERIC
  * @param newValue The new value of attr.
  * @param status A pointer to an UErrorCode to receive any errors
- * @draft ICU 53
+ * @stable ICU 53
  */
-U_DRAFT void U_EXPORT2
+U_STABLE void U_EXPORT2
 udat_setBooleanAttribute(UDateFormat *fmt, UDateFormatBooleanAttribute attr, UBool newValue, UErrorCode* status);
 
-#endif /* U_HIDE_DRAFT_API */
-
 
 
 #if U_SHOW_CPLUSPLUS_API
@@ -936,7 +953,7 @@ udat_clone(const UDateFormat *fmt,
        UErrorCode *status);
 
 /**
-* Format a date using an UDateFormat.
+* Format a date using a UDateFormat.
 * The date will be formatted using the conventions specified in {@link #udat_open }
 * @param format The formatter to use
 * @param dateToFormat The date to format
@@ -961,6 +978,112 @@ udat_format(    const    UDateFormat*    format,
                         UFieldPosition* position,
                         UErrorCode*     status);
 
+#ifndef U_HIDE_DRAFT_API
+/**
+* Format a date using an UDateFormat.
+* The date will be formatted using the conventions specified in {@link #udat_open }
+* @param format The formatter to use
+* @param calendar The calendar to format. The calendar instance might be
+*                 mutated if fields are not yet fully calculated, though
+*                 the function won't change the logical date and time held
+*                 by the instance.
+* @param result A pointer to a buffer to receive the formatted number.
+* @param capacity The maximum size of result.
+* @param position A pointer to a UFieldPosition.  On input, position->field
+* is read.  On output, position->beginIndex and position->endIndex indicate
+* the beginning and ending indices of field number position->field, if such
+* a field exists.  This parameter may be NULL, in which case no field
+* position data is returned.
+* @param status A pointer to an UErrorCode to receive any errors
+* @return The total buffer size needed; if greater than resultLength, the output was truncated.
+* @see udat_format
+* @see udat_parseCalendar
+* @see UFieldPosition
+* @draft ICU 55
+*/
+U_DRAFT int32_t U_EXPORT2
+udat_formatCalendar(    const UDateFormat*  format,
+                        UCalendar*      calendar,
+                        UChar*          result,
+                        int32_t         capacity,
+                        UFieldPosition* position,
+                        UErrorCode*     status);
+
+/**
+* Format a date using a UDateFormat.
+* The date will be formatted using the conventions specified in {@link #udat_open}
+* @param format
+*          The formatter to use
+* @param dateToFormat
+*          The date to format
+* @param result
+*          A pointer to a buffer to receive the formatted number.
+* @param resultLength
+*          The maximum size of result.
+* @param fpositer
+*          A pointer to a UFieldPositionIterator created by {@link #ufieldpositer_open}
+*          (may be NULL if field position information is not needed). Any
+*          iteration information already present in the UFieldPositionIterator
+*          will be deleted, and the iterator will be reset to apply to the
+*          fields in the formatted string created by this function call; the
+*          field values provided by {@link #ufieldpositer_next} will be from the
+*          UDateFormatField enum.
+* @param status
+*          A pointer to a UErrorCode to receive any errors
+* @return
+*          The total buffer size needed; if greater than resultLength, the output was truncated.
+* @see udat_parse
+* @see UFieldPositionIterator
+* @draft ICU 55
+*/
+U_DRAFT int32_t U_EXPORT2 
+udat_formatForFields(   const UDateFormat* format,
+                        UDate           dateToFormat,
+                        UChar*          result,
+                        int32_t         resultLength,
+                        UFieldPositionIterator* fpositer,
+                        UErrorCode*     status);
+
+/**
+* Format a date using a UDateFormat.
+* The date will be formatted using the conventions specified in {@link #udat_open }
+* @param format
+*          The formatter to use
+* @param calendar
+*          The calendar to format. The calendar instance might be mutated if fields
+*          are not yet fully calculated, though the function won't change the logical
+*          date and time held by the instance.
+* @param result
+*          A pointer to a buffer to receive the formatted number.
+* @param capacity
+*          The maximum size of result.
+* @param fpositer
+*          A pointer to a UFieldPositionIterator created by {@link #ufieldpositer_open}
+*          (may be NULL if field position information is not needed). Any
+*          iteration information already present in the UFieldPositionIterator
+*          will be deleted, and the iterator will be reset to apply to the
+*          fields in the formatted string created by this function call; the
+*          field values provided by {@link #ufieldpositer_next} will be from the
+*          UDateFormatField enum.
+* @param status
+*          A pointer to a UErrorCode to receive any errors
+* @return
+*          The total buffer size needed; if greater than resultLength, the output was truncated.
+* @see udat_format
+* @see udat_parseCalendar
+* @see UFieldPositionIterator
+* @draft ICU 55
+*/
+U_DRAFT int32_t U_EXPORT2
+udat_formatCalendarForFields( const UDateFormat* format,
+                        UCalendar*      calendar,
+                        UChar*          result,
+                        int32_t         capacity,
+                        UFieldPositionIterator* fpositer,
+                        UErrorCode*     status);
+
+#endif  /* U_HIDE_DRAFT_API */
+
 /**
 * Parse a string into an date/time using a UDateFormat.
 * The date will be parsed using the conventions specified in {@link #udat_open }.
@@ -1084,7 +1207,6 @@ udat_setCalendar(            UDateFormat*    fmt,
 U_STABLE const UNumberFormat* U_EXPORT2 
 udat_getNumberFormat(const UDateFormat* fmt);
 
-#ifndef U_HIDE_DRAFT_API
 /**
 * Get the UNumberFormat for specific field associated with an UDateFormat.
 * For example: 'y' for year and 'M' for month
@@ -1092,9 +1214,9 @@ udat_getNumberFormat(const UDateFormat* fmt);
 * @param field the field to query
 * @return A pointer to the UNumberFormat used by fmt to format field numbers.
 * @see udat_setNumberFormatForField
-* @draft ICU 54
+* @stable ICU 54
 */
-U_DRAFT const UNumberFormat* U_EXPORT2 
+U_STABLE const UNumberFormat* U_EXPORT2 
 udat_getNumberFormatForField(const UDateFormat* fmt, UChar field);
 
 /**
@@ -1110,15 +1232,13 @@ udat_getNumberFormatForField(const UDateFormat* fmt, UChar field);
 * @param numberFormatToSet A pointer to the UNumberFormat to be used by fmt to format numbers.
 * @param status error code passed around (memory allocation or invalid fields)
 * @see udat_getNumberFormatForField
-* @draft ICU 54
+* @stable ICU 54
 */
-U_DRAFT void U_EXPORT2 
+U_STABLE void U_EXPORT2 
 udat_adoptNumberFormatForFields(  UDateFormat* fmt,
                             const UChar* fields,
                                   UNumberFormat*  numberFormatToSet,
                                   UErrorCode* status);
-#endif  /* U_HIDE_DRAFT_API */
-
 /**
 * Set the UNumberFormat associated with an UDateFormat.
 * A UDateFormat uses a UNumberFormat to format numbers within a date,
@@ -1134,8 +1254,6 @@ udat_adoptNumberFormatForFields(  UDateFormat* fmt,
 U_STABLE void U_EXPORT2 
 udat_setNumberFormat(            UDateFormat*    fmt,
                         const   UNumberFormat*  numberFormatToSet);
-
-#ifndef U_HIDE_DRAFT_API
 /**
 * Adopt the UNumberFormat associated with an UDateFormat.
 * A UDateFormat uses a UNumberFormat to format numbers within a date,
@@ -1143,13 +1261,11 @@ udat_setNumberFormat(            UDateFormat*    fmt,
 * @param fmt The formatter to set.
 * @param numberFormatToAdopt A pointer to the UNumberFormat to be used by fmt to format numbers.
 * @see udat_getNumberFormat
-* @draft ICU 54
+* @stable ICU 54
 */
-U_DRAFT void U_EXPORT2 
+U_STABLE void U_EXPORT2 
 udat_adoptNumberFormat(            UDateFormat*    fmt,
                                    UNumberFormat*  numberFormatToAdopt);
-#endif  /* U_HIDE_DRAFT_API */
-
 /**
 * Get a locale for which date/time formatting patterns are available.
 * A UDateFormat in a locale returned by this function will perform the correct
@@ -1297,44 +1413,41 @@ typedef enum UDateFormatSymbolType {
      * Standalone version of UDAT_SHORTER_WEEKDAYS.
      * @stable ICU 51
      */
-    UDAT_STANDALONE_SHORTER_WEEKDAYS
-#ifndef U_HIDE_DRAFT_API
-    ,
-	/**
-	 * Cyclic year names (only supported for some calendars, and only for FORMAT usage;
-	 * udat_setSymbols not supported for UDAT_CYCLIC_YEARS_WIDE)
-	 * @draft ICU 54
-	 */
-	UDAT_CYCLIC_YEARS_WIDE,
-	/**
-	 * Cyclic year names (only supported for some calendars, and only for FORMAT usage)
-	 * @draft ICU 54
-	 */
-	UDAT_CYCLIC_YEARS_ABBREVIATED,
-	/**
-	 * Cyclic year names (only supported for some calendars, and only for FORMAT usage;
-	 * udat_setSymbols not supported for UDAT_CYCLIC_YEARS_NARROW)
-	 * @draft ICU 54
-	 */
-	UDAT_CYCLIC_YEARS_NARROW,
-	/**
-	 * Calendar zodiac  names (only supported for some calendars, and only for FORMAT usage;
-	 * udat_setSymbols not supported for UDAT_ZODIAC_NAMES_WIDE)
-	 * @draft ICU 54
-	 */
-	UDAT_ZODIAC_NAMES_WIDE,
-	/**
-	 * Calendar zodiac  names (only supported for some calendars, and only for FORMAT usage)
-	 * @draft ICU 54
-	 */
-	UDAT_ZODIAC_NAMES_ABBREVIATED,
-	/**
-	 * Calendar zodiac  names (only supported for some calendars, and only for FORMAT usage;
-	 * udat_setSymbols not supported for UDAT_ZODIAC_NAMES_NARROW)
-	 * @draft ICU 54
-	 */
-	UDAT_ZODIAC_NAMES_NARROW
-#endif  /* U_HIDE_DRAFT_API */
+    UDAT_STANDALONE_SHORTER_WEEKDAYS,
+    /**
+     * Cyclic year names (only supported for some calendars, and only for FORMAT usage;
+     * udat_setSymbols not supported for UDAT_CYCLIC_YEARS_WIDE)
+     * @stable ICU 54
+     */
+    UDAT_CYCLIC_YEARS_WIDE,
+    /**
+     * Cyclic year names (only supported for some calendars, and only for FORMAT usage)
+     * @stable ICU 54
+     */
+    UDAT_CYCLIC_YEARS_ABBREVIATED,
+    /**
+     * Cyclic year names (only supported for some calendars, and only for FORMAT usage;
+     * udat_setSymbols not supported for UDAT_CYCLIC_YEARS_NARROW)
+     * @stable ICU 54
+     */
+    UDAT_CYCLIC_YEARS_NARROW,
+    /**
+     * Calendar zodiac  names (only supported for some calendars, and only for FORMAT usage;
+     * udat_setSymbols not supported for UDAT_ZODIAC_NAMES_WIDE)
+     * @stable ICU 54
+     */
+    UDAT_ZODIAC_NAMES_WIDE,
+    /**
+     * Calendar zodiac  names (only supported for some calendars, and only for FORMAT usage)
+     * @stable ICU 54
+     */
+    UDAT_ZODIAC_NAMES_ABBREVIATED,
+    /**
+     * Calendar zodiac  names (only supported for some calendars, and only for FORMAT usage;
+     * udat_setSymbols not supported for UDAT_ZODIAC_NAMES_NARROW)
+     * @stable ICU 54
+     */
+    UDAT_ZODIAC_NAMES_NARROW
 } UDateFormatSymbolType;
 
 struct UDateFormatSymbols;
@@ -1432,7 +1545,6 @@ udat_getLocaleByType(const UDateFormat *fmt,
 U_DRAFT void U_EXPORT2
 udat_setContext(UDateFormat* fmt, UDisplayContext value, UErrorCode* status);
 
-#ifndef U_HIDE_DRAFT_API
 /**
  * Get the formatter's UDisplayContext value for the specified UDisplayContextType,
  * such as UDISPCTX_TYPE_CAPITALIZATION.
@@ -1440,13 +1552,11 @@ udat_setContext(UDateFormat* fmt, UDisplayContext value, UErrorCode* status);
  * @param type The UDisplayContextType whose value to return
  * @param status A pointer to an UErrorCode to receive any errors
  * @return The UDisplayContextValue for the specified type.
- * @draft ICU 53
+ * @stable ICU 53
  */
-U_DRAFT UDisplayContext U_EXPORT2
+U_STABLE UDisplayContext U_EXPORT2
 udat_getContext(const UDateFormat* fmt, UDisplayContextType type, UErrorCode* status);
 
-#endif  /* U_HIDE_DRAFT_API */
-
 #ifndef U_HIDE_INTERNAL_API
 /**
 * Extract the date pattern from a UDateFormat set for relative date formatting.