harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r772552 [5/5] - /harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/
Date Thu, 07 May 2009 08:42:03 GMT
Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/RuleBasedCollator.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/RuleBasedCollator.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/RuleBasedCollator.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/RuleBasedCollator.java Thu May  7 08:42:00 2009
@@ -20,25 +20,245 @@
 import org.apache.harmony.text.internal.nls.Messages;
 
 /**
- * <code>RuleBasedCollator</code> is a concrete subclass of
- * <code>Collator</code>. It allows customization of the
- * <code>Collator</code> via user-specified rule sets.
- * <code>RuleBasedCollator</code> is designed to be fully compliant to the <a
- * href="http://www.unicode.org/unicode/reports/tr10/"> Unicode Collation
- * Algorithm (UCA) </a> and conforms to ISO 14651.
- * </p>
- * <p>
- * Create a <code>RuleBasedCollator</code> from a locale by calling the
- * <code>getInstance(Locale)</code> factory method in the base class
- * <code>Collator</code>.<code>Collator.getInstance(Locale)</code> creates
- * a <code>RuleBasedCollator</code> object based on the collation rules
- * defined by the argument locale. If a customized collation is required, use
- * the <code>RuleBasedCollator(String)</code> constructor with the appropriate
- * rules. The customized <code>RuleBasedCollator</code> will base its ordering
- * on UCA, while re-adjusting the attributes and orders of the characters in the
- * specified rule accordingly.
- * </p>
- * 
+ * A concrete implementation class for {@code Collation}.
+ * <p>
+ * {@code RuleBasedCollator} has the following restrictions for efficiency
+ * (other subclasses may be used for more complex languages):
+ * <ol>
+ * <li> If a French secondary ordering is specified it applies to the whole
+ * collator object.</li>
+ * <li> All non-mentioned Unicode characters are at the end of the collation
+ * order.</li>
+ * <li> If a character is not located in the {@code RuleBasedCollator}, the
+ * default Unicode Collation Algorithm (UCA) rulebased table is automatically
+ * searched as a backup.</li>
+ * </ol>
+ * <p>
+ * The collation table is composed of a list of collation rules, where each rule
+ * is of three forms:
+ * <blockquote>
+ *
+ * <pre>
+ * <modifier>
+ * <relation> <text-argument>
+ * <reset> <text-argument>
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * The rule elements are defined as follows:
+ * <ul type="disc">
+ * <li><strong>Text-Argument</strong>: A text-argument is any sequence of
+ * characters, excluding special characters (that is, common whitespace
+ * characters [0009-000D, 0020] and rule syntax characters [0021-002F,
+ * 003A-0040, 005B-0060, 007B-007E]). If those characters are desired, you can
+ * put them in single quotes (for example, use '&' for ampersand). Note that
+ * unquoted white space characters are ignored; for example, {@code b c} is
+ * treated as {@code bc}.</li>
+ * <li><strong>Modifier</strong>: There is a single modifier which is used to
+ * specify that all accents (secondary differences) are backwards.
+ * <p>
+ * '@' : Indicates that accents are sorted backwards, as in French.
+ * </li>
+ * <li><strong>Relation</strong>: The relations are the following:
+ * <ul type=square>
+ * <li>'<' : Greater, as a letter difference (primary)
+ * <li>';' : Greater, as an accent difference (secondary)
+ * <li>',' : Greater, as a case difference (tertiary)
+ * <li>'=' : Equal
+ * </ul>
+ * </li>
+ * <li><strong>Reset</strong>: There is a single reset which is used primarily
+ * for contractions and expansions, but which can also be used to add a
+ * modification at the end of a set of rules.
+ * <p>
+ * '&' : Indicates that the next rule follows the position to where the reset
+ * text-argument would be sorted.
+ * </li>
+ * </ul>
+ * <p>
+ * This sounds more complicated than it is in practice. For example, the
+ * following are equivalent ways of expressing the same thing:
+ * <blockquote>
+ *
+ * <pre>
+ * a < b < c
+ * a < b & b < c
+ * a < c & a < b
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Notice that the order is important, as the subsequent item goes immediately
+ * after the text-argument. The following are not equivalent:
+ * <blockquote>
+ *
+ * <pre>
+ * a < b & a < c
+ * a < c & a < b
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Either the text-argument must already be present in the sequence, or some
+ * initial substring of the text-argument must be present. For example
+ * {@code "a < b & ae < e"} is valid since "a" is present in the sequence before
+ * "ae" is reset. In this latter case, "ae" is not entered and treated as a
+ * single character; instead, "e" is sorted as if it were expanded to two
+ * characters: "a" followed by an "e". This difference appears in natural
+ * languages: in traditional Spanish "ch" is treated as if it contracts to a
+ * single character (expressed as {@code "c < ch < d"}), while in traditional
+ * German a-umlaut is treated as if it expands to two characters (expressed as
+ * {@code "a,A < b,B  ... & ae;\u00e3 & AE;\u00c3"}, where \u00e3 and \u00c3
+ * are the escape sequences for a-umlaut).
+ * <h4>Ignorable Characters</h4>
+ * <p>
+ * For ignorable characters, the first rule must start with a relation (the
+ * examples we have used above are really fragments; {@code "a < b"} really
+ * should be {@code "< a < b"}). If, however, the first relation is not
+ * {@code "<"}, then all text-arguments up to the first {@code "<"} are
+ * ignorable. For example, {@code ", - < a < b"} makes {@code "-"} an ignorable
+ * character.
+ * <h4>Normalization and Accents</h4>
+ * <p>
+ * {@code RuleBasedCollator} automatically processes its rule table to include
+ * both pre-composed and combining-character versions of accented characters.
+ * Even if the provided rule string contains only base characters and separate
+ * combining accent characters, the pre-composed accented characters matching
+ * all canonical combinations of characters from the rule string will be entered
+ * in the table.
+ * <p>
+ * This allows you to use a RuleBasedCollator to compare accented strings even
+ * when the collator is set to NO_DECOMPOSITION. However, if the strings to be
+ * collated contain combining sequences that may not be in canonical order, you
+ * should set the collator to CANONICAL_DECOMPOSITION to enable sorting of
+ * combining sequences. For more information, see <a
+ * href="http://www.aw.com/devpress">The Unicode Standard, Version 3.0</a>.
+ * <h4>Errors</h4>
+ * <p>
+ * The following rules are not valid:
+ * <ul type="disc">
+ * <li>A text-argument contains unquoted punctuation symbols, for example
+ * {@code "a < b-c < d"}.</li>
+ * <li>A relation or reset character is not followed by a text-argument, for
+ * example {@code "a < , b"}.</li>
+ * <li>A reset where the text-argument (or an initial substring of the
+ * text-argument) is not already in the sequence or allocated in the default UCA
+ * table, for example {@code "a < b & e < f"}.</li>
+ * </ul>
+ * <p>
+ * If you produce one of these errors, {@code RuleBasedCollator} throws a
+ * {@code ParseException}.
+ * <h4>Examples</h4>
+ * <p>
+ * Normally, to create a rule-based collator object, you will use
+ * {@code Collator}'s factory method {@code getInstance}. However, to create a
+ * rule-based collator object with specialized rules tailored to your needs, you
+ * construct the {@code RuleBasedCollator} with the rules contained in a
+ * {@code String} object. For example:
+ * <blockquote>
+ *
+ * <pre>
+ * String Simple = "< a < b < c < d";
+ *
+ * RuleBasedCollator mySimple = new RuleBasedCollator(Simple);
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Or:
+ * <blockquote>
+ *
+ * <pre>
+ * String Norwegian = "< a,A< b,B< c,C< d,D< e,E< f,F< g,G< h,H< i,I"
+ *         + "< j,J< k,K< l,L< m,M< n,N< o,O< p,P< q,Q< r,R"
+ *         + "< s,S< t,T< u,U< v,V< w,W< x,X< y,Y< z,Z"
+ *         + "< \u00E5=a\u030A,\u00C5=A\u030A"
+ *         + ";aa,AA< \u00E6,\u00C6< \u00F8,\u00D8";
+ *
+ * RuleBasedCollator myNorwegian = new RuleBasedCollator(Norwegian);
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * Combining {@code Collator}s is as simple as concatenating strings. Here is
+ * an example that combines two {@code Collator}s from two different locales:
+ * <blockquote>
+ *
+ * <pre>
+ * // Create an en_US Collator object
+ * RuleBasedCollator en_USCollator = (RuleBasedCollator)Collator
+ *         .getInstance(new Locale("en", "US", ""));
+ *
+ * // Create a da_DK Collator object
+ * RuleBasedCollator da_DKCollator = (RuleBasedCollator)Collator
+ *         .getInstance(new Locale("da", "DK", ""));
+ *
+ * // Combine the two collators
+ * // First, get the collation rules from en_USCollator
+ * String en_USRules = en_USCollator.getRules();
+ *
+ * // Second, get the collation rules from da_DKCollator
+ * String da_DKRules = da_DKCollator.getRules();
+ *
+ * RuleBasedCollator newCollator = new RuleBasedCollator(en_USRules + da_DKRules);
+ * // newCollator has the combined rules
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * The next example shows to make changes on an existing table to create a new
+ * {@code Collator} object. For example, add {@code "& C < ch, cH, Ch, CH"} to
+ * the {@code en_USCollator} object to create your own:
+ * <blockquote>
+ *
+ * <pre>
+ * // Create a new Collator object with additional rules
+ * String addRules = "& C < ch, cH, Ch, CH";
+ *
+ * RuleBasedCollator myCollator = new RuleBasedCollator(en_USCollator + addRules);
+ * // myCollator contains the new rules
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * The following example demonstrates how to change the order of non-spacing
+ * accents:
+ * <blockquote>
+ *
+ * <pre>
+ * // old rule
+ * String oldRules = "= \u00a8 ; \u00af ; \u00bf" + "< a , A ; ae, AE ; \u00e6 , \u00c6"
+ *         + "< b , B < c, C < e, E & C < d, D";
+ *
+ * // change the order of accent characters
+ * String addOn = "& \u00bf ; \u00af ; \u00a8;";
+ *
+ * RuleBasedCollator myCollator = new RuleBasedCollator(oldRules + addOn);
+ * </pre>
+ *
+ * </blockquote>
+ * <p>
+ * The last example shows how to put new primary ordering in before the default
+ * setting. For example, in the Japanese {@code Collator}, you can either sort
+ * English characters before or after Japanese characters:
+ * <blockquote>
+ *
+ * <pre>
+ * // get en_US Collator rules
+ * RuleBasedCollator en_USCollator = (RuleBasedCollator)
+ *     Collator.getInstance(Locale.US);
+ *
+ * // add a few Japanese character to sort before English characters
+ * // suppose the last character before the first base letter 'a' in
+ * // the English collation rule is \u30A2
+ * String jaString = "& \u30A2 , \u30FC < \u30C8";
+ *
+ * RuleBasedCollator myJapaneseCollator =
+ *     new RuleBasedCollator(en_USCollator.getRules() + jaString);
+ * </pre>
+ *
+ * </blockquote>
  */
 public class RuleBasedCollator extends Collator {
 
@@ -47,13 +267,24 @@
     }
 
     /**
-     * Constructs a new instance of <code>RuleBasedCollator</code> using the
-     * specified <code>rules</code>.
-     * 
+     * Constructs a new instance of {@code RuleBasedCollator} using the
+     * specified {@code rules}. The {@code rules} are usually either
+     * hand-written based on the {@link RuleBasedCollator class description} or
+     * the result of a former {@link #getRules()} call.
+     * <p>
+     * Note that the {@code rules} are actually interpreted as a delta to the
+     * standard Unicode Collation Algorithm (UCA). Hence, an empty {@code rules}
+     * string results in the default UCA rules being applied. This differs
+     * slightly from other implementations which work with full {@code rules}
+     * specifications and may result in different behavior.
+     *
      * @param rules
      *            the collation rules.
+     * @throws NullPointerException
+     *             if {@code rules} is {@code null}.
      * @throws ParseException
-     *             when the rules contains an invalid collation rule syntax.
+     *             if {@code rules} contains rules with invalid collation rule
+     *             syntax.
      */
     public RuleBasedCollator(String rules) throws ParseException {
         if (rules == null) {
@@ -79,13 +310,13 @@
     }
 
     /**
-     * Obtains a <code>CollationElementIterator</code> for the given
-     * <code>CharacterIterator</code>. The source iterator's integrity will
-     * be preserved since a new copy will be created for use.
+     * Obtains a {@code CollationElementIterator} for the given
+     * {@code CharacterIterator}. The source iterator's integrity will be
+     * preserved since a new copy will be created for use.
      * 
      * @param source
-     *            the specified source
-     * @return a <code>CollationElementIterator</code> for the source.
+     *            the source character iterator.
+     * @return a {@code CollationElementIterator} for {@code source}.
      */
     public CollationElementIterator getCollationElementIterator(
             CharacterIterator source) {
@@ -98,11 +329,11 @@
     }
 
     /**
-     * Obtains a <code>CollationElementIterator</code> for the given String.
+     * Obtains a {@code CollationElementIterator} for the given string.
      * 
      * @param source
-     *            the specified source
-     * @return a <code>CollationElementIterator</code> for the given String
+     *            the source string.
+     * @return the {@code CollationElementIterator} for {@code source}.
      */
     public CollationElementIterator getCollationElementIterator(String source) {
         if (source == null) {
@@ -114,8 +345,15 @@
     }
 
     /**
-     * Obtains the collation rules of the <code>RuleBasedCollator</code>.
-     * 
+     * Returns the collation rules of this collator. These {@code rules} can be
+     * fed into the {@code RuleBasedCollator(String)} constructor.
+     * <p>
+     * Note that the {@code rules} are actually interpreted as a delta to the
+     * standard Unicode Collation Algorithm (UCA). Hence, an empty {@code rules}
+     * string results in the default UCA rules being applied. This differs
+     * slightly from other implementations which work with full {@code rules}
+     * specifications and may result in different behavior.
+     *
      * @return the collation rules.
      */
     public String getRules() {
@@ -123,9 +361,11 @@
     }
 
     /**
-     * Obtains the cloned object of the <code>RuleBasedCollator</code>
+     * Returns a new collator with the same collation rules, decomposition mode and
+     * strength value as this collator.
      * 
-     * @return the cloned object of the <code>RuleBasedCollator</code>
+     * @return a shallow copy of this collator.
+     * @see java.lang.Cloneable
      */
     @Override
     public Object clone() {
@@ -134,27 +374,25 @@
     }
 
     /**
-     * Compares the <code>source</code> text <code>String</code> to the
-     * <code>target</code> text <code>String</code> according to the
-     * collation rules, strength and decomposition mode for this
-     * <code>RuleBasedCollator</code>. See the <code>Collator</code> class
-     * description for an example of use.
+     * Compares the {@code source} text to the {@code target} text according to
+     * the collation rules, strength and decomposition mode for this
+     * {@code RuleBasedCollator}. See the {@code Collator} class description
+     * for an example of use.
      * <p>
-     * General recommendation: If comparisons are to be done to the same String
-     * multiple times, it would be more efficient to generate
-     * <code>CollationKeys</code> for the <code>String</code> s and use
-     * <code>CollationKey.compareTo(CollationKey)</code> for the comparisons.
-     * If the each Strings are compared to only once, using the method
-     * RuleBasedCollator.compare(String, String) will have a better performance.
-     * </p>
+     * General recommendation: If comparisons are to be done with the same strings
+     * multiple times, it is more efficient to generate {@code CollationKey}
+     * objects for the strings and use
+     * {@code CollationKey.compareTo(CollationKey)} for the comparisons. If each
+     * string is compared to only once, using
+     * {@code RuleBasedCollator.compare(String, String)} has better performance.
      * 
      * @param source
-     *            the source text
+     *            the source text.
      * @param target
-     *            the target text
+     *            the target text.
      * @return an integer which may be a negative value, zero, or else a
-     *         positive value depending on whether <code>source</code> is less
-     *         than, equivalent to, or greater than <code>target</code>.
+     *         positive value depending on whether {@code source} is less than,
+     *         equivalent to, or greater than {@code target}.
      */
     @Override
     public int compare(String source, String target) {
@@ -166,11 +404,11 @@
     }
 
     /**
-     * Obtains the <code>CollationKey</code> for the given source text.
+     * Returns the {@code CollationKey} for the given source text.
      * 
      * @param source
-     *            the specified source text
-     * @return the <code>CollationKey</code> for the given source text.
+     *            the specified source text.
+     * @return the {@code CollationKey} for the given source text.
      */
     @Override
     public CollationKey getCollationKey(String source) {
@@ -182,11 +420,6 @@
         return new CollationKey(source, icuKey);
     }
 
-    /**
-     * Obtains a unique hash code for the <code>RuleBasedCollator</code>
-     * 
-     * @return the hash code for the <code>RuleBasedCollator</code>
-     */
     @Override
     public int hashCode() {
         return ((com.ibm.icu.text.RuleBasedCollator) this.icuColl).getRules()
@@ -194,15 +427,16 @@
     }
 
     /**
-     * Compares the equality of two <code>RuleBasedCollator</code> objects.
-     * <code>RuleBasedCollator</code> objects are equal if they have the same
-     * collation rules and the same attributes.
+     * Compares the specified object with this {@code RuleBasedCollator} and
+     * indicates if they are equal. In order to be equal, {@code object} must be
+     * an instance of {@code Collator} with the same collation rules and the
+     * same attributes.
      * 
      * @param obj
-     *            the other object.
-     * @return <code>true</code> if this <code>RuleBasedCollator</code> has
-     *         exactly the same collation behaviour as obj, <code>false</code>
-     *         otherwise.
+     *            the object to compare with this object.
+     * @return {@code true} if the specified object is equal to this
+     *         {@code RuleBasedCollator}; {@code false} otherwise.
+     * @see #hashCode
      */
     @Override
     public boolean equals(Object obj) {

Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/SimpleDateFormat.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/SimpleDateFormat.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/SimpleDateFormat.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/SimpleDateFormat.java Thu May  7 08:42:00 2009
@@ -30,12 +30,277 @@
 import org.apache.harmony.text.internal.nls.Messages;
 
 /**
- * SimpleDateFormat is used to format and parse Gregorian calendar dates and
- * times based on a pattern of date and time fields. Each date and time field is
- * specified in the pattern by a specific character. The characters used can be
- * either localized or non-localized. For some fields, which have both numeric
- * and text representations or abbreviated as well as full names, the number of
- * grouped characters specifies how the field is formatted or parsed.
+ * A concrete class for formatting and parsing dates in a locale-sensitive
+ * manner. It allows for formatting (date to text), parsing (text to date) and
+ * normalization.
+ * <p>
+ * {@code SimpleDateFormat} allows you to start by choosing any user-defined
+ * patterns for date-time formatting. However, you are encouraged to create a
+ * date-time formatter with either {@code getTimeInstance}, {@code
+ * getDateInstance}, or {@code getDateTimeInstance} in {@code DateFormat}. Each
+ * of these class methods can return a date/time formatter initialized with a
+ * default format pattern. You may modify the format pattern using the {@code
+ * applyPattern} methods as desired. For more information on using these
+ * methods, see {@link DateFormat}.
+ * <h4>Time Format Syntax</h4>
+ * <p>
+ * To specify the time format, use a <em>time pattern</em> string. In this
+ * pattern, all ASCII letters are reserved as pattern letters, which are defined
+ * as follows:
+ * <table border=0 cellspacing=3 cellpadding=0>
+ * <tr bgcolor="#ccccff">
+ * <th>Symbol</th>
+ * <th>Meaning</th>
+ * <th>Presentation</th>
+ * <th>Example</th>
+ * </tr>
+ * <tr valign=top>
+ * <td>G</td>
+ * <td>era designator</td>
+ * <td>(Text)</td>
+ * <td>AD</td>
+ * </tr>
+ * <tr valign=top bgcolor="#eeeeff">
+ * <td>y</td>
+ * <td>year</td>
+ * <td>(Number)</td>
+ * <td>1996</td>
+ * </tr>
+ * <tr valign=top>
+ * <td>M</td>
+ * <td>month in year</td>
+ * <td>(Text &amp; Number)</td>
+ * <td>July &amp; 07</td>
+ * </tr>
+ * <tr valign=top bgcolor="#eeeeff">
+ * <td>d</td>
+ * <td>day in month</td>
+ * <td>(Number)</td>
+ * <td>10</td>
+ * </tr>
+ * <tr valign=top>
+ * <td>h</td>
+ * <td>hour in am/pm (1&tilde;12)</td>
+ * <td>(Number)</td>
+ * <td>12</td>
+ * </tr>
+ * <tr valign=top bgcolor="#eeeeff">
+ * <td>H</td>
+ * <td>hour in day (0&tilde;23)</td>
+ * <td>(Number)</td>
+ * <td>0</td>
+ * </tr>
+ * <tr valign=top>
+ * <td>m</td>
+ * <td>minute in hour</td>
+ * <td>(Number)</td>
+ * <td>30</td>
+ * </tr>
+ * <tr valign=top bgcolor="#eeeeff">
+ * <td>s</td>
+ * <td>second in minute</td>
+ * <td>(Number)</td>
+ * <td>55</td>
+ * </tr>
+ * <tr valign=top>
+ * <td>S</td>
+ * <td>fractional second</td>
+ * <td>(Number)</td>
+ * <td>978</td>
+ * </tr>
+ * <tr valign=top bgcolor="#eeeeff">
+ * <td>E</td>
+ * <td>day of week</td>
+ * <td>(Text)</td>
+ * <td>Tuesday</td>
+ * </tr>
+ * <tr valign=top bgcolor="#eeeeff">
+ * <td>D</td>
+ * <td>day in year</td>
+ * <td>(Number)</td>
+ * <td>189</td>
+ * </tr>
+ * <tr valign=top>
+ * <td>F</td>
+ * <td>day of week in month</td>
+ * <td>(Number)</td>
+ * <td>2 (2nd Wed in July)</td>
+ * </tr>
+ * <tr valign=top bgcolor="#eeeeff">
+ * <td>w</td>
+ * <td>week in year</td>
+ * <td>(Number)</td>
+ * <td>27</td>
+ * </tr>
+ * <tr valign=top>
+ * <td>W</td>
+ * <td>week in month</td>
+ * <td>(Number)</td>
+ * <td>2</td>
+ * </tr>
+ * <tr valign=top bgcolor="#eeeeff">
+ * <td>a</td>
+ * <td>am/pm marker</td>
+ * <td>(Text)</td>
+ * <td>PM</td>
+ * </tr>
+ * <tr valign=top>
+ * <td>k</td>
+ * <td>hour in day (1&tilde;24)</td>
+ * <td>(Number)</td>
+ * <td>24</td>
+ * </tr>
+ * <tr valign=top bgcolor="#eeeeff">
+ * <td>K</td>
+ * <td>hour in am/pm (0&tilde;11)</td>
+ * <td>(Number)</td>
+ * <td>0</td>
+ * </tr>
+ * <tr valign=top>
+ * <td>z</td>
+ * <td>time zone</td>
+ * <td>(Text)</td>
+ * <td>Pacific Standard Time</td>
+ * </tr>
+ * <tr valign=top bgcolor="#eeeeff">
+ * <td>Z</td>
+ * <td>time zone (RFC 822)</td>
+ * <td>(Number)</td>
+ * <td>-0800</td>
+ * </tr>
+ * <tr valign=top>
+ * <td>v</td>
+ * <td>time zone (generic)</td>
+ * <td>(Text)</td>
+ * <td>Pacific Time</td>
+ * </tr>
+ * <tr valign=top bgcolor="#eeeeff">
+ * <td>V</td>
+ * <td>time zone (location)</td>
+ * <td>(Text)</td>
+ * <td>United States (Los Angeles)</td>
+ * </tr>
+ * <tr valign=top>
+ * <td>'</td>
+ * <td>escape for text</td>
+ * <td>(Delimiter)</td>
+ * <td>'Date='</td>
+ * </tr>
+ * <tr valign=top bgcolor="#eeeeff">
+ * <td>''</td>
+ * <td>single quote</td>
+ * <td>(Literal)</td>
+ * <td>'o''clock'</td>
+ * </tr>
+ * </table>
+ * <p>
+ * The count of pattern letters determines the format:
+ * <p>
+ * <strong>(Text)</strong>: 4 or more pattern letters &rarr; use the full form,
+ * less than 4 pattern letters &rarr; use a short or abbreviated form if one
+ * exists.
+ * <p>
+ * <strong>(Number)</strong>: the minimum number of digits. Shorter numbers are
+ * zero-padded to this amount. Year is handled specially; that is, if the count
+ * of 'y' is 2, the year will be truncated to 2 digits. (if "yyyy" produces
+ * "1997", "yy" produces "97".) Unlike other fields, fractional seconds are
+ * padded on the right with zero.
+ * <p>
+ * <strong>(Text & Number)</strong>: 3 or over, use text, otherwise use number.
+ * <p>
+ * Any characters in the pattern that are not in the ranges of ['a'..'z'] and
+ * ['A'..'Z'] will be treated as quoted text. For instance, characters like ':',
+ * '.', ' ', '#' and '@' will appear in the resulting time text even they are
+ * not embraced within single quotes.
+ * <p>
+ * A pattern containing any invalid pattern letter will result in an exception
+ * thrown during formatting or parsing.
+ * <h4>Examples Using the US Locale</h4> <blockquote>
+ * 
+ * <pre>
+ * Format Pattern                       Result
+ * --------------                       -------
+ * "yyyy.MM.dd G 'at' HH:mm:ss vvvv" &rarr;  1996.07.10 AD at 15:08:56 Pacific Time
+ * "EEE, MMM d, ''yy"                &rarr;  Wed, July 10, '96
+ * "h:mm a"                          &rarr;  12:08 PM
+ * "hh 'o''clock' a, zzzz"           &rarr;  12 o'clock PM, Pacific Daylight Time
+ * "K:mm a, vvv"                     &rarr;  0:00 PM, PT
+ * "yyyyy.MMMMM.dd GGG hh:mm aaa"    &rarr;  01996.July.10 AD 12:08 PM
+ * </pre>
+ * 
+ * </blockquote> <h4>Code Sample:</h4> <blockquote>
+ * 
+ * <pre>
+ * SimpleTimeZone pdt = new SimpleTimeZone(-8 * 60 * 60 * 1000, "PST");
+ * pdt.setStartRule(Calendar.APRIL, 1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);
+ * pdt.setEndRule(Calendar.OCTOBER, -1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);
+ * 
+ * // Format the current time.
+ * SimpleDateFormat formatter = new SimpleDateFormat(
+ *         "yyyy.MM.dd G 'at' hh:mm:ss a zzz");
+ * Date currentTime_1 = new Date();
+ * String dateString = formatter.format(currentTime_1);
+ * 
+ * // Parse the previous string back into a Date.
+ * ParsePosition pos = new ParsePosition(0);
+ * Date currentTime_2 = formatter.parse(dateString, pos);
+ * </pre>
+ * 
+ * </blockquote>
+ * <p>
+ * In the example, the time value {@code currentTime_2} obtained from parsing
+ * will be equal to {@code currentTime_1}. However, they may not be equal if the
+ * am/pm marker 'a' is left out from the format pattern while the
+ * "hour in am/pm" pattern symbol is used. This information loss can happen when
+ * formatting the time in PM.
+ * <p>
+ * When parsing a date string using the abbreviated year pattern ("yy"), {@code
+ * SimpleDateFormat} must interpret the abbreviated year relative to some
+ * century. It does this by adjusting dates to be within 80 years before and 20
+ * years after the time the {@code SimpleDateFormat} instance is created. For
+ * example, using a pattern of "MM/dd/yy" and a {@code SimpleDateFormat}
+ * instance created on Jan 1, 1997, the string "01/11/12" would be interpreted
+ * as Jan 11, 2012 while the string "05/04/64" would be interpreted as May 4,
+ * 1964. During parsing, only strings consisting of exactly two digits, as
+ * defined by {@link java.lang.Character#isDigit(char)}, will be parsed into the
+ * default century. Any other numeric string, such as a one digit string, a
+ * three or more digit string, or a two digit string that isn't all digits (for
+ * example, "-1"), is interpreted literally. So "01/02/3" or "01/02/003" are
+ * parsed, using the same pattern, as Jan 2, 3 AD. Likewise, "01/02/-3" is
+ * parsed as Jan 2, 4 BC.
+ * <p>
+ * If the year pattern does not have exactly two 'y' characters, the year is
+ * interpreted literally, regardless of the number of digits. So using the
+ * pattern "MM/dd/yyyy", "01/11/12" parses to Jan 11, 12 A.D.
+ * <p>
+ * When numeric fields are adjacent directly, with no intervening delimiter
+ * characters, they constitute a run of adjacent numeric fields. Such runs are
+ * parsed specially. For example, the format "HHmmss" parses the input text
+ * "123456" to 12:34:56, parses the input text "12345" to 1:23:45, and fails to
+ * parse "1234". In other words, the leftmost field of the run is flexible,
+ * while the others keep a fixed width. If the parse fails anywhere in the run,
+ * then the leftmost field is shortened by one character, and the entire run is
+ * parsed again. This is repeated until either the parse succeeds or the
+ * leftmost field is one character in length. If the parse still fails at that
+ * point, the parse of the run fails.
+ * <p>
+ * For time zones that have no names, use the strings "GMT+hours:minutes" or
+ * "GMT-hours:minutes".
+ * <p>
+ * The calendar defines the first day of the week, the first week of the year,
+ * whether hours are zero based or not (0 vs. 12 or 24) and the time zone. There
+ * is one common decimal format to handle all the numbers; the digit count is
+ * handled programmatically according to the pattern.
+ * <h4>Synchronization</h4> Date formats are 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.
+ * 
+ * @see Calendar
+ * @see GregorianCalendar
+ * @see TimeZone
+ * @see DateFormat
+ * @see DateFormatSymbols
+ * @see DecimalFormat
  */
 public class SimpleDateFormat extends DateFormat {
 
@@ -54,8 +319,8 @@
     private transient com.ibm.icu.text.SimpleDateFormat icuFormat;
 
     /**
-     * Constructs a new SimpleDateFormat for formatting and parsing dates and
-     * times in the SHORT style for the default Locale.
+     * Constructs a new {@code SimpleDateFormat} for formatting and parsing
+     * dates and times in the {@code SHORT} style for the default locale.
      */
     public SimpleDateFormat() {
         this(Locale.getDefault());
@@ -65,29 +330,28 @@
     }
 
     /**
-     * Constructs a new SimpleDateFormat using the specified non-localized
-     * pattern and the DateFormatSymbols and Calendar for the default Locale.
+     * Constructs a new {@code SimpleDateFormat} using the specified
+     * non-localized pattern and the {@code DateFormatSymbols} and {@code
+     * Calendar} for the default locale.
      * 
      * @param pattern
-     *            the pattern
-     * 
-     * @exception NullPointerException
-     *                if a <code>null</code> value of <code>pattern</code>
-     *                is supplied.
-     * @exception IllegalArgumentException
-     *                if <code>pattern</code> is not considered to be useable
-     *                by this formatter.
+     *            the pattern.
+     * @throws NullPointerException
+     *            if the pattern is {@code null}.
+     * @throws IllegalArgumentException
+     *            if {@code pattern} is not considered to be usable by this
+     *            formatter.
      */
     public SimpleDateFormat(String pattern) {
         this(pattern, Locale.getDefault());
     }
     
     /**
-     * Validate the format character.
-     * 
+     * Validates the format character.
+     *
      * @param format
      *            the format character
-     * 
+     *
      * @throws IllegalArgumentException
      *             when the format character is invalid
      */
@@ -101,11 +365,11 @@
     }
 
     /**
-     * Validate the pattern.
-     * 
+     * Validates the pattern.
+     *
      * @param template
      *            the pattern to validate.
-     * 
+     *
      * @throws NullPointerException
      *             if the pattern is null
      * @throws IllegalArgumentException
@@ -162,18 +426,18 @@
     }
     
     /**
-     * Constructs a new SimpleDateFormat using the specified non-localized
-     * pattern and DateFormatSymbols and the Calendar for the default Locale.
-     * 
+     * Constructs a new {@code SimpleDateFormat} using the specified
+     * non-localized pattern and {@code DateFormatSymbols} and the {@code
+     * Calendar} for the default locale.
+     *
      * @param template
-     *            the pattern
+     *            the pattern.
      * @param value
-     *            the DateFormatSymbols
-     * 
-     * @exception NullPointerException
-     *                if the pattern is null
-     * @exception IllegalArgumentException
-     *                if the pattern is invalid
+     *            the DateFormatSymbols.
+     * @throws NullPointerException
+     *            if the pattern is {@code null}.
+     * @throws IllegalArgumentException
+     *            if the pattern is invalid.
      */
     public SimpleDateFormat(String template, DateFormatSymbols value) {
         this(Locale.getDefault());
@@ -195,18 +459,18 @@
     }
     
     /**
-     * Constructs a new SimpleDateFormat using the specified non-localized
-     * pattern and the DateFormatSymbols and Calendar for the specified Locale.
+     * Constructs a new {@code SimpleDateFormat} using the specified
+     * non-localized pattern and the {@code DateFormatSymbols} and {@code
+     * Calendar} for the specified locale.
      * 
      * @param template
-     *            the pattern
+     *            the pattern.
      * @param locale
-     *            the Locale
-     * 
-     * @exception NullPointerException
-     *                if the pattern is null
-     * @exception IllegalArgumentException
-     *                if the pattern is invalid
+     *            the locale.
+     * @throws NullPointerException
+     *            if the pattern is {@code null}.
+     * @throws IllegalArgumentException
+     *            if the pattern is invalid.
      */
     public SimpleDateFormat(String template, Locale locale) {
         this(locale);
@@ -234,11 +498,11 @@
     }
 
     /**
-     * Changes the pattern of this SimpleDateFormat to the specified pattern
+     * Changes the pattern of this simple date format to the specified pattern
      * which uses localized pattern characters.
      * 
      * @param template
-     *            the localized pattern
+     *            the localized pattern.
      */
     public void applyLocalizedPattern(String template) {
         icuFormat.applyLocalizedPattern(template);
@@ -246,16 +510,15 @@
     }
 
     /**
-     * Changes the pattern of this SimpleDateFormat to the specified pattern
+     * Changes the pattern of this simple date format to the specified pattern
      * which uses non-localized pattern characters.
      * 
      * @param template
-     *            the non-localized pattern
-     * 
-     * @exception NullPointerException
-     *                if the pattern is null
-     * @exception IllegalArgumentException
-     *                if the pattern is invalid
+     *            the non-localized pattern.
+     * @throws NullPointerException
+     *                if the pattern is {@code null}.
+     * @throws IllegalArgumentException
+     *                if the pattern is invalid.
      */
     @SuppressWarnings("nls")
     public void applyPattern(String template) {
@@ -302,11 +565,10 @@
     }
 
     /**
-     * Answers a new SimpleDateFormat with the same pattern and properties as
-     * this SimpleDateFormat.
-     * 
-     * @return a shallow copy of this SimpleDateFormat
+     * Returns a new {@code SimpleDateFormat} with the same pattern and
+     * properties as this simple date format.
      * 
+     * @return a shallow copy of this simple date format.
      * @see java.lang.Cloneable
      */
     @Override
@@ -318,16 +580,15 @@
     }
 
     /**
-     * Compares the specified object to this SimpleDateFormat and answer if they
-     * are equal. The object must be an instance of SimpleDateFormat and have
-     * the same DateFormat properties, pattern, DateFormatSymbols, and creation
-     * year.
+     * Compares the specified object with this simple date format and indicates
+     * if they are equal. In order to be equal, {@code object} must be an
+     * instance of {@code SimpleDateFormat} and have the same {@code DateFormat}
+     * properties, pattern, {@code DateFormatSymbols} and creation year.
      * 
      * @param object
-     *            the object to compare with this object
-     * @return true if the specified object is equal to this SimpleDateFormat,
-     *         false otherwise
-     * 
+     *            the object to compare with this object.
+     * @return {@code true} if the specified object is equal to this simple date
+     *         format; {@code false} otherwise.
      * @see #hashCode
      */
     @Override
@@ -344,19 +605,19 @@
     }
 
     /**
-     * Formats the specified object using the rules of this SimpleDateFormat and
-     * returns an AttributedCharacterIterator with the formatted Date and
-     * attributes.
+     * Formats the specified object using the rules of this simple date format
+     * and returns an {@code AttributedCharacterIterator} with the formatted
+     * date and attributes.
      * 
      * @param object
-     *            the object to format
-     * @return an AttributedCharacterIterator with the formatted date and
-     *         attributes
-     * 
-     * @exception NullPointerException
-     *                when the object is null
-     * @exception IllegalArgumentException
-     *                when the object cannot be formatted by this Format
+     *            the object to format.
+     * @return an {@code AttributedCharacterIterator} with the formatted date
+     *         and attributes.
+     * @throws NullPointerException
+     *            if the object is {@code null}.
+     * @throws IllegalArgumentException
+     *            if the object cannot be formatted by this simple date
+     *            format.
      */
     @Override
     public AttributedCharacterIterator formatToCharacterIterator(Object object) {
@@ -399,11 +660,11 @@
     /**
      * Formats the date.
      * <p>
-     * If the FieldPosition <code>field</code> is not null, and the field
+     * If the FieldPosition {@code field} is not null, and the field
      * specified by this FieldPosition is formatted, set the begin and end index
      * of the formatted field in the FieldPosition.
      * <p>
-     * If the Vector <code>fields</code> is not null, find fields of this
+     * If the Vector {@code fields} is not null, find fields of this
      * date, set FieldPositions with these fields, and add them to the fields
      * vector.
      * 
@@ -417,11 +678,9 @@
      * @param fields
      *            Vector used to store the FieldPositions for each field in this
      *            date
-     * 
      * @return the formatted Date
-     * 
-     * @exception IllegalArgumentException
-     *                when the object cannot be formatted by this Format
+     * @throws IllegalArgumentException
+     *            if the object cannot be formatted by this Format.
      */
     private StringBuffer formatImpl(Date date, StringBuffer buffer,
             FieldPosition field, Vector<FieldPosition> fields) {
@@ -665,21 +924,24 @@
     
 
     /**
-     * Formats the specified Date into the specified StringBuffer using the
-     * pattern of this SimpleDateFormat. 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 date as a string using the pattern of this date
+     * format and appends the string to the specified string buffer.
+     * <p>
+     * If the {@code field} member of {@code field} 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 date
-     *            the Date to format
+     *            the date to format.
      * @param buffer
-     *            the StringBuffer
+     *            the target string buffer to append the formatted date/time to.
      * @param field
-     *            the FieldPosition
-     * @return the StringBuffer parameter <code>buffer</code>
-     * 
-     * @exception IllegalArgumentException
-     *                when there are invalid characters in the pattern
+     *            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 there are invalid characters in the pattern.
      */
     @Override
     public StringBuffer format(Date date, StringBuffer buffer,
@@ -766,23 +1028,15 @@
     }
 
     /**
-     * Answers the DateFormatSymbols used by this SimpleDateFormat.
-     * 
-     * @return a DateFormatSymbols
+     * Returns the {@code DateFormatSymbols} used by this simple date format.
+     *
+     * @return the {@code DateFormatSymbols} object.
      */
     public DateFormatSymbols getDateFormatSymbols() {
         // Return a clone so the arrays in the ResourceBundle are not modified
         return (DateFormatSymbols) formatData.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() {
         return super.hashCode() + pattern.hashCode() + formatData.hashCode()
@@ -790,21 +1044,25 @@
     }
 
     /**
-     * Parse a Date 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 date 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 according to the pattern of this
-     *            SimpleDateFormat
+     *            the string to parse using the pattern of this simple date
+     *            format.
      * @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 the Date resulting from the parse, or null if there is an error
-     * 
-     * @exception IllegalArgumentException
-     *                when there are invalid characters in the pattern
+     *            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 date resulting from the parse, or {@code null} if there is an
+     *         error.
+     * @throws IllegalArgumentException
+     *             if there are invalid characters in the pattern.
      */
     @Override
     public Date parse(String string, ParsePosition position) {
@@ -814,11 +1072,11 @@
     }
 
     /**
-     * Sets the Date which is the start of the one hundred year period for two
+     * Sets the date which is the start of the one hundred year period for two
      * digits year values.
      * 
      * @param date
-     *            the Date
+     *            the new date.
      */
     public void set2DigitYearStart(Date date) {
         icuFormat.set2DigitYearStart(date);
@@ -829,10 +1087,10 @@
     }
 
     /**
-     * Sets the DateFormatSymbols used by this SimpleDateFormat.
+     * Sets the {@code DateFormatSymbols} used by this simple date format.
      * 
      * @param value
-     *            the DateFormatSymbols
+     *            the new {@code DateFormatSymbols} object.
      */
     public void setDateFormatSymbols(DateFormatSymbols value) {
         com.ibm.icu.text.DateFormatSymbols icuSymbols = new com.ibm.icu.text.DateFormatSymbols();
@@ -842,20 +1100,20 @@
     }
 
     /**
-     * Answers the pattern of this SimpleDateFormat using localized pattern
+     * Returns the pattern of this simple date format using localized pattern
      * characters.
      * 
-     * @return the localized pattern
+     * @return the localized pattern.
      */
     public String toLocalizedPattern() {
         return icuFormat.toLocalizedPattern();
     }
 
     /**
-     * Answers the pattern of this SimpleDateFormat using non-localized pattern
-     * characters.
+     * Returns the pattern of this simple date format using non-localized
+     * pattern characters.
      * 
-     * @return the non-localized pattern
+     * @return the non-localized pattern.
      */
     public String toPattern() {
         return pattern;

Modified: harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/StringCharacterIterator.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/StringCharacterIterator.java?rev=772552&r1=772551&r2=772552&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/StringCharacterIterator.java (original)
+++ harmony/enhanced/classlib/trunk/modules/text/src/main/java/java/text/StringCharacterIterator.java Thu May  7 08:42:00 2009
@@ -18,8 +18,7 @@
 package java.text;
 
 /**
- * StringCharacterIterator is an implementation of CharacterIterator for
- * Strings.
+ * An implementation of {@link CharacterIterator} for strings.
  */
 public final class StringCharacterIterator implements CharacterIterator {
 
@@ -28,12 +27,12 @@
     int start, end, offset;
 
     /**
-     * Constructs a new StringCharacterIterator on the specified String. The
-     * begin and current indexes are set to the beginning of the String, the end
-     * index is set to the length of the String.
+     * Constructs a new {@code StringCharacterIterator} on the specified string.
+     * The begin and current indices are set to the beginning of the string, the
+     * end index is set to the length of the string.
      * 
      * @param value
-     *            the new source String to iterate
+     *            the source string to iterate over.
      */
     public StringCharacterIterator(String value) {
         string = value;
@@ -42,18 +41,18 @@
     }
 
     /**
-     * Constructs a new StringCharacterIterator on the specified String with the
-     * current index set to the specified value. The begin index is set to the
-     * beginning of the String, the end index is set to the length of the String.
+     * Constructs a new {@code StringCharacterIterator} on the specified string
+     * with the current index set to the specified value. The begin index is set
+     * to the beginning of the string, the end index is set to the length of the
+     * string.
      * 
      * @param value
-     *            the new source String to iterate
+     *            the source string to iterate over.
      * @param location
-     *            the current index
-     * 
-     * @exception IllegalArgumentException
-     *                when the current index is less than zero or greater than
-     *                the length of the String
+     *            the current index.
+     * @throws IllegalArgumentException
+     *            if {@code location} is negative or greater than the length
+     *            of the source string.
      */
     public StringCharacterIterator(String value, int location) {
         string = value;
@@ -66,23 +65,21 @@
     }
 
     /**
-     * Constructs a new StringCharacterIterator on the specified String with the
-     * begin, end and current index set to the specified values.
+     * Constructs a new {@code StringCharacterIterator} on the specified string
+     * with the begin, end and current index set to the specified values.
      * 
      * @param value
-     *            the new source String to iterate
+     *            the source string to iterate over.
      * @param start
-     *            the index of the first character to iterate
+     *            the index of the first character to iterate.
      * @param end
-     *            the index one past the last character to iterate
+     *            the index one past the last character to iterate.
      * @param location
-     *            the current index
-     * 
-     * @exception IllegalArgumentException
-     *                when the begin index is less than zero, the end index is
-     *                greater than the String length, the begin index is greater
-     *                than the end index, the current index is less than the
-     *                begin index or greater than the end index
+     *            the current index.
+     * @throws IllegalArgumentException
+     *            if {@code start < 0}, {@code start > end}, {@code location <
+     *            start}, {@code location > end} or if {@code end} is greater
+     *            than the length of {@code value}.
      */
     public StringCharacterIterator(String value, int start, int end,
             int location) {
@@ -97,11 +94,10 @@
     }
 
     /**
-     * Answers a new StringCharacterIterator with the same source String, begin,
-     * end, and current index as this StringCharacterIterator.
-     * 
-     * @return a shallow copy of this StringCharacterIterator
+     * Returns a new {@code StringCharacterIterator} with the same source
+     * string, begin, end, and current index as this iterator.
      * 
+     * @return a shallow copy of this iterator.
      * @see java.lang.Cloneable
      */
     @Override
@@ -114,10 +110,10 @@
     }
 
     /**
-     * Answers the character at the current index in the source String.
+     * Returns the character at the current index in the source string.
      * 
-     * @return the current character, or DONE if the current index is past the
-     *         end
+     * @return the current character, or {@code DONE} if the current index is
+     *         past the end.
      */
     public char current() {
         if (offset == end) {
@@ -127,15 +123,15 @@
     }
 
     /**
-     * Compares the specified object to this StringCharacterIterator and answer
-     * if they are equal. The object must be a StringCharacterIterator iterating
-     * over the same sequence of characters with the same index.
+     * Compares the specified object with this {@code StringCharacterIterator}
+     * and indicates if they are equal. In order to be equal, {@code object}
+     * must be an instance of {@code StringCharacterIterator} that iterates over
+     * the same sequence of characters with the same index.
      * 
      * @param object
-     *            the object to compare with this object
-     * @return true if the specified object is equal to this
-     *         StringCharacterIterator, false otherwise
-     * 
+     *            the object to compare with this object.
+     * @return {@code true} if the specified object is equal to this
+     *         {@code StringCharacterIterator}; {@code false} otherwise.
      * @see #hashCode
      */
     @Override
@@ -149,10 +145,11 @@
     }
 
     /**
-     * Sets the current position to the begin index and answers the character at
-     * the begin index.
+     * Sets the current position to the begin index and returns the character at
+     * the new position in the source string.
      * 
-     * @return the character at the begin index
+     * @return the character at the begin index or {@code DONE} if the begin
+     *         index is equal to the end index.
      */
     public char first() {
         if (start == end) {
@@ -163,50 +160,43 @@
     }
 
     /**
-     * Answers the begin index in the source String.
+     * Returns the begin index in the source string.
      * 
-     * @return the index of the first character to iterate
+     * @return the index of the first character of the iteration.
      */
     public int getBeginIndex() {
         return start;
     }
 
     /**
-     * Answers the end index in the source String.
+     * Returns the end index in the source string.
      * 
-     * @return the index one past the last character to iterate
+     * @return the index one past the last character of the iteration.
      */
     public int getEndIndex() {
         return end;
     }
 
     /**
-     * Answers the current index in the source String.
+     * Returns the current index in the source string.
      * 
-     * @return the current index
+     * @return the current index.
      */
     public int getIndex() {
         return offset;
     }
 
-    /**
-     * 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 string.hashCode() + start + end + offset;
     }
 
     /**
-     * Sets the current position to the end index - 1 and answers the character
-     * at the current position.
+     * Sets the current position to the end index - 1 and returns the character
+     * at the new position.
      * 
-     * @return the character before the end index
+     * @return the character before the end index or {@code DONE} if the begin
+     *         index is equal to the end index.
      */
     public char last() {
         if (start == end) {
@@ -218,9 +208,9 @@
 
     /**
      * Increments the current index and returns the character at the new index.
-     * 
-     * @return the character at the next index, or DONE if the next index is
-     *         past the end
+     *
+     * @return the character at the next index, or {@code DONE} if the next
+     *         index would be past the end.
      */
     public char next() {
         if (offset >= (end - 1)) {
@@ -233,8 +223,8 @@
     /**
      * Decrements the current index and returns the character at the new index.
      * 
-     * @return the character at the previous index, or DONE if the previous
-     *         index is past the beginning
+     * @return the character at the previous index, or {@code DONE} if the
+     *         previous index would be past the beginning.
      */
     public char previous() {
         if (offset == start) {
@@ -244,14 +234,15 @@
     }
 
     /**
-     * Sets the current index in the source String.
+     * Sets the current index in the source string.
      * 
-     * @return the character at the new index, or DONE if the index is past the
-     *         end
-     * 
-     * @exception IllegalArgumentException
-     *                when the new index is less than the begin index or greater
-     *                than the end index
+     * @param location
+     *            the index the current position is set to.
+     * @return the character at the new index, or {@code DONE} if
+     *         {@code location} is set to the end index.
+     * @throws IllegalArgumentException
+     *            if {@code location} is smaller than the begin index or greater
+     *            than the end index.
      */
     public char setIndex(int location) {
         if (location < start || location > end) {
@@ -265,11 +256,11 @@
     }
 
     /**
-     * Sets the source String to iterate. The begin and end positions are set to
-     * the start and end of this String.
+     * Sets the source string to iterate over. The begin and end positions are
+     * set to the start and end of this string.
      * 
      * @param value
-     *            the new source String
+     *            the new source string.
      */
     public void setText(String value) {
         string = value;



Mime
View raw message