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