ICU-59180.0.1.tar.gz

[apple/icu.git] / icuSources / i18n / unicode / ucal.h

diff --git a/icuSources/i18n/unicode/ucal.h b/icuSources/i18n/unicode/ucal.h
index 3097e57ac3ef0feffa0d229b43d75f2043417453..cb89a74b1866c6ce49c59a377bdd86773f9ce675 100644 (file)
--- a/icuSources/i18n/unicode/ucal.h
+++ b/icuSources/i18n/unicode/ucal.h
@@ -1,6 +1,8 @@
+// © 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html

 /*
  *******************************************************************************
 /*
  *******************************************************************************

- * Copyright (C) 1996-2013, International Business Machines Corporation and
+ * Copyright (C) 1996-2015, International Business Machines Corporation and

  * others. All Rights Reserved.
  *******************************************************************************
  */
  * others. All Rights Reserved.
  *******************************************************************************
  */


@@ -422,11 +424,13 @@ enum UCalendarDateFields {
    * an example of this.
    */
   UCAL_IS_LEAP_MONTH,
    * an example of this.
    */
   UCAL_IS_LEAP_MONTH,

-  
-  /**
-   * Field count
-   * @stable ICU 2.6
-   */
+
+    /* Do not conditionalize the following with #ifndef U_HIDE_DEPRECATED_API,
+     * it is needed for layout of Calendar, DateFormat, and other objects */
+    /**
+     * One more than the highest normal UCalendarDateFields value.
+     * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
+     */

   UCAL_FIELD_COUNT,
 
  /**
   UCAL_FIELD_COUNT,
 
  /**


@@ -716,7 +720,7 @@ U_DEFINE_LOCAL_OPEN_POINTER(LocalUCalendarPointer, UCalendar, ucal_close);
 
 U_NAMESPACE_END
 
 
 U_NAMESPACE_END
 

-#endif
+#endif // U_SHOW_CPLUSPLUS_API

 
 /**
  * Open a copy of a UCalendar.
 
 /**
  * Open a copy of a UCalendar.


@@ -745,7 +749,6 @@ ucal_setTimeZone(UCalendar*    cal,
                  int32_t       len,
                  UErrorCode*   status);
 
                  int32_t       len,
                  UErrorCode*   status);
 

-#ifndef U_HIDE_DRAFT_API

 /** 
  * Get the ID of the UCalendar's time zone. 
  * 
 /** 
  * Get the ID of the UCalendar's time zone. 
  * 


@@ -754,14 +757,13 @@ ucal_setTimeZone(UCalendar*    cal,
  * @param resultLength  The maximum size of result. 
  * @param status        Receives the status. 
  * @return              The total buffer size needed; if greater than resultLength, the output was truncated. 
  * @param resultLength  The maximum size of result. 
  * @param status        Receives the status. 
  * @return              The total buffer size needed; if greater than resultLength, the output was truncated. 

- * @draft ICU 51 
+ * @stable ICU 51 

  */ 
  */ 

-U_DRAFT int32_t U_EXPORT2 
+U_STABLE int32_t U_EXPORT2 

 ucal_getTimeZoneID(const UCalendar *cal,
                    UChar *result,
                    int32_t resultLength,
                    UErrorCode *status);
 ucal_getTimeZoneID(const UCalendar *cal,
                    UChar *result,
                    int32_t resultLength,
                    UErrorCode *status);

-#endif /* U_HIDE_DRAFT_API */

 
 /**
  * Possible formats for a UCalendar's display name 
 
 /**
  * Possible formats for a UCalendar's display name 


@@ -1289,7 +1291,7 @@ ucal_getTZDataVersion(UErrorCode* status);
  * @param resultCapacity    The capacity of the result buffer.
  * @param isSystemID        Receives if the given ID is a known system
      *                      timezone ID.
  * @param resultCapacity    The capacity of the result buffer.
  * @param isSystemID        Receives if the given ID is a known system
      *                      timezone ID.

- * @param status    Recevies the status.  When the given timezone ID
+ * @param status    Receives the status.  When the given timezone ID

  *                  is neither a known system time zone ID nor a
  *                  valid custom timezone ID, U_ILLEGAL_ARGUMENT_ERROR
  *                  is set.
  *                  is neither a known system time zone ID nor a
  *                  valid custom timezone ID, U_ILLEGAL_ARGUMENT_ERROR
  *                  is set.


@@ -1445,40 +1447,38 @@ ucal_getFieldDifference(UCalendar* cal,
                         UCalendarDateFields field,
                         UErrorCode* status);
 
                         UCalendarDateFields field,
                         UErrorCode* status);
 

-#ifndef U_HIDE_DRAFT_API

 /**
  * Time zone transition types for ucal_getTimeZoneTransitionDate
 /**
  * Time zone transition types for ucal_getTimeZoneTransitionDate

- * @draft ICU 50
+ * @stable ICU 50

  */
 enum UTimeZoneTransitionType {
     /**
      * Get the next transition after the current date,
      * i.e. excludes the current date
  */
 enum UTimeZoneTransitionType {
     /**
      * Get the next transition after the current date,
      * i.e. excludes the current date

-     * @draft ICU 50
+     * @stable ICU 50

      */
     UCAL_TZ_TRANSITION_NEXT,
     /**
      * Get the next transition on or after the current date,
      * i.e. may include the current date
      */
     UCAL_TZ_TRANSITION_NEXT,
     /**
      * Get the next transition on or after the current date,
      * i.e. may include the current date

-     * @draft ICU 50
+     * @stable ICU 50

      */
     UCAL_TZ_TRANSITION_NEXT_INCLUSIVE,
     /**
      * Get the previous transition before the current date,
      * i.e. excludes the current date
      */
     UCAL_TZ_TRANSITION_NEXT_INCLUSIVE,
     /**
      * Get the previous transition before the current date,
      * i.e. excludes the current date

-     * @draft ICU 50
+     * @stable ICU 50

      */
     UCAL_TZ_TRANSITION_PREVIOUS,
     /**
      * Get the previous transition on or before the current date,
      * i.e. may include the current date
      */
     UCAL_TZ_TRANSITION_PREVIOUS,
     /**
      * Get the previous transition on or before the current date,
      * i.e. may include the current date

-     * @draft ICU 50
+     * @stable ICU 50

      */
     UCAL_TZ_TRANSITION_PREVIOUS_INCLUSIVE
 };
 
      */
     UCAL_TZ_TRANSITION_PREVIOUS_INCLUSIVE
 };
 

-/** @draft ICU 50 */
-typedef enum UTimeZoneTransitionType UTimeZoneTransitionType;
+typedef enum UTimeZoneTransitionType UTimeZoneTransitionType; /**< @stable ICU 50 */

 
 /**
 * Get the UDate for the next/previous time zone transition relative to
 
 /**
 * Get the UDate for the next/previous time zone transition relative to


@@ -1493,13 +1493,123 @@ typedef enum UTimeZoneTransitionType UTimeZoneTransitionType;
 * @param status A pointer to a UErrorCode to receive any errors.
 * @return TRUE if a valid transition time is set in *transition, FALSE
 *         otherwise.
 * @param status A pointer to a UErrorCode to receive any errors.
 * @return TRUE if a valid transition time is set in *transition, FALSE
 *         otherwise.

-* @draft ICU 50
+* @stable ICU 50

 */
 */

-U_DRAFT UBool U_EXPORT2 
+U_STABLE UBool U_EXPORT2 

 ucal_getTimeZoneTransitionDate(const UCalendar* cal, UTimeZoneTransitionType type,
                                UDate* transition, UErrorCode* status);
 
 ucal_getTimeZoneTransitionDate(const UCalendar* cal, UTimeZoneTransitionType type,
                                UDate* transition, UErrorCode* status);
 

-#endif  /* U_HIDE_DRAFT_API */
+/**
+* Converts a system time zone ID to an equivalent Windows time zone ID. For example,
+* Windows time zone ID "Pacific Standard Time" is returned for input "America/Los_Angeles".
+*
+* <p>There are system time zones that cannot be mapped to Windows zones. When the input
+* system time zone ID is unknown or unmappable to a Windows time zone, then this
+* function returns 0 as the result length, but the operation itself remains successful
+* (no error status set on return).
+*
+* <p>This implementation utilizes <a href="http://unicode.org/cldr/charts/supplemental/zone_tzid.html">
+* Zone-Tzid mapping data</a>. The mapping data is updated time to time. To get the latest changes,
+* please read the ICU user guide section <a href="http://userguide.icu-project.org/datetime/timezone#TOC-Updating-the-Time-Zone-Data">
+* Updating the Time Zone Data</a>.
+*
+* @param id            A system time zone ID.
+* @param len           The length of <code>id</code>, or -1 if null-terminated.
+* @param winid         A buffer to receive a Windows time zone ID.
+* @param winidCapacity The capacity of the result buffer <code>winid</code>.
+* @param status        Receives the status.
+* @return              The result string length, not including the terminating null.
+* @see ucal_getTimeZoneIDForWindowsID
+*
+* @stable ICU 52
+*/
+U_STABLE int32_t U_EXPORT2
+ucal_getWindowsTimeZoneID(const UChar* id, int32_t len,
+                            UChar* winid, int32_t winidCapacity, UErrorCode* status);
+
+/**
+* Converts a Windows time zone ID to an equivalent system time zone ID
+* for a region. For example, system time zone ID "America/Los_Angeles" is returned
+* for input Windows ID "Pacific Standard Time" and region "US" (or <code>null</code>),
+* "America/Vancouver" is returned for the same Windows ID "Pacific Standard Time" and
+* region "CA".
+*
+* <p>Not all Windows time zones can be mapped to system time zones. When the input
+* Windows time zone ID is unknown or unmappable to a system time zone, then this
+* function returns 0 as the result length, but the operation itself remains successful
+* (no error status set on return).
+*
+* <p>This implementation utilizes <a href="http://unicode.org/cldr/charts/supplemental/zone_tzid.html">
+* Zone-Tzid mapping data</a>. The mapping data is updated time to time. To get the latest changes,
+* please read the ICU user guide section <a href="http://userguide.icu-project.org/datetime/timezone#TOC-Updating-the-Time-Zone-Data">
+* Updating the Time Zone Data</a>.
+*
+* @param winid         A Windows time zone ID.
+* @param len           The length of <code>winid</code>, or -1 if null-terminated.
+* @param region        A null-terminated region code, or <code>NULL</code> if no regional preference.
+* @param id            A buffer to receive a system time zone ID.
+* @param idCapacity    The capacity of the result buffer <code>id</code>.
+* @param status        Receives the status.
+* @return              The result string length, not including the terminating null.
+* @see ucal_getWindowsTimeZoneID
+*
+* @stable ICU 52
+*/
+U_STABLE int32_t U_EXPORT2
+ucal_getTimeZoneIDForWindowsID(const UChar* winid, int32_t len, const char* region,
+                                UChar* id, int32_t idCapacity, UErrorCode* status);
+
+#ifndef U_HIDE_DRAFT_API
+/**
+ * Day periods
+ * @draft Apple
+ */
+typedef enum UADayPeriod {
+    UADAYPERIOD_MORNING1,
+    UADAYPERIOD_MORNING2,
+    UADAYPERIOD_AFTERNOON1,
+    UADAYPERIOD_AFTERNOON2,
+    UADAYPERIOD_EVENING1,
+    UADAYPERIOD_EVENING2,
+    UADAYPERIOD_NIGHT1,
+    UADAYPERIOD_NIGHT2,
+    UADAYPERIOD_MIDNIGHT,   /* Should only get this for formatStyle TRUE */
+    UADAYPERIOD_NOON,       /* Should only get this for formatStyle TRUE */
+    UADAYPERIOD_UNKNOWN
+} UADayPeriod;
+
+/**
+ * Get the locale-specific day period for a particular time of day.
+ * This comes from the dayPeriod CLDR data in ICU.
+ *
+ * @param locale
+ *            The locale
+ * @param hour
+ *            Hour of day, in range 0..23.
+ * @param minute
+ *            Minute of the hour, in range 0..59. Currently does not affect dayPeriod
+ *            selection if formatStyle is FALSE.
+ * @param formatStyle
+ *            FALSE to get dayPeriods for selecting strings to be used "stand-alone"
+ *            without a particular time of day, e.g. "Good morning", "Good afternoon",
+ *            "Good evening".
+ *            TRUE to get dayPeriods for selecting strings to be used when formatting
+ *            a particular time of day, e.g. "12:00 noon", "3:00 PM".
+ * @param status
+ *            A pointer to a UErrorCode to receive any errors. In-out parameter; if
+ *            this indicates an error on input, the function will return immediately.
+ * @return
+ *            The UADayPeriod (possibly UADAYPERIOD_UNKNOWN).
+ * @draft Apple
+ */
+U_DRAFT UADayPeriod U_EXPORT2
+uacal_getDayPeriod( const char* locale,
+                    int32_t     hour,
+                    int32_t     minute,
+                    UBool       formatStyle,
+                    UErrorCode* status );
+
+#endif /* U_HIDE_DRAFT_API */

 
 #endif /* #if !UCONFIG_NO_FORMATTING */
 
 
 #endif /* #if !UCONFIG_NO_FORMATTING */