Class java.text.Format





All Packages Class Hierarchy This Package Previous Next Index


Class java.text.Format


java.lang.Object
|
+----java.text.Format



public abstract class Format
extends Object
implements Serializable, Cloneable

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 Strings (the
format method) and for parsing Strings 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

In addition, some subclasses may also choose to implement other
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.


See Also:
ParsePosition, FieldPosition, NumberFormat, DateFormat, MessageFormat








Format()







clone()
Creates a new object of the same class as this object.

format(Object)
Formats an object to produce a string.

format(Object, StringBuffer, FieldPosition)
Formats an object to produce a string.

parseObject(String)
Parses a string to produce an object.

parseObject(String, ParsePosition)
Parses a string to produce an object.







Format

public Format()






format

public final String format(Object obj)


Formats an object to produce a string.
Subclasses will override the StringBuffer version of format.


Parameters:
obj - The object to format
Returns:
Formatted string.
Throws: IllegalArgumentException
when the Format cannot format the
type of object.
See Also:
MessageFormat, format



format

public abstract StringBuffer format(Object obj,
StringBuffer toAppendTo,
FieldPosition pos)


Formats an object to produce a string.
Subclasses will implement for particular object, such as:

StringBuffer format (Number obj, StringBuffer toAppendTo)
Number parse (String str)

These general routines allow polymorphic parsing and
formatting for objects such as the MessageFormat.


Parameters:
obj - The object to format
toAppendTo - where the text is to be appended
status - On input: an alignment field, if desired.
On output: the offsets of the alignment field.
Returns:
the value passed in as toAppendTo (this allows chaining,
as with StringBuffer.append())
Throws: IllegalArgumentException
when the Format cannot format the
given object.
See Also:
MessageFormat, FieldPosition



parseObject

public abstract Object parseObject(String source,
ParsePosition status)


Parses a string to produce an object.
Subclasses will typically implement for particular object, such as:

String format (Number obj);
String format (long obj);
String format (double obj);
Number parse (String str);



Parameters:
ParsePosition - Input-Output parameter.
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.
Returns:
Object parsed from string. In case of error, returns null.
See Also:
ParsePosition



parseObject

public Object parseObject(String source) throws ParseException


Parses a string to produce an object.


Throws: ParseException
if the specified string is invalid.



clone

public Object clone()


Creates a new object of the same class as this object.


Overrides:
clone in class Object




All Packages Class Hierarchy This Package Previous Next Index

Submit a bug or feature - Version 1.1.7 of Java Platform API Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1995-1998 Sun Microsystems, Inc. 901 San Antonio Road,
Palo Alto, California, 94303, U.S.A. All Rights Reserved.