ICU 56 update step 1

source/i18n/unicode/udat.h

 /*
  *******************************************************************************
- * Copyright (C) 1996-2014, International Business Machines
+ * Copyright (C) 1996-2015, International Business Machines
  * Corporation and others. All Rights Reserved.
  *******************************************************************************
 */
 
 #ifndef UDAT_H
 #define UDAT_H
 
 #include "unicode/utypes.h"
 
 #if !UCONFIG_NO_FORMATTING
 
 #include "unicode/localpointer.h"
 #include "unicode/ucal.h"
 #include "unicode/unum.h"
 #include "unicode/udisplaycontext.h"
+#include "unicode/ufieldpositer.h"
 /**
  * \file
  * \brief C API: DateFormat
  *
  * <h2> Date Format C API</h2>
  *
  * Date Format C API  consists of functions that convert dates and
  * times from their internal representations to textual form and back again in a
  * language-independent manner. Converting from the internal representation (milliseconds
  * since midnight, January 1, 1970) to text is known as "formatting," and converting
@@ skipping 724 matching lines @@
 
 #ifndef U_HIDE_INTERNAL_API
     /**
      * FieldPosition and UFieldPosition selector for 'r' field alignment,
      * no directly corresponding UCAL_ field.
      * @internal ICU 53
      */
     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.
      * Valid selectors range from 0 to UDAT_FIELD_COUNT-1.
      * This value is subject to change if new fields are defined
      * 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.
  * @param field the UDateFormatField.
  * @return the UCalendarDateField.  This will be UCAL_FIELD_COUNT in case
  * of error (e.g., the input field is UDAT_FIELD_COUNT).
  * @stable ICU 4.4
  */
 U_STABLE UCalendarDateFields U_EXPORT2
 udat_toCalendarDateField(UDateFormatField field);
@@ skipping 41 matching lines @@
 /**
 * Close a UDateFormat.
 * Once closed, a UDateFormat may no longer be used.
 * @param format The formatter to close.
 * @stable ICU 2.0
 */
 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.
  * If the formatter does not understand the attribute, -1 is returned.
  * @param fmt The formatter to query.
  * @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);
 
 /**
  * Set a boolean attribute associated with a UDateFormat.
  * An example of a boolean attribute is parse leniency control.  If the formatter does not understand
  * the attribute, the call is ignored.
  * @param fmt The formatter to set.
  * @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
 
 U_NAMESPACE_BEGIN
 
 /**
  * \class LocalUDateFormatPointer
  * "Smart pointer" class, closes a UDateFormat via udat_close().
  * For most methods see the LocalPointerBase base class.
@@ skipping 14 matching lines @@
  * @param fmt The format to copy
  * @param status A pointer to an UErrorCode to receive any errors.
  * @return A pointer to a UDateFormat identical to fmt.
  * @stable ICU 2.0
  */
 U_STABLE UDateFormat* U_EXPORT2 
 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
 * @param result A pointer to a buffer to receive the formatted number.
 * @param resultLength 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_parse
 * @see UFieldPosition
 * @stable ICU 2.0
 */
 U_STABLE int32_t U_EXPORT2 
 udat_format(    const    UDateFormat*    format,
                         UDate           dateToFormat,
                         UChar*          result,
                         int32_t         resultLength,
                         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 }.
 * <P>
 * Note that the normal date formats associated with some calendars - such
 * as the Chinese lunar calendar - do not specify enough fields to enable
 * dates to be parsed unambiguously. In the case of the Chinese lunar
 * calendar, while the year within the current 60-year cycle is specified,
 * the number of such cycles since the start date of the calendar (in the
 * UCAL_ERA field of the UCalendar object) is not normally part of the format,
 * and parsing may assume the wrong era. For cases such as this it is
@@ skipping 102 matching lines @@
 * A UDateFormat uses a UNumberFormat to format numbers within a date,
 * for example the day number.
 * @param fmt The formatter to query.
 * @return A pointer to the UNumberFormat used by fmt to format numbers.
 * @see udat_setNumberFormat
 * @stable ICU 2.0
 */
 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
 * @param fmt The formatter to query.
 * @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);
 
 /**
 * Set the UNumberFormat for specific field associated with an UDateFormat.
 * It can be a single field like: "y"(year) or "M"(month)
 * It can be several field combined together: "yM"(year and month)
 * Note: 
 * 1 symbol field is enough for multiple symbol field (so "y" will override "yy", "yyy")
 * If the field is not numeric, then override has no effect (like "MMM" will use abbreviation, not numerical field)
 *
 * @param fields the fields to set
 * @param fmt The formatter to set.
 * @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,
 * for example the day number.
 * This method also clears per field NumberFormat instances previously 
 * set by {@see udat_setNumberFormatForField} 
 * @param fmt The formatter to set.
 * @param numberFormatToSet A pointer to the UNumberFormat to be used by fmt to format numbers.
 * @see udat_getNumberFormat
 * @see udat_setNumberFormatForField
 * @stable ICU 2.0
 */
 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,
 * for example the day number.
 * @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
 * formatting and parsing for the locale.
 * @param localeIndex The index of the desired locale.
 * @return A locale for which date/time formatting patterns are available, or 0 if none.
 * @see udat_countAvailable
 * @stable ICU 2.0
 */
 U_STABLE const char* U_EXPORT2 
@@ skipping 127 matching lines @@
      * These are named "SHORTER" to contrast with the constants using _SHORT_
      * above, which actually get the CLDR-style *abbreviated* versions of the
      * corresponding names.
      * @stable ICU 51
      */
     UDAT_SHORTER_WEEKDAYS,
     /**
      * 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;
 /** Date format symbols.
  *  For usage in C programs.
  *  @stable ICU 2.6
  */
 typedef struct UDateFormatSymbols UDateFormatSymbols;
 
 /**
@@ skipping 77 matching lines @@
  * Set a particular UDisplayContext value in the formatter, such as
  * UDISPCTX_CAPITALIZATION_FOR_STANDALONE.
  * @param fmt The formatter for which to set a UDisplayContext value.
  * @param value The UDisplayContext value to set.
  * @param status A pointer to an UErrorCode to receive any errors
  * @stable ICU 51
  */
 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.
  * @param fmt The formatter to query.
  * @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.
 * The pattern will follow the pattern syntax rules.
 * @param fmt The formatter to query.
 * @param result A pointer to a buffer to receive the pattern.
 * @param resultLength The maximum size of result.
 * @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_applyPatternRelative
@@ skipping 67 matching lines @@
  * @internal ICU 49
  */
 U_INTERNAL UDateFormatOpener U_EXPORT2
 udat_unregisterOpener(UDateFormatOpener opener, UErrorCode *status);
 #endif  /* U_HIDE_INTERNAL_API */
 
 
 #endif /* #if !UCONFIG_NO_FORMATTING */
 
 #endif