public abstract class Format extends Object implements Serializable, Cloneable
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
conversion 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 are worth mentioning: 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 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 descriptions for
further information.
| Modifier and Type | Class and Description |
|---|---|
static class |
Format.Field
Inner class used to represent
Format attributes in the
AttributedCharacterIterator that the
formatToCharacterIterator() method returns in Format
subclasses. |
| Modifier | Constructor and Description |
|---|---|
protected |
Format()
Used by subclasses.
|
| Modifier and Type | Method and Description |
|---|---|
Object |
clone()
Returns a copy of this
Format instance. |
String |
format(Object object)
Formats the specified object using the rules of this format.
|
abstract StringBuffer |
format(Object object,
StringBuffer buffer,
FieldPosition field)
Appends the specified object to the specified string buffer using the
rules of this format.
|
AttributedCharacterIterator |
formatToCharacterIterator(Object object)
Formats the specified object using the rules of this format and returns
an
AttributedCharacterIterator with the formatted string and no
attributes. |
Object |
parseObject(String string)
Parses the specified string using the rules of this format.
|
abstract Object |
parseObject(String string,
ParsePosition position)
Parses the specified string starting at the index specified by
position. |
public Object clone()
Format instance.public final String format(Object object)
object - the object to format.IllegalArgumentException - if the object cannot be formatted by this format.public abstract StringBuffer format(Object object, StringBuffer buffer, FieldPosition field)
field is an input/output parameter. If its field
member contains an enum value specifying a field on input, then its
beginIndex and endIndex members will be updated with the
text offset of the first occurrence of this field in the formatted text.
object - the object to format.buffer - the string buffer where the formatted string is appended to.field - on input: an optional alignment field; on output: the offsets
of the alignment field in the formatted text.IllegalArgumentException - if the object cannot be formatted by this format.public AttributedCharacterIterator formatToCharacterIterator(Object object)
AttributedCharacterIterator with the formatted string and no
attributes.
Subclasses should return an AttributedCharacterIterator with the
appropriate attributes.
object - the object to format.AttributedCharacterIterator with the formatted object
and attributes.IllegalArgumentException - if the object cannot be formatted by this format.public Object parseObject(String string) throws ParseException
string - the string to parse.ParseException - if an error occurs during parsing.public abstract Object parseObject(String string, ParsePosition position)
position. If the string is successfully parsed then the index of
the ParsePosition is updated to the index following the parsed
text. On error, the index is unchanged and the error index of
ParsePosition is set to the index where the error occurred.string - the string to parse.position - input/output parameter, specifies the start index in
string from where to start parsing. If parsing is
successful, it is updated with the index following the parsed
text; on error, the index is unchanged and the error index is
set to the index where the error occurred.null if there is
an error.