Format is an abstract base class for formatting locale-sensitive information such as dates, messages, numbers, and lists.

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

Generally, a format's parseObject method must be able to parse any string formatted by its format method. However, there may be exceptional cases where this is not possible. For example, a format method might create two adjacent integer numbers with no separator in between, and in this case the parseObject could not tell which digits belong to which number.

Subclassing

The Java Platform provides specialized subclasses of Format-- DateFormat, MessageFormat, NumberFormat, and ListFormat--for formatting dates, messages, numbers, and lists respectively.

Concrete subclasses must implement three methods:

format(Object obj, StringBuffer toAppendTo, FieldPosition pos)
formatToCharacterIterator(Object obj)
parseObject(String source, ParsePosition pos)

These general methods allow polymorphic parsing and formatting of objects and are used, for example, by MessageFormat. Subclasses often also provide additional format methods for specific input types as well as parse methods for specific result types. Any parse method that does not take a ParsePosition argument should throw ParseException when no text in the required format is at the beginning of the input text.

Most subclasses will also implement the following factory methods:

getInstance for getting a useful format object appropriate for the current locale
getInstance(Locale) for getting a useful format object appropriate for the specified locale

In addition, some subclasses may also 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()

Subclasses may also consider implementing leniency when parsing. The definition of leniency should be delegated to the subclass.

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.

Synchronization

Formats are generally not synchronized. It is recommended to create separate format instances for each thread. If multiple threads access a format concurrently, it must be synchronized externally.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static class	Format.Field Defines constants that are used as attribute keys in the `AttributedCharacterIterator` returned from `Format.formatToCharacterIterator` and as field identifiers in `FieldPosition`.
pack-priv static interface	Format.FieldDelegate FieldDelegate is notified by the various `Format` implementations as they are formatting the Objects.
pack-priv static interface	Format.StringBuf StringBuf is the minimal common interface of `StringBuffer` and `StringBuilder`.

Modifier and Type	Field and Description
private static final long	serialVersionUID

Access	Constructor and Description
protected	Format() Sole constructor.

Method Summary

Modifier and Type	Method and Description
public Object	Returns: a clone of this instance. clone() Overrides java.lang.Object.clone. Creates and returns a copy of this object.
pack-priv AttributedCharacterIterator	Returns: AttributedCharacterIterator wrapping s createAttributedCharacterIterator(String String to create AttributedCharacterIterator from s) Creates an `AttributedCharacterIterator` for the String `s`.
pack-priv AttributedCharacterIterator	Returns: AttributedCharacterIterator wrapping passed in AttributedCharacterIterators createAttributedCharacterIterator(AttributedCharacterIterator[] AttributedCharacterIterators used to create resulting AttributedCharacterIterators iterators) Creates an `AttributedCharacterIterator` containing the concatenated contents of the passed in `AttributedCharacterIterator`s.
pack-priv AttributedCharacterIterator	Returns: AttributedCharacterIterator wrapping args createAttributedCharacterIterator(String String to create AttributedCharacterIterator from string, AttributedCharacterIterator.Attribute Key for AttributedCharacterIterator key, Object Value associated with key in AttributedCharacterIterator value) Returns an AttributedCharacterIterator with the String `string` and additional key/value pair `key`, `value`.
pack-priv AttributedCharacterIterator	Returns: AttributedCharacterIterator wrapping args createAttributedCharacterIterator(AttributedCharacterIterator Initial AttributedCharacterIterator to add arg to iterator, AttributedCharacterIterator.Attribute Key for AttributedCharacterIterator key, Object Value associated with key in AttributedCharacterIterator value) Creates an AttributedCharacterIterator with the contents of `iterator` and the additional attribute `key` `value`.
public final String	Returns: Formatted string. format(Object The object to format obj) Formats an object to produce a string.
public abstract StringBuffer	Returns: the string buffer passed in as `toAppendTo`, with formatted text appended format(Object The object to format obj, StringBuffer where the text is to be appended toAppendTo, FieldPosition A `FieldPosition` identifying a field in the formatted text pos) Formats an object and appends the resulting text to a given string buffer.
pack-priv Format.StringBuf	format(Object obj, Format.StringBuf toAppendTo, FieldPosition pos)
public AttributedCharacterIterator	Returns: AttributedCharacterIterator describing the formatted value. formatToCharacterIterator(Object The object to format obj) Formats an Object producing an `AttributedCharacterIterator`.
public abstract Object	Returns: An `Object` parsed from the string. In case of error, returns `null`. parseObject(String the `String` to parse source, ParsePosition A `ParsePosition` object with index and error index information as described above. pos) Parses text from the given string to produce an object.
public Object	Returns: An `Object` parsed from the string. parseObject(String A `String`, to be parsed from the beginning. source) Parses text from the beginning of the given string to produce an object.

Inherited from java.lang.Object:: equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

serialVersionUID	back to summary
private static final long serialVersionUID Annotations @Serial

Constructor Detail

Format	back to summary
protected Format() Sole constructor. (For invocation by subclass constructors, typically implicit.)

Method Detail

clone	back to summary
public Object clone() Overrides java.lang.Object.clone. Creates and returns a copy of this object. Returns:Object a clone of this instance.

clone

back to summary

public Object clone()

Overrides java.lang.Object.clone.

Creates and returns a copy of this object.

Returns:Object: a clone of this instance.

createAttributedCharacterIterator back to summary

createAttributedCharacterIterator	back to summary
pack-priv AttributedCharacterIterator createAttributedCharacterIterator(String s) Creates an `AttributedCharacterIterator` for the String `s`. Parameters s:String String to create AttributedCharacterIterator from Returns:AttributedCharacterIterator AttributedCharacterIterator wrapping s

pack-priv AttributedCharacterIterator createAttributedCharacterIterator(String s)

Creates an AttributedCharacterIterator for the String s.

Parameters

s:String: String to create AttributedCharacterIterator from

Returns:AttributedCharacterIterator

AttributedCharacterIterator wrapping s

createAttributedCharacterIterator back to summary

createAttributedCharacterIterator	back to summary
pack-priv AttributedCharacterIterator createAttributedCharacterIterator(AttributedCharacterIterator[] iterators) Creates an `AttributedCharacterIterator` containing the concatenated contents of the passed in `AttributedCharacterIterator`s. Parameters iterators:AttributedCharacterIterator[] AttributedCharacterIterators used to create resulting AttributedCharacterIterators Returns:AttributedCharacterIterator AttributedCharacterIterator wrapping passed in AttributedCharacterIterators

pack-priv AttributedCharacterIterator createAttributedCharacterIterator(AttributedCharacterIterator[] iterators)

Creates an AttributedCharacterIterator containing the concatenated contents of the passed in AttributedCharacterIterators.

Parameters

iterators:AttributedCharacterIterator[]: AttributedCharacterIterators used to create resulting AttributedCharacterIterators

Returns:AttributedCharacterIterator

AttributedCharacterIterator wrapping passed in AttributedCharacterIterators

createAttributedCharacterIterator back to summary

createAttributedCharacterIterator	back to summary
pack-priv AttributedCharacterIterator createAttributedCharacterIterator(String string, AttributedCharacterIterator.Attribute key, Object value) Returns an AttributedCharacterIterator with the String `string` and additional key/value pair `key`, `value`. Parameters string:String String to create AttributedCharacterIterator from key:AttributedCharacterIterator.Attribute Key for AttributedCharacterIterator value:Object Value associated with key in AttributedCharacterIterator Returns:AttributedCharacterIterator AttributedCharacterIterator wrapping args

pack-priv AttributedCharacterIterator createAttributedCharacterIterator(String string, AttributedCharacterIterator.Attribute key, Object value)

Returns an AttributedCharacterIterator with the String string and additional key/value pair key, value.

Parameters

string:String: String to create AttributedCharacterIterator from
key:AttributedCharacterIterator.Attribute: Key for AttributedCharacterIterator
value:Object: Value associated with key in AttributedCharacterIterator

Returns:AttributedCharacterIterator

AttributedCharacterIterator wrapping args

createAttributedCharacterIterator back to summary

createAttributedCharacterIterator	back to summary
pack-priv AttributedCharacterIterator createAttributedCharacterIterator(AttributedCharacterIterator iterator, AttributedCharacterIterator.Attribute key, Object value) Creates an AttributedCharacterIterator with the contents of `iterator` and the additional attribute `key` `value`. Parameters iterator:AttributedCharacterIterator Initial AttributedCharacterIterator to add arg to key:AttributedCharacterIterator.Attribute Key for AttributedCharacterIterator value:Object Value associated with key in AttributedCharacterIterator Returns:AttributedCharacterIterator AttributedCharacterIterator wrapping args

pack-priv AttributedCharacterIterator createAttributedCharacterIterator(AttributedCharacterIterator iterator, AttributedCharacterIterator.Attribute key, Object value)

Creates an AttributedCharacterIterator with the contents of iterator and the additional attribute key value.

Parameters

iterator:AttributedCharacterIterator: Initial AttributedCharacterIterator to add arg to
key:AttributedCharacterIterator.Attribute: Key for AttributedCharacterIterator
value:Object: Value associated with key in AttributedCharacterIterator

Returns:AttributedCharacterIterator

AttributedCharacterIterator wrapping args

format back to summary

format	back to summary
public final String format(Object obj) Formats an object to produce a string. Implementation Specification This method returns a string that would be equal to the string returned by `format(obj, new StringBuffer(), new FieldPosition(0)).toString();` Parameters obj:Object The object to format Returns:String Formatted string. Exceptions IllegalArgumentException: if the Format cannot format the given object

public final String format(Object obj)

Formats an object to produce a string.

Implementation Specification

This method returns a string that would be equal to the string returned by

format(obj, new StringBuffer(), new FieldPosition(0)).toString();

Parameters

obj:Object: The object to format

Returns:String

Formatted string.

Exceptions

IllegalArgumentException:: if the Format cannot format the given object

format back to summary

format	back to summary
public abstract StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos) Formats an object and appends the resulting text to a given string buffer. If the `pos` argument identifies a field used by the format, then its indices are set to the beginning and end of the first such field encountered. Parameters obj:Object The object to format toAppendTo:StringBuffer where the text is to be appended pos:FieldPosition A `FieldPosition` identifying a field in the formatted text Returns:StringBuffer the string buffer passed in as `toAppendTo`, with formatted text appended Exceptions NullPointerException: if `toAppendTo` or `pos` is null IllegalArgumentException: if the Format cannot format the given object

public abstract StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos)

Formats an object and appends the resulting text to a given string buffer. If the pos argument identifies a field used by the format, then its indices are set to the beginning and end of the first such field encountered.

Parameters

obj:Object: The object to format
toAppendTo:StringBuffer: where the text is to be appended
pos:FieldPosition: A FieldPosition identifying a field in the formatted text

Returns:StringBuffer

the string buffer passed in as toAppendTo, with formatted text appended

Exceptions

NullPointerException:: if toAppendTo or pos is null
IllegalArgumentException:: if the Format cannot format the given object

format	back to summary
pack-priv Format.StringBuf format(Object obj, Format.StringBuf toAppendTo, FieldPosition pos)

formatToCharacterIterator back to summary

formatToCharacterIterator	back to summary
public AttributedCharacterIterator formatToCharacterIterator(Object obj) Formats an Object producing an `AttributedCharacterIterator`. You can use the returned `AttributedCharacterIterator` to build the resulting String, as well as to determine information about the resulting String. Each attribute key of the AttributedCharacterIterator will be of type `Field`. It is up to each `Format` implementation to define what the legal values are for each attribute in the `AttributedCharacterIterator`, but typically the attribute key is also used as the attribute value. API Note Subclasses that support fields should override this and create an `AttributedCharacterIterator` with meaningful attributes. Implementation Specification The default implementation creates an `AttributedCharacterIterator` with no attributes. Parameters obj:Object The object to format Returns:AttributedCharacterIterator AttributedCharacterIterator describing the formatted value. Exceptions NullPointerException: if obj is null. IllegalArgumentException: when the Format cannot format the given object. Since 1.4

public AttributedCharacterIterator formatToCharacterIterator(Object obj)

Formats an Object producing an AttributedCharacterIterator. You can use the returned AttributedCharacterIterator to build the resulting String, as well as to determine information about the resulting String.

Each attribute key of the AttributedCharacterIterator will be of type Field. It is up to each Format implementation to define what the legal values are for each attribute in the AttributedCharacterIterator, but typically the attribute key is also used as the attribute value.

API Note

Subclasses that support fields should override this and create an AttributedCharacterIterator with meaningful attributes.

Implementation Specification

The default implementation creates an AttributedCharacterIterator with no attributes.

Parameters

obj:Object: The object to format

Returns:AttributedCharacterIterator

AttributedCharacterIterator describing the formatted value.

Exceptions

NullPointerException:: if obj is null.
IllegalArgumentException:: when the Format cannot format the given object.

Since

1.4

parseObject back to summary

parseObject	back to summary
public abstract Object parseObject(String source, ParsePosition pos) Parses text from the given string to produce an object. This method attempts to parse text starting at the index given by `pos`. If parsing succeeds, then the index of `pos` is updated to the index after the last character used (parsing does not necessarily use all characters up to the end of the string), and the parsed object is returned. The updated `pos` can be used to indicate the starting point for the next call to this method. If an error occurs, then the index of `pos` is not changed, the error index of `pos` is set to the index of the character where the error occurred, and `null` is returned. Parameters source:String the `String` to parse pos:ParsePosition A `ParsePosition` object with index and error index information as described above. Returns:Object An `Object` parsed from the string. In case of error, returns `null`. Exceptions NullPointerException: if `source` or `pos` is `null`.

public abstract Object parseObject(String source, ParsePosition pos)

Parses text from the given string to produce an object.

This method attempts to parse text starting at the index given by pos. If parsing succeeds, then the index of pos is updated to the index after the last character used (parsing does not necessarily use all characters up to the end of the string), and the parsed object is returned. The updated pos can be used to indicate the starting point for the next call to this method. If an error occurs, then the index of pos is not changed, the error index of pos is set to the index of the character where the error occurred, and null is returned.

Parameters

source:String: the String to parse
pos:ParsePosition: A ParsePosition object with index and error index information as described above.

Returns:Object

An Object parsed from the string. In case of error, returns null.

Exceptions

NullPointerException:: if source or pos is null.

parseObject back to summary

parseObject	back to summary
public Object parseObject(String source) throws ParseException Parses text from the beginning of the given string to produce an object. This method may not use the entire text of the given string. Parameters source:String A `String`, to be parsed from the beginning. Returns:Object An `Object` parsed from the string. Exceptions ParseException: if parsing fails NullPointerException: if `source` is `null`.

public Object parseObject(String source) throws ParseException

Parses text from the beginning of the given string to produce an object. This method may not use the entire text of the given string.

Parameters

source:String: A String, to be parsed from the beginning.

Returns:Object

An Object parsed from the string.

Exceptions

ParseException:: if parsing fails
NullPointerException:: if source is null.

java.text back to summary

public Class Format.Field

Class Inheritance

extends Attribute

java.lang.Object
java.text.AttributedCharacterIterator.Attribute
java.text.Format.Field

Known Direct Subclasses

java.text.MessageFormat.Field, java.text.NumberFormat.Field, java.text.DateFormat.Field

Defines constants that are used as attribute keys in the AttributedCharacterIterator returned from Format.formatToCharacterIterator and as field identifiers in FieldPosition.

Since: 1.4

Field Summary

Modifier and Type	Field and Description
private static final long	serialVersionUID Hides java.text.AttributedCharacterIterator.Attribute.serialVersionUID.

Inherited from java.text.AttributedCharacterIterator.Attribute:: INPUT_METHOD_SEGMENT LANGUAGE READING

Constructor Summary

Access	Constructor and Description
protected	Field(String Name of the attribute name) Creates a Field with the specified name.

Method Summary

Inherited from java.text.AttributedCharacterIterator.Attribute:: equals getName hashCode readResolve toString

Field Detail

serialVersionUID	back to summary
private static final long serialVersionUID Hides java.text.AttributedCharacterIterator.Attribute.serialVersionUID. Annotations @Serial

Constructor Detail

Field	back to summary
protected Field(String name) Creates a Field with the specified name. Parameters name:String Name of the attribute

Field

back to summary

protected Field(String name)

Creates a Field with the specified name.

Parameters

name:String: Name of the attribute

java.text back to summary

pack-priv Interface Format.FieldDelegate

Known Direct Implementers: java.text.CharacterIteratorFieldDelegate, java.text.FieldPosition.Delegate

FieldDelegate is notified by the various Format implementations as they are formatting the Objects. This allows for storage of the individual sections of the formatted String for later use, such as in a FieldPosition or for an AttributedCharacterIterator.

Delegates should NOT assume that the Format will notify the delegate of fields in any particular order.

See Also: FieldPosition#getFieldDelegate, CharacterIteratorFieldDelegate

Method Summary

Modifier and Type	Method and Description
public void	formatted(Format.Field Identifies the field matched attr, Object Value associated with the field value, int Beginning location of the field, will be >= 0 start, int End of the field, will be >= start and <= buffer.length() end, Format.StringBuf Contains current formatted value, receiver should NOT modify it. buffer) Notified when a particular region of the String is formatted.
public void	formatted(int Identifies the field by integer fieldID, Format.Field Identifies the field matched attr, Object Value associated with the field value, int Beginning location of the field, will be >= 0 start, int End of the field, will be >= start and <= buffer.length() end, Format.StringBuf Contains current formatted value, receiver should NOT modify it. buffer) Notified when a particular region of the String is formatted.

Modifier and Type

Method and Description

public void

formatted(Format.Field

Identifies the field matched

attr, Object

Value associated with the field

value, int

Beginning location of the field, will be >= 0

start, int

End of the field, will be >= start and <= buffer.length()

end, Format.StringBuf

Contains current formatted value, receiver should NOT modify it.

buffer)

Notified when a particular region of the String is formatted.

public void

formatted(int

Identifies the field by integer

fieldID, Format.Field

Identifies the field matched

attr, Object

Value associated with the field

value, int

Beginning location of the field, will be >= 0

start, int

End of the field, will be >= start and <= buffer.length()

end, Format.StringBuf

Contains current formatted value, receiver should NOT modify it.

buffer)

Notified when a particular region of the String is formatted.

Method Detail

formatted back to summary

formatted	back to summary
public void formatted(Format.Field attr, Object value, int start, int end, Format.StringBuf buffer) Notified when a particular region of the String is formatted. This method will be invoked if there is no corresponding integer field id matching `attr`. Parameters attr:Format.Field Identifies the field matched value:Object Value associated with the field start:int Beginning location of the field, will be >= 0 end:int End of the field, will be >= start and <= buffer.length() buffer:Format.StringBuf Contains current formatted value, receiver should NOT modify it.

public void formatted(Format.Field attr, Object value, int start, int end, Format.StringBuf buffer)

Notified when a particular region of the String is formatted. This method will be invoked if there is no corresponding integer field id matching attr.

Parameters

attr:Format.Field: Identifies the field matched
value:Object: Value associated with the field
start:int: Beginning location of the field, will be >= 0
end:int: End of the field, will be >= start and <= buffer.length()
buffer:Format.StringBuf: Contains current formatted value, receiver should NOT modify it.

formatted	back to summary
public void formatted(int fieldID, Format.Field attr, Object value, int start, int end, Format.StringBuf buffer) Notified when a particular region of the String is formatted. Parameters fieldID:int Identifies the field by integer attr:Format.Field Identifies the field matched value:Object Value associated with the field start:int Beginning location of the field, will be >= 0 end:int End of the field, will be >= start and <= buffer.length() buffer:Format.StringBuf Contains current formatted value, receiver should NOT modify it.

formatted

back to summary

public void formatted(int fieldID, Format.Field attr, Object value, int start, int end, Format.StringBuf buffer)

Notified when a particular region of the String is formatted.

Parameters

fieldID:int: Identifies the field by integer
attr:Format.Field: Identifies the field matched
value:Object: Value associated with the field
start:int: Beginning location of the field, will be >= 0
end:int: End of the field, will be >= start and <= buffer.length()
buffer:Format.StringBuf: Contains current formatted value, receiver should NOT modify it.

java.text back to summary

pack-priv sealed Interface Format.StringBuf

Known Direct Implementers: java.text.StringBufFactory.StringBufferImpl, java.text.StringBufFactory.StringBuilderImpl

StringBuf is the minimal common interface of StringBuffer and StringBuilder. It is used by the various Format implementations as the internal string buffer.

Method Summary

Modifier and Type	Method and Description
public Format.StringBuf	append(char c)
public Format.StringBuf	append(String str)
public Format.StringBuf	append(int i)
public Format.StringBuf	append(char[] str, int offset, int len)
public Format.StringBuf	append(CharSequence s, int start, int end)
public Format.StringBuf	append(StringBuffer sb)
public StringBuffer	asStringBuffer()
public StringBuilder	asStringBuilder()
public boolean	isProxyStringBuilder()
public int	length()
public String	substring(int start, int end)
public String	substring(int start)

Method Detail

append	back to summary
public Format.StringBuf append(char c)

append	back to summary
public Format.StringBuf append(String str)

append	back to summary
public Format.StringBuf append(int i)

append	back to summary
public Format.StringBuf append(char[] str, int offset, int len)

append	back to summary
public Format.StringBuf append(CharSequence s, int start, int end)

append	back to summary
public Format.StringBuf append(StringBuffer sb)

asStringBuffer	back to summary
public StringBuffer asStringBuffer()

asStringBuilder	back to summary
public StringBuilder asStringBuilder()

isProxyStringBuilder	back to summary
public boolean isProxyStringBuilder()

length	back to summary
public int length()

substring	back to summary
public String substring(int start, int end)

substring	back to summary
public String substring(int start)

public abstract Class Format

Subclassing

Synchronization

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public Class Format.Field

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

pack-priv Interface Format.FieldDelegate

Method Summary

Method Detail

pack-priv sealed Interface Format.StringBuf

Method Summary

Method Detail