to top
Android APIs
public abstract class

Format

extends Object
implements Serializable Cloneable
java.lang.Object
   ↳ java.text.Format
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

The 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 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.

Summary

Nested Classes
class Format.Field Inner class used to represent Format attributes in the AttributedCharacterIterator that the formatToCharacterIterator() method returns in Format subclasses. 
Protected Constructors
Format()
Used by subclasses.
Public Methods
Object clone()
Returns a copy of this Format instance.
final 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.
[Expand]
Inherited Methods
From class java.lang.Object

Protected Constructors

protected Format ()

Since: API Level 1

Used by subclasses. This was public in Java 5.

Public Methods

public Object clone ()

Since: API Level 1

Returns a copy of this Format instance.

Returns
  • a shallow copy of this format.
See Also

public final String format (Object object)

Since: API Level 1

Formats the specified object using the rules of this format.

Parameters
object the object to format.
Returns
  • the formatted string.
Throws
IllegalArgumentException if the object cannot be formatted by this format.

public abstract StringBuffer format (Object object, StringBuffer buffer, FieldPosition field)

Since: API Level 1

Appends the specified object to the specified string buffer using the rules of this format.

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.

Parameters
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.
Returns
  • the string buffer.
Throws
IllegalArgumentException if the object cannot be formatted by this format.

public AttributedCharacterIterator formatToCharacterIterator (Object object)

Since: API Level 1

Formats the specified object using the rules of this format and returns an AttributedCharacterIterator with the formatted string and no attributes.

Subclasses should return an AttributedCharacterIterator with the appropriate attributes.

Parameters
object the object to format.
Returns
  • an AttributedCharacterIterator with the formatted object and attributes.
Throws
IllegalArgumentException if the object cannot be formatted by this format.

public Object parseObject (String string)

Since: API Level 1

Parses the specified string using the rules of this format.

Parameters
string the string to parse.
Returns
  • the object resulting from the parse.
Throws
ParseException if an error occurs during parsing.

public abstract Object parseObject (String string, ParsePosition position)

Since: API Level 1

Parses the specified string starting at the index specified by 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.

Parameters
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.
Returns
  • the object resulting from the parse or null if there is an error.