measfmt.h (11688B)
1 // © 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 ********************************************************************** 5 * Copyright (c) 2004-2016, International Business Machines 6 * Corporation and others. All Rights Reserved. 7 ********************************************************************** 8 * Author: Alan Liu 9 * Created: April 20, 2004 10 * Since: ICU 3.0 11 ********************************************************************** 12 */ 13 #ifndef MEASUREFORMAT_H 14 #define MEASUREFORMAT_H 15 16 #include "unicode/utypes.h" 17 18 #if U_SHOW_CPLUSPLUS_API 19 20 #if !UCONFIG_NO_FORMATTING 21 22 #include "unicode/format.h" 23 #include "unicode/udat.h" 24 25 /** 26 * \file 27 * \brief C++ API: Compatibility APIs for measure formatting. 28 */ 29 30 /** 31 * Constants for various widths. 32 * There are 4 widths: Wide, Short, Narrow, Numeric. 33 * For example, for English, when formatting "3 hours" 34 * Wide is "3 hours"; short is "3 hrs"; narrow is "3h"; 35 * formatting "3 hours 17 minutes" as numeric give "3:17" 36 * @stable ICU 53 37 */ 38 enum UMeasureFormatWidth { 39 40 // Wide, short, and narrow must be first and in this order. 41 /** 42 * Spell out measure units. 43 * @stable ICU 53 44 */ 45 UMEASFMT_WIDTH_WIDE, 46 47 /** 48 * Abbreviate measure units. 49 * @stable ICU 53 50 */ 51 UMEASFMT_WIDTH_SHORT, 52 53 /** 54 * Use symbols for measure units when possible. 55 * @stable ICU 53 56 */ 57 UMEASFMT_WIDTH_NARROW, 58 59 /** 60 * Completely omit measure units when possible. For example, format 61 * '5 hours, 37 minutes' as '5:37' 62 * @stable ICU 53 63 */ 64 UMEASFMT_WIDTH_NUMERIC, 65 66 #ifndef U_HIDE_DEPRECATED_API 67 /** 68 * One more than the highest normal UMeasureFormatWidth value. 69 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. 70 */ 71 UMEASFMT_WIDTH_COUNT = 4 72 #endif // U_HIDE_DEPRECATED_API 73 }; 74 /** @stable ICU 53 */ 75 typedef enum UMeasureFormatWidth UMeasureFormatWidth; 76 77 U_NAMESPACE_BEGIN 78 79 class Measure; 80 class MeasureUnit; 81 class NumberFormat; 82 class PluralRules; 83 class MeasureFormatCacheData; 84 class SharedNumberFormat; 85 class SharedPluralRules; 86 class QuantityFormatter; 87 class SimpleFormatter; 88 class ListFormatter; 89 class DateFormat; 90 91 /** 92 * <p><strong>IMPORTANT:</strong> New users are strongly encouraged to see if 93 * numberformatter.h fits their use case. Although not deprecated, this header 94 * is provided for backwards compatibility only, and has much more limited 95 * capabilities. 96 * 97 * @see Format 98 * @author Alan Liu 99 * @stable ICU 3.0 100 */ 101 class U_I18N_API MeasureFormat : public Format { 102 public: 103 using Format::parseObject; 104 using Format::format; 105 106 /** 107 * Constructor. 108 * <p> 109 * <strong>NOTE:</strong> New users are strongly encouraged to use 110 * {@link icu::number::NumberFormatter} instead of NumberFormat. 111 * @stable ICU 53 112 */ 113 MeasureFormat( 114 const Locale &locale, UMeasureFormatWidth width, UErrorCode &status); 115 116 /** 117 * Constructor. 118 * <p> 119 * <strong>NOTE:</strong> New users are strongly encouraged to use 120 * {@link icu::number::NumberFormatter} instead of NumberFormat. 121 * @stable ICU 53 122 */ 123 MeasureFormat( 124 const Locale &locale, 125 UMeasureFormatWidth width, 126 NumberFormat *nfToAdopt, 127 UErrorCode &status); 128 129 /** 130 * Copy constructor. 131 * @stable ICU 3.0 132 */ 133 MeasureFormat(const MeasureFormat &other); 134 135 /** 136 * Assignment operator. 137 * @stable ICU 3.0 138 */ 139 MeasureFormat &operator=(const MeasureFormat &rhs); 140 141 /** 142 * Destructor. 143 * @stable ICU 3.0 144 */ 145 virtual ~MeasureFormat(); 146 147 /** 148 * Return true if given Format objects are semantically equal. 149 * @stable ICU 53 150 */ 151 virtual bool operator==(const Format &other) const override; 152 153 /** 154 * Clones this object polymorphically. 155 * @stable ICU 53 156 */ 157 virtual MeasureFormat *clone() const override; 158 159 /** 160 * Formats object to produce a string. 161 * @stable ICU 53 162 */ 163 virtual UnicodeString &format( 164 const Formattable &obj, 165 UnicodeString &appendTo, 166 FieldPosition &pos, 167 UErrorCode &status) const override; 168 169 #ifndef U_FORCE_HIDE_DRAFT_API 170 /** 171 * Parse a string to produce an object. This implementation sets 172 * status to U_UNSUPPORTED_ERROR. 173 * 174 * @draft ICU 53 175 */ 176 virtual void parseObject( 177 const UnicodeString &source, 178 Formattable &reslt, 179 ParsePosition &pos) const override; 180 #endif // U_FORCE_HIDE_DRAFT_API 181 182 /** 183 * Formats measure objects to produce a string. An example of such a 184 * formatted string is 3 meters, 3.5 centimeters. Measure objects appear 185 * in the formatted string in the same order they appear in the "measures" 186 * array. The NumberFormat of this object is used only to format the amount 187 * of the very last measure. The other amounts are formatted with zero 188 * decimal places while rounding toward zero. 189 * @param measures array of measure objects. 190 * @param measureCount the number of measure objects. 191 * @param appendTo formatted string appended here. 192 * @param pos the field position. 193 * @param status the error. 194 * @return appendTo reference 195 * 196 * @stable ICU 53 197 */ 198 UnicodeString &formatMeasures( 199 const Measure *measures, 200 int32_t measureCount, 201 UnicodeString &appendTo, 202 FieldPosition &pos, 203 UErrorCode &status) const; 204 205 /** 206 * Formats a single measure per unit. An example of such a 207 * formatted string is 3.5 meters per second. 208 * @param measure The measure object. In above example, 3.5 meters. 209 * @param perUnit The per unit. In above example, it is 210 * `*%MeasureUnit::createSecond(status)`. 211 * @param appendTo formatted string appended here. 212 * @param pos the field position. 213 * @param status the error. 214 * @return appendTo reference 215 * 216 * @stable ICU 55 217 */ 218 UnicodeString &formatMeasurePerUnit( 219 const Measure &measure, 220 const MeasureUnit &perUnit, 221 UnicodeString &appendTo, 222 FieldPosition &pos, 223 UErrorCode &status) const; 224 225 /** 226 * Gets the display name of the specified {@link MeasureUnit} corresponding to the current 227 * locale and format width. 228 * @param unit The unit for which to get a display name. 229 * @param status the error. 230 * @return The display name in the locale and width specified in 231 * the MeasureFormat constructor, or null if there is no display name available 232 * for the specified unit. 233 * 234 * @stable ICU 58 235 */ 236 UnicodeString getUnitDisplayName(const MeasureUnit& unit, UErrorCode &status) const; 237 238 239 /** 240 * Return a formatter for CurrencyAmount objects in the given 241 * locale. 242 * <p> 243 * <strong>NOTE:</strong> New users are strongly encouraged to use 244 * {@link icu::number::NumberFormatter} instead of NumberFormat. 245 * @param locale desired locale 246 * @param ec input-output error code 247 * @return a formatter object, or nullptr upon error 248 * @stable ICU 3.0 249 */ 250 static MeasureFormat* U_EXPORT2 createCurrencyFormat(const Locale& locale, 251 UErrorCode& ec); 252 253 /** 254 * Return a formatter for CurrencyAmount objects in the default 255 * locale. 256 * <p> 257 * <strong>NOTE:</strong> New users are strongly encouraged to use 258 * {@link icu::number::NumberFormatter} instead of NumberFormat. 259 * @param ec input-output error code 260 * @return a formatter object, or nullptr upon error 261 * @stable ICU 3.0 262 */ 263 static MeasureFormat* U_EXPORT2 createCurrencyFormat(UErrorCode& ec); 264 265 /** 266 * Return the class ID for this class. This is useful only for comparing to 267 * a return value from getDynamicClassID(). For example: 268 * <pre> 269 * . Base* polymorphic_pointer = createPolymorphicObject(); 270 * . if (polymorphic_pointer->getDynamicClassID() == 271 * . erived::getStaticClassID()) ... 272 * </pre> 273 * @return The class ID for all objects of this class. 274 * @stable ICU 53 275 */ 276 static UClassID U_EXPORT2 getStaticClassID(); 277 278 /** 279 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This 280 * method is to implement a simple version of RTTI, since not all C++ 281 * compilers support genuine RTTI. Polymorphic operator==() and clone() 282 * methods call this method. 283 * 284 * @return The class ID for this object. All objects of a 285 * given class have the same class ID. Objects of 286 * other classes have different class IDs. 287 * @stable ICU 53 288 */ 289 virtual UClassID getDynamicClassID() const override; 290 291 protected: 292 /** 293 * Default constructor. 294 * @stable ICU 3.0 295 */ 296 MeasureFormat(); 297 298 #ifndef U_HIDE_INTERNAL_API 299 300 /** 301 * ICU use only. 302 * Initialize or change MeasureFormat class from subclass. 303 * @internal. 304 */ 305 void initMeasureFormat( 306 const Locale &locale, 307 UMeasureFormatWidth width, 308 NumberFormat *nfToAdopt, 309 UErrorCode &status); 310 /** 311 * ICU use only. 312 * Allows subclass to change locale. Note that this method also changes 313 * the NumberFormat object. Returns true if locale changed; false if no 314 * change was made. 315 * @internal. 316 */ 317 UBool setMeasureFormatLocale(const Locale &locale, UErrorCode &status); 318 319 /** 320 * ICU use only. 321 * Let subclass change NumberFormat. 322 * @internal. 323 */ 324 void adoptNumberFormat(NumberFormat *nfToAdopt, UErrorCode &status); 325 326 /** 327 * ICU use only. 328 * @internal. 329 */ 330 const NumberFormat &getNumberFormatInternal() const; 331 332 /** 333 * ICU use only. 334 * Always returns the short form currency formatter. 335 * @internal. 336 */ 337 const NumberFormat& getCurrencyFormatInternal() const; 338 339 /** 340 * ICU use only. 341 * @internal. 342 */ 343 const PluralRules &getPluralRules() const; 344 345 /** 346 * ICU use only. 347 * @internal. 348 */ 349 Locale getLocale(UErrorCode &status) const; 350 351 /** 352 * ICU use only. 353 * @internal. 354 */ 355 const char *getLocaleID(UErrorCode &status) const; 356 357 #endif /* U_HIDE_INTERNAL_API */ 358 359 private: 360 const MeasureFormatCacheData *cache; 361 const SharedNumberFormat *numberFormat; 362 const SharedPluralRules *pluralRules; 363 UMeasureFormatWidth fWidth; 364 365 // Declared outside of MeasureFormatSharedData because ListFormatter 366 // objects are relatively cheap to copy; therefore, they don't need to be 367 // shared across instances. 368 ListFormatter *listFormatter; 369 370 UnicodeString &formatMeasure( 371 const Measure &measure, 372 const NumberFormat &nf, 373 UnicodeString &appendTo, 374 FieldPosition &pos, 375 UErrorCode &status) const; 376 377 UnicodeString &formatMeasuresSlowTrack( 378 const Measure *measures, 379 int32_t measureCount, 380 UnicodeString& appendTo, 381 FieldPosition& pos, 382 UErrorCode& status) const; 383 384 UnicodeString &formatNumeric( 385 const Formattable *hms, // always length 3: [0] is hour; [1] is 386 // minute; [2] is second. 387 int32_t bitMap, // 1=hour set, 2=minute set, 4=second set 388 UnicodeString &appendTo, 389 UErrorCode &status) const; 390 }; 391 392 U_NAMESPACE_END 393 394 #endif // #if !UCONFIG_NO_FORMATTING 395 396 #endif /* U_SHOW_CPLUSPLUS_API */ 397 398 #endif // #ifndef MEASUREFORMAT_H