Package java.text

Class Format

java.lang.Object
java.text.Format
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
DateFormat, MessageFormat, NumberFormat
public abstract class Format
extends Object
implements Serializable, Cloneable
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.

See Also:
Serialized Form

  • Constructor Details

    • Format

      protected Format()
      Used by subclasses. This was public in Java 5.

  • Method Details

    • clone

      public Object clone()
      Returns a copy of this Format instance.
      Overrides:
      clone in class Object
      Returns:
      a shallow copy of this format.
      See Also:
      Cloneable

    • format

      public final String format​(Object object)
      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.

    • format

      public abstract StringBuffer format​(Object object, StringBuffer buffer, FieldPosition field)
      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.

    • formatToCharacterIterator

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

      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.

    • parseObject

      public Object parseObject​(String string) throws ParseException
      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.

    • parseObject

      public abstract Object parseObject​(String string, ParsePosition position)
      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.