FileDocCategorySizeDatePackage
Format.javaAPI DocAndroid 1.5 API12781Wed May 06 22:41:06 BST 2009java.text

Format

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 {@code 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 {@code SimpleDateFormat} may represent a specific date, encoded numerically, as a string such as "Wednesday, February 26, 1997 AD".

Many of the concrete subclasses of {@code 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 {@code 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 {@code Format} classes in general, and is not part of the explicit base class protocol.

Two complex formatting classes are worth mentioning: {@code MessageFormat} and {@code ChoiceFormat}. {@code ChoiceFormat} is a subclass of {@code 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". {@code MessageFormat} is a formatter which utilizes other {@code Format} objects to format a string containing multiple values. For instance, a {@code 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 {@link ChoiceFormat} and {@link MessageFormat} descriptions for further information.

since
Android 1.0

Fields Summary
private static final long
serialVersionUID
Constructors Summary
public Format()
Constructs a new {@code Format} instance.

since
Android 1.0
Methods Summary
public java.lang.Objectclone()
Returns a copy of this {@code Format} instance.

return
a shallow copy of this format.
see
java.lang.Cloneable
since
Android 1.0

        try {
            return super.clone();
        } catch (CloneNotSupportedException e) {
            return null;
        }
java.lang.StringconvertPattern(java.lang.String template, java.lang.String fromChars, java.lang.String toChars, boolean check)

        if (!check && fromChars.equals(toChars)) {
            return template;
        }
        boolean quote = false;
        StringBuilder output = new StringBuilder();
        int length = template.length();
        for (int i = 0; i < length; i++) {
            int index;
            char next = template.charAt(i);
            if (next == '\'") {
                quote = !quote;
            }
            if (!quote && (index = fromChars.indexOf(next)) != -1) {
                output.append(toChars.charAt(index));
            } else if (check
                    && !quote
                    && ((next >= 'a" && next <= 'z") || (next >= 'A" && next <= 'Z"))) {
                // text.05=Invalid pattern char {0} in {1}
                throw new IllegalArgumentException(Messages.getString(
                        "text.05", String.valueOf(next), template)); //$NON-NLS-1$
            } else {
                output.append(next);
            }
        }
        if (quote) {
            // text.04=Unterminated quote
            throw new IllegalArgumentException(Messages.getString("text.04")); //$NON-NLS-1$
        }
        return output.toString();
public final java.lang.Stringformat(java.lang.Object object)
Formats the specified object using the rules of this format.

param
object the object to format.
return
the formatted string.
exception
IllegalArgumentException if the object cannot be formatted by this format.
since
Android 1.0

        return format(object, new StringBuffer(), new FieldPosition(0))
                .toString();
public abstract java.lang.StringBufferformat(java.lang.Object object, java.lang.StringBuffer buffer, java.text.FieldPosition field)
Appends the specified object to the specified string buffer using the rules of this format.

{@code field} is an input/output parameter. If its {@code field} member contains an enum value specifying a field on input, then its {@code beginIndex} and {@code endIndex} members will be updated with the text offset of the first occurrence of this field in the formatted text.

param
object the object to format.
param
buffer the string buffer where the formatted string is appended to.
param
field on input: an optional alignment field; on output: the offsets of the alignment field in the formatted text.
return
the string buffer.
exception
IllegalArgumentException if the object cannot be formatted by this format.
since
Android 1.0

public java.text.AttributedCharacterIteratorformatToCharacterIterator(java.lang.Object object)
Formats the specified object using the rules of this format and returns
an {@code AttributedCharacterIterator} with the formatted string and no
attributes.


Subclasses should return an {@code AttributedCharacterIterator} with the
appropriate attributes.

param
object
the object to format.
return
an {@code AttributedCharacterIterator} with the formatted object
and attributes.
exception
IllegalArgumentException
if the object cannot be formatted by this format.
since
Android 1.0
        return new AttributedString(format(object)).getIterator();
    
static java.util.ResourceBundlegetBundle(java.util.Locale locale)
        return AccessController
                .doPrivileged(new PrivilegedAction<ResourceBundle>() {
                    public ResourceBundle run() {
                        return ResourceBundle
                                .getBundle(
                                        "org.apache.harmony.luni.internal.locale.Locale", locale); //$NON-NLS-1$
                    }
                });
    
public java.lang.ObjectparseObject(java.lang.String string)
Parses the specified string using the rules of this format.
param
string
the string to parse.
return
the object resulting from the parse.
exception
ParseException
if an error occurs during parsing.
since
Android 1.0
        ParsePosition position = new ParsePosition(0);
        Object result = parseObject(string, position);
        if (position.getErrorIndex() != -1 || position.getIndex() == 0) {
            throw new ParseException(null, position.getErrorIndex());
        }
        return result;
    
public abstract java.lang.ObjectparseObject(java.lang.String string, java.text.ParsePosition position)
Parses the specified string starting at the index specified by
{@code position}. If the string is successfully parsed then the index of
the {@code ParsePosition} is updated to the index following the parsed
text. On error, the index is unchanged and the error index of
{@code ParsePosition} is set to the index where the error occurred.
param
string
the string to parse.
param
position
input/output parameter, specifies the start index in
{@code 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.
return
the object resulting from the parse or {@code null} if there is
an error.
since
Android 1.0
static booleanupTo(java.lang.String string, java.text.ParsePosition position, java.lang.StringBuffer buffer, char stop)
        int index = position.getIndex(), length = string.length();
        boolean lastQuote = false, quote = false;
        while (index < length) {
            char ch = string.charAt(index++);
            if (ch == '\'") {
                if (lastQuote) {
                    buffer.append('\'");
                }
                quote = !quote;
                lastQuote = true;
            } else if (ch == stop && !quote) {
                position.setIndex(index);
                return true;
            } else {
                lastQuote = false;
                buffer.append(ch);
            }
        }
        position.setIndex(index);
        return false;
    
static booleanupToWithQuotes(java.lang.String string, java.text.ParsePosition position, java.lang.StringBuffer buffer, char stop, char start)
        int index = position.getIndex(), length = string.length(), count = 1;
        boolean quote = false;
        while (index < length) {
            char ch = string.charAt(index++);
            if (ch == '\'") {
                quote = !quote;
            }
            if (!quote) {
                if (ch == stop) {
                    count--;
                }
                if (count == 0) {
                    position.setIndex(index);
                    return true;
                }
                if (ch == start) {
                    count++;
                }
            }
            buffer.append(ch);
        }
        // text.07=Unmatched braces in the pattern
        throw new IllegalArgumentException(Messages.getString("text.07")); //$NON-NLS-1$