ICU 76.1: icu::MeasureFormat Class Reference

ICU 76.1 76.1

Public Member Functions | Static Public Member Functions | Protected Member Functions
icu::MeasureFormat Class Reference

`#include <measfmt.h>`

Inheritance diagram for icu::MeasureFormat:

## Public Member Functions
| MeasureFormat (const Locale &locale, UMeasureFormatWidth width, UErrorCode &status)
| Constructor.
| MeasureFormat (const Locale &locale, UMeasureFormatWidth width, NumberFormat *nfToAdopt, UErrorCode &status)
| Constructor.
| MeasureFormat (const MeasureFormat &other)
| Copy constructor.
MeasureFormat & | operator= (const MeasureFormat &rhs)
| Assignment operator.
virtual | ~MeasureFormat ()
| Destructor.
virtual bool | operator== (const Format &other) const override
| Return true if given Format objects are semantically equal.
virtual MeasureFormat * | clone () const override
| Clones this object polymorphically.
virtual UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const override
| Formats object to produce a string.
virtual void | parseObject (const UnicodeString &source, Formattable &reslt, ParsePosition &pos) const override
| Parse a string to produce an object.
UnicodeString & | formatMeasures (const Measure *measures, int32_t measureCount, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
| Formats measure objects to produce a string.
UnicodeString & | formatMeasurePerUnit (const Measure &measure, const MeasureUnit &perUnit, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
| Formats a single measure per unit.
UnicodeString | getUnitDisplayName (const MeasureUnit &unit, UErrorCode &status) const
| Gets the display name of the specified `MeasureUnit` corresponding to the current locale and format width.
virtual UClassID | getDynamicClassID () const override
| Returns a unique class ID POLYMORPHICALLY.
void | parseObject (const UnicodeString &source, Formattable &result, UErrorCode &status) const
| Parses a string to produce an object.
UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, UErrorCode &status) const
| Formats an object to produce a string.
virtual UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
| Format an object to produce a string.
Public Member Functions inherited from icu::Format
virtual | ~Format ()
| Destructor.
bool | operator!= (const Format &other) const
| Return true if the given Format objects are not semantically equal.
UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, UErrorCode &status) const
| Formats an object to produce a string.
void | parseObject (const UnicodeString &source, Formattable &result, UErrorCode &status) const
| Parses a string to produce an object.
Locale | getLocale (ULocDataLocaleType type, UErrorCode &status) const
| Get the locale for this format object.
const char * | getLocaleID (ULocDataLocaleType type, UErrorCode &status) const
| Get the locale for this format object.
Public Member Functions inherited from icu::UObject
virtual | ~UObject ()
| Destructor.

## Static Public Member Functions
static MeasureFormat * | createCurrencyFormat (const Locale &locale, UErrorCode &ec)
| Return a formatter for CurrencyAmount objects in the given locale.
static MeasureFormat * | createCurrencyFormat (UErrorCode &ec)
| Return a formatter for CurrencyAmount objects in the default locale.
static UClassID | getStaticClassID ()
| Return the class ID for this class.

## Protected Member Functions
| MeasureFormat ()
| Default constructor.
void | initMeasureFormat (const Locale &locale, UMeasureFormatWidth width, NumberFormat *nfToAdopt, UErrorCode &status)
| ICU use only.
UBool | setMeasureFormatLocale (const Locale &locale, UErrorCode &status)
| ICU use only.
void | adoptNumberFormat (NumberFormat *nfToAdopt, UErrorCode &status)
| ICU use only.
const NumberFormat & | getNumberFormatInternal () const
| ICU use only.
const NumberFormat & | getCurrencyFormatInternal () const
| ICU use only.
const PluralRules & | getPluralRules () const
| ICU use only.
Locale | getLocale (UErrorCode &status) const
| ICU use only.
const char * | getLocaleID (UErrorCode &status) const
| ICU use only.
Protected Member Functions inherited from icu::Format
void | setLocaleIDs (const char *valid, const char *actual)
| Format ()
| Default constructor for subclass use only.
| Format (const Format &)
Format & | operator= (const Format &)

## Additional Inherited Members
Static Protected Member Functions inherited from icu::Format
static void | syntaxError (const UnicodeString &pattern, int32_t pos, UParseError &parseError)
| Simple function for initializing a UParseError from a UnicodeString.

## Detailed Description

IMPORTANT: New users are strongly encouraged to see if numberformatter.h fits their use case. Although not deprecated, this header is provided for backwards compatibility only, and has much more limited capabilities.

See also
  Format

Author
  Alan Liu

Stable
  ICU 3.0

Definition at line 101 of file measfmt.h.

## Constructor & Destructor Documentation

## ◆ MeasureFormat() [1/4]

icu::MeasureFormat::MeasureFormat | ( | const Locale & | locale,
|  | UMeasureFormatWidth | width,
|  | UErrorCode & | status )

Constructor.

NOTE: New users are strongly encouraged to use `icu::number::NumberFormatter` instead of NumberFormat.

Stable
  ICU 53

## ◆ MeasureFormat() [2/4]

icu::MeasureFormat::MeasureFormat | ( | const Locale & | locale,
|  | UMeasureFormatWidth | width,
|  | NumberFormat * | nfToAdopt,
|  | UErrorCode & | status )

Constructor.

NOTE: New users are strongly encouraged to use `icu::number::NumberFormatter` instead of NumberFormat.

Stable
  ICU 53

## ◆ MeasureFormat() [3/4]

icu::MeasureFormat::MeasureFormat | ( | const MeasureFormat & | other | ) |

Copy constructor.

Stable
  ICU 3.0

## ◆ ~MeasureFormat()

virtual icu::MeasureFormat::~MeasureFormat | ( |  | ) |
| virtual

Destructor.

Stable
  ICU 3.0

## ◆ MeasureFormat() [4/4]

icu::MeasureFormat::MeasureFormat | ( |  | ) |
| protected

Default constructor.

Stable
  ICU 3.0

## Member Function Documentation

## ◆ adoptNumberFormat()

void icu::MeasureFormat::adoptNumberFormat | ( | NumberFormat * | nfToAdopt,
|  | UErrorCode & | status )
| protected

ICU use only.

Let subclass change NumberFormat.

Internal
  Do not use. This API is for internal use only..

## ◆ clone()

virtual MeasureFormat * icu::MeasureFormat::clone | ( |  | ) | const
| overridevirtual

Clones this object polymorphically.

Stable
  ICU 53

Implements icu::Format.

Reimplemented in icu::TimeUnitFormat.

## ◆ createCurrencyFormat() [1/2]

static MeasureFormat * icu::MeasureFormat::createCurrencyFormat | ( | const Locale & | locale,
|  | UErrorCode & | ec )
| static

Return a formatter for CurrencyAmount objects in the given locale.

NOTE: New users are strongly encouraged to use `icu::number::NumberFormatter` instead of NumberFormat.

Parameters

  locale | desired locale
  ec | input-output error code

Returns
  a formatter object, or nullptr upon error

Stable
  ICU 3.0

## ◆ createCurrencyFormat() [2/2]

static MeasureFormat * icu::MeasureFormat::createCurrencyFormat | ( | UErrorCode & | ec | ) |
| static

Return a formatter for CurrencyAmount objects in the default locale.

NOTE: New users are strongly encouraged to use `icu::number::NumberFormatter` instead of NumberFormat.

Parameters

  ec | input-output error code

Returns
  a formatter object, or nullptr upon error

Stable
  ICU 3.0

## ◆ format() [1/3]

virtual UnicodeString & icu::MeasureFormat::format | ( | const Formattable & | obj,
|  | UnicodeString & | appendTo,
|  | FieldPosition & | pos,
|  | UErrorCode & | status ) const
| overridevirtual

Formats object to produce a string.

Stable
  ICU 53

Implements icu::Format.

## ◆ format() [2/3]

virtual UnicodeString & icu::Format::format | ( | const Formattable & | obj,
|  | UnicodeString & | appendTo,
|  | FieldPositionIterator * | posIter,
|  | UErrorCode & | status ) const
| virtual

Format an object to produce a string.

Subclasses should override this method. This method allows polymorphic formatting of Formattable objects. If a subclass of Format receives a Formattable object type it doesn't handle (e.g., if a numeric Formattable is passed to a DateFormat object) then it returns a failing UErrorCode.

Parameters

  obj | The object to format.
  appendTo | Output parameter to receive result. Result is appended to existing contents.
  posIter | On return, can be used to iterate over positions of fields generated by this format call.
  status | Output param filled with success/failure status.

Returns
  Reference to 'appendTo' parameter.

Stable
  ICU 4.4

Reimplemented from icu::Format.

## ◆ format() [3/3]

UnicodeString & icu::Format::format | ( | const Formattable & | obj,
|  | UnicodeString & | appendTo,
|  | UErrorCode & | status ) const

Formats an object to produce a string.

Parameters

  obj | The object to format.
  appendTo | Output parameter to receive result. Result is appended to existing contents.
  status | Output parameter filled in with success or failure status.

Returns
  Reference to 'appendTo' parameter.

Stable
  ICU 2.0

## ◆ formatMeasurePerUnit()

UnicodeString & icu::MeasureFormat::formatMeasurePerUnit | ( | const Measure & | measure,
|  | const MeasureUnit & | perUnit,
|  | UnicodeString & | appendTo,
|  | FieldPosition & | pos,
|  | UErrorCode & | status ) const

Formats a single measure per unit.

An example of such a formatted string is 3.5 meters per second.

Parameters

  measure | The measure object. In above example, 3.5 meters.
  perUnit | The per unit. In above example, it is `*MeasureUnit::createSecond(status)`.
  appendTo | formatted string appended here.
  pos | the field position.
  status | the error.

Returns
  appendTo reference

Stable
  ICU 55

## ◆ formatMeasures()

UnicodeString & icu::MeasureFormat::formatMeasures | ( | const Measure * | measures,
|  | int32_t | measureCount,
|  | UnicodeString & | appendTo,
|  | FieldPosition & | pos,
|  | UErrorCode & | status ) const

Formats measure objects to produce a string.

An example of such a formatted string is 3 meters, 3.5 centimeters. Measure objects appear in the formatted string in the same order they appear in the "measures" array. The NumberFormat of this object is used only to format the amount of the very last measure. The other amounts are formatted with zero decimal places while rounding toward zero.

Parameters

  measures | array of measure objects.
  measureCount | the number of measure objects.
  appendTo | formatted string appended here.
  pos | the field position.
  status | the error.

Returns
  appendTo reference

Stable
  ICU 53

## ◆ getCurrencyFormatInternal()

const NumberFormat & icu::MeasureFormat::getCurrencyFormatInternal | ( |  | ) | const
| protected

ICU use only.

Always returns the short form currency formatter.

Internal
  Do not use. This API is for internal use only..

## ◆ getDynamicClassID()

virtual UClassID icu::MeasureFormat::getDynamicClassID | ( |  | ) | const
| overridevirtual

Returns a unique class ID POLYMORPHICALLY.

Pure virtual override. This method is to implement a simple version of RTTI, since not all C++ compilers support genuine RTTI. Polymorphic operator==() and clone() methods call this method.

Returns
  The class ID for this object. All objects of a given class have the same class ID. Objects of other classes have different class IDs.

Stable
  ICU 53

Reimplemented from icu::UObject.

Reimplemented in icu::TimeUnitFormat.

## ◆ getLocale()

Locale icu::MeasureFormat::getLocale | ( | UErrorCode & | status | ) | const
| protected

ICU use only.

Internal
  Do not use. This API is for internal use only..

## ◆ getLocaleID()

const char * icu::MeasureFormat::getLocaleID | ( | UErrorCode & | status | ) | const
| protected

ICU use only.

Internal
  Do not use. This API is for internal use only..

## ◆ getNumberFormatInternal()

const NumberFormat & icu::MeasureFormat::getNumberFormatInternal | ( |  | ) | const
| protected

ICU use only.

Internal
  Do not use. This API is for internal use only..

## ◆ getPluralRules()

const PluralRules & icu::MeasureFormat::getPluralRules | ( |  | ) | const
| protected

ICU use only.

Internal
  Do not use. This API is for internal use only..

## ◆ getStaticClassID()

static UClassID icu::MeasureFormat::getStaticClassID | ( |  | ) |
| static

Return the class ID for this class.

This is useful only for comparing to a return value from getDynamicClassID(). For example:

    .   Base* polymorphic_pointer = createPolymorphicObject();
    .   if (polymorphic_pointer->getDynamicClassID() ==
    .       erived::getStaticClassID()) ...

Returns
  The class ID for all objects of this class.

Stable
  ICU 53

## ◆ getUnitDisplayName()

UnicodeString icu::MeasureFormat::getUnitDisplayName | ( | const MeasureUnit & | unit,
|  | UErrorCode & | status ) const

Gets the display name of the specified `MeasureUnit` corresponding to the current locale and format width.

Parameters

  unit | The unit for which to get a display name.
  status | the error.

Returns
  The display name in the locale and width specified in the MeasureFormat constructor, or null if there is no display name available for the specified unit.

Stable
  ICU 58

## ◆ initMeasureFormat()

void icu::MeasureFormat::initMeasureFormat | ( | const Locale & | locale,
|  | UMeasureFormatWidth | width,
|  | NumberFormat * | nfToAdopt,
|  | UErrorCode & | status )
| protected

ICU use only.

Initialize or change MeasureFormat class from subclass.

Internal
  Do not use. This API is for internal use only..

## ◆ operator=()

MeasureFormat & icu::MeasureFormat::operator= | ( | const MeasureFormat & | rhs | ) |

Assignment operator.

Stable
  ICU 3.0

## ◆ operator==()

virtual bool icu::MeasureFormat::operator== | ( | const Format & | other | ) | const
| overridevirtual

Return true if given Format objects are semantically equal.

Stable
  ICU 53

Implements icu::Format.

## ◆ parseObject() [1/2]

virtual void icu::MeasureFormat::parseObject | ( | const UnicodeString & | source,
|  | Formattable & | reslt,
|  | ParsePosition & | pos ) const
| overridevirtual

Parse a string to produce an object.

This implementation sets status to U_UNSUPPORTED_ERROR.

Draft
  This API may be changed in the future versions and was introduced in ICU 53

Implements icu::Format.

Reimplemented in icu::TimeUnitFormat.

## ◆ parseObject() [2/2]

void icu::Format::parseObject | ( | const UnicodeString & | source,
|  | Formattable & | result,
|  | UErrorCode & | status ) const

Parses a string to produce an object.

This is a convenience method which calls the pure virtual parseObject() method, and returns a failure UErrorCode if the ParsePosition indicates failure.

Parameters

  source | The string to be parsed into an object.
  result | Formattable to be set to the parse result. If parse fails, return contents are undefined.
  status | Output param to be filled with success/failure result code.

Stable
  ICU 2.0

## ◆ setMeasureFormatLocale()

UBool icu::MeasureFormat::setMeasureFormatLocale | ( | const Locale & | locale,
|  | UErrorCode & | status )
| protected

ICU use only.

Allows subclass to change locale. Note that this method also changes the NumberFormat object. Returns true if locale changed; false if no change was made.

Internal
  Do not use. This API is for internal use only..

The documentation for this class was generated from the following file:

- i18n/unicode/measfmt.h