Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.3.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## java.text
Class Format

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

All Implemented Interfaces:
  Cloneable, Serializable

Direct Known Subclasses:
  DateFormat, MessageFormat, NumberFormat

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 `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 Java 2 platform provides three concrete subclasses of `Format`-- `DateFormat`, `MessageFormat`, and `NumberFormat`--for formatting dates, messages, and numbers, respectively.

Concrete subclasses must implement these two methods:

1. `format(Object obj, StringBuffer toAppendTo, FieldPosition pos)`
2. `parseObject (String source, ParsePosition pos)`

Most subclasses will also implement the following two methods:

1. `getInstance` for getting a useful format object appropriate for the current locale
2. `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`, Serialized Form

Constructor Summary
`Format()`

Method Summary
`Object` | `clone()` Overrides Cloneable
`String` | `format(Object obj)` Formats an object to produce a string.
`abstract StringBuffer` | `format(Object obj, StringBuffer toAppendTo, FieldPosition pos)` Formats an object to produce a string.
`Object` | `parseObject(String source)` Parses a string to produce an object.
`abstract Object` | `parseObject(String source, ParsePosition status)` Parses a string to produce an object.

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### Format

    public Format()

Method Detail

### 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(Object, StringBuffer, FieldPosition)`

### 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
    `pos` - 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:
    `status` - 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()

  Overrides Cloneable
  Overrides:
    `clone` in class `Object`
  Following copied from class: `java.lang.Object`
  Returns:
    a clone of this instance.
  Throws:
    `CloneNotSupportedException` - if the object's class does not support the `Cloneable` interface. Subclasses that override the `clone` method can also throw this exception to indicate that an instance cannot be cloned.
    `OutOfMemoryError` - if there is not enough memory.
  See Also:
    `Cloneable`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.3.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2001 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.