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