All Packages Class Hierarchy This Package Previous Next Index
Object | +----java.text.Format
Format
is an abstract base class for formatting locale-sensitive
information such as dates, messages, and numbers.
Format
defines the programming interface for formatting
locale-sensitive objects into String
s (the
format
method) and for parsing String
s back
into objects (the parseObject
method). Any String
formatted by format
is guaranteed to be parseable by
parseObject
.
If formatting is unsuccessful because the Format
object
cannot format the type of object specified, format
throws an
IllegalArgumentException
. Otherwise, if there is something
illformed about the object, format
returns the Unicode
replacement character \\uFFFD
.
If there is no match when parsing,
parseObject(String)
throws a ParseException
,
and parseObject(String, ParsePosition)
leaves the
ParsePosition
index
member unchanged and
returns null
.
Subclassing:
The JDK provides three concrete subclasses of Format
--
DateFormat
, MessageFormat
, and
NumberFormat
--for formatting dates, messages, and numbers,
respectively.
Concrete subclasses must implement these two methods:
format(Object obj, StringBuffer toAppendTo, FieldPosition pos)
parseObject (String source, ParsePosition pos)
Most subclasses will also implement the following two methods:
getInstance
for getting a useful format object appropriate
for the current locale
getInstance(Locale)
for getting a useful format
object appropriate for the specified locale
getXxxxInstance
methods for more specialized control. For
example, the NumberFormat
class provides
getPercentInstance
and getCurrencyInstance
methods for getting specialized number formatters.
Subclasses of Format
that allow programmers to create objects
for locales (with getInstance(Locale)
for example)
must also implement the following class method:
public static Locale[] getAvailableLocales()
And finally subclasses may define a set of constants to identify the various
fields in the formatted output. These constants are used to create a FieldPosition
object which identifies what information is contained in the field and its
position in the formatted result. These constants should be named
item_FIELD
where item
identifies
the field. For examples of these constants, see ERA_FIELD
and its
friends in DateFormat
.
public Format()
public java.lang.Object clone()
public final java.lang.String format(Object obj)
Subclasses will override the StringBuffer version of format.
public abstract java.lang.StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos)
StringBuffer format (Number obj, StringBuffer toAppendTo) Number parse (String str)These general routines allow polymorphic parsing and formatting for objects such as the MessageFormat.
public abstract java.lang.Object parseObject(String source, ParsePosition status)
String format (Number obj); String format (long obj); String format (double obj); Number parse (String str);
Before calling, set status.index to the offset you want to start parsing at in the source. After calling, status.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 status.index updated to 3 (just before the second space). Parsing a second time will result in a ParseException 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 status should throw ParseException when no text in the required format is at the start position.
public java.lang.Object parseObject(String source) throws ParseException
All Packages Class Hierarchy This Package Previous Next Index