站内搜索: 请输入搜索关键词
当前页面: 在线文档首页 > JDK 5 Documentation v1.2.2, Java 2 SDK 英文文档

Java(TM) 2 Platform, Standard Edition, v1.2.2 API Specification: Class Format - JDK 5 Documentation v1.2.2, Java 2 SDK 英文文档

Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
JavaTM 2 Platform
Standard Edition
 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
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 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:

  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()
          Creates and returns a copy of this object.
 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()
Description copied from class: Object
Creates and returns a copy of this object. The precise meaning of "copy" may depend on the class of the object. The general intent is that, for any object x, the expression: 
 x.clone() != x
will be true, and that the expression: 
 x.clone().getClass() == x.getClass()
will be true, but these are not absolute requirements. While it is typically the case that: 
 x.clone().equals(x)
will be true, this is not an absolute requirement. Copying an object will typically entail creating a new instance of its class, but it also may require copying of internal data structures as well. No constructors are called.

The method clone for class Object performs a specific cloning operation. First, if the class of this object does not implement the interface Cloneable, then a CloneNotSupportedException is thrown. Note that all arrays are considered to implement the interface Cloneable. Otherwise, this method creates a new instance of the class of this object and initializes all its fields with exactly the contents of the corresponding fields of this object, as if by assignment; the contents of the fields are not themselves cloned. Thus, this method performs a "shallow copy" of this object, not a "deep copy" operation.

The class Object does not itself implement the interface Cloneable, so calling the clone method on an object whose class is Object will result in throwing an exception at run time. The clone method is implemented by the class Object as a convenient, general utility for subclasses that implement the interface Cloneable, possibly also overriding the clone method, in which case the overriding definition can refer to this utility definition by the call: 

 super.clone()
Overrides:
clone in class Object
Tags copied from class: 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
Standard Edition
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD
Submit a bug or feature
Java, Java 2D, and JDBC are a trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1999 Sun Microsystems, Inc. 901 San Antonio Road,
Palo Alto, California, 94303, U.S.A. All Rights Reserved.