Base class for all formats. More...

#include <format.h>

Inheritance diagram for icu::Format:

Public Member Functions
virtual	~Format ()
	Destructor. More...

virtual bool	operator== (const Format &other) const =0
	Return true if the given Format objects are semantically equal. More...

bool	operator!= (const Format &other) const
	Return true if the given Format objects are not semantically equal. More...

virtual Format *	clone () const =0
	Clone this object polymorphically. More...

UnicodeString &	format (const Formattable &obj, UnicodeString &appendTo, UErrorCode &status) const
	Formats an object to produce a string. More...

virtual UnicodeString &	format (const Formattable &obj, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const =0
	Format an object to produce a string. More...

virtual UnicodeString &	format (const Formattable &obj, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
	Format an object to produce a string. More...

virtual void	parseObject (const UnicodeString &source, Formattable &result, ParsePosition &parse_pos) const =0
	Parse a string to produce an object. More...

void	parseObject (const UnicodeString &source, Formattable &result, UErrorCode &status) const
	Parses a string to produce an object. More...

Locale	getLocale (ULocDataLocaleType type, UErrorCode &status) const
	Get the locale for this format object. More...

const char *	getLocaleID (ULocDataLocaleType type, UErrorCode &status) const
	Get the locale for this format object. More...

Public Member Functions inherited from icu::UObject
virtual	~UObject ()
	Destructor. More...

virtual UClassID	getDynamicClassID () const
	ICU4C "poor man's RTTI", returns a UClassID for the actual ICU class. More...

Protected Member Functions
void	setLocaleIDs (const char valid, const char actual)

	Format ()
	Default constructor for subclass use only. More...

	Format (const Format &)

Format &	operator= (const Format &)

Static Protected Member Functions
static void	syntaxError (const UnicodeString &pattern, int32_t pos, UParseError &parseError)
	Simple function for initializing a UParseError from a UnicodeString. More...

Detailed Description

Base class for all formats.

This is an abstract base class which specifies the protocol for classes which convert other objects or values, such as numeric values and dates, and their string representations. In some cases these representations may be localized or contain localized characters or strings. For example, a numeric formatter such as DecimalFormat may convert a numeric value such as 12345 to the string "$12,345". It may also parse the string back into a numeric value. A date and time formatter like SimpleDateFormat may represent a specific date, encoded numerically, as a string such as "Wednesday, February 26, 1997 AD".

Many of the concrete subclasses of Format employ the notion of a pattern. A pattern is a string representation of the rules which govern the interconversion between values and strings. For example, a DecimalFormat object may be associated with the pattern "$#,##0.00;($#,##0.00)", which is a common US English format for currency values, yielding strings such as "$1,234.45" for 1234.45, and "($987.65)" for 987.6543. The specific syntax of a pattern is defined by each subclass.

Even though many subclasses use patterns, the notion of a pattern is not inherent to Format classes in general, and is not part of the explicit base class protocol.

Two complex formatting classes bear mentioning. These are MessageFormat and ChoiceFormat. ChoiceFormat is a subclass of NumberFormat which allows the user to format different number ranges as strings. For instance, 0 may be represented as "no files", 1 as "one file", and any number greater than 1 as "many files". MessageFormat is a formatter which utilizes other Format objects to format a string containing with multiple values. For instance, A MessageFormat object might produce the string "There are no files on the disk MyDisk on February 27, 1997." given the arguments 0, "MyDisk", and the date value of 2/27/97. See the ChoiceFormat and MessageFormat headers for further information.

If formatting is unsuccessful, a failing UErrorCode is returned when the Format cannot format the type of object, otherwise if there is something illformed about the the Unicode replacement character 0xFFFD is returned.

If there is no match when parsing, a parse failure UErrorCode is returned for methods which take no ParsePosition. For the method that takes a ParsePosition, the index parameter is left unchanged.

User subclasses are not supported. While clients may write subclasses, such code will not necessarily work and will not be guaranteed to work stably from release to release.

Definition at line 98 of file format.h.

Constructor & Destructor Documentation

◆ ~Format()

virtual icu::Format::~Format ( )

virtual

Destructor.

Stable:: ICU 2.4

◆ Format() [1/2]

icu::Format::Format ( )

protected

Default constructor for subclass use only.

Does nothing.

Stable:: ICU 2.0

◆ Format() [2/2]

icu::Format::Format ( const Format & )

protected

Stable:: ICU 2.0

Member Function Documentation

◆ clone()

virtual Format * icu::Format::clone ( ) const

pure virtual

Clone this object polymorphically.

The caller is responsible for deleting the result when done.

Returns: A copy of the object

Stable:: ICU 2.0

Implemented in icu::ChoiceFormat, icu::DateIntervalFormat, icu::MeasureFormat, icu::MessageFormat, icu::PluralFormat, icu::RuleBasedNumberFormat, icu::SelectFormat, icu::SimpleDateFormat, icu::TimeUnitFormat, icu::TimeZoneFormat, icu::DateFormat, icu::NumberFormat, icu::CompactDecimalFormat, and icu::DecimalFormat.

◆ format() [1/3]

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

pure virtual

Format an object to produce a string.

This is a pure virtual method which subclasses must implement. 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.
pos	On input: an alignment field, if desired. On output: the offsets of the alignment field.
status	Output param filled with success/failure status.

Returns: Reference to 'appendTo' parameter.

Stable:: ICU 2.0

Implemented in icu::DateIntervalFormat, icu::RuleBasedNumberFormat, icu::SimpleDateFormat, icu::ChoiceFormat, icu::DateFormat, icu::DecimalFormat, icu::MeasureFormat, icu::MessageFormat, icu::NumberFormat, icu::PluralFormat, icu::RuleBasedNumberFormat, icu::SelectFormat, icu::SimpleDateFormat, icu::TimeZoneFormat, icu::DateFormat, icu::DateIntervalFormat, icu::MeasureFormat, icu::MessageFormat, icu::NumberFormat, icu::PluralFormat, icu::SelectFormat, and icu::TimeZoneFormat.

◆ 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 in icu::DateFormat, icu::DateIntervalFormat, icu::MeasureFormat, icu::MessageFormat, icu::NumberFormat, icu::PluralFormat, icu::RuleBasedNumberFormat, icu::SelectFormat, icu::SimpleDateFormat, icu::TimeZoneFormat, icu::ChoiceFormat, icu::DateFormat, icu::DecimalFormat, icu::NumberFormat, icu::RuleBasedNumberFormat, and icu::SimpleDateFormat.

◆ 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

◆ getLocale()

Locale icu::Format::getLocale	(	ULocDataLocaleType	type,
		UErrorCode &	status
	)		const

Get the locale for this format object.

You can choose between valid and actual locale.

Parameters

type	type of the locale we're looking for (valid or actual)
status	error code for the operation

Returns: the locale

Stable:: ICU 2.8

◆ getLocaleID()

const char * icu::Format::getLocaleID	(	ULocDataLocaleType	type,
		UErrorCode &	status
	)		const

Get the locale for this format object.

You can choose between valid and actual locale.

Parameters

type	type of the locale we're looking for (valid or actual)
status	error code for the operation

Returns: the locale

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

◆ operator!=()

bool icu::Format::operator!= ( const Format & other ) const

inline

Return true if the given Format objects are not semantically equal.

Parameters

other the object to be compared with.

Returns: Return true if the given Format objects are not semantically.

Stable:: ICU 2.0

Definition at line 123 of file format.h.

References icu::operator==().

◆ operator=()

Format & icu::Format::operator= ( const Format & )

protected

Stable:: ICU 2.0

◆ operator==()

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

pure virtual

Return true if the given Format objects are semantically equal.

Objects of different subclasses are considered unequal.

Parameters

other the object to be compared with.

Returns: Return true if the given Format objects are semantically equal. Objects of different subclasses are considered unequal.

Stable:: ICU 2.0

Implemented in icu::DateFormat, icu::ChoiceFormat, icu::DateIntervalFormat, icu::MeasureFormat, icu::MessageFormat, icu::NumberFormat, icu::PluralFormat, icu::RuleBasedNumberFormat, icu::SelectFormat, icu::SimpleDateFormat, icu::TimeZoneFormat, and icu::DecimalFormat.

◆ parseObject() [1/2]

virtual void icu::Format::parseObject	(	const UnicodeString &	source,
		Formattable &	result,
		ParsePosition &	parse_pos
	)		const

pure virtual

Parse a string to produce an object.

This is a pure virtual method which subclasses must implement. This method allows polymorphic parsing of strings into Formattable objects.

Before calling, set parse_pos.index to the offset you want to start parsing at in the source. After calling, parse_pos.index is the end of the text you parsed. If error occurs, index is unchanged.

When parsing, leading whitespace is discarded (with successful parse), while trailing whitespace is left as is.

Example:

Parsing "_12_xy" (where _ represents a space) for a number, with index == 0 will result in the number 12, with parse_pos.index updated to 3 (just before the second space). Parsing a second time will result in a failing UErrorCode since "xy" is not a number, and leave index at 3.

Subclasses will typically supply specific parse methods that return different types of values. Since methods can't overload on return types, these will typically be named "parse", while this polymorphic method will always be called parseObject. Any parse method that does not take a parse_pos should set status to an error value when no text in the required format is at the start position.

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.
parse_pos	The position to start parsing at. Upon return this param is set to the position after the last character successfully parsed. If the source is not parsed successfully, this param will remain unchanged.

Stable:: ICU 2.0

Implemented in icu::MeasureFormat, icu::DateFormat, icu::DateIntervalFormat, icu::NumberFormat, icu::PluralFormat, icu::SelectFormat, icu::TimeZoneFormat, icu::MeasureFormat, icu::MessageFormat, and 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

◆ setLocaleIDs()

void icu::Format::setLocaleIDs	(	const char *	valid,
		const char *	actual
	)

protected

Stable:: ICU 2.8

◆ syntaxError()

static void icu::Format::syntaxError	(	const UnicodeString &	pattern,
		int32_t	pos,
		UParseError &	parseError
	)

staticprotected

Simple function for initializing a UParseError from a UnicodeString.

Parameters

pattern	The pattern to copy into the parseError
pos	The position in pattern where the error occurred
parseError	The UParseError object to fill in

Stable:: ICU 2.4

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

format.h

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~Format()

◆ Format() [1/2]

◆ Format() [2/2]

Member Function Documentation

◆ clone()

◆ format() [1/3]

◆ format() [2/3]

◆ format() [3/3]

◆ getLocale()

◆ getLocaleID()

◆ operator!=()

◆ operator=()

◆ operator==()

◆ parseObject() [1/2]

◆ parseObject() [2/2]

◆ setLocaleIDs()

◆ syntaxError()