icuSources/i18n/unicode/uatimeunitformat.h

   1 /*
   2 *****************************************************************************************
   3 * Copyright (C) 2014 Apple Inc. All Rights Reserved.
   4 *****************************************************************************************
   5 */
   6
   7 #ifndef UATIMEUNITFORMAT_H
   8 #define UATIMEUNITFORMAT_H
   9
  10 #include "unicode/utypes.h"
  11
  12 #if !UCONFIG_NO_FORMATTING
  13 #ifndef U_HIDE_DRAFT_API
  14
  15 #include "unicode/localpointer.h"
  16 #include "unicode/unum.h"
  17
  18 /**
  19  * \file
  20  * \brief C API: Support functions for formatting time units or portions thereof.
  21  *
  22  * These are somewhat temporary Apple-only functions to support NSDateComponentsFormatter.
  23  */
  24
  25 /**
  26  * Opaque UATimeUnitFormat object for use in C programs.
  27  * @draft ICU 53
  28  */
  29 struct UATimeUnitFormat;
  30 typedef struct UATimeUnitFormat UATimeUnitFormat;  /**< C typedef for struct UATimeUnitFormat. @draft ICU 53 */
  31
  32 /**
  33  * TimeUnit format styles
  34  * @draft ICU 53
  35  */
  36 typedef enum UATimeUnitStyle {
  37     /**
  38      * full style, e.g. "1.0 minutes"
  39      * @draft ICU 53 */
  40     UATIMEUNITSTYLE_FULL,
  41     /**
  42      * abbreviated/short style, e.g. "1.0 min"
  43      * @draft ICU 53 */
  44     UATIMEUNITSTYLE_ABBREVIATED,
  45     /**
  46      * narrow style, e.g. "1.0 m"
  47      * @draft ICU 53 */
  48     UATIMEUNITSTYLE_NARROW,
  49     /**
  50      * shorter style,between abbreviated and narrow"
  51      * @draft ICU 57 */
  52     UATIMEUNITSTYLE_SHORTER,
  53     /** @draft ICU 53 */
  54     UATIMEUNITSTYLE_COUNT
  55 } UATimeUnitStyle;
  56
  57 /**
  58  * TimeUnit fields
  59  * @draft ICU 53
  60  */
  61 typedef enum UATimeUnitField {
  62     /** @draft ICU 53 */
  63     UATIMEUNITFIELD_YEAR,
  64     /** @draft ICU 53 */
  65     UATIMEUNITFIELD_MONTH,
  66     /** @draft ICU 53 */
  67     UATIMEUNITFIELD_DAY,
  68     /** @draft ICU 53 */
  69     UATIMEUNITFIELD_WEEK,
  70     /** @draft ICU 53 */
  71     UATIMEUNITFIELD_HOUR,
  72     /** @draft ICU 53 */
  73     UATIMEUNITFIELD_MINUTE,
  74     /** @draft ICU 53 */
  75     UATIMEUNITFIELD_SECOND,
  76     /** @draft ICU 63 */
  77     UATIMEUNITFIELD_MILLISECOND,
  78     /** @draft ICU 63 */
  79     UATIMEUNITFIELD_MICROSECOND,
  80     /** @draft ICU 63 */
  81     UATIMEUNITFIELD_NANOSECOND,
  82 #ifndef U_HIDE_DEPRECATED_API
  83      /** @deprecated The numeric value may change over time */
  84     UATIMEUNITFIELD_COUNT
  85 #endif  /* U_HIDE_DEPRECATED_API */
  86 } UATimeUnitField;
  87
  88 /**
  89  * Open a new UATimeUnitFormat object for a given locale using the specified style,
  90  * using the default decimal formatter.
  91  * @param locale
  92  *            The locale
  93  * @param style
  94  *            The style (width) - full, abbreviated, etc.
  95  * @param status
  96  *            A pointer to a UErrorCode to receive any errors.
  97  * @return
  98  *            A pointer to a UATimeUnitFormat object for the specified locale,
  99  *            or NULL if an error occurred.
 100  * @draft ICU 53
 101  */
 102 U_DRAFT UATimeUnitFormat* U_EXPORT2
 103 uatmufmt_open(const char*  locale,
 104               UATimeUnitStyle style,
 105               UErrorCode*  status);
 106
 107 /**
 108  * Open a new UATimeUnitFormat object for a given locale using the specified style,
 109  * along with the number formatter to use for the numeric part of the time unit,
 110  * e.g. "1 min", "1.0 min", etc.
 111 * @param locale
 112  *            The locale
 113  * @param style
 114  *            The style (width) - full, abbreviated, etc.
 115  * @param nfToAdopt
 116  *            A number formatter to set for this UATimeUnitFormat object (instead of
 117  *            the default decimal formatter). Ownership of this UNumberFormat object
 118  *            will pass to the UATimeUnitFormat object (the UATimeUnitFormat adopts the
 119  *            UNumberFormat), which becomes responsible for closing it. If the caller
 120  *            wishes to retain ownership of the UNumberFormat object, the caller must
 121  *            clone it (with unum_clone) and pass the clone to
 122  *            uatmufmt_openWithNumberFormat. May be NULL to use the default decimal
 123  *            formatter.
 124  * @param status
 125  *            A pointer to a UErrorCode to receive any errors.
 126  * @return
 127  *            A pointer to a UATimeUnitFormat object for the specified locale,
 128  *            or NULL if an error occurred.
 129  * @draft ICU 53
 130  */
 131 U_DRAFT UATimeUnitFormat* U_EXPORT2
 132 uatmufmt_openWithNumberFormat(const char*  locale,
 133                             UATimeUnitStyle style,
 134                             UNumberFormat*  nfToAdopt,
 135                             UErrorCode*  status);
 136
 137 /**
 138  * Close a UATimeUnitFormat object. Once closed it may no longer be used.
 139  * @param tufmt
 140  *            The UATimeUnitFormat object to close.
 141  * @draft ICU 53
 142  */
 143 U_DRAFT void U_EXPORT2
 144 uatmufmt_close(UATimeUnitFormat *tufmt);
 145
 146
 147 #if U_SHOW_CPLUSPLUS_API
 148
 149 U_NAMESPACE_BEGIN
 150
 151 /**
 152  * \class LocalUDateIntervalFormatPointer
 153  * "Smart pointer" class, closes a UATimeUnitFormat via uatmufmt_close().
 154  * For most methods see the LocalPointerBase base class.
 155  *
 156  * @see LocalPointerBase
 157  * @see LocalPointer
 158  * @draft ICU 53
 159  */
 160 U_DEFINE_LOCAL_OPEN_POINTER(LocalUATimeUnitFormatPointer, UATimeUnitFormat, uatmufmt_close);
 161
 162 U_NAMESPACE_END
 163
 164 #endif // U_SHOW_CPLUSPLUS_API
 165
 166
 167 /**
 168  * Set the number formatter to use for the numeric part of the time unit,
 169  * e.g. "1 min", "1.0 min", etc.
 170  * DO NOT USE - use uatmufmt_openWithNumberFormat instead, this will be
 171  * removed soon.
 172  * @param tufmt
 173  *            The UATimeUnitFormat object specifying the format conventions.
 174  * @param numfmt
 175  *            The number formatter to set for this UATimeUnitFormat object;
 176  *            uatmufmt_setNumberFormat clones this for its own use, so the
 177  *            caller retains ownership of the passed-in UNumberFormat object.
 178  * @param status
 179  *            A pointer to a UErrorCode to receive any errors.
 180  * @deprecated ICU 53, use uatmufmt_openWithNumberFormat
 181  */
 182 U_DEPRECATED void U_EXPORT2
 183 uatmufmt_setNumberFormat(UATimeUnitFormat* tufmt,
 184                         UNumberFormat*  numfmt,
 185                         UErrorCode*     status);
 186
 187 /**
 188  * Format a value like 1.0 and a field like UATIMEUNIT_MINUTE to e.g. "1.0 minutes".
 189  * @param tufmt
 190  *            The UATimeUnitFormat object specifying the format conventions.
 191  * @param value
 192  *            The numeric value to format
 193  * @param field
 194  *            The time field to format with the specified numeric value
 195  * @param result
 196  *            A pointer to a buffer to receive the formatted result.
 197  * @param resultCapacity
 198  *            The maximum size of result.
 199  * @param status
 200  *            A pointer to a UErrorCode to receive any errors. In case of error status,
 201  *            the contents of result are undefined.
 202  * @return
 203  *            The length of the formatted result; may be greater than resultCapacity,
 204  *            in which case an error is returned.
 205  * @draft ICU 53
 206  */
 207 U_DRAFT int32_t U_EXPORT2
 208 uatmufmt_format(const UATimeUnitFormat* tufmt,
 209                 double          value,
 210                 UATimeUnitField field,
 211                 UChar*          result,
 212                 int32_t         resultCapacity,
 213                 UErrorCode*     status);
 214
 215
 216 /**
 217  * Parse a single formatted time unit like "1.0 minutes" into a numeric value and unit type.
 218  * NOT CURRENTLY SUPPORTED, sets status to U_UNSUPPORTED_ERROR and returns 0.0.
 219  * @param tufmt
 220  *            The UATimeUnitFormat object specifying the format conventions.
 221  * @param text
 222  *            The text to parse
 223  * @param textLength
 224  *            The length of text, or -1 if null-terminated
 225  * @param parsePos
 226  *            A pointer to an offset index into text at which to begin parsing. On output,
 227  *            *parsePos will point after the last parsed character. This parameter may be
 228  *            NULL, in which case parsing begins at offset 0.
 229  * @param field
 230  *            A pointer to a UATimeUnitField to be set to the parsed firled type.
 231  * @param status
 232  *            A pointer to a UErrorCode to receive any errors.
 233  * @return
 234  *            The parsed double value.
 235  * @draft ICU 53
 236  */
 237 U_DRAFT double U_EXPORT2
 238 uatmufmt_parse( const UATimeUnitFormat* tufmt,
 239                 const UChar*    text,
 240                 int32_t         textLength,
 241                 int32_t*        parsePos,
 242                 UATimeUnitField* field,
 243                 UErrorCode*     status);
 244
 245
 246 /**
 247  * TimeUnit time duration positional pattern types
 248  * @draft ICU 53
 249  */
 250 typedef enum UATimeUnitTimePattern {
 251     /**
 252      * e.g. "h:mm"
 253      * @draft ICU 53 */
 254     UATIMEUNITTIMEPAT_HM,
 255     /**
 256      * e.g. "h:mm:ss"
 257      * @draft ICU 53 */
 258     UATIMEUNITTIMEPAT_HMS,
 259     /**
 260      * e.g. "m:ss"
 261      * @draft ICU 53 */
 262     UATIMEUNITTIMEPAT_MS,
 263     /** @draft ICU 53 */
 264     UATIMEUNITTIMEPAT_COUNT
 265 } UATimeUnitTimePattern;
 266
 267 /**
 268  * Get a localized pattern for positional duration style, e.g. "h:mm:ss".
 269  * This comes from the durationUnits CLDR data in ICU, e.g.
 270  *  durationUnits{
 271  *      hm{"h:mm"}
 272  *      hms{"h:mm:ss"}
 273  *      ms{"m:ss"}
 274  *  }
 275  * For usage see CLDR documentation on durationUnit under
 276  * <a href="http://www.unicode.org/reports/tr35/tr35-general.html#Unit_Elements">Unit Elements</a>.
 277  *
 278  * @param locale
 279  *            The locale
 280  * @param type
 281  *            The type of time pattern to get (hm, hms, ms)
 282  * @param result
 283  *            A pointer to a buffer to receive the formatted result.
 284  * @param resultCapacity
 285  *            The maximum size of result.
 286  * @param status
 287  *            A pointer to a UErrorCode to receive any errors. In case of error status,
 288  *            the contents of result are undefined.
 289  * @return
 290  *            The length of the formatted result; may be greater than resultCapacity,
 291  *            in which case an error is returned.
 292  * @draft ICU 53
 293  */
 294 U_DRAFT int32_t U_EXPORT2
 295 uatmufmt_getTimePattern(const char*     locale,
 296                         UATimeUnitTimePattern type,
 297                         UChar*          result,
 298                         int32_t         resultCapacity,
 299                         UErrorCode*     status);
 300
 301
 302 /**
 303  * TimeUnit list pattern types
 304  * @draft ICU 53
 305  */
 306 typedef enum UATimeUnitListPattern {
 307     /**
 308      * for two only, e.g. "{0} and {1}"
 309      * @draft ICU 53 */
 310     UATIMEUNITLISTPAT_TWO_ONLY,
 311     /**
 312      * for end of list with 3 or more, e.g. "{0}, and {1}"
 313      * @draft ICU 53 */
 314     UATIMEUNITLISTPAT_END_PIECE,
 315     /**
 316      * for middle of list with 3 or more, e.g. "{0}, {1}"
 317      * @draft ICU 53 */
 318     UATIMEUNITLISTPAT_MIDDLE_PIECE,
 319     /**
 320      * for start of list with 3 or more, e.g. "{0}, {1}"
 321      * @draft ICU 53 */
 322     UATIMEUNITLISTPAT_START_PIECE,
 323     /** @draft ICU 53 */
 324     UATIMEUNITLISTPAT_COUNT
 325 } UATimeUnitListPattern;
 326
 327 /**
 328  * Get a localized pattern for combining units in a list, e.g. "3 min, 42 sec".
 329  * This comes from the listPattern/unit* CLDR data in ICU, e.g.
 330  *  listPattern{
 331  *      unit{
 332  *          .. use short if not present
 333  *      }
 334  *      unit-short{
 335  *          2{"{0}, {1}"}
 336  *          end{"{0}, {1}"}
 337  *          middle{"{0}, {1}"}
 338  *          start{"{0}, {1}"}
 339  *      }
 340  *      unit-narrow{
 341  *          .. use short if not present
 342  *      }
 343  *  }
 344  * For usage see CLDR documentation on
 345  * <a href="http://www.unicode.org/reports/tr35/tr35-general.html#ListPatterns">List Patterns</a>.
 346  *
 347  * @param locale
 348  *            The locale
 349  * @param style
 350  *            The style (width) - full, abbreviated, etc.
 351  * @param type
 352  *            The type of list pattern to get (for two items, end part for >= 3 items, etc.)
 353  * @param result
 354  *            A pointer to a buffer to receive the formatted result.
 355  * @param resultCapacity
 356  *            The maximum size of result.
 357  * @param status
 358  *            A pointer to a UErrorCode to receive any errors. In case of error status,
 359  *            the contents of result are undefined.
 360  * @return
 361  *            The length of the formatted result; may be greater than resultCapacity,
 362  *            in which case an error is returned.
 363  * @draft ICU 53
 364  */
 365 U_DRAFT int32_t U_EXPORT2
 366 uatmufmt_getListPattern(const char*     locale,
 367                         UATimeUnitStyle style,
 368                         UATimeUnitListPattern type,
 369                         UChar*          result,
 370                         int32_t         resultCapacity,
 371                         UErrorCode*     status);
 372
 373
 374 #endif /* U_HIDE_DRAFT_API */
 375 #endif /* #if !UCONFIG_NO_FORMATTING */
 376
 377 #endif /* #ifndef UATIMEUNITFORMAT_H */