class Format
Defined at line 99 of file ../../third_party/icu/latest/source/i18n/unicode/format.h
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".
<P
>
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.
<P
>
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.
<P
>
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.
<P
>
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.
<P
>
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.
<P
>
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.
Public Methods
bool operator!= (const Format & other)Return true if the given Format objects are not semantically
equal.
Parameters
Returns
Return true if the given Format objects are not semantically.
ICU 2.0
Defined at line 124 of file ../../third_party/icu/latest/source/i18n/unicode/format.h
void ~Format ()Destructor
ICU 2.4
bool operator== (const Format & other)Return true if the given Format objects are semantically equal.
Objects of different subclasses are considered unequal.
Parameters
Returns
Return true if the given Format objects are semantically equal.
Objects of different subclasses are considered unequal.
ICU 2.0
Format * clone ()Clone this object polymorphically. The caller is responsible
for deleting the result when done.
Returns
A copy of the object
ICU 2.0
UnicodeString & format (const Formattable & obj, UnicodeString & appendTo, UErrorCode & status)Formats an object to produce a string.
Parameters
Returns
Reference to 'appendTo' parameter.
ICU 2.0
UnicodeString & format (const Formattable & obj, UnicodeString & appendTo, FieldPosition & pos, UErrorCode & status)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
Returns
Reference to 'appendTo' parameter.
ICU 2.0
UnicodeString & format (const Formattable & obj, UnicodeString & appendTo, FieldPositionIterator * posIter, UErrorCode & status)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
Returns
Reference to 'appendTo' parameter.
ICU 4.4
void parseObject (const UnicodeString & source, Formattable & result, ParsePosition & parse_pos)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.
<P
>
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.
<P
>
When parsing, leading whitespace is discarded (with successful
parse), while trailing whitespace is left as is.
<P
>
Example:
<P
>
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.
<P
>
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
void parseObject (const UnicodeString & source, Formattable & result, UErrorCode & status)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
Locale getLocale (ULocDataLocaleType type, UErrorCode & status)Get the locale for this format object. You can choose between valid and actual locale.
Parameters
Returns
the locale
ICU 2.8
const char * getLocaleID (ULocDataLocaleType type, UErrorCode & status)Get the locale for this format object. You can choose between valid and actual locale.
Parameters
Returns
the locale
Protected Methods
void setLocaleIDs (const char * valid, const char * actual)ICU 2.8
void Format ()Default constructor for subclass use only. Does nothing.
ICU 2.0
void Format (const Format & )ICU 2.0
Format & operator= (const Format & )ICU 2.0
void syntaxError (const UnicodeString & pattern, int32_t pos, UParseError & parseError)Simple function for initializing a UParseError from a UnicodeString.