You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/05/07 10:42:03 UTC
svn commit: r772552 [3/5] -
/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/
Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DateFormatSymbols.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DateFormatSymbols.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DateFormatSymbols.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DateFormatSymbols.java Thu May 7 08:42:00 2009
@@ -22,8 +22,41 @@
import java.util.Locale;
/**
- * DateFormatSymbols holds the Strings used in the formating and parsing of
- * dates and times.
+ * Encapsulates localizable date-time formatting data, such as the names of the
+ * months, the names of the days of the week, and the time zone data.
+ * {@code DateFormat} and {@code SimpleDateFormat} both use
+ * {@code DateFormatSymbols} to encapsulate this information.
+ * <p>
+ * Typically you shouldn't use {@code DateFormatSymbols} directly. Rather, you
+ * are encouraged to create a date/time formatter with the {@code DateFormat}
+ * class's factory methods: {@code getTimeInstance}, {@code getDateInstance},
+ * or {@code getDateTimeInstance}. These methods automatically create a
+ * {@code DateFormatSymbols} for the formatter so that you don't have to. After
+ * the formatter is created, you may modify its format pattern using the
+ * {@code setPattern} method. For more information about creating formatters
+ * using {@code DateFormat}'s factory methods, see {@link DateFormat}.
+ * <p>
+ * If you decide to create a date/time formatter with a specific format pattern
+ * for a specific locale, you can do so with:
+ * <blockquote>
+ *
+ * <pre>
+ * new SimpleDateFormat(aPattern, new DateFormatSymbols(aLocale)).
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * {@code DateFormatSymbols} objects can be cloned. When you obtain a
+ * {@code DateFormatSymbols} object, feel free to modify the date/time
+ * formatting data. For instance, you can replace the localized date/time format
+ * pattern characters with the ones that you feel easy to remember or you can
+ * change the representative cities to your favorite ones.
+ * <p>
+ * New {@code DateFormatSymbols} subclasses may be added to support
+ * {@code SimpleDateFormat} for date/time formatting for additional locales.
+ *
+ * @see DateFormat
+ * @see SimpleDateFormat
*/
public class DateFormatSymbols implements Serializable, Cloneable {
@@ -36,19 +69,19 @@
String[][] zoneStrings;
/**
- * Constructs a new DateFormatSymbols containing the symbols for the default
- * Locale.
+ * Constructs a new {@code DateFormatSymbols} instance containing the
+ * symbols for the default locale.
*/
public DateFormatSymbols() {
this(Locale.getDefault());
}
/**
- * Constructs a new DateFormatSymbols containing the symbols for the
- * specified Locale.
+ * Constructs a new {@code DateFormatSymbols} instance containing the
+ * symbols for the specified locale.
*
* @param locale
- * the Locale
+ * the locale.
*/
public DateFormatSymbols(Locale locale) {
com.ibm.icu.text.DateFormatSymbols icuSymbols = new com.ibm.icu.text.DateFormatSymbols(locale);
@@ -63,14 +96,6 @@
zoneStrings = icuSymbols.getZoneStrings();
}
- /**
- * Answers a new DateFormatSymbols with the same symbols as this
- * DateFormatSymbols.
- *
- * @return a shallow copy of this DateFormatSymbols
- *
- * @see java.lang.Cloneable
- */
@Override
public Object clone() {
try {
@@ -92,15 +117,14 @@
}
/**
- * Compares the specified object to this DateFormatSymbols and answer if
- * they are equal. The object must be an instance of DateFormatSymbols with
- * the same symbols.
+ * Compares this object with the specified object and indicates if they are
+ * equal.
*
* @param object
- * the object to compare with this object
- * @return true if the specified object is equal to this DateFormatSymbols,
- * false otherwise
- *
+ * the object to compare with this object.
+ * @return {@code true} if {@code object} is an instance of
+ * {@code DateFormatSymbols} and has the same symbols as this
+ * object, {@code false} otherwise.
* @see #hashCode
*/
@Override
@@ -151,87 +175,89 @@
}
/**
- * Answers the array of Strings which represent AM and PM. Use the Calendar
- * constants Calendar.AM and Calendar.PM to index into the array.
+ * Returns the array of strings which represent AM and PM. Use the
+ * {@link java.util.Calendar} constants {@code Calendar.AM} and
+ * {@code Calendar.PM} as indices for the array.
*
- * @return an array of String
+ * @return an array of strings.
*/
public String[] getAmPmStrings() {
return ampms.clone();
}
/**
- * Answers the array of Strings which represent BC and AD. Use the Calendar
- * constants GregorianCalendar.BC and GregorianCalendar.AD to index into the
- * array.
+ * Returns the array of strings which represent BC and AD. Use the
+ * {@link java.util.Calendar} constants {@code GregorianCalendar.BC} and
+ * {@code GregorianCalendar.AD} as indices for the array.
*
- * @return an array of String
+ * @return an array of strings.
*/
public String[] getEras() {
return eras.clone();
}
/**
- * Answers the pattern characters used by SimpleDateFormat to specify date
- * and time fields.
+ * Returns the pattern characters used by {@link SimpleDateFormat} to
+ * specify date and time fields.
*
- * @return a String containing the pattern characters
+ * @return a string containing the pattern characters.
*/
public String getLocalPatternChars() {
return localPatternChars;
}
/**
- * Answers the array of Strings containing the full names of the months. Use
- * the Calendar constants Calendar.JANUARY, etc. to index into the array.
+ * Returns the array of strings containing the full names of the months. Use
+ * the {@link java.util.Calendar} constants {@code Calendar.JANUARY} etc. as
+ * indices for the array.
*
- * @return an array of String
+ * @return an array of strings.
*/
public String[] getMonths() {
return months.clone();
}
/**
- * Answers the array of Strings containing the abbreviated names of the
- * months. Use the Calendar constants Calendar.JANUARY, etc. to index into
- * the array.
+ * Returns the array of strings containing the abbreviated names of the
+ * months. Use the {@link java.util.Calendar} constants
+ * {@code Calendar.JANUARY} etc. as indices for the array.
*
- * @return an array of String
+ * @return an array of strings.
*/
public String[] getShortMonths() {
return shortMonths.clone();
}
/**
- * Answers the array of Strings containing the abbreviated names of the days
- * of the week. Use the Calendar constants Calendar.SUNDAY, etc. to index
- * into the array.
+ * Returns the array of strings containing the abbreviated names of the days
+ * of the week. Use the {@link java.util.Calendar} constants
+ * {@code Calendar.SUNDAY} etc. as indices for the array.
*
- * @return an array of String
+ * @return an array of strings.
*/
public String[] getShortWeekdays() {
return shortWeekdays.clone();
}
/**
- * Answers the array of Strings containing the full names of the days of the
- * week. Use the Calendar constants Calendar.SUNDAY, etc. to index into the
- * array.
+ * Returns the array of strings containing the full names of the days of the
+ * week. Use the {@link java.util.Calendar} constants
+ * {@code Calendar.SUNDAY} etc. as indices for the array.
*
- * @return an array of String
+ * @return an array of strings.
*/
public String[] getWeekdays() {
return weekdays.clone();
}
/**
- * Answers the two-dimensional array of Strings containing the names of the
- * timezones. Each element in the array is an array of five Strings, the
- * first is a TimeZone ID, and second and third are the full and abbreviated
- * timezone names for standard time, and the fourth and fifth are the full
+ * Returns the two-dimensional array of strings containing the names of the
+ * time zones. Each element in the array is an array of five strings, the
+ * first is a TimeZone ID, the second and third are the full and abbreviated
+ * time zone names for standard time, and the fourth and fifth are the full
* and abbreviated names for daylight time.
*
- * @return a two-dimensional array of String
+ * @return a two-dimensional array of strings.
*/
public String[][] getZoneStrings() {
String[][] clone = new String[zoneStrings.length][];
@@ -241,14 +267,6 @@
return clone;
}
- /**
- * Answers an integer hash code for the receiver. Objects which are equal
- * answer the same value for this method.
- *
- * @return the receiver's hash
- *
- * @see #equals
- */
@Override
public int hashCode() {
int hashCode;
@@ -282,37 +300,37 @@
}
/**
- * Sets the array of Strings which represent AM and PM. Use the Calendar
- * constants Calendar.AM and Calendar.PM to index into the array.
+ * Sets the array of strings which represent AM and PM. Use the
+ * {@link java.util.Calendar} constants {@code Calendar.AM} and
+ * {@code Calendar.PM} as indices for the array.
*
* @param data
- * the array of Strings
+ * the array of strings for AM and PM.
*/
public void setAmPmStrings(String[] data) {
ampms = data.clone();
}
/**
- * Sets the array of Strings which represent BC and AD. Use the Calendar
- * constants GregorianCalendar.BC and GregorianCalendar.AD to index into the
- * array.
+ * Sets the array of Strings which represent BC and AD. Use the
+ * {@link java.util.Calendar} constants {@code GregorianCalendar.BC} and
+ * {@code GregorianCalendar.AD} as indices for the array.
*
* @param data
- * the array of Strings
+ * the array of strings for BC and AD.
*/
public void setEras(String[] data) {
eras = data.clone();
}
/**
- * Sets the pattern characters used by SimpleDateFormat to specify date and
- * time fields.
+ * Sets the pattern characters used by {@link SimpleDateFormat} to specify
+ * date and time fields.
*
* @param data
- * the String containing the pattern characters
- *
- * @exception NullPointerException
- * when the data is null
+ * the string containing the pattern characters.
+ * @throws NullPointerException
+ * if {@code data} is null
*/
public void setLocalPatternChars(String data) {
if (data == null) {
@@ -322,61 +340,62 @@
}
/**
- * Sets the array of Strings containing the full names of the months. Use
- * the Calendar constants Calendar.JANUARY, etc. to index into the array.
+ * Sets the array of strings containing the full names of the months. Use
+ * the {@link java.util.Calendar} constants {@code Calendar.JANUARY} etc. as
+ * indices for the array.
*
* @param data
- * the array of Strings
+ * the array of strings.
*/
public void setMonths(String[] data) {
months = data.clone();
}
/**
- * Sets the array of Strings containing the abbreviated names of the months.
- * Use the Calendar constants Calendar.JANUARY, etc. to index into the
- * array.
+ * Sets the array of strings containing the abbreviated names of the months.
+ * Use the {@link java.util.Calendar} constants {@code Calendar.JANUARY}
+ * etc. as indices for the array.
*
* @param data
- * the array of Strings
+ * the array of strings.
*/
public void setShortMonths(String[] data) {
shortMonths = data.clone();
}
/**
- * Sets the array of Strings containing the abbreviated names of the days of
- * the week. Use the Calendar constants Calendar.SUNDAY, etc. to index into
- * the array.
+ * Sets the array of strings containing the abbreviated names of the days of
+ * the week. Use the {@link java.util.Calendar} constants
+ * {@code Calendar.SUNDAY} etc. as indices for the array.
*
* @param data
- * the array of Strings
+ * the array of strings.
*/
public void setShortWeekdays(String[] data) {
shortWeekdays = data.clone();
}
/**
- * Sets the array of Strings containing the full names of the days of the
- * week. Use the Calendar constants Calendar.SUNDAY, etc. to index into the
- * array.
+ * Sets the array of strings containing the full names of the days of the
+ * week. Use the {@link java.util.Calendar} constants
+ * {@code Calendar.SUNDAY} etc. as indices for the array.
*
* @param data
- * the array of Strings
+ * the array of strings.
*/
public void setWeekdays(String[] data) {
weekdays = data.clone();
}
/**
- * Sets the two-dimensional array of Strings containing the names of the
- * timezones. Each element in the array is an array of five Strings, the
+ * Sets the two-dimensional array of strings containing the names of the
+ * time zones. Each element in the array is an array of five strings, the
* first is a TimeZone ID, and second and third are the full and abbreviated
- * timezone names for standard time, and the fourth and fifth are the full
+ * time zone names for standard time, and the fourth and fifth are the full
* and abbreviated names for daylight time.
*
* @param data
- * the two-dimensional array of Strings
+ * the two-dimensional array of strings.
*/
public void setZoneStrings(String[][] data) {
zoneStrings = data.clone();
Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DecimalFormat.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DecimalFormat.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DecimalFormat.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DecimalFormat.java Thu May 7 08:42:00 2009
@@ -29,9 +29,512 @@
import java.util.Locale;
/**
- * DecimalFormat is used to format and parse numbers, both integers and
- * fractions, based on a pattern. The pattern characters used can be either
- * localized or non-localized.
+ * A concrete subclass of {@link NumberFormat} that formats decimal numbers. It
+ * has a variety of features designed to make it possible to parse and format
+ * numbers in any locale, including support for Western, Arabic, or Indic
+ * digits. It also supports different flavors of numbers, including integers
+ * ("123"), fixed-point numbers ("123.4"), scientific notation ("1.23E4"),
+ * percentages ("12%"), and currency amounts ("$123"). All of these flavors can
+ * be easily localized.
+ * <p>
+ * <strong>This is an enhanced version of {@code DecimalFormat} that is based on
+ * the standard version in the RI. New or changed functionality is labeled
+ * <strong><font color="red">NEW</font></strong>.</strong>
+ * <p>
+ * To obtain a {@link NumberFormat} for a specific locale (including the default
+ * locale), call one of {@code NumberFormat}'s factory methods such as
+ * {@code NumberFormat.getInstance}. Do not call the {@code DecimalFormat}
+ * constructors directly, unless you know what you are doing, since the
+ * {@link NumberFormat} factory methods may return subclasses other than
+ * {@code DecimalFormat}. If you need to customize the format object, do
+ * something like this: <blockquote>
+ *
+ * <pre>
+ * NumberFormat f = NumberFormat.getInstance(loc);
+ * if (f instanceof DecimalFormat) {
+ * ((DecimalFormat)f).setDecimalSeparatorAlwaysShown(true);
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <h5>Example:</h5>
+ * <blockquote>
+ *
+ * <pre>
+ * // Print out a number using the localized number, currency,
+ * // and percent format for each locale
+ * Locale[] locales = NumberFormat.getAvailableLocales();
+ * double myNumber = -1234.56;
+ * NumberFormat format;
+ * for (int j = 0; j < 3; ++j) {
+ * System.out.println("FORMAT");
+ * for (int i = 0; i < locales.length; ++i) {
+ * if (locales[i].getCountry().length() == 0) {
+ * // Skip language-only locales
+ * continue;
+ * }
+ * System.out.print(locales[i].getDisplayName());
+ * switch (j) {
+ * case 0:
+ * format = NumberFormat.getInstance(locales[i]);
+ * break;
+ * case 1:
+ * format = NumberFormat.getCurrencyInstance(locales[i]);
+ * break;
+ * default:
+ * format = NumberFormat.getPercentInstance(locales[i]);
+ * break;
+ * }
+ * try {
+ * // Assume format is a DecimalFormat
+ * System.out.print(": "; + ((DecimalFormat)format).toPattern() + " -> "
+ * + form.format(myNumber));
+ * } catch (Exception e) {
+ * }
+ * try {
+ * System.out.println(" -> " + format.parse(form.format(myNumber)));
+ * } catch (ParseException e) {
+ * }
+ * }
+ * }
+ * </pre>
+ *
+ * </blockquote>
+ * <h4>Patterns</h4>
+ * <p>
+ * A {@code DecimalFormat} consists of a <em>pattern</em> and a set of
+ * <em>symbols</em>. The pattern may be set directly using
+ * {@link #applyPattern(String)}, or indirectly using other API methods which
+ * manipulate aspects of the pattern, such as the minimum number of integer
+ * digits. The symbols are stored in a {@link DecimalFormatSymbols} object. When
+ * using the {@link NumberFormat} factory methods, the pattern and symbols are
+ * read from ICU's locale data.
+ * <h4>Special Pattern Characters</h4>
+ * <p>
+ * Many characters in a pattern are taken literally; they are matched during
+ * parsing and are written out unchanged during formatting. On the other hand,
+ * special characters stand for other characters, strings, or classes of
+ * characters. For example, the '#' character is replaced by a localized digit.
+ * Often the replacement character is the same as the pattern character; in the
+ * U.S. locale, the ',' grouping character is replaced by ','. However, the
+ * replacement is still happening, and if the symbols are modified, the grouping
+ * character changes. Some special characters affect the behavior of the
+ * formatter by their presence; for example, if the percent character is seen,
+ * then the value is multiplied by 100 before being displayed.
+ * <p>
+ * To insert a special character in a pattern as a literal, that is, without any
+ * special meaning, the character must be quoted. There are some exceptions to
+ * this which are noted below.
+ * <p>
+ * The characters listed here are used in non-localized patterns. Localized
+ * patterns use the corresponding characters taken from this formatter's
+ * {@link DecimalFormatSymbols} object instead, and these characters lose their
+ * special status. Two exceptions are the currency sign and quote, which are not
+ * localized.
+ * <blockquote> <table border="0" cellspacing="3" cellpadding="0" summary="Chart
+ * showing symbol, location, localized, and meaning.">
+ * <tr bgcolor="#ccccff">
+ * <th align="left">Symbol</th>
+ * <th align="left">Location</th>
+ * <th align="left">Localized?</th>
+ * <th align="left">Meaning</th>
+ * </tr>
+ * <tr valign="top">
+ * <td>{@code 0}</td>
+ * <td>Number</td>
+ * <td>Yes</td>
+ * <td>Digit.</td>
+ * </tr>
+ * <tr valign="top">
+ * <td>{@code @}</td>
+ * <td>Number</td>
+ * <td>No</td>
+ * <td><strong><font color="red">NEW</font> </strong> Significant
+ * digit.</td>
+ * </tr>
+ * <tr valign="top" bgcolor="#eeeeff">
+ * <td>{@code #}</td>
+ * <td>Number</td>
+ * <td>Yes</td>
+ * <td>Digit, leading zeroes are not shown.</td>
+ * </tr>
+ * <tr valign="top">
+ * <td>{@code .}</td>
+ * <td>Number</td>
+ * <td>Yes</td>
+ * <td>Decimal separator or monetary decimal separator.</td>
+ * </tr>
+ * <tr valign="top" bgcolor="#eeeeff">
+ * <td>{@code -}</td>
+ * <td>Number</td>
+ * <td>Yes</td>
+ * <td>Minus sign.</td>
+ * </tr>
+ * <tr valign="top">
+ * <td>{@code ,}</td>
+ * <td>Number</td>
+ * <td>Yes</td>
+ * <td>Grouping separator.</td>
+ * </tr>
+ * <tr valign="top" bgcolor="#eeeeff">
+ * <td>{@code E}</td>
+ * <td>Number</td>
+ * <td>Yes</td>
+ * <td>Separates mantissa and exponent in scientific notation.
+ * <em>Does not need to be quoted in prefix or suffix.</em></td>
+ * </tr>
+ * <tr valign="top">
+ * <td>{@code +}</td>
+ * <td>Exponent</td>
+ * <td>Yes</td>
+ * <td><strong><font color="red">NEW</font> </strong> Prefix
+ * positive exponents with localized plus sign.
+ * <em>Does not need to be quoted in prefix or suffix.</em></td>
+ * </tr>
+ * <tr valign="top" bgcolor="#eeeeff">
+ * <td>{@code ;}</td>
+ * <td>Subpattern boundary</td>
+ * <td>Yes</td>
+ * <td>Separates positive and negative subpatterns.</td>
+ * </tr>
+ * <tr valign="top">
+ * <td>{@code %}</td>
+ * <td>Prefix or suffix</td>
+ * <td>Yes</td>
+ * <td>Multiply by 100 and show as percentage.</td>
+ * </tr>
+ * <tr valign="top" bgcolor="#eeeeff">
+ * <td>{@code \u2030} ({@code \u2030})</td>
+ * <td>Prefix or suffix</td>
+ * <td>Yes</td>
+ * <td>Multiply by 1000 and show as per mille.</td>
+ * </tr>
+ * <tr valign="top">
+ * <td>{@code ¤} ({@code \u00A4})</td>
+ * <td>Prefix or suffix</td>
+ * <td>No</td>
+ * <td>Currency sign, replaced by currency symbol. If doubled, replaced by
+ * international currency symbol. If present in a pattern, the monetary decimal
+ * separator is used instead of the decimal separator.</td>
+ * </tr>
+ * <tr valign="top" bgcolor="#eeeeff">
+ * <td>{@code '}</td>
+ * <td>Prefix or suffix</td>
+ * <td>No</td>
+ * <td>Used to quote special characters in a prefix or suffix, for example,
+ * {@code "'#'#"} formats 123 to {@code "#123"}. To create a single quote
+ * itself, use two in a row: {@code "# o''clock"}.</td>
+ * </tr>
+ * <tr valign="top">
+ * <td>{@code *}</td>
+ * <td>Prefix or suffix boundary</td>
+ * <td>Yes</td>
+ * <td><strong><font color="red">NEW</font> </strong> Pad escape,
+ * precedes pad character. </td>
+ * </tr>
+ * </table> </blockquote>
+ * <p>
+ * A {@code DecimalFormat} pattern contains a postive and negative subpattern,
+ * for example, "#,##0.00;(#,##0.00)". Each subpattern has a prefix, a numeric
+ * part and a suffix. If there is no explicit negative subpattern, the negative
+ * subpattern is the localized minus sign prefixed to the positive subpattern.
+ * That is, "0.00" alone is equivalent to "0.00;-0.00". If there is an explicit
+ * negative subpattern, it serves only to specify the negative prefix and
+ * suffix; the number of digits, minimal digits, and other characteristics are
+ * ignored in the negative subpattern. This means that "#,##0.0#;(#)" produces
+ * precisely the same result as "#,##0.0#;(#,##0.0#)".
+ * <p>
+ * The prefixes, suffixes, and various symbols used for infinity, digits,
+ * thousands separators, decimal separators, etc. may be set to arbitrary
+ * values, and they will appear properly during formatting. However, care must
+ * be taken that the symbols and strings do not conflict, or parsing will be
+ * unreliable. For example, either the positive and negative prefixes or the
+ * suffixes must be distinct for {@link #parse} to be able to distinguish
+ * positive from negative values. Another example is that the decimal separator
+ * and thousands separator should be distinct characters, or parsing will be
+ * impossible.
+ * <p>
+ * The <em>grouping separator</em> is a character that separates clusters of
+ * integer digits to make large numbers more legible. It is commonly used for
+ * thousands, but in some locales it separates ten-thousands. The <em>grouping
+ * size</em>
+ * is the number of digits between the grouping separators, such as 3 for
+ * "100,000,000" or 4 for "1 0000 0000". There are actually two different
+ * grouping sizes: One used for the least significant integer digits, the
+ * <em>primary grouping size</em>, and one used for all others, the
+ * <em>secondary grouping size</em>. In most locales these are the same, but
+ * sometimes they are different. For example, if the primary grouping interval
+ * is 3, and the secondary is 2, then this corresponds to the pattern
+ * "#,##,##0", and the number 123456789 is formatted as "12,34,56,789". If a
+ * pattern contains multiple grouping separators, the interval between the last
+ * one and the end of the integer defines the primary grouping size, and the
+ * interval between the last two defines the secondary grouping size. All others
+ * are ignored, so "#,##,###,####", "###,###,####" and "##,#,###,####" produce
+ * the same result.
+ * <p>
+ * Illegal patterns, such as "#.#.#" or "#.###,###", will cause
+ * {@code DecimalFormat} to throw an {@link IllegalArgumentException} with a
+ * message that describes the problem.
+ * <h4>Pattern BNF</h4>
+ *
+ * <pre>
+ * pattern := subpattern (';' subpattern)?
+ * subpattern := prefix? number exponent? suffix?
+ * number := (integer ('.' fraction)?) | sigDigits
+ * prefix := '\\u0000'..'\\uFFFD' - specialCharacters
+ * suffix := '\\u0000'..'\\uFFFD' - specialCharacters
+ * integer := '#'* '0'* '0'
+ * fraction := '0'* '#'*
+ * sigDigits := '#'* '@' '@'* '#'*
+ * exponent := 'E' '+'? '0'* '0'
+ * padSpec := '*' padChar
+ * padChar := '\\u0000'..'\\uFFFD' - quote
+ *
+ * Notation:
+ * X* 0 or more instances of X
+ * X? 0 or 1 instances of X
+ * X|Y either X or Y
+ * C..D any character from C up to D, inclusive
+ * S-T characters in S, except those in T
+ * </pre>
+ *
+ * The first subpattern is for positive numbers. The second (optional)
+ * subpattern is for negative numbers.
+ * <p>
+ * Not indicated in the BNF syntax above:
+ * <ul>
+ * <li>The grouping separator ',' can occur inside the integer and sigDigits
+ * elements, between any two pattern characters of that element, as long as the
+ * integer or sigDigits element is not followed by the exponent element.
+ * <li><font color="red"><strong>NEW</strong> </font> Two
+ * grouping intervals are recognized: The one between the decimal point and the
+ * first grouping symbol and the one between the first and second grouping
+ * symbols. These intervals are identical in most locales, but in some locales
+ * they differ. For example, the pattern "#,##,###" formats the number
+ * 123456789 as "12,34,56,789".</li>
+ * <li> <strong><font color="red">NEW</font> </strong> The pad
+ * specifier {@code padSpec} may appear before the prefix, after the prefix,
+ * before the suffix, after the suffix or not at all.
+ * </ul>
+ * <h4>Parsing</h4>
+ * <p>
+ * {@code DecimalFormat} parses all Unicode characters that represent decimal
+ * digits, as defined by {@link Character#digit(int, int)}. In addition,
+ * {@code DecimalFormat} also recognizes as digits the ten consecutive
+ * characters starting with the localized zero digit defined in the
+ * {@link DecimalFormatSymbols} object. During formatting, the
+ * {@link DecimalFormatSymbols}-based digits are written out.
+ * <p>
+ * During parsing, grouping separators are ignored.
+ * <p>
+ * If {@link #parse(String, ParsePosition)} fails to parse a string, it returns
+ * {@code null} and leaves the parse position unchanged.
+ * <h4>Formatting</h4>
+ * <p>
+ * Formatting is guided by several parameters, all of which can be specified
+ * either using a pattern or using the API. The following description applies to
+ * formats that do not use <a href="#sci">scientific notation</a> or <a
+ * href="#sigdig">significant digits</a>.
+ * <ul>
+ * <li>If the number of actual integer digits exceeds the
+ * <em>maximum integer digits</em>, then only the least significant digits
+ * are shown. For example, 1997 is formatted as "97" if maximum integer digits
+ * is set to 2.
+ * <li>If the number of actual integer digits is less than the
+ * <em>minimum integer digits</em>, then leading zeros are added. For
+ * example, 1997 is formatted as "01997" if minimum integer digits is set to 5.
+ * <li>If the number of actual fraction digits exceeds the <em>maximum
+ * fraction digits</em>,
+ * then half-even rounding is performed to the maximum fraction digits. For
+ * example, 0.125 is formatted as "0.12" if the maximum fraction digits is 2.
+ * <li>If the number of actual fraction digits is less than the
+ * <em>minimum fraction digits</em>, then trailing zeros are added. For
+ * example, 0.125 is formatted as "0.1250" if the mimimum fraction digits is set
+ * to 4.
+ * <li>Trailing fractional zeros are not displayed if they occur <em>j</em>
+ * positions after the decimal, where <em>j</em> is less than the maximum
+ * fraction digits. For example, 0.10004 is formatted as "0.1" if the maximum
+ * fraction digits is four or less.
+ * </ul>
+ * <p>
+ * <strong>Special Values</strong>
+ * <p>
+ * {@code NaN} is represented as a single character, typically
+ * {@code \uFFFD}. This character is determined by the
+ * {@link DecimalFormatSymbols} object. This is the only value for which the
+ * prefixes and suffixes are not used.
+ * <p>
+ * Infinity is represented as a single character, typically {@code \u221E},
+ * with the positive or negative prefixes and suffixes applied. The infinity
+ * character is determined by the {@link DecimalFormatSymbols} object. <a
+ * name="sci">
+ * <h4>Scientific Notation</h4>
+ * </a>
+ * <p>
+ * Numbers in scientific notation are expressed as the product of a mantissa and
+ * a power of ten, for example, 1234 can be expressed as 1.234 x 10<sup>3</sup>.
+ * The mantissa is typically in the half-open interval [1.0, 10.0) or sometimes
+ * [0.0, 1.0), but it does not need to be. {@code DecimalFormat} supports
+ * arbitrary mantissas. {@code DecimalFormat} can be instructed to use
+ * scientific notation through the API or through the pattern. In a pattern, the
+ * exponent character immediately followed by one or more digit characters
+ * indicates scientific notation. Example: "0.###E0" formats the number 1234 as
+ * "1.234E3".
+ * <ul>
+ * <li>The number of digit characters after the exponent character gives the
+ * minimum exponent digit count. There is no maximum. Negative exponents are
+ * formatted using the localized minus sign, <em>not</em> the prefix and
+ * suffix from the pattern. This allows patterns such as "0.###E0 m/s". To
+ * prefix positive exponents with a localized plus sign, specify '+' between the
+ * exponent and the digits: "0.###E+0" will produce formats "1E+1", "1E+0",
+ * "1E-1", etc. (In localized patterns, use the localized plus sign rather than
+ * '+'.)
+ * <li>The minimum number of integer digits is achieved by adjusting the
+ * exponent. Example: 0.00123 formatted with "00.###E0" yields "12.3E-4". This
+ * only happens if there is no maximum number of integer digits. If there is a
+ * maximum, then the minimum number of integer digits is fixed at one.
+ * <li>The maximum number of integer digits, if present, specifies the exponent
+ * grouping. The most common use of this is to generate <em>engineering
+ * notation</em>,
+ * in which the exponent is a multiple of three, e.g., "##0.###E0". The number
+ * 12345 is formatted using "##0.###E0" as "12.345E3".
+ * <li>When using scientific notation, the formatter controls the digit counts
+ * using significant digits logic. The maximum number of significant digits
+ * limits the total number of integer and fraction digits that will be shown in
+ * the mantissa; it does not affect parsing. For example, 12345 formatted with
+ * "##0.##E0" is "12.3E3". See the section on significant digits for more
+ * details.
+ * <li>The number of significant digits shown is determined as follows: If no
+ * significant digits are used in the pattern then the minimum number of
+ * significant digits shown is one, the maximum number of significant digits
+ * shown is the sum of the <em>minimum integer</em> and
+ * <em>maximum fraction</em> digits, and it is unaffected by the maximum
+ * integer digits. If this sum is zero, then all significant digits are shown.
+ * If significant digits are used in the pattern then the number of integer
+ * digits is fixed at one and there is no exponent grouping.
+ * <li>Exponential patterns may not contain grouping separators.
+ * </ul>
+ * <a name="sigdig">
+ * <h4> <strong><font color="red">NEW</font> </strong> Significant
+ * Digits</h4>
+ * <p>
+ * </a> {@code DecimalFormat} has two ways of controlling how many digits are
+ * shown: (a) significant digit counts or (b) integer and fraction digit counts.
+ * Integer and fraction digit counts are described above. When a formatter uses
+ * significant digits counts, the number of integer and fraction digits is not
+ * specified directly, and the formatter settings for these counts are ignored.
+ * Instead, the formatter uses as many integer and fraction digits as required
+ * to display the specified number of significant digits.
+ * <h5>Examples:</h5>
+ * <blockquote> <table border=0 cellspacing=3 cellpadding=0>
+ * <tr bgcolor="#ccccff">
+ * <th align="left">Pattern</th>
+ * <th align="left">Minimum significant digits</th>
+ * <th align="left">Maximum significant digits</th>
+ * <th align="left">Number</th>
+ * <th align="left">Output of format()</th>
+ * </tr>
+ * <tr valign="top">
+ * <td>{@code @@@}
+ * <td>3</td>
+ * <td>3</td>
+ * <td>12345</td>
+ * <td>{@code 12300}</td>
+ * </tr>
+ * <tr valign="top" bgcolor="#eeeeff">
+ * <td>{@code @@@}</td>
+ * <td>3</td>
+ * <td>3</td>
+ * <td>0.12345</td>
+ * <td>{@code 0.123}</td>
+ * </tr>
+ * <tr valign="top">
+ * <td>{@code @@##}</td>
+ * <td>2</td>
+ * <td>4</td>
+ * <td>3.14159</td>
+ * <td>{@code 3.142}</td>
+ * </tr>
+ * <tr valign="top" bgcolor="#eeeeff">
+ * <td>{@code @@##}</td>
+ * <td>2</td>
+ * <td>4</td>
+ * <td>1.23004</td>
+ * <td>{@code 1.23}</td>
+ * </tr>
+ * </table> </blockquote>
+ * <ul>
+ * <li>Significant digit counts may be expressed using patterns that specify a
+ * minimum and maximum number of significant digits. These are indicated by the
+ * {@code '@'} and {@code '#'} characters. The minimum number of significant
+ * digits is the number of {@code '@'} characters. The maximum number of
+ * significant digits is the number of {@code '@'} characters plus the number of
+ * {@code '#'} characters following on the right. For example, the pattern
+ * {@code "@@@"} indicates exactly 3 significant digits. The pattern
+ * {@code "@##"} indicates from 1 to 3 significant digits. Trailing zero digits
+ * to the right of the decimal separator are suppressed after the minimum number
+ * of significant digits have been shown. For example, the pattern {@code "@##"}
+ * formats the number 0.1203 as {@code "0.12"}.
+ * <li>If a pattern uses significant digits, it may not contain a decimal
+ * separator, nor the {@code '0'} pattern character. Patterns such as
+ * {@code "@00"} or {@code "@.###"} are disallowed.
+ * <li>Any number of {@code '#'} characters may be prepended to the left of the
+ * leftmost {@code '@'} character. These have no effect on the minimum and
+ * maximum significant digit counts, but may be used to position grouping
+ * separators. For example, {@code "#,#@#"} indicates a minimum of one
+ * significant digit, a maximum of two significant digits, and a grouping size
+ * of three.
+ * <li>In order to enable significant digits formatting, use a pattern
+ * containing the {@code '@'} pattern character.
+ * <li>In order to disable significant digits formatting, use a pattern that
+ * does not contain the {@code '@'} pattern character.
+ * <li>The number of significant digits has no effect on parsing.
+ * <li>Significant digits may be used together with exponential notation. Such
+ * patterns are equivalent to a normal exponential pattern with a minimum and
+ * maximum integer digit count of one, a minimum fraction digit count of the
+ * number of '@' characters in the pattern - 1, and a maximum fraction digit
+ * count of the number of '@' and '#' characters in the pattern - 1. For
+ * example, the pattern {@code "@@###E0"} is equivalent to {@code "0.0###E0"}.
+ * <li>If signficant digits are in use then the integer and fraction digit
+ * counts, as set via the API, are ignored.
+ * </ul>
+ * <h4> <strong><font color="red">NEW</font> </strong> Padding</h4>
+ * <p>
+ * {@code DecimalFormat} supports padding the result of {@code format} to a
+ * specific width. Padding may be specified either through the API or through
+ * the pattern syntax. In a pattern, the pad escape character followed by a
+ * single pad character causes padding to be parsed and formatted. The pad
+ * escape character is '*' in unlocalized patterns. For example,
+ * {@code "$*x#,##0.00"} formats 123 to {@code "$xx123.00"}, and 1234 to
+ * {@code "$1,234.00"}.
+ * <ul>
+ * <li>When padding is in effect, the width of the positive subpattern,
+ * including prefix and suffix, determines the format width. For example, in the
+ * pattern {@code "* #0 o''clock"}, the format width is 10.</li>
+ * <li>The width is counted in 16-bit code units (Java {@code char}s).</li>
+ * <li>Some parameters which usually do not matter have meaning when padding is
+ * used, because the pattern width is significant with padding. In the pattern "*
+ * ##,##,#,##0.##", the format width is 14. The initial characters "##,##," do
+ * not affect the grouping size or maximum integer digits, but they do affect
+ * the format width.</li>
+ * <li>Padding may be inserted at one of four locations: before the prefix,
+ * after the prefix, before the suffix or after the suffix. If padding is
+ * specified in any other location, {@link #applyPattern} throws an {@link
+ * IllegalArgumentException}. If there is no prefix, before the prefix and after
+ * the prefix are equivalent, likewise for the suffix.</li>
+ * <li>When specified in a pattern, the 16-bit {@code char} immediately
+ * following the pad escape is the pad character. This may be any character,
+ * including a special pattern character. That is, the pad escape
+ * <em>escapes</em> the following character. If there is no character after
+ * the pad escape, then the pattern is illegal.</li>
+ * </ul>
+ * <h4>Synchronization</h4>
+ * <p>
+ * {@code DecimalFormat} objects are not synchronized. Multiple threads should
+ * not access one formatter concurrently.
+ *
+ * @see Format
+ * @see NumberFormat
*/
public class DecimalFormat extends NumberFormat {
@@ -50,8 +553,8 @@
private transient int serialVersionOnStream = 3;
/**
- * Constructs a new DecimalFormat for formatting and parsing numbers for the
- * default Locale.
+ * Constructs a new {@code DecimalFormat} for formatting and parsing numbers
+ * for the default locale.
*/
public DecimalFormat() {
Locale locale = Locale.getDefault();
@@ -66,14 +569,13 @@
}
/**
- * Constructs a new DecimalFormat using the specified non-localized pattern
- * and the DecimalFormatSymbols for the default Locale.
+ * Constructs a new {@code DecimalFormat} using the specified non-localized
+ * pattern and the {@code DecimalFormatSymbols} for the default Locale.
*
* @param pattern
- * the non-localized pattern
- *
- * @exception IllegalArgumentException
- * when the pattern cannot be parsed
+ * the non-localized pattern.
+ * @throws IllegalArgumentException
+ * if the pattern cannot be parsed.
*/
public DecimalFormat(String pattern) {
Locale locale = Locale.getDefault();
@@ -88,16 +590,15 @@
}
/**
- * Constructs a new DecimalFormat using the specified non-localized pattern
- * and DecimalFormatSymbols.
+ * Constructs a new {@code DecimalFormat} using the specified non-localized
+ * pattern and {@code DecimalFormatSymbols}.
*
* @param pattern
- * the non-localized pattern
+ * the non-localized pattern.
* @param value
- * the DecimalFormatSymbols
- *
- * @exception IllegalArgumentException
- * when the pattern cannot be parsed
+ * the DecimalFormatSymbols.
+ * @throws IllegalArgumentException
+ * if the pattern cannot be parsed.
*/
public DecimalFormat(String pattern, DecimalFormatSymbols value) {
symbols = (DecimalFormatSymbols) value.clone();
@@ -114,28 +615,26 @@
}
/**
- * Changes the pattern of this DecimalFormat to the specified pattern which
+ * Changes the pattern of this decimal format to the specified pattern which
* uses localized pattern characters.
*
* @param pattern
- * the localized pattern
- *
- * @exception IllegalArgumentException
- * when the pattern cannot be parsed
+ * the localized pattern.
+ * @throws IllegalArgumentException
+ * if the pattern cannot be parsed.
*/
public void applyLocalizedPattern(String pattern) {
dform.applyLocalizedPattern(pattern);
}
/**
- * Changes the pattern of this SimpleDateFormat to the specified pattern
- * which uses non-localized pattern characters.
+ * Changes the pattern of this decimal format to the specified pattern which
+ * uses non-localized pattern characters.
*
* @param pattern
- * the non-localized pattern
- *
- * @exception IllegalArgumentException
- * when the pattern cannot be parsed
+ * the non-localized pattern.
+ * @throws IllegalArgumentException
+ * if the pattern cannot be parsed.
*/
public void applyPattern(String pattern) {
@@ -143,11 +642,10 @@
}
/**
- * Answers a new instance of DecimalFormat with the same pattern and
- * properties as this DecimalFormat.
- *
- * @return a shallow copy of this DecimalFormat
+ * Returns a new instance of {@code DecimalFormat} with the same pattern and
+ * properties as this decimal format.
*
+ * @return a shallow copy of this decimal format.
* @see java.lang.Cloneable
*/
@Override
@@ -159,15 +657,14 @@
}
/**
- * Compares the specified object to this DecimalFormat and answer if they
- * are equal. The object must be an instance of DecimalFormat with the same
- * pattern and properties.
+ * Compares the specified object to this decimal format and indicates if
+ * they are equal. In order to be equal, {@code object} must be an instance
+ * of {@code DecimalFormat} with the same pattern and properties.
*
* @param object
- * the object to compare with this object
- * @return true if the specified object is equal to this DecimalFormat,
- * false otherwise
- *
+ * the object to compare with this object.
+ * @return {@code true} if the specified object is equal to this decimal
+ * format; {@code false} otherwise.
* @see #hashCode
*/
@Override
@@ -184,19 +681,18 @@
}
/**
- * Formats the specified object using the rules of this DecimalNumberFormat
- * and returns an AttributedCharacterIterator with the formatted number and
- * attributes.
+ * Formats the specified object using the rules of this decimal format and
+ * returns an {@code AttributedCharacterIterator} with the formatted number
+ * and attributes.
*
* @param object
- * the object to format
+ * the object to format.
* @return an AttributedCharacterIterator with the formatted number and
- * attributes
- *
- * @exception NullPointerException
- * when the object is null
- * @exception IllegalArgumentException
- * when the object cannot be formatted by this Format
+ * attributes.
+ * @throws IllegalArgumentException
+ * if {@code object} cannot be formatted by this format.
+ * @throws NullPointerException
+ * if {@code object} is {@code null}.
*/
@Override
public AttributedCharacterIterator formatToCharacterIterator(Object object) {
@@ -207,18 +703,23 @@
}
/**
- * Formats the double value into the specified StringBuffer using the
- * pattern of this DecimalFormat. If the field specified by the
- * FieldPosition is formatted, set the begin and end index of the formatted
- * field in the FieldPosition.
- *
+ * Formats the specified double value as a string using the pattern of this
+ * decimal format and appends the string to the specified string buffer.
+ * <p>
+ * If the {@code field} member of {@code position} contains a value
+ * specifying a format field, then its {@code beginIndex} and
+ * {@code endIndex} members will be updated with the position of the first
+ * occurrence of this field in the formatted text.
+ *
* @param value
- * the double to format
+ * the double to format.
* @param buffer
- * the StringBuffer
+ * the target string buffer to append the formatted double value
+ * to.
* @param position
- * the FieldPosition
- * @return the StringBuffer parameter <code>buffer</code>
+ * on input: an optional alignment field; on output: the offsets
+ * of the alignment field in the formatted text.
+ * @return the string buffer.
*/
@Override
public StringBuffer format(double value, StringBuffer buffer,
@@ -227,18 +728,23 @@
}
/**
- * Formats the long value into the specified StringBuffer using the pattern
- * of this DecimalFormat. If the field specified by the FieldPosition is
- * formatted, set the begin and end index of the formatted field in the
- * FieldPosition.
- *
+ * Formats the specified long value as a string using the pattern of this
+ * decimal format and appends the string to the specified string buffer.
+ * <p>
+ * If the {@code field} member of {@code position} contains a value
+ * specifying a format field, then its {@code beginIndex} and
+ * {@code endIndex} members will be updated with the position of the first
+ * occurrence of this field in the formatted text.
+ *
* @param value
- * the long to format
+ * the long to format.
* @param buffer
- * the StringBuffer
+ * the target string buffer to append the formatted long value
+ * to.
* @param position
- * the FieldPosition
- * @return the StringBuffer parameter <code>buffer</code>
+ * on input: an optional alignment field; on output: the offsets
+ * of the alignment field in the formatted text.
+ * @return the string buffer.
*/
@Override
public StringBuffer format(long value, StringBuffer buffer,
@@ -247,20 +753,26 @@
}
/**
- * Formats the number into the specified StringBuffer using the pattern of
- * this DecimalFormat. If the field specified by the FieldPosition is
- * formatted, set the begin and end index of the formatted field in the
- * FieldPosition.
- *
+ * Formats the specified object as a string using the pattern of this
+ * decimal format and appends the string to the specified string buffer.
+ * <p>
+ * If the {@code field} member of {@code position} contains a value
+ * specifying a format field, then its {@code beginIndex} and
+ * {@code endIndex} members will be updated with the position of the first
+ * occurrence of this field in the formatted text.
+ *
* @param number
- * the object to format
+ * the object to format.
* @param toAppendTo
- * the StringBuffer
+ * the target string buffer to append the formatted number to.
* @param pos
- * the FieldPosition
- * @return the StringBuffer parameter <code>buffer</code>
+ * on input: an optional alignment field; on output: the offsets
+ * of the alignment field in the formatted text.
+ * @return the string buffer.
* @throws IllegalArgumentException
- * if the given number is not instance of <code>Number</code>
+ * if {@code number} is not an instance of {@code Number}.
+ * @throws NullPointerException
+ * if {@code toAppendTo} or {@code pos} is {@code null}.
*/
@Override
public final StringBuffer format(Object number, StringBuffer toAppendTo,
@@ -278,18 +790,19 @@
}
/**
- * Answers the DecimalFormatSymbols used by this DecimalFormat.
+ * Returns the {@code DecimalFormatSymbols} used by this decimal format.
*
- * @return a DecimalFormatSymbols
+ * @return a copy of the {@code DecimalFormatSymbols} used by this decimal
+ * format.
*/
public DecimalFormatSymbols getDecimalFormatSymbols() {
return (DecimalFormatSymbols) symbols.clone();
}
/**
- * Answers the currency used by this decimal format.
+ * Returns the currency used by this decimal format.
*
- * @return currency of DecimalFormatSymbols used by this decimal format
+ * @return the currency used by this decimal format.
* @see DecimalFormatSymbols#getCurrency()
*/
@Override
@@ -301,120 +814,118 @@
}
/**
- * Answers the number of digits grouped together by the grouping separator.
- *
- * @return the number of digits grouped together
+ * Returns the number of digits grouped together by the grouping separator.
+ * This only allows to get the primary grouping size. There is no API to get
+ * the secondary grouping size.
+ *
+ * @return the number of digits grouped together.
*/
public int getGroupingSize() {
return dform.getGroupingSize();
}
/**
- * Answers the multiplier which is applied to the number before formatting
+ * Returns the multiplier which is applied to the number before formatting
* or after parsing.
*
- * @return the multiplier
+ * @return the multiplier.
*/
public int getMultiplier() {
return dform.getMultiplier();
}
/**
- * Answers the prefix which is formatted or parsed before a negative number.
+ * Returns the prefix which is formatted or parsed before a negative number.
*
- * @return the negative prefix
+ * @return the negative prefix.
*/
public String getNegativePrefix() {
return dform.getNegativePrefix();
}
/**
- * Answers the suffix which is formatted or parsed after a negative number.
+ * Returns the suffix which is formatted or parsed after a negative number.
*
- * @return the negative suffix
+ * @return the negative suffix.
*/
public String getNegativeSuffix() {
return dform.getNegativeSuffix();
}
/**
- * Answers the prefix which is formatted or parsed before a positive number.
+ * Returns the prefix which is formatted or parsed before a positive number.
*
- * @return the positive prefix
+ * @return the positive prefix.
*/
public String getPositivePrefix() {
return dform.getPositivePrefix();
}
/**
- * Answers the suffix which is formatted or parsed after a positive number.
+ * Returns the suffix which is formatted or parsed after a positive number.
*
- * @return the positive suffix
+ * @return the positive suffix.
*/
public String getPositiveSuffix() {
return dform.getPositiveSuffix();
}
- /**
- * Answers an integer hash code for the receiver. Objects which are equal
- * answer the same value for this method.
- *
- * @return the receiver's hash
- *
- * @see #equals
- */
@Override
public int hashCode() {
return dform.hashCode();
}
/**
- * Answers whether the decimal separator is shown when there are no
+ * Indicates whether the decimal separator is shown when there are no
* fractional digits.
*
- * @return true if the decimal separator should always be formatted, false
- * otherwise
+ * @return {@code true} if the decimal separator should always be formatted;
+ * {@code false} otherwise.
*/
public boolean isDecimalSeparatorAlwaysShown() {
return dform.isDecimalSeparatorAlwaysShown();
}
/**
- * This value indicates whether the return object of the parse operation
- * will be of type BigDecimal. This value will default to false.
+ * This value indicates whether the return object of the parse operation is
+ * of type {@code BigDecimal}. This value defaults to {@code false}.
*
- * @return true and parse will always return BigDecimals, false and the type
- * of the result will be Long or Double.
+ * @return {@code true} if parse always returns {@code BigDecimals},
+ * {@code false} if the type of the result is {@code Long} or
+ * {@code Double}.
*/
public boolean isParseBigDecimal() {
return this.parseBigDecimal;
}
/**
- * When DecimalFormat is used to parsing, and this value is set to true,
- * then all the resulting number will be of type
- * <code>java.lang.Integer</code>. Except that, NaN, positive and
- * negative infinity are still returned as <code>java.lang.Double</code>
- *
- * In this implementation, com.ibm.icu.text.DecimalFormat is wrapped to
- * fulfill most of the format and parse feature. And this method is
- * delegated to the wrapped instance of com.ibm.icu.text.DecimalFormat.
+ * Sets the flag that indicates whether numbers will be parsed as integers.
+ * When this decimal format is used for parsing and this value is set to
+ * {@code true}, then the resulting numbers will be of type
+ * {@code java.lang.Integer}. Special cases are NaN, positive and negative
+ * infinity, which are still returned as {@code java.lang.Double}.
*
+ *
* @param value
- * If set to true, all the resulting number will be of type
- * java.lang.Integer except some special cases.
+ * {@code true} that the resulting numbers of parse operations
+ * will be of type {@code java.lang.Integer} except for the
+ * special cases described above.
*/
@Override
public void setParseIntegerOnly(boolean value) {
+ // In this implementation, com.ibm.icu.text.DecimalFormat is wrapped to
+ // fulfill most of the format and parse feature. And this method is
+ // delegated to the wrapped instance of com.ibm.icu.text.DecimalFormat.
+
dform.setParseIntegerOnly(value);
}
/**
- * Returns true if this <code>DecimalFormat</code>'s all resulting number
- * will be of type <code>java.lang.Integer</code>
+ * Indicates whether parsing with this decimal format will only
+ * return numbers of type {@code java.lang.Integer}.
*
- * @return true if this <code>DecimalFormat</code>'s all resulting number
- * will be of type <code>java.lang.Integer</code>
+ * @return {@code true} if this {@code DecimalFormat}'s parse method only
+ * returns {@code java.lang.Integer}; {@code false} otherwise.
*/
@Override
public boolean isParseIntegerOnly() {
@@ -424,20 +935,27 @@
private static final Double NEGATIVE_ZERO_DOUBLE = new Double(-0.0);
/**
- * Parse a Long or Double from the specified String starting at the index
- * specified by the ParsePosition. If the string is successfully parsed, the
- * index of the ParsePosition is updated to the index following the parsed
- * text.
+ * Parses a {@code Long} or {@code Double} from 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
+ * the string to parse.
* @param position
- * the ParsePosition, updated on return with the index following
- * the parsed text, or on error the index is unchanged and the
- * error index is set to the index where the error occurred
- * @return a Long or Double resulting from the parse, or null if there is an
- * error. The result will be a Long if the parsed number is an
- * integer in the range of a long, otherwise the result is a Double.
+ * 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 a {@code Long} or {@code Double} resulting from the parse or
+ * {@code null} if there is an error. The result will be a
+ * {@code Long} if the parsed number is an integer in the range of a
+ * long, otherwise the result is a {@code Double}. If
+ * {@code isParseBigDecimal} is {@code true} then it returns the
+ * result as a {@code BigDecimal}.
*/
@Override
public Number parse(String string, ParsePosition position) {
@@ -475,10 +993,10 @@
}
/**
- * Sets the DecimalFormatSymbols used by this DecimalFormat.
+ * Sets the {@code DecimalFormatSymbols} used by this decimal format.
*
* @param value
- * the DecimalFormatSymbols
+ * the {@code DecimalFormatSymbols} to set.
*/
public void setDecimalFormatSymbols(DecimalFormatSymbols value) {
if (value != null) {
@@ -494,6 +1012,7 @@
* digits remain the same.
*
* @param currency
+ * the currency this {@code DecimalFormat} should use.
* @see DecimalFormatSymbols#setCurrency(Currency)
*/
@Override
@@ -508,8 +1027,8 @@
* digits.
*
* @param value
- * true if the decimal separator should always be formatted,
- * false otherwise
+ * {@code true} if the decimal separator should always be
+ * formatted; {@code false} otherwise.
*/
public void setDecimalSeparatorAlwaysShown(boolean value) {
dform.setDecimalSeparatorAlwaysShown(value);
@@ -517,9 +1036,11 @@
/**
* Sets the number of digits grouped together by the grouping separator.
- *
+ * This only allows to set the primary grouping size; the secondary grouping
+ * size can only be set with a pattern.
+ *
* @param value
- * the number of digits grouped together
+ * the number of digits grouped together.
*/
public void setGroupingSize(int value) {
dform.setGroupingSize(value);
@@ -530,8 +1051,7 @@
* affects both parsing and formatting.
*
* @param value
- * true if uses grouping,false otherwise.
- *
+ * {@code true} if grouping is used; {@code false} otherwise.
*/
@Override
public void setGroupingUsed(boolean value) {
@@ -539,9 +1059,9 @@
}
/**
- * This value indicates whether grouping will be used in this format.
+ * Indicates whether grouping will be used in this format.
*
- * @return true if grouping is used,false otherwise.
+ * @return {@code true} if grouping is used; {@code false} otherwise.
*/
@Override
public boolean isGroupingUsed() {
@@ -550,12 +1070,14 @@
/**
* Sets the maximum number of fraction digits that are printed when
- * formatting. If the maximum is less than the number of fraction digits,
- * the least significant digits are truncated. Limit the maximum to
- * DOUBLE_FRACTION_DIGITS.
+ * formatting numbers other than {@code BigDecimal} and {@code BigInteger}.
+ * If the maximum is less than the number of fraction digits, the least
+ * significant digits are truncated. If the value passed is bigger than 340
+ * then it is replaced by 340. If the value passed is negative then it is
+ * replaced by 0.
*
* @param value
- * the maximum number of fraction digits
+ * the maximum number of fraction digits.
*/
@Override
public void setMaximumFractionDigits(int value) {
@@ -565,12 +1087,14 @@
/**
* Sets the maximum number of integer digits that are printed when
- * formatting. If the maximum is less than the number of integer digits, the
- * most significant digits are truncated. Limit the maximum to
- * DOUBLE_INTEGER_DIGITS.
+ * formatting numbers other than {@code BigDecimal} and {@code BigInteger}.
+ * If the maximum is less than the number of integer digits, the most
+ * significant digits are truncated. If the value passed is bigger than 309
+ * then it is replaced by 309. If the value passed is negative then it is
+ * replaced by 0.
*
* @param value
- * the maximum number of integer digits
+ * the maximum number of integer digits.
*/
@Override
public void setMaximumIntegerDigits(int value) {
@@ -580,10 +1104,12 @@
/**
* Sets the minimum number of fraction digits that are printed when
- * formatting. Limit the minimum to DOUBLE_FRACTION_DIGITS.
+ * formatting numbers other than {@code BigDecimal} and {@code BigInteger}.
+ * If the value passed is bigger than 340 then it is replaced by 340. If the
+ * value passed is negative then it is replaced by 0.
*
* @param value
- * the minimum number of fraction digits
+ * the minimum number of fraction digits.
*/
@Override
public void setMinimumFractionDigits(int value) {
@@ -593,10 +1119,12 @@
/**
* Sets the minimum number of integer digits that are printed when
- * formatting. Limit the minimum to DOUBLE_INTEGER_DIGITS.
+ * formatting numbers other than {@code BigDecimal} and {@code BigInteger}.
+ * If the value passed is bigger than 309 then it is replaced by 309. If the
+ * value passed is negative then it is replaced by 0.
*
* @param value
- * the minimum number of integer digits
+ * the minimum number of integer digits.
*/
@Override
public void setMinimumIntegerDigits(int value) {
@@ -609,7 +1137,7 @@
* after parsing.
*
* @param value
- * the multiplier
+ * the multiplier.
*/
public void setMultiplier(int value) {
dform.setMultiplier(value);
@@ -619,7 +1147,7 @@
* Sets the prefix which is formatted or parsed before a negative number.
*
* @param value
- * the negative prefix
+ * the negative prefix.
*/
public void setNegativePrefix(String value) {
dform.setNegativePrefix(value);
@@ -629,7 +1157,7 @@
* Sets the suffix which is formatted or parsed after a negative number.
*
* @param value
- * the negative suffix
+ * the negative suffix.
*/
public void setNegativeSuffix(String value) {
dform.setNegativeSuffix(value);
@@ -639,7 +1167,7 @@
* Sets the prefix which is formatted or parsed before a positive number.
*
* @param value
- * the positive prefix
+ * the positive prefix.
*/
public void setPositivePrefix(String value) {
dform.setPositivePrefix(value);
@@ -649,38 +1177,39 @@
* Sets the suffix which is formatted or parsed after a positive number.
*
* @param value
- * the positive suffix
+ * the positive suffix.
*/
public void setPositiveSuffix(String value) {
dform.setPositiveSuffix(value);
}
/**
- * Let users change the behavior of a DecimalFormat, If set to true all the
- * returned objects will be of type BigDecimal
+ * Sets the behaviour of the parse method. If set to {@code true} then all
+ * the returned objects will be of type {@code BigDecimal}.
*
* @param newValue
- * true if all the returned objects should be type of BigDecimal
+ * {@code true} if all the returned objects should be of type
+ * {@code BigDecimal}; {@code false} otherwise.
*/
public void setParseBigDecimal(boolean newValue) {
this.parseBigDecimal = newValue;
}
/**
- * Answers the pattern of this DecimalFormat using localized pattern
+ * Returns the pattern of this decimal format using localized pattern
* characters.
*
- * @return the localized pattern
+ * @return the localized pattern.
*/
public String toLocalizedPattern() {
return dform.toLocalizedPattern();
}
/**
- * Answers the pattern of this DecimalFormat using non-localized pattern
+ * Returns the pattern of this decimal format using non-localized pattern
* characters.
*
- * @return the non-localized pattern
+ * @return the non-localized pattern.
*/
public String toPattern() {
return dform.toPattern();
Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DecimalFormatSymbols.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DecimalFormatSymbols.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DecimalFormatSymbols.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/DecimalFormatSymbols.java Thu May 7 08:42:00 2009
@@ -27,8 +27,15 @@
import java.util.Locale;
/**
- * DecimalFormatSymbols holds the symbols used in the formating and parsing of
- * numbers.
+ * Encapsulates the set of symbols (such as the decimal separator, the grouping
+ * separator, and so on) needed by {@code DecimalFormat} to format numbers.
+ * {@code DecimalFormat} internally creates an instance of
+ * {@code DecimalFormatSymbols} from its locale data. If you need to change any
+ * of these symbols, you can get the {@code DecimalFormatSymbols} object from
+ * your {@code DecimalFormat} and modify it.
+ *
+ * @see java.util.Locale
+ * @see DecimalFormat
*/
public final class DecimalFormatSymbols implements Cloneable, Serializable {
@@ -48,8 +55,10 @@
private String infinity, NaN, currencySymbol, intlCurrencySymbol;
/**
- * Constructs a new DecimalFormatSymbols containing the symbols for the
- * default Locale.
+ * Constructs a new {@code DecimalFormatSymbols} containing the symbols for
+ * the default locale. Best practice is to create a {@code DecimalFormat}
+ * and then to get the {@code DecimalFormatSymbols} from that object by
+ * calling {@link DecimalFormat#getDecimalFormatSymbols()}.
*/
public DecimalFormatSymbols() {
this(Locale.getDefault());
@@ -57,10 +66,12 @@
/**
* Constructs a new DecimalFormatSymbols containing the symbols for the
- * specified Locale.
+ * specified Locale. Best practice is to create a {@code DecimalFormat}
+ * and then to get the {@code DecimalFormatSymbols} from that object by
+ * calling {@link DecimalFormat#getDecimalFormatSymbols()}.
*
* @param locale
- * the Locale
+ * the locale.
*/
public DecimalFormatSymbols(Locale locale) {
com.ibm.icu.text.DecimalFormatSymbols icuSymbols = new com.ibm.icu.text.DecimalFormatSymbols(
@@ -90,10 +101,10 @@
}
/**
- * Answers a new DecimalFormatSymbols with the same symbols as this
- * DecimalFormatSymbols.
+ * Returns a new {@code DecimalFormatSymbols} with the same symbols as this
+ * {@code DecimalFormatSymbols}.
*
- * @return a shallow copy of this DecimalFormatSymbols
+ * @return a shallow copy of this {@code DecimalFormatSymbols}.
*
* @see java.lang.Cloneable
*/
@@ -109,15 +120,14 @@
}
/**
- * Compares the specified object to this DecimalFormatSymbols and answer if
- * they are equal. The object must be an instance of DecimalFormatSymbols
- * with the same symbols.
+ * Compares the specified object to this {@code DecimalFormatSymbols} and
+ * indicates if they are equal. In order to be equal, {@code object} must be
+ * an instance of {@code DecimalFormatSymbols} and contain the same symbols.
*
* @param object
- * the object to compare with this object
- * @return true if the specified object is equal to this
- * DecimalFormatSymbols, false otherwise
- *
+ * the object to compare with this object.
+ * @return {@code true} if the specified object is equal to this
+ * {@code DecimalFormatSymbols}; {@code false} otherwise.
* @see #hashCode
*/
@Override
@@ -136,16 +146,16 @@
}
/**
- * Answers the currency.
+ * Returns the currency.
* <p>
- * <code>null<code> is returned
- * if <code>setInternationalCurrencySymbol()</code> has been previously called
- * with a value that is not a valid ISO 4217 currency code.
+ * {@code null} is returned if {@code setInternationalCurrencySymbol()} has
+ * been previously called with a value that is not a valid ISO 4217 currency
+ * code.
* <p>
*
- * @return the currency that was set in the constructor, <code>setCurrency()</code>,
- * or <code>setInternationalCurrencySymbol()</code>, or </code>null</code>
- *
+ * @return the currency that was set in the constructor or by calling
+ * {@code setCurrency()} or {@code setInternationalCurrencySymbol()},
+ * or {@code null} if an invalid currency was set.
* @see #setCurrency(Currency)
* @see #setInternationalCurrencySymbol(String)
*/
@@ -154,55 +164,55 @@
}
/**
- * Answers the international currency symbol.
+ * Returns the international currency symbol.
*
- * @return a String
+ * @return the international currency symbol as string.
*/
public String getInternationalCurrencySymbol() {
return intlCurrencySymbol;
}
/**
- * Answers the currency symbol.
+ * Returns the currency symbol.
*
- * @return a String
+ * @return the currency symbol as string.
*/
public String getCurrencySymbol() {
return currencySymbol;
}
/**
- * Answers the character which represents the decimal point in a number.
+ * Returns the character which represents the decimal point in a number.
*
- * @return a char
+ * @return the decimal separator character.
*/
public char getDecimalSeparator() {
return patternChars[DecimalSeparator];
}
/**
- * Answers the character which represents a single digit in a format
+ * Returns the character which represents a single digit in a format
* pattern.
*
- * @return a char
+ * @return the digit pattern character.
*/
public char getDigit() {
return patternChars[Digit];
}
/**
- * Answers the character used as the thousands separator in a number.
+ * Returns the character used as the thousands separator in a number.
*
- * @return a char
+ * @return the thousands separator character.
*/
public char getGroupingSeparator() {
return patternChars[GroupingSeparator];
}
/**
- * Answers the String which represents infinity.
+ * Returns the string which represents infinity.
*
- * @return a String
+ * @return the infinity symbol as a string.
*/
public String getInfinity() {
return infinity;
@@ -214,65 +224,65 @@
}
/**
- * Answers the minus sign character.
+ * Returns the minus sign character.
*
- * @return a char
+ * @return the minus sign as a character.
*/
public char getMinusSign() {
return patternChars[MinusSign];
}
/**
- * Answers the character which represents the decimal point in a monetary
+ * Returns the character which represents the decimal point in a monetary
* value.
*
- * @return a char
+ * @return the monetary decimal point as a character.
*/
public char getMonetaryDecimalSeparator() {
return patternChars[MonetaryDecimalSeparator];
}
/**
- * Answers the String which represents NaN.
+ * Returns the string which represents NaN.
*
- * @return a String
+ * @return the symbol NaN as a string.
*/
public String getNaN() {
return NaN;
}
/**
- * Answers the character which separates the positive and negative patterns
+ * Returns the character which separates the positive and negative patterns
* in a format pattern.
*
- * @return a char
+ * @return the pattern separator character.
*/
public char getPatternSeparator() {
return patternChars[PatternSeparator];
}
/**
- * Answers the percent character.
+ * Returns the percent character.
*
- * @return a char
+ * @return the percent character.
*/
public char getPercent() {
return patternChars[Percent];
}
/**
- * Answers the mille percent sign character.
+ * Returns the per mill sign character.
*
- * @return a char
+ * @return the per mill sign character.
*/
public char getPerMill() {
return patternChars[PerMill];
}
/**
- * Answers the character which represents zero.
+ * Returns the character which represents zero.
*
- * @return a char
+ * @return the zero character.
*/
public char getZeroDigit() {
return patternChars[ZeroDigit];
@@ -282,14 +292,6 @@
return patternChars[Exponent];
}
- /**
- * Answers an integer hash code for the receiver. Objects which are equal
- * answer the same value for this method.
- *
- * @return the receiver's hash
- *
- * @see #equals
- */
@Override
public int hashCode() {
return new String(patternChars).hashCode() + infinity.hashCode()
@@ -300,15 +302,14 @@
/**
* Sets the currency.
* <p>
- * The international currency symbol and currency symbol are updated, but
- * the min and max number of fraction digits stay the same.
+ * The international currency symbol and the currency symbol are updated,
+ * but the min and max number of fraction digits stays the same.
* <p>
*
* @param currency
- * the new currency
- *
- * @throws java.lang.NullPointerException
- * if currency is null
+ * the new currency.
+ * @throws NullPointerException
+ * if {@code currency} is {@code null}.
*/
public void setCurrency(Currency currency) {
if (currency == null) {
@@ -325,13 +326,13 @@
/**
* Sets the international currency symbol.
* <p>
- * currency and currency symbol also are updated, if <code>value</code> is
- * a valid ISO4217 currency code.
+ * The currency and currency symbol are also updated if {@code value} is a
+ * valid ISO4217 currency code.
* <p>
* The min and max number of fraction digits stay the same.
*
* @param value
- * currency code
+ * the currency code.
*/
public void setInternationalCurrencySymbol(String value) {
if (value == null) {
@@ -357,7 +358,7 @@
* Sets the currency symbol.
*
* @param value
- * a String
+ * the currency symbol.
*/
public void setCurrencySymbol(String value) {
currencySymbol = value;
@@ -367,7 +368,7 @@
* Sets the character which represents the decimal point in a number.
*
* @param value
- * the decimal separator character
+ * the decimal separator character.
*/
public void setDecimalSeparator(char value) {
patternChars[DecimalSeparator] = value;
@@ -377,7 +378,7 @@
* Sets the character which represents a single digit in a format pattern.
*
* @param value
- * the digit character
+ * the digit character.
*/
public void setDigit(char value) {
patternChars[Digit] = value;
@@ -387,17 +388,17 @@
* Sets the character used as the thousands separator in a number.
*
* @param value
- * the grouping separator character
+ * the grouping separator character.
*/
public void setGroupingSeparator(char value) {
patternChars[GroupingSeparator] = value;
}
/**
- * Sets the String which represents infinity.
+ * Sets the string which represents infinity.
*
* @param value
- * the String
+ * the string representing infinity.
*/
public void setInfinity(String value) {
infinity = value;
@@ -407,7 +408,7 @@
* Sets the minus sign character.
*
* @param value
- * the minus sign character
+ * the minus sign character.
*/
public void setMinusSign(char value) {
patternChars[MinusSign] = value;
@@ -418,17 +419,17 @@
* value.
*
* @param value
- * the monetary decimal separator character
+ * the monetary decimal separator character.
*/
public void setMonetaryDecimalSeparator(char value) {
patternChars[MonetaryDecimalSeparator] = value;
}
/**
- * Sets the String which represents NaN.
+ * Sets the string which represents NaN.
*
* @param value
- * the String
+ * the string representing NaN.
*/
public void setNaN(String value) {
NaN = value;
@@ -439,7 +440,7 @@
* a format pattern.
*
* @param value
- * the pattern separator character
+ * the pattern separator character.
*/
public void setPatternSeparator(char value) {
patternChars[PatternSeparator] = value;
@@ -449,17 +450,17 @@
* Sets the percent character.
*
* @param value
- * the percent character
+ * the percent character.
*/
public void setPercent(char value) {
patternChars[Percent] = value;
}
/**
- * Sets the mille percent sign character.
+ * Sets the per mill sign character.
*
* @param value
- * the mille percent character
+ * the per mill character.
*/
public void setPerMill(char value) {
patternChars[PerMill] = value;
@@ -469,7 +470,7 @@
* Sets the character which represents zero.
*
* @param value
- * the zero digit character
+ * the zero digit character.
*/
public void setZeroDigit(char value) {
patternChars[ZeroDigit] = value;
Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/FieldPosition.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/FieldPosition.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/FieldPosition.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/FieldPosition.java Thu May 7 08:42:00 2009
@@ -18,7 +18,16 @@
package java.text;
/**
- * FieldPosition is used to identify fields in formatted Strings.
+ * Identifies fields in formatted strings. If a {@code FieldPosition} is passed
+ * to the format method with such a parameter, then the indices will be set to
+ * the start and end indices of the field in the formatted string.
+ * <p>
+ * A {@code FieldPosition} can be created by using the integer constants in the
+ * various format classes (for example {@code NumberFormat.INTEGER_FIELD}) or
+ * one of the fields of type {@code Format.Field}.
+ * <p>
+ * If more than one field information is needed, the method
+ * {@link NumberFormat#formatToCharacterIterator(Object)} should be used.
*/
public class FieldPosition {
@@ -27,20 +36,21 @@
private Format.Field myAttribute;
/**
- * Constructs a new FieldPosition on the specified field.
+ * Constructs a new {@code FieldPosition} for the specified field.
*
* @param field
- * the field to identify
+ * the field to identify.
*/
public FieldPosition(int field) {
myField = field;
}
/**
- * Constructs a new FieldPosition on the specified Field attribute.
+ * Constructs a new {@code FieldPosition} for the specified {@code Field}
+ * attribute.
*
* @param attribute
- * the field attribute to identify
+ * the field attribute to identify.
*/
public FieldPosition(Format.Field attribute) {
myAttribute = attribute;
@@ -48,13 +58,13 @@
}
/**
- * Constructs a new FieldPosition on the specified Field attribute and field
- * id.
+ * Constructs a new {@code FieldPosition} for the specified {@code Field}
+ * attribute and field id.
*
* @param attribute
- * the field attribute to identify
+ * the field attribute to identify.
* @param field
- * the field to identify
+ * the field to identify.
*/
public FieldPosition(Format.Field attribute, int field) {
myAttribute = attribute;
@@ -66,15 +76,14 @@
}
/**
- * Compares the specified object to this FieldPosition and answer if they
- * are equal. The object must be an instance of FieldPosition with the same
- * field, begin index and end index.
+ * Compares the specified object to this field position and indicates if
+ * they are equal. In order to be equal, {@code object} must be an instance
+ * of {@code FieldPosition} with the same field, begin index and end index.
*
* @param object
- * the object to compare with this object
- * @return true if the specified object is equal to this fieldPosition,
- * false otherwise
- *
+ * the object to compare with this object.
+ * @return {@code true} if the specified object is equal to this field
+ * position; {@code false} otherwise.
* @see #hashCode
*/
@Override
@@ -88,49 +97,41 @@
}
/**
- * Answers the index of the beginning of the field.
+ * Returns the index of the beginning of the field.
*
- * @return the first index of the field
+ * @return the first index of the field.
*/
public int getBeginIndex() {
return beginIndex;
}
/**
- * Answers the index one past the end of the field.
+ * Returns the index one past the end of the field.
*
- * @return one past the index of the last character in the field
+ * @return one past the index of the last character in the field.
*/
public int getEndIndex() {
return endIndex;
}
/**
- * Answers the field which is being identified.
+ * Returns the field which is being identified.
*
- * @return the field
+ * @return the field constant.
*/
public int getField() {
return myField;
}
/**
- * Answers the attribute which is being identified.
+ * Returns the attribute which is being identified.
*
- * @return the field
+ * @return the field.
*/
public Format.Field getFieldAttribute() {
return myAttribute;
}
- /**
- * Answers an integer hash code for the receiver. Objects which are equal
- * answer the same value for this method.
- *
- * @return the receiver's hash
- *
- * @see #equals
- */
@Override
public int hashCode() {
int attributeHash = (myAttribute == null) ? 0 : myAttribute.hashCode();
@@ -141,7 +142,7 @@
* Sets the index of the beginning of the field.
*
* @param index
- * the index of the first character in the field
+ * the index of the first character in the field.
*/
public void setBeginIndex(int index) {
beginIndex = index;
@@ -151,16 +152,16 @@
* Sets the index of the end of the field.
*
* @param index
- * one past the index of the last character in the field
+ * one past the index of the last character in the field.
*/
public void setEndIndex(int index) {
endIndex = index;
}
/**
- * Answers the string representation of this FieldPosition.
+ * Returns the string representation of this field position.
*
- * @return the string representation of this FieldPosition
+ * @return the string representation of this field position.
*/
@Override
public String toString() {